cool-workflow 0.1.92 → 0.1.93

package/docs/mcp-app-surface.7.md

@@ -232,4 +232,16 @@ The CLI is still the easiest way for people to drive a run. MCP is the steady
 tool surface for agent hosts. New runtime powers should come up in both
 surfaces, keep old names as aliases or wrappers, and use clear JSON
 contracts in place of host-specific policy hidden in the bridge.
+
+## Implementation
+
+The app-management surface (`listWorkflows`, `listApps`, `showApp`,
+`validateApp`, `initApp`, `packageApp`) lives on the `CoolWorkflowRunner`
+facade as thin delegators with no logic of their own. Their bodies sit in
+`src/orchestrator/app-operations.ts` as pure functions — the same v0.1.40
+router pattern used by the other `src/orchestrator/*-operations.ts` modules.
+The runner-owned calls (`resolveFromBase`, `validateApp`) are passed in as
+callbacks so the moved bodies stay byte-for-byte the same. The public method
+names, signatures, and return types do not change, so the CLI/MCP parity gate
+stays green.
 0.1.51

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

@@ -304,4 +304,4 @@ The host-facing surface tracks the CLI golden-path fixes (`cw -q` routing + repo
 
 0.1.91
 
-0.1.92
+0.1.93

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

@@ -338,4 +338,4 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 
 0.1.91
 
-0.1.92
+0.1.93

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

@@ -350,4 +350,4 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 
 0.1.91
 
-0.1.92
+0.1.93

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

@@ -171,4 +171,4 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 
 0.1.91
 
-0.1.92
+0.1.93

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

@@ -230,4 +230,4 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 
 0.1.91
 
-0.1.92
+0.1.93

package/docs/project-index.md

@@ -1,15 +1,15 @@
 # Cool Workflow Project Index
 
-Generated from the current repository code on 2026-06-21 by `npm run sync:project-index`.
+Generated from the current repository code on 2026-06-25 by `npm run sync:project-index`.
 
 ## Snapshot
 
 - Package: `cool-workflow`
-- Version: `0.1.92`
+- Version: `0.1.93`
 - Source modules: `68`
 - Workflow apps: `7`
 - Docs: `53`
-- Smoke tests: `139`
+- Smoke tests: `149`
 - Repository: https://github.com/coo1white/cool-workflow
 
 ## Architecture
@@ -196,6 +196,7 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [agent-delegation-drive-smoke.js](../test/agent-delegation-drive-smoke.js)
 - [append-run-node-no-realloc-smoke.js](../test/append-run-node-no-realloc-smoke.js)
 - [architecture-review-fast-automation-smoke.js](../test/architecture-review-fast-automation-smoke.js)
+- [architecture-review-fast-phase-cache-smoke.js](../test/architecture-review-fast-phase-cache-smoke.js)
 - [architecture-review-fast-smoke.js](../test/architecture-review-fast-smoke.js)
 - [artifact-integrity-smoke.js](../test/artifact-integrity-smoke.js)
 - [audit-verify-smoke.js](../test/audit-verify-smoke.js)
@@ -209,6 +210,12 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [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-format-smoke.js](../test/cli-format-smoke.js)
+- [cli-handler-clones-smoke.js](../test/cli-handler-clones-smoke.js)
+- [cli-handler-eval-node-smoke.js](../test/cli-handler-eval-node-smoke.js)
+- [cli-handler-maintenance-smoke.js](../test/cli-handler-maintenance-smoke.js)
+- [cli-handler-workbench-smoke.js](../test/cli-handler-workbench-smoke.js)
+- [cli-io-smoke.js](../test/cli-io-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)
@@ -222,6 +229,8 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [contract-migration-tooling-smoke.js](../test/contract-migration-tooling-smoke.js)
 - [control-plane-scheduling-smoke.js](../test/control-plane-scheduling-smoke.js)
 - [coordinator-blackboard-smoke.js](../test/coordinator-blackboard-smoke.js)
+- [cw-help-per-command-smoke.js](../test/cw-help-per-command-smoke.js)
+- [dead-export-removal-guard-smoke.js](../test/dead-export-removal-guard-smoke.js)
 - [demo-bundle-smoke.js](../test/demo-bundle-smoke.js)
 - [det-ids-b-smoke.js](../test/det-ids-b-smoke.js)
 - [doctor-smoke.js](../test/doctor-smoke.js)
@@ -301,6 +310,7 @@ Smoke tests mirror the public contracts. The high-signal suites are:
 - [run-import-tamper-failclosed-smoke.js](../test/run-import-tamper-failclosed-smoke.js)
 - [run-inspect-archive-smoke.js](../test/run-inspect-archive-smoke.js)
 - [run-registry-control-plane-smoke.js](../test/run-registry-control-plane-smoke.js)
+- [run-restore-failclosed-smoke.js](../test/run-restore-failclosed-smoke.js)
 - [run-resume-drive-smoke.js](../test/run-resume-drive-smoke.js)
 - [run-retention-reclamation-smoke.js](../test/run-retention-reclamation-smoke.js)
 - [sample-determinism-smoke.js](../test/sample-determinism-smoke.js)

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

@@ -178,4 +178,4 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 
 0.1.91
 
-0.1.92
+0.1.93

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

@@ -318,4 +318,4 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 
 0.1.91
 
-0.1.92
+0.1.93

package/docs/release-tooling.7.md

@@ -265,4 +265,4 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 
 0.1.91
 
-0.1.92
+0.1.93

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

@@ -216,9 +216,30 @@ before importing a bad archive. It is a true preview of import: under
 turn away) also inspects as `ok:false`; with the env unset (default) an absent integrity
 block is only reported, not failed.
 
