@iowarp/clio-coder 0.4.0 → 0.4.1

package/dist/worker/entry.js

@@ -16,13 +16,13 @@ import {
   resolveDeliveryTools,
   sanitizeLockedSynthesisMessage,
   workerLoopBlockBudget
-} from "../chunk-HJJTYUHX.js";
+} from "../chunk-QMXC4JB7.js";
 import "../chunk-K7VKOLQQ.js";
 import {
   createMiddlewareContractFromSnapshot,
   createMiddlewareToolChoiceControl,
   shouldRequestStalledTurnContinuation
-} from "../chunk-QLL7ILRG.js";
+} from "../chunk-JA5QWE4Z.js";
 import {
   CONFIRMED_SCOPE,
   READONLY_SCOPE,
@@ -37,11 +37,11 @@ import "../chunk-BMS5RKQY.js";
 import "../chunk-QSNYB6ZV.js";
 import "../chunk-QDC3K2U3.js";
 import "../chunk-YPI3QQCF.js";
-import "../chunk-HWHKMHUA.js";
-import "../chunk-LQ3DZAMX.js";
-import "../chunk-NHCZP4K7.js";
-import "../chunk-36EJLSQQ.js";
-import "../chunk-BKFJHQCA.js";
+import "../chunk-7OBGU7UB.js";
+import "../chunk-ABLSQ6JX.js";
+import "../chunk-PBP4B7XR.js";
+import "../chunk-JZWT5J3Y.js";
+import "../chunk-I66EAJFY.js";
 import "../chunk-VG7TBQIY.js";
 import {
   DEFAULT_ESCALATION_FALLBACK,
@@ -58,28 +58,29 @@ import {
   startAntigravityWorkerRun,
   startClaudeCodeWorkerRun,
   validateRehydratedWorkerRuntime
-} from "../chunk-J4W7KFM7.js";
-import "../chunk-SJ5ZKQ4S.js";
-import "../chunk-2JDWVJND.js";
-import "../chunk-GKF55TAZ.js";
+} from "../chunk-2VG7KLYV.js";
+import "../chunk-7EPLI7VL.js";
+import "../chunk-6DWBAZ5U.js";
+import "../chunk-PVAMAVBB.js";
 import {
   createSafetyPolicyEngine
-} from "../chunk-32KWKNSF.js";
+} from "../chunk-IXJT6DCX.js";
 import {
   describeCallTarget
 } from "../chunk-TVHHYFHE.js";
 import "../chunk-42FMPA75.js";
 import "../chunk-H7IXIC72.js";
-import "../chunk-5LXZXPKX.js";
+import "../chunk-VN3SHNBN.js";
 import "../chunk-OQE5J4C6.js";
 import {
   DEFAULT_AUTONOMY_LEVEL,
   agentSkillToolPolicy
-} from "../chunk-RAPCMZL4.js";
-import "../chunk-CY6FY24N.js";
+} from "../chunk-FSP7CMNU.js";
+import "../chunk-R23Z6K6I.js";
 import "../chunk-OZNBF4L3.js";
 import "../chunk-4BJ5BYCE.js";
 import "../chunk-6XLNIQDB.js";
+import "../chunk-U2WB7TZS.js";
 import {
   UNKNOWN_RESOURCE,
   WORKER_PROTOCOL_VERSION,
@@ -94,10 +95,10 @@ import {
   toolSignatureOf,
   withinFrameBudget,
   workerSpecDigest
-} from "../chunk-CMZWFGD2.js";
+} from "../chunk-VAVR4IJY.js";
 import {
   deleteInjectedCompileCacheFrom
-} from "../chunk-PQEFIJ36.js";
+} from "../chunk-2LEAKD4C.js";
 import "../chunk-HHV2GANA.js";
 import {
   RESULT_CONTRACT_REPAIR_LIMIT,
@@ -105,7 +106,7 @@ import {
   parseWorkerResultContract,
   resultContractRepairMessages,
   validateResultContract
-} from "../chunk-DYJP44XW.js";
+} from "../chunk-IG7BCQBA.js";
 import {
   protectedArtifactMutationBlockReason
 } from "../chunk-GCSMB2KY.js";
@@ -126,24 +127,27 @@ import {
   setGlobalDefaultMaxOutputTokens,
   setProtectedModelsProvider,
   setResidencyNoticeSink
-} from "../chunk-DQITNCXG.js";
+} from "../chunk-UEDMSP56.js";
 import "../chunk-CFGTUFWB.js";
