@iowarp/clio-coder 0.3.0 → 0.3.2

package/docs/installation-and-lifecycle.md

@@ -1,9 +1,9 @@
 # Installation and Lifecycle Operations
 
-Clio Coder is designed to be self-contained and platform-compliant. This document outlines the default directory paths, file purposes, permission levels, and lifecycle commands (`install`, `reset`, `upgrade`, and `uninstall`). The supported alpha install path is a source checkout with a deterministic local symlink; npm distribution of `@iowarp/clio-coder` begins with the first stable v0.3.0 (the CLI already classifies and upgrades npm installs, so nothing here changes shape at that point).
+Clio Coder is designed to be self-contained and platform-compliant. This document outlines the default directory paths, file purposes, permission levels, and lifecycle commands (`install`, `reset`, `upgrade`, and `uninstall`). Clio Coder installs from npm as `@iowarp/clio-coder` (`npm install -g @iowarp/clio-coder`, published since v0.3.0) or from a source checkout with a deterministic local symlink; the CLI classifies both install kinds and `clio-coder upgrade` handles each.
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard with a path simulator and visual flowcharts is located at [docs/html/lifecycle_blueprint.html](html/lifecycle_blueprint.html) (Version: 0.3.0). You can open it directly in any web browser to view details dynamically.
+> **Interactive Spec Available:** An interactive dashboard with a path simulator and visual flowcharts is located at [docs/html/lifecycle_blueprint.html](html/lifecycle_blueprint.html) (Version: 0.3.2). You can open it directly in any web browser to view details dynamically.
 
 ---
 
@@ -49,7 +49,7 @@ The tables above cover the per-user roots. A repository Clio works in also grows
 | `.clio-coder/profile.yaml` | Operator input | Operator profile; closed enums and bounded path lists. | Yes. | Kept |
 | `.clio-coder/fleets/*.md`, `.clio-coder/fleets/commands.yaml` | Overlay | Fleet contracts and their command registry. Adds to the fleets shipped under `src/domains/agents/fleets/`. | Yes; shipped fleets remain. | Kept |
 | `.clio-coder/agents/*.md` | Overlay | Project agent recipes. Composes with shipped builtins and the user's `~/.config/clio-coder/agents`; a project recipe reusing a builtin id is **ignored**, not applied, with a note on stderr. | Yes; shipped agents remain. | Kept, and named |
-| `.clio-coder/skills/**` | Overlay | Project skills, trusted as repository-local. Composes with skills Clio ships. | Yes; shipped skills remain. | Kept, and named |
+| `.clio-coder/skills/**` | Overlay | Project skills, trusted as repository-local. This is where `clio-coder skills install <name>` lands a catalog skill; the shipped catalog under the package's `skills/` is a marketplace to install from, not a discovery root, so nothing appears here until the operator installs it. | Yes; the shipped catalog remains installable. | Kept, and named |
 | `CLIO-CODER.md` (repository root) | Runtime state | The generated project handbook. Human-reviewable, but written by `context init`. | Yes; regenerate with `clio-coder context init`. | Kept unless `--all` |
 | `.clio-coder/codewiki.json` | Runtime state | Structural index, schema v5. | Yes; rebuilt by `clio-coder context index`. | **Removed** |
 | `.clio-coder/state.json` | Runtime state | Index fingerprint and freshness stamps. | Yes; forces a rebuild. | **Removed** |
@@ -59,14 +59,16 @@ The tables above cover the per-user roots. A repository Clio works in also grows
 | `.clio-coder/wiki-prev/` | Runtime state | Previous wiki, retained for rollback during generation. | Yes. | Kept, not named |
 | `.clio-coder/worktrees/` | Runtime state | Git worktrees for `compete` candidate groups. | Prefer `git worktree remove`; a plain delete leaves git metadata behind. | Kept, not named |
 
-`~/.clio-coder/runtimes/` is a separate, user-level directory for third-party runtime
-plugins. It is not part of any repository.
+`~/.config/clio-coder/runtimes/` holds third-party runtime plugins. It lives under the
+user configuration directory, not in any repository.
 
 None of `.clio-coder/` is published by Clio's own package. The directories Clio ships