+**Restore in one fail-closed step.** `run restore PATH --target DIR [--json]`
+does the whole move-a-run-to-another-machine flow as ONE atomic, fail-closed
+step: it integrity-**inspects** the bundle first (writing nothing), **imports**
+it, then reuses the verification `import` already ran — and reports `ok:true`
+ONLY when that verify passes. This closes a real gap: `run import` runs a
+verification (it re-proves restored file digests, the **telemetry ledger**, and
+the **trust-audit hash chain**) and reports it, but does NOT fail on it — it
+exits `0` even when that chain does not verify. So a run whose telemetry or
+trust-audit chain was tampered (yet whose file digests are intact) imports with a
+made-up success. `run restore` refuses exactly that: it fails closed on the same
+verification `import` only reports. A bundle that fails the up-front integrity
+inspect is refused **before any import**, so nothing is written and the run is
+never left part-restored; the result carries `imported:null` and `verify:null`.
+A bundle that imports but fails post-import verification is reported with
+`ok:false` too. It exits `1` whenever `ok:false`, so `cw run restore <path>` is a
+single command that either lands a fully-proven run or refuses with a non-zero
+exit — never a made-up success. The result is structured
+(`{ schemaVersion, ok, target, inspect, imported, verify, registry }`) so it is
+scriptable. `run import` and `run inspect-archive` are unchanged; restore is a
+thin composition of `inspectArchive` + `importRun` (reusing its verification).
+
 MCP gives the same mechanisms as `cw_run_export`, `cw_run_import`,
-`cw_run_verify_import`, and `cw_run_inspect_archive`; the CLI and MCP paths share
-the same runtime functions.
+`cw_run_verify_import`, `cw_run_inspect_archive`, and `cw_run_restore`; the CLI
+and MCP paths share the same runtime functions.
 
 ## Cross-repo history
 
@@ -243,6 +264,7 @@ node scripts/cw.js run export <run-id> --output PATH
 node scripts/cw.js run import PATH --target DIR
 node scripts/cw.js run verify-import <run-id> [--cwd DIR]
 node scripts/cw.js run inspect-archive PATH [--json]
+node scripts/cw.js run restore PATH --target DIR [--json]
 node scripts/cw.js queue add [--app ID|--workflow ID|--runId ID] [--repo PATH] [--priority N] [--note TEXT]
 node scripts/cw.js queue list [--status STATE] [--repo PATH] [--json]
 node scripts/cw.js queue show <queue-id>
@@ -439,4 +461,4 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 
 0.1.91
 
-0.1.92
+0.1.93

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

@@ -229,4 +229,4 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 
 0.1.91
 
-0.1.92
+0.1.93

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

@@ -307,4 +307,4 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 
 0.1.91
 
-0.1.92
+0.1.93

package/docs/team-collaboration.7.md

@@ -243,4 +243,4 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 
 0.1.91
 
-0.1.92
+0.1.93

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

