@iowarp/clio-coder 0.3.1 → 0.3.3

package/docs/session-lifecycle.md

@@ -1,6 +1,6 @@
 # Session Lifecycle
 
-This document is the authoritative specification for Clio Coder interactive and headless session lifecycles, on-disk ledger structures, tree-based conversation branching, checkpoints, and recovery protocols in `v0.3.1`.
+This document is the authoritative specification for Clio Coder interactive and headless session lifecycles, on-disk ledger structures, tree-based conversation branching, checkpoints, and recovery protocols in `v0.3.3`.
 
 Source implementations: `src/engine/session.ts` and `src/domains/session/`.
 
@@ -43,7 +43,7 @@ export interface ClioSessionMeta {
 }
 ```
 
-Format version `CURRENT_SESSION_FORMAT_VERSION = 3` (`src/engine/session.ts:66`) is stamped on all sessions created in `v0.3.1`. Sessions with missing or earlier format versions trigger schema migrations in `src/domains/session/migrations/` on `/resume`.
+Format version `CURRENT_SESSION_FORMAT_VERSION = 3` (`src/engine/session.ts:66`) is stamped on all sessions created in `v0.3.3`. Sessions with missing or earlier format versions trigger schema migrations in `src/domains/session/migrations/` on `/resume`.
 
 ---
 
@@ -77,6 +77,10 @@ Subsequent lines represent typed `SessionEntry` objects (`src/domains/session/en
 2. **`label`**: User-defined turn bookmark or tag anchored to `targetTurnId`.
 3. **`sessionInfo`**: Metadata event (such as model switch, target change, or thinking level adjustment).
 4. **`compactionSummary`**: Progressive compaction snapshot retaining historical context up to `firstKeptTurnId`.
+5. **`taskLedger`**: Full session task-board snapshot with a stable board id, goal and subgoal states, active run ids, required validation evidence, and optional operator provenance through `origin: "user"` plus `userTaskId`.
+6. **`decisionLedger`**: Branch-anchored snapshot of a completed or cancelled `ask_user` interview, including its timing, round count, settled values, superseded values, and operator corrections.
+
+`taskLedger` and `decisionLedger` are context-free bookkeeping entries. They refold the `/tasks` and `/decisions` surfaces and enter evidence projection, but do not consume model-context tokens or become model messages by themselves.
 
 ### Write Durability & Atomicity
 
