docs(architecture): define agent-managed compute plan

CLAUDE.md

@@ -35,25 +35,25 @@ This repo's bottleneck is agents paying a **re-discovery tax**: re-reading 15 fi
 
 0. **`docs/canonical-api.md`** — THE API reference + anti-reinvention decision table ("I want to ___ → use ___ → NOT ___"). The genome→run→optimize→gate spine, the recursive atom (persona=driver, `spawnChild`=worker|sub-driver, isolated|`Workspace` artifact, conserved sub-budgets, analyst dimensions+gaps), every signature `file:line`-verified. **Read before writing ANY orchestration/optimization/measurement code** — if you're about to write `runConversation`, a "skill optimizer", a "profile-seam", or a `new Sandbox(...)` loop, it already exists. **§1.5 is the AgentProfile law we keep forgetting:** an agent IS its full profile (prompt+skills+tools+mcp+subagents+hooks); you change behavior by AUTHORING the profile and letting the sandbox substrate materialize it into harness shapes — never write a verify-loop or harness-specific config (self-verification is a hook/process, not code; opencode is only the cli-bridge test target — generalize, never specialize).
 1. **`docs/architecture.md`** — the canonical spine (one recursive `Agent` atom; two timescales; benchmark-as-adapter; selector≠judge). Wins on any architecture conflict. `docs/README.md` indexes the rest; `docs/roadmap-rsi.md` is the dependency-ordered build plan; `docs/architecture-interpretations.md` defines **the decision gate**.
+   **`docs/agent-managed-compute/README.md`** is the active audit and implementation plan for distributed coordination, provider-backed workers, recovery, and run-API convergence.
 2. **`bench/HARNESS.md`** — the experiment-harness map: commands, the `rollout → corpus → selector → CI → gate` data flow, the wired/needs-creds/scaffolded matrix, and run-the-gate-in-2-lines. Read it before touching `bench/`.
 3. **`.evolve/current.json`** — the single source of truth for the active goal + generation + the live science state. Then `.evolve/progress.md` and the newest `.evolve/pursuits/*.md`.
 4. **Persistent memory** (`MEMORY.md` + the `memory/` notes) — the code-map and the evidence ledger. Start with the map; verify it, don't rebuild it.
 
 **The anti-staleness law:** these maps are kept short and code-adjacent. If a map disagrees with the code, the **code wins** — fix the map in the *same* turn. Discovery is paid once, by whoever records it. When you learn something undocumented, write it to the map/memory before moving on. **For `docs/canonical-api.md` this is now ENFORCED, not aspirational:** the mechanical leaves (per-symbol signatures + `file:line`) are GENERATED into `docs/api/` by TypeDoc — never hand-edit them — and a CI freshness gate (`pnpm docs:check` → `scripts/check-docs-freshness.mjs`) turns a stale version pin, a broken `file:line` citation, or a decision-table symbol that no longer exists into a RED BUILD. The judgment layer (§2 decision table, when-to-use, every "Do NOT") stays hand-curated and the gate never touches it. Local fix path on a red docs gate: `pnpm run docs:api` then commit, or fix the cited line — see `docs/MAINTAINING.md`.
 
-## Repo layering — this package depends on agent-eval, never the reverse
+## Repo layering
 
-```
-agent-knowledge ──► agent-runtime (this repo — wraps the substrate)
-       │                  │
-       └──────────────────┴──► agent-eval (substrate — the bottom)
-```
+- `agent-interface` owns portable contracts.
+- `agent-eval` depends on `agent-interface` and owns evaluation data and decisions.
+- `agent-knowledge` depends on `agent-interface` and `agent-eval`, and never on this runtime.
+- `agent-runtime` depends on those lower packages and composes optional knowledge workflows from `src/knowledge/`.
 
-agent-knowledge depends on agent-runtime (it imports `/loops`) and on agent-eval. agent-runtime depends ONLY on agent-eval and deliberately does NOT import agent-knowledge — domain stores/tools enter by injection (`createMcpServer({ feedbackStore })`, per `src/mcp/feedback-store.ts`), so importing the domain package would induce a dependency cycle.
+**Rule: lower packages MUST NOT import from agent-runtime.** No `peerDependencies` in `agent-eval` or `agent-knowledge` pointing here, and no `import type { X } from '@tangle-network/agent-runtime'` inside either package. A spotted upward import is a bug. Move a portable contract into `agent-interface`, an evaluation concept into `agent-eval`, or inject runtime behavior through a callback.
 
