cool-workflow 0.1.89 → 0.1.91

package/dist/term.js

@@ -16,10 +16,29 @@ exports.cyan = cyan;
 exports.doctorGlyph = doctorGlyph;
 exports.cwLabel = cwLabel;
 exports.indent = indent;
+exports.nextHint = nextHint;
+exports.tryHint = tryHint;
+exports.sectionHeader = sectionHeader;
+exports.phaseProgressLine = phaseProgressLine;
+exports.formatDuration = formatDuration;
 exports.printSuccessSummary = printSuccessSummary;
+exports.stripAnsi = stripAnsi;
+exports.visibleWidth = visibleWidth;
+exports.truncate = truncate;
+exports.formatFindingsSummary = formatFindingsSummary;
 function isTTY(stream = process.stderr) {
     return Boolean(stream.isTTY);
 }
+/** Whether to emit ANSI color on a stream, honoring the de-facto env standards:
+ *  NO_COLOR / CW_NO_COLOR (any non-empty value) disable; FORCE_COLOR (non-"0") forces on
+ *  even when piped; otherwise fall back to isTTY. The `--no-color` flag sets CW_NO_COLOR. */
+function colorEnabled(stream, env = process.env) {
+    if ((env.NO_COLOR ?? "") !== "" || (env.CW_NO_COLOR ?? "") !== "")
+        return false;
+    if (env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== "" && env.FORCE_COLOR !== "0")
+        return true;
+    return isTTY(stream);
+}
 // ---- ansi codes ----
 const ansi = {
     reset: "\x1b[0m",
@@ -32,7 +51,7 @@ const ansi = {
 };
 // ---- styled text ----
 function style(code, text, stream) {
-    if (!isTTY(stream))
+    if (!colorEnabled(stream))
         return text;
     return `${code}${text}${ansi.reset}`;
 }
@@ -74,20 +93,119 @@ function indent(text, spaces = 2) {
     const prefix = " ".repeat(spaces);
     return text.split("\n").map((line) => `${prefix}${line}`).join("\n");
 }
-/** Print a success summary to stderr (TTY-gated). Shows the report path and a
- *  suggested next command. Pipe-friendly: silent when stderr is not a TTY. */
+/** A `Next: <cmd>` hint line (the command stays plain so it is copy-pasteable). */
+function nextHint(cmd, stream) {
+    return `${dim("Next:", stream)} ${cmd}`;
+}
+/** A `Try: <cmd>` recovery hint (brew-style; the command stays plain to copy). */
+function tryHint(cmd, stream) {
+    return `${dim("Try:", stream)} ${cmd}`;
+}
+/** A `==> Title` section header (brew-style). */
+function sectionHeader(title, stream) {
+    return `${bold("==>", stream)} ${title}`;
+}
+/** A phase-progress line: `==> Map ✓ (6/6)` / `==> Assess … (3/6)`. Parallel phases
+ *  use ⇉, sequential use …; a finished phase uses a green ✓. */
+function phaseProgressLine(name, done, total, mode, stream) {
+    const complete = total > 0 && done >= total;
+    const glyph = complete ? green("✓", stream) : (mode === "parallel" ? "⇉" : "…");
+    const count = total > 0 ? ` (${done}/${total})` : "";
+    return `${sectionHeader(name, stream)} ${glyph}${count}`;
+}
+/** Format a DURATION in ms as `850ms` / `5.2s` / `1m02s`. Pure (no clock) — the
+ *  caller measures elapsed via process.hrtime, so this never reads wall-clock time. */
+function formatDuration(ms) {
+    if (ms < 1000)
+        return `${Math.max(0, Math.round(ms))}ms`;
+    const s = Math.round(ms / 100) / 10;
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    const rem = Math.round(s % 60);
+    return `${m}m${String(rem).padStart(2, "0")}s`;
+}
+/** Print a success summary to stderr (TTY-gated). Shows the report path, a one-line
+ *  status (with N/N worker counts when known), and a copy-pasteable next/recovery
+ *  command. Pipe-friendly: silent when stderr is not a TTY, so it never pollutes
+ *  piped/`--json` stdout. A non-complete run with no agent configured gets a brew-style
+ *  `Try: cw doctor` recovery line; otherwise `Next: cw status <id>` to inspect. */
 function printSuccessSummary(fields, stream) {
     if (!isTTY(stream))
         return;
     const s = stream || process.stderr;
-    s.write(`\n${green("✓")} Report: ${fields.reportPath}\n`);
+    const counts = (typeof fields.completedWorkers === "number" && typeof fields.plannedWorkers === "number")
+        ? ` — ${fields.completedWorkers}/${fields.plannedWorkers}` : "";
+    s.write(`\n${green("✓", s)} Report: ${fields.reportPath}\n`);
     if (fields.status === "complete") {
-        s.write(`  Next: cw status ${fields.runId} --brief\n`);
-        if (fields.bundle !== false) {
-            s.write(`  Bundle: cw report bundle ${fields.runId}\n`);
-        }
+        s.write(`  ${green("✓", s)} Status: complete${counts}\n`);
+        s.write(`  ${nextHint(`cw report ${fields.runId} --show`, s)}\n`);
     }
     else {
-        s.write(`  ${yellow("!")} Status: ${fields.status}. Next: cw status ${fields.runId}\n`);
+        s.write(`  ${yellow("!", s)} Status: ${fields.status}${counts}\n`);
+        // No agent backend is the #1 first-run blocker — point at the one command that
+        // diagnoses and prints the fix, brew-style. Otherwise inspect the run's state.
+        if (fields.agentConfigured === false)
+            s.write(`  ${tryHint("cw doctor", s)}\n`);
+        else
+            s.write(`  ${nextHint(`cw status ${fields.runId}`, s)}\n`);
+    }
+}
+// ---- width-aware truncation (zero-dep) ----
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+/** Strip ANSI SGR codes (for measuring visible width). */
+function stripAnsi(text) {
+    return text.replace(ANSI_RE, "");
+}
+/** Visible width of a string, ignoring ANSI. Counts each code point as width 1 — a known
+ *  minor caveat for wide (CJK/emoji) glyphs, acceptable for one-line status truncation. */
+function visibleWidth(text) {
+    return [...stripAnsi(text)].length;
+}
+/** Truncate a (possibly styled) string to `maxWidth` visible columns, appending `…` when cut.
+ *  Operates on the PLAIN text (callers truncate before styling), so no ANSI is split. */
+function truncate(text, maxWidth) {
+    if (maxWidth <= 0)
+        return "";
+    const chars = [...stripAnsi(text)];
+    if (chars.length <= maxWidth)
+        return text;
+    if (maxWidth === 1)
+        return "…";
+    return `${chars.slice(0, maxWidth - 1).join("")}…`;
+}
+// ---- findings summary table (end-of-run, compact) ----
+/** Severity order for sorting + counting (most severe first). */
+const SEVERITY_ORDER = ["P0", "P1", "P2", "P3", "none"];
+/** Render a compact findings summary assembled from the run's `cw:result` blocks: a one-line
+ *  count headline (e.g. `Findings: 3 — 2×P1, 1×P2`) plus a small id/severity/class table. This
+ *  is the end-of-run summary — NOT the full prose (that stays in report.md + the transcript).
+ *  Returns "" when there are no findings (caller prints nothing). */
+function formatFindingsSummary(findings, stream) {
+    if (!findings.length)
+        return "";
+    const bySev = new Map();
+    for (const f of findings)
+        bySev.set(f.severity || "none", (bySev.get(f.severity || "none") || 0) + 1);
+    const order = (s) => {
+        const i = SEVERITY_ORDER.indexOf(s);
+        return i === -1 ? SEVERITY_ORDER.length : i;
+    };
+    const counts = [...bySev.entries()]
+        .sort((a, b) => order(a[0]) - order(b[0]))
+        .map(([sev, n]) => `${n}×${sev}`)
+        .join(", ");
+    const rows = [...findings].sort((a, b) => order(a.severity) - order(b.severity));
+    const sevW = Math.max(8, ...rows.map((r) => (r.severity || "none").length));
+    const clsW = Math.max(5, ...rows.map((r) => (r.classification || "unknown").length));
+    const lines = [
+        `${bold("Findings:", stream)} ${findings.length} — ${counts}`,
+        dim(`  ${"SEVERITY".padEnd(sevW)}  ${"CLASS".padEnd(clsW)}  ID`, stream)
+    ];
+    for (const r of rows) {
+        const sev = (r.severity || "none").padEnd(sevW);
+        const cls = (r.classification || "unknown").padEnd(clsW);
+        lines.push(`  ${sev}  ${cls}  ${truncate(r.id || "(unnamed)", 60)}`);
     }
+    return lines.join("\n");
 }

package/dist/version.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MIN_SUPPORTED_RUN_STATE_SCHEMA_VERSION = exports.LEGACY_RUN_STATE_SCHEMA_VERSION = exports.CURRENT_RUN_STATE_SCHEMA_VERSION = exports.WORKFLOW_APP_SCHEMA_VERSION = exports.CURRENT_COOL_WORKFLOW_VERSION = void 0;
-exports.CURRENT_COOL_WORKFLOW_VERSION = "0.1.89";
+exports.CURRENT_COOL_WORKFLOW_VERSION = "0.1.91";
 exports.WORKFLOW_APP_SCHEMA_VERSION = 1;
 exports.CURRENT_RUN_STATE_SCHEMA_VERSION = 1;
 exports.LEGACY_RUN_STATE_SCHEMA_VERSION = 0;

package/docs/agent-delegation-drive.7.md

@@ -198,28 +198,43 @@ string). Each verb is declared once in `capability-registry.ts`, so `cw <cmd>
 --json` is byte-identical to the matching `cw_<tool>` MCP tool for the read-only
 preview/config-show verbs.
 