-(`src/domains/agents/builtins/`, `src/domains/agents/fleets/`, `skills/workflow/cut-it/`, `skills/git/`,
-`src/domains/prompts/fragments/`, `src/domains/providers/models/`) are read from
-the installed package root; the `.clio-coder/` entries above compose with them and never
-replace them on disk.
+(`src/domains/agents/builtins/`, `src/domains/agents/fleets/`, the whole `skills/` catalog
+with its `registry.yaml` and `skill-marketplace.json`, `src/domains/prompts/fragments/`,
+`src/domains/providers/models/`) are read from the installed package root; the `.clio-coder/`
+entries above compose with them and never replace them on disk. Builtin agent recipes bind
+skills straight out of the package catalog; the operator's own session reaches the same
+catalog only as a marketplace, through `clio-coder skills install <name>` or `/skill <name>`.
 
 ---
 
@@ -79,7 +81,7 @@ The core files are created automatically during the first run. `credentials.yaml
 | **Config** | `settings.yaml` | Target runtimes, model defaults, keybindings, and theme preferences. | `0o644` (rw-r--r--) | Removed by uninstall / `reset --config`. |
 | **Config** | `credentials.yaml` | Private keys and tokens managed via `clio-coder auth`. | `0o600` (rw-------) | Removed by uninstall / `reset --auth`. |
 | **Config** | `credentials.yaml.lock` | Lockfile used during credentials updates to prevent file corruption. | Ephemeral | Auto-removed. |
-| **State** | `install.json` | Install metadata: Clio version, node, platform, `installedAt` (written once at first install), and `upgradedAt` (stamped on upgrade). | Writer/umask default | Removed by uninstall / `reset --state`. |
+| **State** | `install.json` | Install metadata: Clio version, node, platform, `installedAt` (written once at first install), `upgradedAt` and `upgradedFrom` (stamped on a version change), and `noticedVersion` (the version whose one-time upgrade notice the interactive launch has shown). | Writer/umask default | Removed by uninstall / `reset --state`. |
 | **State** | `migrations.json` | Log of successfully applied schema/state migrations. | Writer/umask default | Removed by uninstall / `reset --state`. |
 | **Data** | `memory/records.json` | Long-term learning memories (up to 500 records) proposed/approved from runs. | Writer/umask default | Removed by uninstall / `reset --data`. |
 | **State** | `audit/YYYY-MM-DD.jsonl` | Daily safety audit logs showing allowed/blocked tool actions. | Writer/umask default | Removed by uninstall / `reset --state`. |
@@ -93,7 +95,7 @@ When Clio Coder boots (or after a reset), it calls `initializeClioHome()` (see `
 1.  **Directory Tree**: Recursively creates the four roots (`config`, `data`, `state`, `cache`) and their skeletons: `agents` under config, `memory`/`evidence`/`evals` under data, and `sessions`/`audit`/`receipts`/`interviews`/`scratch` under state.
 2.  **Settings Template**: If `settings.yaml` is absent, creates a fresh default config. An existing file is never read, validated, or rewritten by initialization.
 3.  **Credentials Security**: If `credentials.yaml` is absent, creates a YAML file containing a managed-file comment and an empty object (`{}`), then locks its permissions immediately to owner-only read-write (`0o600`).
-4.  **Install Metadata**: Writes `install.json` with `installedAt` exactly once at first install; a later version, platform, or node change preserves `installedAt` and stamps `upgradedAt`.
+4.  **Install Metadata**: Writes `install.json` with `installedAt` exactly once at first install; a later version, platform, or node change preserves `installedAt` and stamps `upgradedAt`, and a version change also records the previous version as `upgradedFrom`.
 
 ---
 
@@ -122,17 +124,19 @@ clio-coder --version
   --fix` with the caller's environment), so a fresh install passes plain
   `clio-coder doctor` with no manual steps.
 
-On a machine where Clio has never run, plain `clio-coder doctor` reports the
-missing config structure and exits nonzero by design (it is a read-only
-diagnosis); `clio-coder doctor --fix`, the installer above, or simply launching
-`clio-coder` creates everything.
+On a machine where Clio has never run, plain `clio-coder doctor` prints one
+`WARN installation  not set up yet` row, exits 0, and creates nothing (it is a
+read-only diagnosis, and an untouched home is not a broken one). Launching
+`clio-coder`, running `clio-coder configure`, or `clio-coder doctor --fix`
+creates everything; once any root exists, doctor reports each missing piece and
+exits 1 until it is repaired.
 
 First-run target setup after install:
 
 **Option A: Local Model / API Key Target**
 ```bash
 clio-coder configure --list
