@iowarp/clio-coder 0.3.0 → 0.3.2

package/docs/scientific-validation.md

@@ -1,11 +1,11 @@
 # Clio Coder Scientific Validation Contracts
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive numerical tolerance calculator and HPC queue execution simulator is located at [docs/html/validation_blueprint.html](html/validation_blueprint.html) (Version: 0.3.0).
+> **Interactive Spec Available:** An interactive numerical tolerance calculator and HPC queue execution simulator is located at [docs/html/validation_blueprint.html](html/validation_blueprint.html) (Version: 0.3.2).
 
 Scientific software development cannot treat simple file presence as proof of correctness. A simulation script that crashes on rank 48, or writes out NetCDF arrays filled with `NaN`s, may still successfully write a file to the disk. 
 
-Clio Coder recognizes **scientific validation contract files** as an opt-in signal for a higher evidence bar. In v0.3.0, core Clio does not parse or enforce a scientific contract schema. The presence of `.clio-coder/validation.yaml`, `.clio-coder/validation.yml`, `validation.yaml`, `validation.yml`, or `VALIDATION.md` at the workspace root raises the default rigor level to `high`; the file contents are advisory material for developers, project agents, and external validators.
+Clio Coder recognizes **scientific validation contract files** as an opt-in signal for a higher evidence bar. In v0.3.2, core Clio does not parse or enforce a scientific contract schema. The presence of `.clio-coder/validation.yaml`, `.clio-coder/validation.yml`, `validation.yaml`, `validation.yml`, or `VALIDATION.md` at the workspace root raises the default rigor level to `high`; the file contents are advisory material for developers, project agents, and external validators.
 
 The convention below is a recommended shape for scientific projects that need to document expected dimensions, attributes, numerical tolerances, scheduler context, and verification commands for scientific artifacts. Developed at the [Gnosis Research Center (GRC)](https://grc.iit.edu) at Illinois Tech as part of the NSF-funded scientific-software context (NSF Award [#2411318](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2411318)), this convention links execution metadata with physical output checks without claiming that the current harness executes those checks automatically.
 
@@ -77,7 +77,7 @@ Comparing floating-point values in scientific computations must accommodate roun
 
 ## Common Scientific Artifact Families
 
-The following labels are useful project conventions for validation contracts and reports. They are not a closed, core-enforced enum in v0.3.0:
+The following labels are useful project conventions for validation contracts and reports. They are not a closed, core-enforced enum in v0.3.2:
 
 - **`HDF5` / `NetCDF` / `Zarr`:** Multi-dimensional scientific array files.
 - **`FITS`:** Flexible Image Transport System (used in astrophysics).

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.0`.
+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.2`.
 
 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.0`. 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.2`. 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.0).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/skills_blueprint.html](html/skills_blueprint.html) (Version: 0.3.2).
 
-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

