Phase 0-1: OS Kernel Primitives (v0.1.0 to v1.2.0)

Eight foundational mechanisms. Every higher-order system depends on these. Without events, systems poll. Without signals, you can't coordinate. Without memory management, you have no state. Without audit, you can't trace failures. Without transactions, concurrent agents corrupt each other's data. Without lineage, you can't understand causality. Each primitive is small, focused, and orthogonal.

Phase 2: Agent Services (v1.3.0 to v1.3.7)

Services that are only possible because Phase 1 exists. Distributed tracing (needs audit + registry). Checkpoints (needs memory + transactions). Consensus (needs events + transactions). Adaptive routing (needs scheduler + audit). Self-extension (needs consensus + full stack).

Phase 3: Cognitive Infrastructure (v2.0.0 to v2.5.0)

Replacing every human-facing interface with agent-native cognition. Agents navigate capability graphs by meaning using vector embeddings. Memory works in embedding space. Self-extension is fully autonomous.

Phase 4: Autonomous Agent Runtime (v3.0.0 to v4.4.0)

The OS is complete. Now it runs. A persistent daemon cycles through agents, generates plans with a local LLM, executes multi-step pipelines with real data flowing between steps, and produces verifiable artifacts. Goals persist across restarts. Agents accumulate memory. The system governs its own capability expansion through quorum voting.

Phase 5: App Store and Natural Language Install (v4.5.0 to v4.9.0)

128+ tools available via natural language. Type what you want, the system finds the tool, resolves dependencies, clones the repo, synthesizes a wrapper, and launches it. Wrappers are versioned and auto-repaired when they break.

Phase 6: Psychological Layer and HollowOS (v5.0.0 to v5.4.0)

The suffering system, persistent agent identity, and the invoke_claude collaboration model. Plus HollowOS, a web-based graphical shell (in development).

Polling is how you build a prototype. Interrupts are how you build a system.

Agents subscribe to typed event patterns and receive notifications in their inbox when matching events fire. Every subsystem emits events. Subscriptions support glob patterns (task.*, agent.terminated, security.*) and TTLs. The event log is append-only and persists across restarts.

Events emitted system-wide: agent.registered, agent.terminated, agent.suspended, agent.resumed, budget.warning, budget.exhausted, task.queued, task.started, task.completed, task.failed, task.token_chunk, task.partial_available, task.cancelled, message.received, decision.resolved, spec.activated, file.written, txn.committed, txn.rolled_back, txn.conflict, security.anomaly, security.circuit_break, audit.archived, vram.pressure, memory.pressure, model.loaded, model.evicted.

kill() and terminate() are not the same thing. SIGTERM means "shut down cleanly within this grace period." SIGPAUSE means "checkpoint and wait." SIGINFO means "report your current state."

Hollow implements all three. An agent that ignores SIGTERM is force-killed by a watchdog after the grace period. Every terminated agent writes a tombstone: last task, token usage, cause of death, list of children. Process groups let you SIGTERM an entire spawned subtree atomically. Children of a terminated agent are re-parented to root.

Loading a model takes a few seconds. If it's already in VRAM from the previous task, that cost is zero. The scheduler tracks what's loaded, routes tasks to already-loaded models where possible, and evicts LRU models under memory pressure.

Three priority tiers: URGENT (0) preempts BACKGROUND (2) workers via checkpointing. Complexity routing: 1-2 uses the smaller model, 3-4 uses a mid-size model, 5 uses the largest available. Affinity routing: if a suitable model is already in VRAM, use it regardless of the complexity tier.

Language models have no persistent working state between calls. A working memory heap gives agents a place to store intermediate results with actual memory management: TTL expiration, priority-based eviction under pressure, on-heap compression when a slot needs to shrink without being freed.

This is not a key-value store. It's a heap with an eviction policy, the same concept as any OS page frame manager, applied to agent context.

Every operation goes through a single audited boundary. The log is append-only. The audit log and baseline files are blocklisted at the path level — no agent can overwrite them via the filesystem API.

Z-score anomaly detection runs per-agent against a per-role baseline established from the first 50 operations. Anomalies fire at 3 sigma. Circuit breaks fire at 5 sigma. When an agent's anomaly score exceeds that threshold, the circuit break fires: the agent is suspended, its rate limits are reduced to 10% for 5 minutes, a security.circuit_break event fires, and root receives a review decision in its inbox. Causal fields on every entry: caused_by_task_id, parent_txn_id, call_depth.