-**Rule: agent-runtime depends on agent-eval. agent-eval MUST NOT import from agent-runtime.** No upward imports, no `peerDependencies` in agent-eval pointing here, no `import type { X } from '@tangle-network/agent-runtime'` inside agent-eval. A spotted upward import is a bug — file an issue and move the type into agent-eval. agent-eval is declared a **required `peerDependency`** (floor: whatever `package.json` `peerDependencies` says — do not restate the number here), not a hard dependency — keep it in sync with the `selfImprove`/`heldoutSignificance`/`loopDispatch` APIs the code uses.
-
-**The runtime stays domain-clean by taking domain stores/tools as injected adapters, never importing a domain package** — the dependency arrow points up into this repo (agent-knowledge → agent-runtime), never down out of it.
+`agent-eval` is declared a required `peerDependency` here.
+Keep its range aligned with the APIs the runtime consumes.
+`agent-knowledge` is a direct dependency because `src/knowledge/improvement-job.ts` provides the batteries-included composition, while the pure knowledge package remains independently usable.
 
 Substrate primitives CONSUMED from agent-eval: `DefaultVerdict`, `RunRecord`, `AgentEvalError` + taxonomy, `AnalystFinding`/`AnalystRunResult`/`FindingsDiff`, `TraceAnalystKindSpec`, `KnowledgeReadinessReport`, and the campaign types (`DispatchContext`/`ProfileDispatchFn`/`Scenario`, type-only).
 
@@ -64,7 +64,7 @@ Types that stay in THIS repo because they're runtime-shaped (coupled to a runnin
 ## Code map — the loop kernel & the recursive atom (src/runtime/)
 
 - `run-loop.ts` — `runLoop`, the round-synchronous leaf kernel. Per round: `driver.plan()`→N tasks→one sandbox/iteration (bounded by `maxConcurrency`, round-robin `agentRuns`)→`streamPrompt`→`output.parse`→`validator.validate`→`driver.decide`. Owns iteration accounting, concurrency, abort, cost+token aggregation, trace emission, box teardown. Exports `defaultSelectWinner` (best-valid-score, ties→earliest) — the single-sourced selection the personify combinators reuse.
-- `supervise/` — the recursive execution atom (keystone): `Scope` + `Supervisor` over the open `Executor` port, spawn/settle on a **conserved budget pool** so equal-compute holds by construction; journal→replay/resume. `runtime.ts` also holds `createExecutor({backend})` — the ONE built-in executor (backend-as-data: `router`/`router-tools`/`bridge`/`cli`/`sandbox`; `router-tools` is the off-box tool-using agentic loop — chat→tool_calls→`executeToolCall`→repeat — over the router's tool-calling, no sandbox); the per-backend bodies are internal case-arms, BYO agents implement `Executor` directly.
+- `supervise/` — the recursive execution atom (keystone): `Scope` + `Supervisor` over the open `Executor` port, spawn/settle on a **conserved budget pool** so equal-compute holds by construction; the journal replays completed settlements, but live supervised-tree recovery after coordinator restart is not implemented. `runtime.ts` also holds `createExecutor({backend})` — the ONE built-in executor (backend-as-data: `router`/`router-tools`/`bridge`/`cli`/`sandbox`; `router-tools` is the off-box tool-using agentic loop — chat→tool_calls→`executeToolCall`→repeat — over the router's tool-calling, no sandbox); the per-backend bodies are internal case-arms, BYO agents implement `Executor` directly.
 - `personify/` — the content-free generic combinators (`fanout`/`loopUntil`/`widen`/`panel`/`verify`/`pipeline`) + `definePersona`/`runPersonified` + the cross-run `Corpus` + `createScopeAnalyst` (the analyst-on-scope steer firewall).
 - the **agent-driver** is the canonical "drive an agent" path: an `AgentProfile` driving another `AgentProfile` via the coordination toolbox (`createCoordinationTools`, `src/mcp/tools/coordination.ts`) over the `Scope`/`Supervisor`, plus `runAgentic`/`defineStrategy`/`runPersonified` (`strategy.ts`/`personify/persona.ts`) on the Supervisor. Child→parent messages ride ONE typed pipe — `createEventBus` (`supervise/event-bus.ts`): settled outputs, `ask_parent` questions, and analyst findings are all `CoordinationEvent` kinds, delivered pass-through (`subscribe`/`onEvent`, immediate) AND queued for the driver to pull (`await_event({kinds?})` — the ONE wait verb; `kinds:['settled']` = next finished worker, omit = also questions/findings). The pull queue is **priority-ordered** — a blocking question (urgency→priority: `blocks-run`=20/`blocks-step`=10) is bumped ahead of queued settles/findings; ties FIFO by `seq`. The bus is **bidirectional**: UP (settled/question/finding) is queued+pullable; DOWN (`steer_agent` for any live worker — instruction/correction/continuation; `answer_question` routes an answer down) goes to the child inbox via `scope.send`→`deliver` AND records a `queue:false` event (history + subscribers, never pulled back). The receive end is `createInbox` (`supervise/inbox.ts`), which the owned tool-loop executor (`routerToolsInlineExecutor`) exposes as `Executor.deliver`: QUEUED messages flush at each step boundary AND before the worker may settle (it can't finish with an unread steer); a FORCEFUL `steer_agent({interrupt:true})` aborts the in-flight turn so the worker re-plans immediately. Black-box CLI harnesses can't be interrupted mid-step, so there the down-leg degrades to the next spawn. Observability is first-class: every event both ways is stamped (`seq`/`at`/`priority`), the full `history()` is an audit/replay trail, `stats()` counts throughput (both surfaced on `CoordinationTools` and the MCP handle). `analyzeOnSettle` auto-fires trace analysts when a worker settles `done`, re-entering each result as a `finding` on the same bus (cost-governed opt-in; the firewall stays in the analyst registry). Trace analysis is **substrate- AND harness-agnostic** via `TraceSource` (`supervise/trace-source.ts`) — a worker's tool calls as agent-eval `ToolSpan`s from EITHER an owned loop (`createPushTraceSource`; `routerToolsInlineExecutor`'s `onToolStep` feeds `record`) OR a sandbox/fleet box (`sandboxSessionTraceSource(box, sessionId, {harness})` reads `box.messages()` session parts). Harness wire-shapes are decoded by a **per-harness adapter registry** (`toolPartDecoders`): `decodeOpencodePart` decodes against the **canonical `ToolPart`/`ToolState` published by `@tangle-network/agent-interface`** (the type every adc sdk-provider normalizes into — single source of truth, so a status adc adds/renames is a compile error here, not a silent miss; terminal-state + callId-dedup; also live-box-validated), `decodeAnthropicPart` (claude-code/kimi `{type:'tool_use', id|tool_use_id, name|tool, input}` confirmed vs `cli-bridge/src/backends/claude.ts`+`kimi.ts`), `decodeOpenAiPart` (router/kimi top-level `function`). **codex emits NO structured tool calls** (bridge `codex.ts` never yields `tool_calls` — text+shell only) → per-tool detection unavailable for codex from any path (harness property, not a gap). `decodeToolPart(part, harness?)` picks the adapter or tries all. Add a harness = add a decoder + one entry, validated against the cli-bridge backend. Two consumers ride a source: ONLINE `watchTrace` (`detector-monitor.ts`) folds live spans through agent-eval's published streaming kernel (`repeatedActionDetector`/`errorStreakDetector`, the SAME kernel `control-runtime` folds) → `onSignal` → a `finding`; SETTLE `analyzeTrace` (`trajectory-recorder.ts`) collects the spans and runs the published BATCH analyzers (`buildTrajectory`/`stuckLoopView`/`toolWasteView`). `ToolSpan` is the common currency; detection logic + the failure taxonomy live in agent-eval — never reimplement here. Production target = sandbox/fleet; the owned-loop push path is for local/router/cli-bridge. The in-process queue and a future cross-box durable mailbox share this one interface. `assertTraceDerivedFindings` (`personify/analyst.ts`) is the steer-firewall (selector≠judge). `types.ts` holds `Driver`/`AgentRunSpec`/`OutputAdapter`/`Validator`/`Iteration`/`LoopResult`/`SandboxClient` + the `LoopTraceEvent` union. `sandbox-run.ts` is `openSandboxRun` — the one run/stream/resume sandbox seam; `inline-sandbox-client.ts` is `inlineSandboxClient` — the one adapter presenting any non-box `Executor` as a `SandboxClient` for `runLoop`. `loop-dispatch.ts` adapts `runLoop`→agent-eval campaigns; `report-usage.ts` forwards token usage so the integrity guard sees a real backend.
 

docs/README.md

@@ -16,6 +16,7 @@ The map of every doc. **Start here** if you're new; the deeper tracks follow.
 | # | Doc | Role | Purpose |
 |---|---|---|---|
 | 1 | [architecture.md](./architecture.md) | **canonical spine** | One recursive agent tree, two timescales, many benchmarks — the visual mental model (`act`/`Scope`/recursion, the up-flow, the three improvement timescales) folded in. The single source of truth; wins on conflict. |
+| 1a | [agent-managed-compute/](./agent-managed-compute/) | **distributed execution plan** | Current-state audit, converged design, failure behavior, dependency-ordered roadmap, and measurable completion criteria for agents that allocate and steer compute. |
 | 2 | [architecture-interpretations.md](./architecture-interpretations.md) | coherence verdict | Stress-tests the spine through five lenses + the decision gate. Answers "does it cohere?" — and where it doesn't. |
 | 3 | [roadmap-rsi.md](./roadmap-rsi.md) | build plan | The dependency-ordered sequence from scaffold to a measured surface. Phases, exit gates, open decisions. |
 | 4 | [learning-flywheel.md](./learning-flywheel.md) | theory deep-dive | The moat thesis — the `(π, τ, J, D, O)` recursion and cross-run flywheel. |
@@ -32,7 +33,7 @@ The map of every doc. **Start here** if you're new; the deeper tracks follow.
 | [glossary.md](./glossary.md) | canonical vocabulary | One definition per term, grounded to `file:line`; drifted synonyms flagged. |
 | [execution-model.md](./execution-model.md) | the picture | The unified `Executor` port (router/bridge/cli/sandbox/BYO) + two engines, driver vs worker, spawn mechanics. |
 | [agent-bus-protocol.md](./agent-bus-protocol.md) | normative protocol | The multi-agent call bus — depth limits, headers, refusal contract. |
-| [durability-adapters.md](./durability-adapters.md) | subsystem | Journal + durability for resumable conversations + supervisor trees. |
+| [durability-adapters.md](./durability-adapters.md) | subsystem | SQL-backed journal and restart behavior for conversations. Supervised-tree recovery is not implemented. |
 | [intelligence-sdk.md](./intelligence-sdk.md) | product SDK | Observe + OFF billing floor + effort tiers + certified delivery + capability resolver — the `/intelligence` subpath. Designed-not-shipped verbs fenced at the tail. |
 | [BUILDING.md](./BUILDING.md) | process | Building discipline: goal first, cheapest decisive proof, verification rules. |
 | [ANTI_PATTERNS.md](./ANTI_PATTERNS.md) | process | Named failure modes. |
@@ -42,7 +43,7 @@ The map of every doc. **Start here** if you're new; the deeper tracks follow.
 
 | Doc | Role | Purpose |
 |---|---|---|
-| [simplification-plan.md](./research/simplification-plan.md) | **live tracker** | The in-flight simplification/rearchitecture: the converged design, the scratch list, the doc/module inventory, the workstreams + completion criteria. |
+| [simplification-plan.md](./research/simplification-plan.md) | historical tracker | Earlier simplification analysis. The active execution and API convergence plan is [agent-managed-compute/roadmap.md](./agent-managed-compute/roadmap.md). |
 | [research/README.md](./research/README.md) | research index | Forward-looking design threads + decision log. Not the canonical spine. |
 | [archive/](./archive/) | retired notes | Superseded/niche docs kept for history (delivery manifest, conversation economics, artifact-lifecycle, go-live, results, benchmark-matrix consolidation). |