@iowarp/clio-coder 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -9,6 +9,39 @@ produced it.
 Versions follow semantic versioning for a pre-1.0 project: minor versions may
 still change interfaces.
 
+## 0.3.1 - 2026-08-16
+
+- Made a dispatched worker visible while it runs. `/run` and `/delegate` stream into the transcript as a worker block: an attributed header naming the agent, its route or protocol, and its run id; the worker's prose down a rail; a coalesced tool line; and a receipt footer whose failure reason wraps as prose above it. Dispatch lifecycle events fold into one entry per assignment, so a failover reads as one run with an ↻ line per earlier attempt, and a late event from a superseded attempt moves nothing. A model-started run lands folded under the tool call that spawned it, so a fan-out of three reads top to bottom in spawn order, folded cards stack without blank rows, and `Alt+O` folds or unfolds the newest tool call or worker block. Every board row, footer chip, and transcript block leads with who asked for the run: hollow for the operator, filled for the model, a quiet dot for Clio's own. The session records a `workerRun` entry where a block opens, so a `/resume` redraws the block from that entry plus the sealed receipt, bounded exactly like a live one, and a run whose receipt is gone settles as `receipt unavailable`. `--share` on `/run` and `/delegate`, and `/share [runId]` afterwards, hand a worker's bounded receipt text to the main agent as operator text under a `[worker result] <agent> · run <id> · <outcome> · shared by the operator` header, which the operating contract now names so the model treats it as steering rather than an unattributed tool result; bare `/share` picks the newest finished run the operator started and skips agent-origin runs the model already holds. A structured worker answer renders as prose on the rail instead of one line-wrapped JSON string, a mutation report reading as its changed paths, validations with verdict glyphs, summary, and commit line, while the model still receives the raw payload. A replayed operator turn after `/fork` or `/resume` shows what the operator typed rather than the composed prompt with its system-reminder scaffolding. The transcript ledger prints a written file's byte count rather than the length of its confirmation sentence.
+- Added the interop discovery domain. `src/domains/interop` owns knowing which other coding agents are installed: a registry with one pure-data entry per known agent, bounded detection that resolves binaries without a shell and reports `unknown` when a probe cannot answer, and a decision record in `state/interop.json` that only an operator decision writes. `clio-coder configure --interop` and the first-run wizard turn a detection report into consent proposals, show the exact `delegation.agents` YAML before asking, and append an accepted peer through the serialized settings writer; a decline is remembered by fingerprint and stays silent until the binary's version or path moves, and one review that answers n, n, y keeps all three decisions. `clio-coder doctor` gains a row per detected agent, a warning for a configured peer whose command no longer resolves, and one aggregate row for foreign skills, and still writes nothing. The `/interop` overlay lists agents as Detected, Configured, and Declined with one key each to connect or decline, the boot line names installed peers that are unconfigured and undecided, and the `delegation.agents` row in `/settings` gains add and remove actions. Foreign agent directories become a `noWritePaths` policy class from the registry, so Clio never writes into another agent's directory, and foreign prompt roots such as `~/.claude/commands`, `~/.codex/prompts`, and `~/.config/opencode/command` load into `/prompts` trusted at user scope while their project counterparts stay behind `skills.trustProjectCompatRoots`. Detection never spawns a foreign work command, never reads a foreign session store, and never wires a peer without an answer.
+- Fixed every prompt template being unreachable from the TUI. `/demo` and any other `/name` that a loaded template owns now submits through the expansion path instead of failing as `is not a command`; an untrusted project template refuses with a named reason, and headless prints that refusal and exits 1.
+- Implemented the documented `clio-coder acp --cwd PATH` and `--permission-timeout MS`. Both had appeared in `docs/acp.md` since v0.3.0 and were rejected as unknown options. `--cwd` changes into the workspace before boot and `--permission-timeout` overrides `delegation.defaults.permissionTimeoutMs` for that server only; a rejected invocation writes usage to stderr and leaves the protocol channel untouched. ACP `_meta` keys now live under the `clio-coder/` namespace rather than `clio.coder/`.
+- Made the agent ledger reachable and made the main model read it. No builtin recipe declared the ledger tool, so a fanned-out worker was never offered it, and three seams between the dispatch call site, the local spawner, and the fleet transports each dropped the control-lane callback that carries a post; a live three-scout fan-out sealed a board with zero entries. Every builtin that can be fanned out now declares the ledger, every spawn path forwards the full option set, a post that lands before the run has attribution is held in order and appended once it does, a backgrounded parallel batch keeps its board open until collect, and a detached batch closes its board on the collection that settles it. A settled parallel dispatch, a compete result, and monitor collect for a detached batch now carry one `agent ledger (<n> entries, sequence <w>)` section after the per-run lines with the same bounded render, attribution, and corroboration and dispute marks a worker sees, reserved out of the output ceiling so truncation never drops it; a board nobody posted to is omitted, so a single-run dispatch is byte-identical to before. Corroboration keys citations in workspace-relative form, so one file cited by relative and absolute path reads as one corroborated finding. A new composition suite drives the real recipes, bundle, and dispatch and monitor tools with only the worker process faked.
+- Refused an unrunnable review fan-out at admission rather than after approval. A review gate with more than one task, a review under a non-parallel mode, a compete with review or several tasks, an unparseable request set, or an unknown mode never parks for approval and returns the executor's own shape error, so the operator no longer approves a plan the executor rejects in milliseconds and the model is told how to gate a fan-out: run it without review, then dispatch one integration task with review.
+- Answered an identical worker escalation with the operator's earlier decision. The escalate posture keeps a per-run memory keyed by tool plus canonical arguments; a parked call already decided in this run is released with the remembered grant or cancelled with a reason naming the earlier request, both audited as `operator:remembered`, ending the loop where each approved card only bought the next identical card. A different command is still a new decision.
+- Fixed a coder run losing its entire final answer on the synthesis-locked repair round. The lock only set `tool_choice: none`, llama.cpp honoured that by disabling its tool-call parser while the template still rendered every tool schema, and the model's tool markup came back as content the loop guard removed. A locked worker round on OpenAI-family APIs now removes tools from the request, so plain text is the only move left; Anthropic keeps `tool_choice: none`. When the loop guard does remove a reply, the repair rounds, the receipt, and the fallback notice now say that the reply held only tool-call markup and was removed, instead of `result must be valid JSON`.
+- Made the mutation-contract refusal show the value that would have passed. An empty `validations` array is told it was empty and given one shaped entry; wrong keys are told which keys an entry carries; the coder recipe states the same requirement where the model reads its result guidance.
+- Fixed a `/run --model` override stranding a llama.cpp router with one instance slot. A model that will come back tag-pinned may only take an unprotected slot; when the load would fit only by evicting the configured worker model it declines up front with a will-not-fit notice naming that resident and its role, so the swap that could not be undone is never made.
+- Corrected tool timing across the transcript, receipts, and `toolStats`. The registry reports how long a call sat parked on a permission card and the tool adapter subtracts it, and the transcript prefers the registry's own span over the engine frame, so an operator's approval wait is no longer sealed as tool execution time. The park closes at the operator's decision rather than at the verdict, so an approved call's own execution is no longer subtracted with the wait; a review dispatch that fanned out for 224 seconds had settled as a 15ms line (#82).
+- Read every model JSON payload through one shared reader. `parseJsonObjectPayload` in `src/core/json-payload.ts` walks the whole message, the first fenced block, and the outermost brace span, and tries every candidate span in turn, so a fenced code report, judge verdict, verifier report, terminal result contract, or context handbook whose body nests its own fence is no longer refused for its wrapping. Conformance did not widen: a candidate still has to parse to an object and every field check stays where it was.
+- Fixed `clio-coder context init` losing complete handbooks. Citations carrying a line anchor (`src/cart.ts:40-42`) or written as a call (`priceCart()`) are grounded by the path or name underneath, so a handbook whose Gotchas and Architecture sections cited real files no longer falls under the grounding floor; the local import convention is measured from the relative specifiers the indexer extracted, reported only on a clear majority, instead of asserting `.js` because a `tsconfig.json` exists; and the fallback notice names `context-bootstrap` and says the handbook was not produced instead of `Scout unavailable`.
+- Named reachability as reachability. An LM Studio turn that failed with `connect ENETUNREACH` no longer advises resizing a model that was never asked to load; `describeLoadFailure` recognises connect-level errnos and says the server did not answer.
+- Fixed the benchmark adapters. HumanEval manifests count generation errors and failed tasks separately, keep the model and target profile through grading, and record where each completion came from, and `regrade --out <run-dir>` rescores a finished 164-task run from its stored attempts in seconds without calling a model. SciCode steps are graded with the dependency header they were promised and the return line upstream supplies, the prompt reaches the model as prose rather than an indented code block, and `snapshot-step` lets a step solved by hand or through the TUI reach the grader. The Terminal-Bench container mirrors the operator's own fleet per node, runtime and thinking level included, probes the worker endpoint in preflight, writes one manifest per episode, and its installer installs `curl` when neither downloader is present, prints the output that produced a failure, and returns rather than exits when sourced so the harness's tmux signal still fires.
+- Renamed the remaining surfaces the 0.3.0 rename missed. The process title is `clio-coder` and a worker reads `clio-coder-worker:<agent>` in `ps` and `htop`; the fleet node key is `clioCoderEntry` and the eval flag is `--clio-coder-entry`, with both old spellings still read; `CLIO_CODER_MAX_DISPATCH_RUNS` is the canonical guardrail spelling and `CLIO_CODER_MAX_RUNS` still reads. Removed the `identity` setting that shipped in every generated `settings.yaml` and that nothing read; an existing file with the key still loads. Declared the package as a CLI with an `exports` map naming only `./package.json`, so the 778 shipped source files are no longer an unversioned deep-import surface. Corrected the runtime plugin path to `~/.config/clio-coder/runtimes/`, the tool count to twenty in every place it was stated, and the glossary. Replaced one operator's node names, model ids, and addresses in source comments, docs, scripts, soak configurations, and benchmark adapters with neutral placeholders and `CLIO_CODER_*` environment variables, and attributed the identity fragment to the Gnosis Research Center at Illinois Tech and the IOWarp team.
+- Reworked the settings and configuration surfaces of the TUI. `/settings` is a transactional Settings Center grouped as CORE, ROUTING, RUNTIME, and EXPERIENCE; every edit builds a change plan and asks Apply this session, Apply and save globally, or Cancel, a global save writes only the leaves the mutation touched, and `/output` and `/thinking` apply to the session rather than silently rewriting the file. Fleet profiles, agent bindings, and targets are editable rows: Settings → Fleet is an entity workbench with add, remove, node-pin, and unbind flows, and Settings → Targets is a console with use, probe, connect, and remove per row. `/targets`, `/fleet`, `/scoped-models`, bare `/thinking`, and bare `/output` deep-link into the matching section, `/settings <section>` reaches every other one, and the bespoke overlays those commands opened are gone; running and retrying dispatches stay on the `Alt+W` Fleet Runs board. Below 72 columns the overlay drills down one page at a time under a breadcrumb, Esc moves up exactly one level at every width, and `/` filters rows by label, path, and description. A scoped-model reference whose target is unconfigured is kept and disclosed rather than silently dropped at load.
+- Recast the rest of the TUI around the same doctrine: an adaptive welcome launchpad, a composer that reads unmistakably as the place to type, a voice-first transcript with a two-cell hanging indent, slash commands presented as a grouped palette, a quiet two-zone footer that discloses status progressively and degrades notices without losing their dismiss key, one orange activity signal per surface, and a decision prompt that wears the orange frame and names its accept key. An `ask_user` prompt is now the size of the question it asks: a two-option confirmation is a bottom-anchored bar rather than a full-height modal, and only a multi-question round or a later interview round takes the full surface. `/memory` reaches every entry through a filterable master-detail overlay, a narrow list footer keeps the key that opens its detail pane, a skill suggestion line no longer steals the reply glyph from the answer, and the footer says nothing about reasoning tokens when a turn spent none.
+- Rebuilt the trace viewer on the docs blueprint design system: brand assets and a version chip on the masthead, semantic palette tokens that reserve action orange for running state, interactive waterfall lanes with tool tick markers, a run search filter that survives live polling, truthful `$0.00` spend, and contract tests for tool durations, payload truncation honesty, and process status badges.
+- Made time correct across the runtime. Durations are measured on `performance.now()` and never on two wall-clock reads, so an NTP step or a laptop resume cannot publish a time-to-first-token that never happened or abort a healthy stream through the stall watchdog; a backwards clock is counted rather than clamped into silence. Every operator-facing timestamp renders through one `format-time.ts` module in the operator's own timezone, so `/tree`, `/fork`, `/resume`, `/memory` step rows, the banner's handoff freshness, and the `/export` filename no longer read a UTC instant as local and land a whole calendar day off for anyone far from UTC. Lockfiles and capacity leases record host, pid, and birth token, so a sibling host sharing a state directory never steals a live holder's lock or slot and a live holder keeps its lock however long it takes; the four lock implementations that disagreed on staleness by a factor of 26 are one. `runs.json` eviction spends its cap on finished rows and keeps live ones, eval ids can no longer collide within a millisecond, and a run whose owner died mid-dispatch is finalized on store open. The test harness gained a frozen, steppable clock, and the panels that raced the wall clock read it.
+- Made a stalled stream abort and retry instead of waiting forever. `retry.streamStallMs` (default 180000, 0 disables) arms a deadline at `agent_start` that every engine event pushes out; when it passes with nothing from the stream the run is aborted through the same path Esc uses and walks the existing retry ladder, so a headless run, a fleet worker, or an ACP client no longer needs a human at the keyboard. Silence during tool execution does not count. The await-watchdog counts a worker's own stream as progress, so a dispatch that produced thousands of events is no longer reported as `no progress`.
+- Fixed the result-contract repair round. The directive now rides as a tool result paired with a synthetic assistant call, which every served template treats as a history append instead of re-rendering the whole prompt (11,352 tokens reprocessed as a user turn against 407 as a tool result on a warmed 15k prefix), which OpenAI's and Anthropic's validators accept, and whose zero usage the context estimator skips; before that last change every dispatched worker died one round after its terminal message with `Cannot read properties of undefined (reading 'totalTokens')`. LM Studio no longer reports `cacheRead: 0` for a stat it does not have.
+- Made LM Studio residency fit the context and keep one instance. A just-in-time load beside another resident model is capped at 131,072 tokens and the clamp is reported before the first turn, raised with `CLIO_CODER_LMSTUDIO_CORESIDENT_CONTEXT`; a model that is already resident is reused rather than loaded a second time; configured models carry the plane they serve so a forced eviction names its role; and a turn under 2 tok/s for 30 seconds emits a `degraded` notice listing the resident set. The planner budgets against the window the backend has actually loaded rather than a catalog maximum, so the 80% compaction trigger no longer sits above the limit a backend fails at.
+- Added the outward exposure tier to `ask_user`. A skill marks a gate whose confirmation leaves the machine as `exposure: outward`, and that gate parks for the operator at both supervised levels instead of being auto-answered, so filing a public issue can no longer go through in 24ms without a human; `full-auto` is untouched and an unrecognised tier reads as outward. The read-only exploration nudge advises once per turn instead of forcing a second model round, and the footer tools row leads with the registered tool count so a session whose only call was a dispatch no longer reads `tools none`. A turn that claims worker results without a dispatch call to back them draws an honesty notice.
+- Moved generated artifacts out of the working tree. The `artifact` tool's defaults resolve to `.clio-coder/artifacts/PLAN.md`, `REVIEW.md`, and `REPORT.md`, which is gitignored, so a report-writing turn no longer drops a root-level file into a repository a second agent is working in; an explicit `path` still writes exactly where it says. `docs/artifact-placement.md` states the contract.
+- Made the package carry Clio's own source and code map. `files` gains `src/**` and the build ends by indexing exactly the packed file set into `dist/assets/codewiki.json`, so an installed Clio can read her own source and answer questions about herself; the twelve tree-sitter grammars are vendored into `dist/assets/grammars/` in place of two grammar packages costing ~72MB per install, and `chalk`, `diff`, `uuid`, `yaml`, `typebox`, and `undici` are bundled into `dist/` and moved to devDependencies. A pack-install smoke installs the tarball into a scratch prefix and proves `--version` and `context index` from there. The release workflow verifies artifacts and never publishes; `npm publish` is a manual maintainer step, and a contract test guards that no publish path is re-added.
+- Collapsed the git skill pipeline to three stages, `file-ticket`, `fix-issue`, and `ship`, retiring `commit-crafting`, `create-pr`, `investigate-issue`, and `review-changes`; the coder and git-master builtins rebind to the survivors and the catalog is re-pinned.
+- Fixed a pasted slash command with a trailing newline landing in the composer without running, shadow workers reading as `sh:`-prefixed agent names rather than as internal processes with their own footer rows and receipt ids, and evidence attribution claiming an overlapping sibling run's entry as its own; an entry inside two run windows now lists both candidates and appears in each bundle.
+- Made `clio-coder doctor` treat a home Clio has never written to as not set up rather than broken. It prints one `WARN installation not set up yet` row naming `clio-coder`, `clio-coder configure`, and `doctor --fix`, exits 0, and creates nothing, so the `--fix` that follows is stamped as an install rather than a repair; once any root exists the per-row report and exit 1 are unchanged.
+- Made an upgrade say so. `install.json` records `upgradedFrom` when the version changes, `clio-coder doctor` shows `upgraded <when> from <version>`, and the first interactive launch on the new version shows one footer notice naming the transition, the commands and skills that moved, and the CHANGELOG section, then records `noticedVersion` so it never repeats; headless and ACP boots stay silent. `clio-coder upgrade --dry-run` names the recorded and current versions it would move between and says plainly when no migrations are registered, and the post-install and local paths report `0.3.0 -> 0.3.1` rather than the binary's own version twice. Nothing about the 0.3.0 to 0.3.1 upgrade needs a hand step: `identity:` still loads and is ignored, `clioEntry` and `CLIO_CODER_MAX_RUNS` still read.
+
 ## 0.3.0 - 2026-08-14
 
 - Renamed every namespace the tool occupies on a user's machine from `clio` to `clio-coder` ahead of the first npm publish, so the future clio-core, clio-agent, and clio-kit tools can coexist with it: the installed binary and every command example are now `clio-coder`, XDG config/state/cache directories use a `clio-coder` segment, the project context directory is `.clio-coder/`, the generated handbook is `CLIO-CODER.md`, environment variables are `CLIO_CODER_*`, and extension manifests are `clio-coder-extension.*`. The product name in prose remains Clio Coder, and code-internal identifiers, event names, and receipt fields are unchanged. There are no migration shims: this ships in the first published release, so there is no installed base to migrate.

package/README.md

@@ -20,7 +20,7 @@
 </p>
 
 > [!WARNING]
-> **Experimental v0.3.0 release.** Clio Coder's behavior and interfaces may
+> **Experimental v0.3.1 release.** Clio Coder's behavior and interfaces may
 > break or change without notice. Use version control, review proposed changes,
 > and keep backups when operating on important repositories.
 
@@ -42,6 +42,24 @@ CLIO stands for Context Layer for Input/Output. Clio Coder is the interactive
 coding agent in IOWarp's ecosystem of agentic science, named for the Greek
 muse of history and built by the Gnosis Research Center at Illinois Tech.
 
+### Get started
+
+Requires Node.js `>=22.19.0`. Three commands, in order:
+
+```bash
+npm install -g @iowarp/clio-coder
+clio-coder configure      # pick a model provider or a local server
+clio-coder                # start the interactive session in any project directory
+```
+
+`configure` is the wizard: it lists the runtimes, asks for the endpoint and
+model, probes it, and saves it as the chat and worker target. Skip it and bare
+`clio-coder` starts the same wizard when no usable target is configured. In the
+first session, type a request in plain words, or `/help` for the command
+palette; `/settings` (or `/targets`) changes the model later; `/quit` leaves.
+`clio-coder doctor` reports the install's health, and on a home nothing has set
+up yet it says so in one row and exits 0.
+
 ### Pick your path
 
 |  | You are | Start here |
@@ -108,17 +126,14 @@ experiment-protocol guides.
 
 ## Install
 
-From npm:
-
-```bash
-npm install -g @iowarp/clio-coder
-clio-coder --version
-```
+From npm, [Get started](#get-started) is the whole install. `clio-coder upgrade`
+moves an existing install to the latest release; `--channel=beta` follows a
+dist-tag instead.
 
 From source, pinned to this release:
 
 ```bash
-git clone --branch v0.3.0 https://github.com/iowarp/clio-coder.git
+git clone --branch v0.3.1 https://github.com/iowarp/clio-coder.git
 cd clio-coder
 npm run install:local
 export PATH="$HOME/.local/bin:$PATH"
@@ -126,51 +141,29 @@ hash -r
 "$HOME/.local/bin/clio-coder" --version
 ```
 
-The clone is pinned to `v0.3.0`, the release these instructions describe.
-Without `--branch` you get the default branch, which is ahead of the release and
-is not what the rest of this page documents.
-
-`npm run install:local` verifies dependencies, builds the CLI, installs a
-symlink at `${CLIO_CODER_BIN_DIR:-$HOME/.local/bin}/clio-coder`, and runs the installed
-CLI's structure repair so a fresh install passes plain `clio-coder doctor` with no
-manual steps. It warns if the bin directory is not on your `PATH` and prints the
-`export` line above; the line is a no-op for the shell that already has it, and
-it is what makes a bare `clio-coder` resolve in the shell that does not. Put it in
-your shell profile to keep it across sessions. The symlink executes
-`dist/cli/index.js`, so re-run `npm run build` after editing TypeScript sources.
-
-The last line runs the launcher by its full path on purpose. A bare `clio-coder` may
-resolve to an older install earlier on your `PATH`, so it verifies whichever one
-that is rather than the one you just installed; the installer warns when it
-finds that shadowing, and names the other path.
-
-Before you switch to the bare name, ask which file it reaches:
-
-```bash
-command -v clio-coder    # expect $HOME/.local/bin/clio-coder
-```
-
-Comparing `clio-coder --version` against `"$HOME/.local/bin/clio-coder" --version` does not
-answer that. Two installs of the same release print the same version, so the
-versions agree while the name still resolves to the other one. The path is the
-question.
+`npm run install:local` builds the CLI, links it at
+`${CLIO_CODER_BIN_DIR:-$HOME/.local/bin}/clio-coder`, and initializes the home.
+Put the `export PATH` line in your shell profile. If an older install is on your
+`PATH`, `command -v clio-coder` shows which file the bare name reaches; the
+installer warns when it finds one.
 
 To remove it, preview first:
 
 ```bash
 clio-coder uninstall --dry-run
 clio-coder uninstall --remove-binary --force
-hash -r
 ```
 
-For selective wipes that keep settings or credentials, use `clio-coder reset`. Full
-details live in [docs/installation-and-lifecycle.md](docs/installation-and-lifecycle.md).
+Full lifecycle details, including `reset` and the upgrade path, are in
+[docs/installation-and-lifecycle.md](docs/installation-and-lifecycle.md).
 
 ## Five-minute start
 
 Run Clio from the repository you want to work on and point one target at a
-running model server. This example uses LM Studio; other local runtime ids
-include `ollama-native`, `llamacpp`, `vllm`, and `sglang`.
+running model server. The wizard under [Get started](#get-started) does this
+interactively; the flags below do the same thing from a script. This example
+uses LM Studio; other local runtime ids include `ollama-native`, `llamacpp`,
+`vllm`, and `sglang`.
 
 ```bash
 cd /path/to/your/repo
@@ -196,8 +189,10 @@ clio-coder run "Summarize this repository layout and identify the main entry poi
 clio-coder                   # interactive terminal UI
 ```
 
-Inside the TUI, `/targets`, `/agents`, `/fleet`, and `/skill` confirm what the
-session can see. `/help` opens the interactive help center.
+Inside the TUI, `/settings` shows the target, fleet, and routing the session
+uses (`/targets` and `/fleet` open straight into their sections), `/agents` and
+`/skill` list what it can dispatch and run, and `/help` opens the interactive
+help center.
 
 ## Bring your own model
 
@@ -327,8 +322,8 @@ flowchart LR
   O --> P["execution plan<br/>hashed DAG, capacity waves"]
   P --> A["admission<br/>leases, queue, cost ceiling"]
   A --> L["local worker"]
-  A --> S1["ssh node: blade"]
-  A --> S2["ssh node: dragon"]
+  A --> S1["ssh node: node-a"]
+  A --> S2["ssh node: node-b"]
   L --> R["receipts and evidence"]
   S1 --> R
   S2 --> R
@@ -341,20 +336,21 @@ present:
 ```yaml
 fleet:
   nodes:
-    - id: blade
-      host: blade.example.net
+    - id: node-a
+      host: node-a.example.net
       maxWorkers: 2
       residency: observe
-    - id: dragon
-      host: dragon.example.net
+    - id: node-b
+      host: node-b.example.net
       maxWorkers: 1
 ```
 
 Then `clio-coder doctor` runs a per-node preflight, `clio-coder fleet list|run|status`
 drives and observes contracts, and `clio-coder fleet drain|resume` closes or reopens
 durable dispatch admission. A drain preserves running work, rejects every new
-execution start, and expires after one hour unless renewed. The `/fleet`
-overlay shows nodes, profiles, bindings, and live runs. Nodes must share the
+execution start, and expires after one hour unless renewed. `/fleet` opens
+Settings → Fleet with defaults, profiles, agent bindings, and node placement,
+and the `Alt+W` Fleet Runs board shows live runs. Nodes must share the
 project filesystem at the same absolute path; hosts that do not fail admission
 with a clear reason. Target URLs resolve on the node the worker runs on, so
 `localhost` means that node's own inference server and there is no central
@@ -439,7 +435,7 @@ list|propose|approve|reject|prune`. Design notes:
 ## Status
 
 Clio Coder is experimental software in a soft beta. The current release is
-**v0.3.0**, installable from npm as
+**v0.3.1**, installable from npm as
 [`@iowarp/clio-coder`](https://www.npmjs.com/package/@iowarp/clio-coder) or
 from source. Interfaces may still move between minor versions, and
 model-specific behavior varies by target.
@@ -675,6 +671,7 @@ Benchmarks against public suites live under `benchmarks/`:
 ```bash
 npm run bench:swe        # SWE-bench Lite
 npm run bench:scicode    # SciCode
+npm run bench:tb         # Terminal-Bench
 ```
 
 ## Where to start
@@ -708,7 +705,7 @@ locally with interactive blueprints.
 | Argonne ALCF Sophia and Metis inference targets over Globus OAuth | [alcf-provider.md](docs/alcf-provider.md) |
 | Safety posture, default-deny Bash, project policy, damage-control rules, typed validation | [safety-model.md](docs/safety-model.md) |
 | Source layout, compile-time boundaries, domain loading, runtime data flow | [architecture.md](docs/architecture.md) |
-| Reference for all 19 worker tools: parameters, payloads, error examples | [tool-usage.md](docs/tool-usage.md) |
+| Reference for all 20 worker tools: parameters, payloads, error examples | [tool-usage.md](docs/tool-usage.md) |
 | Prompt envelope reuse, provider tool delivery, bounded tool results | [prompt-envelope-and-tools.md](docs/prompt-envelope-and-tools.md) |
 | Implementing custom model runtimes and inference server integrations | [provider-adapter-cookbook.md](docs/provider-adapter-cookbook.md) |
 | Artifact browsing, receipt verification, dispatch diagnostics, observability routing | [observability.md](docs/observability.md) |

package/dist/acp-FPR54DGL.js

@@ -0,0 +1,138 @@
+import { createRequire as __clioCreateRequire } from "node:module"; const require = __clioCreateRequire(import.meta.url);
+import {
+  restoreStdout,
+  runClioCommand,
+  takeOverStdout,
+  writeRawStdout
+} from "./chunk-FCIH3BIZ.js";
+import "./chunk-KKNLWXI6.js";
+import "./chunk-RPTR2H26.js";
+import "./chunk-R5KLMSBV.js";
+import "./chunk-G34LV2PF.js";
+import "./chunk-MAR7Y6HW.js";
+import "./chunk-4QKXUHSR.js";
+import "./chunk-ASND7OZK.js";
+import "./chunk-Q3RUPKEJ.js";
+import "./chunk-XYWBQRDM.js";
+import "./chunk-PIUMUEMV.js";
+import "./chunk-DKGKUHFA.js";
+import "./chunk-XPLRXC72.js";
+import "./chunk-M5T5VO65.js";
+import "./chunk-5WIGXA4T.js";
+import "./chunk-PFEFKVGL.js";
+import "./chunk-7SS2CTV2.js";
+import "./chunk-FST4FYJB.js";
+import "./chunk-BSU2YIWB.js";
+import "./chunk-ZPY3JZ5E.js";
+import "./chunk-N6F52NLF.js";
+import "./chunk-LU4TK2PR.js";
+import "./chunk-GEP36Y4X.js";
+import "./chunk-OLBBMFRD.js";
+import "./chunk-474KN5II.js";
+import "./chunk-CGKSTWHD.js";
+import "./chunk-C4PTHK7P.js";
+import "./chunk-GAEBEQVI.js";
+import "./chunk-TXOTCRLG.js";
+import "./chunk-K5XEMXTI.js";
+import "./chunk-TEKV33Q5.js";
+import "./chunk-2STGEDFV.js";
+import "./chunk-IS3ONKU3.js";
+import "./chunk-PV4JUBVJ.js";
+import "./chunk-673JJUWJ.js";
+import "./chunk-RDLVBZEO.js";
+import {
+  printError
+} from "./chunk-K2ITRMHZ.js";
+import "./chunk-H6F6BYOH.js";
+import "./chunk-EYOKLTMF.js";
+import "./chunk-IHXBNWMM.js";
+import "./chunk-Q5WJOSJ7.js";
+import "./chunk-KY56HMHH.js";
+import "./chunk-NMOX6HFD.js";
+import "./chunk-GB6QRBXN.js";
+import "./chunk-3I7MS7N2.js";
+import "./chunk-HQQID6OA.js";
+import "./chunk-R346GLFC.js";
+import "./chunk-WEPFGWHJ.js";
+import "./chunk-BNAZZHFG.js";
+import "./chunk-IWHMRKLL.js";
+import {
+  init_esm_shims
+} from "./chunk-3R73A4XB.js";
+
+// src/cli/acp.ts
+init_esm_shims();
+import path from "node:path";
+var HELP = `clio-coder acp [--cwd PATH] [--permission-timeout MS]
+
+Serve Clio Coder as an Agent Client Protocol v1 agent over stdio.
+
+  --cwd PATH               Workspace root the server boots in and opens sessions at.
+  --permission-timeout MS  How long a mediated permission request may wait for the
+                           client before it is denied. Defaults to the configured
+                           delegation.defaults.permissionTimeoutMs.
+
+This command is intended for ACP frontends to spawn. Interactive delegation remains
+available through /agents, /delegate, the dispatch board, and receipts.
+`;
+function parseAcpFlags(args) {
+  const flags = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    const value = args[index + 1];
+    if (arg === "--cwd") {
+      if (value === void 0) return "--cwd needs a directory";
+      flags.cwd = path.resolve(value);
+      index += 1;
+      continue;
+    }
+    if (arg === "--permission-timeout") {
+      const ms = value === void 0 ? Number.NaN : Number(value);
+      if (!Number.isInteger(ms) || ms <= 0) return "--permission-timeout needs a positive whole number of milliseconds";
+      flags.permissionTimeoutMs = ms;
+      index += 1;
+      continue;
+    }
+    return `unknown clio-coder acp option: ${arg ?? ""}`;
+  }
+  return flags;
+}
+async function runAcpCommand(args, options = {}) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+  const flags = parseAcpFlags(args);
+  if (typeof flags === "string") {
+    printError(flags);
+    process.stderr.write(HELP);
+    return 2;
+  }
+  if (flags.cwd !== void 0) {
+    try {
+      process.chdir(flags.cwd);
+    } catch {
+      printError(`--cwd is not a directory this process can enter: ${flags.cwd}`);
+      return 2;
+    }
+  }
+  takeOverStdout();
+  try {
+    return await runClioCommand({
+      ...options.apiKey === void 0 ? {} : { apiKey: options.apiKey },
+      ...options.noContextFiles ? { noContextFiles: true } : {},
+      ...options.noSkills ? { noSkills: true } : {},
+      ...options.skillPaths && options.skillPaths.length > 0 ? { skillPaths: options.skillPaths } : {},
+      acp: {
+        transportOptions: { write: writeRawStdout },
+        ...flags.permissionTimeoutMs === void 0 ? {} : { permissionTimeoutMs: flags.permissionTimeoutMs }
+      }
+    });
+  } finally {
+    restoreStdout();
+  }
+}
+export {
+  runAcpCommand
+};
+//# sourceMappingURL=acp-FPR54DGL.js.map

package/dist/{agents-Q4MYPMUW.js → agents-OGPIHPJH.js}

@@ -1,41 +1,49 @@
+import { createRequire as __clioCreateRequire } from "node:module"; const require = __clioCreateRequire(import.meta.url);
 import {
   AgentsDomainModule,
   SafetyDomainModule
-} from "./chunk-JPOWPFCU.js";
-import "./chunk-NI4DEJMC.js";
+} from "./chunk-MAR7Y6HW.js";
+import "./chunk-4QKXUHSR.js";
 import {
   ensureClioState
-} from "./chunk-7RBKDI66.js";
+} from "./chunk-ASND7OZK.js";
 import {
   ConfigDomainModule,
   loadDomains
-} from "./chunk-527KG6XR.js";
-import "./chunk-UU3R62TT.js";
-import "./chunk-HMYNFFY4.js";
-import "./chunk-XV4ZJ6ZM.js";
-import "./chunk-26BZQOAD.js";
+} from "./chunk-Q3RUPKEJ.js";
+import "./chunk-XYWBQRDM.js";
+import "./chunk-XPLRXC72.js";
+import "./chunk-GEP36Y4X.js";
 import {
   isUserVisibleAgent
-} from "./chunk-WD6AJM35.js";
-import "./chunk-QV47YRF4.js";
-import "./chunk-CLJ5HLUD.js";
-import "./chunk-262G75JS.js";
-import "./chunk-TFSSEXL6.js";
-import "./chunk-PIDUD6M2.js";
+} from "./chunk-OLBBMFRD.js";
+import "./chunk-474KN5II.js";
+import "./chunk-CGKSTWHD.js";
+import "./chunk-C4PTHK7P.js";
+import "./chunk-PV4JUBVJ.js";
+import "./chunk-673JJUWJ.js";
+import "./chunk-RDLVBZEO.js";
 import {
   printError
-} from "./chunk-67MTHP2E.js";
-import "./chunk-D5YD55AR.js";
-import "./chunk-JWHCJDCI.js";
-import "./chunk-UHTSULZS.js";
-import "./chunk-5LDRNKX2.js";
-import "./chunk-UGYAX5YI.js";
-import "./chunk-5N2FG33Q.js";
-import "./chunk-VPAWTYLY.js";
-import "./chunk-X3NE4WVW.js";
-import "./chunk-DXQNI4PC.js";
+} from "./chunk-K2ITRMHZ.js";
+import "./chunk-EYOKLTMF.js";
+import "./chunk-IHXBNWMM.js";
+import "./chunk-Q5WJOSJ7.js";
+import "./chunk-KY56HMHH.js";
+import "./chunk-NMOX6HFD.js";
+import "./chunk-GB6QRBXN.js";
+import "./chunk-3I7MS7N2.js";
+import "./chunk-HQQID6OA.js";
+import "./chunk-R346GLFC.js";
+import "./chunk-WEPFGWHJ.js";
+import "./chunk-BNAZZHFG.js";
+import "./chunk-IWHMRKLL.js";
+import {
+  init_esm_shims
+} from "./chunk-3R73A4XB.js";
 
 // src/cli/agents.ts
+init_esm_shims();
 var HELP = `clio-coder agents [--json] [--all]
 
 List user-facing agent specs from built-in, user, and project recipes.
@@ -88,4 +96,4 @@ function renderLine(spec) {
 export {
   runAgentsCommand
 };
-//# sourceMappingURL=agents-Q4MYPMUW.js.map
+//# sourceMappingURL=agents-OGPIHPJH.js.map