Two agents writing to the same file is a race condition. Transactions make it a conflict instead — detectable, handleable, not silently corrupting.

txn_begin() opens a transaction. txn/stage(fs_write | message_send | memory_set) buffers operations without applying them. txn/commit() applies everything atomically, detecting conflicts (file modified between begin and commit) and rolling back if any op fails. Uncommitted writes are invisible to readers. Transactions that don't commit within 60 seconds auto-roll back.

The audit log tells you what happened. Lineage tells you why: which agent spawned which agent, which task created which agent, which agents are affected if a given agent fails right now.

agent_lineage(id) returns the full ancestor chain. agent_subtree(id) returns the recursive descendant tree with edge types (spawned, delegated, signaled, transacted). agent_blast_radius(id) computes forward-reachability: affected descendants, held locks, open transactions, running tasks. task_critical_path(id) finds the longest depends_on chain through the task graph — the wall time you cannot parallelize away.

submit(stream=True) returns immediately with a task_id, stream_url, and partial_url. Token chunks arrive as SSE events. GET /tasks/{id}/partial returns a snapshot of accumulated output without connecting to the stream. DELETE /tasks/{id} cancels and frees the worker.

submit(wait=True) still works exactly as before.

Per-resource limits: tokens_in, shell_calls, api_calls, task_submissions. Per-role defaults with per-agent overrides. 429 responses include a Retry-After header.

Circuit breaker fires at 5 sigma anomaly score: agent suspended, rate limits cut to 10% for 5 minutes, event fires, root gets a review decision with options ["restore", "terminate"].

Checkpoints serialize everything: memory heap contents, unread inbox messages, current task snapshot, and agent metadata. Restore overwrites the current state with the saved snapshot. The agent resumes as if the interruption never happened.

Three auto-checkpoint triggers: before transaction commit, on SIGPAUSE, and after tasks over 30 seconds.

Replay runs a task N times from the same checkpoint and measures response consistency (Jaccard similarity across runs). A factual question should score above 0.95 across 5 runs. An ambiguous question will score lower and produce a divergence_points list showing where runs first diverged. This is the foundation for measuring agent determinism.

One agent reaching a conclusion is a decision. Multiple independent agents reaching the same conclusion is a commitment that survives the failure or compromise of any single participant.

A proposer submits an action with a list of participants and a required vote count. Participants receive a consensus.vote_requested event and vote. Early rejection is computed: if the remaining uncast votes cannot mathematically close the gap, the proposal is rejected immediately rather than waiting for the TTL. This prevents cascading delays in time-sensitive pipelines.

Consensus is a coordination mechanism, not an executor. consensus.reached carries the action dict; the proposer acts on it.

The adaptive router observes every task completion — model, complexity, duration_ms, tokens_out, success — and maintains exponential moving averages (EMA, alpha=0.15) per (model, complexity) pair. The composite score weights success rate highest (50%), then throughput (30%), then latency (20%).

Routing decision hierarchy:

1. Hard override — admin-set rules that bypass scoring entirely
2. Adaptive score — highest-scoring model with at least 5 observations for this complexity tier
3. VRAM affinity — prefer already-loaded model to avoid eviction cost
4. Static tier default

Overrides resolve by specificity: agent_id beats role beats complexity-only beats global.

Agents navigate capabilities by meaning, not by name. When an agent needs to do something, the capability graph returns semantically similar capabilities using cosine similarity over nomic-embed-text embeddings. This means agents can discover relevant tools without knowing their exact names.

Semantic memory stores per-agent experience: after each successful goal step, a summary is embedded and stored. Future goals retrieve relevant past experiences at planning time, injecting them into context so agents can build on prior work and avoid repeating mistakes.

The workspace is continuously indexed: every file in /agentOS/workspace/ is chunked with an AST-aware splitter and embedded. semantic_search and read_context return chunks ranked by cosine similarity to the query, not by filename. This is how agents find relevant code across a large workspace without scanning every file.

Seven structural scenarios that don't require Ollama:

Two Ollama-dependent scenarios (task_latency_c1, task_latency_c3) measure end-to-end task latency at each complexity tier. GET /benchmarks/compare diffs any two runs and flags regressions (>15% degradation) and improvements (>15% gain).

Selected numbers from live system runs: