@iowarp/clio-coder 0.3.0 → 0.3.2

package/docs/fleet-demo-runbook.md

@@ -10,38 +10,38 @@ Background and reference: [fleet-dispatch.md](fleet-dispatch.md).
 
 | Role | Machine | Notes |
 | --- | --- | --- |
-| Orchestrator | `zbook` | Runs the interactive Clio session. |
-| SSH node | `blade` | General worker capacity. |
-| SSH node | `mini` | Serves the operator's resident models on its GPU; residency stays observe. |
-| SSH node | `dragon` | General worker capacity. |
+| Orchestrator | `local` | Runs the interactive Clio session. |
+| SSH node | `node-a` | General worker capacity. |
+| SSH node | `node-b` | Serves the operator's resident models on its GPU; residency stays observe. |
+| SSH node | `node-c` | General worker capacity. |
 
 All four machines share the filesystem, so the project root resolves to the
 same absolute path everywhere. The demo project is any CMake/C++ repository
 with a known failing build or test; a one-line compile error in a `.cpp` file
 works well on camera.
 
-## 1. Declare the fleet (zbook)
+## 1. Declare the fleet (local)
 
 Add the nodes to `settings.yaml` (see `clio-coder paths` for its location):
 
 ```yaml
 fleet:
   nodes:
-    - id: blade
-      host: blade
+    - id: node-a
+      host: node-a.example.net
       maxWorkers: 2
-    - id: mini
-      host: mini
+    - id: node-b
+      host: node-b.example.net
       maxWorkers: 1
       residency: observe
-    - id: dragon
-      host: dragon
+    - id: node-c
+      host: node-c.example.net
       maxWorkers: 2
 ```
 
-The implicit `local` node (zbook itself) is never declared. `residency:
+The implicit `local` node (the orchestrator host itself) is never declared. `residency:
 observe` is the default and is written here only to make the demo point
-explicit: workers on mini must never evict its resident models.
+explicit: workers on node-b must never evict its resident models.
 
 ## 2. Preflight the nodes
 
@@ -69,9 +69,8 @@ clio-coder
 
 In the session:
 
-- `/fleet` opens the fleet overlay; Tab cycles status, nodes, profiles, and
-  bindings. The nodes tab shows blade, mini, and dragon online with their
-  capacity.
+- `/fleet` opens Settings → Fleet; its node rows show node-a, node-b, and node-c
+  online with their capacity.
 - Alt+W toggles the dispatch board, which will fill with per-run cards once
   work starts.
 
@@ -82,13 +81,13 @@ placement. Example prompt for the chat input:
 
 ```
 Dispatch the fix for the failing CMake build as a reviewed task: builder on
-node blade, reviewer on node dragon, at most 2 review cycles. The task is:
+node node-a, reviewer on node node-c, at most 2 review cycles. The task is:
 "Fix the compile error in src/mesh/loader.cpp so `cmake --build build` and
 `ctest --test-dir build` both pass. Keep the change minimal."
 ```
 
 The model calls the dispatch tool with `review: {max_cycles: 2, node:
-"dragon"}` and `node: "blade"` on the task. Because a remote placement is
+"node-c"}` and `node: "node-a"` on the task. Because a remote placement is
 plan-scale, supervised autonomy parks the call and shows the plan artifact
 (topology, per-task agent, model, node); one approval launches the whole
 plan. Full-auto skips the stop and seals the plan hash into the receipts
@@ -96,15 +95,15 @@ instead.
 
 What to watch:
 
-- The board card for the builder shows `node blade`, live tool activity, and
+- The board card for the builder shows `node node-a`, live tool activity, and
   the per-worker context meter.
-- The reviewer card shows `node dragon` and `gate reviewer c1`; the reviewer
+- The reviewer card shows `node node-c` and `gate reviewer c1`; the reviewer
   runs read-only and ends with a `VERDICT:` line.
 - On a revise verdict, a second builder card appears with `gate builder c2`;
   the reviewer's findings were threaded to it as input data.
-- `/fleet` status rows carry the node column for both runs.
+- The `Alt+W` Fleet Runs board carries the node column for both runs.
 
-If a node dies mid-run (for the demo: stop sshd on blade), the run finalizes
+If a node dies mid-run (for the demo: stop sshd on node-a), the run finalizes
 as stalled, the node is classified dead after consecutive channel failures,
 and the bounded retry reroutes to a survivor with the hop recorded on the new
 receipt.
@@ -135,7 +134,7 @@ clio-coder evidence inspect <evidenceId>
 
 `clio-coder evidence build` recomputes the receipt's integrity digest against the
 run ledger; a tampered or mismatched receipt fails the build with the field
-that diverged. The receipts of the remote runs verify on zbook because the
+that diverged. The receipts of the remote runs verify on the orchestrator host because the
 ledger and receipts live on the shared filesystem. Current receipts use strict
 v15 and authenticate every current receipt and reconstructed-ledger field.
 Every other receipt version is rejected rather than reported as partial; the

package/docs/fleet-dispatch.md

@@ -1,6 +1,6 @@
 # Fleet Dispatch
 
-> **Interactive Spec Available:** An interactive fleet node topology planner, scout router, receipt verifier, and failure taxonomy simulator is located at [docs/html/fleet_dispatch_blueprint.html](html/fleet_dispatch_blueprint.html) (Version: 0.3.0).
+> **Interactive Spec Available:** An interactive fleet node topology planner, scout router, receipt verifier, and failure taxonomy simulator is located at [docs/html/fleet_dispatch_blueprint.html](html/fleet_dispatch_blueprint.html) (Version: 0.3.2).
 
 Clio Coder dispatches bounded worker agents. With a fleet configured, those
 workers run on remote machines over SSH while the orchestrator keeps every
@@ -37,12 +37,12 @@ attestation are strict protocol evidence, not proof against a malicious child
 that controls its own process; SSH also uses the attested remote process group
 for bounded abort escalation.
 
-Scout routing is advisory rather than forced: the worker operating contract
-steers explicit broad repository exploration to the read-only `scout` recipe,
-and middleware emits a continuation nudge after nine or more manual
-read-only exploration calls without a successful Scout dispatch. Direct reads
-remain allowed; Clio does not automatically rewrite a broad request into a
-Scout run.
+Scout routing is advisory rather than forced: the session's Delegation
+passage steers explicit broad repository exploration to the read-only `scout` recipe,
+and middleware emits one advisory notice after nine or more manual
+read-only exploration calls without a successful Scout dispatch. The advisory
+costs no extra model round. Direct reads remain allowed; Clio does not
+automatically rewrite a broad request into a Scout run.
 
 Design decisions that shape everything else:
 
@@ -82,7 +82,9 @@ Recipes may declare `budget: {toolCalls, readReserve, synthesis}`. `toolCalls` i
 ## Node setup
 
 Fleet nodes are declared under `fleet.nodes` in `settings.yaml`. The implicit
-`local` node always exists and is never declared.
+`local` node always exists and is never declared. A run's node is the host its
+worker process ran on, never the host serving the model, so a run against a
+remote target from this machine still records `node: local`.
 
 ```yaml
 fleet:
@@ -100,13 +102,13 @@ fleet:
       maxWorkers: 1
 ```
 
-`clioEntry` may override the remote invocation (default `clio-coder worker`).
+`clioCoderEntry` may override the remote invocation (default `clio-coder worker`).
 Node ids must be unique and `local` is reserved.
 
 Worker profiles can pin work to a node: `workers.profiles.<name>.node` routes
-every dispatch bound to that profile. The `/fleet` overlay's profiles tab
-edits the pin (`o` key), and the dispatch tool accepts an explicit `node`
-argument per task.
+every dispatch bound to that profile. Settings → Fleet (`/fleet`) edits the
+pin on the profile's `node` row, and the dispatch tool accepts an explicit
+`node` argument per task.
 
 ## Doctor preflight
 
@@ -173,6 +175,12 @@ accepted by the current reader.
   failures change the process-local registry health to `offline`. Doctor
   preflight is a separate durable eligibility gate: a failed or stale record
   blocks placement without pretending it changed channel health.
+- A result-contract repair round is a synthetic tool exchange, and its assistant
+  half carries explicit zero usage. Request sizing reads usage from every
+  assistant message that is not aborted or errored, and a repair message with no
+  usage crashed the worker one round after its terminal message. Zero usage is
+  skipped by the estimator, so the model's last real usage still anchors the
+  estimate and the worker survives the repair round (#70).
 
 ## Topologies
 
@@ -192,6 +200,56 @@ request-level `autonomy` can only narrow the level (reviewers and judges run
 | Compete | `mode: "compete", candidates: 2..4` | N candidates in scratch worktrees, read-only judge, winner applied or preserved. |
 | Agent automation | `agent: "auto"` | Baselines candidate agent from task shape via shared classifier (`coder`, `tester`, `documenter`, `verifier`, `researcher`, `scout`); advisory unless activated. |
 
+### Agent ledger
+
+Every topology that runs more than one worker at once opens an agent ledger, the
+bounded coordination board those workers share while they run: the parallel
+fan-out (`src/tools/dispatch.ts:3247`), a detached batch of two or more
+(`:538`), and compete (`:1549`). A worker reaches it through the `ledger` tool
+and posts one of three typed entries. A `claim` stakes path prefixes so peers
+stop colliding, a `finding` reports one observation with the path and line that
+ground it, and a `review` judges another entry by its id. Nothing untyped is
+postable, and a run gets 20 posts.
+
+The orchestrator is the sole writer. A post travels up the control lane as a
+body and nothing else, and every attribution field is stamped from the
+orchestrator's own admission record, so no worker-supplied value can reach a
+field a peer or a receipt reads as identity. Admitted entries are pushed back
+down as `ledger_delta` stdin frames into a per-worker mirror, so a read answers
+locally with a watermark instead of blocking on a round trip. A worker that
+spawns late is handed the whole board twice over: the hub replays it on
+subscription, and it is rendered into that worker's dynamic prompt messages at
+spawn as untrusted peer data.
+
+The reducers never merge. Citations are compared in workspace-relative form, so
+`./src/a.ts` and the absolute path of that file are one path. A path cited by
+two or more runs is corroborated, a path cited by one is uncorroborated and still rendered standing on its own, a
+finding with no citation is an ungrounded lead, and an entry a review failed is
+marked disputed where it stands. Overlapping claims from different runs carry
+the ids they overlap, which is advisory; the per-wave write boundary is what
+actually stops two writers.
+
+When the board closes depends on where the batch settles. An attached parallel
+fan-out closes it when the tool call returns, and compete closes it once every
+candidate and the judge have settled. A detached batch, and a parallel batch the
+operator moved to the background, carry the ledger id on the durable batch
+record and close it on the first `monitor(mode="collect")`, because their peers
+stay concurrent past the call that started them. After the close, appends are
+refused and counted.
+
+The main model reads the board too, once its workers have all settled. The
+parallel dispatch result, the compete result, and `monitor(mode="collect")` for
+a detached batch each carry one `agent ledger (<n> entries, sequence <w>)`
+section after the per-run lines, holding the same bounded render a worker sees,
+with the same attribution and the same corroboration and dispute marks and
+still no count, score, or consensus line. The same text is on the result's
+`details.agentLedgerBoard`. A board nobody posted to is omitted, so a
+single-run dispatch and an unused board read exactly as they did before.
+
+What survives into a receipt is that run's `ledgerContribution`, which is the
+ledger id, its posted and refused counts, and a sha256 over its own attributed entries, sealed orchestrator-side
+and covered by receipt integrity.
+
 ### Detached fan-out, backgrounding, and collect
 
 `detach: true` validates, admits, and spawns every task, then returns. The
@@ -481,7 +539,7 @@ closed while a winner remains unapplied.
 Receipts carry exactly one integrity version (`RUN_RECEIPT_INTEGRITY_VERSION = 15`), which authenticates the complete receipt and reconstructible ledger provenance surface. There is no historical verification path: any other version is invalid, and a receipt that fails verification is never read as evidence. The fleet provenance fields covered by the digest
 include:
 
-- `node`: the fleet node the worker ran on (`id`, `kind`, `host`).
+- `node`: the fleet node the worker ran on (`id`, `kind`, `host`). The `node.id` explicitly identifies the worker process host executing the task, not the model host (which is represented by the `target` id). This behavior tracks issue #120.
 - `reroutes`: dead-node failover hops, oldest first.
 - `gate`: review/compete provenance (role, group, cycle, subject run ids with
   their receipt digests, and the verdict that caused a revise builder).
@@ -545,6 +603,44 @@ hard block.
 
 ## Operator visibility
 
+- Every run carries the origin that asked for it, and every surface shows it
+  with the same pair of glyphs: `◇` for a run the operator started with `/run`
+  or `/delegate`, `◆` for one the model started by calling a dispatch tool, and
+  a dim `·` for the runs Clio starts for itself. A running `◇` on the board is
+  therefore the operator's own work. The footer chip in the status line splits
+  into `◇1 ◆3` when more than one kind is live and stays `fleet N` otherwise.
+  Board rows carry an origin glyph too.
+- User-origin and agent-origin runs stream into the chat transcript as an
+  attributed worker block. The typed command is echoed dim above the block.
+  Header units display `<agentId>` then `<targetId>/<wireModelId>` then `run <runId>`
+  for fleet workers (such as `◇ coder · node-a/example-coder-model · run 2mkas6s`),
+  or `<id> (acp) · run <runId>` with no route for ACP delegation peers. The block
+  body renders the worker prose down a rail, one coalesced line of tool names,
+  and a one-line receipt footer showing the outcome glyph, token count, duration,
+  and contract status (such as `└ ✓ ok · 8.4k tok · 18s · contract unmeasured`),
+  with the failure reason printed on the rail above the footer when a run fails.
+- Runs the model itself asked for through the dispatch tool (identified by
+  parentToolCallId) render as folded `◆` cards under the spawning tool segment;
+  operator-typed runs are `◇` and open. The fold chord uses the `clio.tool.expand`
+  keybinding (`Alt+O`), which toggles the newest foldable item of either kind
+  (tool call or worker block). `Ctrl+Alt+O` or `Alt+Shift+O` toggles every tool
+  call and worker block at once.
+- Sharing: nothing a worker produced enters the main model's context unless
+  `--share` was passed or the operator runs `/share [runId]`. What enters is a
+  bounded note of the shape `[worker result] <agent> · run <id> · <outcome> · shared by the operator`
+  followed by the bounded answer text, traveling the ordinary user-turn path.
+  The operating contract tells the main agent that this note is operator
+  steering backed by a readable receipt, not a tool result to verify against
+  its own dispatch history.
+  Bare `/share` picks the newest finished run the operator started themselves
+  (never a model-asked `◆` run); `/share <runId>` may name a model-asked run
+  explicitly. `/new` resets the transcript and the pool bare `/share` draws
+  from, so a run from the previous session cannot be shared into the new one.
+- Replay: `/resume` replays worker blocks from receipts; the session file's
+  `workerRun` entries carry ids, origin, and runtime only, without prose; the
+  replayed answer is bounded from the receipt exactly like the live one. A
+  missing receipt renders `receipt unavailable`.
+- Memory workers on the background target never appear as transcript blocks.
 - The dispatch board shows per-run cards with the node id (absent placement
   renders `local`), gate badges (`gate reviewer c2`), reroute badges, live
   tool activity (names only; arguments never cross the worker stdout seam),
@@ -552,9 +648,9 @@ hard block.
 - The context meter renders the worker's last-message context occupancy
   against the model's context window: healthy below 80 percent, warn from 80,
   critical from 95.
-- `/fleet` cycles status (running and retrying runs with a node column),
-  nodes (the registry view with state, capacity, and last-seen), profiles
-  (with the node pin), and bindings.
+- `/fleet` opens Settings → Fleet: profiles (with the node pin), bindings,
+  and read-only node rows (state, capacity, and last-seen). Running and
+  retrying runs, with their node, live in the `Alt+W` Fleet Runs board.
 - The monitor tool reports the node and reroute lineage on `status`, `list`,
   and `collect`.
 - `clio-coder fleet status [--json]` shows the durable ledger view cross-process.
@@ -575,6 +671,11 @@ Remote workers default to residency observe: the SSH transport exports
 them. A node opts into management explicitly with `residency: manage` in its
 fleet entry.
 
+A model the router tags as pinned (`pinned:true` or `role:scout`) is never
+evicted once resident, so Clio refuses to load it by evicting a resident that
+settings still reference by role; on a one-slot router such an override
+declines with a `will-not-fit` notice instead of stranding the configured model.
+
 ## Opt-in live regression
 
 After `npm run build`, an operator with a configured model target can run the

package/docs/git-commit-provenance.md

@@ -0,0 +1,120 @@
+# Git Commit Provenance
+
+Clio Coder adds evidence-aware role trailers to commits created through Clio.
+The feature is enabled by default:
+
+```yaml
+attribution:
+  gitCommits: true
+```
+
+Settings -> Advanced exposes the same switch as **Clio commit provenance**, with
+`enabled` and `disabled` values. A change applies immediately to subsequent
+commits in the session. When disabled, Clio leaves commit messages entirely
+unchanged.
+
+## Canonical identity
+
+The identity is compiled into Clio and is not user-editable:
+
+```text
+Clio Coder <clio-coder@iowarp.ai>
+```
+
+Clio never replaces the human author or committer. The person and Git identity
+that made the commit remain in the commit's author and committer fields.
+
+## Evidence-dependent roles
+
+Each trailer states what trusted execution evidence proves. A role is not an
+advertisement and is never inferred from an agent saying in prose that it ran a
+check or performed a review.
+
+```text
+Assisted-by: Clio Coder <clio-coder@iowarp.ai>
+Tested-by: Clio Coder <clio-coder@iowarp.ai>
+Reviewed-by: Clio Coder <clio-coder@iowarp.ai>
+Co-authored-by: Clio Coder <clio-coder@iowarp.ai>
+```
+
+- `Assisted-by` means Clio materially created or edited work in the commit.
+- `Tested-by` means an actual validation command completed successfully against
+  the work. Prose that claims tests passed is not evidence.
+- `Reviewed-by` means an independent verifier or reviewer produced a passing
+  result. A self-review or an unsealed assertion is not enough.
+- `Co-authored-by` is added only when Clio materially authored part of the
+  change. GitHub and GitLab recognize this compatibility trailer for
+  contributor and avatar display. Testing or review alone never adds it.
+
+Existing human trailers stay in place. A Clio trailer already present in any
+letter case is respected rather than repeated, line endings are normalized only
+while attribution is enabled, and repeated processing is idempotent. When a directly relevant
+receipt-v15 digest passes integrity verification, Clio may additionally add the
+full digest:
+
+```text
+Clio-Evidence: receipt-v15/sha256:<64-character digest>
+```
+
+Clio does not invent, shorten, or add an unrelated digest. The role trailers do
+not depend on this optional line.
+
+## Commit paths and hooks
+
+The deterministic SDLC fleet attributes its plan, code, and documentation
+commits at the controlled commit seam. Material agent work supplies assistance
+and authorship, successful deterministic code steps supply testing, and a
+passing independent gate supplies review. Any later workspace mutation makes
+prior testing and review stale; only validation or review that is fresh for the
+commit can be claimed.
+
+For Clio-controlled child processes, Clio supplies a process-local managed
+hooks directory through command-scope Git configuration. The directory holds a
+chaining wrapper for every hook name Git knows, so the repository's own
+`pre-commit`, `commit-msg`, `pre-push`, and remaining default hooks still run
+exactly as before with their original exit status. Only the `prepare-commit-msg`
+wrapper adds anything, and only after the repository's own hook has run and
+succeeded. It runs only when both `AI_AGENT=clio-coder` and the effective
+attribution setting are present. It uses `git interpret-trailers`. Normal
+commits from an external terminal do not receive Clio's managed hooks.
+
+The child-process seams attribute by spawn provenance, not by sealed evidence.
+A commit the agent itself runs through the Bash tool, a worker, or a registered
+code step claims assistance and authorship, because it records the agent's own
+session work. A commit made by a delegated external harness over ACP claims
+assistance only, since that harness authored the change. A commit made by an
+operator hook command claims nothing. Testing and review are never claimed at
+these seams; only the fleet's coordinator-owned results can supply them.
+
+The managed hook attributes only a message supplied up front with `-m`, `-F`,
+or a merge. It skips amend, commit-message reuse, squash, cherry-pick, revert,
+rebase, sequencer operations, and editor sessions, so historical messages are
+not falsely attributed and an abandoned editor still aborts the commit.
+`--no-verify` does not bypass `prepare-commit-msg`, matching Git's normal hook
+semantics. The message is finalized at this stage before Git signs the commit,
+so signed commits retain their existing behavior.
+
+Clio never overwrites repository hooks or changes `core.hooksPath`. If a custom
+hooks path or another setup cannot be composed safely, Clio fails open, emits a
+bounded diagnostic, and relies on controlled commit seams such as the fleet
+runner. Attribution failure does not destroy a commit; only a pre-existing hook
+that already failed continues to block it.
+
+The repository probe behind the managed environment (whether the command's
+working directory is inside a work tree, and what `core.hooksPath` resolves to)
+is reused for ten seconds per working directory and Git environment, and the
+managed hooks directory is installed once per process. A `git init` or a
+`core.hooksPath` change takes effect for spawns that begin after that window.
+
+## Platform identity and avatar
+
+Git commit data contains names and email addresses, not logos. GitHub and
+GitLab obtain the displayed avatar from the platform account that has verified
+the commit email. Until maintainers verify `clio-coder@iowarp.ai` on
+IOWarp-controlled GitHub and GitLab identities, for example `clio-coder-bot` or
+`iowarp-clio`, those platforms render the trailers as plain text with a default
+avatar; the trailers themselves are complete and correct either way. That
+verification is a maintainer follow-up rather than a release gate, and
+`assets/clio-coder-avatar-512.png` is an exact PNG conversion of the existing
+512 px Clio logo for platforms that require PNG. No account creation or remote
+operation is performed by Clio Coder.

package/docs/glossary.md

@@ -8,39 +8,39 @@ This document defines core architectural concepts and terminology used throughou
 
 ### 1. Assignment
 - **Definition**: The logical unit of work dispatched to the fleet. An assignment encapsulates the requested task, briefing, authority boundaries, and retry history across one or more concrete run attempts.
-- **Owning Type**: `AssignmentRecord` in `src/domains/dispatch/types.ts`.
+- **Owning Type**: `DurableAssignmentRecord` in `src/domains/dispatch/assignment-store.ts`.
 
 ### 2. Run
 - **Definition**: A concrete execution attempt of an assignment. Every run possesses a unique UUIDv7 identifier, an isolated event stream, a designated execution node, and a final cryptographically sealed receipt.
-- **Owning Type**: `RunRecord` in `src/domains/dispatch/types.ts`.
+- **Owning Type**: `RunEnvelope` in `src/domains/dispatch/types.ts`.
 
 ### 3. Attempt
-- **Definition**: A 1-based sequential retry index of a logical assignment. When a run fails due to retriable infrastructure errors, a new attempt is created while preserving historical attempt records.
-- **Owning Type**: `AssignmentAttemptRecord` in `src/domains/dispatch/types.ts`.
+- **Definition**: A 0-based sequential retry index of a logical assignment. The first run of an assignment is attempt 0; a retry after a retriable infrastructure error increments it while preserving the earlier attempt's own run and receipt.
+- **Owning Type**: `RunLineage.attempt` in `src/domains/dispatch/types.ts`.
 
 ### 4. Batch
 - **Definition**: A durable collection of detached assignments created and tracked together under a single batch ID (`batches.json`).
-- **Owning Type**: `BatchRecord` in `src/domains/dispatch/types.ts`.
+- **Owning Type**: `DetachedBatchRecord` in `src/domains/dispatch/batch-store.ts`.
 
 ### 5. Plan
 - **Definition**: A multi-step directed acyclic graph (DAG) defining steps, dependencies, code validations, and budget ceilings approved by the operator before dispatch.
-- **Owning Type**: `ExecutionPlan` in `src/domains/dispatch/types.ts`.
+- **Owning Type**: `ExecutionPlan` in `src/domains/dispatch/execution-plan.ts`.
 
 ### 6. Receipt
 - **Definition**: An immutable, cryptographically sealed record of a completed run containing full execution facts, tool telemetry, token accounting, validation grounding, and outcome codes.
-- **Owning Type**: `RunReceiptV15` in `src/domains/dispatch/types.ts` (`RUN_RECEIPT_INTEGRITY_VERSION = 15`).
+- **Owning Type**: `RunReceipt` in `src/domains/dispatch/types.ts` (`RUN_RECEIPT_INTEGRITY_VERSION = 15`).
 
 ### 7. Envelope
-- **Definition**: A bounded container enforcing byte-length limits, truncation indicators, and SHA-256 provenance on dynamic payloads (e.g. parent briefings and tool outputs).
-- **Owning Type**: `ObservationEnvelope` in `src/tools/observation.ts`.
+- **Definition**: A bounded container enforcing byte-length limits and truncation indicators on a dynamic payload. Tool output carries shown and total byte counts plus a continuation fragment; a parent briefing carries byte count and SHA-256 content hash instead.
+- **Owning Type**: `Observation` in `src/tools/observation.ts` for tool output; `RunBriefingProvenance` in `src/domains/dispatch/types.ts` for briefings.
 
 ### 8. Phase
-- **Definition**: A designated execution interval within a run (such as `warmup`, `prompt`, `tool_execution`, or `finalize`) recorded in the trace store.
-- **Owning Type**: `PhaseRecord` in `src/domains/observability/trace-store.ts`.
+- **Definition**: A designated execution interval within a run. Every trace event and spend row is keyed to one `phaseId`, and the `phases` table is opened alongside `runs` for each operator turn.
+- **Owning Type**: `TraceEventInput.phaseId` and the `phases` table in `src/domains/observability/trace-store.ts`.
 
 ### 9. Gate
 - **Definition**: A validation or review barrier (such as a read-only reviewer verdict or a compete judge decision) determining whether candidate diffs are merged or revised.
-- **Owning Type**: `GateDecision` in `src/domains/dispatch/types.ts`.
+- **Owning Type**: `GateDecisionArtifact` in `src/domains/dispatch/gate-decisions.ts`.
 
 ### 10. Recipe
 - **Definition**: A versioned Markdown document declaring an agent's static persona, tool profile, execution capability class, cost ceilings, and result contracts.
@@ -60,7 +60,7 @@ This document defines core architectural concepts and terminology used throughou
 
 ### 14. Route
 - **Definition**: An exact execution tuple composed of `{ agent, target, model, node }` evaluated by the active route planner for capability fit and cost readiness.
-- **Owning Type**: `RouteTuple` in `src/domains/dispatch/types.ts`.
+- **Owning Type**: `RouteCandidate` in `src/domains/dispatch/route-decision.ts`.
 
 ### 15. Posture (Autonomy Level)
 - **Definition**: The active safety permission level governing tool mutation authority (`read-only`, `suggest`, `auto-edit`, `full-auto`).
@@ -71,5 +71,97 @@ This document defines core architectural concepts and terminology used throughou
 - **Owning Type**: `AgentCapabilityClass` in `src/domains/agents/spec.ts`.
 
 ### 17. Topology
-- **Definition**: The multi-agent structural orchestration pattern governing workflow execution (`singular`, `parallel`, `sequential`, `pipeline`, `detached`, `review`, `compete`, `auto`).
-- **Owning Type**: `DispatchTopology` in `src/domains/dispatch/types.ts`.
+- **Definition**: The multi-agent structural orchestration pattern governing workflow execution. Three unions spell it for three different jobs and their value sets differ: `parallel`, `sequential`, `pipeline`, `review`, `compete`, and `fleet` in a compiled plan; the same set with `detached` and without `fleet` for a capacity reservation; both plus `detached` and `fleet` at the tool surface. The operator-facing argument is spelled `mode`, and `singular` (the one-task call shape) and `auto` are values of that argument, not topologies.
+- **Owning Types**: `ExecutionPlanTopology` in `src/domains/dispatch/execution-plan.ts`, `ReservationTopology` in `src/domains/dispatch/reservation-store.ts`, `DispatchPlanTopology` in `src/tools/dispatch-plan.ts`.
+
+### 18. Worker Block
+- **Definition**: The attributed transcript segment rendering a worker's streaming execution. It includes a header with origin glyph and route, a rail for worker prose, coalesced tool names, and a one-line receipt footer.
+- **Owning Type**: `WorkerEntryState` in `src/interactive/worker-stream.ts`.
+
+### 19. Origin Glyphs (`◇`/`◆`)
+- **Definition**: Transcript and fleet board indicators that identify who requested a run. The glyph `◇` marks operator-typed runs, `◆` marks model-requested dispatches, and a dim dot marks internal Clio runs.
+- **Owning Type**: `WorkerRunOrigin` in `src/domains/session/entries.ts`.
+
+### 20. Share Note
+- **Definition**: A bounded operator note formatted as `[worker result] <agent> · run <id> · <outcome> · shared by the operator` that delivers a finished worker answer into the main agent context over the user-turn path.
+- **Owning Type**: `WorkerShareFacts` in `src/interactive/worker-share.ts`.
+
+### 21. Fold
+- **Definition**: Collapsing an expanded tool call or worker block down to a single-line summary row. Toggled for the newest foldable item with `Alt+O` or for all items with `Ctrl+Alt+O` / `Alt+Shift+O`.
+- **Owning Type**: `WorkerEntryRenderOptions` in `src/interactive/renderers/worker-entry.ts`.
+
+### 22. Interop
+- **Definition**: The domain governing discovery, compatibility roots, and delegation wiring for other coding agents installed on the local machine and in the repository.
+- **Owning Type**: `InteropContract` in `src/domains/interop/contract.ts`.
+
+### 23. Consent Record
+- **Definition**: A persistent state entry recording the operator's decision to accept or decline an interop agent proposal, written atomically under `interop.json`.
+- **Owning Type**: `InteropAgentRecord` in `src/domains/interop/types.ts`.
+
+### 24. Fingerprint
+- **Definition**: A SHA-256 digest of stable agent facts (including binary path, version, and launch recipe) that keys consent records so standing decisions stay valid until facts change.
+- **Owning Type**: `InteropAgentFacts` in `src/domains/interop/types.ts`.
+
+### 25. noWritePaths
+- **Definition**: A damage-control path policy class that permits reads while blocking writes and deletes under every registered foreign agent directory across all autonomy levels.
+- **Owning Type**: `PathPolicyKind` in `src/domains/safety/path-policy.ts`.
+
+### 26. Foreign Prompt Root
+- **Definition**: An external prompt directory owned by another coding agent (such as `.claude/commands` or `.codex/prompts`) from which Clio loads prompt templates.
+- **Owning Type**: `PromptTemplateRoot` in `src/domains/resources/prompts/loader.ts`.
+
+### 27. Compat Root
+- **Definition**: A compatibility directory for prompts or skills discovered from foreign agent installations, ranked below native Clio resource roots.
+- **Owning Type**: `ResourceSourceInfo` in `src/domains/resources/collision.ts`.
+
+### 28. Trust Gate
+- **Definition**: A security boundary requiring explicit operator opt-in via `skills.trustProjectCompatRoots` before prompt templates or skills from project-scope foreign roots can execute or expand.
+- **Owning Type**: `PromptTemplate` in `src/domains/resources/prompts/loader.ts`.
+
+### 29. Fleet
+- **Definition**: The set of addressable nodes Clio may place work on, `local` plus every configured SSH host, together with their capacity accounting. `fleet` is also the topology of a plan compiled from a fleet contract.
+- **Owning Types**: `FleetNodeSnapshot` in `src/domains/scheduling/cluster.ts` for capacity; `FleetContract` in `src/domains/agents/fleet-contract.ts` for the declared multi-step workflow.
+
+### 30. Dispatch
+- **Definition**: Sending one unit of work to a worker: the domain that resolves recipe, target, model, and node, admits the request against authority, spawns the worker, and seals the receipt. It is the `dispatch` tool, the `/run` slash command, and `src/domains/dispatch/`.
+- **Owning Type**: `DispatchRequest` in `src/domains/dispatch/contract.ts`.
+
+### 31. Run Ledger
+- **Definition**: The durable dispatch run list at `runs.json` in the state directory, retention-capped by `guardrails.maxDispatchRuns`. It is what the fleet board, `clio-coder fleet status`, and eval linking read.
+- **Owning Type**: `RunEnvelope` in `src/domains/dispatch/types.ts`, persisted by `src/domains/dispatch/state.ts`.
+
+### 32. Agent Ledger
+- **Definition**: The append-only progress log a worker writes for itself through the `ledger` tool, mirrored to the orchestrator over the control lane and persisted in `agent-ledgers.json`. Live subscribers are tracked in memory by the ledger hub.
+- **Owning Type**: `AgentLedgerEntry` in `src/worker/protocol.ts`, stored by `src/domains/dispatch/agent-ledger-store.ts`.
+
+### 33. Session Ledger
+- **Definition**: The JSONL record of one session's turns, written per session and referenced by eval artifacts as `sessionLedgers`. It is what `/resume`, `/fork`, and replay read.
+- **Owning Type**: `SessionEntry` in `src/domains/session/entries.ts`.
+
+### 34. Task Ledger
+- **Definition**: The persisted form of the session task board: goals, subgoals, and the run ids in flight when the snapshot was folded. One session entry kind, distinct from the board that renders it.
+- **Owning Type**: `TaskLedgerEntry` in `src/domains/session/entries.ts`.
+
+### 35. Context Ledger
+- **Definition**: The accounting of how the model's context window is spent, bucketed into system, tools, agents, skills, memory, and the rest, and the input to compaction decisions.
+- **Owning Type**: `ContextLedgerCategory` in `src/domains/session/context-ledger.ts`.
+
+### 36. Dispatch Board
+- **Definition**: The live fleet view: one row per in-flight or recently finished run, carrying origin glyph, route, status, and the steer and cancel affordances.
+- **Owning Type**: `DispatchBoardRow` in `src/interactive/dispatch-board.ts`.
+
+### 37. Task Board
+- **Definition**: The operator-facing goal and subgoal checklist for the session. It renders from a snapshot and persists as a task ledger entry, so the UI noun and the wire format are deliberately named differently.
+- **Owning Type**: `TaskBoardSnapshot` in `src/domains/session/task-board.ts`.
+
+### 38. Dashboard
+- **Definition**: The startup and footer panels summarizing targets, session, and spend. Not a board in the dispatch or task sense; it holds no rows a run or a goal maps to.
+- **Owning Type**: `WelcomeDashboardStats` in `src/interactive/welcome-dashboard.ts`.
+
+### 39. Handbook
+- **Definition**: `CLIO-CODER.md`, the human-owned, version-controlled project context file at the repository root: project name, one-line description, conventions, hard invariants, and optional sections, closed by a fingerprint comment.
+- **Owning Type**: `ParsedClioMd` in `src/domains/context/clio-md.ts`.
+
+### 40. Delegate
+- **Definition**: Another coding agent Clio drives over ACP stdio as if it were a worker, configured under `delegation.agents` and invoked with `/delegate`. A delegate is a foreign harness, not a model target.
+- **Owning Type**: `DelegationAgentConfig` in `src/core/defaults.ts`.