-## Live output — opt-in stderr passthrough (Unix-clean)
-
-A drive can show the agent's activity live, without touching the evidence
-contract, when the operator opts in with `CW_AGENT_STREAM=1`:
-
-- **Default stays buffered.** Without `CW_AGENT_STREAM=1`, the bundled wrapper
-  keeps the buffered path and writes one JSON report to stdout after writing
-  `result.md`.
-- **The opt-in wrapper renders; stderr only.** With `CW_AGENT_STREAM=1`, the
-  bundled Claude wrapper runs claude in `--output-format stream-json`, and the
-  bundled Codex wrapper runs `codex exec --json --output-last-message`.
-  Each wrapper renders a short human trace (tool uses, assistant text, per-turn
-  summaries where present) to its **stderr** — diagnostics, never data. It builds
-  the single `{model, usage, result}` object for stdout after the final answer is
-  captured.
-- **Core forwards, never parses.** `runAgentProcess` passes the agent child's
-  stderr straight through to the operator's terminal (`stdio` inherit) only when
-  `CW_AGENT_STREAM=1`, CW's own stderr is a TTY, and `CW_NO_STREAM` is not set.
-  Piped / CI runs stay quiet (the Rule of Silence). Vendor-specific rendering
-  lives in the wrapper (policy), not the kernel (mechanism).
-- **Determinism intact.** The backend evidence triple hashes stdout only, so
-  the live stderr stream never changes recorded evidence or replay.
+## Live output — a calm live view, on stderr, Unix-clean
+
+A drive shows the agent's activity live without ever touching the evidence
+contract. The async per-vendor wrapper owns the live region (it parses
+`--output-format stream-json` and its event loop is free); cw renders the calm
+orchestration between agents plus the end-of-run summary. **Everything goes to
+stderr — stdout stays the byte-exact data channel** (the `cw:result` fence, the
+wrapper's `{model, usage, result}` JSON, cw's `--json` payload), so a pipe is
+never polluted.
+
+- **Interactive (TTY).** The wrapper renders ONE in-place status line: a Braille
+  spinner + the current action + elapsed (e.g. `⠹ Read app.js 1.2s`). Tool calls
+  fold to a single line each — spinning while running, then resolving to
+  `✓ Read app.js (0.3s)` / `✗ Bash (1.1s)` (dimmed, args width-truncated). The
+  cursor is hidden while the spinner runs and **ALWAYS restored** on exit /
+  Ctrl-C / SIGTERM (Ctrl-C exits non-zero, leaving a clean terminal).
+- **Non-TTY stays SILENT by default** (the Rule of Silence). `CW_AGENT_STREAM=1`
+  opts a CI/piped run into a **plain append-only** trace (`→ …` / `✓ … (Xs)`
+  lines, zero ANSI/cursor bytes) for debuggability — mirroring `CW_DRIVE_PROGRESS=1`.
+- **Verbosity.** Default is compact: the current action + folded tool lines, with
+  the model's narration/reasoning HIDDEN. `--verbose` (sets `CW_VERBOSE=1`)
+  surfaces the full narration inline; `--full` (sets `CW_OUTPUT=full`) implies
+  verbose AND prints the report inline at run end.
+- **Transcript always on disk.** Regardless of verbosity — even when the screen
+  view is silent or compact — the wrapper writes the COMPLETE narration + tool I/O
+  to `transcript.md` next to that worker's `result.md`. The end-of-run summary
+  prints the run dir where the transcripts live, so nothing is ever lost to a
+  compact view.
+- **Color control.** `NO_COLOR` / `CW_NO_COLOR` (the `--no-color` flag sets the
+  latter) disable ANSI; `FORCE_COLOR` forces it even when piped; otherwise color
+  follows isTTY. Honored identically by cw (`term.ts`) and every wrapper.
+- **End-of-run summary (cw side).** A COMPACT findings table — id / severity /
+  classification + counts, re-parsed from each completed worker's `cw:result` —
+  plus the report path, status, and run dir. NOT the full prose (that stays in
+  `report.md` + the transcript); `--full` also prints the report inline.
+- **Determinism intact.** The backend evidence triple hashes stdout only, so the
+  live stderr view never changes recorded evidence or replay.
 
 The built-in templates are:
 