@@ -251,4 +251,4 @@ _No behavioral change in v0.1.89 (CLI-surface golden-path + help-output fixes on
 
 0.1.91
 
-0.1.92
+0.1.93

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.92",
+    "version": "0.1.93",
     "license": "BSD-2-Clause",
     "homepage": "https://github.com/coo1white/cool-workflow",
     "author": {

package/package.json

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

package/scripts/architecture-review-fast.js

@@ -38,13 +38,20 @@ function main() {
   const fastModel = stringArg(args.fastModel || args["fast-model"]);
   const strongModel = stringArg(args.strongModel || args["strong-model"]);
   const modelEnv = modelPolicyEnv(fastModel, strongModel);
+  // Opt-in incremental overlay: scope the exported source context to files
+  // changed since REF (e.g. origin/main). The source-context export resolves
+  // the ref, keys its cache separately, and records the base. The fast review
+  // then runs over the narrower context; the scheduled full review stays a
+  // complete audit (see scheduleFullReview).
+  const changedFrom = stringArg(args.changedFrom || args["changed-from"]);
 
   const contextExport = timed(() => exportSourceContext({
     repo,
     profile,
     ref,
     profileFile,
-    cacheDir
+    cacheDir,
+    changedFrom
   }));
   const contextText = contextExport.value;
   assertNonEmptySourceContext(contextText, profile, repo);
@@ -87,7 +94,8 @@ function main() {
     digest,
     profile,
     ref,
-    cacheDir
+    cacheDir,
+    ...(changedFrom ? { changedFrom } : {})
   };
   const fullReviewScheduleRun = truthy(args.scheduleFull || args["schedule-full"])
     ? timed(() => scheduleFullReview(repo, question, args, fastReview, sourceContextMeta))
@@ -101,7 +109,7 @@ function main() {
     fastReview,
     ...(fastModel || strongModel ? { modelPolicy: { ...(fastModel ? { fastModel } : {}), ...(strongModel ? { strongModel } : {}) } } : {}),
     ...(fullReviewSchedule ? { fullReviewSchedule } : {}),
-    ...(includeMetrics ? { metrics: buildMetrics(started, contextText, contextExport.elapsedMs, fastReview, fastReviewRun.elapsedMs, fullReviewScheduleRun?.elapsedMs) } : {})
+    ...(includeMetrics ? { metrics: buildMetrics(started, contextText, contextExport.elapsedMs, fastReview, fastReviewRun.elapsedMs, fullReviewScheduleRun?.elapsedMs, changedFrom) } : {})
   });
 }
 
@@ -119,6 +127,7 @@ function exportSourceContext(options) {
     options.cacheDir
   ];
   if (options.profileFile) argv.push("--profile-file", path.resolve(options.profileFile));
+  if (options.changedFrom) argv.push("--changed-from", options.changedFrom);
   const result = spawnSync(node, argv, {
     cwd: repoRoot,
     encoding: "utf8",
@@ -194,6 +203,9 @@ function scheduleFullReview(repo, question, args, fastReview, sourceContextMeta)
     fastReview?.reportPath ? `Fast review report: ${fastReview.reportPath}.` : "",
     `Fast review status: ${fastReview?.status || "unknown"} (${fastReview?.completedWorkers || 0}/${fastReview?.plannedWorkers || 0} workers completed).`,
     `Source context: ${sourceContextMeta.path} (${sourceContextMeta.digest}, profile ${sourceContextMeta.profile}, ref ${sourceContextMeta.ref}).`,
+    sourceContextMeta.changedFrom
+      ? `Fast review used an incremental overlay (changed-from ${sourceContextMeta.changedFrom}); this full review must audit the complete source, not only the changed files.`
+      : "",
     "Use the completed architecture-review-fast report as the foreground triage result; write the full review report path and digest when the background review finishes."
   ].filter(Boolean).join(" ");
   return runCwJson([
@@ -304,7 +316,7 @@ function timed(fn) {
   return { value, elapsedMs: elapsedMs(started) };
 }
 
-function buildMetrics(started, contextText, sourceContextElapsedMs, fastReview, fastReviewElapsedMs, fullReviewScheduleElapsedMs) {
+function buildMetrics(started, contextText, sourceContextElapsedMs, fastReview, fastReviewElapsedMs, fullReviewScheduleElapsedMs, changedFrom) {
   const steps = Array.isArray(fastReview?.steps) ? fastReview.steps : [];
   const handleKinds = countBy(steps.map((step) => step && step.handleKind).filter(Boolean));
   const actions = countBy(steps.map((step) => step && step.action).filter(Boolean));
@@ -314,7 +326,8 @@ function buildMetrics(started, contextText, sourceContextElapsedMs, fastReview,
     sourceContext: {
       elapsedMs: sourceContextElapsedMs,
       bytes: Buffer.byteLength(contextText, "utf8"),
-      digest: `sha256:${crypto.createHash("sha256").update(contextText, "utf8").digest("hex")}`
+      digest: `sha256:${crypto.createHash("sha256").update(contextText, "utf8").digest("hex")}`,
+      ...(changedFrom ? { changedFrom } : {})
     },
     fastReview: {
       elapsedMs: fastReviewElapsedMs,
@@ -388,6 +401,7 @@ function usage(code) {
     "",
     "options:",
     "  --profile core --ref HEAD --profile-file PATH --cache-dir DIR --context-out PATH",
+    "  --changed-from REF   (incremental overlay: scope context to files changed since REF)",
     "  --fast-model MODEL --strong-model MODEL",
     "  --invariant TEXT --focus TEXT --preview --once",
     "  --schedule-full [--full-delay-minutes N]",

package/scripts/bump-version.js

@@ -143,6 +143,22 @@ function main() {
     note(rel);
   }
 
+  // 5c. Homebrew formula (repo root, not under pluginRoot). Structured surface:
+  //     a git-tag formula with no sha256. Homebrew reads the version from the
+  //     tag, so the ONLY literal that moves is `tag: "v<version>"` (an explicit
+  //     `version` line would be redundant and brew audit rejects it). A targeted
+  //     exact-string swap keeps the file byte-formatting intact;
+  //     version-sync-check.js asserts the tag at HEAD, so it can never drift.
+  const formula = path.join(repoRoot, "Formula", "cool-workflow.rb");
+  if (fs.existsSync(formula)) {
+    const text = fs.readFileSync(formula, "utf8");
+    const updated = text.split(`tag: "v${current}"`).join(`tag: "v${next}"`);
+    if (updated !== text) {
+      fs.writeFileSync(formula, updated);
+      note("Formula/cool-workflow.rb");
+    }
+  }
+
   process.stdout.write(`bump:version ${current} -> ${next}\n`);
   for (const rel of touched) process.stdout.write(`  updated  ${rel}\n`);
 

package/scripts/canonical-apps.js

@@ -83,7 +83,7 @@ const canonicalApps = [
       "--source",
       "plugins/cool-workflow/docs/workflow-app-framework.7.md",
       "--scope",
-      "Cool Workflow v0.1.92",
+      "Cool Workflow v0.1.93",
       "--freshness",
       "as of release preparation"
     ]
@@ -117,14 +117,14 @@ function main() {
     assert.ok(summary, `${app.id} must appear in app list`);
     assert.equal(summary.sourceKind, "app-directory");
     assert.equal(summary.legacy, false);
-    assert.equal(summary.version, "0.1.92");
+    assert.equal(summary.version, "0.1.93");
 
     const validation = runJson(["app", "validate", manifestPath]);
     assert.equal(validation.valid, true, `${app.id} manifest must validate`);
 
     const shown = runJson(["app", "show", app.id]);
     assert.equal(shown.app.id, app.id);
-    assert.equal(shown.app.version, "0.1.92");
+    assert.equal(shown.app.version, "0.1.93");
     assert.ok(shown.app.metadata.canonical, `${app.id} must be marked canonical`);
     assert.ok(shown.app.sandboxProfiles.length > 0, `${app.id} must declare sandbox profiles`);
     assertTaskIdsUnique(shown);
@@ -135,7 +135,7 @@ function main() {
     const plan = runJson(["plan", app.id, ...app.args(workspace)]);
     const state = JSON.parse(fs.readFileSync(plan.statePath, "utf8"));
     assert.equal(state.workflow.app.id, app.id);
-    assert.equal(state.workflow.app.version, "0.1.92");
+    assert.equal(state.workflow.app.version, "0.1.93");
     assert.equal(state.workflow.app.metadata.canonical, true);
     assert.ok(state.tasks.some((task) => task.requiresEvidence), `${app.id} plan must include evidence gates`);
     assert.ok(state.tasks.every((task) => task.sandboxProfileId), `${app.id} plan must include sandbox hints`);

package/scripts/dogfood-release.js

@@ -6,7 +6,7 @@ const fs = require("node:fs");
 const path = require("node:path");
 const { CoolWorkflowRunner } = require("../dist/orchestrator.js");
 
-const TARGET_VERSION = "0.1.92";
+const TARGET_VERSION = "0.1.93";
 const PREVIOUS_VERSION = "0.1.31";
 const pluginRoot = path.resolve(__dirname, "..");
 const repoRoot = path.resolve(pluginRoot, "..", "..");

package/scripts/golden-path.js

@@ -33,7 +33,7 @@ function main() {
     const appValidation = runJson(["app", "validate", "end-to-end-golden-path"], pluginRoot);
     assert.equal(appValidation.valid, true);
     assert.equal(appValidation.summary.id, "end-to-end-golden-path");
-    assert.equal(appValidation.summary.version, "0.1.92");
+    assert.equal(appValidation.summary.version, "0.1.93");
 
     const plan = runJson(
       [
@@ -42,7 +42,7 @@ function main() {
         "--repo",
         tmp,
         "--question",
-        "Prove the deterministic v0.1.92 end-to-end golden path."
+        "Prove the deterministic v0.1.93 end-to-end golden path."
       ],
       pluginRoot
     );
@@ -52,7 +52,7 @@ function main() {
 
     let state = readJson(plan.statePath);
     assert.equal(state.workflow.app.id, "end-to-end-golden-path");
-    assert.equal(state.workflow.app.version, "0.1.92");
+    assert.equal(state.workflow.app.version, "0.1.93");
     assert.equal(state.loopStage, "interpret");
 
     const dispatch = runJson(["dispatch", plan.runId, "--limit", "1", "--sandbox", "readonly"], tmp);
@@ -195,7 +195,7 @@ function main() {
     assert.equal(reportPath, plan.reportPath);
     assert.ok(fs.existsSync(reportPath));
     const report = fs.readFileSync(reportPath, "utf8");
-    assert.match(report, /Workflow App: end-to-end-golden-path@0\.1\.92/);
+    assert.match(report, /Workflow App: end-to-end-golden-path@0\.1\.93/);
     assert.match(report, /## Candidates/);
     assert.match(report, /## Trust Audit/);
     assert.match(report, /## Acceptance Rationale/);

package/scripts/parity-check.js

@@ -69,7 +69,15 @@ function cliDispatchTokens() {
 }
 
 function cliDispatchSources() {
-  return [cli, path.join(pluginRoot, "dist", "cli", "command-surface.js")].filter((file) => fs.existsSync(file));
+  // The dispatcher + every per-command handler module carved out of it (the
+  // command-surface god-object decomposition). A verb's subcommand `case`s may
+  // live in dist/cli/handlers/<group>.js, so scan those too or their tokens read
+  // as "missing from dist/cli.js".
+  const handlersDir = path.join(pluginRoot, "dist", "cli", "handlers");
+  const handlerFiles = fs.existsSync(handlersDir)
+    ? fs.readdirSync(handlersDir).filter((name) => name.endsWith(".js")).map((name) => path.join(handlersDir, name))
+    : [];
+  return [cli, path.join(pluginRoot, "dist", "cli", "command-surface.js"), ...handlerFiles].filter((file) => fs.existsSync(file));
 }
 
 function cliHelpTokens() {

package/scripts/version-sync-check.js

@@ -196,6 +196,11 @@ function main() {
   checkIncludes("plugins/cool-workflow/docs/release-and-migration.7.md", VERSION, checks);
   checkIncludes("CHANGELOG.md", `## ${VERSION}`, checks);
   checkIncludes("RELEASE.md", VERSION, checks);
+  // Homebrew formula (repo root): git-tag formula. Homebrew scans the version
+  // from the tag, so the tag is the single version surface to gate (an explicit
+  // `version` line would be redundant and brew audit rejects it). bump-version.js
+  // moves this tag.
+  checkIncludes("Formula/cool-workflow.rb", `tag: "v${VERSION}"`, checks);
   checkIncludes("plugins/cool-workflow/skills/cool-workflow/SKILL.md", "release:check", checks);
 
   process.stdout.write(