-clio-coder configure --id local-lmstudio --runtime lmstudio-native --url http://localhost:1234 --model your-model --set-orchestrator --set-fleet-default
+clio-coder configure --id local-lmstudio --runtime lmstudio --url http://localhost:1234 --model your-model --set-orchestrator --set-fleet-default
 clio-coder targets use local-lmstudio
 clio-coder targets --probe
 clio-coder
@@ -182,7 +186,61 @@ The command detects the install method from the running binary. On a source
 checkout it never runs `npm install -g`: it performs its safe local duties
 (migration check, `install.json` refresh) and prints the real update steps,
 `git pull`, `npm run install:local`, `hash -r`. The npm reinstall path applies
-only to a genuinely npm-installed binary, once the package is published.
+only to a genuinely npm-installed binary.
+
+#### Upgrading from 0.3.0
+
+Nothing has to be done by hand. On an npm install, one command does it all:
+
+```bash
+clio-coder upgrade
+```
+
+The 0.3.0 binary prints its header (`install npm`, `channel latest`,
+`current 0.3.0`), runs `npm install -g @iowarp/clio-coder@latest`, and then
+hands over to the binary that install just put on `PATH` with
+`clio-coder upgrade --post-install`. That newer binary runs the migration
+check, records `2026-08-18-lmstudio-runtime-id` in `state/migrations.json`, and
+normalizes any legacy LM Studio target id, websocket URL, and stored credential
+name. It then runs `clio-coder doctor --fix`,
+which refreshes `install.json`, and reports the transition as
+`ok: 0.3.0 -> 0.3.1 (migrations: 1)`. The outer 0.3.0 process closes with
+`ok: 0.3.0 -> post-install checks complete`. Under nvm or a custom npm prefix
+this works because `npm install -g` and the bare `clio-coder` resolve through
+the same prefix; the doctor rows the child prints are the proof of which binary
+answered. `clio-coder upgrade --dry-run` first names the exact command it would
+run, names the pending LM Studio migration, and prints
+`would refresh state metadata 0.3.0 -> 0.3.1` without touching the record.
+
+If you instead ran `npm install -g @iowarp/clio-coder` yourself, or launched
+the new binary before running `upgrade`, plain `clio-coder doctor` shows one
+failing row, `state metadata  stale 0.3.0 (...); current 0.3.1`, pointing at
+`clio-coder doctor --fix`, and exits 1. Either `clio-coder doctor --fix` or the
+next `clio-coder` launch refreshes it. `install.json` then reads
+`version: 0.3.1`, keeps the original `installedAt`, and gains `upgradedAt` and
+`upgradedFrom: "0.3.0"`; doctor's row becomes
+`0.3.1 (installed ..., upgraded ... from 0.3.0)`.
+
+#### Upgrading to 0.3.2
+
+Upgrading from 0.3.1 to 0.3.2 is automated:
+
+```bash
+clio-coder upgrade
+```
+
+Key lifecycle and operational updates in v0.3.2:
+- Upgraded the underlying engine SDK libraries to 0.84.0 with signal-aware OAuth cancellation.
+- Hardened migration resilience: damaged `credentials.yaml` files no longer block upgrades when no renames are needed (#121); `--skip-migrations` is available as a recovery override.
+- Fullscreen TUI mode (`terminal.tuiMode`, `terminal.fullscreenScrollbar`) is available via Settings → Terminal (restart required). Adaptive presentation pacing is the live `terminal.smoothStreaming` setting; 0.3.2 defaults it to `off`, with conservative `auto` and explicit `on` available from the same section.
+- Interactive launch paints a measured Stage 0 shell on the same terminal and editor that Stage 1 hydrates. Typing, queued submits, resize, and Ctrl+C remain live during hydration; set `CLIO_CODER_INSTANT_SHELL=0` for the legacy fully hydrated first-frame path.
+- Turn settlement is enforced on `/new`, `/resume`, `/tree`, and `/fork` to cleanly commit in-flight streams before session writer replacement (#114).
+- Resumed and forked session entry replays standardize message prefixes through `src/engine/messages.ts`.
+- `AI_AGENT=clio-coder` is set on all child processes for system attribution.
+
+The first interactive launch after upgrading shows the version notice:
+`clio: upgraded 0.3.1 → 0.3.2. What changed at the keyboard: ...`
+Recorded once per version in `install.json` as `noticedVersion`.
 
 ### C. System Resets (`clio-coder reset`)
 Selective recovery wipes:

package/docs/middleware-and-components.md

@@ -1,7 +1,7 @@
 # Middleware and Component Registry
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard with an interactive component scanner and a dynamic hook-and-effect pipeline is located at [docs/html/middleware_blueprint.html](html/middleware_blueprint.html) (Version: 0.3.0).
+> **Interactive Spec Available:** An interactive dashboard with an interactive component scanner and a dynamic hook-and-effect pipeline is located at [docs/html/middleware_blueprint.html](html/middleware_blueprint.html) (Version: 0.3.2).
 
 Clio Coder has two related but separate surfaces:
 

package/docs/model-catalog.md

@@ -1,18 +1,18 @@
 # Model Catalog, Runtime Refresh, and Field Notes
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard mapping capabilities, probe discovery, and target resolution is located at [docs/html/models_blueprint.html](html/models_blueprint.html) (Version: 0.3.0).
+> **Interactive Spec Available:** An interactive dashboard mapping capabilities, probe discovery, and target resolution is located at [docs/html/models_blueprint.html](html/models_blueprint.html) (Version: 0.3.2).
 
 Clio Coder treats a selectable model as the intersection of three sources:
 
 1. **Configured targets** in `settings.yaml` (`targets[]`, `defaultModel`, and optional `wireModels`).
 2. **Live runtime probes** (`probe()` / `probeModels()`), which discover models that appeared after Clio started.
-3. **Catalog knowledge** from pi-ai provider catalogs, Clio's bundled local YAML knowledge base under `src/domains/providers/models/**`, and user/project model-catalog overlays.
+3. **Catalog knowledge** from provider catalogs, Clio's bundled local YAML knowledge base under `src/domains/providers/models/**`, and user/project model-catalog overlays.
 
 ## Runtime refresh controls
 
-- `/targets`: `r` probes the selected target; `R` probes all targets.
-- `/model` or `/models`: `r` refreshes the selected row's target; `R` refreshes all targets.
+- `/targets` (Settings → Targets): probes every target when it opens; a row's probe action re-probes that target.
+- `/model`: `r` refreshes the selected row's target; `R` refreshes all targets.
 - `clio-coder models`: probes live targets by default before printing the CLI model list. Use `--offline` to skip live probing. Former `--probe` and `--no-probe` flags are gone.
 
 Configured `wireModels` and a target `defaultModel` remain selectable before a
@@ -53,14 +53,14 @@ The benchmarks record context-window, thinking, sampling, weight quantization, a
 A model family is "sanctioned" only when we can say what was tested and under which runtime. It is not a blanket endorsement. For each family, capture:
 
 - exact model id / artifact / quantization;
-- provider or runtime surface (`lmstudio-native`, `ollama-native`, `llamacpp`, `openrouter`, `openai-codex`, etc.);
+- provider or runtime surface (`lmstudio`, `ollama-native`, `llamacpp`, `openrouter`, `openai-codex`, etc.);
 - hardware and serving configuration;
 - context window and max output actually exercised;
 - tool-use, reasoning, vision, embeddings/rerank/FIM behavior where relevant;
 - quirks needed by the engine (thinking mechanism, sampling, KV cache);
 - failures and "do not use this route yet" notes.
 
-Engine-visible quirks belong in catalog YAML entries under `quirks.kvCache`, `quirks.sampling`, and `quirks.thinking`. Bundled entries under `src/domains/providers/models/**/*.yaml` are for curated Clio-supported families. User/lab/project experiments should start as overlays before they are promoted into source. Free-form notes can live alongside catalog entries and in this docs area for later cookbooks/blog posts.
+Engine-visible quirks belong in catalog YAML entries under `quirks.kvCache`, `quirks.sampling`, and `quirks.thinking`. Bundled entries under `src/domains/providers/models/**/*.yaml` are for curated Clio-supported families. User/lab/project experiments should start as overlays before they are promoted into source. Free-form notes can live alongside catalog entries and in this docs area for later cookbooks/blog posts. Catalog entries for LM Studio (`lmstudio`) no longer promise native SDK behavior or track SDK versions; all routing and capability reporting now reflects the strict HTTP adapter.
 
 ## Local catalog overlays
 
@@ -85,10 +85,11 @@ Overlay files are ordinary YAML lists using the same schema as the bundled
 catalog:
 
 ```yaml
-- family: ornith-1.0-35b-local
+- family: qwen3.8-27b
   matchPatterns:
-    - ornith-1.0-35b
-    - Ornith-1.0-35B-Q4_K_M-262K
+    - qwen3.8-27b
+    - qwen3_8-27b
+    - qwen3-8-27b
   capabilities:
     chat: true
     tools: true
@@ -102,7 +103,7 @@ catalog:
     rerank: false
     fim: false
     contextWindow: 262144
-    maxTokens: 65536
+    maxTokens: 32768
   quirks:
     sampling:
       thinking:
@@ -112,8 +113,7 @@ catalog:
     thinking:
       mechanism: always-on
       guidance: |
-        The serving endpoint separates Qwen-style thinking into
-        reasoning_content while content contains the final answer.
+        Official Qwen3.8-27B chat template. llama.cpp's qwen3_coder parser converts XML tool calls to standard tool_calls JSON.
 ```
 
 Use `settings.yaml` `wireModels` for target inventory. Use overlays for
@@ -162,7 +162,7 @@ Use this shape when testing a subscription model, homelab GPU target, research-l
 The Context Engine evaluates thinking mechanisms per model target and manages live reasoning streams. Depending on the runtime capabilities, Clio Coder employs specific thinking replay semantics to ensure chain-of-thought data is preserved or replayed correctly in the conversation history:
 
 - **Ollama Native (`ollama-native`):** Ollama utilizes the native `thinking` field in the request and response payloads. The engine handles Ollama-specific effort levels and streams reasoning increments cleanly through the native thinking channel.
-- **LM Studio Native (`lmstudio-native`):** Because LM Studio does not expose a native reasoning field, the engine replays prior thinking blocks by prepending them to assistant message payloads. These are formatted as a text-prepended part wrapped in `<think>` and `</think>` tags.
+- **LM Studio (`lmstudio`):** Chat uses the OpenAI-compatible `/v1/chat/completions` surface, including its `reasoning` stream field. Clio controls thinking only with `reasoning_effort` and never sends `chat_template_kwargs` to LM Studio. See <https://lmstudio.ai/docs/developer/openai-compat/chat-completions>.
 - **OpenAI Completions (`openai-completions`):** The OpenAI-compatible completions provider preserves reasoning blocks within assistant messages. It replays thinking blocks via the `reasoning_content` parameter in the message history, ensuring that the model maintains its chain-of-thought across conversational turns without stripping the data.
 - **Anthropic OAuth / API (`anthropic-max`):** Uses the `anthropic-extended` thinking format. The engine supports Anthropic's native extended thinking block protocol, streaming thinking increments and outputting them wrapped appropriately or natively depending on target capabilities.
 - **Reasoning-Never Models (`thinking.mechanism: none`):** When a model is configured or cataloged with `thinking.mechanism: none`, it is treated as a reasoning-never model. For these models, Clio must not send any thinking fields or parameters in requests, must not replay thinking blocks, must not surface thinking events to the TUI, and must not preserve or log reasoning token usage in metrics.
@@ -174,16 +174,47 @@ The Context Engine evaluates thinking mechanisms per model target and manages li
 Subscription models are registered and managed as standard HTTP/cloud targets:
 
 - **`openai-codex` (ChatGPT Plus/Pro OAuth):** Maps to catalog-backed Codex model ids surfaced by `clio-coder configure --list` and `clio-coder models` via a browser-minted subscription OAuth token, supporting complete chat, vision, and tool-use capabilities.
-- **`anthropic-max` (Claude Pro/Max OAuth):** Powers chat and workers using catalog-backed Claude model ids surfaced by `clio-coder configure --list` and `clio-coder models`. It relies on pi-ai's `anthropic` OAuth provider. During auth initialization, it alerts the operator to usage-terms caveat via:
+- **`anthropic-max` (Claude Pro/Max OAuth):** Powers chat and workers using catalog-backed Claude model ids surfaced by `clio-coder configure --list` and `clio-coder models`. It relies on the engine's Anthropic OAuth provider. During auth initialization, it alerts the operator to usage-terms caveat via:
   `Connects with your Claude Pro/Max subscription via OAuth (the same path Claude Code uses). Using subscription credentials outside Anthropic's first-party apps may not align with their terms of service; enable at your own discretion.`
 
 ---
 
+## Local Runtime Resolution & Quirks
+
+### LM Studio Host and Instance Resolution
+
+LM Studio lists downloadable model keys alongside loaded model instances. When using LM Link, instances hosted on peer nodes also appear in discovery. To prevent duplicate instance loading (#113):
+- Clio resolves a requested model ID against the target host's currently loaded instances.
+- Bare keys that already have a resident instance are never sent as raw keys (avoiding duplicate GPU allocations).
+- Resolution prefers the target's `defaultModel`, then instances unique to that host.
+- Keys reported as loaded by multiple hosts are identified as LM Link peer projections and are excluded from auto-selection.
+- Unloaded keys trigger just-in-time loading as expected.
+
+### llama.cpp Residency and Sleep Handling
+
+To maintain router availability during model switches and idle states (#127, #134):
+- The residency reconciler refuses eviction if the requested replacement model is not present in the router catalog.
+- If a model load is rejected, the reconciler reloads the previously evicted model to keep the slot occupied.
+- When the llama.cpp router reports an idle model as `sleeping`, Clio recognizes it as resident rather than requesting another load (preventing `400 model is already running` errors).
+
+### Probed Context Window Precedence
+
+Loaded context window probe results take precedence over static or advertised catalog defaults (#129). When a local model server reports an active loaded context length via `/v1/models` or runtime probe, Clio adopts that measured window size for all subsequent token budgeting and compaction decisions.
+
+### Thinking Levels and vLLM Token Budgets
+
+- `--thinking max` resolves to the highest thinking budget or effort level supported by the active model runtime (#128, #130).
+- For vLLM targets, thinking token budgets are explicitly bounded (`thinking_token_budget`) to guarantee that reasoning tokens do not consume the complete response ceiling, reserving headroom for final answer generation.
+
+### `/model` Fuzzy Ranking
+
+Interactive `/model` search applies fuzzy matching across provider-qualified search strings. Direct `target/model` matches outrank proxy-carried model IDs while preserving availability, health status, and favorite marks.
+
 ## Promotion path
 
 1. Capture raw field notes in docs or a lab notebook.
 2. Add or update a user/project catalog overlay with capabilities and quirks.
 3. Add focused unit/integration coverage when behavior changes engine routing.
-4. Refresh `/models` with `R` and verify the selected row reports the expected source/caps.
+4. Refresh `/model` with `R` and verify the selected row reports the expected source/caps.
 5. Promote the cleaned overlay into the bundled catalog only when the model family is ready to bless for Clio users.
 6. Promote the cleaned field note into a cookbook, guideline, or community blog post.

package/docs/observability.md

@@ -1,9 +1,9 @@
 # Observability Viewer
 
 > [!TIP]
-> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/observability_blueprint.html](html/observability_blueprint.html) (Version: 0.3.0).
+> **Interactive Spec Available:** An interactive dashboard is located at [docs/html/observability_blueprint.html](html/observability_blueprint.html) (Version: 0.3.2).
 
-`/view` is the interactive artifact viewer for a Clio session. It keeps the live transcript compact while preserving a full inspection path for durable artifacts.
+`/view` is the interactive artifact viewer for a Clio session. It keeps the live transcript compact while preserving a full inspection path for durable artifacts, task ledgers, and successful workspace outputs.
 
 ```text
 /view
@@ -67,13 +67,16 @@ Clio resolves directories under platform-specific XDG defaults (on Linux, these
 | **Evidence bundles** | Deterministic run or session overviews, findings, totals, and linked files. | `<dataDir>/evidence/<evidenceId>/` |
 | **Receipts** | Durable run receipts verified by SHA-256 integrity digests. | `<stateDir>/receipts/<runId>.json` |
 | **Dispatch outputs** | Logs and ledger records detailing worker execution. | `<stateDir>/runs.json` and `<stateDir>/receipts/<runId>.json` |
-| **Task ledgers** | Per-turn task-board goals, active runs, and required validation evidence. | `<stateDir>/sessions/<cwdHash>/<sessionId>/current.jsonl` |
+| **Task ledgers** | Per-turn task-board goals, active runs, required validation evidence, and operator-task provenance when present. | `<stateDir>/sessions/<cwdHash>/<sessionId>/current.jsonl` |
+| **Workspace outputs** | Latest successful `artifact`, `write`, or `edit` result for each normalized path on the active session branch. Missing files remain visible as durable recorded facts. | Recorded path beneath the session metadata `cwd` |
 | **Tool outputs** | Offloaded large outputs or execution logs. | `<stateDir>/scratch/<sessionId>/<toolCallId>.txt` |
 | **Protected artifacts** | Validation-protected artifact metadata and its absolute artifact path when available. | Session ledger record plus the protected workspace path |
 | **Compaction** | Summaries of compacted history sessions. | `<stateDir>/sessions/<cwdHash>/<sessionId>/current.jsonl` |
 | **Prompt manifests** | One validated record per prompt compile: `systemPromptHash`, previous hash, token estimate, thinking dial at compile time, per-section token estimates, and per-fragment content hashes. Identifies the exact compiled prompt and supports hash diffs without storing prompt text. Malformed records appear as an explicit read-error artifact. | `<stateDir>/sessions/<cwdHash>/<sessionId>/prompt-manifest.jsonl` |
 | **Safety audit rows** | Current-session safety and permission decisions, with malformed ledger lines surfaced separately. | `<stateDir>/audit/<date>.jsonl` |
 
+Workspace output containment is checked again when the operator loads an item, not only when `/view` builds its list. The loader re-resolves the recorded workspace root and target through symlinks on every load, verifies canonical path-segment containment, and reads the canonical target. A target or ancestor symlink swapped outside the workspace is refused. A missing target keeps the recorded timestamp and reports `file no longer on disk`; it does not disappear from the artifact history.
+
 ---
 
 ## The Accountability Panel
@@ -156,8 +159,8 @@ The base provenance sets, steering, routing, quality, worker identity, and resul
 | `safety.toolTelemetry.ingestionErrors` | `number` | Current dispatch receipts | Malformed or lost frames, event-fold/source errors, and drain timeouts that make otherwise mediated telemetry incomplete | experimental |
 | `safety.toolTelemetry.unfinished` | `{ tool, count }[]` | Current dispatch receipts | Tool starts that had no matching finish when the receipt sealed | experimental |
 | `safety.toolTelemetry.workspaceMutationPossible` | `boolean` | Current dispatch receipts | Whether incomplete or unavailable telemetry could conceal a shared-workspace mutation; retry admission fails closed when true | experimental |
-| `autonomyEnforcement.grade` | `string` | Always in v0.3.0 | The autonomy grade level enforced for the run | experimental |
-| `autonomyEnforcement.autonomy` | `string` | Always in v0.3.0 | The effective autonomy level name (e.g. auto-edit, suggest, read-only, full-auto) | experimental |
+| `autonomyEnforcement.grade` | `string` | Always in v0.3.2 | The autonomy grade level enforced for the run | experimental |
+| `autonomyEnforcement.autonomy` | `string` | Always in v0.3.2 | The effective autonomy level name (e.g. auto-edit, suggest, read-only, full-auto) | experimental |
 | `autonomyEnforcement.externalMode` | `string` | When running external worker | The execution mode of the external worker runtime | experimental |
 | `autonomyEnforcement.dangerousBypass` | `boolean` | When running external worker | Whether a safety bypass was explicitly activated | experimental |
 | `validationGrounding.claimed` | `number` | Validation grounding evaluated | Count of validations claimed by worker | experimental |