@@ -317,3 +332,7 @@ Orchestration-parity for the agent drive: `run --drive --incremental` step-level
 ## 0.1.89 (v0.1.89)
 
 The one-command `cw -q` headline now routes the question and defaults the repo to the caller cwd before driving the agent; the delegation contract, drive, and accept path are unchanged.
+
+0.1.90
+
+0.1.91

package/docs/cli-mcp-parity.7.md

@@ -82,7 +82,7 @@ relationship. `identical` means `cw <cmd> --json` is equal to the `cw_<tool>`
 payload; `projected` means a declared divergence with a reason; `cli-only` marks
 a surface-specific capability with a recorded reason. The matrix is
 <!-- gen:parity:count -->
-machine-complete by design: 199 capabilities, 186 MCP tools.
+machine-complete by design: 201 capabilities, 188 MCP tools.
 <!-- /gen:parity:count -->
 
 <!-- gen:parity:table -->
@@ -272,6 +272,8 @@ machine-complete by design: 199 capabilities, 186 MCP tools.
 | `gc.plan` | `cw gc plan` | `cw_gc_plan` | `gcPlan` | both | identical |
 | `gc.run` | `cw gc run` | `cw_gc_run` | `gcRun` | both | projected |
 | `gc.verify` | `cw gc verify` | `cw_gc_verify` | `gcVerify` | both | identical |