-import "../chunk-P3FOHJT4.js";
-import "../chunk-UM7N4G5A.js";
-import "../chunk-ZGVHUX3M.js";
-import "../chunk-HLW2MRKE.js";
-import "../chunk-76ONBSIA.js";
+import "../chunk-72GZI5EV.js";
+import "../chunk-CWVRRIEI.js";
+import "../chunk-MQXIVJ35.js";
 import "../chunk-R346GLFC.js";
+import "../chunk-PMZVFWSR.js";
+import "../chunk-HLW2MRKE.js";
+import "../chunk-BTK3SSSK.js";
 import "../chunk-IHXBNWMM.js";
 import {
   readSettings,
   validateSettingsFile
-} from "../chunk-VFA6GDY5.js";
+} from "../chunk-EIMVLWB3.js";
+import "../chunk-D7E7WCDF.js";
+import "../chunk-HJWWJ6IL.js";
 import {
   setGitCommitAttributionEnabled,
   withManagedGitCommitAttributionEnvironment
-} from "../chunk-BBVJUZHB.js";
-import "../chunk-FQ4SKYE4.js";
+} from "../chunk-JIEGK6UF.js";
+import "../chunk-EBY63B7G.js";
 import {
   AI_AGENT_NAME
 } from "../chunk-6EJMN2Y3.js";
@@ -152,17 +156,18 @@ import {
 } from "../chunk-IWHMRKLL.js";
 import {
   registerBuiltinRuntimes
-} from "../chunk-6DB53AJS.js";
-import "../chunk-GXNLGKAB.js";
+} from "../chunk-QKIFBZKT.js";
+import "../chunk-BWW4HLO4.js";
 import "../chunk-LL4KHSZI.js";
 import {
   configureGuardrails,
+  guardrailValuesFromSettings,
   isWorkerToolCallCapExceededReason,
   isWorkerToolCallCapSynthesisReason
-} from "../chunk-4ZG3XFUR.js";
-import "../chunk-HI63TFOG.js";
-import "../chunk-BBVYXMFO.js";
-import "../chunk-SST6Z5JA.js";
+} from "../chunk-NLFAQR7Z.js";
+import "../chunk-CDNVLKUX.js";
+import "../chunk-WNP7O5WZ.js";
+import "../chunk-336NSSKI.js";
 import "../chunk-IKCO5N3L.js";
 import "../chunk-3I7MS7N2.js";
 import "../chunk-APJ265NV.js";
@@ -171,10 +176,10 @@ import "../chunk-WEPFGWHJ.js";
 import {
   getRuntimeRegistry
 } from "../chunk-NUGM5KR6.js";
