@iowarp/clio-coder 0.3.0 → 0.3.2

package/docs/tui-design.md

@@ -1,7 +1,7 @@
 # Clio TUI Design System
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive color/glyph token laboratory and terminal transcript preview renderer is located at [docs/html/tui_design_blueprint.html](html/tui_design_blueprint.html) (Version: 0.3.0).
+> **Interactive Spec Available:** An interactive color/glyph token laboratory and terminal transcript preview renderer is located at [docs/html/tui_design_blueprint.html](html/tui_design_blueprint.html) (Version: 0.3.2).
 
 This document is the reference specification for the Clio Coder TUI visual layout, styling, and behavior. It describes color semantics, the glyph vocabulary, structural recipes, and state choreography for all surfaces under [src/interactive/](../src/interactive/).
 
@@ -19,7 +19,7 @@ All color styling is defined in [src/interactive/theme/tokens.ts](../src/interac
 |---|---|---|
 | `accent` | `rgb(70, 229, 208)` (Teal) | Brand and interactivity: frame titles, selection highlight, keybinding/slash-command affordances, agent voice glyphs, tool verbs, and active/writing phases. |
 | `accentDeep` | `rgb(31, 183, 166)` | Structural emphasis only: bold CAPS section tags. |
-| `action` | `rgb(255, 126, 41)` (Orange) | Active autonomous operations: dispatching phase pills, active fleet badges, running fleet indicators, and user-steering queues. |
+| `action` | `rgb(255, 126, 41)` (Orange) | Active autonomous operations: dispatching phase pills, active fleet badges, running fleet indicators, running connect/probe indicators, and user-steering queues. |
 | `success` | `rgb(87, 227, 137)` (Green) | Positive outcomes: success indicators (`✓`), ok health status, clean git trees, and output-token count updates. |
 | `warning` | `rgb(255, 180, 84)` (Amber) | Real warnings only: stale data, dirty trees, retry status, blocked tools, and truncation. |
 | `error` | `rgb(255, 92, 102)` (Red) | Failures: error indicators (`✗`), error rails, stuck states, and error message text. |
@@ -36,6 +36,7 @@ All color styling is defined in [src/interactive/theme/tokens.ts](../src/interac
 - Color is used functionally to indicate state. If removing a color does not lose information, the text is colored using `dim`, `muted`, or left unstyled.
 - `warning` amber is reserved for true warnings. Costs and neutral telemetry numbers use `muted`.
 - `accentDeep` is used only in section tags. Metric values (such as TTFT, tokens-per-second, and autonomy status) use `muted`.
+- `action` neon orange remains scarce and strictly disciplined: only while Clio is acting or a prompt owns the keyboard (e.g. running connect/probe operations, active dispatch/fleet execution, or the keyboard-owning confirmation border / `STEER` mode). It is never used for idle decoration or settled telemetry, and never appears on more than one element per screen region.
 - Per-surface color budgets limit noise: chip strips use at most one non-neutral token per chip, and framed cards use at most one status token alongside neutral colors.
 
 ---
@@ -46,7 +47,7 @@ All symbols are defined as constants in [src/interactive/theme/glyphs.ts](../src
 
 | Glyph | Name | Meaning | Used by |
 |---|---|---|---|
-| `>C_` | `brand` | Clio wordmark | Welcome header and dashboard header only. |
+| `>C_` | `brand` | Clio wordmark | Welcome launchpad header, session header, and dashboard header only. |
 | `✦` | `agent` | Agent voice | Chat reply prefix (accent; error red on failed turns). |
 | `›` | `user` | User voice | Chat user prefix (accent); steering queue marker (action). |
 | `❯` | `cursor` | Selection focus | Settings, list overlays, selectors. |
@@ -75,7 +76,7 @@ All symbols are defined as constants in [src/interactive/theme/glyphs.ts](../src
 | `─` | (rules) | Horizontal rule and borders | Frames and rules. |
 | `╌` | `innerDivider` | Divider inside a frame | Task island, any framed list. |
 | `·` | (dotSep) | Chip separator (dim) | Everywhere. |
-| `◆ ◇` | `active/scoped` | Active and scoped marks | Model selector, thinking selector. |
+| `◆ ◇` | `active/scoped` | Active and scoped marks | Model selector, thinking selector, Settings profile workbench. |
 
 ---
 
@@ -139,21 +140,60 @@ Drawn as `<key padded, dim> <value>`, where the value defaults to `muted` unless
 ### 4.6 Narrow Terminal Behavior
 
 All TUI overlays and cards support compact widths down to 40 columns:
-- Split overlays such as `/view` fall back to a single pane layout with `[Tab]` switching between the artifact list and details.
+- Split overlays such as `/view` fall back to a single-pane layout with `[Tab]` switching between the artifact list and details.
 - Keybinding hints, cards, and markdown detail text wrap fluidly without horizontal clipping.
-
+- Settings provides a dedicated drill-down stack below 72 columns.
 
 ---
 
-## 5. State Choreography
+## 5. Screen Surfaces & State Choreography
+
+The Clio screen maintains a responsive, four-zone structure: the launchpad / session header, transcript, composer, and footer. `terminal.tuiMode` chooses the renderer at startup. The default `regular` mode uses terminal scrollback. Opt-in `fullscreen` mode uses the alternate screen: the launchpad/header and transcript occupy an independently scrollable viewport while the follow-up queue, composer, and footer remain docked at the bottom.
+
+In fullscreen mode, `PageUp` and `PageDown` scroll one viewport, `Home` and `End` jump to its bounds, `Ctrl+Shift+Up` and `Ctrl+Shift+Down` jump between semantic prompts, and the mouse wheel scrolls the transcript. Dragging the scrollbar thumb moves the viewport directly. `terminal.fullscreenScrollbar` is `hidden`, `auto` (visible during interaction), or `always`. Manual scrolling suspends follow-end so new output does not steal the operator's position; returning to the bottom resumes it. Both fullscreen settings are restart-scoped because Clio constructs its terminal renderer and component graph once at startup.
+
+`terminal.smoothStreaming` controls presentation-only pacing of derived assistant text and thinking. `off`, the 0.3.2 release default, is the existing immediate 16 ms coalescer. `auto` paces only on a capable local TTY and bypasses pacing for non-TTY, SSH, multiplexers, CI, screen-reader/reduced-motion markers, or observed stdout backpressure. `on` explicitly requests grapheme-safe pacing, while still stopping frame production behind stdout backpressure. Raw provider wrappers never enter the panel, canonical events and persistence remain synchronous, and tool/message/turn/abort/retry/submit/teardown boundaries drain visible state before they continue. `CLIO_CODER_SMOOTH_STREAM` is the one-process escape hatch and takes precedence over settings; invalid values resolve to `off`.
+
+Interactive startup uses one terminal lease across both boot stages. Stage 0 owns the terminal, renderer, root host, exact editor instance, input decoder, raw mode, resize subscription, protocol queries, signals, and stop lifecycle, and commits a measured minimal frame while services hydrate. Hydration synchronously swaps the root and input/signal delegates without reconstructing the editor or initializing terminal protocols again. Early Enter submissions become immutable, visibly queued admissions and drain once through the ordinary command pipeline; a later draft and cursor stay in the same editor. Boot failure or an early signal closes the lease exactly once, restores the terminal, and prints recoverable queued input and draft text. `CLIO_CODER_INSTANT_SHELL=0` selects the legacy fully hydrated first frame; ACP, headless, ordinary non-TTY invocation, and subcommand execution never acquire the lease. An explicit `CLIO_CODER_INTERACTIVE=1` retains its established force-interactive behavior on a non-TTY stream.
+
+### 5.1 Welcome Launchpad & Session Header
+
+- **Pre-Submit Launchpad**: Before the first prompt, renders a compact launchpad at line 0 with bold CAPS section tags (`WORKSPACE`, `ROUTE`, `NEXT`), honest readiness state, and a context-sensitive next action (e.g. `ctx missing · /context init`, `ctx checking…`, or `ctx ready · type a task`). Asynchronous repository probes use height-stable dim placeholders (`factsPending`).
+- **Session Header Collapse**: On first user submission, the launchpad deliberately collapses into an immutable, single-line session header (`>C_ Clio Coder vX.Y.Z · <workspace · git branch> · <target·model · ready> · ctx ready · type a task`) so the conversation transcript owns the viewport while the header keeps naming where Clio works, which route answers, and what the context is ready for.
+
+### 5.2 Composer (ClioEditor)
+
+- **Mode Section Tag**: The top rail features an explicit left section tag indicating prompt semantics:
+  - `MESSAGE` (dim/teal) while idle.
+  - `FOLLOW-UP` (muted) while Clio is actively processing a run.
+  - `STEER` (neon orange) when Enter will actively steer in-flight work.
+  - When the draft scrolls, the active mode folds into the scroll indicator row so the orange warning remains visible.
+- **Top Rail Metadata**: The top rail right displays target/model and thinking level with two-step color hierarchy: `off` (dim), `minimal`/`low` (muted), `medium`/`high` (`reason` purple), and `xhigh`/`max`/`on` (bold `reason` purple).
+- **Empty-State Placeholder**: Displays dim prompt `Ask Clio…  / for commands`.
+- **Lower Rail Affordance**: On terminals at or above 60 columns, the bottom rail displays `Enter send · Shift+Enter newline` (or resolved keybindings).
 
-The Clio screen maintains a fixed structure: banner, transcript, editor rail, and footer. State is signaled through the status pill in the footer and matches the following table:
+### 5.3 Progressively Disclosed Footer
+
+- **Compact Mode (Quiet Idle)**: Two always-on lines that eliminate idle telemetry noise (suppresses `tools none`, `◌ idle`, and default-output tags):
+  - **Line 1 (Workspace & Readiness)**: CWD path, git branch/dirty state, and active phase pill only when meaningful.
+  - **Line 2 (Context & Receipt)**: Context window meter and the best current/last-turn receipt.
+- **Expanded Mode (`Alt+U`)**: Four responsive sections ordered by operational urgency rather than a static telemetry grid:
+  1. `Activity`: Live agent phase, active workers, running tool calls.
+  2. `Context`: Context window gauge, breakdown, token headroom.
+  3. `Session`: Session cost, throughput, total token breakdown, leader key state.
+  4. `Workspace`: CWD, branch, target, git dirty status.
+  Empty rows collapse rather than occupying blank grid space.
+- **Notification Badge & Degradation Ladder**: The footer notification badge reserves the severity head (`ℹ 1 notice`, `⚠ 1 warning`, `✗ 1 error`), separator, and `[Alt+X] dismiss` tail first, allocating the middle width to an ellipsized message. At narrow widths, it degrades gracefully down the ladder (`head · [Alt+X] dismiss` → `head · [Alt+X]` → `head` → glyph alone) without clipping the action key.
+
+### 5.4 State Choreography Table
+
+State is signaled through the status pill in the footer and matches the following table:
 
 | State | Pill | Transcript Echo | Action Orange? |
 |---|---|---|---|
-| idle | `◌ idle · tools none` (muted) | None; last-turn telemetry on line 2 | No |
+| idle | Quiet (phase omitted; line 1 shows workspace, line 2 shows context/receipt) | None; last-turn telemetry on line 2 | No |
 | preparing / waiting | spinner + `waiting` (info) | None | No |
-| thinking | spinner + `thinking` (reason) | Dim `Thinking (N tokens)...` marker | No |
+| thinking | spinner + `thinking` (reason) | Dim `Thinking (N tokens)…` marker | No |
 | writing | spinner + `writing` (accent) | Streaming markdown text | No |
 | tool running | spinner + `tool <name>` (accent) | `▸` tool execution ledger line | No |
 | blocked | `⏸ blocked` (warning) | Permission prompt surface | No |
@@ -161,33 +201,52 @@ The Clio screen maintains a fixed structure: banner, transcript, editor rail, an
 | compacting | spinner + `compacting` (reason) | None | No |
 | dispatching / fleet live | spinner + `dispatch` (action) | Task island status updates | Yes |
 | stuck | `⚠ stuck 12s` (error) | Inline watchdog warning | No |
-| done | `✓ done` (success), then telemetry | Settled transcript blocks | No |
+| done | `✓ done` (success), then quiet telemetry | Settled transcript blocks | No |
 
 ---
 
 ## 6. Agent and Transcript Formatting
 
-### 6.1 Voices
+### 6.1 Voices & Hanging Indent
 - **User**: `› text` with the user glyph in `accent`.
-- **Agent**: `✦ text` with the agent glyph in `accent` (turning `error` red on failed turns, along with the text message).
+- **Agent**: `✦ text` with the agent glyph in `accent` (turning `error` red on failed turns, along with the text message). Skill suggestions do not claim the `✦` reply glyph.
+- **Two-Cell Hanging Indent**: User and assistant prose are rendered with a fixed two-cell gutter. The first line begins with the turn prefix (`› ` or `✦ `), while all wrapped continuation lines indent by two spaces (`PROSE_GUTTER = "  "`), keeping multiline text visibly attached to its voice glyph.
 
 ### 6.2 Thinking Blocks
-Drawn as a folded dim marker (`Thinking (N tokens)...` or `Thinking...`), which expands into a body using the `reason` color vertical `│` rail. Cap of 12 lines.
+Drawn as a folded dim marker (`Thinking (N tokens)…` or `Thinking…`), which expands into a body using the `reason` color vertical `│` rail. Cap of 12 lines.
 
 ### 6.3 Tool Ledger
-Tool lines wrap as a single composed block:
+Every tool call owns one stable transcript block for its complete lifecycle. Streamed
+`toolcall_*` message updates first expose the call as `forming call`, the completed argument block
+becomes `ready`, `tool_execution_start` changes the same row to `running`, and cumulative
+`tool_execution_update` results replace the live body until `tool_execution_end` settles it. Rapid
+tool updates are coalesced to terminal frame rate; settlement always renders immediately.
+
+The collapsed form is one composed ledger line:
 ```
-▸ verb object · resource · facts · size ✓ · 230ms · full: path (ctrl+o)
+▸ verb(object) · resource · facts · size ✓ · 230ms · full: path (Alt+O)
 ```
-- Verb is bold `accent`, tail details are `dim`, status glyph is semantic (`✓`/`✗`), and the keyboard shortcut hint is appended at the end.
+- Verb is bold `accent`, tail details are `dim`, status glyph is semantic (`✓`/`✗`), and the keyboard shortcut hint is appended at the end. Tool ledgers maintain full terminal width and bypass the prose hanging indent.
+- Expanded calls show the primary argument in the signature and every secondary argument as a typed field list. Multiline argument bodies become line and byte facts, nested objects retain structured rendering, and safety-sensitive values remain redacted.
+- Running calls label `live output` and replace the cumulative partial result in place. Settled calls label `output` and show available exit status, result or observation counts, line count, displayed and total byte sizes, truncation, timeout, tool-token usage, dynamically added tools, context exclusion, and the full-output path. A blocked or aborted admission instead labels its `decision` and does not claim that the tool ran.
+- A call parked for one-shot approval replaces its running timer with `awaiting approval` and shows the already-sanitized action class, asking safety axis, and target below the row. These facts are transient UI state: approval, denial, abort, or settlement clears them, and they are never reconstructed from the session ledger.
+- Text and image tool results keep their text while rendering images as MIME and byte-size placeholders; base64 image data is never written to the terminal.
+- Successful `edit` and `write` calls render the bounded diff produced by the tool result. Live regular-screen and fullscreen rows color removed and added lines with the `error` and `success` tokens and emphasize changed words; `/resume` replay and `/export` keep the same numbered diff as plain text.
+- Operator `!` and `!!` bash commands use the same running and settled block as model-initiated bash. The block appears before the process starts, streams the throttled cumulative stdout/stderr tail, and settles in place while the existing `bashExecution` session entry remains the durable record. `!!` continues to exclude that record from model context and says so in the block.
 
 ### 6.4 Editor Rail
-The right-hand label shows `model · thinking`. Thinking level colors map as: `off` (dim), `minimal`/`low` (muted), and `medium` and above (purple `reason`).
+The right-hand label shows `model · thinking`. Thinking level colors map as: `off` (dim), `minimal`/`low` (muted), `medium`/`high` (`reason` purple), and `xhigh`/`max`/`on` (bold `reason` purple).
 
 ### 6.5 Transcript Notices
 Replay and system tags (e.g. `[retry]`, `[model]`) are wrapped in `dim` brackets with a `muted` message. Retry tags use `warning` amber.
 
-### 6.6 Code Ink (Syntax Highlighting)
+### 6.6 Output Verbosity Receipts
+Turn usage receipts rendered at the bottom of completed turns respect the output verbosity configuration:
+- `minimal`: Omits the turn usage receipt entirely.
+- `default`: Renders one compact dim receipt: `turn · in <N> · out <M>`.
+- `verbose`: Renders the full receipt with model call counts (`over N calls`), cache reads/writes (`cache R/W`), reasoning tokens with provenance (`reasoning N provider` or `reasoning ≈N estimated`), and the verification caveat (`· reasoning text is a UI excerpt, not a verification`).
+
+### 6.7 Code Ink (Syntax Highlighting)
 
 Syntax highlighting within code blocks is handled by [src/interactive/renderers/code-ink.ts](../src/interactive/renderers/code-ink.ts). It maps a restricted set of four tokens to stay quiet:
 
@@ -198,18 +257,52 @@ Syntax highlighting within code blocks is handled by [src/interactive/renderers/
 
 All other code elements (identifiers, types, function names, punctuation) remain plain. Diff blocks highlight added lines with `success` green and removed lines with `error` red.
 
----
+### 6.8 Mermaid and LaTeX
 
-## 7. v0.2.9 TUI & Cost Provenance Transformations
+Finalized assistant Markdown renders inline and display LaTeX as terminal-friendly Unicode through
+the Markdown renderer. For example, `$x^2$` becomes `x²` without requiring an image-capable
+terminal.
 
-### 7.1 Fleet Visibility Across Surfaces
-- **Dispatch Board**: Displays per-run status cards with node assignments (`local` vs remote node ID), reroute badges, gate indicators (`gate reviewer c2`), live tool activity, and context occupancy meters.
-- **`/fleet` Overlay**: Modal overlay allowing operators to view running dispatches, inspect node capabilities, edit profile node pins, and monitor worker heartbeats.
-- **Parked Tools & Approvals**: Parked tool calls awaiting permission are rendered as `⏸ awaiting approval` with explicit approval prompts. Input overlays stay modal during active runs so background completions do not displace open dialogs.
+Top-level fenced `mermaid` blocks pass through the width-aware Markdown `transform` hook and the
+engine's Unicode-diagram strategy. Supported flowcharts, state diagrams,
+class diagrams, entity-relationship diagrams, and sequence diagrams render with quiet `frame`
+borders, plain labels, and `accent` connectors. If a diagram is invalid, unsupported, or wider than
+the transcript content width, Clio leaves the original Mermaid fence visible instead of clipping or
+silently dropping it. Mermaid transformation runs only after an assistant text segment is finalized,
+so partial fences never flicker into incomplete diagrams while streaming.
+
+---
 
-### 7.2 Cost Provenance & Evidence Rendering
-- **Session vs Run Provenance**: The Activity footer renders session token/cost totals, while the dispatch board and `/fleet` overlay render per-run worker tokens and cost with `known`, `estimated`, or `unknown` provenance markers. The current surfaces do not present a separate orchestrator-versus-worker algebra.
-- **Proof Markers**: Dispatch cards and `/fleet` rows render evidence readiness as `proof` markers (`pending`, `ready`, or `failed`) from the observability projection. Model-facing dispatch and monitor output use `receipt_integrity=verified/v15/sha256` and a separate `evidence_verification` label; the TUI does not emit a `[VERIFIED_RECEIPT_OK]` badge.
+## 7. Settings Center & Command Overlays
+
+### 7.1 Settings Center Architecture
+The `/settings` overlay is a full-screen transactional control center:
+- **Group Structure**: Sections are organized under non-selectable section headers:
+  - `CORE`: Autonomy & Safety (`safety`), Orchestrator (`orchestrator`)
+  - `ROUTING`: Fleet (`fleet`), Targets (`targets`), Models (`models`)
+  - `RUNTIME`: Budget (`budget`), Compaction (`compaction`), Retry (`retry`)
+  - `EXPERIENCE`: Terminal (`terminal`), Advanced (`advanced`)
+- **Semantic Row Grammar**: Explicit presentation kinds (`setting`, `status`, `action`, `group-header`, `read-only-fact`, `destructive-action`) prevent confusion between focus (teal), health (green/amber/red), modified status (neutral/teal mark), and active operations (scarce orange).
+- **Transactional Edits**: Selecting a row and pressing `Enter` opens a dedicated value picker, input dialog, or checklist rather than immediately toggling values. Edits construct an immutable `SettingsChangePlan` and present explicit destination choices:
+  - `Apply this session` (for live-capable settings)
+  - `Apply and save globally`
+  - `Cancel` (or `Esc`)
+  - Restart-required settings (`budget.concurrency`, `runtimePlugins`, `terminal.tuiMode`, and `terminal.fullscreenScrollbar`) offer only global save and announce `Saved to settings.yaml · restart Clio to apply`.
+  - Destructive actions (target/profile removal) execute preflight analysis showing affected chat, fleet, and memory routes before confirmation.
+- **Fleet Workbench**: Organizes fleet settings with dim group headers (`Defaults`, `Profiles`, `Agent routes`, `Placement`). Profiles render as one-row summaries with `◆ Edit` affordance; pressing `Enter` drills into profile fields (target, model, thinking level, placement) or destructive removal.
+- **Targets Console Table**: Displays configured targets in an operational console table (`HEALTH`, `ID`, `ROLES`, `RUNTIME`, `LATENCY`) with an in-place action/detail drawer (URL, default model, last probe, failure reason). Actions include `Use`, `Connect`, `Probe`, and `Remove`. Active connect/probe operations show the single orange activity indicator.
+- **Scoped Models Checklist**: Settings → `Models` provides a provider-backed checklist subview with target-level and target/model items, checked current selections, `Space` to toggle, and capability details in the inspector. Unresolved model references are preserved under an `Unavailable` group.
+- **Narrow Terminal Drill-Down Navigation**: Below 72 columns, Settings transitions from a split view to a modal drill-down stack (section list → section rows → detail drawer) with a breadcrumb and `Esc` moving up one level before closing. Includes `/` filtering across label, path, and description, narrowing per keystroke like `/model` and `/resume`. Below 60 columns, side margins are removed for full-width presentation.
+
+### 7.2 Task and Decision Boards
+
+- **Composite Tasks Board (`/tasks`, `Alt+B`)**: Presents four sections in one reopenable overlay: the live session board, terminal task history, successful workspace artifacts, and project-scoped operator tasks. Selecting a workspace artifact opens the filtered `/view` path. Operator rows support add, hand, done, and drop actions; refresh is explicit for captured history and artifacts, while lightweight repaint reads the current board snapshot.
+- **Settled Decisions Board (`/decisions`, `Alt+D`)**: Groups completed and cancelled interviews on the active branch, expands source questions and answers, and lets the operator supersede a value or submit a correction. Corrections travel through the ordinary operator-turn path after the durable decision snapshot is updated.
+- **Approved editor overrides**: `Alt+B` and `Alt+D` are deliberate application-input boundary overrides of Pi's editor word-back and word-delete chords. Clio routes them before the editor so the two global boards remain one chord away. They are explicit exceptions to the general rule that Clio app bindings avoid Pi editor reserves, and users may rebind the Clio actions in `settings.yaml`.
+
+### 7.3 Slash Autocomplete Command Palette
+- **Grouped Palette**: Typing `/` opens a grouped command palette (ordered by `Run`, `Inspect`, `Configure`, `Sessions`) with compact argument hints and formatted descriptions.
+- **One Canonical Spelling**: Autocomplete, help, and parsing expose the same unique slash-command names; no alias rows compete with canonical commands.
 
 ---
 

package/docs/worker-dispatch-mechanics.md

@@ -1,7 +1,7 @@
 # Worker Dispatch Mechanics
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive NDJSON protocol timeline stream and heartbeat watchdog simulator is located at [docs/html/worker_dispatch_blueprint.html](html/worker_dispatch_blueprint.html) (Version: 0.3.0).
+> **Interactive Spec Available:** An interactive NDJSON protocol timeline stream and heartbeat watchdog simulator is located at [docs/html/worker_dispatch_blueprint.html](html/worker_dispatch_blueprint.html) (Version: 0.3.2).
 
 This document describes the design and lifecycle of Clio Coder dispatched workers, focusing on the spawning sequence, execution isolation, the standard input/output NDJSON communication loop, and permission escalation routing.
 
@@ -63,7 +63,7 @@ Clio divides worker output into two isolated streams to protect control signals
 2. **Control Lane (`stderr`)**:
    Emits out-of-band control frames prefixed by `@clio-control/1 `, capped at `WORKER_CONTROL_FRAME_MAX_BYTES` (16 KiB). Because control frames travel over `stderr`, they bypass backpressured bulk stdout streams and reach orchestrator watchdogs immediately. Control frame kinds include:
    * **Announce:** `{"kind": "announce", "attestation": ...}` sent immediately upon startup.
-   * **Heartbeat:** `{"kind": "heartbeat", "at": 1720186123000}` emitted every 1000 milliseconds.
+   * **Heartbeat:** `{"kind": "heartbeat"}` emitted every 1000 milliseconds. The frame carries no timestamp; the orchestrator stamps arrival on its own clock.
    * **Steer / Cancel Acknowledgments:** Confirming reception of stdin control directives.
 
 ### 2.2 Worker Input (`stdin`)
@@ -87,7 +87,7 @@ Any stdin chunk that is not a valid JSON structure matching these schemas is log
 
 Even when a model is processing a long thinking phase or generating a heavy output, the worker must prove it is alive to prevent the parent orchestrator's watchdog from reclaiming it.
 
-* **Emission:** The heartbeat loop (`startWorkerHeartbeat` in `src/worker/heartbeat.ts`) writes a heartbeat control frame (`{"kind": "heartbeat", "at": ...}`) to the `stderr` control lane every 1000 milliseconds.
+* **Emission:** The heartbeat loop (`startWorkerHeartbeat` in `src/worker/heartbeat.ts`) writes a heartbeat control frame (`{"kind": "heartbeat"}`) to the `stderr` control lane every 1000 milliseconds.
 * **Stream Isolation:** Because heartbeats ride the control lane rather than `stdout`, a large bulk output or queued tool result cannot starve or delay the watchdog check.
 * **Non-Blocking Timer:** The heartbeat timer interval is explicitly `.unref()`'d, ensuring the Node.js runtime is not kept alive past the natural lifetime of the worker run.
 * **Termination:** Once `startWorkerRun` resolves, the timer is cleared before returning the worker's exit code.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@iowarp/clio-coder",
-	"version": "0.3.0",
+	"version": "0.3.2",
 	"description": "Coding agent for HPC and scientific-software developers, part of IOWarp's CLIO ecosystem of agentic science.",
 	"keywords": [
 		"ai",
@@ -42,19 +42,16 @@
 	"bin": {
 		"clio-coder": "dist/cli/index.js"
 	},
+	"exports": {
+		"./package.json": "./package.json"
+	},
 	"files": [
 		"dist",
 		"!dist/**/*.map",
 		"assets/clio-coder-logo-128.webp",
-		"src/domains/agents/builtins/**",
-		"src/domains/agents/fleets/**",
-		"skills/workflow/cut-it/**",
-		"skills/git/**",
-		"skills/skill-marketplace.json",
-		"src/domains/providers/models/**",
-		"src/domains/prompts/fragments/**",
+		"src/**",
+		"skills/**",
 		"docs/*.md",
-		"docs/html/**",
 		"README.md",
 		"CHANGELOG.md",
 		"CONTRIBUTING.md",
@@ -68,52 +65,45 @@
 		"access": "public"
 	},
 	"scripts": {
-		"build": "tsup",
+		"build": "tsup && node --import tsx scripts/build-codewiki-asset.ts",
 		"dev": "tsup --watch",
 		"clean": "rm -rf dist",
 		"typecheck": "tsc -p tsconfig.tests.json",
 		"format": "biome format --write .",
-		"lint": "biome check .",
-		"check:boundaries": "node --import tsx --import ./tests/harness/tmp-root.ts --test 'tests/boundaries/**/*.test.ts'",
+		"lint": "biome check . && node --import tsx scripts/check-hygiene.ts",
+		"pi:surface-diff": "node --import tsx scripts/pi-surface-diff.ts",
+		"pi:surface-snapshot": "node --import tsx scripts/pi-surface-diff.ts --write",
 		"test:file": "node --import tsx --import ./tests/harness/tmp-root.ts --test",
-		"test:smoke": "node --import tsx --import ./tests/harness/tmp-root.ts --test 'tests/smoke/**/*.test.ts'",
-		"test:contracts": "node --import tsx --import ./tests/harness/tmp-root.ts --test 'tests/contracts/**/*.test.ts'",
-		"test": "node --import tsx --import ./tests/harness/tmp-root.ts --test 'tests/contracts/**/*.test.ts' 'tests/smoke/**/*.test.ts' 'tests/boundaries/**/*.test.ts'",
-		"test:coverage": "node --import tsx --import ./tests/harness/tmp-root.ts --test --experimental-test-coverage --test-coverage-include='src/**/*.ts' --test-coverage-exclude='src/**/*.d.ts' 'tests/contracts/**/*.test.ts' 'tests/smoke/**/*.test.ts' 'tests/boundaries/**/*.test.ts'",
+		"pretest": "test -f dist/assets/codewiki.json && [ -z \"$(find src -newer dist/assets/codewiki.json -type f -print -quit)\" ] || npm run build",
+		"test": "node scripts/shard-tests.mjs",
+		"test:coverage": "node scripts/test-coverage.mjs --experimental-test-coverage --test-coverage-include='src/**/*.ts' --test-coverage-exclude='src/**/*.d.ts' 'tests/contracts/**/*.test.ts' 'tests/smoke/**/*.test.ts'",
 		"test:repeat": "node tests/harness/repeat-tests.mjs",
 		"test:trace-viewer": "npm --prefix apps/trace-viewer test",
 		"trace:ui": "node apps/trace-viewer/server.mjs",
 		"ci": "npm run typecheck && npm run lint && npm run skills:check && npm run build && npm run test && npm run test:trace-viewer",
 		"ci:release": "npm run ci && node scripts/check-release.mjs",
+		"install:local": "bash scripts/install-local.sh",
+		"prepublishOnly": "npm run ci:release",
+		"skills:pin": "node --import tsx scripts/pin-skills.ts",
+		"skills:check": "node --import tsx scripts/pin-skills.ts --check",
+		"//": "below here: real providers or a live model target, cost money and/or time, never run in CI",
 		"test:live": "node scripts/live-smoke.mjs",
 		"test:live-eval": "node scripts/live-eval-recon.mjs",
 		"test:live-eval:fleet-dispatch": "node scripts/live-eval-fleet-dispatch.mjs",
 		"test:live-verify:dispatch-routing": "node scripts/live-verify-dispatch-routing.mjs",
+		"test:lifecycle": "node --import tsx scripts/lifecycle-matrix.mjs",
 		"bench:swe": "python3 benchmarks/community/swe-bench-lite/swebench_clio.py",
 		"bench:scicode": "python3 benchmarks/community/scicode/scicode_clio.py",
-		"bench:tb": "python3 benchmarks/community/clio_fleet.py",
-		"install:local": "bash scripts/install-local.sh",
-		"prepublishOnly": "npm run ci:release",
-		"skills:pin": "node --import tsx scripts/pin-skills.ts",
-		"skills:check": "node --import tsx scripts/pin-skills.ts --check",
-		"test:lifecycle": "node --import tsx scripts/lifecycle-matrix.mjs"
+		"bench:tb": "python3 benchmarks/community/clio_fleet.py"
 	},
 	"dependencies": {
 		"@anthropic-ai/claude-agent-sdk": "0.3.186",
-		"@earendil-works/pi-agent-core": "0.83.0",
-		"@earendil-works/pi-ai": "0.83.0",
-		"@earendil-works/pi-tui": "0.83.0",
-		"@lmstudio/sdk": "1.5.0",
+		"@earendil-works/pi-agent-core": "0.84.0",
+		"@earendil-works/pi-ai": "0.84.0",
+		"@earendil-works/pi-tui": "0.84.0",
 		"@silvia-odwyer/photon-node": "^0.3.4",
-		"@vscode/tree-sitter-wasm": "^0.3.1",
-		"chalk": "5.6.2",
-		"diff": "9.0.0",
-		"ollama": "0.6.3",
-		"tree-sitter-wasms": "^0.1.13",
-		"typebox": "1.3.0",
-		"undici": "8.5.0",
-		"uuid": "14.0.1",
-		"yaml": "2.9.0"
+		"grok-mermaid": "0.2.2",
+		"ollama": "0.6.3"
 	},
 	"overrides": {
 		"@anthropic-ai/sdk": "0.105.0",
@@ -123,10 +113,17 @@
 	"devDependencies": {
 		"@biomejs/biome": "2.5.1",
 		"@types/node": "24.12.2",
+		"@vscode/tree-sitter-wasm": "^0.3.1",
+		"chalk": "5.6.2",
+		"diff": "9.0.0",
 		"esbuild": "0.28.1",
 		"node-pty": "1.1.0",
+		"tree-sitter-wasms": "^0.1.13",
 		"tsup": "8.5.1",
 		"tsx": "4.22.4",
-		"typescript": "6.0.3"
+		"typebox": "1.3.0",
+		"typescript": "6.0.3",
+		"uuid": "14.0.1",
+		"yaml": "2.9.0"
 	}
 }

package/skills/README.md

@@ -57,10 +57,9 @@ folder is presentation and provenance, not a namespace.
 
 | Skill | Type | Use when |
 |---|---|---|
-| [`commit-crafting`](git/commit-crafting/) | workflow | The user asks to commit finished work. One atomic conventional commit, explicit-path staging, no push. |
-| [`review-changes`](git/review-changes/) | workflow | Pre-commit review of uncommitted work: real bugs and security, verified findings, severity-ranked report. |
-| [`create-pr`](git/create-pr/) | workflow | The user asks to push the branch and open a PR. Base detection, state gates, structured body, URL back. |
-| [`investigate-issue`](git/investigate-issue/) | workflow | A GitHub issue needs diagnosis before a fix: parallel exploration, evidence-cited why-chain, reviewable RCA. |
+| [`file-ticket`](git/file-ticket/) | workflow | Something noticed mid-session must become a tracker issue: capture evidence, dedup, compose, confirm, create via gh. |
+| [`fix-issue`](git/fix-issue/) | workflow | A tracker issue should be resolved: diagnose only the unknown, fix test-first, self-review against the issue's acceptance criteria. |
+| [`ship`](git/ship/) | workflow | Finished work leaves the machine: one atomic conventional commit referencing the issue, gated push, PR on explicit intent. |
 | [`worktree-create`](git/worktree-create/) | workflow | Stand up isolated worktrees for parallel branches: detected install/config/health-check, per-worktree verification. |
 | [`worktree-merge`](git/worktree-merge/) | workflow | Integrate finished worktree branches through a throwaway integration branch with per-merge tests and a full final gate. |
 | [`resolve-merge-conflicts`](git/resolve-merge-conflicts/) | workflow | A merge/rebase is stopped on conflicts. Resolves from both sides' reconstructed intent, validates, completes the operation. |
@@ -316,7 +315,7 @@ hash is exact, and drift detection uses the hash.
 
 The invariant is that a catalog skill dropped unmodified into `.claude/skills`
 loads and runs in Claude Code. Verified against Claude Code 2.1.231:
-`skills/git/commit-crafting` copied into a scratch project's
+`skills/git/ship` copied into a scratch project's
 `.claude/skills/`, invoked headlessly, loaded through the `Skill` tool and
 answered a question about its own body. The `clio:` block is an unknown
 frontmatter key there and is ignored.
@@ -362,7 +361,7 @@ The rest of the surface, read from the same build:
 Degradation summary for a catalog skill running under Claude Code: it loads,
 its body drives the workflow, and its tool narrowing does not apply. A skill
 whose safety argument rests on narrowing (`ast-grep` is search-only,
-`review-changes` does not write) is advisory there and enforced here.
+`ship` cannot edit source) is advisory there and enforced here.
 
 ## Contributing / approval
 

package/skills/coding/ast-grep/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: ast-grep
+description: Use when a code search needs structure, not text — "find all async functions without error handling", "find calls with this argument shape", "find X inside Y" — or when grep returns too much noise to filter. Writes and tests ast-grep rules, then scans the codebase. Search only; never rewrites code. Not for plain string or filename lookups; use grep or find.
+version: 0.1.0
+license: Apache-2.0
+allowed-tools:
+  - bash
+  - read
+  - write
+  - grep
+  - ls
+clio:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/coding/ast-grep
+  audit: pass
+  provenance: adapted
+  origin: https://github.com/coleam00/skills/tree/main/.claude/skills/ast-grep
+  eval-status: scenarios-recorded
+  model-size: any
+  agents:
+    - main
+---
+
+# ast-grep Structural Search
+
+Translate a structural question into an ast-grep rule, prove the rule on a
+tiny example, then scan the real codebase. Never scan first: an untested rule
+that returns nothing tells you nothing.
+
+Search only. Never use `--update-all` / `-U` / `--rewrite`; when matches need
+changing, report them and edit through the normal edit tools.
+
+## Step 0 — Check the binary
+
+```bash
+command -v ast-grep || command -v sg
+```
+
+If neither exists, say ast-grep is not installed (`cargo install ast-grep` or
+the platform package) and stop. Some installs expose only `sg`; use whichever
+resolved.
+
+## Step 1 — Pin down the question
+
+Before writing any rule, state: the target language; the structure to match;
+what must be included and excluded. If the request is ambiguous on any of
+these, ask one clarifying question instead of guessing.
+
+## Step 2 — Write a minimal example
+
+Write the smallest code snippet that MUST match (and, when exclusions matter,
+one that must NOT match) to a scratch file, e.g. `/tmp/astgrep-example.js`.
+This is the rule's test fixture.
+
+## Step 3 — Write the rule, simplest first
+
+Escalate only when the simpler form fails:
+
+1. `pattern` alone for direct shapes: `console.log($ARG)`.
+2. `kind` plus relational rules (`has`, `inside`) for context: "function
+   containing await".
+3. Composite rules (`all`, `any`, `not`) for logic: "has await but no
+   try-catch".
+
+Non-negotiable: every relational rule (`has`, `inside`) carries
+`stopBy: end`, or traversal stops at the first non-matching child and the
+rule silently under-matches.
+
+```yaml
+# /tmp/astgrep-rule.yml
+id: async-no-trycatch
+language: javascript
+rule:
+  all:
+    - kind: function_declaration
+    - has: {pattern: await $EXPR, stopBy: end}
+    - not:
+        has: {pattern: 'try { $$$ } catch ($E) { $$$ }', stopBy: end}
+```
+
+Full syntax (atomic, relational, composite rules, metavariables, `constraints`,
+`utils`): read `references/rule_reference.md` when the rule needs more than
+the three forms above.
+
+## Step 4 — Test against the example
+
+```bash
+ast-grep scan --rule /tmp/astgrep-rule.yml /tmp/astgrep-example.js
+```
+
+Prefer a rule file over `--inline-rules`: inline YAML in shell needs `$VAR`
+escaped as `\$VAR` (or single quotes), and quoting errors look exactly like
+non-matches.
+
+The rule must match the positive example and miss the negative one before
+you scan anything real. When it does not, debug in this order:
+
+1. Strip the rule to its simplest positive key; re-add parts one at a time.
+2. Confirm every `has`/`inside` has `stopBy: end`.
+3. Dump the tree to check node kinds — never guess a `kind` name:
+
+```bash
+ast-grep run --pattern '<target code>' --lang javascript --debug-query=cst
+```
+
+(`cst` = every node; `ast` = named nodes only; `pattern` = how ast-grep
+parsed your pattern.)
+
+## Step 5 — Scan the codebase
+
+Simple one-node patterns skip the rule file:
+
+```bash
+ast-grep run --pattern 'console.log($ARG)' --lang javascript .
+```
+
+Rule-based scans:
+
+```bash
+ast-grep scan --rule /tmp/astgrep-rule.yml <path>
+```
+
+Add `--json` when the output feeds further processing. Report matches as
+`path:line` with a one-line reading of each; do not paste raw JSON at the
+user. Done when the reported matches answer the Step 1 question and false
+positives you noticed are either excluded by the rule or called out. Delete
+the scratch files.
+
+## Red flags
+
+- Scanning the codebase with a rule never proven on an example.
+- A `has`/`inside` without `stopBy: end`.
+- A guessed `kind` name instead of a `--debug-query=cst` dump.
+- Any rewrite flag: this skill only reads.
+- Falling back to grep halfway because rule debugging felt slow — fix the
+  rule with Step 4; that is the job.

package/skills/coding/ast-grep/evals.md

@@ -0,0 +1,56 @@
+# Evals — ast-grep
+
+Baseline scenarios (run a subagent WITHOUT the skill to capture the gap, then
+WITH the skill to confirm it closes). Rubric is pass/fail per bullet. Status:
+written at port time, not yet executed (`eval-status: untested`).
+
+## S1 — structural search with context
+Setup: find async functions that await something but have no error
+handling.
+
+Fixture:
+```bash
+mkdir -p src
+printf 'async function fetchUser(id) {\n  const res = await fetch("api" + id);\n  return res.json();\n}\n\nmodule.exports = { fetchUser };\n' > src/users.js
+printf 'async function fetchSafe(url) {\n  try {\n    const res = await fetch(url);\n    return await res.json();\n  } catch (err) {\n    return null;\n  }\n}\n\nmodule.exports = { fetchSafe };\n' > src/safe.js
+printf 'function plainSync(a, b) {\n  return a + b;\n}\n\nmodule.exports = { plainSync };\n' > src/plain.js
+```
+
+Expected:
+- Writes a positive and a negative example file before any repo scan.
+- Rule uses `kind` + `has`/`not` with `stopBy: end` on every relational rule.
+- Tests the rule on the examples first; scans the repo only after it passes.
+- Reports matches as path:line, not raw JSON.
+
+## S2 — unknown node kind
+Setup: rule fails to match the example. Prompt continues from S1.
+Expected:
+- Uses `--debug-query=cst` to read the real node kinds; does not guess.
+- Simplifies the rule and re-adds parts instead of abandoning to grep.
+
+## S3 — rewrite temptation
+Setup: user asks "find and fix all console.log calls".
+Expected:
+- Uses ast-grep for the find only; never passes `-U`/`--update-all`.
+- Applies changes through the ordinary edit tools after reading matches.
+
+## Baseline failure modes to watch for (RED)
+- Scanning the whole repo with an untested rule and reporting "no matches".
+- Missing `stopBy: end`, silently under-matching.
+- Escaping errors in `--inline-rules` read as "pattern doesn't match".
+- Guessed `kind:` names that do not exist in the grammar.
+
+## Smoke record (2026-08-13)
+
+One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning
+(30B local, llamacpp on mini), full-auto sandbox. NOT SMOKED: ast-grep binary absent on the eval host (2026-08-13). Needs the binary, then a re-run.
+
+Follow-up (2026-08-13): the durable fix considered here was a typed read-only
+`ast_grep` tool in `src/tools`, which would drop the binary dependency from the
+skill body and let read-only recipes such as `scout` bind structural search
+directly. Not built: a new tool is a new entry in the canonical tool surface,
+which means a name reserved in `core/tool-names.ts`, an action class and
+concurrency rule, admission and profile entries, and prompt-prefix cost paid by
+every run whether or not anyone searches structurally. That is a tool-surface
+decision, not skill-catalog cleanup. Until then the skill stays
+`scenarios-recorded` and its first step is the binary check it already has.