@iowarp/clio-coder 0.4.9 → 0.5.0

package/dist/workspace-check-3764ZKC2.js

@@ -0,0 +1,83 @@
+import { createRequire as __clioCreateRequire } from "node:module"; const require = __clioCreateRequire(import.meta.url);
+import {
+  canSelect,
+  promptSelect
+} from "./chunk-HSQQFDB3.js";
+import "./chunk-ZIDFQJRB.js";
+import "./chunk-SQZHXUB3.js";
+import {
+  sanitizeCallTargetText
+} from "./chunk-XNIZBOFV.js";
+import "./chunk-EFSEIZE6.js";
+import {
+  init_esm_shims
+} from "./chunk-ECBHH7LU.js";
+
+// src/cli/workspace-check.ts
+init_esm_shims();
+import { realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+function workspaceConcern(cwd, home) {
+  if (cwd === home || ["/home", "/Users"].includes(path.dirname(cwd)) || cwd === "/root") return "home";
+  const under = (root) => cwd === root || cwd.startsWith(`${root}${path.sep}`);
+  if ([path.parse(cwd).root, "/home", "/Users", "/tmp", "/var/tmp", "/opt", "/srv", "/mnt", "/media"].includes(cwd))
+    return "system";
+  if (["/var/tmp", "/var/folders", "/usr/local/src"].some(under)) return null;
+  return [
+    "/etc",
+    "/usr",
+    "/bin",
+    "/sbin",
+    "/lib",
+    "/lib64",
+    "/boot",
+    "/dev",
+    "/proc",
+    "/sys",
+    "/run",
+    "/var",
+    "/System",
+    "/Library"
+  ].some(under) ? "system" : null;
+}
+async function confirmStartupWorkspace(cwd = process.cwd()) {
+  const canonical = realpathSync(cwd);
+  const concern = workspaceConcern(canonical, realpathSync(homedir()));
+  if (concern === null) return true;
+  const heading = [
+    "",
+    "Open this workspace?",
+    "",
+    `  ${sanitizeCallTargetText(canonical)}`,
+    "",
+    concern === "home" ? "This is your home folder. It includes personal files and application settings." : "This is a system or shared folder. Changes here can affect more than one project.",
+    "Clio can read files and, depending on permissions, edit files and run commands.",
+    "Open a project folder instead if you did not intend this scope.",
+    ""
+  ];
+  if (!canSelect()) {
+    process.stderr.write(
+      `${heading.join("\n")}
+Start from a project folder or use a terminal to confirm this workspace.
+`
+    );
+    return false;
+  }
+  const result = await promptSelect({
+    heading,
+    choices: [
+      { value: false, label: "No, exit" },
+      { value: true, label: "Yes, open this folder" }
+    ],
+    initialIndex: 0,
+    backLabel: "cancel",
+    clearOnExit: true
+  });
+  return result.kind === "selected" && result.value;
+}
+export {
+  confirmStartupWorkspace,
+  workspaceConcern
+};
+//# sourceMappingURL=workspace-check-3764ZKC2.js.map

package/docs/README.md

@@ -20,9 +20,19 @@ docs/
 ├── guide/          Operator and user workflows
 ├── architecture/   Runtime contracts and design
 ├── process/        Development, validation, and release practice
+├── gui/            Early GUI preview and browser docs
 └── history/        Dated records that are not current guidance
 ```
 
+For the v0.5.0 launch, Clio Coder is first and foremost a terminal coding agent.
+Browser documentation and workspace inspection are provided via an early GUI
+preview (`clio-coder docs [topic]`, `clio-coder gui [--open]`), explicitly without
+claiming production GUI parity. Start with the [release notes](../CHANGELOG.md),
+[configuration and target guide](guide/configuration-and-targets.md), and
+[pre-release checks](process/release-cut-checklist.md#working-tree-pre-release-checks).
+The current guides describe the working implementation, not a promise that the
+candidate has been published or that every server capability has been tested.
+
 ## Start here
 
 | Goal | Guide |
@@ -31,6 +41,8 @@ docs/
 | Learn the interactive session and CLI | [Commands and Modes](guide/commands-and-modes.md) |
 | Understand what Clio may read, change, or execute | [Safety Model](architecture/safety-model.md) |
 | Diagnose a problem by its exact message | [Troubleshooting](guide/troubleshooting.md) |
+| Check an install, its targets, and the HPC toolchain | [Doctor](guide/doctor.md) |
+| Submit, poll, and cancel Slurm jobs through the clio-kit MCP server | [Slurm](guide/slurm.md) |
 
 A minimal first run needs Node.js 22.19 or newer and a model to talk to: a
 local inference server such as Ollama or LM Studio, a lab gateway, or a cloud
@@ -68,6 +80,7 @@ interactive session. `clio-coder doctor` is a read-only installation check;
 | Executable harness capabilities | [Harness Extensions](guide/harness-extensions.md) |
 | TUI layout, responsive behavior, colors, and interaction rules | [TUI Design](architecture/tui-design.md) |
 | Terminal panes beside a session and the files pane: install, keys, settings, doctor, troubleshooting | [Panes and the Files Pane](guide/panes-and-files.md) |
+| Early GUI preview: browser docs, REST routes, boundaries, and parity roadmap | [GUI Reference](gui/README.md) |
 
 ## Safety, evidence, and reproducibility
 
@@ -120,10 +133,7 @@ validation, reference data, or human scientific judgment.
 | Correct render, startup, import-graph, and streaming measurements | [Performance Methodology](process/performance-methodology.md) |
 | Falsifiable change manifests and `clio-coder evolve` | [Evolution](process/evolution.md) |
 
-Reviewable reference suites ship under [`evals/`](../evals/). They are explicit
-operator measurements, not hidden CI steps. Private prompts, credentials,
-endpoints, raw campaign artifacts, and proprietary datasets belong outside the
-repository.
+Reviewable reference suites are available in the source checkout under [`evals/`](../evals/) (omitted from the published package tarball). They are explicit operator measurements, not hidden CI steps. Private prompts, credentials, endpoints, raw campaign artifacts, and proprietary datasets belong outside the repository.
 
 ## Architecture and contributing
 
@@ -205,15 +215,21 @@ root**, which is that directory's parent. So when the prompt names `/pkg/docs`:
 Do not duplicate the `docs/` segment, and do not resolve a citation against the
 workspace. Omitting `query` lists the corpus instead of searching it.
 
-**The web documentation.** `clio-coder docs` opens the documentation map in the
-Clio Coder web app. `clio-coder docs safety` opens the safety guide. It resolves
-content from the installed package, independent of your current project, and
-reuses this installation's background app when configured. Otherwise it starts
-a foreground loopback server; press Ctrl+C to stop. `--no-open` prints the private
-launch link without opening a browser. The command never installs a service.
+**The web documentation.** `clio-coder docs` opens the documentation map in your
+browser, and `clio-coder docs safety` opens the safety guide. It resolves content
+from the installed package, independent of your current project. If you installed
+the background app, it uses that. Otherwise it starts a loopback server that keeps
+running after the command returns, so the terminal is free, and reuses that server
+on the next call. The server stops on `clio-coder docs --stop`, or by itself 15
+minutes after the last page closes. `--no-open` prints the private launch link
+without opening a browser, and `--foreground` serves privately in the terminal
+until Ctrl+C. The command never installs a service.
 
 ## Reading in the application
 
+Clio Coder is designed primarily as a terminal coding agent; the bundled web
+application is an early preview for browsing documentation, reviewing sessions,
+and inspecting workspace telemetry, rather than claiming production GUI parity.
 The GUI renders these Markdown sources directly with the application's theme,
 syntax highlighting, copy controls, tables and diagrams. Navigation groups come
 from this map, search indexes the same pages, and each page's outline is generated

package/docs/architecture/acp.md

@@ -11,10 +11,9 @@ Source implementations: `src/engine/acp/` and `src/cli/acp.ts`.
 Clio Coder provides a native ACP server via the `clio-coder acp` command. The server implements the open Agent Client Protocol specification (ACP v1 / schema 0.4.5) over standard I/O JSON-RPC 2.0 transport (`src/engine/acp/transport.ts`).
 
 The ACP server allows external IDEs, editors (such as Zed), and automated orchestration engines to drive Clio Coder sessions over a structured protocol.
-The source tree includes the `apps/clio-coder-web` application, which supervises
+The source tree includes the `apps/clio-coder-gui` application, which supervises
 ACP children and exposes session operations through authenticated local REST and
-SSE. The earlier `apps/workbench` client is retained as reference source and is
-excluded from workspace builds, publication, and product gates.
+SSE.
 
 ```mermaid
 graph LR
@@ -39,7 +38,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 `integrations.externalAgents.defaults.permissionTimeoutMs` for this server only, which itself defaults to `DEFAULT_DELEGATION_PERMISSION_TIMEOUT_MS = 120000` (`src/core/defaults.ts:290`). The source-checkout 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`.
+- `--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 `integrations.externalAgents.defaults.permissionTimeoutMs` for this server only, which itself defaults to `DEFAULT_DELEGATION_PERMISSION_TIMEOUT_MS = 120000` (`src/core/defaults.ts:290`). The graphical application treats the remaining ACP request window as a hard ceiling on its own approval budget, projects that duration onto its own 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.
 
@@ -65,8 +64,15 @@ These are every method the server answers (`src/engine/acp/server.ts`). Anything
 | `clio-coder/settings/patch_safe` | Client → Server | Atomically validates, persists, and applies a flat patch over the closed safe setting set. Refused during a prompt. |
 | `clio-coder/targets/list` | Client → Server | Lists bounded, credential-free target/model summaries from configuration and the in-memory cache without network traffic. |
 | `clio-coder/targets/probe` | Client → Server | Explicitly probes one configured target through the provider domain and returns only a closed health result. |
+| `clio-coder/session/steer` | Client → Server | Queues operator guidance on the running turn, on the steering queue (`next-slot`) or the follow-up queue (`end-of-turn`). Reports a refusal rather than a silent success when nothing is streaming. |
+| `clio-coder/session/queue` | Client → Server | Reads both queues in enqueue order. |
+| `clio-coder/session/queue_clear` | Client → Server | Drains both queues together and returns the texts, which become the client's to re-send. |
+| `clio-coder/session/interrupt` | Client → Server | Cancels the running turn, or reports why it cannot be. Cancel only: the outstanding `session/prompt` settles with `cancelled` and the next prompt is the client's to send. |
+| `clio-coder/dispatch/steer` | Client → Server | Queues guidance on, or aborts, one running worker by `runId`. Acceptance means queued on the worker's stdin, never delivered. |
+| `clio-coder/commands/list` | Client → Server | Returns the catalog of exposed operator commands with the grammar a palette builds its argument UI from. |
+| `clio-coder/commands/invoke` | Client → Server | Runs one exposed operator command headlessly and returns its notice level and output lines. |
 | `session/request_permission` | Server → Client | Requests permission from the client for a gated tool operation. |
-| `clio-coder/event` | Server → Client | Sends a versioned extension event only to a client that opted into a recognized kind. The v1 allowlist is `safety.loopBlocked` plus `dispatch.enqueued`, `dispatch.started`, `dispatch.progress`, `dispatch.completed`, `dispatch.failed`, and `accountability.evidenceReady`. |
+| `clio-coder/event` | Server → Client | Sends a versioned extension event only to a client that opted into a recognized kind. The v1 allowlist is `safety.loopBlocked`, `dispatch.enqueued`, `dispatch.started`, `dispatch.progress`, `dispatch.completed`, `dispatch.failed`, `accountability.evidenceReady`, `compaction.end`, `context.warning`, `safety.toolBudgetExceeded`, and `provider.health`. Every kind is the engine's own `BusChannels` value, never a renamed alias, so a captured frame names its producer. |
 
 `agentCapabilities.loadSession` is `true`. All non-standard methods are advertised only under `agentCapabilities._meta`; a strict generic ACP v1 client sees the standard new/load/prompt/cancel/permission surface, ignores namespaced result metadata, and receives no non-standard notification unless it explicitly opts into a recognized event kind.
 
@@ -161,7 +167,67 @@ The values above are illustrative. Thinking is one of `off`, `minimal`, `low`, `
 
 A client opts into the first extension event with `initialize.params.clientCapabilities._meta["clio-coder/events"]={version:1,kinds:["safety.loopBlocked"]}`. The kinds array has at most 16 strings, each at most 64 UTF-8 bytes and C0/DEL-free; a malformed opt-in is ignored. Unknown bounded versions and kinds are ignored. Without a recognized opt-in, no `clio-coder/event` notification is sent.
 
-The v1 notification is `{version,workspaceInstanceId,sessionId,turnId,sequence,kind,terminal,payload}`. `workspaceInstanceId` is one opaque process UUID advertised at initialize, and `sequence` increases monotonically within it. Recognized kinds are `safety.loopBlocked`, `dispatch.enqueued`, `dispatch.started`, `dispatch.progress`, `dispatch.completed`, `dispatch.failed`, and `accountability.evidenceReady`. A loop-blocked event is emitted only during the hosted active prompt and has `terminal:false`. Its payload is `{toolCallId:null,tool,repeatCount,blocksThisTurn,budget,disposition,interrupted,shape:null}`. Disposition is `block`, `lockout`, or `stop`, and `interrupted` is true exactly for `stop`. The detector fires before the blocked call executes, so no honest ACP tool-call id exists; the bus has no disclosure-safe normalized shape. Both fields therefore remain null rather than being fabricated. Dispatch events carry bounded run and agent identity plus the small lifecycle counters or terminal taxonomy appropriate to their kind; completed and failed events set `terminal:true`. Enqueued and started events may include `taskPreview`, a control-character-stripped prefix bounded to 160 UTF-8 bytes. The exact task and raw progress or failure prose never cross this boundary. An `accountability.evidenceReady` event follows the terminal event of a run whose evidence bundle has landed and sets `terminal:true`. Its payload is `{runId,evidenceId,firstPassSuccess,findingCount,tags}`, the same summary the observability projection attaches to the run, published once by the observability extension on the `accountability.evidenceReady` bus channel. Tags are at most 32 bounded identifiers of at most 64 bytes; the bundle's findings and overview prose never cross. A run whose build failed sends nothing, so the absence of the event means only that no bundle is ready.
+The v1 notification is
+`{version,workspaceInstanceId,sessionId,turnId,sequence,kind,terminal,payload}`.
+`workspaceInstanceId` is one opaque process UUID advertised at initialize, and
+`sequence` increases monotonically within it.
+
+| Kind | Payload | `terminal` |
+| --- | --- | --- |
+| `safety.loopBlocked` | `{toolCallId:null,tool,repeatCount,blocksThisTurn,budget,disposition,interrupted,shape:null}`. Disposition is `block`, `lockout`, or `stop`. | `false` |
+| `dispatch.enqueued`, `dispatch.started` | Bounded run and agent identity, optionally with `taskPreview`. | `false` |
+| `dispatch.progress` | Bounded run and agent identity plus lifecycle counters. | `false` |
+| `dispatch.completed`, `dispatch.failed` | Bounded run and agent identity plus terminal taxonomy. | `true` |
+| `accountability.evidenceReady` | `{runId,evidenceId,firstPassSuccess,findingCount,tags}`. | `true` |
+| `compaction.end` | `{trigger}`, the bounded identifier naming why the window was cut. | `false` |
+| `context.warning` | Always the object `{warning}`, where `warning` is a control-character-stripped sentence bounded to 256 UTF-8 bytes, or `null`. The clearing edge is `{warning: null}`, never a null payload. | `false` |
+| `safety.toolBudgetExceeded` | `{tool,callsThisTurn,softBudget,hardCeiling,interrupted}`. | `true` exactly when `interrupted` |
+| `provider.health` | `{targetId,status,available,latencyMs}`, where status is exactly `healthy`, `degraded`, `unknown`, or `down`. | `false` |
+
+An event whose identity or taxonomy cannot be represented safely is dropped
+rather than forwarded under a repaired one.
+
+<details>
+<summary>What each kind deliberately leaves behind, and why two loop-block fields are null</summary>
+
+`safety.loopBlocked` is emitted only during the hosted active prompt, and its
+`interrupted` is true exactly for a `stop` disposition. `safety.toolBudgetExceeded`
+has no disposition; its `interrupted` is the bus payload's own flag. The loop detector fires before the
+blocked call executes, so no honest ACP tool-call id exists, and the bus has no
+disclosure-safe normalized shape; both fields stay null rather than being
+fabricated.
+
+`taskPreview` on enqueued and started events is a control-character-stripped
+prefix bounded to 160 UTF-8 bytes. The exact task and raw progress or failure
+prose never cross this boundary.
+
+`accountability.evidenceReady` follows the terminal event of a run whose evidence
+bundle has landed, carrying the same summary the observability projection
+attaches to the run, published once by the observability extension on the
+`accountability.evidenceReady` bus channel. Tags are at most 32 bounded
+identifiers of at most 64 bytes; the bundle's findings and overview prose never
+cross. A run whose build failed sends nothing, so the absence of the event means
+only that no bundle is ready.
+
+`safety.toolBudgetExceeded` is emitted only during the hosted active prompt,
+because the budget it names is per-turn.
+
+`compaction.end` does not carry the producer's `at` timestamp, because a client
+re-stamps on arrival.
+
+`context.warning` is a transition-only channel, so `{warning: null}` is the
+clearing edge and crosses as itself. Dropping it would leave a client's banner up
+forever.
+
+`provider.health` leaves `lastError` behind: it is provider prose that
+legitimately quotes URLs and response bodies, the same way `dispatch.failed`'s
+`outcomeDetail` does.
+
+The last four kinds describe the session rather than the fleet, and close the
+context-meter, footer-status, and retry-visibility parity rows a client would
+otherwise have to infer from timing and tool titles.
+
+</details>
 
 ### Prompt input
 
@@ -174,19 +240,114 @@ Every frame the server writes is bounded (`src/engine/acp/types.ts`). Every cap
 - `agent_message_chunk` and `agent_thought_chunk` text is at most 16 KiB per chunk. A longer delta is split across consecutive chunks and nothing is dropped, so concatenating chunks in order reproduces the model's text exactly. No split falls inside a code point, so a surrogate pair never arrives as two replacement characters.
 - Tool `content` text is truncated at 16 KiB with a trailing `…[truncated]`.
 - Live tool titles are at most 512 UTF-8 bytes. The bound applies identically to `tool_call`, `tool_call_update`, and `session/request_permission`; replay titles retain their stricter 64-byte stored-data bound.
-- Every string inside `rawInput` and `rawOutput` is truncated at 4 KiB with the same marker, and the walk stops at depth 8, replacing anything deeper with `"[depth]"`. The marker is reserved inside the cap, so a truncated value is at most the cap itself. If the bounded record still serializes past 32 KiB of UTF-8 it becomes `{"truncated":true,"bytes":<serialized UTF-8 length>}`, where the length is the record's serialization before any bounding, so the figure names the payload the engine produced rather than the shortened copy that was not sent. A record that does not serialize at all reports the bounded copy's length, or `0` when neither form serializes.
+- Tool progress is off unless the client opts in, and bounded three ways when it is on: at most 64 non-terminal `tool_call_update` frames per `toolCallId` per turn, at least 250 ms between two frames for one id, and a snapshot byte-identical to the previous one for that id is never re-sent. Each frame's text is the tool's cumulative output, bounded to 16 KiB with the standard marker, so a client replaces the row's content rather than appending. A frame naming a `toolCallId` with no open call is dropped, never minted, and the terminal update still arrives exactly once, last.
+- Every string inside `rawInput` and `rawOutput` is truncated at 4 KiB with the same marker, with one path-aware exception: `rawOutput.result.details.diff` is bounded at 28 KiB, `ACP_MAX_RAW_RECORD_BYTES` minus one generic string budget reserved for the rest of the record. At 4 KiB a multi-hunk refactor stopped mid-hunk; at the full record cap a large diff would have tripped the record cap and degraded the whole record to `{truncated:true}`, which is worse than the bug. A top-level `diff`, an array member, and every sibling string stay at 4 KiB. The walk stops at depth 8, replacing anything deeper with `"[depth]"`. The marker is reserved inside the cap, so a truncated value is at most the cap itself. If the bounded record still serializes past 32 KiB of UTF-8 it becomes `{"truncated":true,"bytes":<serialized UTF-8 length>}`, where the length is the record's serialization before any bounding, so the figure names the payload the engine produced rather than the shortened copy that was not sent. A record that does not serialize at all reports the bounded copy's length, or `0` when neither form serializes.
 - Every `toolCallId` is at most 128 UTF-8 bytes. An engine id longer than that, a missing one, or one that collides with an alias this turn already minted is replaced by a per-turn `clio-coder-tool-<n>` alias, and the same alias is used for the call's `tool_call`, its `tool_call_update`, and its permission request, so one call never splits into two identities on the client. Identity runs one way: each engine tool-call id maps to exactly one emitted call. A turn that starts a second call under an engine id it already used mints a fresh alias for it rather than reusing the earlier wire id, so two calls never merge into one, and a `tool_execution_end` closes that id's most recently opened call first. An end that names an engine id is confined to that engine id's own calls: an id this turn never started binds to nothing, and the end is dropped and reported on the stderr tail rather than borrowing another call's wire id, which reported one tool's result under another tool's identity and closed a call that was still running. Every wire id receives exactly one terminal update. Once a `tool_call_update` with `completed` or `failed` has gone out for an id, the cancel/fail sweep included, that id never receives another, and a late or duplicate end for it is dropped and reported on the stderr tail instead of overwriting the result the client already rendered. An end arriving with no engine id binds to the most recently opened call still running, which is what makes a nested lifecycle close correctly: with an outer and an inner call open and the inner one already ended, the next unidentified end is the outer call's. With nothing still open it binds to the most recently emitted call of the turn, which drops it when that call is already terminal, and an end arriving before the turn has emitted any `tool_call` is dropped outright. Nothing on the end path mints a wire id, so a `tool_call_update` never announces an id the client never saw start.
 - `locations` carries the absolute path for the built-in path-bearing tools (`read`, `write`, `edit`, `ls`, `grep`, `find`) when the arguments name one, resolved against the pinned workspace and deliberately not realpath'ed, since an `edit` or `write` target may not exist yet. Each emitted path is at most 4 KiB of UTF-8, with `…[truncated]` inside that budget when the resolved value is longer. The exact bounded snapshot is reused by `session/request_permission`. When there is no recognizable path the field is omitted entirely rather than sent as `null` or `[]`.
 - A live prompt emits at most 128 `tool_call` starts. On the next start the server emits no 129th call, cancels the underlying Clio turn, suppresses subsequent chat events, terminally fails every already-rendered open call, and resolves `session/prompt` with standard stop reason `max_turn_requests`. This stop reason is emitted by the ACP bridge only for that presentation ceiling; Clio's separate configurable execution guard remains an engine policy rather than a wire-cardinality promise.
 - A cancelled or failed turn synthesizes a `tool_call_update` with `status: "failed"` for every call that received a `tool_call` and no terminal update, before the prompt request settles.
+- Steer text is at most 16 KiB and must be non-blank. `\n`, `\r`, and `\t` are content; every other C0 control is refused rather than stripped, because a steer the model saw rewritten would disagree with the copy the client's own UI is showing. An interrupt `reason` is at most 256 bytes and control-character-free. Each queue returns at most 64 entries, each bounded to 16 KiB with the standard marker. A `runId` for dispatch steering is at most 128 bytes.
+- One `clio-coder/commands/invoke` returns at most 200 lines of at most 1 KiB each, with a trailing `…output truncated at 200 lines` when capped. `argv` is at most 32 elements of at most 4 KiB; elements are joined with single spaces and never quoted, so a quote character, a control character, and whitespace in any element that is not the last are all refused rather than escaped. A rest positional is taken verbatim to end of line, and a client cannot tell from the catalog which of its arguments lands in a rest slot.
 
 ### Admission failure
 
-A prompt Clio cannot start fails with `prompt_not_admitted` and zero preceding `session/update` notifications. `data.reason` is one of `orchestrator-not-configured`, `target-unknown`, `target-not-configured`, `target-not-found`, `runtime-not-registered`, `model-not-configured`, `chat-unsupported`, `streaming-unsupported`, `authentication-required`, or the catch-all `admission-failed`. That list is closed and the server enforces it: the engine's runtime-resolution diagnostics are a larger and faster-moving vocabulary (`runtime-target-unsupported`, `runtime-use-unsupported`, `required-capability-missing`, and others), and any reason outside the list is reported as `admission-failed` rather than teaching clients a code the profile never promised. The two halves of an unconfigured orchestrator are distinguished: no `chat.target` reports `orchestrator-not-configured`, and a configured target with no `chat.model` reports `model-not-configured`, so a client is pointed at the half of the settings that is actually missing. The message is a sanitized one-line sentence and never contains the settings path. A failure after admission fails with `turn_failed` instead. The server checks credential availability through the provider auth contract before admitting a prompt; `authentication-required` carries no environment-variable name, credential, or provider prose. A background service does not inherit terminal-only API keys: save the key with `clio-coder auth login <target>`, then close and reopen the session. Other readiness checks before the first prompt live in the CLI: `paths --json` for home identity, `doctor --json` for installation sanity, and `targets --json [--probe]` for target, auth, and health. `--probe` performs a request to the configured endpoint, so the client decides when that is allowed.
+A prompt Clio cannot start fails with `prompt_not_admitted` and zero preceding
+`session/update` notifications. `data.reason` is one of a closed list:
+`orchestrator-not-configured`, `target-unknown`, `target-not-configured`,
+`target-not-found`, `runtime-not-registered`, `model-not-configured`,
+`chat-unsupported`, `streaming-unsupported`, `authentication-required`, or the
+catch-all `admission-failed`. A failure after admission fails with `turn_failed`
+instead.
+
+The server enforces that list. The engine's runtime-resolution diagnostics are a
+larger and faster-moving vocabulary (`runtime-target-unsupported`,
+`runtime-use-unsupported`, `required-capability-missing`, and others), and any
+reason outside the list is reported as `admission-failed` rather than teaching
+clients a code the profile never promised.
+
+The two halves of an unconfigured orchestrator are distinguished: no
+`chat.target` reports `orchestrator-not-configured`, and a configured target with
+no `chat.model` reports `model-not-configured`, so a client is pointed at the
+half of the settings that is actually missing. The message is a sanitized
+one-line sentence and never contains the settings path, and
+`authentication-required` carries no environment-variable name, credential, or
+provider prose.
+
+The server checks credential availability through the provider auth contract
+before admitting a prompt. A background service does not inherit terminal-only
+API keys: save the key with `clio-coder auth login <target>`, then close and
+reopen the session.
+
+Other readiness checks before the first prompt live in the CLI: `paths --json`
+for home identity, `doctor --json` for installation sanity, and
+`targets --json [--probe]` for target, auth, and health. `--probe` performs a
+request to the configured endpoint, so the client decides when that is allowed.
 
 ### Permission requests
 
-The outbound `session/request_permission` carries `{sessionId, toolCall:{sessionUpdate:"tool_call", toolCallId, title, kind, status:"pending", rawInput, locations?}, options}`. `toolCallId` is always the id of a `tool_call` the client already rendered and has not yet seen finish. Binding is lookup-only. When the engine supplies an id, it resolves through the calls this turn actually emitted, and only to one that is still open; when that id has more than one open call, because the engine reused it, the request binds to the most recently opened of them. When the engine supplies no id, the request binds to the turn's one open tool call. Every other case fails closed: an id nothing was emitted for, an id whose calls have all completed, zero open calls, or more than one open call with no id to choose between them. Failing closed means the client is never asked, no `session/request_permission` frame is written, the parked call is cancelled, and the resolution is recorded as denied with `decidedBy: "error"` and the reason `permission request has no bindable tool call`. There is no bridge-local id and no id is minted here: asking about an id the client never received put an approval on a call nobody could identify. `rawInput` and `locations` are the stored snapshot of the bound call's `tool_call` update, replayed byte for byte and never recomputed, so a client can diff the call it is showing against the call it is being asked to approve and find nothing. The snapshot is taken when the `tool_call` is emitted and keyed by wire id, because the registry's copy of a call is not always the engine's: a tool's `prepareAdmissionArguments` may rewrite a relative path to an absolute one or attach a prepared artifact before the safety net sees the call, so deriving the ask from those arguments made the two frames disagree for reasons the client could only read as a mismatch. The tool's name is in `title`, never folded into `rawInput`. Options are exactly `allow-once` and `reject-once`. Only the exact `optionId: "allow-once"` under `outcome: "selected"` grants; every other client answer, including `outcome: "cancelled"`, is a client denial. At most one request is outstanding at a time and the queue is serial. Transport loss denies every queued request and cancels the parked calls. A `session/cancel` while a request is outstanding stops the server waiting on it, cancels the parked tool, and settles the prompt with `stopReason: "cancelled"`; a late answer to the abandoned request is ignored.
+The outbound `session/request_permission` carries
+`{sessionId, toolCall:{sessionUpdate:"tool_call", toolCallId, title, kind, status:"pending", rawInput, locations?}, options}`.
+`toolCallId` is always the id of a `tool_call` the client already rendered and
+has not yet seen finish. The tool's name is in `title`, never folded into
+`rawInput`.
+
+Options are `allow-once`, `reject-once`, and `reject-and-stop`, in that order.
+Only the exact `optionId: "allow-once"` under `outcome: "selected"` grants; every
+other client answer, including `outcome: "cancelled"`, is a client denial.
+`reject-once` denies only the presented request and the turn continues with
+`end_turn`. `reject-and-stop` additionally denies every other parked request from
+the turn and aborts the prompt, which settles with `cancelled`.
+
+<details>
+<summary>How a request binds to a tool call, and what failing closed does</summary>
+
+Binding is lookup-only. No bridge-local id exists and no id is minted here,
+because asking about an id the client never received put an approval on a call
+nobody could identify.
+
+| Engine supplies | Binds to |
+| --- | --- |
+| An id matching one still-open call this turn actually emitted | That call. |
+| An id matching several still-open calls, because the engine reused it | The most recently opened of them. |
+| No id, with exactly one open call this turn | That call. |
+| Anything else: an id nothing was emitted for, an id whose calls have all completed, zero open calls, or several open calls with no id to choose between them | Nothing. It fails closed. |
+
+Failing closed means the client is never asked, no `session/request_permission`
+frame is written, the parked call is cancelled, and the resolution is recorded as
+denied with `decidedBy: "error"` and the reason
+`permission request has no bindable tool call`.
+
+`rawInput` and `locations` are the stored snapshot of the bound call's
+`tool_call` update, replayed byte for byte and never recomputed, so a client can
+diff the call it is showing against the call it is being asked to approve and
+find nothing. The snapshot is taken when the `tool_call` is emitted and keyed by
+wire id, because the registry's copy of a call is not always the engine's: a
+tool's `prepareAdmissionArguments` may rewrite a relative path to an absolute one
+or attach a prepared artifact before the safety net sees the call, so deriving
+the ask from those arguments made the two frames disagree for reasons the client
+could only read as a mismatch.
+
+</details>
+
+`params._meta["clio-coder/decision"]` carries the classification the server
+already computed to pick the option labels:
+`{version:1, tier, tierLabel, title, semanticToken, authorizationCopy, consequenceCopy, reversibilityCopy, requestedByCopy, actionClass, axis, origin, exposure, affectedScope, reversibility, target?}`.
+Without it a client re-derives a tier and a consequence from a tool name, which
+is a second and worse classifier.
+
+`tier` is one of `conversation`, `workspace`, `outward`, `safety-net`, `system`,
+or `worker`. `semanticToken` is `accent`, `action`, or `warning`. `affectedScope`
+and `reversibility` are the machine-readable facts behind the copy, so a client
+colours a badge without string-matching prose. `target` is a one-line allowlisted
+render of the call's arguments and is omitted when nothing is derivable. Every
+string is control-character-stripped and bounded to 512 UTF-8 bytes, and no
+model-authored prose reaches this record.
+
+At most one request is outstanding at a time and the queue is serial. Transport
+loss denies every queued request and cancels the parked calls. A `session/cancel`
+while a request is outstanding stops the server waiting on it, cancels the parked
+tool, and settles the prompt with `stopReason: "cancelled"`; a late answer to the
+abandoned request is ignored.
 
 The server timeout is different from a client answer. When `--permission-timeout` wins, every permission still parked for the active turn is internally resolved as `expired`, the registry calls are cancelled only to unwind execution, the chat loop is aborted, any later ordinary tool/message events from that unwind are suppressed, and `session/prompt` fails with `permission_expired`. The client therefore never sees a fabricated human denial or model prose reacting to it. A literal `reject-once` remains an ordinary client denial and may be observed by the model as the tool result.
 
@@ -205,7 +366,13 @@ The shipped `clio-coder acp` composition supplies the session, settings, provide
 | `clio-coder/targets` | `initialize` → `agentCapabilities._meta` | `{ list:true, probe:true }` |
 | `clio-coder/agent` | `initialize` → `agentCapabilities._meta` | `{ version:1, meta:"clio-coder/agent" }`, advertising per-frame agent attribution. |
 | `clio-coder/agent` | live and replayed `session/update.params._meta` | An array beginning with orchestrator attribution and including bounded delegated-agent attribution for a tool call when available. |
-| `clio-coder/events` | `initialize` → `agentCapabilities._meta` | `{ version:1, notification:"clio-coder/event", kinds:["safety.loopBlocked","dispatch.enqueued","dispatch.started","dispatch.progress","dispatch.completed","dispatch.failed","accountability.evidenceReady"], workspaceInstanceId }` |
+| `clio-coder/events` | `initialize` → `agentCapabilities._meta` | `{ version:1, notification:"clio-coder/event", kinds:["safety.loopBlocked","dispatch.enqueued","dispatch.started","dispatch.progress","dispatch.completed","dispatch.failed","accountability.evidenceReady","compaction.end","context.warning","safety.toolBudgetExceeded","provider.health"], workspaceInstanceId }` |
+| `clio-coder/steering` | `initialize` → `agentCapabilities._meta` | `{ version:1, main, dispatch, modes:["next-slot","end-of-turn"], interrupt:true, methods:{steer,queue,clear,interrupt,dispatch} }`. `main` and `dispatch` report which queues this build actually wired. |
+| `clio-coder/commands` | `initialize` → `agentCapabilities._meta` | `{ version:1, list:"clio-coder/commands/list", invoke:"clio-coder/commands/invoke", count }`. Absent when the composition wired no command host, in which case both methods refuse. |
+| `clio-coder/toolProgress` | `initialize` → `clientCapabilities._meta` | `{ version:1 }`. The client opt-in that turns the stream on. Anything else, a missing key, a different version, or a non-object, leaves it off. |
+| `clio-coder/toolProgress` | `initialize` → `agentCapabilities._meta` | `{ version:1, minIntervalMs:250, maxFramesPerCall:64, maxContentBytes:16384 }`. Always announced, so a client that never receives a second frame can tell "the tool printed once" from "the floor suppressed it". |
+| `clio-coder/decision` | `initialize` → `agentCapabilities._meta` | `{ version:1, meta:"clio-coder/decision", options:["allow-once","reject-once","reject-and-stop"] }`. Present only when a tool registry is wired. |
+| `clio-coder/decision` | `session/request_permission` → `params._meta` | The classified decision facts for this ask; see **Permission requests**. |
 | `clio-coder/session` | `session/new` / `session/load` result `_meta` | Bind-time `{sessionId,target,model,autonomy,createdAt,resumed,replayed?}` attribution. |
 | `clio-coder/replay` | replayed `session/update.params._meta` | `{ turn }`; absent on live updates. |
 | `clio-coder/truncated` | `clio-coder/targets/list` or `clio-coder/session/list` result `_meta` | `true` only when that method's aggregate byte budget omitted a target/model entry or session row; absent otherwise. |
@@ -346,10 +513,10 @@ The submission procedure follows these steps:
 
 ## Independent lifecycle coverage
 
-Workbench host replacement and direct ACP session isolation are separate checks. For the supported host API lifecycle, open a session and complete a turn, close, then use New and complete another turn. Close retires child A and initializes unbound child B; New binds B without a third launch. Record actual PIDs and host generations: both must change. A reused session ID alone cannot prove child replacement.
+Host replacement and direct ACP session isolation are separate checks. For the supported host API lifecycle, open a session and complete a turn, close, then use New and complete another turn. Close retires child A and initializes unbound child B; New binds B without a third launch. Record actual PIDs and host generations: both must change. A reused session ID alone cannot prove child replacement.
 
 For direct ACP isolation, keep one stdio child alive through new, turn, close, new, and turn. Record the same live PID and distinct session IDs. Check that the second request and persisted ledger exclude first-session history and turn ancestry and that the actual tasks list has no board. Explicitly resuming the first session must restore its own history and task state without second-session text. Record bounded teardown and child exit.
 
-The Workbench host contract uses a fixture subprocess; the direct ACP smoke uses built Clio with a loopback provider. Neither establishes browser interaction or live-provider behavior. The GUI has no close control, and the host API retires its child on close. Record host restart and direct same-child isolation independently, with the actions, process identities, evidence mode, and limits.
+The host contract uses a fixture subprocess; the direct ACP smoke uses built Clio with a loopback provider. Neither establishes browser interaction or live-provider behavior. The GUI has no close control, and the host API retires its child on close. Record host restart and direct same-child isolation independently, with the actions, process identities, evidence mode, and limits.
 
 ACP delegation receipts preserve peer-reported token totals, including explicit zero usage, and supported cost provenance without double-counting event metering. A peer total is used when supplied; otherwise components determine the total. Unknown cost is not evidence of free execution.

package/docs/architecture/artifact-placement.md

@@ -69,7 +69,7 @@ first. Keep several by naming explicit paths.
 
 The manifest records script path, canonical path, byte size and SHA-256, interpreter name/resolved path/arguments, exact argv, workspace-relative cwd, timeout, start/end times and duration, environment key names, outcome, effective `exitCode`, observed `leaderExit`, signal, stream byte counts, log paths, input identities, output status, `cleanup`, and `pipeDrainIncomplete`. Environment values are never recorded there. Regular-file hashes cover at most 64 MiB; omitted hashes carry `too-large`, `cancelled`, or `unreadable`. These are observed identities, not immutable snapshots. Logs stream to disk and have no total byte ceiling; bounded terminal tails are not the full log.
 
-Failure does not erase partial logs or outputs. Outcomes include `cleanup-incomplete` and `pipe-drain-incomplete`, with effective failure even if the leader exited zero. The first means original-group teardown could not be confirmed; the second means the one-second post-exit drain bound expired. Escaped processes can remain alive and outputs can still change. See [execution and cleanup](../guide/tool-usage.md#run_script-stream-a-scientific-processing-step-to-disk).
+Failure does not erase partial logs or outputs. Outcomes include `cleanup-incomplete` and `pipe-drain-incomplete`, with effective failure even if the leader exited zero. The first means original-group teardown could not be confirmed; the second means the one-second post-exit drain bound expired. Escaped processes can remain alive and outputs can still change. See [execution and cleanup](../guide/tool-usage.md#runscript-stream-a-scientific-processing-step-to-disk).
 
 After each run, `sweepRunRecords` keeps the newest 100 completed records by completion time. Recent manifest-less directories are treated as active; those at least 24 hours old are orphan candidates. Retention reads at most 64 KiB per manifest in chunks of at most 8 KiB. Oversized or malformed regular manifests fall back to opened-file mtime for ordering. Nonregular manifests, symlinked run directories, changed identities, and inaccessible entries are explicitly skipped and counted, not followed or silently removed. The sweep reports `removed`, `kept`, `active`, and `skipped`. This bounds metadata reads, not total directory enumeration or disk usage. Preserve needed evidence outside this retention tree before it ages out.
 

package/docs/architecture/capacity-and-scheduling.md

@@ -25,13 +25,13 @@ graph TD
 
 | Dimension | Identity | Limit resolution |
 | :--- | :--- | :--- |
-| Global | All dispatches using the state directory. | `fleet.concurrency: auto` remains four. |
-| Node | The local node or one configured fleet node. | The configured node limit applies. An unset local node cap remains unbounded. |
+| Global | All dispatches using the state directory. | `fleet.concurrency: auto` resolves to `AUTO_MAX_WORKERS` (8); a numeric setting sets the exact limit. It is not host-sized, so a small orchestrator host never shrinks remote execution. |
+| Node | The local node or one configured fleet node. | For the local node, `auto` sizes dynamically from host facts (usable CPUs, available memory minus a 2 GiB reserve divided by 1 GiB per worker, and cgroup limit, at most 8); a numeric setting sets an exact limit. Configured remote nodes apply their own `maxWorkers` (default 2). |
 | Inference endpoint | A normalized scheme, host, port, and base path. | A target's `maxConcurrentRequests` override wins, then a probe in this process, then a persisted probe from an earlier process, then one slot for other local-native targets. vLLM and SGLang remain unbounded. |
 
 The conventional final `/v1` mount and a trailing slash normalize to the same endpoint. Host aliases are not collapsed because Clio cannot prove they address the same server. For example, `http://localhost:8080/` and `http://127.0.0.1:8080/v1` remain distinct, while two target descriptors that use the same normalized URL share one endpoint limit.
 
-llama.cpp discovery reads `total_slots` from cached probe results. A router can expose the selected worker's value from `/props?model=<id>` even when router `/props` has no slot count. The selected model's `/v1/models` argv supplies a `--parallel` fallback. LM Studio defaults to one slot when its REST response supplies no concurrency fact. Ollama defaults to one unless `OLLAMA_NUM_PARALLEL` is visible to the local process.
+llama.cpp discovery reads `total_slots` from cached probe results. A router can expose the selected worker's value from `/props?model=<id>` even when router `/props` has no slot count. The selected model's `/v1/models` argv supplies a `--parallel` fallback. LM Studio defaults to one slot when its REST response supplies no concurrency fact. Ollama reports one because its native API exposes no slot count; use `maxConcurrentRequests` for a known daemon limit. The client’s environment is not server configuration.
 
 The endpoint set is resolved from the configured targets as well as the probed statuses, so it is the same set a second after boot as it is a minute later. An endpoint that resolves to no limit is not checked at all, and "not checked" is not a conservative answer.
 
@@ -105,11 +105,10 @@ dispatch: admission denied: endpoint '127.0.0.1:8080' capacity reached (1/1 slot
 
 Direct lease acquisition in `src/domains/dispatch/capacity-lease.ts` reports saturation as `capacity reached`. The normal admission controller in `src/domains/dispatch/admission.ts` treats that signal as transient and leaves the assignment in its bounded shared queue, retrying until capacity opens or the request's deadline or 60-second queue ceiling wins. Capacity marked `unavailable`, drain mode, corrupt state, and other errors still fail immediately. Reservation preflight in `src/domains/dispatch/reservation-store.ts` refuses an over-capacity plan instead of queuing a partial reservation. The `1/1` example represents a generic llama.cpp server started with `--parallel 1`: a singular dispatch raised while the orchestrator is streaming waits for that slot, and a council reservation is refused before any worker starts.
 
-The reference `mini` target is not a one-slot example. It is a llama.cpp router
-at `192.168.86.141:8080` serving `ornith1.5-35b-moe` with four parallel slots
-and 262,144 context tokens per slot. One foreground stream on that endpoint
-leaves three slots for worker admission. The reference chat target, `dynamo`,
-is LM Studio at `192.168.86.143:1234` serving `qwen3.8-27b-dynamo`.
+A four-slot llama.cpp endpoint leaves three admission slots while one foreground
+stream is active. This says nothing about four independent full context windows:
+with unified KV, requests can share a single pool. Slot admission does not reserve
+VRAM or prove that the aggregate prompts will fit or meet a latency target.
 
 ### What `/council` Needs on a Single-GPU Setup