+| `clones.list` | `cw clones list` | `cw_clones_list` | `listClones` | both | identical |
+| `clones.gc` | `cw clones gc` | `cw_clones_gc` | `gcClones` | both | projected |
 | `telemetry.verify` | `cw telemetry verify` | `cw_telemetry_verify` | `telemetryVerify` | both | identical |
 | `demo.tamper` | `cw demo tamper` | `—` | `demoTamper` | cli-only | cli-only |
 | `demo.bundle` | `cw demo bundle` | `—` | `demoBundle` | cli-only | cli-only |
@@ -319,12 +321,13 @@ carry a recorded reason in the registry.
 <!-- /gen:parity:cliOnly -->
 
 <!-- gen:parity:projected -->
-Five capabilities are payload-divergent on purpose (`projected`):
+Six capabilities are payload-divergent on purpose (`projected`):
 
 - `commit` — Both surfaces route through the single core entry runner.commit. The CLI emits the raw StateCommitResult for scripting (commit.id, commit.evidence, commit.gate, commit.acceptanceRationale); cw_commit emits the operator commit envelope (commitId, verifierGated, checkpoint, evidenceCount, snapshotPath, nextActions, plus the raw result under `commit`). Declared projection via capability-core.commitEnvelope, not drift.
 - `backend.agent.config.set` — Mutating: persists $CW_HOME/agent-config.json (secret-stripped) before returning the effective config; both surfaces perform the same write — it is a surface-mutating verb, not a read probe.
 - `run.drive.step` — Mutating: advances the run by spawning the external agent per worker and recording attested output — not a read probe. CLI (--drive/--step) and MCP route through the same drive() core.
 - `gc.run` — Mutating: frees disk and appends a tombstone; both surfaces perform the identical transaction but the payload reports now-derived bytesFreed/tombstone.