@@ -0,0 +1,101 @@
+# Time and Clock Conventions
+
+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 conducted on 2026-08-15.
+
+---
+
+## 1. Which Clock for What Purpose
+
+### Monotonic clocks for durations
+
+All durations must be measured using `performance.now()` without exception. This rule applies to latency measurements, elapsed run times, time-to-first-token (TTFT), execution budgets, timeouts, stall watchdogs, retry backoff intervals, and rendering metrics.
+
+Whenever a value answers the question "how long did this take" or "how long until", it must originate from the monotonic clock. Monotonic clocks are unaffected by Network Time Protocol (NTP) adjustments, system suspend or resume events, and Daylight Saving Time (DST) transitions.
+
+### Wall clocks for anchored instants
+
+Wall clock reads via `Date.now()` or `new Date()` are reserved exclusively for anchoring instants that a human operator or an external machine will inspect. These include timestamps such as `startedAt`, `endedAt`, `createdAt`, and `expiresAt`. Wall clocks must never be used to measure durations or elapsed intervals.
+
+### Combined anchor and span pattern
+
+When both an anchor instant and a duration are required, code must follow the pattern established in `src/domains/dispatch/code-step.ts:291-306`:
+
+```ts
+const startedAtMs = Date.now();                      // wall anchor, for the record
+const clock = process.hrtime.bigint();               // monotonic span
+const startedAt = new Date(startedAtMs).toISOString();
+// ... operation executes ...
+const durationMs = Number((process.hrtime.bigint() - clock) / 1_000_000n);
+const endedAt = new Date(startedAtMs + durationMs).toISOString();
+```
+
+The wall clock anchors the starting instant for human correlation. The monotonic clock measures the elapsed span. The ending timestamp `endedAt` is derived by adding the monotonic span to the initial wall anchor. This derivation guarantees that `endedAt - startedAt === durationMs` remains true regardless of any wall-clock adjustments that occur during execution.
+
+### Injectable clock seams
+
+Every module that reads a clock must accept an optional injectable clock interface in its configuration or options, defaulting to the system clock. Injectable clock seams allow test suites to run deterministically without relying on real-time passage or introducing timing races.
+
+### Cross-host timestamp boundaries
+
+A timestamp produced on one host must never be compared directly against a clock read on another host. Systems must receive-stamp incoming events upon arrival on the local host, maintain an explicit clock offset, or order events using sequence numbers rather than timestamps. Code must never subtract timestamps across host boundaries.
+
+### Sequence numbers over timestamps for ordering
+
+When ordering operations under concurrency, code must prefer monotonic sequence numbers over timestamps. Components such as the agent ledger (`src/domains/session/agent-ledger-store.ts`) and the execution scheduler (`src/domains/dispatch/execution-scheduler.ts`) rely on sequence numbers to remain correct by construction. Timestamps are reserved for human display and coarse windowing. Any attribution logic that relies on timestamps must report ambiguity explicitly rather than returning null.
+
+---
+
+## 2. Where UTC Is Converted
+
+### Storage, transport, and comparisons in UTC
+
+The system stores UTC, transports UTC, and compares UTC. Conversion to local time occurs once, strictly at the render call site.
+
+1. On disk and across the wire, timestamps are always represented as canonical ISO-8601 strings produced by `toISOString()`. Every store validates timestamps upon reading using the exact round-trip check from `src/domains/dispatch/capacity-lease.ts:80-84`.
+2. In memory, instants are stored as epoch milliseconds or canonical ISO-8601 strings. Localized or pre-formatted date strings must not be held in memory models.
+3. At the user interface render boundary, UTC instants are converted to the operator's local timezone.
+4. Whenever a converted local timestamp is displayed, the underlying canonical UTC instant must remain accessible. For example, a table row displays local time while the associated detail pane preserves the exact ISO-8601 string so that the two representations can always be reconciled.
+
+---
+
+## 3. Formatter Policy
+
+All operator-facing time formatting is consolidated in `src/interactive/format-time.ts`. The module provides three standardized formatting functions:
+
+| Function | Output Format | Timezone and Locale Frame | Purpose |
+|---|---|---|---|
+| `clockLocal(instant)` | `HH:MM:SS` | Operator local timezone using `en-GB` locale with 24-hour cycle (`hourCycle: "h23"`) | Renders time-of-day for logs, tree selectors, and message pickers |
+| `dateLocal(instant)` | `YYYY-MM-DD` | Operator local timezone using `en-CA` locale | Renders calendar dates for session selectors, welcome dashboards, and export filenames |
+| `relative(instant, now)` | `"3m ago"` (falls back to `dateLocal`) | Operator local timezone | Renders relative recency ladders with automatic fallback to calendar dates |
+
+Both `Intl.DateTimeFormat` instances are constructed at module scope. The module automatically rebuilds formatters if `process.env.TZ` changes during runtime.
+
+Machine surfaces such as filenames, IDs, structured log fields, and receipt records bypass the formatting module entirely and use canonical `toISOString()`.
+
+---
+
+## 4. Test Determinism and Receipt Integrity
+
+### Test clock harness
+
+Test suites must rely on the steppable clock helper in `tests/harness/clock.ts`. Every factory function that reads a clock must default to the harness clock in test environments. Real-time passage in tests is opt-in and requires explicit configuration.
+
+### Receipt integrity digests
+
+Persisted fields such as `startedAt` and `endedAt` participate in receipt integrity digests (`src/domains/dispatch/receipt-integrity.ts`). Any timestamp normalization, derivation, or adjustment must occur before the receipt digest is sealed. Timestamps must never be rewritten after receipt creation.
+
+---
+
+## 5. State-Root and Audit-Filename Assumptions
+
+### Host-scoped state root and coordination
+
+The state root directory is host-scoped. Durable locks and capacity leases carry a metadata payload containing `{host, pid, birthToken}`.
+
+A coordination record created by a foreign host is never adjudicated against the local process table. This follows the host-scoping pattern implemented in `src/tools/compete-worktrees.ts:207-215`, `src/domains/dispatch/orphan-recovery.ts:140-149`, and `src/core/run-identity.ts:23`.
+
+### Audit filename semantics
+
+The date in an audit log filename (such as `audit-YYYY-MM-DD.jsonl`) is a human-facing label indicating the local calendar date on which the audit log was opened. It does not represent machine-read data. All individual audit event records contained within the file store canonical UTC ISO-8601 timestamps.

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.0).
+> **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.2).
 
 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.0, `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.2, `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")
