cool-workflow 0.1.88 → 0.1.90

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.88",
+  "version": "0.1.90",
   "author": {
     "name": "COOLWHITE LLC"
   },

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cool-workflow",
-  "version": "0.1.88",
+  "version": "0.1.90",
   "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

@@ -53,7 +53,44 @@ cw -q "What are the security risks?" -codex
 cw -q "What are the security risks?" -deepseek
 ```
 
-You will see live streaming output as the agent works — no env vars needed.
+Review a project **from any directory** — no `cd` needed — by pointing at its folder:
+
+```bash
+cw -q "What are the risks?" -dir /path/to/project   # -d / --dir / --repo are equivalent
+```
+
+Or review a **remote repo by URL** — CW clones it for you, then reviews the checkout
+(`-l` / `--link`, or just pass the URL to `-dir`/`--repo`):
+
+```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
+```
+
+Works with GitHub, GitLab, Bitbucket, self-hosted git, `ssh://`, and `file://` — **and with
+downloadable archives** (`.tar.gz`/`.tgz`/`.tar`/`.zip`, e.g. a GitHub "Download ZIP" link),
+which are fetched, extracted, and snapshotted into a local repo before review. The clone is
+cached under `~/.local/state/cool-workflow/clones/` and reused on the next question (`--refresh`
+re-fetches; manage with `cw clones list` / `cw clones gc`). The report records the exact origin —
+`Source: <url>@<commit>` — and a tamper-evident `source.clone` event you can re-prove with
+`cw audit verify`. A private repo with no credentials **fails closed** (it never hangs on a
+prompt). Validate without fetching: `cw -q "…" --link <url> --check`.
+
+As it runs you see CW's own phases tick by, then a clean summary — no env vars needed:
+
+```text
+==> Map ✓ (6/6)
+==> Assess ✓ (6/6)
+==> Verdict ✓
+
+✓ Report: /path/to/project/.cw/runs/<run-id>/report.md
+  ✓ Status: complete — 14/14
+  Next: cw report <run-id> --show
+```
+
+If something is off, the error hands you the next move — e.g. `Try: cw doctor` when no
+agent is configured. Pipe-clean: with `--json`, stdout is pure data and all of this chrome
+goes to stderr (TTY only).
 
 ### 3. Open the report
 
@@ -462,6 +499,10 @@ Verification and synthesis tasks need a structured result block:
 ```
 ````
 
+## 0.1.89 (v0.1.89)
+
+Headline golden-path fixes: `cw -q "question"` asks the question (was read as an app id), auto-detects the cwd as the repo (run anywhere, no `--repo`/`cd`), and `cw help` renders a clean wrapped command list with a trailing newline; plus a vendor-agnostic UI/UX prevention gate (a headline-command smoke + a real `npm install -g` run-from-anywhere smoke) so a CLI-surface regression can't ship invisibly again.
+
 ## 0.1.88 (v0.1.88)
 
 Orchestration-parity for the agent drive — inline `subWorkflow()` nesting, bounded dynamic `loop()` phases (a `predicate` or a `budget-target` token `until`), and `cw run --drive --incremental` step-level resume; the agent now signs its findings (result-bound ed25519) and `cw report verify-bundle --require-signatures` proves offline that every signed finding is in the report unaltered; CLI simplified to 6 commands with agent streaming on by default; path-traversal run ids refused on archive import.
@@ -469,3 +510,5 @@ Orchestration-parity for the agent drive — inline `subWorkflow()` nesting, bou
 ## 0.1.87 (v0.1.87)
 
 npm test parallel, 4-vendor wrappers (Claude/Codex/Gemini/OpenCode), Homebrew-style CLI UX (colors/did-you-mean/categorized help/error tips/cw info/cw search/cw man/doctor --fix), post-success summaries, agent execution timing
+
+v0.1.90

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.88",
+  "version": "0.1.90",
   "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.88",
+  "version": "0.1.90",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

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.88",
+  "version": "0.1.90",
   "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.88",
+  "version": "0.1.90",
   "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.88",
+  "version": "0.1.90",
   "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.88",
+  "version": "0.1.90",
   "author": "COOLWHITE LLC",
   "inputs": [
     {

package/dist/capability-core.js

@@ -21,7 +21,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.QUICKSTART_DEFAULT_APP = void 0;
+exports.gcClones = exports.listClones = exports.QUICKSTART_DEFAULT_APP = void 0;
 exports.planSummary = planSummary;
 exports.appRun = appRun;
 exports.sandboxChoose = sandboxChoose;
@@ -79,6 +79,7 @@ const observability_1 = require("./observability");
 const telemetry_ledger_1 = require("./telemetry-ledger");
 const telemetry_attestation_1 = require("./telemetry-attestation");
 const trust_audit_1 = require("./trust-audit");
+const remote_source_1 = require("./remote-source");
 const telemetry_demo_1 = require("./telemetry-demo");
 const state_1 = require("./state");
 const run_export_1 = require("./run-export");
@@ -497,7 +498,13 @@ const DRIVE_RUNTIME_KEYS = [
     "agentTimeoutMs",
     "agent-timeout-ms",
     "resume",
-    "incremental"
+    "incremental",
+    // Remote-source flags (v0.1.91): materialized into a local checkout in the capability
+    // layer, never passed to plan as inputs (the resolved sourceUrl/sourceCommit ARE inputs).
+    "link",
+    "ref",
+    "branch",
+    "refresh"
 ];
 function planInputsFor(args) {
     const copy = withoutRuntimeKeys(args);
@@ -548,9 +555,41 @@ exports.QUICKSTART_DEFAULT_APP = "architecture-review";
  *  the drive fails closed (status=blocked) and we never fabricate a completion. */
 function quickstart(runner, args) {
     const appId = String(args.appId || args.app || args.workflowId || exports.QUICKSTART_DEFAULT_APP);
+    // Remote source (v0.1.91): a `--link <url>` — or a URL passed to `--repo`/`-dir` — is
+    // materialized to a LOCAL checkout in the capability layer (below). Cloning is
+    // non-deterministic network I/O and must never enter the replay-deterministic core, so we
+    // rewrite `args.repo` to the local path here; everything downstream is a normal local run.
+    const linkArg = optionalString(args.link);
+    const repoArgRaw = optionalString(args.repo);
+    const remoteCandidate = linkArg || (repoArgRaw && (0, remote_source_1.isRemoteUrl)(repoArgRaw) ? repoArgRaw : undefined);
+    // Run anywhere (like brew): default the repo-under-review to the caller's cwd when no
+    // --repo/--cwd/--link is given. A remote candidate is materialized below, so it must NOT
+    // fall through to the cwd default here.
+    if (!remoteCandidate && !optionalString(args.repo) && !optionalString(args.cwd)) {
+        args.repo = invocationCwd(args);
+    }
     const agentConfigured = Boolean((0, agent_config_1.resolveAgentConfig)(args).command || (0, agent_config_1.resolveAgentConfig)(args).endpoint);
-    if (isTrue(args.check))
-        return quickstartCheck(runner, appId, args, agentConfigured);
+    if (isTrue(args.check)) {
+        return remoteCandidate
+            ? remoteQuickstartCheck(runner, appId, args, agentConfigured, remoteCandidate)
+            : quickstartCheck(runner, appId, args, agentConfigured);
+    }
+    // Materialize the remote NOW — after `--check` (which never fetches) and before any
+    // plan/preview/drive — so the orchestrator only ever sees the local checkout. Fails closed:
+    // a bad URL / blocked scheme / network / auth failure throws here, before any run is planned.
+    let remoteSource;
+    if (remoteCandidate) {
+        remoteSource = (0, remote_source_1.materializeRemote)(remoteCandidate, {
+            ref: optionalString(args.ref || args.branch),
+            refresh: isTrue(args.refresh)
+        });
+        args.repo = remoteSource.localPath;
+        // Record the origin as plan INPUTS so it rides into run.inputs → the report header.
+        args.sourceUrl = remoteSource.url;
+        args.sourceCommit = remoteSource.commit;
+        if (remoteSource.ref)
+            args.sourceRef = remoteSource.ref;
+    }
     // `--resume`: a discoverability flag over the existing continuation. With no
     // `--run`, advance exactly ONE step (reuse the `--once` path) and print a
     // copy-pasteable continue line; with `--run <id>`, continue that run to
@@ -589,6 +628,25 @@ function quickstart(runner, args) {
     const runRepoCwd = node_path_1.default.resolve(node_path_1.default.dirname(result.statePath), "..", "..", "..");
     const reportTarget = node_fs_1.default.existsSync(runRepoCwd) ? runRepoCwd : undefined;
     const reportPath = runner.withBaseDir(reportTarget).report(result.runId).path;
+    // Tamper-evident provenance: bind the remote origin (url@sha) into the run's hash-chained
+    // trust-audit log so `cw audit verify` re-proves where the code came from. metadata is
+    // auto-scrubbed of credentials by recordTrustAuditEvent → scrubMetadata. Best-effort: the
+    // origin is already in run.inputs/report/the result, so a recording hiccup never fails the
+    // review (additive trust evidence, not a gate).
+    if (remoteSource) {
+        try {
+            const provRun = runner.withBaseDir(reportTarget).loadRun(result.runId);
+            (0, trust_audit_1.recordTrustAuditEvent)(provRun, {
+                kind: remoteSource.kind === "archive" ? "source.download" : "source.clone",
+                decision: "recorded",
+                source: "operator-recorded",
+                metadata: { url: remoteSource.url, commit: remoteSource.commit, ref: remoteSource.ref || null, kind: remoteSource.kind, depth: 1 }
+            });
+        }
+        catch {
+            /* provenance is additive; never fail a completed review over an audit-log hiccup */
+        }
+    }
     // --bundle: after a COMPLETE drive, seal the run into a portable, self-verified
     // bundle so the one command yields a client-verifiable artifact. Pure composition
     // of reportBundle() (export sealed + offline self-verify); spawns nothing. Gated on
@@ -658,7 +716,12 @@ function quickstart(runner, args) {
         ...(resumeRunId ? { resumedFrom: resumeRunId } : {}),
         // Same conditional-spread discipline: `bundle` is present only when --bundle ran
         // on a completed drive, so the default (no --bundle) payload is byte-identical.
-        ...(bundle ? { bundle } : {})
+        ...(bundle ? { bundle } : {}),
+        // `remote` is present only when the review targeted a --link/URL source, so a local-repo
+        // run stays byte-identical. Carries the sanitized origin + resolved commit for provenance.
+        ...(remoteSource
+            ? { remote: { url: remoteSource.url, commit: remoteSource.commit, kind: remoteSource.kind, cached: remoteSource.cached, ...(remoteSource.ref ? { ref: remoteSource.ref } : {}) } }
+            : {})
     };
 }
 function quickstartCheck(runner, appId, args, agentConfigured) {
@@ -765,6 +828,55 @@ function quickstartCheck(runner, appId, args, agentConfigured) {
         nextCommand: quickstartNextCommand(appId, repo, args)
     };
 }
+/** Preflight for a `--link`/URL review: validate the URL SHAPE + tooling WITHOUT fetching
+ *  (a clone is heavy and side-effecting; --check stays read-only). Mirrors quickstartCheck's
+ *  app/question/agent sub-checks but swaps the local-repo readability checks for link+tooling.
+ *  `repo` carries the sanitized URL so the result reports what would be reviewed. */
+function remoteQuickstartCheck(runner, appId, args, agentConfigured, candidate) {
+    const validation = (0, remote_source_1.validateRemoteUrl)(candidate);
+    const checks = [];
+    try {
+        runner.showApp(appId);
+        checks.push({ name: "app", status: "ok", detail: `Workflow app ${appId} is available.` });
+    }
+    catch (error) {
+        checks.push({ name: "app", status: "blocked", detail: `Workflow app ${appId} is not available.`, fix: "Run `cw app list` and choose one of the listed app ids." });
+    }
+    if (validation.ok) {
+        checks.push({ name: "link", status: "ok", detail: `Remote source is a valid ${validation.kind} URL (${validation.url}).` });
+    }
+    else {
+        checks.push({ name: "link", status: "blocked", detail: `Remote source is not usable: ${validation.reason}.`, fix: "Pass a git URL (https/ssh/git/file or git@host:repo)." });
+    }
+    if ((0, remote_source_1.gitAvailable)()) {
+        checks.push({ name: "tooling", status: "ok", detail: "git is available to clone the remote." });
+    }
+    else {
+        checks.push({ name: "tooling", status: "blocked", detail: "git was not found on PATH.", fix: "Install git, then re-run." });
+    }
+    if (optionalString(args.question)) {
+        checks.push({ name: "question", status: "ok", detail: "Question is set." });
+    }
+    else {
+        checks.push({ name: "question", status: "blocked", detail: "Question is missing.", fix: "Pass --question TEXT." });
+    }
+    if (agentConfigured) {
+        checks.push({ name: "agent", status: "ok", detail: "Agent backend is configured." });
+    }
+    else {
+        checks.push({ name: "agent", status: "blocked", detail: "No agent backend is configured.", fix: "Pass --agent-command \"claude -p\", set $CW_AGENT_COMMAND, or use --agent-command builtin:claude." });
+    }
+    const ok = checks.every((check) => check.status !== "blocked");
+    return {
+        schemaVersion: 1,
+        mode: "check",
+        ok,
+        appId,
+        repo: validation.url,
+        checks,
+        nextCommand: `cw quickstart ${shellWord(appId)} --link ${shellWord(validation.url)}${optionalString(args.question) ? ` --question ${shellWord(String(args.question))}` : ""}`
+    };
+}
 function quickstartNextCommand(appId, repo, args) {
     const parts = ["cw", "quickstart", shellWord(appId), "--repo", shellWord(repo)];
     const question = optionalString(args.question);
@@ -838,6 +950,12 @@ function gcRun(reg, runId, args) {
 function gcVerify(reg, runId, args) {
     return reg.gcVerify(runId, { scope: scopeOf(args, "home") });
 }
+// Remote-source clone cache (v0.1.91): list/reclaim the `~/.local/state/cool-workflow/clones`
+// checkouts that `--link`/URL reviews populate. Pure filesystem work; both CLI and MCP route
+// here so `cw clones …` and `cw_clones_…` are byte-identical.
+var clones_1 = require("./clones");
+Object.defineProperty(exports, "listClones", { enumerable: true, get: function () { return clones_1.listClones; } });
+Object.defineProperty(exports, "gcClones", { enumerable: true, get: function () { return clones_1.gcClones; } });
 function runHistory(reg, args) {
     return reg.history({
         scope: scopeOf(args, "home"),

package/dist/capability-registry.js

@@ -427,6 +427,8 @@ const BUILTIN_CAPABILITIES = [
     { capability: "gc.plan", summary: "Dry-run plan of run reclamation (per-kind bytes + capability downgrade); frees nothing.", entry: "gcPlan", surface: "both", cli: { path: ["gc", "plan"], caseTokens: ["gc", "plan"], jsonMode: "flag" }, mcp: { tool: "cw_gc_plan" } },
     { capability: "gc.run", summary: "Execute the write-ahead reclamation transaction (skeleton -> tombstone -> fsync -> free).", entry: "gcRun", surface: "both", cli: { path: ["gc", "run"], caseTokens: ["gc", "run"], jsonMode: "flag" }, mcp: { tool: "cw_gc_run" }, payloadIdentical: false, reason: "Mutating: frees disk and appends a tombstone; both surfaces perform the identical transaction but the payload reports now-derived bytesFreed/tombstone." },
     { capability: "gc.verify", summary: "Re-prove a reclaimed run: skeleton-complete, tombstone chain untampered, artifacts reconstructable.", entry: "gcVerify", surface: "both", cli: { path: ["gc", "verify"], caseTokens: ["gc", "verify"], jsonMode: "flag" }, mcp: { tool: "cw_gc_verify", requiredArgs: ["runId"] } },
+    { capability: "clones.list", summary: "List the cached remote-source checkouts that --link/URL reviews populate (origin URL, kind, commit, age, bytes). Read-only.", entry: "listClones", surface: "both", cli: { path: ["clones", "list"], caseTokens: ["clones", "list"], jsonMode: "flag" }, mcp: { tool: "cw_clones_list" } },
+    { capability: "clones.gc", summary: "Reclaim cached remote-source checkouts: a TTL sweep (--older-than-days, default 30) or --all. Deletes only inside the clones cache.", entry: "gcClones", surface: "both", cli: { path: ["clones", "gc"], caseTokens: ["clones", "gc"], jsonMode: "flag" }, mcp: { tool: "cw_clones_gc" }, payloadIdentical: false, reason: "Mutating: removes cache directories and reports now-derived freedBytes/removed; both surfaces perform the identical reclamation." },
     { capability: "telemetry.verify", summary: "Re-prove a run's telemetry attestation ledger offline: chain linkage + independent hash recompute, and (with --pubkey / CW_AGENT_ATTEST_PUBKEY) re-verify each attested hop's ed25519 signature against the public key.", entry: "telemetryVerify", surface: "both", cli: { path: ["telemetry", "verify"], caseTokens: ["telemetry"], jsonMode: "flag" }, mcp: { tool: "cw_telemetry_verify", requiredArgs: ["runId"] } },
     { capability: "demo.tamper", summary: "Prove tamper-evidence: build a signed telemetry ledger, forge it, watch verification fail offline.", entry: "demoTamper", surface: "cli-only", cli: { path: ["demo", "tamper"], caseTokens: ["demo", "tamper"], jsonMode: "flag" }, reason: "Human-facing demonstration (operator/newcomer onboarding); the underlying integrity check is exposed programmatically as the both-surface telemetry.verify. No agent or MCP client needs to invoke a demo." },
     { capability: "demo.bundle", summary: "Prove portable-bundle verification: export a sealed report bundle, forge it two ways, watch report verify-bundle catch both offline with only the embedded public key.", entry: "demoBundle", surface: "cli-only", cli: { path: ["demo", "bundle"], caseTokens: ["demo", "bundle"], jsonMode: "flag" }, reason: "Human-facing demonstration (operator/newcomer onboarding); the underlying integrity check is exposed programmatically as the both-surface report.verify-bundle. No agent or MCP client needs to invoke a demo." },
@@ -560,6 +562,10 @@ const PAYLOAD_PROBE_DEFERRED_GROUPS = [
             "init",
             "dispatch",
             "result",
+            // clones.list is payload-identical by construction (both surfaces call listClones), but it
+            // reads the external filesystem clone cache (absolute paths + per-entry bytes/timestamps),
+            // so it is not byte-probed by the deterministic bootstrap.
+            "clones.list",
             "app.init",
             "app.run",
             "migration.list",

package/dist/cli/command-surface.js

@@ -69,7 +69,7 @@ async function runCli(argv = process.argv.slice(2)) {
             return;
         }
         if (!args.command || args.command === "--help" || args.command === "-h" || args.options.h || args.options.help) {
-            process.stdout.write((0, orchestrator_1.formatHelp)());
+            process.stdout.write((0, orchestrator_1.formatHelp)() + "\n");
             return;
         }
     }
@@ -80,10 +80,16 @@ async function runCli(argv = process.argv.slice(2)) {
         args.options["agent-command"] = "builtin:codex";
     if (args.options.deepseek)
         args.options["agent-command"] = "builtin:deepseek";
+    // -dir / --dir / -d : an intuitive alias for --repo — the project folder to review,
+    // so `cw -q "…" -dir /path` works from any directory (no cd). Explicit --repo wins.
+    if (!args.options.repo && args.options.dir)
+        args.options.repo = args.options.dir;
     // Bare -q / --question -> redirect to quickstart (auto-detect repo/agent/app).
+    // CONSUME the positional (shift) so the question never survives as positionals[0]
+    // — otherwise the quickstart handler reads it as the app id ("Workflow app not found").
     if (args.command === "-q" || args.command === "--question") {
         if (!args.options.question && args.positionals[0])
-            args.options.question = args.positionals[0];
+            args.options.question = args.positionals.shift();
         args.command = "quickstart";
     }
     else if (!args.command && typeof args.options.question === "string") {
@@ -97,7 +103,7 @@ async function runCli(argv = process.argv.slice(2)) {
     switch (args.command) {
         case "help":
         case undefined:
-            process.stdout.write((0, orchestrator_1.formatHelp)());
+            process.stdout.write((0, orchestrator_1.formatHelp)() + "\n");
             return;
         case "version":
             process.stdout.write(`${version_1.CURRENT_COOL_WORKFLOW_VERSION}\n`);
@@ -234,12 +240,18 @@ async function runCli(argv = process.argv.slice(2)) {
             const qs = (0, capability_core_1.quickstart)(runner, { ...args.options, ...(appId ? { appId } : {}), ...(runId ? { runId } : {}) });
             printJson(qs);
             const qr = qs;
-            if (typeof qr.runId === "string" && typeof qr.reportPath === "string") {
+            // Clean human summary on stderr (TTY-gated). Suppressed under --json so machine
+            // mode emits ONLY the stdout payload — no stderr chrome to parse around. The
+            // type guard also skips --check/--preview results (no reportPath of their own).
+            if (!wantsJson(args.options) && typeof qr.runId === "string" && typeof qr.reportPath === "string") {
                 (0, term_1.printSuccessSummary)({
                     runId: qr.runId,
                     reportPath: qr.reportPath,
                     status: String(qr.status || ""),
-                    bundle: Boolean(args.options.bundle)
+                    bundle: Boolean(args.options.bundle),
+                    completedWorkers: typeof qr.completedWorkers === "number" ? qr.completedWorkers : undefined,
+                    plannedWorkers: typeof qr.plannedWorkers === "number" ? qr.plannedWorkers : undefined,
+                    agentConfigured: typeof qr.agentConfigured === "boolean" ? qr.agentConfigured : undefined
                 });
             }
             if (qs.mode === "check" && qs.ok === false) {
@@ -1205,7 +1217,16 @@ async function runCli(argv = process.argv.slice(2)) {
                     driveArgs.appId = target;
                 const dr = (0, capability_core_1.runDrive)(runner, driveArgs);
                 printJson(dr);
-                (0, term_1.printSuccessSummary)({ runId: dr.runId, reportPath: dr.reportPath, status: dr.status });
+                if (!wantsJson(args.options)) {
+                    (0, term_1.printSuccessSummary)({
+                        runId: dr.runId,
+                        reportPath: dr.reportPath,
+                        status: dr.status,
+                        completedWorkers: dr.completedWorkers,
+                        plannedWorkers: dr.plannedWorkers,
+                        agentConfigured: dr.agentConfigured
+                    });
+                }
                 return;
             }
             const registry = (0, capability_core_1.runRegistryFor)(args.options, runner);
@@ -1219,7 +1240,16 @@ async function runCli(argv = process.argv.slice(2)) {
                             driveArgs.runId = id;
                         const dr = (0, capability_core_1.runDrive)(runner, driveArgs);
                         printJson(dr);
-                        (0, term_1.printSuccessSummary)({ runId: dr.runId, reportPath: dr.reportPath, status: dr.status });
+                        if (!wantsJson(args.options)) {
+                            (0, term_1.printSuccessSummary)({
+                                runId: dr.runId,
+                                reportPath: dr.reportPath,
+                                status: dr.status,
+                                completedWorkers: dr.completedWorkers,
+                                plannedWorkers: dr.plannedWorkers,
+                                agentConfigured: dr.agentConfigured
+                            });
+                        }
                         return;
                     }
                     printJson((0, capability_core_1.runDrivePreview)(runner, { ...args.options, runId: required(id, "run id") }));
@@ -1352,6 +1382,32 @@ async function runCli(argv = process.argv.slice(2)) {
                     throw new Error("Usage: cw.js sched plan|lease|release|complete|reclaim|reset|policy [show|set] [id] [--maxConcurrent N --maxAttempts N ...]");
             }
         }
+        case "clones": {
+            // Remote-source clone cache (v0.1.91): `list` inspects the ~/.local/state/cool-workflow
+            // /clones checkouts that `--link`/URL reviews populate; `gc` reclaims them (a TTL sweep,
+            // or --all). Pure filesystem work — no network, no run registry.
+            const [subcommand] = args.positionals;
+            switch (subcommand) {
+                case "list": {
+                    const result = (0, capability_core_1.listClones)(args.options);
+                    if (wantsJson(args.options))
+                        printJson(result);
+                    else
+                        process.stdout.write(`${formatClonesList(result)}\n`);
+                    return;
+                }
+                case "gc": {
+                    const result = (0, capability_core_1.gcClones)(args.options);
+                    if (wantsJson(args.options))
+                        printJson(result);
+                    else
+                        process.stdout.write(`${formatClonesGc(result)}\n`);
+                    return;
+                }
+                default:
+                    throw new Error("Usage: cw.js clones list [--json] | clones gc [--older-than-days N] [--all] [--json]");
+            }
+        }
         case "gc": {
             // Run Retention & Provable Reclamation (v0.1.39). `plan` is a pure dry-run
             // (frees nothing); `run` executes the write-ahead reclamation transaction;
@@ -1503,6 +1559,42 @@ function optionalArg(value) {
 function printJson(value) {
     process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
+function humanBytes(n) {
+    if (n < 1024)
+        return `${n}B`;
+    const units = ["KiB", "MiB", "GiB"];
+    let v = n / 1024;
+    let i = 0;
+    while (v >= 1024 && i < units.length - 1) {
+        v /= 1024;
+        i += 1;
+    }
+    return `${v.toFixed(1)}${units[i]}`;
+}
+function formatClonesList(result) {
+    if (result.count === 0)
+        return `No cached remote checkouts in ${result.clonesDir}.`;
+    const rows = result.entries.map((e) => {
+        const when = e.fetchedAt ? e.fetchedAt.replace("T", " ").replace(/\..*$/, "Z") : "unknown";
+        return `  ${e.kind.padEnd(7)} ${humanBytes(e.bytes).padStart(8)}  ${when}  ${e.url}${e.ref ? `@${e.ref}` : ""}`;
+    });
+    return [
+        `${result.count} cached checkout${result.count === 1 ? "" : "s"} — ${humanBytes(result.totalBytes)} in ${result.clonesDir}`,
+        "  KIND       SIZE  FETCHED               SOURCE",
+        ...rows,
+        `\nReclaim with: cw clones gc --older-than-days 30   (or --all)`
+    ].join("\n");
+}
+function formatClonesGc(result) {
+    const scope = result.all ? "all entries" : `entries older than ${result.olderThanDays} day(s)`;
+    if (result.removed.length === 0)
+        return `Nothing to reclaim (${scope}); ${result.keptCount} kept in ${result.clonesDir}.`;
+    const rows = result.removed.map((r) => `  ${humanBytes(r.bytes).padStart(8)}  ${r.url}`);
+    return [
+        `Reclaimed ${result.removed.length} checkout${result.removed.length === 1 ? "" : "s"} (${scope}) — freed ${humanBytes(result.freedBytes)}; ${result.keptCount} kept`,
+        ...rows
+    ].join("\n");
+}
 function wantsJson(options) {
     return Boolean(options.json || options.format === "json");
 }

package/dist/cli.js

@@ -1,10 +1,36 @@
 #!/usr/bin/env node
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.recoveryHint = recoveryHint;
 const command_surface_1 = require("./cli/command-surface");
 const term_1 = require("./term");
 (0, command_surface_1.runCli)(process.argv.slice(2)).catch((error) => {
     const message = error instanceof Error ? error.message : String(error);
-    process.stderr.write(`${(0, term_1.bold)("cw:")} ${(0, term_1.red)(message)}\n`);
+    const err = process.stderr;
+    // Errors go to stderr → color must key off stderr (not the term default).
+    err.write(`${(0, term_1.bold)("cw:", err)} ${(0, term_1.red)(message, err)}\n`);
+    // Brew-style recovery: a failed command should suggest a concrete next move. The hint
+    // is TTY-gated (tryHint dims only on a TTY) and goes to stderr, so piped stdout stays
+    // clean. It points at CW's OWN diagnose/discovery verbs (vendor-neutral) — never a model.
+    const hint = recoveryHint(message);
+    if (hint)
+        err.write(`  ${(0, term_1.tryHint)(hint, err)}\n`);
     process.exitCode = 1;
 });
+/** Map a top-level error message to ONE copy-pasteable recovery command (brew's `Try:`).
+ *  Content-based so it stays correct for any vendor; returns undefined rather than a
+ *  wrong guess when nothing matches (no hint beats a misleading one). */
+function recoveryHint(message) {
+    const m = message.toLowerCase();
+    if (m.startsWith("unknown command"))
+        return "cw help";
+    if (m.includes("not configured") || m.includes("agent backend"))
+        return "cw doctor";
+    if (m.includes("missing") && m.includes("repo"))
+        return 'cw -q "<question>" -dir <project-folder>';
+    if (m.includes("app") && (m.includes("not found") || m.includes("not available")))
+        return "cw app list";
+    if (m.includes("run id") || m.includes("run not found"))
+        return "cw run list";
+    return undefined;
+}