@iowarp/clio-coder 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -9,6 +9,128 @@ produced it.
 Versions follow semantic versioning for a pre-1.0 project: minor versions may
 still change interfaces.
 
+## 0.3.2 - 2026-08-20
+
+This release upgrades the engine and hardens the terminal agent. The three engine SDK libraries move to 0.84.0, and a pass over the interactive surface ported the behaviors listed first below. A day of audits against the live code and a Qwen3.8-27B fleet on llama.cpp and LM Studio then produced the defects listed after them; every one is fixed here, each code fix carries a regression test, and the tickets (#110 through #136) carry the evidence.
+
+- Added default-on, evidence-aware Git commit provenance. Commits created through Clio receive only the `Assisted-by`, `Tested-by`, `Reviewed-by`, and contributor-compatible `Co-authored-by` trailers justified by trusted material authorship, successful validation commands, and independent passing review; the human author and committer remain unchanged, normal external commits are untouched, replayed history is skipped, and Settings -> Advanced can disable attribution with byte-for-byte message preservation.
+- Made the `/settings` filter narrow the catalog per keystroke (#135), matching `/model` and `/resume`. The `[/]` editor's draft is now the live query, so rows, section match counts, and the empty state track each character; Enter commits the query and Esc restores the committed one.
+- Named the winning project handbook in `/context` (#136). The overlay showed the preload class only (`full (0.3kB, 11 lines)`) and never said which `CLIO-CODER.md` or `CLIO-CODER.override.md` produced it, which the override semantics make ambiguous; it now lists the effective chain, ancestor to nearest, with workspace-relative paths.
+- Proved at the process boundary that the real built worker entry consumes Clio's injected compile-cache pair before any descendant it spawns can see it (#148). A hermetic smoke drives `dist/worker/entry.js` through one stubbed inference turn whose tool call is a real bash descendant launching a generic Node child; neither inherits Clio's cache directory or marker, while an operator-supplied `NODE_COMPILE_CACHE` reaches both unchanged through matching and mismatched spoofed markers on the direct `clio-coder worker` path.
+- Admitted prompts in the order they were typed during the instant shell's boot window. Two submissions in that window could be answered out of order: `ChatLoop.submit` had no admission gate, so a second submit arriving while the first was still awaiting its target probe and prompt compile ran the same pipeline concurrently, reached the engine first, and left the first recorded in the ledger but never sent. Each submit now waits for the previous one to own the stream or return, then lands as the next steer or follow-up, and the engine's raw active-prompt invariant no longer leaks into the transcript.
+- Made the fullscreen TUI render its transcript. `terminal.tuiMode: fullscreen` painted the header, composer, and footer but left the transcript region blank because the Stage 0 to Stage 1 terminal-lease handoff never attached the transcript to the alternate-screen root.
+- Made the footer's live `↓` and `⚡` counters report the streaming turn instead of the previous turn's totals. A turn cancelled while the model was still reasoning now settles the footer, the `turn · in/out` receipt, and the ledger's closing row to the same estimated spend instead of `↑0 ↓0`.
+- Kept the draft editable when an unknown slash command is rejected. `/compact` and `/skill:foo` failed closed correctly but cleared the editor; rejected input now stays in place and never enters prompt history.
+- Stopped shipping `docs/html` in the npm package. The Markdown guides under `docs/` remain bundled; `clio-coder docs` serves the interactive blueprints from a source checkout and, from an npm install, says where they are instead of serving nothing.
+- Replaced the bold experimental warning in the launchpad, the one-line session header, and the CLI banner with facts. The session header now names where Clio is working, which route answers, and what the context is ready for; the maturity caveat is stated once, in the README.
+
+- Upgraded the three Pi SDK libraries to 0.84.0, bringing Clio the release's provider, OAuth cancellation, terminal rendering, and platform fixes while preserving its own agent loop, session store, and regular-screen TUI behavior. Clio now uses Pi's explicit `TuiMainScreen` renderer and forwards concrete abort signals through built-in and ALCF OAuth refreshes, so a cancelled authentication flow no longer leaves token work running in the background.
+- Added the redacted action class, asking safety axis, and target beneath a tool row parked for approval. The facts use the same transient view as the permission overlay, disappear when the call resumes or settles, and never enter the session ledger.
+- Added Page Up and Page Down navigation to the `/resume` picker, moving by the 12 visible rows while preserving Clio's existing session filtering and ledger behavior.
+- Rendered successful `edit` and `write` calls as numbered diffs in their live tool rows, with word-level emphasis and Clio's add/remove theme colors in regular and fullscreen modes. Replayed and exported diffs remain plain text.
+- Made `/export` write a themed, self-contained, size-bounded HTML transcript by default, with terminal styling converted to HTML and each tool call kept in a semantic row. Passing a `.md` path preserves the existing plain Markdown export.
+- Added durable task, decision, and workspace-output inspection. `/tasks` now combines live work, terminal board history, recorded workspace outputs, and a project operator inbox; `/decisions` preserves settled interviews and operator corrections; `/view` renders task-ledger snapshots and active-branch workspace outputs. The model-facing task ledger and inbox bookkeeping intentionally stays audited as read class without granting workspace mutation authority, and `Alt+B` plus `Alt+D` are approved application-boundary shortcuts for the two boards. Workspace output loading re-resolves the current workspace root and target before every read, refuses symlink swaps outside that root, and retains the recorded missing-file result.
+- Ranked `/model` search with fuzzy matching over provider-qualified search text. Direct `target/model` matches outrank proxy-carried model ids while Clio's availability, authentication, health, runtime, favorites, and recent-model facts remain intact.
+- Routed prompt-template arguments through the engine's command-argument parser and substitution, retiring Clio's second parser. Templates support quoted arguments, `$1` through `$9`, `$@`, `$ARGUMENTS`, and argument slices.
+- Added a maintained engine SDK ownership table, thin-wrapper watch list, regression net, and five-step dependency-upgrade checklist (`docs/pi-boundary.md`) so each release identifies upstream fixes that Clio should inherit and Clio-owned deltas that must remain.
+- Added a checked engine declaration-surface snapshot (`docs/pi-surface.json`). Dependency upgrades now fail lint when an imported SDK symbol changes or disappears and report newly exported primitives for review.
+- Set `AI_AGENT=clio-coder` for spawned commands, fleet workers, registered code steps, and hooks so generic developer tooling can attribute child processes to Clio Coder.
+- Rebuilt the tool transcript as one stable lifecycle block from streamed arguments through live progress and settlement. Expanded calls now expose typed secondary arguments, exit status, counts, displayed and total bytes, truncation, timeouts, usage, added tools, context exclusion, and full-output paths; mixed image results never print base64, admission refusals never masquerade as executions, and operator `!`/`!!` bash commands stream and settle with the same grammar as model tools.
+- Let the engine assemble Anthropic thinking requests from the active thinking level, including adaptive effort and bounded token budgets. Clio removed its competing Anthropic payload rewrite and retains only the OpenAI Responses summary field that the engine's agent loop does not expose.
+- Aligned resumed and forked custom session entries with the engine's model-facing message text. Compaction summaries, branch summaries, and local bash executions now reach the model through the engine's message-text helpers instead of Clio-maintained copies, while Clio keeps its own durable ledger format.
+- Replaced Clio's TypeBox `anyOf` string-enum helper with the engine's compact string-enum schema. Tool schemas keep their exact accepted values and descriptions while avoiding a duplicate schema implementation and preserving the simpler wire form across providers.
+- Connected native tool progress to the engine's cumulative tool-update callback. Bash now streams a throttled, bounded output tail into its existing live transcript row while it runs, so operators see useful command progress without changing approval decisions, final result shaping, or the session ledger.
+- Replaced Clio's copied tool-output truncation implementation with the engine's UTF-8-safe head, tail, line, and size-formatting primitives. Read, search, context, and shell output retain Clio's 16 KiB per-observation ceiling while sharing the engine's maintained byte and line handling.
+- Gave every slash operation one canonical spelling across parsing, autocomplete, help, documentation, and skill guidance. `/quit`, `/context compact`, `/model`, `/settings`, `/skill <name>`, `/run --agent-profile`, and `/run --runtime` are now the only accepted forms; retired aliases fail closed and remain editable, and prompt templates that collide with built-in commands are diagnosed and ignored consistently in interactive and headless runs.
+- Completed fullscreen prompt navigation by marking every Clio user turn with the OSC 133 semantic prompt sequence, so `Ctrl+Shift+Up` and `Ctrl+Shift+Down` now move between real transcript prompts. Clio's editor chrome and transcript export now use the engine's terminal-sequence stripper instead of partial local ANSI regexes, and the optional presentation-settings path retains regular-screen defaults.
+- Made OAuth cancellation reach the complete production credential path. Active agent and background-request signals now cross `providers.auth`, credential mutations carry the engine's signal-aware operation options, cancelled lock waiters leave the live holder alone, and a token aborted before persistence never appears in Clio's in-memory credential view.
+- Fixed refused local commands and unresolved worker steering so the editor's pre-submit clearing restores the draft instead of losing it or recording rejected input in prompt history.
+- Replaced Clio's copied transient-provider regex with the engine's retryable-error classifier. DNS and WebSocket failures now enter the bounded retry ladder, quota, usage-limit, and billing failures stop immediately even when they contain an HTTP retry status, and Clio retains only its longer local-model loading delay and cancellable countdown.
+- Added directory-scoped `CLIO-CODER.override.md` handbooks with an explicit subtree boundary. An override replaces inherited guidance for its directory and descendants without affecting siblings, deeper handbooks may add narrower instructions, prompt blocks retain source paths, malformed overrides fail closed, and reset never deletes an override.
+- Added `Ctrl+P` and `Ctrl+N` prompt history through the editor's dedicated history actions. Accepted chat, slash, local-command, steering, follow-up, and interrupt inputs are available in process-local history, consecutive duplicates collapse, rejected inputs remain editable without polluting history, and browsing forward restores the unfinished draft.
+- Added an opt-in fullscreen TUI built on the engine's alternate-screen layout. Settings → Terminal can select a sticky composer and footer beneath an independently scrollable transcript, with follow-end behavior and a mouse-draggable scrollbar whose visibility is configurable; regular terminal scrollback remains the default.
+- Added terminal-native Mermaid diagrams and Unicode LaTeX to finalized assistant transcripts. Supported `mermaid` fences now become themed box-drawing diagrams when they fit, inline and display math render without a browser, and unsupported or oversized diagrams remain readable as their original source.
+- Made generic OpenAI-compatible, llama.cpp, LM Studio, and vLLM streams tolerant of servers that omit `finish_reason`. The engine now infers a normal or tool-use stop at the clean end of those local streams, so a complete answer is no longer reported as a provider failure solely because its server omitted the optional marker.
+- Routed local OpenAI-compatible sampling through the engine's typed sampling-parameter request path and enabled its bounded `thinking_token_budget` support for vLLM. Family-specific temperature, top-p, top-k, min-p, presence-penalty, and repetition-penalty values still reach llama.cpp and LM Studio byte for byte, while vLLM now reserves room for the final answer instead of allowing reasoning to consume the complete response ceiling.
+- Kept the local `!` bash row live until its command settles. The row froze at its first frame (`running · 7ms`, `no output yet`) because the chat panel classified every replay block as settled; a replay block can now declare itself live, so the elapsed counter ticks, output streams in, and the row leaves the frozen history prefix only when the execution record says it finished.
+- Kept a one-column gutter between a truncated model id and the context column in the `/model` overlay, so a long id no longer runs into the ctx figure and reads as one token.
+- Made the persisted post-compaction token count report what compaction freed. The `/tree` compaction row echoed the pre-compaction figure (`~16276 -> ~16276 tokens`) because the estimator anchored on an assistant message whose usage described the old prompt; the after figure now drops the summarized history, matching the footer's reclaimed-context notice.
+- Made an LM Studio model id mean one loaded instance on one host (#113). LM Studio lists a downloadable key next to its loaded instances and, with LM Link, next to a peer's instances too, and sending the bare key made the server load a second copy of a 27B model behind the operator's back. Clio now resolves a requested id against the target host's loaded instances, never sends a bare key that already has an instance, prefers the target's `defaultModel` and then an instance no other configured LM Studio target reports, flags an id reported loaded by two hosts as an LM Link peer projection and never auto-selects it, and never triggers a load for a key that already has a resident instance. A key with no instance still loads just in time as before.
+- Stopped the llama.cpp residency path from taking a node out of service (#127, #134). Asking for a model id the router does not know used to unload the resident model first and then fail the load, leaving the router empty; the reconciler now refuses the eviction when the replacement is not in the router catalog and reloads what it evicted when a load is rejected for any other reason. A router that reports an idle model as `sleeping` is read as resident instead of being asked to load it again, which had failed every turn with `400 model is already running`.
+- Fixed `/new`, `/resume`, `/tree`, and `/fork` issued while a turn was streaming (#114). The session was switched before the turn settled, so the aborted assistant record landed in the new session as a phantom root and the original session kept a question with no answer; each path now cancels and awaits the in-flight turn so it seals into the session that owns it.
+- Made two dispatch processes stop overwriting each other's run ledger (#118). A ledger persisted every row it had read at open time, reverting a sibling's settled run to `running`, and orphan recovery then stamped that run `dead` with exit 1 without reading its own receipt, which said it succeeded. Only rows a process mutated win on merge, and recovery seals from a verified receipt before declaring a run abandoned.
+- Accepted a target whose settings still say `runtime: lmstudio-native` in the worker spec contract (#119), resolving the alias instead of failing three attempts with an internal mismatch string, and stopped retrying a spec-contract rejection at full cost.
+- Stopped a damaged `credentials.yaml` from wedging `clio-coder upgrade` forever (#121): the provider-rename migration no longer throws on a damaged store when it has nothing to rename, each successful migration is recorded before the next runs, and the upgrade error names `--skip-migrations`.
+- Made the headless JSON stream honor its documented contract (#122). `--json` no longer re-emits every message in full after streaming its deltas, and `--json-events terminal` emits only `session`, `turn_start`, `agent_end`, `turn_end`, and `notice` instead of 40 KB of message bodies for a one-word answer.
+- Brought CLI exit codes back to the documented table (#123): `trace` validates its command and arguments before the no-database courtesy message, `trace sql` mutation refusal and bare `extensions`/`skills` exit 2 with usage on stderr, `trace runs --json` exists, `fleet` rejects unknown flags, `$COLUMNS` widens piped `targets` output, and a real `upgrade` no longer says "would write it".
+- Restored the gemma-4 channel-marker stream filter (#126), now applied on every runtime whenever the resolved family is gemma-4 rather than only on the removed LM Studio SDK path, so chain-of-thought and tool-call channel text no longer leak into the transcript.
+- Fixed `--thinking max` resolving to the lowest active level on families whose effort map stops at `high` (#128); the effective level is now monotonic across the seven configured levels for every catalog family.
+- Made the probed context window win over the catalog's in every consumer (#129). The orchestrator's engine model was sized from the catalog's 262144 while the server served 131072, so `max_tokens` overran the real window on long turns and auto-compaction never fired before the limit; deployment limits now override model metadata at resolution time.
+- Made the LM Studio request carry the resolver's effective reasoning effort (#130), so `xhigh` reaches models that accept it, `mechanism: none` families are not asked to reason, and always-on families are not told `none`. A target's literal `lmstudio.request.reasoning` override of `low`, `medium`, or `high` now outranks the thinking dial but is clamped to the efforts the model advertises, so a model that reports only on and off receives `low`; `auto` keeps the resolver's mapping.
+- Made a stalled stream fail with its reason instead of `Request aborted` (#131). The reclassified stall (`stream stalled: no output from <target> for <n>s`) is now the assistant message and the receipt's `outcomeDetail`, each stalled attempt leaves one assistant row rather than an aborted row beside a corrected one, and a headless provider failure on stderr names the target, runtime, and endpoint it was talking to.
+- Bounded the estimated reasoning-token count to the reported output tokens (#132), gave every receipt the same `node` block on success and failure (#120), made `/export` reject unknown flags and extra arguments like every other command (#115), and marked truncated rows in the expanded notices panel with an ellipsis (#116).
+- Rewrote the Qwen3.8-27B catalog entry's prose as portable hardware classes (#133), removing one operator's node names, one-off timings, and a citation of a deleted source file, and added a catalog test that every cited source path exists.
+- Corrected two documentation claims (#117): `docs/session-lifecycle.md` described `/resume <sessionId>`, an argument the command does not take, and the configuration knob table said `defaults.maxTokens` must be at least 1 while 0 is accepted.
+- Isolated the test suite from the developer's machine (#110, #111). A contract test resolved the real `~/.config/clio-coder/settings.yaml`, overwrote it with malformed YAML, and deleted it; the shared harness now redirects every Clio root into the run's scratch home with `CLIO_CODER_REQUIRE_HOME_PREFIX`, guards it with a canary test, and the welcome-dashboard test no longer reads the checkout it runs in.
+- Gated `npm publish` on version coherence (#124): `scripts/check-release.mjs` fails when `package.json` and the top `CHANGELOG.md` heading disagree or the heading is still `Unreleased`, and the release checklist is rewritten for this version.
+- Replaced the LM Studio SDK path with one HTTP adapter. The canonical runtime is now `lmstudio`, with `lmstudio-native` retained as an in-memory compatibility alias and an upgrade migration for persisted runtime ids, websocket URLs, and stored credentials. Chat, reasoning streams, tools, and usage use `/v1/chat/completions`; probing and residency prefer `/api/v1/models` with v0 and OpenAI listing fallbacks; explicit load and unload use native REST and carry bearer authentication. A target without `lmstudio.load` keeps server just-in-time defaults, while an explicit block controls context length, flash attention, eval batch size, expert count, and KV-cache GPU offload. Every successful load records its returned instance id for this process, and unload or fallback swap refuses every pre-existing or LM Link instance. Same-key LM Link instances are independent, not duplicates. Request settings cover TTL, draft model, and reasoning effort. The LM Studio path never sends `chat_template_kwargs`; its seven Clio thinking levels map to `none`, `low`, `medium`, or `high`, with on/off-only models clamped to `low`. Configure verifies the exact LM Studio greeting before saving, direct and legacy ids both persist canonically, the model catalog no longer promises SDK behavior, and scripted HTTP contract tests cover v1, v0, auth, migration, configuration, loading, ownership-safe release, reasoning defaults, split tool calls, and usage without live model calls.
+- Extended the strict ACP v1 server into the durable control surface an external session-managing client needs without weakening generic clients. A process may now bind its one chat runtime with either `session/new` or standard `session/load`; load authorizes against canonical-workspace history, refuses any unended record it cannot prove is free, resets provider context to the durable pinned branch, and emits only bounded original transcript replay before its response. Namespaced methods list, label, and delete workspace sessions; expose and atomically patch only target, model, thinking level, and global autonomy; list and explicitly probe credential-free target projections; and read or override a bound session's autonomy for its next prompt. New/load results and durable metadata record bind-time target/model attribution, including the TUI `/new` path. Clients may opt into one permanent versioned `clio-coder/event` envelope whose first kind forwards loop-block detector counts without a fabricated tool id, command shape, path, or timestamp authority; clients that do not opt in receive no extension notification. A server-side approval timeout is now audited as `expired`, aborts the turn, suppresses model continuation, and fails the prompt with `permission_expired` instead of inventing a denial the model can retry. Workspace Git identity treats ignored nested scratch roots as non-Git and path-scopes dirty status and recent history for legitimate monorepo subdirectories while preserving the exact workspace as the authority boundary. ACP output additionally bounds live tool titles and location paths, session-list aggregate frames, live tool-call cardinality, and replay tool-call cardinality to fixed reader limits a client can rely on.
+- Hardened `clio-coder acp` into a strict, truthful ACP v1 server so an external client can drive it safely, and corrected `docs/acp.md` to the methods that actually exist. `initialize` must come first, exactly once, with `protocolVersion: 1`; the launch `--cwd` is realpath-canonicalized and is the process's only workspace, so every session opener must carry an absolute `cwd` that canonicalizes to it and the server never falls back to another directory or calls `chdir` after boot (the first `session/new` used to retarget the whole process to any existing directory it named). One successful new or load per process, since one chat instance backs the server and a second session id would share provider context and ledger ancestry. A prompt Clio cannot start (no orchestrator target, no model, unknown target, runtime resolution failure) now fails the `session/prompt` request with `prompt_not_admitted` and a closed-set reason instead of returning an empty `end_turn` with zero usage, which the ACP client could not tell from a model that chose to say nothing. Every error carries its machine-readable detail under `error.data._meta["clio-coder/error"]` and nothing else: no `Error.stack`, no echoed frame, no absolute path, no provider prose (`turn_failed` and `internal_error` messages are fixed host text and the original goes to stderr). Text, thought, tool `content`, `rawInput`, `rawOutput`, and `toolCallId` are bounded in UTF-8 bytes; each tool call has one wire identity across `tool_call`, `tool_call_update`, and `session/request_permission`, the permission request reuses the exact `rawInput`/`locations` snapshot the client already rendered and binds only to a currently open call, and only the exact `allow-once` option grants. `session/cancel` while a permission is parked settles the permission, the parked tool, and the prompt; `session/close` refuses under an active prompt and is idempotent otherwise; a cancelled or failed turn closes every open tool call with a terminal update; stdin EOF waits for the in-flight prompt to settle before the session store stops. The stdio transport bounds an input line at 1 MiB and answers `id: null` requests instead of dropping them. Protected by the ACP contract suites plus a spawned real-server smoke test that drives the built CLI with an isolated `CLIO_CODER_HOME` and a loopback provider stub through a text turn, an admission failure, a tool call with permission allow and reject, and cancel while a permission is parked.
+- Loaded the two wiki dispatch prompts through the same fragment loader every other prompt fragment uses instead of a hand-rolled `readFileSync` (#92). `prompts/fragments/wiki/{page,plan}.md` sat inside the directory `fragment-loader.ts` walks, but `walk()` explicitly skipped any directory named `wiki`; `context/wiki/prompts.ts` read the two files directly and did its own `{{token}}` substitution, with no id, no version, no content hash, and no hot reload. The skip was not an oversight: neither file had real YAML frontmatter, only a decorative leading and trailing `---` line, and `page.md`'s body has its own literal `---` fences (the front matter format the wiki *writer* must produce) that the loader's first-`---`-to-next-`---` frontmatter regex would have matched against instead of a real closing delimiter, corrupting the split and throwing at every Clio startup. Both files now carry real `id`/`version`/`description` frontmatter above their unchanged body, so the loader's existing delimiter search closes on the new marker instead; the old decorative `---` lines are kept as ordinary body text rather than stripped, so the substituted, trimmed prompt text `context/wiki/prompts.ts` sends as a dispatch's `task` is byte-identical to before, verified by comparing the old hand-rolled substitution against the new loader-backed one for both files. `{{token}}` substitution still has no home in the loader itself, the same division `identity.self-awareness`'s `{TOKEN}` placeholders already use in `compiler.ts`: the loader hands back a raw body and the one caller that needs live per-dispatch values fills them in. Grepped `src/` for other hand-rolled prompt-text `readFileSync` calls; the only other `{{token}}` users found (`agents/fleet-contract.ts`, `dispatch/code-step.ts`, the fleet `.md` templates) already have their own strict, validated template contracts and are a different system. No builtin worker system prompt changes size: the wiki fragments were never part of `compileWorker`'s output, only ever a dispatch's dynamic task text.
+- Gave `compileWorker` the `additionalFragments` channel `compile()` already had, so active project rules and the operator profile reach a dispatched worker (#96). Both are built once per compile in `prompts/extension.ts` and were injected for the main session only; a coder worker editing a file under an active `.clio-coder/rules/**` path never saw the rule that governed it, the layer inversion the user-editable configuration is supposed to prevent. Project rules are scoped to the worker's inferred working context, so a worker whose task never touches a ruled path does not carry that rule's text. That context is `writeRoots`, when the caller sets them, plus path-like tokens recalled from the task and briefing text, since the model-facing `dispatch` tool has no structured path field; a missed path token means a rule can go unseen, never fabricated, because `selectActiveRules` still requires a real glob match. The operator profile renders unconditionally, the same as it does for the session, because it governs how the worker should do the task (validation preference, commit-message style, local-only paths), not only how the orchestrator talks to the operator. The channel is `additionalFragments`, rendered last after persona: nothing splices into an existing worker section, the pattern a7faa133 removed. Measured with a matching rule and a profile both firing: +289 bytes per builtin (+3,468 across the twelve, 66,472 to 69,940); the operator profile alone is +178 bytes per builtin; a worker whose task touches nothing ruled pays 0.
+- Made `/tree` switch and `/fork` of the same turn reconstruct the same state, and fixed the task board following the abandoned branch after a switch (#94). Live replay after a `/tree` switch kept every unanchored sidecar (`taskLedger`, routing notices, a leafless `workerRun`) regardless of where it sat in the file, while `/fork` dropped anything written after the fork point; `filterEntriesToActivePath` (`src/domains/session/tree/active-path.ts`) and `fork.ts`'s `sessionEntryBelongsToPath` now share one `entryBelongsToPath` verdict, so both surfaces exclude a sidecar written after the leaf's position. The task board's own fold (`task-board.ts:181-187`) was a second, independent copy of the same bug: it took the last `taskLedger` entry in raw file order with no branch filter at all, so a plain `/resume` on a branched session could show whichever branch happened to write last, not just a `/tree` switch; `readEntries` now runs through the same active-path filter (`src/entry/orchestrator.ts`). The board's session-id-keyed cache (`task-board.ts:327-336`) also never noticed a `/tree` switch, since that only moves the append point inside the same session; a new `SessionTurnSwitched` bus event and a `TaskBoardStore.invalidate()` method fix that. Also: the `/tree` pin is now persisted to `meta.pinnedLeafTurnId` and cleared on the next append, so a switch made without a follow-up message survives quit and resume instead of reverting to the abandoned tip via timestamp inference; `/tree` marks the active tip with its own glyph; and Enter on a compaction or branch row is inert with a status message instead of throwing `turn not found`.
+- Replaced the doc routing table in the system prompt with a directive to call `context(scope="docs")`. `identity.self-awareness` carried a 42-row "topic -> docs/file.md" table, 2,410 bytes of every session prompt, guarded by its own first line ("read these only when the user asks about Clio herself; never for ordinary coding work") and growing by one row per doc. The docs engine already indexes every bundled `docs/*.md` and every search response lists the whole corpus, so the table was resident knowledge the model could fetch in one call; measured on the current index, 39 of the 42 rows rank their document in the top five from the bare row label and all 42 from a natural question. The new `identity.docs-routing` fragment tells the model to call `context(scope="docs", query=<the question>)` before answering and before any grep, find, or read when asked about Clio herself, phrased as an instruction rather than a note that docs exist, because a note is what once sent the model grepping the workspace for a skill; it renders only when `context` is on the surface, the same gate the Skills passage uses. The paths, the code-outranks-docs rule, and the configuration locations stay unconditional. Session prompt drops from 15,724 to 13,314 bytes; workers are unchanged.
+- Added a `skills-pin` check to `scripts/check-hygiene.ts`, run by `npm run lint`. `skills/registry.yaml` drifting from an edited skill's content was only caught by `npm run skills:check`, which runs inside the full `ci` chain and nowhere else; a5d50940 landed a stale `clio-test` pin from `be2b5ccb` that sat unnoticed for two days because nobody's local lint run ever exercised it. The new check shells out to `pin-skills.ts --check`, the same command `skills:check` runs, so lint and the full gate share one definition of "stale" instead of two. `npm run lint` wall time moves from 4.4s to 5.1s.
+- Made the worker read the same safety text the session reads, and corrected two things that text said. The four `safety.<level>` fragments were rendered for the session only; a dispatched worker got a hand-written copy of the four levels from a `switch` in `compiler.ts`, and the copy drifted: its full-auto branch said "Writes, dispatches, and ordinary commands run" for workers none of which admit dispatch, and its auto-edit branch never said which commands are recognized or that `$(...)` is always approval-required, so a worker learned those only from its first denied call. The `switch` is gone; both renderers read the one fragment body, and the fragments now speak in the safety net's action classes and never name a tool, so nothing in them can be false for a surface that lacks one. Two session-side statements were wrong against the engine and are fixed in passing. `safety/auto-edit.md` said "Commands with pipes, `&&`, or redirects count as unrecognized and ask", while `policy-engine.ts` recognizes and runs a `&&` chain whose every step is recognized; it now says "a `&&` chain whose every step is recognized runs too" and lists pipes, `;`, `||`, redirects, newlines, and a chain with an unrecognized step as the unrecognized forms. `safety/read-only.md` said only "The safety net applies at every autonomy level" where the other three levels name `git_destructive`; it now carries the same sentence. Workers gain the auto-edit detail (about 500 bytes per builtin) and no authority: the worker's engine loads the same builtin allowlist and the same `.clio-coder/safety.yaml`, and already denies the same calls.
+- Removed `test:isolated` from the package scripts. It ran the same contracts and smoke globs `test:coverage` runs, minus the coverage flags, through the same per-file `test:file` invocation, so `npm run test:file -- 'tests/contracts/**/*.test.ts' 'tests/smoke/**/*.test.ts'` reproduces it exactly. `test:repeat` stays: it is the one lane that reruns smoke shuffled to catch order- and timing-dependent flakes a single deterministic pass cannot, and `.github/workflows/ci.yml` runs it on every push. The CI workflow already runs one release gate on both node lanes with no `if: matrix.node-version` guard hiding a check from either one; the single remaining guard skips the coverage summary step on node 24 because coverage is a report about the suite rather than a check of it, and paying node's per-file instrumentation twice would only post the same numbers to the job summary twice.
+- Said each routing rule once. The session prompt told the model seven times, in five places, that broad repository exploration goes to a worker, and the phrasings disagreed: the operating contract and two Tool Contract lines said use `agent:"auto"`, while `FLEET_ROUTING_GUIDANCE` said auto "is a fallback, not a router" and the Fleet roster said broad recon goes to `scout`. Skills guidance was stated in five places. The Tool Contract now keeps only what nothing else says (complete surface, harness model, inventory rule, narrow-orientation tools, validate before claims, retry-shape recovery, the fleet pin rule); the Retrieval Hints keep only what is and is not preloaded; and the single surviving broad-exploration rule, in `operating.delegation`, is the pinned one: hand it to a worker before repo-wide reads, pinning `scout` when the roster lists it. The session prompt loses 1,360 bytes and no capability: every deleted sentence has one surviving statement in a passage that renders exactly when its tool does.
+- Split the operating contract into a constitutional layer and role layers. One file, `operating/contract.md`, was carrying the coordinator's delegation and receipt discipline, the `/share` note, the skills passage, and the shared posture, and the worker compiler was regex-splicing it into a second document; every one of the 12 builtin workers was told to use `dispatch` and `agent:"auto"` although no builtin admits `dispatch` (#91). `operating.contract` now holds only what is true for every reader; `operating.delegation` renders for the session only when `dispatch` is on its tool surface and `operating.skills` only when `context` is, the same rule the Fleet block already followed; `operating.worker` holds the assigned-task contract that used to be inline TypeScript with no fragment provenance. The worker operating contract shrinks from 3,638 to 1,575 bytes for every builtin, the twelve worker prompts from 84,952 to 60,196 bytes total, and no session sentence was removed: the one-shot approval semantics moved from the contract paragraph into the session's safety section, where the level fragments they qualify are.
+- Gave an installed Clio a skills marketplace she can see. Asked how a catalog skill worked, an installed Clio grepped the operator's own project for the skill's name, found nothing, and gave up; asked to list the marketplace, she returned the operator's personal skills. Three defects produced that. `discoverMarketplaceSkills` resolved its index to `<configDir>/skill-marketplace.json`, which nothing ever writes, and never consulted `resolvePackageRoot`, so the `skill-marketplace.json` the tarball ships was read by nothing and an install had no marketplace at all; both the index and the package's own catalog now fall back to the package root, so bare-name search and install work offline against local files. `context(scope="skills")` read installed roots only and never consulted the marketplace, so the one skills surface the model has could not show an installable skill however well configured the marketplace was; it now renders a marketplace section, and loading an uninstalled name explains how to install it rather than reporting an unknown skill. Every prompt string said "installed skills" and the retrieval hint routed questions about where skills live to grep, which is exactly what the model did; the prompt text now names installable skills and routes those questions to `context`. The package ships all 31 skills rather than 7, plus `skills/registry.yaml` so provenance pinning resolves for an installed copy, costing 0.2MB unpacked and 0.08MB on the wire. A new fresh-install suite exercises the path from a foreign working directory with the catalog environment variables blanked, which is the configuration every existing skills test missed and the reason this shipped.
+- Kept the marketplace out of workers and made the skills reminder fire on a fresh install. An unbound worker holding the context tool began seeing marketplace rows it could do nothing with, alongside prose telling it to suggest the skill to an operator it has no channel to address; marketplace rows are now suppressed for every worker registry and the skills passage is stripped for all workers, leaving a worker the skills it was given and nothing else. Bound workers were never affected and the capability boundary is unchanged. Separately, the once-per-session skills reminder is the one channel that reliably makes a model consider a skill, and it was gated on the installed count being above zero, so the operator most likely to benefit from learning that skills exist was the one operator never told; it now counts installed plus installable and says both.
+- Moved the static-analysis checks out of the test runner. Nine files under `tests/` read source, docs, README, config, and script text off disk and asserted on their structure while executing no product code; `export-hygiene` alone cost 57.9 seconds, the second most expensive file in the suite. `scripts/check-hygiene.ts` now runs all ten rules in one process against one read of the tree, wired into `npm run lint`, and every assertion moved with them. `npm test` drops from 1,760 CPU-seconds to 1,465 and from 160 seconds wall to 124. The boundaries test lane is gone; `check-boundaries.ts` remains as a library the lint imports.
+- Restored the streaming display coalescer. The raw engine wrapper that precedes every derived text and thinking delta was classified as a synchronous event, so each provider chunk cancelled the pending 16 ms display frame and forced an immediate render request; the coalescer was defeated exactly while a response streamed, which is the one time it exists for. Wrappers carrying text or thinking deltas, which the panel has always ignored, now stop at the renderer instead of reaching it; tool-call formation keeps its synchronous path, and every event the panel acts on arrives in the same order as before.
+- Enabled Node's V8 compile cache for the boot-path module graphs: interactive chat, `run`, `acp`, and native fleet workers. Locally spawned workers inherit the directory through their spawn environment and consume it before any of their children can see it; SSH-placed workers enable the remote install's own cache in-process at the worker entry, with nothing exported to their children. Read-only and dry-run commands never enable it, `paths` and bare `doctor` keep their promise that nothing is created, and the cache enables only on an initialized install so a home Clio never set up stays untouched. `NODE_COMPILE_CACHE` and `NODE_DISABLE_COMPILE_CACHE` always win, and a cache failure never affects a command. The import-only and real-PTY fill/hit observations, with their deliberately narrower endpoint names, are recorded in `docs/performance-methodology.md` rather than generalized into a per-command saving.
+- Corrected boot and TUI performance instrumentation before using it for 0.3.2 decisions. `first TUI paint` is now marked only after the first real frame has issued all of its stdout writes; explicit frame ids group diff, ANSI, hardware-cursor, and IME writes; canonical event and input ids correlate queue, panel, and committed-frame high-water marks; and stdout return, backpressure, and drain are recorded. The trace writer is bounded, asynchronous, awaited at shutdown, and nonfatal on storage failure. A deterministic contract plus a real built-CLI PTY harness cover first frame, input, resize, grouped writes, paused output, and process reaping. The documented metrics are stdout/PTY endpoints, never an in-process claim of literal glass latency.
+- Added the adaptive stream pacer as `terminal.smoothStreaming: off | auto | on`, with the conservative 0.3.2 default left at `off`. Only derived visible text and thinking are paced, through one ordered generation queue; raw text/thinking wrappers remain transparent and public events, transcript persistence, tool formation, cumulative tool state, and ordered boundaries remain synchronous. Pacing is grapheme-safe, arrival-credit and oldest-age bounded, self-stopping, folded-thinking aware, and forced to settle before abort, retry, submit, mode change, final return, or teardown. Fullscreen frozen scrolling and resize survive paced updates, and stdout backpressure gates frame construction rather than creating a second unbounded SSH buffer. `auto` bypasses non-TTY, remote/multiplexed, CI, accessibility-marked, and backpressured sessions; `CLIO_CODER_SMOOTH_STREAM=off` is the immediate per-process escape hatch. Deterministic fake-clock, ordering, grapheme, reset, folded-thinking, scroll/resize, no-drain, and built-CLI PTY contracts cover the rollout.
+- Added a measured instant interactive shell through one `TerminalLease`, enabled by default with `CLIO_CODER_INSTANT_SHELL=0` as the immediate rollback. Stage 0 and Stage 1 share the exact terminal, TUI, root host, editor, raw mode, decoder, resize subscription, terminal queries, signal router, and stop lifecycle; hydration swaps roots and delegates atomically instead of adopting reconstructed state. Typed drafts and cursor state survive, early submissions are visible immutable FIFO admissions dispatched exactly once after the application attaches, and diagnostics are serialized into the hydrated TUI or emitted after terminal restoration. Boot failure, Ctrl+C before or after attachment, SIGTERM, and a stale hydration all converge on exactly-once terminal restoration and recover accepted input. ACP, headless, ordinary non-TTY invocation, help, and subcommands never mount Stage 0; the explicit force-interactive non-TTY override is preserved. Built-graph contracts keep its closure at five chunks/90,654 bytes and out of provider/tool/codewiki graphs; real PTY acceptance covers early input, multiple submits, resize during hydration, protocol initialization once, failure recovery, signals, and raw-mode restoration. Corrected Stage 0 commit, PTY receipt, and Stage 1 hydration observations are reported separately in `docs/performance-methodology.md`.
+- Removed the eager userland Undici graph from `web_fetch` and use the Node 22.19+ built-in Fetch, Headers, Request, Response, stream, and abort implementation. Localhost contracts preserve request headers/body, redirects, UTF-8 streaming and cancellation at the byte ceiling, external abort, timeout, HTTP previews, binary rejection, and transport errors on both supported Node lines; an installed-tarball turn invokes the real tool from a foreign working directory. The built graph contains no Undici source or dependency, while the measured size and deliberately mixed import-time observations are recorded without turning host noise into a boot claim.
+- Made codewiki's tree-sitter graph genuinely lazy and moved runtime indexing off the interactive event loop. Lightweight schema, artifact, and path modules preserve synchronous cached reads without evaluating the builder; actual full, stale, and incremental builds run in a dedicated worker and load only the required grammars. Session startup, parallel `code_nav` demand, mutation batches, explicit index/refresh, bootstrap, wiki grounding, and reset now share one per-workspace generation queue and cross-process lease, so an older build cannot overwrite newer state or resurrect a reset artifact, and shutdown drains admitted work. Built-source and installed-tarball coverage prove nested help is tree-sitter-free and write-free while a real foreign-cwd build loads the runtime and its vendored grammar; measurements and deliberately scoped import observations are in `docs/performance-methodology.md`.
+- Split `context`, `code_nav`, `verify`, `web_fetch`, `dispatch`, `monitor`, and `steer` into immutable lightweight tool surfaces and first-use implementation chunks. Registration order, provider schemas and descriptions, policy metadata, execution modes, argument normalization, admission, permissions, middleware, result shaping, and worker surface attestation remain registry-owned and eager; only an admitted runner imports code. Dispatch keeps its trusted plan and capacity-reservation identities in one synchronous admission controller shared with the lazy runner, deeply freezes every execution-affecting control before middleware or approval can observe it, binds the `apply_winner` repository destination into the approval hash and text, and releases a guard-blocked prepared admission exactly once. Workers import only the core tool bootstrap, so their built entry never evaluates the three orchestrator-only runners. Concurrent first calls share one import, an implementation whose surface drifted fails closed, unrelated tools remain absent, and a missing Clio-owned chunk carries the same named reinstall guidance as a missing command chunk. V8 coverage repeats the absent-before-use/present-on-invocation proof for every tool and the worker exclusion against both the source build and an installed tarball from a foreign working directory.
+- Removed the eager `pi-ai/compat` and all-provider aggregates from ordinary engine startup. Clio's engine boundary now owns the ordered API dispatcher and its pinned synchronous environment-key lookup while composing only the nine Pi provider factories backed by current Clio runtimes; Pi still owns their public lazy APIs, catalog data, authentication and headers, Bedrock loader, OAuth flows, faux provider, and image registrar. A configured out-of-tree runtime activates a one-time compatibility bridge immediately before plugin evaluation, preserving the existing process-global registry identity and last-writer-wins overrides; a failed bridge prevents that plugin from evaluating. Without a plugin the aggregate, unconfigured provider catalogs, legacy aliases, unrelated provider bodies, OAuth flows, and image generator remain unevaluated. Source and installed foreign-cwd coverage prove both sides of the graph boundary, provider contracts preserve payload and cancellation behavior, every credential mapping is parity-checked against Pi 0.84, and an installed plugin overrides a known API through the shared external Pi instance.
+
+## 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.
@@ -63,9 +185,8 @@ still change interfaces.
 - Made `clio-coder reset` and `clio-coder uninstall` say what they are about to destroy and what survives. The reset preview lists each root's real children with counts and gives every scope a note, and the help defers to that listing rather than describing it. Uninstall enumerates the per-project `.clio-coder/` directories recorded in session metadata and names `clio-coder context reset --all` before the roots and the launcher are touched, because the record it reads lives inside a root it is about to remove and the cleaner is a subcommand of the binary `--remove-binary` is about to delete. Per-project directories are still not removed by uninstall; this makes the ordering visible rather than closing the gap.
 - Made a failed settings reload render as one width-clamped notice from the shared settings formatter instead of an inspect dump and a stack trace that corrupted the frame. Read, parse, and schema failures are distinguished, the remedy matches the kind and leads the detail so frame clamping cuts context rather than the fix, the raw YAML source fragment is gone, and the previous good configuration stays active. Doctor's settings row and the thrown error use the same helpers.
 - Fixed `clio-coder targets --probe` writing fixed-width rows that ignored the terminal. The id column never truncates, url and model truncate with an ellipsis, `--json` stays untruncated, and surplus width goes to url and model before the tier column, which had let four distinct hosts render identically at 120 columns while the group header already carried the tier.
-- Added slash aliases for the spellings people actually type: `/exit` resolves to `/quit`, `/config` to `/settings`, and `/compact` to `/context compact`, with aliases offered in tab completion ranked below their canonical commands. A rejected unknown command now clears the composer rather than leaving the text to concatenate with the next keystrokes into a message to the model.
 - Made the TUI tell the truth about a denied tool call and about usage the ledger was hiding. A denial renders as the dialog outcome and status alone, the collapsed row reads `bash(id) ✗ blocked` instead of claiming the call `ran`, and no parked-approval line survives the decision. `/context compact` persists its summarization usage on the compaction entry and moves `/cost` immediately, so a real model call stops being invisible to every usage surface. A cancelled turn now persists estimated usage marked `estimated: true` in the shape a completed turn uses, rather than the all-zero block the cancel path used to write beside real streamed text, and `/cost` readers skip it. `/tree` shows the fork parent and the compaction and branch nodes, and replay no longer dumps `custom:promptRecompiled` JSON into the transcript. The stop-turn notice no longer doubles the usage line onto the empty assistant entry it splits open, and a settled entry holding nothing renders nothing instead of an empty bubble.
-- Made overlay footers say what Esc will do from where the overlay is right now. The verb was derived from whether an overlay committed anything, which produced `cancel` on half of them and `close` on the other half while neither word described the key: a list overlay clears a typed filter on the first Esc and closes on the second, and the footer said `close` through both. The caller names the action now, out of a fixed vocabulary of `close`, `clear filter`, and `back`, and `/models` and `/resume`, which close on the first Esc, say so instead of advertising a filter they do not clear. Every overlay uses one filter vocabulary.
+- Made overlay footers say what Esc will do from where the overlay is right now. The verb was derived from whether an overlay committed anything, which produced `cancel` on half of them and `close` on the other half while neither word described the key: a list overlay clears a typed filter on the first Esc and closes on the second, and the footer said `close` through both. The caller names the action now, out of a fixed vocabulary of `close`, `clear filter`, and `back`, and `/model` and `/resume`, which close on the first Esc, say so instead of advertising a filter they do not clear. Every overlay uses one filter vocabulary.
 - Fixed a repair masquerading as an install. `initializeClioHome` stamped `installedAt` when it had only repaired an existing home, so the install date moved every time doctor rebuilt the skeleton. A repair writes `repairedAt`, `install.json` accepts either stamp, and doctor prints whichever exist. The doctor damage row groups identical messages instead of repeating one error three times.
 - Made every cost surface claim only what something measured. The cost aggregate could not tell nothing-priced from priced-at-zero, so the footer asserted `$0.00` before any turn had run while `/cost` on the same session said no usage was recorded, and after a real turn against a target that publishes no pricing both printed the literal words `cost unknown` where a number belongs. The aggregate carries its call count, one formatter answers every surface, and a surface with no priced call shows no cost field at all. Usage and cost are separate claims: the tokens were counted whatever the pricing did, so the session total stays on screen and only the cost field disappears. A fixed-width cell that owns a cost column cannot drop the field, so it says `not measured` in words rather than inventing a number.
 - Made the footer describe the branch on screen rather than the whole ledger file. `current.jsonl` is append-only, so after a `/tree` switch the abandoned sibling turns are still in the file: the transcript stopped showing them while the session total, `/cost`, and the last-turn status line kept counting and describing them. All three now fold through the same active-path lineage the transcript replays, on `/tree`, `/resume`, and `/fork`. The footer's chip strip also ranks its chips, so the chip budget and the width budget both shed per-turn detail first and the session total last; it used to slice whatever sat at the end of the list, which cost an 80-column terminal both the total and the cost chip while spending the whole budget on per-turn detail. Two fields the ledger does not record are left neutral on a rescoped line rather than reconstructed: the watchdog peak, and reasoning tokens no provider reported.

package/CONTRIBUTING.md

@@ -63,25 +63,26 @@ output in-process while the reporter runs.
 
 ## Releasing
 
-Releases are tag-driven and publish from CI. Nothing is published from a
-workstation.
+Releases are cut from a tag. The GitHub release is created by CI; the npm
+publish is a manual maintainer step. The ordered procedure for a cut lives in
+[docs/release-cut-checklist.md](docs/release-cut-checklist.md).
 
-1. Bump `version` in `package.json` and retitle the `unreleased` section in
-   `CHANGELOG.md` to the version being cut.
+1. Bump `version` in `package.json` and retitle the top section of
+   `CHANGELOG.md` to the version being cut. `scripts/check-release.mjs` fails
+   when the two disagree or the heading still says `Unreleased`.
 2. Run `npm run ci:release`. It runs the full `ci` gate, then
    `scripts/check-release.mjs`, which verifies the built `dist/` and audits
    the exact npm package contents.
-3. Land the release commit through the normal PR flow.
-4. Tag and push: `git tag vX.Y.Z && git push origin vX.Y.Z`. The tag must
+3. Land the release commit on `main` and let the `ci` workflow go green on
+   that commit.
+4. Tag and push: `git tag -a vX.Y.Z && git push origin vX.Y.Z`. The tag must
    match `package.json`'s version; the release workflow refuses mismatches.
-5. `.github/workflows/release.yml` verifies the tag against `package.json`,
-   reruns the full gate, and creates the GitHub release with the tarball
-   attached. The npm publish step runs only when the repository variable
-   `NPM_PUBLISH` is `true` and the `NPM_TOKEN` secret holds an automation
-   token that can publish `@iowarp` packages; with the variable unset the
-   step is skipped and the GitHub release is still created. A maintainer may
-   run the first publish manually (`npm login && npm publish`);
-   `prepublishOnly` runs the same `ci:release` gate either way.
+5. `.github/workflows/release.yml` requires a successful `ci` run for the
+   tagged commit, verifies the tag against `package.json`, builds `dist/`,
+   runs `scripts/check-release.mjs`, and creates the GitHub release with the
+   tarball attached. It does not publish to npm.
+6. A maintainer publishes from the tagged commit with `npm publish`;
+   `prepublishOnly` runs the same `ci:release` gate first.
 
 What `scripts/check-release.mjs` enforces, and how to respond when it fails:
 
@@ -92,14 +93,15 @@ What `scripts/check-release.mjs` enforces, and how to respond when it fails:
   a forbidden file appears, fix the `files` allowlist in `package.json`
   rather than deleting the file from the repo.
 - Runtime resources must resolve from the installed package root: prompt
-  fragments, builtin agents, model catalogs, `docs/html`, the 128px logo,
+  fragments, builtin agents, model catalogs, the Markdown guides in `docs/`, the 128px logo,
   and `damage-control-rules.yaml`. A new runtime resource must be listed in
   both package.json `files` and the required list in `check-release.mjs`.
   The double bookkeeping is deliberate: neither edit can silently drop a
   resource the CLI needs at runtime.
-- Size budgets: 2 MB tarball, 6 MB unpacked. If a legitimate change exceeds
-  them, raise the budget in the same PR with a justification, never as a
-  drive-by.
+- Size budgets: 15 MB tarball, 40 MB unpacked, set in `check-release.mjs`.
+  They are a tripwire for packaging defects such as a leaked `node_modules`
+  or a doubled `dist/`, not a diet. If a legitimate change exceeds them,
+  raise the budget in the same PR with a justification, never as a drive-by.
 
 Build shape, for anyone changing `tsup.config.ts`: two ESM entries with code
 splitting on. `src/cli/index.ts` imports every subcommand dynamically, so a
@@ -130,11 +132,9 @@ The boundary checker enforces these:
   all other worker domain imports must be type-only.
 - Domain independence: cross-domain flows go through `SafeEventBus`.
 
-Run:
-
-```bash
-npm run check:boundaries
-```
+The checker runs as part of `npm run lint` (`scripts/check-hygiene.ts` imports
+`tests/boundaries/check-boundaries.ts`), so a boundary violation fails the
+same lint every PR runs.
 
 ## Branches