@@ -495,6 +495,7 @@ Arguments:
 - `decisions` (optional array). For `action="complete"`, key-value objects representing settled configurations.
 - `summary` (optional). Closeout explanation for `action="complete"`.
 - `max_rounds` (optional number). Round limit for this interview (default 6, max 24).
+- `exposure` (optional). `local` (default) or `outward`. `outward` marks a gate whose answer publishes or sends something outside the workspace (filing an issue or PR, posting a comment, pushing, releasing). At autonomy `auto-edit` an outward gate parks for the operator instead of being answered automatically; `full-auto` answers it. See [safety-model.md](safety-model.md).
 
 The tool manages a stateful operator interview. The UI presents choices (with an implicit "Other" option for custom text input). Once completed, the final decisions are persisted as standard configurations in the session ledger, allowing the agent to proceed with operators' inputs or defaults.
 
@@ -514,9 +515,9 @@ Arguments:
 - `kind` (required). `plan`, `review`, or `report`.
 - `content` (required). Full Markdown body.
 - `title` (optional). Document title.
-- `path` (optional). Override the default artifact path.
+- `path` (optional). Override the default path under `.clio-coder/artifacts/`.
 
-`kind=plan|review|report` writes a Markdown document to PLAN.md, REVIEW.md, or REPORT.md at the project root by default; `path` may override the destination but must stay inside the workspace. When `content` does not already start with `#`, a non-empty `title` is prepended as an H1. These kinds are TERMINAL: writing the artifact completes the turn and the harness skips the follow-up model call, so the artifact body itself is the answer. Put everything the reader needs in `content`; there is no closing message after the write.
+`kind=plan|review|report` writes a Markdown document to `.clio-coder/artifacts/PLAN.md`, `REVIEW.md`, or `REPORT.md` by default, so a turn nobody asked a file from never litters the working tree; `path` may override the destination but must stay inside the workspace. See [artifact-placement.md](artifact-placement.md) for the full contract. When `content` does not already start with `#`, a non-empty `title` is prepended as an H1. These kinds are TERMINAL: writing the artifact completes the turn and the harness skips the follow-up model call, so the artifact body itself is the answer. Put everything the reader needs in `content`; there is no closing message after the write.
 
 Skills are not artifacts. A skill is a `SKILL.md` folder written with the ordinary write tool into `.clio-coder/skills/<name>/` (or the user skill store) and validated by the skills loader; the `skill-craft` shipped skill documents the format and craft rules.
 

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.0).
+> **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.2).
 
 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.0`.
+This guide provides concrete, actionable remediation procedures for operational errors, permission denials, target connection failures, and system diagnostics in Clio Coder `v0.3.2`.
 
 ---
 
@@ -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>`.