cool-workflow 0.1.92 → 0.1.94

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "cool-workflow",
   "description": "A workflow control plane and run-time you are able to check: it sends out jobs in TypeScript, makes certain of work against facts before it goes through, puts state into fixed records, orders jobs by time, runs jobs again and again, gets a group of agents to do their parts together, and talks MCP. It gives the doing of the work to outside agents — it never runs the models itself.",
-  "version": "0.1.92",
+  "version": "0.1.94",
   "author": {
     "name": "COOLWHITE LLC"
   },

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cool-workflow",
-  "version": "0.1.92",
+  "version": "0.1.94",
   "description": "A workflow control plane and run-time you are able to check: it sends out jobs in TypeScript, makes certain of work against facts before it goes through, puts state into fixed records, orders jobs by time, runs jobs again and again, gets a group of agents to do their parts together, and talks MCP. It gives the doing of the work to outside agents — it never runs the models itself.",
   "author": {
     "name": "COOLWHITE LLC"

package/README.md

@@ -1,217 +1,192 @@
 <!-- AUTO-GENERATED from /README.md by scripts/sync-readme.js — edit the root README, then run `npm run sync:readme`. DO NOT edit this file directly. -->
 <div align="center">
 
-# Cool Workflow
+<img src="https://raw.githubusercontent.com/coo1white/cool-workflow/main/docs/assets/cw-hero.png" alt="Cool Workflow — your AI report, already proven. Point your agent at any repo or folder and get a saved, cited report you can re-verify offline." width="100%">
 
-**Get a saved, cited report from your AI agent — not a chat message you lose.**
+<br><br>
 
-[![CI](https://img.shields.io/github/actions/workflow/status/coo1white/cool-workflow/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/coo1white/cool-workflow/actions/workflows/ci.yml)
+[![CI](https://img.shields.io/github/actions/workflow/status/coo1white/cool-workflow/ci.yml?branch=main&style=flat-square&label=CI&color=EC6516)](https://github.com/coo1white/cool-workflow/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/cool-workflow?style=flat-square&label=npm&color=cb3837)](https://www.npmjs.com/package/cool-workflow)
-[![downloads](https://img.shields.io/npm/dm/cool-workflow?style=flat-square&label=downloads)](https://www.npmjs.com/package/cool-workflow)
+[![downloads](https://img.shields.io/npm/dm/cool-workflow?style=flat-square&label=downloads&color=EC6516)](https://www.npmjs.com/package/cool-workflow)
 [![provenance](https://img.shields.io/badge/npm-provenance-3178C6?style=flat-square)](https://www.npmjs.com/package/cool-workflow)
 [![release](https://img.shields.io/github/v/tag/coo1white/cool-workflow?style=flat-square&label=release&color=brightgreen&sort=semver)](https://github.com/coo1white/cool-workflow/tags)
 [![license](https://img.shields.io/badge/license-BSD--2--Clause-blue?style=flat-square)](https://github.com/coo1white/cool-workflow/blob/main/LICENSE)
 
-<img src="https://raw.githubusercontent.com/coo1white/cool-workflow/main/docs/assets/cw-hero.svg" alt="Your AI report, already proven — cw demo tamper forges a signed report three ways (ledger, signature, result) and catches every one offline with only the public key." width="100%">
+### Get a saved, cited report from your AI agent — not a chat message you lose.
 
 </div>
 
+Point an AI coding agent at a repo (or any folder of docs) and Cool Workflow turns the run into a
+**durable, inspectable workflow**: it plans the work, delegates each task to *your* agent, records and
+verifies every result, then writes a report where every claim is cited to a `file.ts:42`.
+
+> **The model is fuel. CW is the black-box recorder, the dashboard, and the gearbox — never the engine.**
+> It never calls a model API, never holds your keys, and never uploads your code. Your agent spends the
+> tokens; CW keeps the books — as plain JSON on your own disk.
+
+---
+
 ## Install
 
 ```bash
 npm install -g cool-workflow
 ```
 
-What you need: **Node.js v18+** (`node --version`) and one AI agent CLI on your machine
-(`claude`, `codex`, `gemini`, or `opencode`). No agent? `cw demo` still works — CW never runs a model itself.
+<details>
+<summary>Or install with <b>Homebrew</b></summary>
+
+```bash
+brew tap coo1white/cool-workflow https://github.com/coo1white/cool-workflow
+brew install coo1white/cool-workflow/cool-workflow
+cw version
+```
 
-## Quick Start (3 steps)
+Upgrade later with `brew update && brew upgrade cool-workflow`.
+</details>
 
-### 1. Prove it works (30 seconds, no agent needed)
+**You need:** Node.js v18+ and one agent CLI on your machine — `claude`, `codex`, `gemini`, or
+`opencode` (all auto-detected). No agent yet? `cw demo` still works — **CW never runs a model itself.**
+
+## Quick Start
+
+### 1 · Prove it works — 30 seconds, no agent needed
 
 ```bash
 cw demo tamper
+# → builds a real signed ledger, forges it three ways, catches all three offline
 # → VERDICT: tamper-evidence holds ✓
 ```
 
-### 2. Ask a question — your code, or any folder — one command
+### 2 · Ask a question about your code — one command
 
 ```bash
 cw -q "What are the main risks here?"
 ```
 
-CW auto-detects the repo (current folder) and your agent (first found on PATH).
-Pick a specific agent with a flag:
+CW auto-detects the current repo and the first agent on your `PATH`. Pin a specific one with a flag
+(`-claude`, `-codex`, `-gemini`, `-deepseek`). Point it anywhere — no `cd` required — or review a
+**remote repo by URL** and CW clones, snapshots, and reviews the checkout:
 
 ```bash
-cw -q "What are the security risks?" -claude
-cw -q "What are the security risks?" -codex
-cw -q "What are the security risks?" -deepseek
+cw -q "What are the security risks?" -dir /path/to/project
+cw -q "What are the risks?" --link https://github.com/owner/repo
 ```
 
-`claude`, `codex`, `gemini`, and `opencode` are auto-detected on PATH (no flag needed);
-`-deepseek` picks the DeepSeek builtin — no env vars needed.
-
-**Not just code.** Point CW at a folder of docs, notes, or papers and it reads the files
-there as sources, then gives you the same saved, cited report:
+**Not just code.** Aim CW at a folder of docs, notes, or papers and it reads them as sources for the
+same saved, cited report:
 
 ```bash
 cw quickstart research-synthesis --repo /path/to/papers \
   --question "What do these papers conclude?"
 ```
 
-As the agent works you get a **calm, Claude-Code-style live view** — a compact rolling window that
-updates in place instead of an endless wall:
+### 3 · Open the report
 
-```text
-● Read(execution-backend.ts)
-  ⎿ 910 lines
-● Grep(spawnSync)
-  ⎿ 17 matches
-✶ Searching worker-isolation.ts… (3s)
-```
-
-Each tool folds to a `● ToolName(arg)` line with a dim `⎿` result summary; older steps fold away (the
-window stays a few rows) and the worker collapses to one line when done. It's compact by default
-(reasoning hidden) — add `--verbose` for the full narration, `--full` to also print the report inline,
-or `--no-color` to drop ANSI (`NO_COLOR` / `FORCE_COLOR` are honored too). The complete narration +
-tool I/O is always saved to a per-worker `transcript.md` next to the result, and the cursor is
-restored cleanly on Ctrl-C.
-
-Review a project **from any directory** — no `cd` needed — by pointing at its folder
-(`-d` / `--dir` / `--repo` are equivalent):
-
-```bash
-cw -q "What are the risks?" -dir /path/to/project
-```
-
-Or review a **remote repo by URL** — CW clones it, then reviews the checkout (`-l` / `--link`,
-or pass the URL straight to `-dir`/`--repo`):
+The command prints the path. Every finding carries a clickable `file.ts:42` pointer:
 
 ```bash
-cw -q "What are the risks?" --link https://github.com/owner/repo
-cw -q "What are the risks?" --link git@gitlab.com:owner/repo.git --ref v1.2.0
+cat .cw/runs/<run-id>/report.md
 ```
 
-GitHub, GitLab, Bitbucket, self-hosted git, `ssh://`, and `file://` all work — as do downloadable
-archives (`.tar.gz`/`.tgz`/`.tar`/`.zip`), fetched + extracted + snapshotted before review. The clone is cached
-under `~/.local/state/cool-workflow/clones/` and reused next time (`--refresh` re-fetches; `cw clones
-list`/`gc` manage it). The report records `Source: <url>@<commit>` plus a tamper-evident
-`source.clone` event (`cw audit verify`). A credential-less private repo **fails closed** — it never
-hangs on a prompt. Preview without fetching: `cw -q "…" --link <url> --check`.
+While it runs you get a calm, Claude-Code-style live view — a compact rolling window of tool calls
+that updates in place instead of an endless wall — and a clean findings table when it's done.
 
-CW's own phases tick by as it runs, then it prints a clean summary — a **compact findings table**
-(id / severity / classification, not the full prose), the report path, and where the per-worker
-transcripts live:
+---
 
-```text
-==> Map ✓ (6/6)
-==> Verdict ✓
+## Why Cool Workflow
 
-Findings: 3 — 2×P1, 1×P2
+Most agent tooling runs a whole task as one long prompt, then hands you a chat message. When the work
+is long, parallel, or high-stakes, you can't tell what happened or trust the result. CW treats it as a
+**runtime problem** — and rests on four commitments:
 
-✓ Report: /path/to/project/.cw/runs/<run-id>/report.md
-  ✓ Status: complete — 14/14
-  Transcript: /path/to/project/.cw/runs/<run-id>/
-  Next: cw report <run-id> --show
-```
+| Commitment | What it means for you |
+|---|---|
+| **Model as fuel, not engine** | CW never calls a model API. Execution is always delegated to your agent, so the backend is swappable and your credentials and code never leave your machine. |
+| **Evidence-gated decisions** | Every adopted result records its **basis, authority, rationale, and the alternative it beat.** Missing evidence doesn't slip through — it fails closed to a visible `unexplained` state. |
+| **Deterministic, local replay** | Every step is plain JSON under `.cw/runs/<id>/` — read it, diff it, resume it, replay it. No hidden database; the runtime never *guesses* success. |
+| **Vendor-neutral by design** | One source-of-truth manifest generates every vendor adapter (Claude, Codex, …) over a shared CLI + MCP runtime, with a fail-closed drift check. No lock-in, no forked logic. |
 
-If something is off, the error names the next move (e.g. `Try: cw doctor`). With `--json`,
-stdout is pure data — all of this chrome goes to stderr (TTY only).
+## How It Works
 
-### 3. Open the report
+CW is a small TypeScript tool with **zero runtime dependencies**. It drives your agent over a repo — or
+any folder — in saved, replayable stages, writing everything to disk as inspectable files. It never
+imports a model SDK or stores an API key.
 
-The command prints the report path. For example:
+<div align="center">
+<img src="https://raw.githubusercontent.com/coo1white/cool-workflow/main/docs/assets/cw-pipeline.png" alt="The CW pipeline: ask, plan, dispatch (delegated to your agent), verify (evidence gate, fails closed), commit verified state, and a saved, cited, signed report — every step recorded as durable .cw/ JSON." width="100%">
+</div>
 
-```bash
-cat .cw/runs/<run-id>/report.md
-# → findings with clickable file.ts:42 pointers for every claim
+```text
+ask simple → run simple → verify simple → resume simple
 ```
 
-## What Else Can It Do?
+## What You Can Run
+
+| Workflow | What it produces |
+|---|---|
+| `architecture-review` | Map a repo, rank risks, and back every claim with `file:line` evidence |
+| `pr-review-fix-ci` | Review a PR or branch, diagnose CI, and propose + verify fixes |
+| `research-synthesis` | Answer a question over a local folder of files — your docs, notes, or papers |
+| `release-cut` | Run a gated, reviewed release with dry-run evidence |
 
 ```bash
-cw version                        # show version
-cw update                         # update to latest release
-cw doctor                         # check your setup
-cw fix                            # show fix commands for setup issues
+cw app list            # see everything installed
+cw doctor              # check your setup    →    cw fix   shows the fix commands
 ```
 
-| Workflow | Does |
-|---|---|
-| `architecture-review` | Map a repo, rank risks, back every claim with evidence |
-| `pr-review-fix-ci` | Review a pull request, suggest fixes, verify CI |
-| `research-synthesis` | Answer a question over a local folder of files — your own docs, notes, or papers, not only code |
-| `release-cut` | Run a gated, reviewed release |
-
-**Multi-agent, when you need it.** Fan work out across agents with built-in topologies,
-compose flows (a task can run a whole child workflow with `subWorkflow`, or a `loop()` phase
-can keep iterating until a predicate or a token budget says stop) — and re-run fast:
-`cw run <app> --drive --incremental` reuses every step whose inputs didn't change.
+**Multi-agent, when you need it.** Fan work out across agents with built-in topologies, compose flows
+(a task can run a whole child workflow with `subWorkflow`, or a `loop()` phase can iterate until a
+predicate or token budget says stop), and re-run fast — `cw run <app> --drive --incremental` reuses
+every step whose inputs didn't change.
 
 <div align="center">
 <img src="https://raw.githubusercontent.com/coo1white/cool-workflow/main/docs/assets/topologies.svg" alt="Built-in multi-agent topologies: map-reduce (fan out, fold in), debate (argue then draw a verdict), and judge-panel (N independent judges score one candidate)." width="92%">
 </div>
 
-CW also has an **MCP** surface — **Claude Desktop, Cursor, and VS Code call CW as a tool**, so
-your agent can plan a run, drive it, and verify a report without leaving the editor.
-See the [wiki](https://github.com/coo1white/cool-workflow/wiki).
-
-## Can I Trust the Report?
+## Can You Trust the Report?
 
-CW does not run the AI model — it keeps the books. The agent signs its findings (ed25519), and
-`cw report verify-bundle` checks — offline, with nothing but the public key — that every signed
-finding is in the report **unaltered**: edit a finding, in the report or in the agent's own result,
-and the check fails. CW holds no private key — the agent signs, CW only verifies.
+CW doesn't run the model — it keeps the books. Your agent signs its findings (**ed25519**), and
+`cw report verify-bundle` checks — **offline, with nothing but the public key** — that every signed
+finding is in the report unaltered. Edit a finding, in the report or in the agent's own result, and the
+check fails. CW holds no private key: the agent signs, CW only verifies.
 
 ```bash
-cw demo tamper                              # proves it in 30s — edits a signed result, watch it fail
-cw telemetry verify <run-id>                # checks a real run
+cw demo tamper                                  # proves it in 30s — edits a signed result, watch it fail
+cw -q "…" --bundle                              # seal a run into one portable file
+cw report verify-bundle report.cwrun.json       # anyone can re-check it offline, with just the file
 ```
 
-Give the report to another person — they need nothing but the file:
+This attests the agent's **signed findings** — not that nothing else was added or that nothing was left
+out. For exactly what is and isn't proven, see the **[Trust Model](https://github.com/coo1white/cool-workflow/blob/main/plugins/cool-workflow/docs/trust-model.md)**.
 
-```bash
-cw -q "…" --bundle                              # seal into one portable file
-cw report verify-bundle report.cwrun.json       # they check it offline
-cw report verify-bundle report.cwrun.json \
-  --require-signatures                          # …and insist the findings are signed
-```
+## Use It From Your Editor
 
-This attests the agent's **signed findings** — not that the report holds nothing else, and not that
-none were left out. CW has no key to sign the rendered report, and a determined re-chainer can drop a
-signed finding entirely — so check the findings you act on against the signed results. For exactly
-what is and is not proven, see the [Trust Model](https://github.com/coo1white/cool-workflow/blob/main/plugins/cool-workflow/docs/trust-model.md).
+CW exposes the same runtime over **MCP** — **Claude Desktop, Cursor, and VS Code call CW as a tool**, so
+your agent can plan a run, drive it, and verify a report without leaving the editor. CLI and MCP share
+one registry and are parity-checked. See the **[Wiki](https://github.com/coo1white/cool-workflow/wiki)**.
 
 ## Troubleshooting
 
 | Problem | Fix |
 |---|---|
-| No agent found | Run `cw doctor` — it shows which agents are on your machine |
+| No agent found | `cw doctor` — shows which agents are on your machine |
 | `status: blocked` | Set `CW_AGENT_COMMAND=builtin:claude` or pass `-claude` |
 | `claude: command not found` | Install Claude Code and run again |
 | Where is my report? | `<repo>/.cw/runs/<id>/report.md` |
-| Need the old README? | See [docs/readme-v0.1.87-full.md](https://github.com/coo1white/cool-workflow/blob/main/plugins/cool-workflow/docs/readme-v0.1.87-full.md) |
 
-## How It Works
-
-CW is a small TypeScript tool with zero runtime deps. It drives your agent over a repo, or any
-folder of files, in saved, replayable stages — it plans the work, dispatches each task to your agent, records and
-verifies every result, then commits and renders the report — writing everything to disk as
-inspectable files. It never imports a model SDK or stores an API key.
-
-<div align="center">
-<img src="https://raw.githubusercontent.com/coo1white/cool-workflow/main/docs/assets/pipeline.svg" alt="The CW pipeline: ask, plan, dispatch (fanning out to parallel agents), verify, commit, ending in a saved report.md with a clickable file.ts:42 citation. CW keeps the books; it never runs the model itself." width="100%">
-</div>
+## Docs & Wiki
 
-`ask simple → run simple → verify simple → resume simple`
+New here? Start with the **[Wiki](https://github.com/coo1white/cool-workflow/wiki)** →
+[Getting Started](https://github.com/coo1white/cool-workflow/wiki/Getting-Started) ·
+[Mental Model](https://github.com/coo1white/cool-workflow/wiki/Mental-Model) ·
+[Glossary](https://github.com/coo1white/cool-workflow/wiki/Glossary) ·
+[Trust & Audit](https://github.com/coo1white/cool-workflow/wiki/Trust-And-Audit)
 
-For the full API, multi-agent topologies, execution backends, and the CLI/MCP surface,
-see the [wiki](https://github.com/coo1white/cool-workflow/wiki).
+Building on CW? See the [Getting Started doc](https://github.com/coo1white/cool-workflow/blob/main/plugins/cool-workflow/docs/getting-started.md),
+[Project Index](https://github.com/coo1white/cool-workflow/blob/main/plugins/cool-workflow/docs/project-index.md), and
+[CLI ↔ MCP Parity](https://github.com/coo1white/cool-workflow/blob/main/plugins/cool-workflow/docs/cli-mcp-parity.7.md).
 
-CW dogfoods its own release process — every cut runs the `release-cut` workflow against this
-repo. See the [full README](https://github.com/coo1white/cool-workflow/blob/main/plugins/cool-workflow/docs/readme-v0.1.87-full.md) for the
-pre-v0.1.87 reference.
+CW dogfoods its own release process — every cut runs the `release-cut` workflow against this repo.
 
 ## License
 

package/apps/architecture-review/app.json

@@ -3,7 +3,7 @@
   "id": "architecture-review",
   "title": "Architecture Review",
   "summary": "Map a repository architecture, assess risks, verify important findings, and synthesize an evidence-backed verdict.",
-  "version": "0.1.92",
+  "version": "0.1.94",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/apps/architecture-review-fast/app.json

@@ -3,7 +3,7 @@
   "id": "architecture-review-fast",
   "title": "Architecture Review Fast",
   "summary": "Run a shorter architecture review with parallel map and assess phases for faster first results.",
-  "version": "0.1.92",
+  "version": "0.1.94",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/apps/architecture-review-fast/workflow.js

@@ -100,7 +100,14 @@ module.exports = ({ workflow, phase, parallel, agent, artifact, input }) => {
             "Confirm real risks, downgrade unsupported claims, and list exact file paths, commands, logs, or unknowns.",
             "The cw:result evidence array must cite durable locators."
           ].join(" "),
-          strongOptions("Evidence verifier", { requiresEvidence: true })
+          strongOptions("Evidence verifier", {
+            requiresEvidence: true,
+            // Cache the (expensive, ~146s live) verification by source digest +
+            // ALL upstream phase result digests. A hit only when source AND every
+            // Map/Assess output are byte-identical; the cached result still passes
+            // worker-output validation (requiresEvidence stays enforced).
+            resultCache: sourceContextResultCache({ includeCompletedResults: "previous-phases" })
+          })
         )
       ]),
       phase("Verdict", [
@@ -113,7 +120,13 @@ module.exports = ({ workflow, phase, parallel, agent, artifact, input }) => {
             "State when the full architecture-review app should be scheduled as a background routine.",
             "The cw:result evidence array must support the final verdict."
           ].join(" "),
-          strongOptions("Fast verdict synthesizer", { requiresEvidence: true })
+          strongOptions("Fast verdict synthesizer", {
+            requiresEvidence: true,
+            // Cache the (~294s live, largest phase) synthesis by source digest +
+            // all upstream (Map/Assess/Verify) result digests. Busts on any
+            // upstream change; cached verdict re-passes evidence validation.
+            resultCache: sourceContextResultCache({ includeCompletedResults: "previous-phases" })
+          })
         )
       ])
     ]

package/apps/end-to-end-golden-path/app.json

@@ -3,7 +3,7 @@
   "id": "end-to-end-golden-path",
   "title": "End-to-End Golden Path",
   "summary": "Deterministic one-worker workflow app for proving the CW integration chain.",
-  "version": "0.1.92",
+  "version": "0.1.94",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/apps/pr-review-fix-ci/app.json

@@ -3,7 +3,7 @@
   "id": "pr-review-fix-ci",
   "title": "PR Review Fix CI",
   "summary": "Review a pull request or branch, inspect CI failures, diagnose actionable issues, optionally patch, verify, and summarize with evidence.",
-  "version": "0.1.92",
+  "version": "0.1.94",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/apps/release-cut/app.json

@@ -3,7 +3,7 @@
   "id": "release-cut",
   "title": "Release Cut",
   "summary": "Prepare a release with checklist discipline: version checks, changelog, tests, packaging, release notes, and final verification.",
-  "version": "0.1.92",
+  "version": "0.1.94",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/apps/research-synthesis/app.json

@@ -3,7 +3,7 @@
   "id": "research-synthesis",
   "title": "Research Synthesis",
   "summary": "Split a research question into claims, investigate sources, cross-check evidence, verify claims, and synthesize a concise answer.",
-  "version": "0.1.92",
+  "version": "0.1.94",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/dist/capability-core.js

@@ -40,6 +40,7 @@ exports.runExportArchive = runExportArchive;
 exports.runImportArchive = runImportArchive;
 exports.runInspectArchive = runInspectArchive;
 exports.runVerifyImport = runVerifyImport;
+exports.runRestoreArchive = runRestoreArchive;
 exports.reportBundle = reportBundle;
 exports.runVerifyReportBundle = runVerifyReportBundle;
 exports.queueAdd = queueAdd;
@@ -313,6 +314,52 @@ function runInspectArchive(_runner, args) {
 function runVerifyImport(runner, runId, args) {
     return (0, run_export_1.verifyImportedRun)(runner.withBaseDir(optionalString(args.cwd)).loadRun(runId));
 }
+// Fail-closed atomic restore of a portable run archive. `run import` runs a
+// verification (importRun returns it as ImportResult.verification) but does NOT
+// fail on it — it exits 0 even when the telemetry-ledger or trust-audit hash chain
+// does not verify, so a chain-tampered run imports with a fabricated success.
+// `run restore` closes that gap in ONE step: it integrity-INSPECTS the archive
+// FIRST (writing nothing), refuses a bad bundle before any import, then IMPORTS
+// and REUSES importRun's verification verdict — reporting ok:true ONLY when verify
+// passes. Pure composition of the existing functions (inspectArchive + importRun,
+// whose own verification we reuse); no new crypto or IO logic, and no second
+// re-hash. The CLI/MCP surfaces map ok:false to exit 1.
+function runRestoreArchive(runner, args) {
+    const base = invocationCwd(args);
+    const archive = optionalString(args.archive || args.path || args.file);
+    if (!archive)
+        throw new Error("run restore requires an archive path (positional, --archive, --path, or --file)");
+    const resolvedArchive = node_path_1.default.resolve(base, archive);
+    const target = node_path_1.default.resolve(base, optionalString(args.target || args.repo || args.cwd) || base);
+    // (1) Integrity-inspect FIRST — read-only, writes nothing. A bad bundle is
+    // refused here, before any import touches the target tree (no partial restore).
+    const inspect = (0, run_export_1.inspectArchive)(resolvedArchive);
+    if (!inspect.ok) {
+        return { schemaVersion: 1, ok: false, target, inspect, imported: null, verify: null, registry: null };
+    }
+    // (2) Intact: import + refresh the target registry (mirrors runImportArchive).
+    const imported = (0, run_export_1.importRun)(resolvedArchive, target);
+    const registry = new run_registry_1.RunRegistry(target, runner.withBaseDir(target));
+    const registryReport = registry.refresh({ scope: "repo" });
+    // (3) REUSE the verification importRun already ran — it re-proves the same
+    // restored files PLUS the telemetry-ledger and trust-audit hash chains, but
+    // returns the verdict WITHOUT throwing. We do NOT re-run verifyImportedRun (that
+    // would re-hash every file a second time for no new information). The gap restore
+    // closes is exactly that `run import` ships this verdict and exits 0 even when it
+    // is false — restore fails-closed on it below (CLI maps ok:false → exit 1).
+    const verify = imported.verification;
+    return {
+        schemaVersion: 1,
+        // inspect.ok is guaranteed true here — the corrupt-archive case early-returned
+        // above — so the verdict is purely verify.ok (the telemetry/trust-audit chain).
+        ok: verify.ok,
+        target,
+        inspect,
+        imported: { ...imported, registry: registryReport },
+        verify,
+        registry: registryReport
+    };
+}
 // Produce-and-prove: export a run to a portable bundle sealed with the operator's
 // trust key (defaulting to CW_AGENT_ATTEST_PUBKEY, same as `run export`), then
 // IMMEDIATELY verify the artifact offline the way a recipient will. The producer

package/dist/capability-registry.js

@@ -395,6 +395,7 @@ const BUILTIN_CAPABILITIES = [
     { capability: "run.import", summary: "Restore a portable run archive into a target repo and verify restored file digests.", entry: "runImportArchive", surface: "both", cli: { path: ["run", "import"], jsonMode: "default" }, mcp: { tool: "cw_run_import", requiredArgs: ["archive|path|file"] } },
     { capability: "run.verify-import", summary: "Verify an imported run against its restore manifest and telemetry chain.", entry: "runVerifyImport", surface: "both", cli: { path: ["run", "verify-import"], jsonMode: "default" }, mcp: { tool: "cw_run_verify_import", requiredArgs: ["runId"] } },
     { capability: "run.inspect-archive", summary: "Read-only integrity inspection of a portable run archive without importing it.", entry: "runInspectArchive", surface: "both", cli: { path: ["run", "inspect-archive"], jsonMode: "default" }, mcp: { tool: "cw_run_inspect_archive", requiredArgs: ["archive|path|file"] } },
+    { capability: "run.restore", summary: "Fail-closed restore of a portable run archive: integrity-inspect, import, and verify in one step; refuses anything that does not verify.", entry: "runRestoreArchive", surface: "both", cli: { path: ["run", "restore"], jsonMode: "default" }, mcp: { tool: "cw_run_restore", requiredArgs: ["archive|path|file"] } },
     { capability: "report.verify-bundle", summary: "Offline self-contained verify of a portable run bundle: archive bytes + telemetry chain + trust-audit chain + embedded-key signatures.", entry: "runVerifyReportBundle", surface: "both", cli: { path: ["report", "verify-bundle"], caseTokens: ["report"], jsonMode: "default" }, mcp: { tool: "cw_report_verify_bundle", requiredArgs: ["archive|path|file|bundle"] } },
     { capability: "report.bundle", summary: "Produce-and-prove: export a run to a portable bundle sealed with the trust key, then self-verify it offline (fail-closed) so the producer knows it is verifiable before shipping.", entry: "reportBundle", surface: "both", cli: { path: ["report", "bundle"], caseTokens: ["report"], jsonMode: "default" }, mcp: { tool: "cw_report_bundle", requiredArgs: ["runId"] } },
     { capability: "run.drive", summary: "Preview the next agent-delegation drive step for a run (read-only, deterministic).", entry: "runDrivePreview", surface: "both", cli: { path: ["run", "drive"], caseTokens: ["run", "drive"], jsonMode: "default" }, mcp: { tool: "cw_run_drive" } },
@@ -655,6 +656,7 @@ const PAYLOAD_PROBE_DEFERRED_GROUPS = [
             "run.import",
             "run.verify-import",
             "run.inspect-archive",
+            "run.restore",
             "report.verify-bundle",
             "report.bundle",
             "queue.add",