-import "../chunk-VO2LKSTM.js";
+import "../chunk-O42A54GG.js";
 import {
   registerFauxFromEnv
-} from "../chunk-UOSL25KY.js";
+} from "../chunk-VXMFAE2W.js";
 import "../chunk-YXLYO42X.js";
 import {
   init_esm_shims
@@ -717,7 +722,7 @@ function startClaudeSdkWorkerRun(input, emit) {
     },
     () => {
       budgetFailure = true;
-      emit({ type: "clio_run_outcome", payload: { outcomeCode: "worker_tool_call_cap_exhausted" } });
+      emit({ type: "clio_coder_run_outcome", payload: { outcomeCode: "worker_tool_call_cap_exhausted" } });
       abort();
     },
     resolveDeliveryTools(allowedToolSet, input.product)
@@ -742,7 +747,7 @@ function startClaudeSdkWorkerRun(input, emit) {
     if (hookInput.hook_event_name !== "PostToolBatch" || !budgetGate?.phaseReached()) return { continue: true };
     if (input.budget?.synthesis === false) {
       budgetFailure = true;
-      emit({ type: "clio_run_outcome", payload: { outcomeCode: "worker_tool_call_cap_exhausted" } });
+      emit({ type: "clio_coder_run_outcome", payload: { outcomeCode: "worker_tool_call_cap_exhausted" } });
       return { continue: false, stopReason: `worker agent budget reached (${input.budget.toolCalls})` };
     }
     return {
@@ -993,8 +998,8 @@ function startWorkerRun(input, emit) {
   }
   registerClioApiProviders();
   const workerSettings = validateSettingsFile().settings;
-  setGlobalDefaultMaxOutputTokens(workerSettings.defaults.maxTokens);
-  configureGuardrails(workerSettings.guardrails);
+  setGlobalDefaultMaxOutputTokens(workerSettings.chat.maxOutputTokens);
+  configureGuardrails(guardrailValuesFromSettings(workerSettings));
   const fauxModel = registerFauxFromEnv();
   const agentSkillPolicy = input.allowedTools.includes(ToolNames.Context) && input.noSkills !== true ? agentSkillToolPolicy(input.agentSkills ?? []) : void 0;
   const activeWorkerTools = workerProviderSupportsTools(input) ? input.allowedTools : [];
@@ -1107,13 +1112,13 @@ function startWorkerRun(input, emit) {
   );
   const telemetry = {
     onStart(event) {
-      emit({ type: "clio_tool_start", payload: event });
+      emit({ type: "clio_coder_tool_start", payload: event });
     },
     onFinish(event) {
-      emit({ type: "clio_tool_finish", payload: event });
+      emit({ type: "clio_coder_tool_finish", payload: event });
       if (event.outcome !== "blocked" || typeof event.reason !== "string") return;
       if (isWorkerToolCallCapSynthesisReason(event.reason)) {
-        emit({ type: "clio_run_outcome", payload: { outcomeCode: "worker_tool_call_cap_exhausted" } });
+        emit({ type: "clio_coder_run_outcome", payload: { outcomeCode: "worker_tool_call_cap_exhausted" } });
         if (workerBoundFailure === null) {
           workerBoundFailure = event.reason;
           process.stderr.write(`[worker] ${event.reason}
@@ -1123,7 +1128,7 @@ function startWorkerRun(input, emit) {
       }
       if (isWorkerToolCallCapExceededReason(event.reason) || isLoopGuardSynthesisBackstopReason(event.reason)) {
         emit({
-          type: "clio_run_outcome",
+          type: "clio_coder_run_outcome",
           payload: {
             outcomeCode: isLoopGuardSynthesisBackstopReason(event.reason) ? "loop_guard_tools_disabled_exhausted" : "worker_tool_call_cap_exhausted"
           }
@@ -1242,7 +1247,7 @@ function startWorkerRun(input, emit) {
           for (const message of repair) agent.followUp(message);
         } else if (workerBoundFailure === null) {
           workerBoundFailure = `result contract failed after ${RESULT_CONTRACT_REPAIR_LIMIT} bounded repair rounds: ${violation}`;
-          emit({ type: "clio_run_outcome", payload: { outcomeCode: "result_contract_exhausted" } });
+          emit({ type: "clio_coder_run_outcome", payload: { outcomeCode: "result_contract_exhausted" } });
           process.stderr.write(`[worker] ${workerBoundFailure}
 `);
         }
@@ -1279,7 +1284,7 @@ function startWorkerRun(input, emit) {
     answeredEscalations.set(active.callKey, { decision, requestId });
     if (decision === "approve") {
       emit({
-        type: "clio_permission_resolved",
+        type: "clio_coder_permission_resolved",
         payload: {
           tool: active.tool,
           actionClass: active.actionClass,
@@ -1302,7 +1307,7 @@ function startWorkerRun(input, emit) {
     const denialContext = source === "timeout" ? "escalation timed out with no operator decision" : "operator denied";
     const reason = effectiveFail ? `permission required for ${active.tool} (${active.actionClass}); ${denialContext} and workers fallback=fail ends this run` : `permission denied by ${source === "timeout" ? "escalation timeout fallback" : "operator"}: ${active.tool} requires ${active.actionClass} confirmation`;
     emit({
-      type: "clio_permission_resolved",
+      type: "clio_coder_permission_resolved",
       payload: {
         tool: active.tool,
         actionClass: active.actionClass,
@@ -1327,7 +1332,7 @@ function startWorkerRun(input, emit) {
     const active = activeEscalation;
     if (!active) return;
     emit({
-      type: "clio_permission_resolved",
+      type: "clio_coder_permission_resolved",
       payload: {
         tool: active.tool,
         actionClass: active.actionClass,
@@ -1349,7 +1354,7 @@ function startWorkerRun(input, emit) {
         const approved = remembered.decision === "approve";
         const reason2 = approved ? `operator approved an identical ${call.tool} call earlier in this run (request ${remembered.requestId}); the answer stands without a new prompt` : `permission denied by operator: an identical ${call.tool} call was already denied earlier in this run (request ${remembered.requestId}); the answer stands, so do not repeat this call`;
         emit({
-          type: "clio_permission_resolved",
+          type: "clio_coder_permission_resolved",
           payload: {
             tool: call.tool,
             actionClass,
@@ -1377,7 +1382,7 @@ function startWorkerRun(input, emit) {
       activeEscalation = { requestId, tool: call.tool, actionClass, callKey, timer };
       const target = describeCallTarget(call.tool, call.args);
       emit({
-        type: "clio_permission_escalated",
+        type: "clio_coder_permission_escalated",
         payload: {
           requestId,
           tool: call.tool,
@@ -1398,7 +1403,7 @@ function startWorkerRun(input, emit) {
     }
     const reason = onPermission === "fail" ? failReason(call.tool, actionClass) : denyReason(call.tool, actionClass);
     emit({
-      type: "clio_permission_resolved",
+      type: "clio_coder_permission_resolved",
       payload: {
         tool: call.tool,
         actionClass,
@@ -1899,7 +1904,7 @@ async function main() {
     process.stderr.write(`[worker] residency ${notice.kind}: ${notice.message}
 `);
     if (notice.kind === "will-not-fit") {
-      emitEvent({ type: "clio_run_outcome", payload: { outcomeCode: "vram_capacity_fit_failure" } });
+      emitEvent({ type: "clio_coder_run_outcome", payload: { outcomeCode: "vram_capacity_fit_failure" } });
     }
   });
   const demux = createWorkerStdinDemux();
@@ -1988,7 +1993,7 @@ async function main() {
   demux.onSteer(
     createOrderedSteerHandler(
       (text) => handle.steer?.(text) ?? false,
-      ({ text, sequence }) => emitEvent({ type: "clio_steer_received", payload: { chars: text.trim().length, sequence } }),
+      ({ text, sequence }) => emitEvent({ type: "clio_coder_steer_received", payload: { chars: text.trim().length, sequence } }),
       (reason) => process.stderr.write(`[worker] dropped steer: ${reason}
 `)
     )

package/docs/acp.md

@@ -40,7 +40,7 @@ both spellings reach the same command dispatcher, option parser, stdout guard,
 and server boot path.
 
 - `--cwd PATH`: Workspace root the server boots in. The path is resolved and then canonicalized with `fs.realpath`, so a symlinked launch root, a trailing slash, and a `/.` suffix all name the same workspace. Clio changes into that canonical path before it reads settings, builds project context, or opens a session ledger, so a session opens at that root. A path that does not exist or that the process cannot enter exits 2 without starting the server. The canonical path is the server's workspace identity for its whole life: `session/new` must carry a `cwd` that canonicalizes to the same path, and nothing after boot ever changes the process directory.
-- `--permission-timeout MS`: The server-side fail-safe ceiling for one mediated permission request, as a whole number from 1 through Node's maximum schedulable timer delay (`2147483647`) milliseconds. Values outside that range are refused before the protocol server starts. If the timer wins, the approval expires, the active turn is aborted, every parked call for that turn is settled only so execution can unwind, and `session/prompt` fails with `permission_expired`. Expiry is audited as `expired`, never as a human denial, and no denial result is fed into a continuing model loop. The flag overrides `delegation.defaults.permissionTimeoutMs` for this server only, which itself defaults to `DEFAULT_DELEGATION_PERMISSION_TIMEOUT_MS = 120000` (`src/core/defaults.ts:149`). A client may enforce a shorter operator-facing policy by sending ordinary `session/cancel`.
+- `--permission-timeout MS`: The server-side fail-safe ceiling for one mediated permission request, as a whole number from 1 through Node's maximum schedulable timer delay (`2147483647`) milliseconds. Values outside that range are refused before the protocol server starts. If the timer wins, the approval expires, the active turn is aborted, every parked call for that turn is settled only so execution can unwind, and `session/prompt` fails with `permission_expired`. Expiry is audited as `expired`, never as a human denial, and no denial result is fed into a continuing model loop. The flag overrides `delegation.defaults.permissionTimeoutMs` for this server only, which itself defaults to `DEFAULT_DELEGATION_PERMISSION_TIMEOUT_MS = 120000` (`src/core/defaults.ts:149`). The shipped Workbench treats the remaining ACP request window as a hard ceiling on its own approval budget, projects that duration onto the Workbench clock, escalates immediately when the remaining window is shorter than its escalation delay, and cancels without publishing a card if the window has already elapsed. Other clients may enforce a shorter operator-facing policy by sending ordinary `session/cancel`.
 
 Transport frames are JSON-RPC 2.0 messages serialized over `stdin`/`stdout`. All logging and diagnostic output is strictly routed to `stderr` to preserve standard I/O framing integrity.
 

package/docs/built-in-agents.md

@@ -1,9 +1,9 @@
 # Clio Coder Agent Fleet
 
-Clio Coder dispatches focused fleet agents from Markdown recipes. Recipes are data files, not hidden code plugins: YAML frontmatter declares identity, mode, tools, optional target/model hints, and thinking level; the Markdown body is the agent instruction text.
+Clio Coder dispatches focused fleet agents from Markdown recipes. Recipes are data files, not hidden code plugins: YAML frontmatter declares identity, tool requirements, skill bindings, audience, capability and latency classes, budget, and result contract; the Markdown body is the agent instruction text.
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard for the agent registry and dispatch admission check gates is located at [docs/html/agents_blueprint.html](html/agents_blueprint.html) (Version: 0.4.0).
+> **Interactive Spec Available:** An interactive dashboard for the agent registry and dispatch admission check gates is located at [docs/html/agents_blueprint.html](html/agents_blueprint.html) (Version: 0.4.1).
 
 The source of truth is `src/domains/agents/**`. Clio's agent dispatch engine and execution boundaries are built upon the [@earendil-works/pi-agent-core](https://www.npmjs.com/package/@earendil-works/pi-agent-core) library.
 
@@ -47,25 +47,25 @@ 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 | Designs changes across boundaries, contracts, migrations, and validation gates. | `artifact-write` | `deep` |
-| `coder` | read, write, edit, grep, find, ls, web_fetch, git, verify, code_nav | Implements bounded code changes and behavior-preserving refactors. | `workspace-edit` | `balanced` |
-| `debugger` | read, grep, find, ls, git, verify, code_nav | Diagnoses failing code, tests, or receipts without making edits. | `verification` | `balanced` |
-| `documenter` | read, write, edit, grep, find, ls, git, verify, code_nav, context | Updates developer-facing docs, examples, and operational runbooks. | `workspace-edit` | `balanced` |
-| `git-master` | read, write, edit, context, git, bash, grep, find, ls, code_nav | Executes bounded git operations: history, commits, worktrees, and PR prep. | `workspace-edit` | `balanced` |
-| `tester` | read, write, edit, grep, find, ls, git, verify, code_nav | Adds focused deterministic tests for regressions and missing coverage. | `workspace-edit` | `balanced` |
-| `verifier` | read, grep, find, ls, git, verify, code_nav | Independently runs and reports test, lint, build, review, and release gates. | `verification` | `fast` |
-| `wiki-writer` | read, write, edit, grep, find, ls, code_nav, context | Plans one repository wiki, or researches and writes one wiki page. | `workspace-edit` | `balanced` |
+| `architect` | read, grep, find, ls, code_nav, git, artifact, context, ledger | Designs changes across boundaries, contracts, migrations, and validation gates. | `artifact-write` | `deep` |
+| `coder` | read, write, edit, grep, find, ls, web_fetch, git, bash, verify, code_nav, ledger | Implements bounded code changes and behavior-preserving refactors. | `workspace-edit` | `balanced` |
+| `debugger` | read, grep, find, ls, git, verify, code_nav, ledger | Diagnoses failing code, tests, or receipts without making edits. | `verification` | `balanced` |
+| `documenter` | read, write, edit, grep, find, ls, git, verify, code_nav, context, ledger | Updates developer-facing docs, examples, and operational runbooks. | `workspace-edit` | `balanced` |
+| `git-master` | read, write, edit, context, git, bash, grep, find, ls, code_nav, ledger | Executes bounded git operations: history, commits, worktrees, and PR prep. | `workspace-edit` | `balanced` |
+| `tester` | read, write, edit, grep, find, ls, git, verify, code_nav, ledger | Adds focused deterministic tests for regressions and missing coverage. | `workspace-edit` | `balanced` |
+| `verifier` | read, grep, find, ls, git, verify, code_nav, ledger | Independently runs and reports test, lint, build, review, and release gates. | `verification` | `fast` |
+| `wiki-writer` | read, write, edit, grep, find, ls, code_nav, context, ledger | Plans one repository wiki, or researches and writes one wiki page. | `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` and in a separate section of the prompt catalog).
 
 | Agent ID | Primary tools | Purpose | Capability | Latency |
 | --- | --- | --- | --- | --- |
-| `scout` | read, grep, find, ls, context, code_nav, git | Broad repository reconnaissance, codebase orientation, structure and entry-point mapping, and multi-file symbol hunting. | `read-only` | `fast` |
-| `researcher` | read, web_fetch, context | Shadow docs and external-source researcher for coding decisions. | `read-only` | `deep` |
-| `provenance` | read, grep, find, ls, git | Shadow evidence, receipt, diff, and telemetry reader for handoffs. | `read-only` | `balanced` |
-| `oracle` | read, grep, find, ls, code_nav, context | 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` |
+| `scout` | read, grep, find, ls, context, code_nav, git, ledger | Broad repository reconnaissance, codebase orientation, structure and entry-point mapping, and multi-file symbol hunting. | `read-only` | `fast` |
+| `researcher` | read, web_fetch, context, ledger | Shadow docs and external-source researcher for coding decisions. | `read-only` | `deep` |
+| `provenance` | read, grep, find, ls, git, ledger | Shadow evidence, receipt, diff, and telemetry reader for 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, ledger | Internal agent behind `clio-coder context init` that parses repository and returns CLIO-CODER.md payload. | `read-only` | `balanced` |
 
 The builtin `architect` also serves as the default author for a version 5 fleet `plan` step. In that role it returns the coordinator-owned `delegation-plan` result shape instead of writing its ordinary plan artifact. It may name only agents from the contract roster. The coordinator supplies the plan step's target or profile to every admitted task.
 
@@ -106,26 +106,34 @@ Two rounds only help when the reason is actionable, so a validator reason names
 
 ```yaml
 ---
-name: Coder                       # string; defaults to recipe id when absent
-description: Bounded code changes # string; defaults to empty string
-tools: [read, edit, verify]      # string array; filtered by target capabilities and dispatch admission
-model: null                       # string only when set; null is ignored
-target: null                      # string only when set; target hint
-thinkingLevel: off                # off | minimal | low | medium | high | xhigh
-category: implement               # explore | plan | research | implement | quality | science | evolution | operations | internal
-capabilityClass: workspace-edit    # read-only | artifact-write | workspace-edit | verification | orchestration | internal
-latencyClass: balanced             # fast | balanced | deep
-tags: [implementation, repair]    # short lowercase routing hints for catalog display
-skills: []                        # knowledge attachments; requiring the context tool, never expands tool authority
-output: null                      # optional expected artifact name (e.g. PLAN.md)
-budget:                           # optional strict worker-loop phase policy
-  toolCalls: 50                   # admitted calls before final response handling
-  readReserve: 5                  # final admitted slots reserved for canonical read
-  synthesis: true                 # true: text-only final round; false: stop immediately
+version: 1                            # recipe schema version
+name: Coder                           # string; defaults to recipe id when absent
+description: Bounded code changes     # string; defaults to empty string
+tools:                                # required/optional tool mapping, not a flat list
+  required: [read, {anyOf: [write, edit]}, context]   # anyOf: at least one must admit
+  optional: [grep, git, verify, bash, ledger]         # attached when the target carries them
+skills: [fix-issue, ship]             # knowledge attachments; require the context tool, never expand tool authority
+audience: base                        # base | shadow | internal
+category: implement                   # explore | plan | research | implement | quality | science | evolution | operations | internal
+capabilityClass: workspace-edit       # read-only | artifact-write | workspace-edit | verification | orchestration | internal
+latencyClass: balanced                # fast | balanced | deep
+projectContextTier: bounded           # how much project context the worker is briefed with
+tags: [implementation, repair]        # short lowercase routing hints for catalog display
+budget:                               # optional strict worker-loop phase policy
+  toolCalls: 50                       # admitted calls before final response handling
+  readReserve: 5                      # final admitted slots reserved for canonical read
+  synthesis: true                     # true: text-only final round; false: stop immediately
+  # maximum: {toolCalls: 150, readReserve: 16}   # optional hard ceiling (architect ships one)
+resultContract: {kind: mutation-report}  # typed result shape the worker must return
 ---
 ```
 
-A custom source recipe may omit `budget`; admission then materializes a concrete WorkerSpec v3 budget from the operator's current `guardrails.workerToolCallCap`. Built-in recipes declare the field and fail startup if their strict frontmatter is malformed. When a source recipe includes `budget`, it must be a non-null YAML object containing exactly `toolCalls`, `readReserve`, and `synthesis`: the numeric fields must be safe integers, `toolCalls > 0`, and `0 <= readReserve < toolCalls`; `synthesis` must be a boolean. Unknown, missing, quoted-numeric, floating-point, null, and relationally invalid values reject the recipe with its source path and property. Scout declares `18/4/true`; Coder declares `50/5/true`. The model-visible catalog shows declared policy or `operator-default`, never a mutable effective cap.
+The closed key set is defined in `src/domains/agents/recipe-schema.ts`; an
+optional `product` key also exists for product-scoped recipes. There are no
+`model`, `target`, `thinkingLevel`, or `output` frontmatter keys — target and
+model selection belong to dispatch, not the recipe.
+
+A custom source recipe may omit `budget`; admission then materializes a concrete WorkerSpec v3 budget from the operator's current `guardrails.workerToolCallCap`. Built-in recipes declare the field and fail startup if their strict frontmatter is malformed. When a source recipe includes `budget`, it must be a non-null YAML object containing `toolCalls`, `readReserve`, and `synthesis` (plus an optional `maximum` ceiling object, e.g. architect's `maximum: {toolCalls: 150, readReserve: 16}`): the numeric fields must be safe integers, `toolCalls > 0`, and `0 <= readReserve < toolCalls`; `synthesis` must be a boolean. Unknown, missing, quoted-numeric, floating-point, null, and relationally invalid values reject the recipe with its source path and property. Scout declares `18/4/true`; Coder declares `50/5/true`. The model-visible catalog shows declared policy or `operator-default`, never a mutable effective cap.
 
 The operator cap is independent and cannot be widened by a recipe. Dispatch clamps `toolCalls` to that cap and clamps `readReserve` to zero when canonical `read` is absent after tool admission. Reserve slots admit only `read`, not every read-class tool. Blocked non-read attempts do not consume admitted reserve slots, but they still count toward the operator attempt ceiling.
 

package/docs/commands-and-modes.md

@@ -26,7 +26,7 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `clio-coder --no-context-files` / `clio-coder -nc` | Skip `CLIO-CODER.md` project-context injection for one invocation. |
 | `clio-coder --no-skills` | Disable skill discovery for one invocation while still honoring explicit `--skill` paths. |
 | `clio-coder --skill <path>` | Load one explicit skill file or directory for one invocation (repeatable). |
-| `clio-coder configure` | Run the configuration wizard. |
+| `clio-coder configure` | Run the configuration wizard. Ctrl+C reports `configuration cancelled`, writes no target, and exits 130; when first-run onboarding is cancelled, startup stops instead of opening the TUI with no usable target. |
 | `clio-coder configure --interop` | Review other coding agents detected on this machine and connect one as a delegation peer. Without a TTY it prints the proposals and writes nothing. |
 | `clio-coder configure --list` | List user-facing runtime ids. |
 | `clio-coder configure --list --all` | List every registered runtime, including aliases. |
@@ -45,7 +45,7 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `clio-coder auth status [target-or-runtime]` | Inspect auth state. |
 | `clio-coder auth login [target-or-runtime] [--api-key <value>]` | Add credentials through the supported flow. |
 | `clio-coder auth logout [target-or-runtime]` | Remove stored credentials. |
-| `clio-coder doctor [--fix] [--json]` | Diagnose state; with `--fix`, create missing structure and templates, repair credential permissions, and refresh install metadata. Settings remain strict and are not migrated. |
+| `clio-coder doctor [--fix] [--json]` | Diagnose state. Plain `doctor` is read-only and leaves even a partially initialized home byte-for-byte untouched. With `--fix`, create missing structure and templates, repair credential permissions, and refresh install metadata. Settings remain strict; lifecycle migrations belong to `upgrade`, not `doctor --fix`. |
 | `clio-coder tools list [--json]` | List the pinned external tool registry and whether each program resolves from `PATH`, Clio's vendored data directory, or nowhere. |
 | `clio-coder tools status <id> [--json] [--reset-profile]` | Inspect one registered tool. `--reset-profile` applies only to yazi's generated profile. |
 | `clio-coder tools install <id> [--force] [--json]` | Download the platform asset, verify every declared checksum, and atomically vendor it. |
@@ -56,7 +56,7 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `clio-coder upgrade [--dry-run] [--channel=<latest\|beta\|dev>] [--skip-migrations]` | Refresh state metadata, apply migrations, and update npm installs when applicable. |
 | `clio-coder agents [--json] [--all]` | List discovered agent specs. |
 | `clio-coder fleet list\|run\|status\|drain\|resume` | List fleet contracts, run one, show dispatch state, or control admission. `drain` denies new execution starts for up to one hour and preserves running work; `resume` reopens admission immediately. `run <name>` takes `[--var k=v ...]` and `[--json]`; `status`, `drain`, and `resume` each take `[--json]`. |
-| `clio-coder fleet view <runId\|fleetRootId> [--follow]` | Read the append-only run journal after verifying receipt trust. A fleet root prints its durable step index. `--follow` requires an interactive terminal and one run id. |
+| `clio-coder fleet view <runId\|fleetRootId> [--follow]` | Read the append-only run journal after verifying receipt trust. A fleet root prints its durable step index. Without `--follow`, the width-bounded snapshot is plain text with no ANSI control bytes. `--follow` requires an interactive terminal and one run id; `fleet view --help` prints this subcommand's own usage, including `--watch`. |
 | `clio-coder fleet view --watch <selection-file>` | Follow the run id currently named by the selection file and retarget when it changes. This is the operator-pulled watch surface used by the pane integration. |
 | `clio-coder dev components [list] [--json]` | List behavior-affecting harness components. |
 | `clio-coder dev components snapshot --out <path>` | Write a component snapshot JSON file. |
@@ -65,9 +65,11 @@ For process exit codes, stdout deliverable guarantees, and machine-readable JSON
 | `clio-coder eval validate\|run\|report\|compare\|gate` | Validate, run, report, compare, and gate local evaluation suites (Suite v2). |
 | `clio-coder memory list\|propose\|promote\|approve\|reject\|prune` | Manage scoped, evidence-linked memory records. |
 | `clio-coder trace runs [--db PATH] [--limit N] [--json]` | List runs recorded in the durable trace mirror beside the ledger. |
+| `clio-coder trace inspect --json` | Emit the fixed, bounded recent accounting projection used by the Workbench. It accepts no path, identifier, or limit and omits request text, error prose, event payloads, process commands, PIDs, and hosts. |
 | `clio-coder trace phases <runId> [--db PATH]` | Show one run's recorded phases. |
 | `clio-coder trace tail <runId> [--follow] [--db PATH]` | Tail one run's recorded events; `--follow` streams as they land. |
 | `clio-coder trace procs <runId> [--db PATH]` | Show the processes one run spawned. |
+| `clio-coder trace prune [--max-age-days N] [--max-bytes N] [--db PATH] [--json]` | Apply the trace-retention policy while protecting queued and running runs; JSON reports the resolved policy, rows, runs and bytes removed, protected runs, and whether vacuum ran. |
 | `clio-coder trace sql <SELECT query> [--db PATH]` | Run one read-only query against the mirror. Only a single `SELECT` or read-only `WITH` statement is accepted; anything else exits 2. |
 | `clio-coder trace ui [--db PATH] [--port N]` | Serve the localhost-only waterfall viewer. The viewer is not part of the published package. |
 | `clio-coder dev evolve manifest init\|validate\|summarize` | Create and check typed harness change manifests. |
@@ -121,6 +123,10 @@ pings it before registering pane tools. The fleet watch pane runs
 `fleet view --watch` against a selection file. Clio writes only the selected run
 id, while the viewer reads journals itself, so dispatch remains independent of
 the pane host and a second terminal can use the same journal surface directly.
+`panes.enabled: embedded` does not start a host: it is an accepted but
+unimplemented rung that resolves to no panes, prints a refusal during boot, and
+is labelled `NOT IMPLEMENTED` in Settings. Use `auto` or `--with-panes` only
+when Clio is already inside a reachable herdr session.
 
 ### Headless Session Continuity
 

package/docs/config-knobs-audit.md

@@ -8,6 +8,9 @@
 > It details the pre-consolidation state of the codebase before the `v0.2.9` release.
 > For the current, active, and authoritative reference of environment variables, please refer to [environment-variables.md](environment-variables.md).
 
+> [!NOTE]
+> Pane settings were introduced after this audit and are intentionally absent from its tables. In the current schema, `panes.agents` and `panes.keepFailed` are retired and refused when newly authored; `clio-coder upgrade` removes them from an older settings file before strict validation. See [configuration-and-targets.md](configuration-and-targets.md) for the active pane keys and their migration behavior.
+
 ---
 
 Point-in-time inventory of every tunable knob outside `settings.yaml`: environment variables, the compiled-in defaults behind them, and the CLI flags that bridge into them. Gathered 2026-07-03 by sweeping `src/` for `process.env` reads and cross-checking `scripts/`, `benchmarks/`, and `docs/`. Purpose: reason about which knobs earn their keep, which belong in `settings.yaml`, and which are dead.