@iowarp/clio-coder 0.4.2 → 0.4.4

package/docs/architecture/context-engine.md

@@ -274,6 +274,10 @@ reads only the changed indexable files for path-based updates, replaces their fi
 deleted records, and rebuilds edges from the merged import set. Non-indexable
 paths are no-ops.
 
+### Architecture seed
+
+`clio-coder context map` derives an archify architecture specification from the structural index with no model call and writes it to `.clio-coder/artifacts/maps/<repo>.architecture.json` (or `--out <path>`). The seed guarantees that every component is a real directory area of the index under the wiki plan's area-depth rule, capped at twelve by file count plus at most three external packages; that every connection is an import edge the index recorded, collapsed area to area and labeled with its count; and that `meta.repository` appears only when the origin remote is a GitHub URL and `HEAD` is a full revision. Only in that case do components carry `sources`, each naming an indexed file and its first declared symbol's line, because archify accepts source citations only against a pinned revision. Component IDs remain unique across internal and external names, connection IDs are unique, and matching directory/package names retain separate import destinations and counts. Placement is layered by import direction with explicit routes for archify's standard profile; composition warnings may still require operator edits. It refuses, naming `clio-coder context index`, when no index exists. Clio never renders the seed: the archify skill validates and delivers it. When the seed carries pinned repository evidence, pass `--repo-root .` to re-verify every cited path against the working tree; omit that option for an unpinned seed.
+
 ### Markdown Wiki & `code_nav` Resolution
 
 The wiki lives under `.clio-coder/wiki/` as a nested tree and is written by the

package/docs/architecture/dispatch-typed-intent.md

@@ -250,7 +250,7 @@ producer.
 | `intent_absent_legacy_inference` | classifier-only warn | No typed intent; scope came from legacy inference. Production admission does not emit it. |
 | `intent_partial_verification_absent` | classifier-only warn | Declares tree-changing work with no verification requirement. Production admission does not emit it. |
 | `typed_scope_replaced_inferred_paths` | warn | Typed intent was declared, so prose-only paths took no part in scope. |
-| `legacy_scope_inferred` | retained compatibility id | Accepted by the event projection for older producers; no current source emits it. |
+| `legacy_scope_inferred` | warn | Emitted by `path-scope.ts` when prose inference resolves a leading `../` run against the dispatch root. The detail lists each token as `<raw token> -> <path or dropped>`. |
 | `legacy_scope_empty` | retained compatibility id | Accepted by the event projection for older producers; no current source emits it. |
 | `intent_version_unsupported` | refuse | `intent.version` names a version this build does not speak. |
 | `intent_malformed` | refuse | Not a normalized intent for a reason other than its version. |

package/docs/architecture/evidence-and-memory.md

@@ -86,7 +86,7 @@ When a run was chained (pipeline), composed with a persona override, or escalate
 
 ### Task and decision provenance
 
-Session evidence retains the two operator-facing bookkeeping ledgers instead of flattening them into prose. A `taskLedger` projection names the stable board id, goal counts, active runs, required evidence, and bounded task rows with status, origin, `userTaskId`, reason, and evidence. This keeps an operator task traceable from the project inbox correlation through agent pickup and completion. A `decisionLedger` projection names the active-path anchor, interview identity and status, timing, round count, summary, and every settled or superseded decision. Operator revisions are explicit through `revisedAt`, `revisionSource=operator`, and the recorded correction text. Both kinds remain session facts in `trace.raw.jsonl`, `trace.cleaned.jsonl`, and the readable transcript; evidence does not reinterpret them as validation results.
+Session evidence retains the two operator-facing bookkeeping ledgers instead of flattening them into prose. A `taskLedger` projection names the stable board id, goal counts, active runs, required evidence, and bounded task rows with status, origin, `userTaskId`, reason, and evidence. This keeps an operator task traceable from the project inbox correlation through agent pickup and completion. A `decisionLedger` projection names the active-path anchor, interview identity and status, timing, round count, summary, and every settled or superseded decision. Operator revisions are explicit through `revisedAt`, `revisionSource=operator`, and the recorded correction text. Both kinds remain session facts in `trace.raw.jsonl`, `trace.cleaned.jsonl`, and the readable transcript; evidence does not reinterpret them as validation results. Authenticated receipt `decisionRefs` link runs to recorded arguments on the session's active path, with resolved records in `overview.json` and resolved or missing-reference findings in both readable evidence documents. Wiki page writers receive up to twelve active decisions matching their source paths or symbols and cite those refs in the body and optional `decisions` frontmatter instead of inferring rationale.
 
 ---
 

package/docs/architecture/middleware-and-components.md