@@ -108,25 +112,30 @@ export interface SessionTreeNode {
 
 When an operator branches or switches turns using `/tree` or `Alt+T`, the next append point changes without mutating or deleting historical entries in `current.jsonl`.
 
-The active path filter (`src/domains/session/tree/active-path.ts:filterEntriesToActivePath`) traces ancestry back from the active leaf:
-1. Retains all message entries on the direct ancestral path from leaf to root.
-2. Retains sidecar entries anchored to turns on the active path (`targetTurnId`, `parentTurnId`, or `firstKeptTurnId`).
-3. Retains unanchored global sidecars (`parentTurnId: null`).
-4. Prunes abandoned sibling branches from the context window supplied to the LLM.
+The active path filter (`src/domains/session/tree/active-path.ts`) traces ancestry back from the active leaf:
+1. Resolves all `turnId` identifiers tracing back to the root `null` parent.
+2. Selects all ledger entries explicitly matching these `turnId`s.
+3. Both `/tree` (in-session switch) and `/fork` (new session branch) reconstruct the exact same state, strictly excluding any unanchored sidecar entries (`taskLedger`, routing notices, leafless `workerRun`) that appear after the chosen leaf's position.
+4. For a `/tree` switch, the active pin is persisted to `meta.pinnedLeafTurnId` and cleared on the next append, so a switch survives quit and `/resume` without reverting to the abandoned tip via timestamp inference.
+5. Prunes abandoned sibling branches from the context window supplied to the LLM.
 
 ### Branch Forking (`/fork`)
 
 The `/fork` command (`src/domains/session/tree/fork.ts:forkFromParentTurn`) initializes an independent session branched from an arbitrary turn:
 1. Closes the current session writer.
 2. Creates a new session directory and metadata inheriting `cwd`, `model`, and `target` from the parent.
-3. Traces ancestry up to `parentTurnId` and copies only the active path entries into the new session ledger.
+3. Traces ancestry up to `parentTurnId` and copies exactly the active path entries (excluding later unanchored sidecars) into the new session ledger.
 4. Stamps `parentSession` and `parentTurnId` in the new session header.
 
+### Streaming Turn Settlement During Session Transitions
+
+When an operator issues `/new`, `/resume`, `/tree`, or `/fork` while an assistant turn is actively streaming, `settleChatBeforeSessionSwitch` (`src/interactive/session-switch-settlement.ts`) cancels the in-flight stream and awaits completion. This guarantees that partial assistant records and completed tool executions seal cleanly into the active session ledger before the session writer is replaced, preventing orphaned records in new sessions or unanswered prompts in original sessions (#114). Synchronous session transitions when chat is idle continue to execute immediately.
+
 ---
 
 ## 5. Session Resumption (`/resume`) & Working Directory Fallback
 
-When resuming a session via `/resume <sessionId>` or `CLIO_CODER_RESUME_SESSION_ID`:
+When resuming a session via `/resume` or `CLIO_CODER_RESUME_SESSION_ID`:
 1. `src/domains/session/manager.ts:resumeSessionState` loads `meta.json` and runs migrations.
 2. `src/domains/session/cwd-fallback.ts:resolveSessionCwd` probes the recorded `meta.cwd` against the filesystem.
 3. If the directory is invalid, it returns a typed failure reason:
@@ -135,9 +144,42 @@ When resuming a session via `/resume <sessionId>` or `CLIO_CODER_RESUME_SESSION_
    - `not-a-directory`: The path points to a non-directory file or broken symlink.
 4. The interactive layer displays the `cwd-fallback` overlay prompting the operator to choose a valid workspace directory.
 
+### Model-Facing Custom Entry Replay
+
+When resumed or forked session history is replayed to the model, custom session entries (such as compaction summaries, branch summaries, and operator bash executions) are projected into standardized user-role message text via `src/engine/messages.ts` constants (`COMPACTION_SUMMARY_PREFIX`, `BRANCH_SUMMARY_PREFIX`, `bashExecutionToText`) rather than ad-hoc formats, ensuring deterministic prompt construction across sessions.
+
+---
+
+## 6. Session Export
+
+`/export` replays the active branch through the same transcript projection used by the live TUI and `/resume`. With no path, it writes `.clio-coder/exports/<sessionId>-<local-date>.html`. The HTML document is self-contained, carries the active Clio theme through converted ANSI styles, renders tool calls as semantic tool rows, references no external assets, and is capped at 2 MiB. If the transcript exceeds that limit, the export ends at a complete rendered row and states that later rows were omitted.
+
+An explicit path ending in `.md` keeps the plain Markdown form: a heading, UTC export instant, and a terminal-control-free fenced transcript. Export never changes the ledger or the active tree pin. Both formats follow the pinned active leaf and omit abandoned sibling turns.
+
+---
+
+## 7. Directory Handbooks and Project Overrides
+
+During session context loading, `loadProjectContextFiles` (`src/domains/context/clio-md.ts`) discovers root `CLIO-CODER.md` handbooks and directory-scoped `CLIO-CODER.override.md` files:
+- An override handbook replaces inherited project instructions for its directory and all subdirectories, establishing an explicit subtree boundary.
+- Sibling directories remain unaffected.
+- Subdirectories within the subtree may supply narrower instructions with additional override files.
+- Prompt blocks preserve explicit source paths for provenance.
+- Malformed override files fail closed, and context resets never delete override files.
+
+---
+
+## 8. Prompt History and Input Recovery
+
+The interactive editor provides process-local prompt history via `Ctrl+P` (previous) and `Ctrl+N` (next):
+- Accepted chat prompts, slash commands, local command executions, steering inputs, follow-ups, and interrupt messages are preserved in navigation history.
+- Consecutive duplicates are collapsed.
+- Rejected or malformed commands remain editable in the composer without polluting navigation history.
+- Navigating forward past the newest entry restores the unfinished draft prompt.
+
 ---
 
-## 6. Protected-Artifact Write-Ahead Journal
+## 9. Protected-Artifact Write-Ahead Journal
 
 To guarantee that protected artifacts and validation locks survive unexpected crashes between tool execution and ledger commitment, Clio Coder maintains a write-ahead journal (`src/domains/session/protected-artifact-journal.ts`):
 
@@ -149,8 +191,9 @@ To guarantee that protected artifacts and validation locks survive unexpected cr
 
 ---
 
-## 7. In-Session Task Board & Usage Accounting
+## 10. In-Session Task Board & Usage Accounting
 
-- **Task Board** (`src/domains/session/task-board.ts`): Maintains session task items with states (`todo`, `in_progress`, `done`, `failed`). Emits middleware reminders when uncompleted tasks remain before turn end.
+- **Task Board** (`src/domains/session/task-board.ts`): Maintains session task items as full `taskLedger` snapshots with `pending`, `active`, `completed`, `blocked`, and `cancelled` states. Stable board ids retain terminal board history; rows picked from the project operator inbox retain `origin: "user"` and `userTaskId` across `/resume`, `/fork`, `/view`, and evidence export. The project-scoped inbox itself lives at `.clio-coder/user-tasks.json`, outside the session directory.
+- **Decision Board** (`src/domains/session/decision-board.ts`): Appends one branch-anchored `decisionLedger` snapshot when an `ask_user` interview completes or is cancelled. Superseding or correcting a value appends a new snapshot, preserving the earlier value and the operator-authored revision trail.
 - **Usage Accounting** (`src/domains/session/usage.ts`): Aggregates session token counts across input, output, cache read, cache write, and reasoning tokens. Anchors against provider-reported totals on settled turns.
 - **Aborted Turn Persistence**: When a turn is interrupted by `Ctrl+C` or a SIGINT signal, partial assistant output and completed tool executions are committed to `current.jsonl` with `interrupted: true` before yielding the prompt.

package/docs/skills-marketplace.md

@@ -1,20 +1,24 @@
 # Skills Marketplace
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/skills_blueprint.html](html/skills_blueprint.html) (Version: 0.3.1).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/skills_blueprint.html](html/skills_blueprint.html) (Version: 0.3.3).
 
-The Skills Hub (`/skill`) shows project skills, user skills, and the marketplace. Every marketplace row comes from the same local lookup that `clio-coder skills install <name>` and `/skill:<name>` resolve through, so the hub lists nothing it cannot install.
+The Skills Hub (`/skill`) shows project skills, user skills, and the marketplace. Every marketplace row comes from the same local lookup that `clio-coder skills install <name>` and `/skill <name>` resolve through, so the hub lists nothing it cannot install.
 
 ## Where marketplace rows come from
 
 There is one source, `discoverMarketplaceSkills()` in `src/domains/resources/skills/marketplace.ts`, and it reads two kinds of real local data:
 
-1. **A catalog directory** of actual `SKILL.md` packages: `CLIO_CODER_SKILL_CATALOG_DIR`, or a `skills/` directory in the working tree when it holds packages. Metadata comes from the packages themselves through the skill loader, so a row's version, category, and audit state are the package's own.
-2. **A JSON index** at `CLIO_CODER_SKILL_MARKETPLACE_INDEX` or `<configDir>/skill-marketplace.json`, whose entries name a `sourceUrl` that `clio-coder skills install` accepts. `npm run skills:pin` publishes that file's `version`, `audit`, and `category` fields.
+1. **A catalog directory** of actual `SKILL.md` packages. Resolution order: `CLIO_CODER_SKILL_CATALOG_DIR`, then a `skills/` directory in the working tree when it holds packages, then the `skills/` catalog the installed clio-coder package carries. Metadata comes from the packages themselves through the skill loader, so a row's version, category, and audit state are the package's own.
+2. **A JSON index** whose entries name a `sourceUrl` that `clio-coder skills install` accepts. Resolution order: `CLIO_CODER_SKILL_MARKETPLACE_INDEX`, then `<configDir>/skill-marketplace.json`, then the package's own `skills/skill-marketplace.json`. `npm run skills:pin` publishes that file's `version`, `audit`, and `category` fields.
 
-Catalog packages win over index entries on a name collision, because the local files are the thing that installs. Neither source reaches the network; the hub opens on local data and never blocks.
+The package fallbacks mean a fresh npm install has a marketplace with no configuration: `clio-coder skills search grill` lists `grill-me` from the shipped catalog, `clio-coder skills install grill-me` copies it out of the package into `.clio-coder/skills/`, and `/skill grill-me` offers that install before running. The shipped catalog is a marketplace source only, never a discovery root: nothing from it is loadable until the operator installs it, which keeps the install-then-activate contract and the per-skill scope choice in the operator's hands.
 
-When both sources are absent the hub has nothing to list and says so, naming the remedy:
+Catalog packages win over index entries on a name collision, because the local files are the thing that installs. Neither source reaches the network; the hub opens on local data and never blocks. Only an index entry whose `sourceUrl` is a GitHub URL, and that no catalog also carries, needs the network at install time.
+
+The model sees the same lookup: `context(scope="skills")` lists installed skills and, under a `Marketplace (not installed)` heading, the entries this lookup would install. Loading a marketplace-only skill by name answers "not installed" and points at `/skill <name>`, never `unknown skill`.
+
+When both sources are absent (a source checkout with no `skills/` folder, or an incomplete package) the hub has nothing to list and says so, naming the remedy:
 
 ```
 no skills installed and no local marketplace configured. install one with
@@ -29,12 +33,12 @@ The CLI reports the same state as `no local skill marketplace catalog or index c
 | Key | Action |
 |---|---|
 | type | Filter all groups |
-| `Enter` | Insert `/skill:<name> ` into the editor for the task text |
+| `Enter` | Insert `/skill <name> ` into the editor for the task text |
 | `Tab` | Toggle the detail pane (split layout on wide terminals) |
 | `i` | Install the selected marketplace skill into the project scope through the local marketplace resolver |
 | `PgUp`/`PgDn` | Scroll the detail pane |
 
-Invoking an uninstalled marketplace skill with `/skill:<name>` prompts before installing it. `i` runs the same install path eagerly from the hub.
+Invoking an uninstalled marketplace skill with `/skill <name>` prompts before installing it. `i` runs the same install path eagerly from the hub.
 
 The CLI `clio-coder skills` commands manage local skill discovery, validation, and
 creation. Extension resource roots and share archives are documented in

package/docs/time-conventions.md

@@ -2,7 +2,7 @@
 
 This document defines the canonical time and clock conventions for `clio-coder`. These policies establish consistent rules for measuring durations, recording instants, converting timezones, and managing concurrency across the codebase.
 
-This policy is promoted from Section 10 of the repository time audit in [time-audit-2026-08-15.md](issues/time-audit-2026-08-15.md).
+This policy is promoted from Section 10 of the repository time audit conducted on 2026-08-15.
 
 ---
 

package/docs/tool-usage.md

@@ -1,11 +1,11 @@
 # Tool Usage Reference
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive seven-plane tool atlas and observation envelope truncation/offload calculator is located at [docs/html/tool_usage_blueprint.html](html/tool_usage_blueprint.html) (Version: 0.3.1).
+> **Interactive Spec Available:** An interactive seven-plane tool atlas and observation envelope truncation/offload calculator is located at [docs/html/tool_usage_blueprint.html](html/tool_usage_blueprint.html) (Version: 0.3.3).
 
 This is the deep usage reference behind the deliberately terse tool descriptions in the prompt envelope. Toolkit v2 keeps rich guidance out of tool descriptions and puts it here, where `context(scope="docs", query=...)` retrieves it section by section. Each tool below has its own self-contained `##` section covering the argument surface, defaults, truncation and continuation behavior, and concrete calls. Source of truth is `src/tools/`.
 
-In Clio Coder v0.3.1, `src/tools/agent-tools.ts` serves as the single agent-tool adapter across both orchestrator and worker runtimes. Both surfaces resolve their executable tools through the exact same `effectiveToolNames` narrowing, ensuring that attested tool schemas never drift from the tools available at runtime. Tools are keyed strictly by the `ToolName` union with no alias table. Argument leniency for weak-model callers is provided exclusively by per-tool `prepareArguments` normalizers declared on `ToolSpec`.
+In Clio Coder v0.3.3, `src/tools/agent-tools.ts` serves as the single agent-tool adapter across both orchestrator and worker runtimes. Both surfaces resolve their executable tools through the exact same `effectiveToolNames` narrowing, ensuring that attested tool schemas never drift from the tools available at runtime. Tools are keyed strictly by the `ToolName` union with no alias table. Argument leniency for weak-model callers is provided exclusively by per-tool `prepareArguments` normalizers declared on `ToolSpec`.
 
 ## Observation envelope: truncation notices, offload, next hints, and the turn budget
 
@@ -332,7 +332,7 @@ Arguments:
 
 `scope="docs"` runs deterministic, offline retrieval over Clio's bundled docs (every `docs/*.md` plus README.md, CHANGELOG.md, and CLIO-CODER.md), indexed as heading-delimited sections with light stemming, Clio vocabulary aliases, phrase boosts, and BM25-style body scoring. The JSON payload carries `corpus`, the expanded `terms`, and ranked `results` with `file`, `heading`, `breadcrumb`, `anchor`, `lines`, `snippet`, `score`, `coverage`, `matchedTerms`, and `signals`, plus an `omitted` count. Follow the `followUp` guidance: read the cited file and line range when you need the full section. Empty results are still valid JSON with `next` populated (the closest vocabulary expansion, or `query=overview`). 16KB cap; an oversize payload is replaced by the parseable JSON stub. The old `docs_search` `file` filter was dropped in the consolidation. Omitting `query` returns the corpus listing (the file set plus doc and section counts, the same `corpus` shape a search carries) so the model can pick a term without wasting a round on a `requires query` error.
 
-`scope="skills"` with no `name` lists installed skills with descriptions; the listing asks the model to match the current task against the catalog and, on a fit, to open its reply with `Suggested skill: /skill:<name>` (a comma-separated sequence when skills compose) and wait for the operator. Loading a body is policy-gated: a skill loads only after an explicit operator request (a `/skill:<name>` or `/skill <name>` task, including one picked from the Skills Hub), and recipe-bound workers may load only their declared skills. A load attempt without a pending request is denied with the model's compliant next move spelled out: do not retry, open the reply with the `Suggested skill: /skill:<name>` line and wait for the operator, or continue without skills. On the first substantive turn of a session with model-visible skills installed, a once-per-session middleware reminder in the user message teaches the same protocol. A pending request's task text is surfaced with the body. Marketplace-installed skills are drift-checked against their pinned hash; a mismatch annotates the result with a `skill_drift` warning but never blocks. 50KB cap; a truncated body offloads in full.
+`scope="skills"` with no `name` lists installed skills with descriptions; the listing asks the model to match the current task against the catalog and, on a fit, to open its reply with `Suggested skill: /skill <name>` (a comma-separated sequence when skills compose) and wait for the operator. Loading a body is policy-gated: a skill loads only after an explicit `/skill <name> [task]` operator request, including one picked from the Skills Hub, and recipe-bound workers may load only their declared skills. A load attempt without a pending request is denied with the model's compliant next move spelled out: do not retry, open the reply with the `Suggested skill: /skill <name>` line and wait for the operator, or continue without skills. On the first substantive turn of a session with model-visible skills installed, a once-per-session middleware reminder in the user message teaches the same protocol. A pending request's task text is surfaced with the body. Marketplace-installed skills are drift-checked against their pinned hash; a mismatch annotates the result with a `skill_drift` warning but never blocks. 50KB cap; a truncated body offloads in full.
 
 ```text
 context(scope="workspace")

package/docs/trace-store.md

@@ -1,7 +1,7 @@
 # Trace store contract
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive trace database viewer, schema inspector, and SQL query validator simulator is located at [docs/html/trace_blueprint.html](html/trace_blueprint.html) (Version: 0.3.1).
+> **Interactive Spec Available:** An interactive trace database viewer, schema inspector, and SQL query validator simulator is located at [docs/html/trace_blueprint.html](html/trace_blueprint.html) (Version: 0.3.3).
 
 Clio's trace database is a rebuildable, queryable mirror. Receipts, session
 ledgers, gate artifacts, and evidence remain the source of truth. Removing

package/docs/troubleshooting.md

@@ -1,6 +1,6 @@
 # Troubleshooting & Error Remediation
 
-This guide provides concrete, actionable remediation procedures for operational errors, permission denials, target connection failures, and system diagnostics in Clio Coder `v0.3.1`.
+This guide provides concrete, actionable remediation procedures for operational errors, permission denials, target connection failures, and system diagnostics in Clio Coder `v0.3.3`.
 
 ---
 
@@ -11,15 +11,18 @@ This guide provides concrete, actionable remediation procedures for operational
 | `clio-coder run cannot confirm permission requests; rerun interactively to approve this action.` | A tool call required manual permission confirmation during a non-interactive headless `clio-coder run` execution. | Run the command interactively in the TUI (`clio`) to grant one-shot approval, adjust the workspace policy in `.clio-coder/safety.yaml`, or run with `--autonomy full-auto` if safe. |
 | `no trace database yet at <path>` | The trace mirror database has not been initialized because no interactive sessions or dispatches have executed yet. | Execute a turn or dispatch a task. In SQLite trace commands, this notice is informational (exit code `0`). |
 | `error: trace database not found: <path>` | An explicit `--db <path>` flag was provided pointing to a nonexistent database file. | Verify the database path or omit `--db` to use the default state directory database (`<stateDir>/trace.sqlite`). |
-| `no local skill marketplace catalog or index configured` | Neither a local `skills/` catalog directory nor a valid JSON index at `CLIO_CODER_SKILL_MARKETPLACE_INDEX` was found. | Point `CLIO_CODER_SKILL_MARKETPLACE_INDEX` at a valid `skill-marketplace.json` file or install a skill directly via `clio-coder skills install <path\|github-url>`. |
-| `<arg> is a global option and must come before the subcommand: clio-coder <usage> <command> ...` | A global CLI option (such as `--cwd`, `--config-dir`, or `--state-dir`) was placed after the subcommand name. | Move the flag before the subcommand name (e.g. `clio-coder --cwd /path run ...` instead of `clio-coder run --cwd /path ...`). |
-| `target <id> is not registered` | The designated target ID does not exist in `settings.yaml`. | Run `clio-coder targets` to view available targets, or configure a new target using `clio-coder targets add <id> --runtime <type> --base-url <url>`. |
-| `budget: ceiling must be >= 0 (got <val>)` | An invalid negative budget ceiling was passed to the session or dispatch configuration. | Pass a non-negative USD budget value (e.g. `--budget-usd 5.0`). |
+| `no local skill marketplace catalog or index configured` | No catalog directory (`CLIO_CODER_SKILL_CATALOG_DIR`, a `skills/` folder in the working tree, or the installed package's own `skills/` catalog) and no JSON index (`CLIO_CODER_SKILL_MARKETPLACE_INDEX`, `<configDir>/skill-marketplace.json`, or the package's `skills/skill-marketplace.json`) was found. On an npm install this means the package is incomplete; check `clio-coder doctor`. | Point `CLIO_CODER_SKILL_CATALOG_DIR` at a `skills/` catalog or `CLIO_CODER_SKILL_MARKETPLACE_INDEX` at a valid `skill-marketplace.json`, or install a skill directly via `clio-coder skills install <path\|github-url>`. |
+| `<arg> is a global option and must come before the subcommand: clio-coder <usage> <command> ...` | A global CLI option (such as `--api-key`, `--no-context-files`, or `-nc`) was placed after the subcommand name. Directory roots are configured via `CLIO_CODER_*_DIR` environment variables. | Move the flag before the subcommand name (e.g. `clio-coder --api-key <key> run ...` instead of `clio-coder run --api-key <key> ...`). |
+| `target <id> is not registered` | The designated target ID does not exist in `settings.yaml`. | Run `clio-coder targets` to view available targets, or configure a new target using `clio-coder targets add`. |
+| `budget: ceiling must be >= 0 (got <val>)` | A negative session cost ceiling reached the scheduling budget (`src/domains/scheduling/budget.ts`). | Set a non-negative `budget.sessionCeilingUsd` in `settings.yaml`, or edit Session ceiling (USD) in Settings → Budget. |
 | `worker_final_output_missing` | A worker process completed execution with exit code 0 but failed to emit a valid final answer before the stream closed. | Check the worker event log using `clio-coder trace tail <runId>` or inspect the receipt via `monitor(run_id="<id>", mode="receipt")`. |
 | `vram_capacity_fit_failure` | The model could not be scheduled or loaded due to insufficient GPU VRAM capacity on the target node. | Select a smaller quantized model variant, reduce context window size, or route to an alternative fleet node with greater memory capacity. |
 | `loop_guard_tools_disabled_exhausted` | The loop detector identified repeated unproductive tool calls with identical arguments and disabled tool execution. | Inspect model prompts and provide clearer intermediate steering instructions to prevent recursive tool loops. |
 | `Node.js ExperimentalWarning: SQLite is an experimental feature` | Node.js emitted an experimental feature warning for `node:sqlite`. | By default, Clio suppresses this warning via a scoped filter. If visible when running scripts directly, pass `--trace-warnings` to control diagnostics. |
 | `cwd-fallback: no-cwd / missing / not-a-directory` | The session recorded in `meta.json` points to a workspace directory that has been deleted, unmounted, or renamed. | When prompted by the `cwd-fallback` overlay, select a valid existing directory to re-anchor the session. |
+| `LM Studio duplicate model load / peer projection` | Sending a bare model key that already has a loaded instance or an LM Link peer projection. | Clio resolves model IDs to resident instances automatically. Verify loaded instances on the target server with `clio-coder targets --probe`. |
+| `llama.cpp 400 model is already running` | Sending load requests to a router where the model is idle/sleeping. | Sleeping models are treated as resident. Verify router slots and catalog models before initiating eviction. |
+| `OAuth token exchange cancelled` | An in-flight OAuth login or credential refresh was aborted before persistence. | Re-run `clio-coder auth login <target>` to restart the OAuth flow cleanly. Uncommitted tokens are discarded. |
 
 ---
 
@@ -28,6 +31,6 @@ This guide provides concrete, actionable remediation procedures for operational
 When encountering unexpected system behavior:
 
 1. **System Health Check**: Run `clio-coder doctor` (or `clio-coder doctor --fix` to auto-repair state directory permissions and configuration defaults).
-2. **Target Connectivity Probe**: Run `clio-coder configure --probe` to verify authentication and reachability for all configured LLM providers.
+2. **Target Connectivity Probe**: Run `clio-coder targets --probe` to verify authentication and reachability for all configured LLM providers.
 3. **Trace Store Inspection**: Run `clio-coder trace runs` and `clio-coder trace tail <runId>` to inspect event logs, durations, and tool outputs.
-4. **Receipt Validation**: Run `clio-coder evidence inspect <runId>` or `/view verify <runId>` to check cryptographic integrity and execution telemetry.
+4. **Receipt Validation**: Run `clio-coder evidence inspect <evidenceId>` or `/view verify <runId>` to check cryptographic integrity and execution telemetry. Build the evidence id first with `clio-coder evidence build --run <runId>`.

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.1).
+> **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.3).
 
 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/).
 
@@ -148,12 +148,18 @@ All TUI overlays and cards support compact widths down to 40 columns:
 
 ## 5. Screen Surfaces & State Choreography
 
-The Clio screen maintains a responsive, four-zone structure: the launchpad / session header, transcript, composer, and footer.
+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.3 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 · EXPERIMENTAL · ctx ready · type a task`) so the conversation transcript owns the viewport.
+- **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)
 
@@ -210,11 +216,23 @@ State is signaled through the status pill in the footer and matches the followin
 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. 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), `medium`/`high` (`reason` purple), and `xhigh`/`max`/`on` (bold `reason` purple).
@@ -239,6 +257,20 @@ 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
+
+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.
+
+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. Settings Center & Command Overlays
@@ -255,16 +287,22 @@ The `/settings` overlay is a full-screen transactional control center:
   - `Apply this session` (for live-capable settings)
   - `Apply and save globally`
   - `Cancel` (or `Esc`)
-  - Restart-required settings (`budget.concurrency`, `runtimePlugins`) offer only global save and announce `Saved to settings.yaml · restart Clio to apply`.
+  - 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. Below 60 columns, side margins are removed for full-width presentation.
+- **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
 
-### 7.2 Slash Autocomplete Command Palette
+- **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.
-- **Stem-Gated Aliases**: Aliases (e.g. `/exit`, `/ctx`, `/compact`, `/models`, `/config`) are hidden by default and only surface when the typed stem matches the alias spelling.
+- **One Canonical Spelling**: Autocomplete, help, and parsing expose the same unique slash-command names; no alias rows compete with canonical commands.
 
 ---
 
@@ -292,4 +330,3 @@ Two shapes, both ending at something the user can act on.
 ### 8.2 Memory Step Rows
 
 `/memory` activity rows read `<trigger> <decision> <reason>`, followed by `<N>w` when the step wrote to the bank and `<N> cited` when it cited entries, then the tier and latency. `describeTaskMemoryActivity` is the one place that builds this string.
-

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.1).
+> **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.3).
 
 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@iowarp/clio-coder",
-	"version": "0.3.1",
+	"version": "0.3.3",
 	"description": "Coding agent for HPC and scientific-software developers, part of IOWarp's CLIO ecosystem of agentic science.",
 	"keywords": [
 		"ai",
@@ -50,11 +50,8 @@
 		"!dist/**/*.map",
 		"assets/clio-coder-logo-128.webp",
 		"src/**",
-		"skills/workflow/cut-it/**",
-		"skills/git/**",
-		"skills/skill-marketplace.json",
+		"skills/**",
 		"docs/*.md",
-		"docs/html/**",
 		"README.md",
 		"CHANGELOG.md",
 		"CONTRIBUTING.md",
@@ -73,38 +70,39 @@
 		"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",
+		"grok-mermaid": "0.2.2",
 		"ollama": "0.6.3"
 	},
 	"overrides": {
@@ -125,7 +123,6 @@
 		"tsx": "4.22.4",
 		"typebox": "1.3.0",
 		"typescript": "6.0.3",
-		"undici": "8.5.0",
 		"uuid": "14.0.1",
 		"yaml": "2.9.0"
 	}