+- `clones.gc` — Mutating: removes cache directories and reports now-derived freedBytes/removed; both surfaces perform the identical reclamation.
 - `workbench.serve` — Both surfaces route through the single core entry buildWorkbenchServeDescriptor and return the IDENTICAL serve descriptor under `cw workbench serve --json`/`--once` and `cw_workbench_serve`. They diverge only in side effect, not payload: the CLI's default `cw workbench serve` (no --once) additionally STARTS the blocking localhost host (like `schedule daemon`), which an MCP stdio host cannot do, so cw_workbench_serve only ever returns the descriptor. Declared divergence, not drift.
 <!-- /gen:parity:projected -->
 
@@ -521,3 +524,7 @@ CLI surface simplified to 6 commands with agent stderr streaming on by default a
 ## 0.1.89 (v0.1.89)
 
 CLI golden-path fixes: `cw -q "…"` routes the question (was read as an app id → "Workflow app not found"), auto-detects the cwd as the repo (run anywhere, no `--repo`), and `cw help` wraps its command list with a trailing newline; the CLI↔MCP parity contract and the help-token parser are unchanged.
+
+0.1.90
+
+0.1.91

package/docs/contract-migration-tooling.7.md

@@ -157,3 +157,7 @@ _No behavioral change in v0.1.88 (no schema-migration edge was added; the increm
 ## 0.1.89 (v0.1.89)
 
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90
+
+0.1.91

package/docs/control-plane-scheduling.7.md

@@ -141,3 +141,7 @@ _No behavioral change in v0.1.88 (the `sched` priority/readiness selection, conc
 ## 0.1.89 (v0.1.89)
 
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90
+
+0.1.91

package/docs/durable-state-and-locking.7.md

@@ -140,3 +140,7 @@ _No behavioral change in v0.1.88 (atomic writes, fsync-durability for audit-esse
 ## 0.1.89 (v0.1.89)
 
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90
+
+0.1.91

package/docs/evidence-adoption-reasoning-chain.7.md

@@ -301,3 +301,7 @@ _No behavioral change in v0.1.88 (the evidence adoption reasoning chain and its
 ## 0.1.89 (v0.1.89)
 
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90
+
+0.1.91

package/docs/execution-backends.7.md

@@ -331,3 +331,7 @@ Agent stderr live-streaming is now on by default when stderr is a TTY (CW_AGENT_
 ## 0.1.89 (v0.1.89)
 
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90
+
+0.1.91

package/docs/multi-agent-cli-mcp-surface.7.md

@@ -299,3 +299,7 @@ The host-facing surface tracks the CLI simplification to 6 commands (streaming o
 ## 0.1.89 (v0.1.89)
 
 The host-facing surface tracks the CLI golden-path fixes (`cw -q` routing + repo auto-detect + clean help); the multi-agent verbs and their MCP-tool mirrors are unchanged.
+
+0.1.90
+
+0.1.91

package/docs/multi-agent-eval-replay-harness.7.md

@@ -333,3 +333,7 @@ _No change in behavior in v0.1.88 (no harness code changed; the new `loop-contro
 ## 0.1.89 (v0.1.89)
 
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90
+
+0.1.91

package/docs/multi-agent-operator-ux.7.md

@@ -345,3 +345,7 @@ _No behavioral change in v0.1.88 (no operator-view code changed; the new sub-wor
 ## 0.1.89 (v0.1.89)
 
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90
+
+0.1.91

package/docs/node-snapshot-diff-replay.7.md

@@ -166,3 +166,7 @@ A new `loop-control` StateNodeKind now flows through per-node snapshot/diff/repl
 ## 0.1.89 (v0.1.89)
 
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90
+
+0.1.91

package/docs/observability-cost-accounting.7.md

@@ -225,3 +225,7 @@ Attestation now signs the agent's RESULT, not just its usage: `TelemetryAttestat
 ## 0.1.89 (v0.1.89)
 
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90
+
+0.1.91

package/docs/project-index.md

@@ -5,11 +5,11 @@ Generated from the current repository code on 2026-06-21 by `npm run sync:projec
 ## Snapshot
 
 - Package: `cool-workflow`
-- Version: `0.1.89`
-- Source modules: `65`
+- Version: `0.1.91`
+- Source modules: `68`
 - Workflow apps: `7`
-- Docs: `52`
-- Smoke tests: `130`
+- Docs: `53`
+- Smoke tests: `137`
 - Repository: https://github.com/coo1white/cool-workflow
 
 ## Architecture
@@ -83,6 +83,7 @@ multi-agent host -> topology -> blackboard/coordinator
 - [agent-config.ts](../src/agent-config.ts)
 - [capability-core.ts](../src/capability-core.ts)
 - [capability-registry.ts](../src/capability-registry.ts)
+- [clones.ts](../src/clones.ts)
 - [collaboration.ts](../src/collaboration.ts)
 - [compare.ts](../src/compare.ts)
 - [contract-migration.ts](../src/contract-migration.ts)
@@ -102,6 +103,8 @@ multi-agent host -> topology -> blackboard/coordinator
 - [observability.ts](../src/observability.ts)
 - [onramp.ts](../src/onramp.ts)
 - [reclamation.ts](../src/reclamation.ts)
+- [remote-source.ts](../src/remote-source.ts)
+- [reporter.ts](../src/reporter.ts)
 - [result-normalize.ts](../src/result-normalize.ts)
 - [run-export.ts](../src/run-export.ts)
 - [run-registry.ts](../src/run-registry.ts)
@@ -166,6 +169,7 @@ multi-agent host -> topology -> blackboard/coordinator
 - [Release And Migration Discipline](release-and-migration.7.md)
 - [Cool Workflow Release History](release-history.md)
 - [Release Tooling](release-tooling.7.md)
+- [Remote-Source Review (`--link`)](remote-source-review.7.md)
 - [Verifiable Report Bundle](report-verifiable-bundle.7.md)
 - [Routines](routines.md)
 - [Run Registry / Control Plane](run-registry-control-plane.7.md)
@@ -203,9 +207,14 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [candidate-scoring-smoke.js](../test/candidate-scoring-smoke.js)
 - [canonical-workflow-apps-smoke.js](../test/canonical-workflow-apps-smoke.js)
 - [claude-p-agent-wrapper-smoke.js](../test/claude-p-agent-wrapper-smoke.js)
+- [cli-arg-parsing-smoke.js](../test/cli-arg-parsing-smoke.js)
 - [cli-command-surface-smoke.js](../test/cli-command-surface-smoke.js)
 - [cli-jsonmode-parity-smoke.js](../test/cli-jsonmode-parity-smoke.js)
 - [cli-mcp-parity-smoke.js](../test/cli-mcp-parity-smoke.js)
+- [cli-progress-summary-smoke.js](../test/cli-progress-summary-smoke.js)
+- [cli-recoverable-errors-smoke.js](../test/cli-recoverable-errors-smoke.js)
+- [cli-render-smoke.js](../test/cli-render-smoke.js)
+- [clones-gc-smoke.js](../test/clones-gc-smoke.js)
 - [codex-agent-wrapper-smoke.js](../test/codex-agent-wrapper-smoke.js)
 - [concurrency-default-smoke.js](../test/concurrency-default-smoke.js)
 - [concurrent-failure-semantics-smoke.js](../test/concurrent-failure-semantics-smoke.js)
@@ -272,6 +281,8 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [release-flow-smoke.js](../test/release-flow-smoke.js)
 - [release-gate-smoke.js](../test/release-gate-smoke.js)
 - [release-tooling-smoke.js](../test/release-tooling-smoke.js)
+- [remote-link-archive-smoke.js](../test/remote-link-archive-smoke.js)
+- [remote-link-git-smoke.js](../test/remote-link-git-smoke.js)
 - [report-bundle-smoke.js](../test/report-bundle-smoke.js)
 - [report-verify-bundle-smoke.js](../test/report-verify-bundle-smoke.js)
 - [result-normalize-smoke.js](../test/result-normalize-smoke.js)

package/docs/real-execution-backends.7.md

@@ -173,3 +173,7 @@ _No behavioral change in v0.1.88 (the container/remote/ci delegating integration
 ## 0.1.89 (v0.1.89)
 
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90
+
+0.1.91

package/docs/release-and-migration.7.md

@@ -313,3 +313,7 @@ _No behavioral change in v0.1.88 (`release:check` and the durable run-state comp
 ## 0.1.89 (v0.1.89)
 
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90
+
+0.1.91

package/docs/release-tooling.7.md

@@ -251,3 +251,7 @@ The release flow now captures the reviewer's verdict from agent stdout (`release
 ## 0.1.89 (v0.1.89)
 
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90
+
+0.1.91

package/docs/remote-source-review.7.md

@@ -0,0 +1,88 @@
+# Remote-Source Review (`--link`)
+
+CW v0.1.91 lets you point a review at **any repository on the internet** instead
+of only a local path: `cw -q "what are the risks?" --link <url>`. CW materializes
+the remote into a local checkout and runs the **existing** review pipeline against
+it — identical downstream to reviewing a folder. A URL passed to `-dir`/`--repo`
+is auto-detected, so `--link <url>` and `-dir <url>` are equivalent.
+
+```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
+cw -q "What are the risks?" --link https://github.com/owner/repo/archive/refs/heads/main.tar.gz
+cw -q "..." --link <url> --check     # validate the URL + tooling WITHOUT fetching
+```
+
+## Sources
+
+- **Git repositories**, any host: `https://`, `http://`, `ssh://`, `git://`, the
+  scp-style `git@host:owner/repo`, and `file://`. Cloned shallow (`--depth 1
+  --single-branch`); `--ref <branch|tag>` selects a ref. `commit` is the resolved
+  `HEAD` SHA.
+- **Downloadable archives**: `.tar.gz` / `.tgz` / `.tar` / `.zip` (e.g. a GitHub
+  "Download ZIP" / codeload tarball). Fetched, extracted, and `git init`-snapshotted
+  into a local repo so the git-tracked source-context reader works unchanged.
+  `commit` is the **sha256 of the downloaded bytes** (a content address — there is
+  no git SHA).
+
+## The red line — materialize source, do not internalize execution
+
+`--link` only materializes the **source** to review. CW still **DELEGATES** worker
+execution to the operator's configured agent backend (`claude -p`, `codex exec`, an
+HTTP endpoint) exactly as a local review does; it never executes a model itself.
+Cloning is non-deterministic network I/O, so it happens in the **capability layer**
+(before `plan`), never in the replay-deterministic orchestrator core — which only
+ever sees the resulting local path.
+
+## Provenance — where the code came from, tamper-evidently
+
+The sanitized origin rides through three surfaces:
+
+- `run.inputs` → a `- Source: <url>@<commit>` line in `report.md`.
+- the `--json` result's `remote { url, commit, kind, ref, cached }`.
+- a hash-chained `source.clone` / `source.download` **trust-audit event** that
+  `cw audit verify <run-id>` re-proves — editing the recorded origin is detectable.
+
+Credentials in a URL (`https://user:token@host/…`) are stripped before the URL is
+used as a cache key, printed, persisted, or recorded; the raw URL reaches only a
+single `git` argv element. Git/download diagnostics are credential-redacted before
+they are ever surfaced.
+
+## Fail closed
+
+A bad URL, a blocked scheme, a network failure, or a credential-less private repo
+produces an **explicit error and a non-zero exit** — never a fabricated review,
+never a hang on an auth prompt (`GIT_TERMINAL_PROMPT=0`). Hardening:
+
+- **Scheme allowlist** (https/http/ssh/git/file); `ext::`/`fd::` transport helpers
+  and `-`-leading option-injection are rejected; the URL is always a separate argv
+  element (never a shell string); repo hooks are disabled (`-c core.hooksPath=`).
+- **Archive extraction** validates the entry listing for `..`/absolute traversal
+  BEFORE extracting, **rejects symlink/non-regular entries** (walked with `lstat`),
+  and bounds the decompression bomb by **declared** uncompressed size (gzip ISIZE /
+  `unzip -l`) before extracting and **actual** size (1 GiB) after.
+- **SSRF**: http(s) redirects are followed manually and each hop is re-validated
+  (http(s) scheme + no private/loopback/link-local host) before connecting — a
+  public URL cannot redirect CW into an internal service.
+
+## Cache — `cw clones`
+
+Checkouts are cached, content-addressed, under
+`~/.local/state/cool-workflow/clones/<hash>/` (honoring `CW_HOME`/`XDG_STATE_HOME`)
+and reused on the next question; `--refresh` re-fetches. Manage the cache:
+
+```bash
+cw clones list                          # origin url, kind, commit, age, bytes
+cw clones gc --older-than-days 30       # reclaim checkouts older than N days
+cw clones gc --all                      # reclaim everything
+```
+
+`cw clones gc` deletes only paths it has proven are inside the clones cache (fail
+closed). Both verbs have MCP peers (`cw_clones_list`, `cw_clones_gc`) with
+byte-identical payloads.
+
+## Determinism note
+
+The cache is keyed on the URL (+ref), not on content: if a URL's content changes
+upstream, the cached checkout is reused until `--refresh` (mirroring how a git
+clone pins its resolved `HEAD`). Use `--refresh` to re-fetch the latest.

package/docs/run-registry-control-plane.7.md

@@ -434,3 +434,7 @@ Security: archive import now refuses path-traversal run ids (`..`/absolute/separ
 ## 0.1.89 (v0.1.89)
 
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90
+
+0.1.91

package/docs/run-retention-reclamation.7.md

@@ -224,3 +224,7 @@ _No behavioral change in v0.1.88 (the tiered, append-only, cryptographically-ver
 ## 0.1.89 (v0.1.89)
 
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90
+
+0.1.91

package/docs/state-explosion-management.7.md

@@ -302,3 +302,7 @@ _No behavioral change in v0.1.88 (the summarization/compaction layer and its fai
 ## 0.1.89 (v0.1.89)
 
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90
+
+0.1.91

package/docs/team-collaboration.7.md

@@ -238,3 +238,7 @@ _No behavioral change in v0.1.88 (the host-attested actor, append-only approvals
 ## 0.1.89 (v0.1.89)
 
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90
+
+0.1.91

package/docs/web-desktop-workbench.7.md

@@ -246,3 +246,7 @@ _No behavioral change in v0.1.88 (the five operator surfaces and the registry cr
 ## 0.1.89 (v0.1.89)
 
 _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes only; this subsystem is unchanged)._
+
+0.1.90
+
+0.1.91

package/manifest/plugin.manifest.json

@@ -2,7 +2,7 @@
   "_comment": "SINGLE SOURCE OF TRUTH for every vendor manifest. Edit THIS file, then run `npm run gen:manifests`. Do NOT hand-edit the generated vendor manifests (.claude-plugin/, .codex-plugin/, .agents/, .mcp.json) — `npm run gen:manifests -- --check` (run by release:check) will fail if they drift from this source.",
   "identity": {
     "name": "cool-workflow",
-    "version": "0.1.89",
+    "version": "0.1.91",
     "license": "BSD-2-Clause",
     "homepage": "https://github.com/coo1white/cool-workflow",
     "author": {

package/manifest/source-context-profiles.json

@@ -25,7 +25,7 @@
     },
     "runtime": {
       "description": "Runtime-kernel source context for state, orchestration, scheduling, execution, and shared types.",
-      "maxLines": 44000,
+      "maxLines": 48000,
       "include": [
         "plugins/cool-workflow/src/**",
         "plugins/cool-workflow/package.json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cool-workflow",
-  "version": "0.1.89",
+  "version": "0.1.91",
   "bin": {
     "cool-workflow": "scripts/cw.js",
     "cw": "scripts/cw.js"