@@ -127,7 +127,7 @@ These ship in every interactive session. Each is one bounded behavior with a vis
 | --- | --- | --- |
 | `nudge.stalled-turn` | `turn_end` | The one declarative rule. A turn that called no tools and ended on an announced action ("Next I will inspect `src/cli/index.ts`") is continued once with a reminder to perform it or say plainly that it is finished. Questions, "let me know", conditional offers ("if you want me to"), and completion statements are not announcements. |
 | `observer.skills-reminder` | `turn_start`, `turn_end` | Once per session, on the first substantive turn, when installed or installable skills exist, injects one line teaching the suggestion protocol: list with `context(scope="skills")`, open the reply with `Suggested skill: /skill <name>` when one matches, then continue the task in the same turn. Only the operator loads a skill. At `turn_end`, a reply that made the suggestion and stopped with only listing calls behind it is continued once (#184): the suggestion is not the task. Greetings do not spend the session's one reminder; a resumed or forked session never gets one. |
-| `observer.marketplace-offer` | `turn_start`, `after_tool` | On coordinator sessions, locally matches a substantive request against undeclined, uninstalled skills in Clio's marketplace and offers each matching skill at most once per session. Ordinary autonomy asks the operator through a tag-bound `ask_user` choice; `Not now` lasts for the session and `Never offer this skill` persists for that skill version. `full-auto` installs the match at project scope without the question. Both consented and autonomous installs pass the Clio-marketplace source gate, and installation never activates the skill; activation remains operator-gated. |
+| `observer.marketplace-offer` | `turn_start`, `after_tool` | On coordinator sessions, locally matches a substantive request against undeclined, uninstalled skills in Clio's marketplace and offers each matching skill at most once per session. Every autonomy level, including `full-auto`, asks the operator through a tag-bound `ask_user` choice; `Not now` lasts for the session and `Never offer this skill` persists for that skill version. Only an explicit answer to the bound offer can install a skill. Consented installs pass the Clio-marketplace source gate; installation does not itself load the skill. |
 | `observer.task-board-reminder` | `turn_start` | Once per session, when the operator's text literally enumerates three or more steps (`1)`, `2.`, `step 3:`, or three bulleted lines), injects one line asking for `tasks action="plan"` before the first edit. Prose that merely mentions numbers never counts. |
 | `nudge.open-tasks` | `turn_end` | A settled work turn (one that called tools) that ends while the session task board still has pending or active tasks is continued once with the open list. Pure conversation turns, aborted or errored turns, and boards where every remaining task is blocked do not trigger. |
 | `nudge.detached-dispatch` | `turn_end` | A settled turn that ends while a detached dispatch batch has every run terminal and uncollected is continued once, naming the ready batches; `monitor mode="collect"` clears it, including across resume. Batches with runs still in flight, and surfaces without `monitor`, do not trigger. |

package/docs/architecture/model-catalog.md

@@ -20,7 +20,11 @@ Configured `wireModels` and a target `defaultModel` remain selectable before a
 live catalog is known; Clio labels those rows as `configured` or `default`.
 Once a target returns a live catalog, that catalog is authoritative and models
 the runtime no longer reports stop resolving. Live probe discoveries are labeled
-`live` and carry load-state metadata when the runtime exposes it. This preserves
+`live` and carry load-state metadata when the runtime exposes it. Runtime model
+labels are separate metadata: the stable slug remains the wire identity while
+`clio-coder models` and target status may show the human label beside it. Slugs,
+labels, source, and freshness round-trip through the generic target model
+snapshot; a cached label never replaces a live slug. This preserves
 operator-curated defaults while still letting runtime discovery take over after
 newly installed local models or newly entitled cloud models appear. Catalog YAML
 entries are loaded when the provider domain is built, so bundled or overlay
@@ -32,8 +36,9 @@ Live provider probes are the preferred source for loaded context and per-model m
 `probeCapabilitiesForModel` is the one exact-id selector. When a router serves several models, capability resolution queries `probeCapabilitiesForModel` to ensure probe data is extracted only from the `/v1/models` row keyed to its own exact wire model ID.
 
 Transient probe failures preserve the last-good catalog, load states,
-capabilities, and notes for the same target identity, but the target health is
-reported as down or unavailable with the probe error as the reason. Worker
+labels, capabilities, and notes for the same target identity, but those model
+rows are marked cached/stale and target health is reported as down or unavailable
+with the probe error as the reason. Worker
 dispatch canonicalizes requested model ids against the live catalog when one is
 available, so a short alias can resolve to the canonical live id before the
 worker spec and receipt are written.
@@ -185,14 +190,19 @@ override the applicable setting.
 - **Ollama Native (`ollama-native`):** Ollama utilizes the native `thinking` field in the request and response payloads. The engine handles Ollama-specific effort levels and streams reasoning increments cleanly through the native thinking channel.
 - **LM Studio (`lmstudio`):** Chat uses the OpenAI-compatible `/v1/chat/completions` surface, including its `reasoning` stream field. Clio controls thinking only with `reasoning_effort` and never sends `chat_template_kwargs` to LM Studio. See <https://lmstudio.ai/docs/developer/openai-compat/chat-completions>.
 - **LiteLLM (`litellm`):** This is a gateway runtime, not an `openai-compat`
-  alias. Discovery checks `/health/liveliness`, reads aliases and capability
+  alias. Discovery checks `/health/liveliness`, reads routed names and capability
   metadata from `/v1/model/info`, and records the physical deployment reported
-  by `x-litellm-*` response headers. Defaults stay conservative when metadata is
-  absent: tools, vision, and reasoning are not inferred. The runtime advertises
-  standard `json_schema` structured output and treats schema-plus-tools as a
-  conflict because the gateway alias does not identify one stable upstream.
-  Residency is observe-only because LiteLLM owns loading and eviction behind the
-  alias.
+  by `x-litellm-*` response headers. Deterministic gateways should publish one
+  `node/model` name per deployment; genuine multi-deployment aliases expose only
+  the capabilities guaranteed by every route and use the smallest unanimously
+  published context/output limits. Defaults stay conservative when metadata is
+  absent: tools, vision, reasoning, and structured output are not inferred.
+  Explicitly advertised schema support uses standard `json_schema` on the wire.
+  Gateway requests use no hidden OpenAI SDK retries, and LiteLLM failures bypass
+  Clio's interactive transient retry ladder so the operator can select another
+  route. Stable session ids, request tags, optional request-level timeouts, and
+  observed server retry/fallback headers remain supported. Residency is
+  observe-only because LiteLLM owns loading and eviction behind the route.
 - **OpenAI Completions (`openai-completions`):** The OpenAI-compatible completions provider preserves reasoning blocks within assistant messages. It replays thinking blocks via the `reasoning_content` parameter in the message history, ensuring that the model maintains its chain-of-thought across conversational turns without stripping the data.
 - **Anthropic OAuth / API (`anthropic-max`):** Uses the `anthropic-extended` thinking format. The engine supports Anthropic's native extended thinking block protocol, streaming thinking increments and outputting them wrapped appropriately or natively depending on target capabilities.
 - **Reasoning-Never Models (`thinking.mechanism: none`):** When a model is configured or cataloged with `thinking.mechanism: none`, it is treated as a reasoning-never model. For these models, Clio must not send any thinking fields or parameters in requests, must not replay thinking blocks, must not surface thinking events to the TUI, and must not preserve or log reasoning token usage in metrics.
@@ -206,6 +216,7 @@ Subscription models are registered and managed as standard HTTP/cloud targets:
 - **`openai-codex` (ChatGPT Plus/Pro OAuth):** Maps to catalog-backed Codex model ids surfaced by `clio-coder configure --list` and `clio-coder models` via a browser-minted subscription OAuth token, supporting complete chat, vision, and tool-use capabilities.
 - **`anthropic-max` (Claude Pro/Max OAuth):** Powers chat and workers using catalog-backed Claude model ids surfaced by `clio-coder configure --list` and `clio-coder models`. It relies on the engine's Anthropic OAuth provider. During auth initialization, it alerts the operator to usage-terms caveat via:
   `Connects with your Claude Pro/Max subscription via OAuth (the same path Claude Code uses). Using subscription credentials outside Anthropic's first-party apps may not align with their terms of service; enable at your own discretion.`
+- **`antigravity-code` (experimental local delegation):** Is not an HTTP model provider and is never orchestrator-eligible. It invokes the operator's own authenticated official `agy` executable only for dispatch work, consumes structured `stream-json` results and token accounting, and discovers model slugs and labels from the non-generating JSON `models` command. Descriptor models are cold-start hints only; a successful target probe is authoritative for that account, including the disappearance of a former model.
 
 ---
 

package/docs/architecture/observability.md

@@ -151,7 +151,18 @@ A row has the following schema:
 
 `repoIdentity` is the same cwd hash the session ledger is filed under, which is what lets `usage report --repo <path>` select these rows with the hash it already computes for the ledgers.
 
-`label` is one of `side-question`, `handoff`, `prewarm`, or `background-memory`. The last two joined for the same reason as the first two: a prompt pre-warm and a proactive-memory step are provider calls the operator did not ask for and would otherwise never see, and neither appends anything to the session JSONL. A row may also carry `timing { durationMs }` and a `promptCache` block built from the backend's own prefill facts when the server reported them; a backend that reports no timings simply omits the block, as LM Studio's OpenAI-compatible port does.
+`label` is one of `side-question`, `handoff`, `prewarm`, `background-memory`, or `failed-compaction`. Prompt pre-warm and proactive-memory calls are recorded here because neither appends an assistant call to the session JSONL; failed-compaction records preserve calls from an attempt that produced no checkpoint. A row may also carry `timing { durationMs }` and a `promptCache` block built from the backend's own prefill facts when the server reported them; a backend that reports no timings simply omits the block, as LM Studio's OpenAI-compatible port does.
+
+
+Failed compaction attempts record one `failed-compaction` row per invoked summary stream when no checkpoint is produced. `callOutcome` distinguishes a completed first stream (`success`) from an `error` or `aborted` stream; a completed call can belong to an unsuccessful split-compaction attempt. The rows capture the originating session/repository and selected target/model before asynchronous work can switch context. Successful compactions keep usage solely on their checkpoint, and their live accounting uses the same selected route. Unset model controls retain the active chat route.
+
+New failed-compaction rows preserve missing usage fields as `null`. Positive partial-response facts survive an error that resets missing fields to zero. Ambiguous failed zeros remain unknown, reasoning is separate from ordinary output/total tokens, and an absent total is not inferred. Positive adapter prices are labeled `estimated`; zero or missing pricing is `unknown`, not a free-call claim. Existing numeric rows and historical checkpoints remain readable without rewriting them.
+
+`clio-coder usage report` includes these calls in its known subtotals, labels the failed-attempt count, and exposes `failedCompaction.knownUsage`, `erroredKnownUsage`, and per-field `unobservedUsageCalls` in the token and model JSON facts. A field with missing coverage and no known positive amount is `null`, including cost-only or wholly unobserved failures. Text output identifies incomplete subtotals. The live `/cost` view records positive known contributions under a failed-compaction label; its numeric token counters remain known subtotals. These figures do not certify provider billing or complete spending. The existing session-cost ceiling checks the numeric known sum, so unreported cost does not become an enforced complete-cost bound.
+
+Eval tracked/stdout folds do not include the failed-compaction sidecar, and live `/cost` reseeding reads the session ledger rather than this store. A later usage report can therefore include retained failed-compaction amounts that those views omit. This consumer reconciliation is deferred to v0.4.5 or later; the retained known amounts must not be presented as complete cross-surface billing.
+
+A failed or empty summary produces no checkpoint. Required failed-compaction usage appends are flushed and a write failure remains an explicit operation error; no model call is repeated to repair accounting. If checkpoint append throws, Clio checks that checkpoint's exact identity in the original ledger before choosing the sidecar: an already written checkpoint is not counted again, and proven absence permits the sidecar. An unreadable or malformed ledger that leaves persistence ambiguous fails visibly without a speculative duplicate write. This is the existing bounded usage store, not a new recovery store; its 1000-row retention and unknown telemetry limits still apply.
 
 ---
 
@@ -161,7 +172,7 @@ Clio resolves directories under platform-specific XDG defaults (on Linux, these
 
 | Category | Description | Backing Path |
 | --- | --- | --- |
-| **Accountability** | Rolling first-pass-success rate and failure-cause histogram. | `<stateDir>/evidence-index.json` |
+| **Accountability** | Rolling first-pass-success rate, unverified successes, ungrounded claims, and failure-cause histogram. | `<stateDir>/evidence-index.json` |
 | **Evidence bundles** | Deterministic run or session overviews, findings, totals, and linked files. | `<dataDir>/evidence/<evidenceId>/` |
 | **Receipts** | Durable run receipts verified by SHA-256 integrity digests. | `<stateDir>/receipts/<runId>.json` |
 | **Dispatch outputs** | Logs and ledger records detailing worker execution. | `<stateDir>/runs.json` and `<stateDir>/receipts/<runId>.json` |
@@ -190,6 +201,12 @@ A run is marked as a first-pass success when:
 The TUI displays this rate as:
 `first-pass success: <succeeded-attempts>/<total-attempts> (<pct>%)`
 
+### Unverified Successes and Ungrounded Claims
+Two counters sit beside the rate in `/view`, `clio-coder usage`, and the observability contract. An unverified success is a run whose terminal outcome succeeded while its bundle carries the `no-validation` or `proxy-validation` tag or a warning-level `completion-evidence` finding. Ungrounded claims are the sum, over integrity-verified receipts, of validation claims with no matching command (`validationGrounding.claimed` minus `grounded`). Both fold only the fields an index row holds: a historical row without `succeeded`, `completionEvidenceWarning`, or `ungroundedClaims` contributes zero.
+
+The TUI displays them as:
+`unverified successes: <count>` and `ungrounded claims: <count>`
+
 ### Failure-Cause Histogram
 The TUI lists the top failure causes sorted by frequency (descending), then by tag name (ascending). The histogram filters out provenance and quality tags (such as `audit-linked`, `session-linked`, and `no-validation`) and displays only real failure causes:
 - `timeout`

package/docs/architecture/prompt-envelope-and-tools.md

@@ -81,9 +81,9 @@ The compiler runs after target capability and tool-profile admission. Its canoni
 
 Project context, memory, bounded dispatch briefing, pipeline input, the assigned task, and the per-run safety-posture reminder remain dynamic user messages. A briefing is a separately delimited message labeled as untrusted task context/data; it is never concatenated into the task or stable system prompt. Dynamic ordering is project, safety, memory, briefing, then pipeline input, with pipeline input last. These messages do not affect the stable composition hash. Persona, effective autonomy, target tool capability, or final toolkit changes do affect it.
 
-## Seven planes, twenty-one tools
+## Seven planes, twenty-four tools
 
-The canonical builtin catalog contains 21 tools organized in seven planes. A
+The canonical builtin catalog contains 24 tools organized in seven planes. A
 particular session or worker receives the subset whose dependencies and policy
 allow it to register. Each plane is one policy unit: its tools share an action
 class, a size posture, a details schema, and a concurrency rule.
@@ -95,6 +95,7 @@ engine assumes.
 | Plane | Tools | Action class | Concurrency |
 | --- | --- | --- | --- |
 | OBSERVE | `read`, `grep`, `find`, `ls`, `code_nav`, `context`, `credential_present` | read | parallel |
+| OBSERVE | `evidence` | read | sequential |
 | MUTATE | `write`, `edit` | write | sequential |
 | EXECUTE | `bash`, `verify` | execute | sequential |
 | EXECUTE | `git` | read | parallel |
@@ -103,6 +104,8 @@ engine assumes.
 | ORCHESTRATE | `tasks` | read | sequential |
 | ORCHESTRATE | `ledger` | read | sequential |
 | ORCHESTRATE | `panes` | read | sequential |
+| ORCHESTRATE | `limitation` | read | parallel |
+| ORCHESTRATE | `decide` | read | sequential |
 | RETRIEVE | `web_fetch` | read | parallel |
 | INTERACT | `ask_user` | read | sequential |
 | ARTIFACT | `artifact` | write | sequential |
@@ -120,7 +123,14 @@ and a read answers from a local mirror, so it touches no workspace and stays
 read class, and reviewers and judges are pinned to read-only autonomy where a
 write class would block the peer review the board exists for. `panes` controls
 only Clio-owned terminal panes through the live mux; it stays read class but is
-sequential so two operations cannot race the same pane registry.
+sequential so two operations cannot race the same pane registry. `evidence` sits in the OBSERVE plane
+because it only reads canonical evidence, trust status, gate decisions, and
+findings, but it is sequential because `run` mode may materialize a bundle
+under Clio's data directory. `limitation` and `decide` sit in the ORCHESTRATE
+plane as read class: each appends one typed receipt or decision-board entry
+to the session ledger and touches nothing else. `limitation` is parallel
+because the call is pure; `decide` is sequential so two decisions in one batch
+cannot race the supersede lookup.
 
 Registration is conditional on wiring: `context` gains its workspace scope only
 when a session contract is bound, `dispatch`/`monitor`/`steer` register only
@@ -154,7 +164,7 @@ Several tools absorb what used to be separate tools:
 
 ## The observation envelope
 
-The six content-returning OBSERVE tools (`read`, `grep`, `find`, `ls`, `code_nav`, `context`) close every result through one shared envelope in `src/tools/observation.ts`. `credential_present` sits in the OBSERVE plane but returns a typed boolean and carries no envelope cap. The envelope owns four guarantees.
+The six content-returning OBSERVE tools (`read`, `grep`, `find`, `ls`, `code_nav`, `context`) close every result through one shared envelope in `src/tools/observation.ts`. `credential_present` sits in the OBSERVE plane but returns a typed boolean and carries no envelope cap, and `evidence` returns bounded JSON under its own 16KB summary policy. The envelope owns four guarantees.
 
 **One notice line, one format.** A truncated text result appends exactly one notice:
 
@@ -190,7 +200,7 @@ Tool descriptions are tiered by how much a wrong call costs. The hot tools the m
 
 Clio uses two context-protection mechanisms.
 
-1. Tool results are capped at the source and again at the registry boundary. OBSERVE tools use the envelope caps above. Exact mutation tools (`write`, `edit`, `artifact`) use 8KB; `steer` and `credential_present` use 4KB; `ledger` uses 16KB; `panes` uses 8KB; and `ask_user` has a 20KB policy. Summary-kind tools (`bash`, `git`, `verify`, `dispatch`, `monitor`) use 16KB at the registry boundary. Bash also exposes the canonical per-call `output_policy`: omitted/`bounded` keeps its diagnostic tail, `summary` selects stable redacted head/error/tail evidence, `metadata-only` keeps facts and retrieval without stdout/stderr context, and `full` succeeds only inside the same hard result budget or records a typed downgrade. This model-context choice does not change the folded tail-biased operator presentation. `web_fetch` is bounded at 16KB after shaping and may read more before it: its `max_bytes` argument defaults to 600KB and is hard-capped at 5MB. Tools without an explicit result-size policy use an approximately 18KB generic backstop. Over-cap generic results are shown briefly and, when possible, saved under `<stateDir>/scratch/<sessionId>/<sha256 of the captured text>.txt` with an `offloadPath` detail and a 10MB scratch-file cap.
+1. Tool results are capped at the source and again at the registry boundary. OBSERVE tools use the envelope caps above. Exact mutation tools (`write`, `edit`, `artifact`) use 8KB; `steer` and `credential_present` use 4KB; `ledger` uses 16KB; `panes` uses 8KB; `limitation` and `decide` use 4KB; and `ask_user` has a 20KB policy. Summary-kind tools (`bash`, `git`, `verify`, `dispatch`, `monitor`, `evidence`) use 16KB at the registry boundary. Bash also exposes the canonical per-call `output_policy`: omitted/`bounded` keeps its diagnostic tail, `summary` selects stable redacted head/error/tail evidence, `metadata-only` keeps facts and retrieval without stdout/stderr context, and `full` succeeds only inside the same hard result budget or records a typed downgrade. This model-context choice does not change the folded tail-biased operator presentation. `web_fetch` is bounded at 16KB after shaping and may read more before it: its `max_bytes` argument defaults to 600KB and is hard-capped at 5MB. Tools without an explicit result-size policy use an approximately 18KB generic backstop. Over-cap generic results are shown briefly and, when possible, saved under `<stateDir>/scratch/<sessionId>/<sha256 of the captured text>.txt` with an `offloadPath` detail and a 10MB scratch-file cap.
 2. Auto-compaction uses one pressure threshold. The default threshold is 0.8. When pressure crosses the threshold, Clio first applies a non-destructive working-set eviction and records the evicted items in the session ledger. If pressure remains above the threshold, it runs the LLM summary compaction path and replays from the compacted session view. The older destructive observation/thinking mask is available only as a compatibility escape hatch when `CLIO_CODER_LEGACY_MASK=1`.
 
 Manual `/context compact`, `CLIO_CODER_FORCE_COMPACT=1`, and overflow recovery force the LLM summary path directly.
@@ -201,6 +211,8 @@ Compaction rewrites history, so the next turn on a local single-slot backend is
 
 Timing and cache behavior are persisted per API call, so a finished session can be inspected from its stored artifacts alone. Each assistant entry in the session ledger (`current.jsonl`, under the directory reported by `clio-coder paths`) carries `timing { ttftMs, apiMs }` and `promptCache { input, cacheRead, cacheWrite, backendVerdict }`, and the run's first persisted call also carries `expectedColdReasons`. Cache verdicts are `hot`, `partial`, `cold`, or `small`.
 
+Native session timing uses a monotonic clock from each stream invocation, before the provider's response-header wait, to its first observed output (`ttftMs`) and completion (`apiMs`). A tool-loop continuation starts a new clock; no output leaves TTFT null, and a genuine rounded zero remains zero. Historical values are not rewritten and may omit the pre-header wait. Eval prefers these durable native call records. Its stdout-only fallback starts at the provider's `message_start` event, which can arrive after headers, so fallback spans are not complete request latency and must not be compared as equivalent measurements.
+
 For aggregate cost and token facts across sessions, use `clio-coder usage report --days <n>`. Inside the TUI, `/cost` shows session totals and `/context` opens the context-window ledger overlay.
 
 ## Self-documentation retrieval

package/docs/architecture/provider-adapter-cookbook.md

@@ -170,6 +170,69 @@ inherited from the pinned Pi dependency; Clio no longer carries a separate
 contract test that reconstructs Pi's whole adaptive or budget payload.
 
 
+
+### 3.3 Thinking controls through LiteLLM
+
+Dedicated memory and compaction roles read a cold LiteLLM target's metadata
+before synthesizing the completion model. The read disables reasoning probes;
+it does not run an extra inference request. Each selected target owns its probe
+state, even when two targets share a gateway URL. A successful unknown or mixed
+runtime declaration remains unknown and is not repeatedly probed for a preferred
+answer. Memory includes discovery and auth in its existing generation/deadline
+boundary; cancellation cannot launch a later completion or mark the endpoint
+down. Fresh discovered output limits also bound its request. After metadata and auth,
+memory rechecks actual endpoint occupancy immediately before registering its
+inference hold. Late saturation stays a dropped `endpoint_busy` boundary with
+no usage or cache-disturbance claim. Compaction checks
+the originating session/branch after preparation and uses the existing simple
+stream API with thinking off, rather than inferring an active level from the
+model's reasoning capability.
+
+Native worker admission also prepares the selected cold LiteLLM target before
+freezing its capabilities and thinking controls into the worker specification
+and receipt. Tool cancellation and the original admission deadline bound that
+wait, including a delayed metadata response body. Failed preparation releases
+the existing plan reservation and cannot launch a late worker or publish
+cancelled health data. The approved target, model, endpoint and node remain
+binding; changed route identity requires fresh admission. Metadata discovery
+does not infer capacity or residency from another route sharing the gateway,
+and does not bypass the existing capacity or approved tool-surface checks.
+
+
+A gateway alias is not an upstream runtime identity. Clio consumes the optional
+`model_info.runtime` deployment declaration from LiteLLM's `/v1/model/info` only
+when every deployment of the alias names the same recognized control runtime:
+`lm-studio` or `llama.cpp`. Missing, unknown, or mixed declarations produce no
+runtime-specific control hint. The probe-only `thinkingControlRuntime` capability
+travels through the existing main, background and worker model capability path;
+`runtimeId`, authentication, the gateway URL and residency ownership stay LiteLLM.
+Clio never infers this declaration from ports or model names and never loads or
+unloads the gateway's upstream models.
+
+The family still determines whether thinking is switchable and which active
+levels exist. A declared LM Studio route receives `reasoning_effort: "none"` for
+an effective off choice; a llama.cpp route uses its template switch. LiteLLM's
+generic OpenAI adapter may silently filter a resolved effort for local model
+names. Clio therefore adds `allowed_openai_params: ["reasoning_effort"]` only when
+it sends that model/runtime's resolved `reasoning_effort`; unrelated parameters
+and unknown off mechanisms are not newly allowed. This is a request control,
+not a change to gateway configuration. See [LiteLLM parameter forwarding](https://docs.litellm.ai/docs/completion/drop_params).
+
+[Qwen3.8-27B's pinned template](https://huggingface.co/Qwen/Qwen3.8-27B/blob/1d4bf0f2ff6012fd82039f2fa52739d0dd7c60c0/chat_template.jinja)
+accepts active `low`, `medium`, and `xhigh`, with thinking enabled and `xhigh`
+when the template receives no override. Clio shows off/low/medium/xhigh and maps
+released high/max selections to xhigh. That vendor default does not overwrite
+Clio's explicit chat preference or saved low setting. Disabling thinking does
+not remove historical reasoning or discard reasoning a server actually returns.
+
+Controlled gateway filtering tests cover discovery, capability transfer, actual
+HTTP payloads, off/on switching, and built CLI persistence. Live same-route
+probes on the selected LiteLLM deployment returned reasoning with the flag or
+none alone, zero reasoning on two calls with none plus the explicit allowance,
+and positive reasoning for an allowed low control. This verifies the measured
+route and request contract; unknown or heterogeneous gateway aliases need their
+own declared capabilities and acceptance.
+
 ---
 
 ## 4. Configuring Reasoning & Thinking Formats

package/docs/architecture/safety-model.md

@@ -97,7 +97,7 @@ Escalation can never hang a run. Every escalated ask resolves by an operator dec
 ## Operating Posture and Visible Tools
 
 Clio operates under a single operating posture. The canonical catalog contains
-21 built-in tools organized in seven planes; each plane is one policy unit for
+24 built-in tools organized in seven planes; each plane is one policy unit for
 action class, size posture, and concurrency, asserted at bootstrap by
 `src/tools/policy.ts` so the classifier and registered specs cannot drift apart
 silently. Dependency wiring, target capability, worker profile, and recipe
@@ -105,17 +105,17 @@ policy determine which subset is visible in a particular context.
 
 | Plane | Tools | Action class |
 | --- | --- | --- |
-| OBSERVE | `read`, `grep`, `find`, `ls`, `code_nav`, `context`, `credential_present` | `read` |
+| OBSERVE | `evidence`, `read`, `grep`, `find`, `ls`, `code_nav`, `context`, `credential_present` | `read` |
 | MUTATE | `write`, `edit` | `write` |
 | EXECUTE | `bash`, `verify` | `execute` |
 | EXECUTE | `git` | `read` |
 | ORCHESTRATE | `dispatch`, `steer` | `dispatch` |
-| ORCHESTRATE | `monitor`, `tasks`, `ledger`, `panes` | `read` |
+| ORCHESTRATE | `monitor`, `tasks`, `ledger`, `panes`, `limitation`, `decide` | `read` |
 | RETRIEVE | `web_fetch` | `read` |
 | INTERACT | `ask_user` | `read` |
 | ARTIFACT | `artifact` | `write` |
 
-`git` is read-only inspection on the safe-exec spine, so it carries the read class despite living in the EXECUTE plane. `monitor` does not mutate a run or the workspace. The model-facing `tasks` tool is an intentional bookkeeping exception to the everyday meaning of "read": board mutations append full `taskLedger` snapshots to Clio's session ledger, and any action may reconcile the project-local `.clio-coder/user-tasks.json` inbox while `pick` and linked `done` update its durable correlation. Those Clio-owned ledger and inbox mutations intentionally remain audited with `actionClass: "read"`, so task planning and pickup stay available at every autonomy level without an approval card. `ledger` reads a worker-local mirror and posts through the dispatch control lane; it registers only for a worker with an agent-ledger port. `panes` controls Clio-owned terminal panes and registers only when a pane host and live mux are available. Both are read class and sequential because their coordination state must not interleave. This classification grants no source-workspace, command-execution, or run-mutation authority; those operations still require their own tools and action classes. `gateway` is a design-reserved name only (see `src/core/tool-names.ts`), not a registered tool.
+`git` is read-only inspection on the safe-exec spine, so it carries the read class despite living in the EXECUTE plane. `monitor` does not mutate a run or the workspace. The model-facing `tasks` tool is an intentional bookkeeping exception to the everyday meaning of "read": board mutations append full `taskLedger` snapshots to Clio's session ledger, and any action may reconcile the project-local `.clio-coder/user-tasks.json` inbox while `pick` and linked `done` update its durable correlation. Those Clio-owned ledger and inbox mutations intentionally remain audited with `actionClass: "read"`, so task planning and pickup stay available at every autonomy level without an approval card. `ledger` reads a worker-local mirror and posts through the dispatch control lane; it registers only for a worker with an agent-ledger port. `panes` controls Clio-owned terminal panes and registers only when a pane host and live mux are available. Both are read class and sequential because their coordination state must not interleave. `evidence` reads canonical evidence bundles, trust status, gate decisions, and findings; it touches no workspace, and it is sequential because `run` mode may materialize a bundle under Clio's data directory. `limitation` records a typed receipt of what a turn could not verify and why; it touches no filesystem and runs no shell, so it is read class and parallel. `decide` appends the model's own design decision, with its rejected alternatives and rationale, to the session decision board; dispatch seals every active decision's ref onto the run envelope and receipt, and commit seams write them as `Clio-Decision:` trailers. It is read class and sequential. This classification grants no source-workspace, command-execution, or run-mutation authority; those operations still require their own tools and action classes. `gateway` is a design-reserved name only (see `src/core/tool-names.ts`), not a registered tool.
 
 Target capability, dispatch tool profiles, and recipe constraints can further narrow the tools available to a run. That narrowing is convenience and budget control; safety still lives in code gates.
 
@@ -129,11 +129,12 @@ The `/view` workspace category treats a recorded successful write as a durable f
 
 A `SKILL.md` may declare `allowed-tools` and `disallowed-tools`. The declaration is enforced at tool admission, between the safety net and the autonomy mapping, on every surface that activates skills (interactive turns, headless `clio-coder run` turns, and dispatched workers whose recipes declare skills).
 
-- **Window.** Narrowing arms when `context` (scope="skills") successfully loads the skill and lasts for the lifetime of the pending-skill policy: to the end of the current turn for the main agent, and to the end of the run for a worker. A later turn is unrestricted until a skill is requested and loaded again.
+- **Window.** Narrowing arms when `context` (scope="skills") successfully loads the skill and lasts for the lifetime of the pending-skill policy. Interactively that is the session: the surface stays armed across the operator's later turns, because a multi-turn skill workflow is still the same workflow on the operator's next message. It ends when a different skill replaces it (the new skill's declaration replaces the old one, it is never merged into it), when the operator clears it with `/skill off`, or when the session ends. A worker keeps the run-scoped lifetime. Activation and clearing each emit one transcript line naming the armed skills.
+- **Who activates.** At `read-only` and `suggest` only the operator activates a skill: a model `context(scope="skills", name=...)` call is refused and the model's move is the suggestion anchor. At `auto-edit` and `full-auto` the model activates an installed skill itself, under the same per-run policy `/skill` produces, because the operator has already chosen to let it act and narrowing can only subtract from the surface. The autonomy level is the whole opt-in; there is no frontmatter flag. A skill that is not installed stays operator-gated at every level, and the transcript line names who activated. This holds on every surface that resolves effective autonomy through the chat loop, which is all three: interactive turns, headless `clio-coder run --autonomy ...`, and ACP prompts (including a per-session level an ACP client sets). Dispatched workers are unaffected: a worker loads only the skills its recipe declares.
 - **Merge.** Denials win: a tool named in any loaded skill's `disallowed-tools` is blocked. Allow-narrowing applies only while every loaded skill declares `allowed-tools`; the merged surface is the union of those lists. A loaded skill that declares no `allowed-tools` keeps the full surface for its own workflow, which lifts the allow-narrowing (never the denials) for that window.
 - **Exemptions.** `context` (the remaining requested skills of the turn must still load) and `ask_user` (the escape hatch the block message points at) are always admitted.
 - **Direction.** Narrowing only blocks. It never grants a tool the safety net, damage-control rules, or autonomy mapping would refuse, and an out-of-surface call blocks terminally instead of parking for confirmation.
-- **Block message.** The rejection names the tool, the active skill(s), and the merged surface, and states the remediation: work within the declared surface, or use `ask_user` (when available) to hand the step to the operator. The audit row carries reason code `skill_surface`.
+- **Block message.** The rejection names the tool, the active skill(s), the merged surface, and the lifetime that actually applies (session-scoped for a carried surface, turn/run-scoped otherwise), and states the remediation: work within the declared surface, or use `ask_user` (when available) to hand the step to the operator. The audit row carries reason code `skill_surface`.
 
 ---
 
@@ -236,7 +237,8 @@ Path-policy behavior:
 The default damage-control policy populates `noWritePaths` from the interop
 agent registry: `~/.claude/`, `.claude/`, `~/.codex/`, `.codex/`, `~/.config/opencode/`,
 `.opencode/`, `~/.gemini/`, `.gemini/`, `~/.copilot/`, `~/.cursor/`, `.cursor/`,
-`~/.antigravitycli/`, `.antigravitycli/`, `~/.agents/`, and `.agents/`. Clio never writes
+`~/.gemini/antigravity-cli/`, `.gemini/antigravity-cli/`, the legacy
+`~/.antigravitycli/` and `.antigravitycli/`, `~/.agents/`, and `.agents/`. Clio never writes
 into another coding agent's directory. It reads those roots for skills, prompts, and
 rule prose and has no reason to author them. A `write` or `edit` targeting any of
 these paths is refused at every posture including `auto-edit` and `full-auto`, with reason
@@ -261,7 +263,7 @@ Prefer typed tools over Bash:
 - `verify(check="<id>")` runs either a declared package.json verification script (the `test*/lint*/build*/typecheck*/check*/format*/ci*` family) or an exact version-1 `.clio-coder/verifiers.yaml` argv vector through bounded execution helpers with no shell; `verify()` lists both sources through one canonical check projection.
 - `verify(check="frontend", path=...)` validates frontend artifacts without granting arbitrary shell access.
 
-A package-script check and the frontend validator are in the no-prompt set at `auto-edit`: both are bounded by the verification-script family and a fixed argv shape. A project-catalog check is not. The engine resolves the check id against `.clio-coder/verifiers.yaml` on every call and treats the declared argv exactly like a bash command string: the damage-control rules and the zero-access read guard scan it, and it is tagged unrecognized, so `auto-edit` parks it for one confirmation that shows the argv and `full-auto` runs it. `.clio-coder/verifiers.yaml` and `.clio-coder/safety.yaml` are read-only to the model's `write`, `edit`, and bash redirect paths through the default path policy: both files are operator authority, and a model that could author either one could widen its own permissions in two tool calls.
+A package-script check and the frontend validator are in the no-prompt set at `auto-edit`: both are bounded by the verification-script family and a fixed argv shape. A project-catalog check is not. The engine resolves the check id against `.clio-coder/verifiers.yaml` on every call and treats the declared argv exactly like a bash command string: the damage-control rules and the zero-access read guard scan it, and it is tagged unrecognized, so `auto-edit` parks it for one confirmation that shows the argv and `full-auto` runs it. `.clio-coder/verifiers.yaml`, `.clio-coder/safety.yaml`, `.clio-coder/skills/`, and the user-scoped `<configDir>/skills/` are read-only to the model's `write`, `edit`, and bash redirect paths through the default path policy: these files and skill roots are operator authority, and a model that could author them could change its own permissions or active instructions. Skill installs go through `clio-coder skills install`.
 
 The project verifier catalog is an executable authority supplied by the repository, not by model prose. Its schema rejects unknown fields, shell strings, invalid or duplicate IDs, oversized values, absolute or escaping working directories, unsupported versions, and collisions with package-provider IDs. It also refuses the common shell executables (`sh`, `bash`, `zsh`, and the like) as argv[0], which is a tripwire against the obvious mistake rather than a sandbox: `python3 -c`, `node -e`, and `env bash -c` pass the schema, so the authority boundary is the fact that the catalog file is operator-owned and read-only to the model, and that every catalog check is scanned by the damage-control rules and parked at `auto-edit`. A catalog entry fixes argv, repository-relative cwd, and timeout. Tool-call `args`, `cwd`, timeout, output-cap, or environment-shaped fields cannot widen it. Safe-exec uses `spawn` without a shell, filters the child environment to the Clio allowlist, honors cancellation, and reports exact argv and termination evidence.
 
@@ -290,14 +292,22 @@ Fleet dispatch is admitted only when the requested worker scope is a subset of t
 
 Dispatch workers can run the same HTTP or native runtimes as the orchestrator. Clio observes and governs those tool calls directly, so every worker run is subject to the same safety mapping and receipt accounting as an interactive turn.
 
-Three integration paths exist for driving Claude Code, ranging from fully enforced to advisory gating:
+Three worker-runtime safety categories range from fully enforced to advisory gating:
 
 - **`claude-sdk` (Enforced Safety):** Drives [@anthropic-ai/claude-agent-sdk](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) directly. This is the **strong safety path** because Clio enforces tool gating before execution. Clio registers a `PreToolUse` hook (which fires for all tool uses, including auto-allowed reads) and wraps `canUseTool` for permission paths. Every tool request is mapped into a Clio tool/action class, evaluated by the safety net, and passed through the active autonomy matrix. Because a dispatched worker is noninteractive, any `ask` decision is resolved as a non-stall denial (`fleet.permissions.mode=deny` returns denial; `fleet.permissions.mode=fail` terminates the run with a permission-required code).
-- **`claude-code` (Subprocess Gating):** Drives `claude -p` as a subprocess. Because the CLI lacks a direct callback hook, Clio cannot evaluate each tool invocation. Instead, Clio maps the active autonomy level to the binary's command-line parameters (such as `--permission-mode` and tool allowlists). Unrecognized tools are gated by the subprocess runtime itself. Dispatch at autonomy `suggest` is refused outright (the same applies to `antigravity-code`): a subprocess cannot park a tool call for approval, so `suggest` has no honest mapping and the runner fails closed before launching the external CLI. A dangerous bypass (`--allow-dangerously-skip-permissions`) is only sent when autonomy is `full-auto` and `CLIO_CODER_ALLOW_EXTERNAL_FULL_ACCESS=1`, and it is never silent: the run's receipt records it (see the enforcement grades below) and evidence raises an external-bypass finding.
+- **External CLI subprocesses:** `claude-code` drives `claude -p`; the experimental, dispatch-only `antigravity-code` runtime drives the operator's local `agy` through one literal stdin `stream-json` work order. Neither exposes a callback through which Clio can evaluate each tool invocation, so Clio maps autonomy onto each CLI's command-line controls. Antigravity launches always name an explicit mode and disable slash-command expansion rather than inheriting mutable interactive settings. Dispatch at autonomy `suggest` is refused outright: a subprocess cannot park a tool call for approval, so `suggest` has no honest mapping and the runner fails closed before launch. A dangerous bypass (`--allow-dangerously-skip-permissions` for Claude or `--dangerously-skip-permissions` for Antigravity) is sent only when autonomy is `full-auto` and `CLIO_CODER_ALLOW_EXTERNAL_FULL_ACCESS=1`; otherwise Antigravity full-auto is capped at `accept-edits`. A bypass is never silent: the run's receipt records it (see the enforcement grades below) and evidence raises an external-bypass finding. Clio sends an allowlisted child environment rather than its provider keys or external-full-access gate, bounds stdout/stderr and persisted diagnostics, validates the admitted workspace, and owns the deadline and cancellation. POSIX cancellation targets the process group with direct-child fallback and bounded SIGTERM-to-SIGKILL escalation; Windows uses the strongest honest direct-child termination available here.
 - **Claude Code over ACP (Advisory Gating):** Drives Zed's `@zed-industries/claude-code-acp` (or `@agentclientprotocol/claude-agent-acp`) bridge as an [Agent Client Protocol (ACP)](https://agentclientprotocol.com) delegation agent. Clio's ACP mediator intercepts tool calls and filters them against the safety net, but gating is ultimately **advisory** as Claude governs its own runtime execution. For strict, code-enforced per-tool safety, `claude-sdk` is preferred over ACP.
 
 All Claude Code runtimes rely on the user's existing CLI authentication and store no credentials in Clio.
 
+External one-shot receipts also say what budget Clio can and cannot enforce. Clio
+controls one process launch, its wall-clock deadline, cumulative output cap,
+cancellation, and result-contract validation. Recipe per-tool calls, read reserve,
+and synthesis numbers remain in the envelope but are explicitly
+`unobserved-not-enforced`, because Antigravity owns its internal tools, network,
+prompts, and approvals. Clio schedules no automatic retry of an external
+generating agent loop.
+
 ### Autonomy enforcement grades
 
 How faithfully a runtime can honor the autonomy model is a recorded fact, not an assumption. Worker receipts carry an optional `autonomyEnforcement` block sealed into the integrity digest:
@@ -363,26 +373,19 @@ It is critical to distinguish these two control axes:
 The effective rigor level for a session or dispatch run is resolved at boot time using the following prioritization:
 
 1. **Explicit Override**: Checked via the `CLIO_CODER_RIGOR` environment variable. It is trimmed and parsed case-insensitively. A value of `"high"` or `"normal"` overrides any other setting.
-2. **Repository-Derived Default**: If no override is present, Clio checks the workspace root for the presence of any of the following validation contract files:
-   - `.clio-coder/validation.yaml`
-   - `.clio-coder/validation.yml`
-   - `validation.yaml`
-   - `validation.yml`
-   - `VALIDATION.md`
-   
-   If any of these files are present, the default rigor level is raised to `high`. Otherwise, the default is `normal`.
+2. **Repository-Derived Default**: If no override is present, Clio loads the first of `.clio-coder/validation.yaml`, `.clio-coder/validation.yml`, `validation.yaml`, or `validation.yml` at the workspace root through the strict version-1 loader in `src/domains/safety/validation-contract.ts`. A contract that parses raises the default to `high`. A contract that does not parse leaves the default at `normal` and carries the fault as a diagnostic that `clio-coder doctor` and the interactive startup notices print. `VALIDATION.md` is advisory prose: it is recognized as present but never parsed and never raises rigor. `rigorResolution()` returns the rigor with its source (`override`, `validation-contract`, `invalid-contract`, `markdown-advisory`, or `none`) and the diagnostic; `resolveRigor()` is the thin wrapper that returns the rigor alone. See [Scientific Validation](../process/scientific-validation.md) for the schema.
 
 ---
 
 ### The Finish Gate and Re-Prompt Behavior
 
-On every settled `turn_end`, the finish-contract assessor scans entries since the last user message, capped at 80 entries. The trigger is action-scoped: the gate engages only when that window contains successful workspace mutation evidence and no validation evidence or explicit limitation. The model does not have to type a phrase such as `done` or `fixed`; the settled turn after mutation is the completion signal.
+On every settled `turn_end`, the finish-contract assessor scans entries since the last user message, capped at 80 entries. The trigger is action-scoped: the gate engages only when that window contains successful workspace mutation evidence and no validation evidence or `limitation` receipt. The model does not have to type a phrase such as `done` or `fixed`; the settled turn after mutation is the completion signal. The assistant's prose never enters the decision.
 
 The assessor decision order is:
 
 1. If the window has no successful mutating receipt or settled mutating `!` bash execution, the contract passes with `no_mutation`.
 2. If the window has validation evidence, the contract passes with `validation_evidence`. Evidence includes successful validation commands, `verify` checks (declared package scripts, admitted project-catalog entries, and the frontend check), passed dispatch receipts, and protected-artifact validation records.
-3. If the assistant explicitly states what could not be verified and why, the contract passes with `explicit_limitation`.
+3. If the window has a successful `limitation` tool receipt (a `limitation` tool_call paired with a non-error tool_result, carrying the scope, a reason from `no-runner`, `blocked`, `out-of-scope`, `environment`, or `other`, and optional unverified paths), the contract passes with `explicit_limitation`. A call the tool rejected leaves no receipt and does not count.
 4. Otherwise, the contract engages with `unvalidated_mutation`.
 
 The finish assessment projects only onto the canonical completion-evidence
@@ -395,11 +398,11 @@ persisted-format compatibility table are documented in
 [`evidence-and-memory.md`](evidence-and-memory.md#canonical-trust-status).
 
 - **Normal Rigor**: Clio issues a soft advisory warning (`FINISH_CONTRACT_ADVISORY_MESSAGE`) injected as a reminder for the next turn, but permits the turn to settle.
-- **High Rigor**: Clio withholds completion. The assessor emits `request_continuation` and a warning `inject_reminder` carrying `HIGH_RIGOR_REVALIDATION_MESSAGE`, instructing the model to run a verification-family command (e.g. `npm test`, `npm run build`) or explicitly declare a limitation before ending.
+- **High Rigor**: Clio withholds completion. The assessor emits `request_continuation` and a warning `inject_reminder` carrying `HIGH_RIGOR_REVALIDATION_MESSAGE`, instructing the model to run a verification-family command (e.g. `npm test`, `npm run build`) or call `limitation` before ending.
 
 #### Exemptions and Safety Precautions
 - **No-Mutation Turns**: Read-only status, alignment, and inspection turns are exempt because there is no successful workspace mutation in the recent window.
-- **Limitation Claims**: If the model explicitly states what could not be verified and why, the assessor accepts the statement as an explicit limitation and allows the turn to settle cleanly.
+- **Limitation Receipts**: A successful `limitation` tool receipt in the window settles the contract with `explicit_limitation`. The assistant's prose never does, so wording alone cannot pass the gate and a real limitation is never missed for its phrasing.
 - **Dynamic Injection**: All gate directives are injected dynamically through middleware effects. This ensures that the static system prompt prefix remains byte-stable, preserving prompt caches.
 - **Prior Hard-Block Preservation**: If a prior middleware hook has already emitted a hard block (e.g. tool-prose violation), the high-rigor continuation is suppressed so that critical error guidance is not overwritten.
 

package/docs/architecture/tui-design.md

@@ -314,7 +314,7 @@ The `/settings` overlay is a full-screen transactional control center:
 
 ### 7.2 Fleet Runs Board
 
-The `Alt+W` board renders one card per run. The default list is compact: run id, route, task, status, telemetry, retry, tool names, and proof. `Enter` opens the selected run's worker detail, which adds two rows to that card and nothing to any other:
+The `Alt+W` board renders one card per run from the observability run projection, which owns lifecycle, worker progress, receipt trust, retries, cancellation, fleet positions, and evidence readiness; the board owns only ordering, selection, and rendering. The default list is compact: run id, route, task, status, telemetry, retry, tool names, and proof. `Enter` opens the selected run's worker detail, which adds two rows to that card and nothing to any other:
 
 - **`doing`**: the phase (`◐ thinking` in `reason`, `◑ writing` in `accent`, `⚙ tool` in `action`, `◔ waiting` in `info`) followed by the running call as `<tool> <verb> <object>`, or the last finished call as `last <tool> <verb> <object>`. The verb and object come from a descriptor composed at the worker seam; raw arguments never reach the renderer.
 - **`answer`**: the newest rows of the worker's bounded prose on a `│` rail with a hanging indent under the key, then a dim row naming the lines and bytes the bounds refused and the `/view dispatch:<runId>` deep link.

package/docs/guide/built-in-agents.md

@@ -49,14 +49,14 @@ User-facing agents visible in `clio-coder agents` and `/agents`.
 
 | Agent ID | Primary tools | Purpose | Capability | Latency |
 | --- | --- | --- | --- | --- |
-| `architect` | read, grep, find, ls, code_nav, git, artifact, context, ledger | Designs a change across boundaries and slices it into a sprint: contracts, migrations, validation gates, and cut-it sprint slicing. | `artifact-write` | `deep` |
-| `coder` | read, write, edit, grep, find, ls, web_fetch, git, bash, verify, code_nav, ledger | Implements bounded code changes, repairs, and refactors, behavior-preserving by default. | `workspace-edit` | `balanced` |
+| `architect` | read, grep, find, ls, code_nav, git, artifact, context, ledger, limitation | Designs a change across boundaries and slices it into a sprint: contracts, migrations, validation gates, and cut-it sprint slicing. | `artifact-write` | `deep` |
+| `coder` | read, write, edit, grep, find, ls, web_fetch, git, bash, verify, code_nav, ledger, limitation | Implements bounded code changes, repairs, and refactors, behavior-preserving by default. | `workspace-edit` | `balanced` |
 | `debugger` | read, grep, find, ls, git, verify, code_nav, ledger | Diagnoses failing code, tests, or runs without editing, reading receipts, logs, and runtime behavior. | `verification` | `balanced` |
-| `documenter` | read, write, edit, grep, find, ls, git, verify, code_nav, context, ledger | Updates developer docs, examples, and operational runbooks. | `workspace-edit` | `balanced` |
-| `git-master` | read, write, edit, context, git, bash, grep, find, ls, code_nav, ledger | Runs bounded git operations end to end: history, commits, worktrees, integration merges, and PR prep. | `workspace-edit` | `balanced` |
-| `tester` | read, write, edit, grep, find, ls, git, verify, code_nav, ledger | Adds focused deterministic regression and coverage tests. | `workspace-edit` | `balanced` |
-| `verifier` | read, grep, find, ls, git, verify, code_nav, ledger | Runs test, lint, build, review, and release gates and reports each independently. | `verification` | `fast` |
-| `wiki-writer` | read, write, edit, grep, find, ls, code_nav, context, ledger | Plans a repository wiki or writes one wiki page against a supplied plan. | `workspace-edit` | `balanced` |
+| `documenter` | read, write, edit, grep, find, ls, git, verify, code_nav, context, ledger, limitation | Updates developer docs, examples, and operational runbooks. | `workspace-edit` | `balanced` |
+| `git-master` | read, write, edit, context, git, bash, grep, find, ls, code_nav, ledger, limitation | Runs bounded git operations end to end: history, commits, worktrees, integration merges, and PR prep. | `workspace-edit` | `balanced` |
+| `tester` | read, write, edit, grep, find, ls, git, verify, code_nav, ledger, limitation | Adds focused deterministic regression and coverage tests. | `workspace-edit` | `balanced` |
+| `verifier` | verify, evidence, read, grep, find, ls, git, code_nav, ledger | Runs test, lint, build, review, and release gates and reports each independently. | `verification` | `fast` |
+| `wiki-writer` | read, write, edit, grep, find, ls, code_nav, context, ledger, limitation | Plans a repository wiki or writes one wiki page against a supplied plan. | `workspace-edit` | `balanced` |
 
 ### Shipped Shadow and Internal Agents
 Internal orchestration helpers and internal process agents. They are hidden from default displays but visible via `clio-coder agents --all`. The full on-demand catalog has a separate shadow section and omits internal recipes; the compact session prompt likewise omits internal recipes and also excludes the operator-only `oracle`.
@@ -64,8 +64,9 @@ Internal orchestration helpers and internal process agents. They are hidden from
 | Agent ID | Primary tools | Purpose | Capability | Latency |
 | --- | --- | --- | --- | --- |
 | `scout` | read, grep, find, ls, context, code_nav, git, ledger | Broad repository reconnaissance with cited findings: orientation, structure and entry-point mapping, multi-file symbol hunting. | `read-only` | `fast` |
-| `researcher` | read, web_fetch, context, ledger | Researches external docs, standards, and papers for coding decisions. | `read-only` | `deep` |
-| `provenance` | read, grep, find, ls, git, ledger | Reads receipts, diffs, and telemetry for evidence-backed handoffs. | `read-only` | `balanced` |
+| `researcher` | read, web_fetch, context, ledger | Extracts and compares concrete supplied URLs, standards, release notes, and papers through Clio-observed reads and URL retrieval. | `read-only` | `deep` |
+| `world-knowledge` | optional web_fetch, read, context, ledger | Current open-world discovery, ecosystem comparison, broad external context, and an advisory second opinion; reports when discovery is unavailable. | `read-only` | `deep` |
+| `provenance` | evidence, read, grep, find, ls, git, ledger | Reads receipts, diffs, and telemetry for evidence-backed handoffs. | `read-only` | `balanced` |
 | `oracle` | read, grep, find, ls, code_nav, context, ledger | Shadow advisor behind `/oracle` that protects consistency with prior decisions and returns the strongest challenge to a question. | `read-only` | `deep` |
 | `context-bootstrap` | read, grep, find, ls, context, code_nav | Internal agent behind `clio-coder context init` that parses repository and returns CLIO-CODER.md payload. | `read-only` | `balanced` |
 
@@ -75,6 +76,19 @@ The builtin `architect` also serves as the default author for a version 5 fleet
 
 Grounding is checked against the run's own reads, not just against the file. The worker records the exact line span every successful read returned, and a cited line must fall inside one. A line that exists in the file but was never read fails, which is what stops an approximated or inferred line number from passing as observation. `grep` and `code_nav` hits are leads: read the file before citing what they point at.
 
+The three discovery roles are deliberately non-overlapping. `scout` is
+repository-only reconnaissance with live `path:line` grounding and never browses
+external sources. `researcher` starts from concrete URLs or documents and uses
+Clio-observed `read`/`web_fetch` calls to extract and compare them; `web_fetch` is
+URL retrieval, not search. `world-knowledge` is for current open-world discovery,
+ecosystem comparison, broad context, and an independent advisory opinion. Its
+tools are all optional so it can run on a native Clio target or an opaque external
+worker. A native target without discovery must use caller-supplied sources or say
+discovery was unavailable. Its `world-knowledge-report` separates supported
+facts and supplied source identifiers from synthesis, uncertainty, and follow-up
+verification; it never fabricates citations. The capability class remains
+`read-only` regardless of the caller's requested autonomy.
+
 `oracle` is the only shadow agent an operator reaches directly, and only through
 `/oracle <question>`. It never receives a forked transcript. `/oracle` packs a
 bounded digest instead and sends it as dispatch briefing data: the settled
@@ -181,9 +195,9 @@ To ensure security and proper boundary isolation, shadow and internal agents are
 In addition to standard HTTP targets and [Agent Client Protocol (ACP)](https://agentclientprotocol.com) delegation agents, Clio dispatches subagents to sanctioned subscription worker runtimes:
 - **`claude-sdk` (Claude Agent SDK):** Serves as a main worker runtime for driving fleet agents. It integrates with [@anthropic-ai/claude-agent-sdk](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) alongside Clio's native subagent workers (like a local [llama.cpp](https://github.com/ggerganov/llama.cpp), [Ollama](https://ollama.com), [LM Studio](https://lmstudio.ai), [vLLM](https://github.com/vllm-project/vllm), or [SGLang](https://github.com/sgl-project/sglang) fleet) to execute tasks under a Claude subscription. Every tool call is mediated by Clio (`canUseTool` plus a `PreToolUse` hook): the safety net and autonomy matrix apply, and the run's admitted tool surface, which is narrowed by any `tool_profile`, is enforced authoritatively. Consequently, an out-of-profile tool (for example `bash` under `minimal-local`) is denied even though the underlying preset offers it. The narrowed surface is also translated into the SDK's `disallowedTools` option as defense in depth. Because it routes tool calls through Clio safety, it behaves as a native worker.
 - **`claude-code` (Claude Subprocess):** Runs `claude -p` as a subprocess worker, mapping autonomy levels to the CLI's permission modes. It is a black box: tool calls run inside the `claude` process and are not routed through Clio's per-tool mediation, so Clio cannot enforce a per-tool profile on it. Dispatching a narrowing `tool_profile` (`minimal-local` or `science-local`) to this runtime is refused; use `full-agent` (or a native / `claude-sdk` worker) instead.
-- **`antigravity-code` (Antigravity CLI):** Runs an Antigravity CLI subprocess as a subscription worker target for fleet dispatch. Like `claude-code`, it is a black box with no per-tool mediation and no per-tool allowlist, so a narrowing `tool_profile` is refused rather than silently ignored.
+- **`antigravity-code` (Antigravity CLI — experimental local delegation):** Runs the operator-installed and authenticated official `agy` command as a local external delegation worker. It is useful for a `world-knowledge` pass, a second opinion, or another bounded one-shot subtask; it is never an orchestrator or Gemini chat backend. Clio consumes agy's structured stream and live model catalog but cannot mediate individual tools, so a narrowing `tool_profile` is refused rather than silently ignored. The `world-knowledge` binding is permanently read-only.
 
-Agent budgets follow the same mediation boundary. Native workers and `claude-sdk` enforce canonical call counting, the canonical-`read` reserve, and the synthesis transition. Every valid Markdown recipe declares a budget, so recipe-based runs are refused on `claude-code` and `antigravity-code`; those subprocess targets can accept only work that reaches admission without an explicit recipe or request budget. Silently ignoring numeric bounds would be unsafe. Claude vendor aliases never appear in recipes or prompt authority and cannot reintroduce a canonical tool removed by admission.
+Agent budgets follow the same mediation boundary. Native workers and `claude-sdk` enforce canonical call counting, the canonical-`read` reserve, and the synthesis transition. An opaque external loop instead receives an `external-one-shot` enforcement classification: Clio enforces one subprocess launch, its deadline, output cap, cancellation, and result-contract validation, while recording recipe per-tool numbers as `unobserved-not-enforced`. Receipts and status never label those internal per-tool limits enforced, and Clio never automatically retries a generating external-agent run. Claude vendor aliases never appear in recipes or prompt authority and cannot reintroduce a canonical tool removed by admission.
 
 Interactive TUI: