cool-workflow 0.1.97 → 0.2.0

package/scripts/children/batch-delegate-child.js

@@ -8,13 +8,19 @@
 //
 // Reads jobs JSON on stdin, spawns ALL concurrently (shell:false, inherited env —
 // the agent's own credentials resolve; CW never reads them), per-job SIGTERM at
-// timeoutMs + SIGKILL at +5s, caps each captured stdout at 32MB, and prints the
-// outcome array when every job has settled. stderr is drained (a full pipe must
-// never wedge a child). A kill yields exitCode null — the no-exit-code refusal.
+// timeoutMs + SIGKILL at +5s, caps each captured stdout at 32MB. Streams ONE
+// NDJSON line per job — `{i, spawnError?, exitCode, stdout}\n` — the INSTANT
+// that job settles (not once at the end): the parent's spawnSync call has its
+// own combined-output cap, so writing incrementally means a job whose line
+// already flushed keeps its real outcome even if a LATER job's output pushes
+// the combined stream over that cap and the whole child gets killed. `i` is
+// the job's index (settle order is concurrent, not submission order — the
+// parent cannot infer which line belongs to which job without it). stderr is
+// drained (a full pipe must never wedge a child). A kill yields exitCode null
+// — the no-exit-code refusal.
 //
 // THE RED LINE: this child only `spawn`s the operator-resolved agent binary with
-// shell:false. It imports NO model SDK and reads NO credentials. Behavior MUST
-// stay byte-identical to the previous embedded string.
+// shell:false. It imports NO model SDK and reads NO credentials.
 
 const { spawn } = require("node:child_process");
 let raw = "";
@@ -30,17 +36,16 @@ process.stdin.on("end", () => {
     return;
   }
   if (!jobs.length) { process.stdout.write("[]"); return; }
-  const out = new Array(jobs.length);
-  let pending = jobs.length;
   const CAP = 32 * 1024 * 1024;
   jobs.forEach((job, i) => {
     let stdout = "";
+    let stdoutBytes = 0;
+    let stdoutTruncated = false;
     let settled = false;
     const settle = (o) => {
       if (settled) return;
       settled = true;
-      out[i] = o;
-      if (--pending === 0) process.stdout.write(JSON.stringify(out));
+      process.stdout.write(JSON.stringify({ i, ...o }) + "\n");
     };
     let child;
     try {
@@ -51,7 +56,18 @@ process.stdin.on("end", () => {
     }
     const term = setTimeout(() => { try { child.kill("SIGTERM"); } catch {} }, job.timeoutMs);
     const kill = setTimeout(() => { try { child.kill("SIGKILL"); } catch {} }, job.timeoutMs + 5000);
-    child.stdout.on("data", (d) => { if (stdout.length < CAP) stdout += d; });
+    child.stdout.on("data", (d) => {
+      const chunk = Buffer.isBuffer(d) ? d : Buffer.from(String(d));
+      stdoutBytes += chunk.length;
+      if (stdoutTruncated) return;
+      const remaining = CAP - Buffer.byteLength(stdout);
+      if (remaining <= 0 || chunk.length > remaining) {
+        stdoutTruncated = true;
+        if (remaining > 0) stdout += chunk.subarray(0, remaining).toString();
+        return;
+      }
+      stdout += chunk.toString();
+    });
     child.stderr.on("data", () => {});
     child.on("error", (error) => {
       clearTimeout(term); clearTimeout(kill);
@@ -59,6 +75,10 @@ process.stdin.on("end", () => {
     });
     child.on("close", (code) => {
       clearTimeout(term); clearTimeout(kill);
+      if (stdoutTruncated) {
+        settle({ spawnError: `stdout exceeded ${CAP} byte cap (${stdoutBytes} bytes)`, exitCode: null, stdout: "" });
+        return;
+      }
       settle({ exitCode: typeof code === "number" ? code : null, stdout });
     });
   });

package/scripts/dogfood-architecture-review.js

@@ -23,9 +23,8 @@ const os = require("node:os");
 const path = require("node:path");
 
 const pluginRoot = path.resolve(__dirname, "..");
-const { CoolWorkflowRunner } = require(path.join(pluginRoot, "dist/orchestrator.js"));
-const { drive } = require(path.join(pluginRoot, "dist/drive.js"));
-const { resolveAgentConfig } = require(path.join(pluginRoot, "dist/agent-config.js"));
+const { CoolWorkflowRunner, drive } = require(path.join(pluginRoot, "dist/shell/orchestrator.js"));
+const { resolveAgentConfig } = require(path.join(pluginRoot, "dist/shell/agent-config.js"));
 
 const argv = process.argv.slice(2);
 const flags = new Set(argv.filter((a) => a.startsWith("--")));

package/scripts/dogfood-release.js

@@ -4,9 +4,9 @@
 const { spawnSync } = require("node:child_process");
 const fs = require("node:fs");
 const path = require("node:path");
-const { CoolWorkflowRunner } = require("../dist/orchestrator.js");
+const { CoolWorkflowRunner } = require("../dist/shell/orchestrator.js");
 
-const TARGET_VERSION = "0.1.97";
+const TARGET_VERSION = "0.2.0";
 const PREVIOUS_VERSION = "0.1.31";
 const pluginRoot = path.resolve(__dirname, "..");
 const repoRoot = path.resolve(pluginRoot, "..", "..");
@@ -269,7 +269,7 @@ function commandsForTask(taskId, context) {
               "-e",
               [
                 releaseSourceReaderSnippet(),
-                "for (const f of ['plugins/cool-workflow/package.json','plugins/cool-workflow/src/version.ts','CHANGELOG.md','RELEASE.md']) {",
+                "for (const f of ['plugins/cool-workflow/package.json','plugins/cool-workflow/src/core/version.ts','CHANGELOG.md','RELEASE.md']) {",
                 " const t=readSurface(f);",
                 ` if (t===null) throw new Error(f+' missing from release commit');`,
                 ` if (!t.includes('${TARGET_VERSION}')) throw new Error(f+' missing ${TARGET_VERSION}');`,

package/scripts/gen-parity-doc.js

@@ -22,7 +22,13 @@ const pluginRoot = path.resolve(__dirname, "..");
 const DOC = path.join(pluginRoot, "docs", "cli-mcp-parity.7.md");
 const CHECK = process.argv.includes("--check");
 
-const { CAPABILITY_REGISTRY } = require(path.join(pluginRoot, "dist", "capability-registry.js"));
+// v2 repoint: the flat dist/capability-registry.js is gone. The single
+// source of truth is now core/capability-table's REGISTRY (same row shape:
+// capability, surface, cli, mcp, payloadIdentical, reason, entry, ...),
+// exported under the old name too (CAPABILITY_REGISTRY = REGISTRY, an
+// alias declared in capability-table.ts for callers written against the
+// old name).
+const { CAPABILITY_REGISTRY } = require(path.join(pluginRoot, "dist", "core", "capability-table.js"));
 
 const NUM_WORDS = ["Zero", "One", "Two", "Three", "Four", "Five", "Six", "Seven", "Eight", "Nine", "Ten", "Eleven", "Twelve"];
 const numWord = (n) => NUM_WORDS[n] || String(n);
@@ -41,6 +47,13 @@ function payload(cap) {
   if (cap.surface !== "both") return cap.surface;
   return cap.payloadIdentical === false ? "projected" : "identical";
 }
+// v2 adapt: this table's `entry` field is only set where a row names its
+// shared core entry explicitly (most rows do not yet, unlike the old flat
+// registry where every row named one). Fall back to the capability id
+// itself so the doc table never prints a literal "undefined".
+function coreEntry(cap) {
+  return cap.entry || cap.capability;
+}
 
 function buildCount() {
   const caps = CAPABILITY_REGISTRY.length;
@@ -54,7 +67,7 @@ function buildTable() {
     "| --- | --- | --- | --- | --- | --- |"
   ];
   for (const cap of CAPABILITY_REGISTRY) {
-    lines.push(`| \`${cap.capability}\` | \`${cliCommand(cap)}\` | \`${mcpTool(cap)}\` | \`${cap.entry}\` | ${payload(cap) === "cli-only" || cap.surface !== "both" ? cap.surface : "both"} | ${payload(cap)} |`);
+    lines.push(`| \`${cap.capability}\` | \`${cliCommand(cap)}\` | \`${mcpTool(cap)}\` | \`${coreEntry(cap)}\` | ${payload(cap) === "cli-only" || cap.surface !== "both" ? cap.surface : "both"} | ${payload(cap)} |`);
   }
   return lines.join("\n");
 }

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.97");
+    assert.equal(appValidation.summary.version, "0.2.0");
 
     const plan = runJson(
       [
@@ -42,7 +42,7 @@ function main() {
         "--repo",
         tmp,
         "--question",
-        "Prove the deterministic v0.1.97 end-to-end golden path."
+        "Prove the deterministic v0.2.0 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.97");
+    assert.equal(state.workflow.app.version, "0.2.0");
     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\.97/);
+    assert.match(report, /Workflow App: end-to-end-golden-path@0\.2\.0/);
     assert.match(report, /## Candidates/);
     assert.match(report, /## Trust Audit/);
     assert.match(report, /## Acceptance Rationale/);

package/scripts/onramp-check.js

@@ -6,7 +6,7 @@
 // source/app/script changes need an iteration-log row.
 
 const path = require("node:path");
-const { evaluateOnrampContract, resolveChangedFiles } = require("../dist/onramp.js");
+const { evaluateOnrampContract, resolveChangedFiles } = require("../dist/shell/onramp.js");
 
 const pluginRoot = path.resolve(__dirname, "..");
 

package/scripts/parity-check.js

@@ -15,8 +15,16 @@
 //      `cw <cmd> --json` payload must equal the `cw_<tool>` MCP result on a real
 //      bootstrap run (whitespace + generation-moment ISO timestamps aside).
 //
-// The registry (src/capability-registry.ts -> dist/capability-registry.js) is
-// the single source of truth; this script never re-declares capabilities.
+// The registry (src/core/capability-table.ts -> dist/core/capability-table.js)
+// is the single source of truth; this script never re-declares capabilities.
+//
+// v2 repoint: the old flat dist/capability-registry.js, dist/orchestrator.js,
+// dist/state.js, dist/state-node.js are gone. Each function this script
+// actually calls now lives in its v2 core/shell home:
+//   - registry (capability + parity planning data) -> core/capability-table.js
+//   - formatHelp                                    -> core/format/help.js
+//   - loadRunFromCwd, saveCheckpoint                 -> shell/run-store.js
+//   - appendRunNode, createStateNode                 -> core/state/state-node.js
 
 const assert = require("node:assert/strict");
 const { execFileSync, spawn } = require("node:child_process");
@@ -29,10 +37,10 @@ const pluginRoot = path.resolve(__dirname, "..");
 const node = process.execPath;
 const cli = path.join(pluginRoot, "dist", "cli.js");
 const mcpServer = path.join(pluginRoot, "dist", "mcp-server.js");
-const registry = require(path.join(pluginRoot, "dist", "capability-registry.js"));
-const { formatHelp } = require(path.join(pluginRoot, "dist", "orchestrator.js"));
-const { loadRunFromCwd, saveCheckpoint } = require(path.join(pluginRoot, "dist", "state.js"));
-const { appendRunNode, createStateNode } = require(path.join(pluginRoot, "dist", "state-node.js"));
+const registry = require(path.join(pluginRoot, "dist", "core", "capability-table.js"));
+const { formatHelp } = require(path.join(pluginRoot, "dist", "core", "format", "help.js"));
+const { loadRunFromCwd, saveCheckpoint } = require(path.join(pluginRoot, "dist", "shell", "run-store.js"));
+const { appendRunNode, createStateNode } = require(path.join(pluginRoot, "dist", "core", "state", "state-node.js"));
 
 function capById(id) {
   const cap = registry.CAPABILITY_REGISTRY.find((entry) => entry.capability === id);
@@ -64,21 +72,20 @@ function liveMcpTools() {
 }
 
 function cliDispatchTokens() {
-  const source = cliDispatchSources().map((file) => fs.readFileSync(file, "utf8")).join("\n");
-  return [...new Set([...source.matchAll(/case\s+"([^"]+)":/g)].map((match) => match[1]))];
+  // v2 dispatch is table-driven (findCapabilityByCliPath over REGISTRY), not a
+  // switch, so the token set is the union of every CLI capability's accepted
+  // first tokens (cli.caseTokens where an alias set is declared, else cli.path).
+  // The reachability check below then proves each declared path resolves through
+  // the live dispatcher — replacing the old `case "x":` dist source-grep.
+  return [...new Set(registry.cliCapabilities().flatMap((cap) => cap.cli.caseTokens ?? cap.cli.path))];
 }
 
-function cliDispatchSources() {
-  // 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));
-}
+// Old-build top-level verbs kept in the frozen help "More commands" index line
+// but folded in v2 into subcommands / the shell layer: init->app.init,
+// search->run.search (declaredCliHelpTokens collapses both to app/run), and
+// update is a shell-level command with no capability-table row. Help-index
+// discovery text, not dispatch-parity tokens — exclude them.
+const HELP_INDEX_ONLY_TOKENS = new Set(["init", "search", "update"]);
 
 function cliHelpTokens() {
   const lines = formatHelp().split(/\r?\n/);
@@ -91,7 +98,7 @@ function cliHelpTokens() {
     const first = trimmed.split(/\s+/)[0];
     for (const token of first.split("|")) {
       const clean = token.replace(/[<[].*$/, "");
-      if (clean) tokens.add(clean);
+      if (clean && !HELP_INDEX_ONLY_TOKENS.has(clean)) tokens.add(clean);
     }
   }
   return [...tokens].sort();
@@ -101,8 +108,18 @@ function cliHelpTokens() {
 // Generation-moment ISO timestamps are presentation metadata, not capability
 // data: the same field carries the wall-clock instant of the render. Neutralize
 // them (and only them) before comparison so we assert canonical-payload identity.
+// Also neutralize the metrics fields derived from a live run's `updatedAt`
+// (wallClockMs = elapsed-since-updatedAt; sourceFingerprint / freshness's
+// current+persisted fingerprints = a hash folding updatedAt). These drift
+// between two separate reads (the CLI subprocess vs the in-process MCP call) of
+// the SAME unchanged run — the same non-determinism web-desktop-workbench-smoke
+// neutralizes with its canonicalStable. Only the workbench/metrics payloads
+// carry these fields, so the extra replacements are a no-op elsewhere.
 function canonical(value) {
-  return JSON.stringify(value).replace(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z/g, "<ts>");
+  return JSON.stringify(value)
+    .replace(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z/g, "<ts>")
+    .replace(/"wallClockMs":\d+/g, '"wallClockMs":<ms>')
+    .replace(/"(sourceFingerprint|currentFingerprint|persistedFingerprint)":"[^"]*"/g, '"$1":"<fp>"');
 }
 
 function escapeRegExp(value) {

package/scripts/release-flow.js

@@ -233,9 +233,9 @@ function delegateReview(resultPath, inputPath) {
   // Reuse the canonical agent-config resolver (flags > env > file).
   let resolveAgentConfig;
   try {
-    ({ resolveAgentConfig } = require(path.join(pluginRoot, "dist", "agent-config.js")));
+    ({ resolveAgentConfig } = require(path.join(pluginRoot, "dist", "shell", "agent-config.js")));
   } catch (e) {
-    die("cannot load dist/agent-config.js — run `npm run build` first", String(e));
+    die("cannot load dist/shell/agent-config.js — run `npm run build` first", String(e));
   }
   const cfg = resolveAgentConfig(
     { "agent-command": val("--agent-command"), "agent-model": val("--agent-model") },
@@ -283,7 +283,13 @@ function delegateReview(resultPath, inputPath) {
     // the file takes precedence. stderr goes to the terminal for live output.
     const r = spawnSync(bin, args, {
       cwd: repoRoot,
-      env: { ...process.env },
+      // CW_RELEASE_REVIEW=1 is a vendor-agnostic signal that THIS spawn is a
+      // release verdict, not a fast worker turn. Wrappers that can re-run the gate
+      // (e.g. codex-agent.js) read it to raise reasoning effort and open an
+      // exec-capable sandbox — a read-only/low-effort reviewer can't execute the
+      // gate it judges and degrades to fabricated verdicts. Preflight liveness
+      // probes never set it, so they stay fast and read-only.
+      env: { ...process.env, CW_RELEASE_REVIEW: "1" },
       encoding: "utf8",
       timeout: cfg.timeoutMs || REVIEWER_TIMEOUT_MS,
       shell: false,

package/scripts/sync-project-index.js

@@ -25,51 +25,55 @@ const CHECK = process.argv.includes("--check");
 const REPO_ONLY = process.argv.includes("--repo-only");
 const indexPathOverride = process.env.CW_PROJECT_INDEX_PATH || "";
 
+// v2 layout: src/ splits into a pure core/ (state kernel, pipeline decisions,
+// multi-agent decisions, workflow-app schema) and an impure shell/ (file IO,
+// CLI/MCP wiring, worker sandboxing). Paths below are relative to src/ and
+// may include a subdirectory — the render step keeps the full relative path
+// as both the link target and the label, so the table also shows which
+// layer (core vs shell) each module lives in.
 const moduleCatalog = {
   "Core runtime": [
-    ["orchestrator.ts", "Plans runs, loads workflows, records results, writes reports, and exposes runner commands."],
-    ["state.ts", "Persists run checkpoints, JSON state, run paths, and state migration entrypoints."],
-    ["state-node.ts", "Defines explicit state nodes, pipeline transitions, evidence checks, and node persistence."],
-    ["pipeline-contract.ts", "Builds the default pipeline contract used by run state."],
-    ["pipeline-runner.ts", "Finds runnable stages and advances/fails pipeline nodes with retry-aware errors."],
-    ["types.ts", "Owns the shared workflow, run, app, evidence, worker, candidate, audit, and topology types."]
+    ["shell/orchestrator.ts", "Plans runs, loads workflows, records results, writes reports, and exposes runner commands (a thin facade over the shell functions below)."],
+    ["shell/run-store.ts", "Persists run checkpoints, JSON state, run paths, and state migration entrypoints."],
+    ["core/state/state-node.ts", "Defines explicit state nodes, pipeline transitions, evidence checks, and node persistence."],
+    ["core/pipeline/contract.ts", "Builds the default pipeline contract used by run state."],
+    ["core/pipeline/runner.ts", "Finds runnable stages and advances/fails pipeline nodes with retry-aware errors."],
+    ["core/state/types.ts", "Owns the shared run/state types: WorkflowRun and everything it carries, StateNode, and the pipeline contract shape."]
   ],
   "Verification and state gates": [
-    ["verifier.ts", "Validates result envelopes, findings, evidence, and run gate completion."],
-    ["commit.ts", "Creates verifier-gated commits and explicit manual checkpoints."],
-    ["candidate-scoring.ts", "Registers, scores, ranks, selects, rejects, and summarizes candidate outputs."],
-    ["error-feedback.ts", "Turns failures into persisted feedback records and correction tasks."],
-    ["trust-audit.ts", "Records provenance, sandbox decisions, host attestations, and acceptance rationale."]
+    ["shell/verifier.ts", "Validates result envelopes, findings, evidence, and run gate completion."],
+    ["shell/commit.ts", "Creates verifier-gated commits and explicit manual checkpoints."],
+    ["core/multi-agent/candidate-scoring.ts", "Registers, scores, ranks, selects, rejects, and summarizes candidate outputs."],
+    ["core/pipeline/error-feedback.ts", "Turns failures into persisted feedback records and correction tasks."],
+    ["shell/trust-audit.ts", "Records provenance, sandbox decisions, host attestations, and acceptance rationale."]
   ],
   "Workers and policy": [
-    ["dispatch.ts", "Selects runnable tasks and writes dispatch manifests."],
-    ["worker-isolation.ts", "Allocates worker scopes, writes manifests, records worker outputs, and validates boundaries."],
-    ["sandbox-profile.ts", "Resolves named sandbox policy contracts and validates read/write/command/network boundaries."],
-    ["harness.ts", "Renders task files for dispatched work."]
+    ["shell/dispatch.ts", "Selects runnable tasks and writes dispatch manifests."],
+    ["shell/worker-isolation.ts", "Allocates worker scopes, writes manifests, records worker outputs, and validates boundaries."],
+    ["shell/sandbox-profile.ts", "Resolves named sandbox policy contracts and validates read/write/command/network boundaries."],
+    ["shell/harness.ts", "Renders task files for dispatched work."]
   ],
   "Multi-agent layer": [
-    ["multi-agent.ts", "Persists multi-agent runs, roles, groups, memberships, fanouts, and fanins."],
-    ["coordinator.ts", "Owns blackboard topics, messages, context, artifacts, snapshots, and coordinator decisions."],
-    ["topology.ts", "Defines and applies official map-reduce, debate, and judge-panel topologies."],
-    ["multi-agent-host.ts", "Provides the preferred host loop for run, status, step, blackboard, score, and select."]
+    ["core/multi-agent/runtime.ts", "Persists multi-agent runs, roles, groups, memberships, fanouts, and fanins."],
+    ["core/multi-agent/coordinator.ts", "Owns blackboard topics, messages, context, artifacts, snapshots, and coordinator decisions."],
+    ["core/multi-agent/topology.ts", "Defines and applies official map-reduce, debate, and judge-panel topologies."],
+    ["shell/multi-agent-host.ts", "Provides the preferred host loop for run, status, step, blackboard, score, and select."]
   ],
   "User and host surfaces": [
     ["cli.ts", "Routes human CLI commands to runtime, app, topology, multi-agent, and operator flows."],
     ["mcp-server.ts", "Exposes JSON-RPC/MCP tool parity for agent hosts."],
-    ["operator-ux.ts", "Formats status, reports, graph, worker, candidate, feedback, commit, and trust summaries."],
-    ["workflow-app-framework.ts", "Validates app manifests and loads app entrypoints."],
-    ["workflow-api.ts", "Provides the fluent workflow, phase, task, artifact, and input API."],
-    ["daemon.ts", "Runs scheduled tasks through the desktop scheduler daemon."],
-    ["scheduler.ts", "Creates, stores, computes, and runs schedules."],
-    ["triggers.ts", "Bridges routine triggers to explicit workflow events."],
-    ["version.ts", "Defines current package and state schema versions."]
+    ["shell/operator-ux.ts", "Formats status, reports, graph, worker, candidate, feedback, commit, and trust summaries."],
+    ["shell/workflow-app-loader.ts", "Validates app manifests and loads app entrypoints."],
+    ["core/workflow-apps/app-schema.ts", "Provides the fluent workflow, phase, task, artifact, and input API."],
+    ["shell/scheduler-io.ts", "Runs wall-clock schedules, the desktop scheduler daemon tick, and routine triggers."],
+    ["core/version.ts", "Defines current package and state schema versions."]
   ]
 };
 
 function main() {
   const apps = listApps();
   const docs = listMarkdown(path.join(pluginRoot, "docs"));
-  const sourceFiles = listFiles(path.join(pluginRoot, "src"), ".ts");
+  const sourceFiles = listFilesRecursive(path.join(pluginRoot, "src"), ".ts");
   const smokeTests = listFiles(path.join(pluginRoot, "test"), ".js").filter((file) => file.endsWith("-smoke.js"));
   const context = { apps, docs, sourceFiles, smokeTests };
 
@@ -184,6 +188,26 @@ function listFiles(dir, extension) {
     .sort();
 }
 
+// v2's src/ splits into core/ and shell/ subdirectories (see moduleCatalog's
+// header note), so a flat top-level scan misses almost every file. Walk the
+// whole tree and return paths relative to `dir` with forward slashes, so a
+// catalog entry like "shell/orchestrator.ts" matches what this returns.
+function listFilesRecursive(dir, extension) {
+  const out = [];
+  const walk = (current) => {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (entry.isFile() && entry.name.endsWith(extension)) {
+        out.push(path.relative(dir, full).split(path.sep).join("/"));
+      }
+    }
+  };
+  walk(dir);
+  return out.sort();
+}
+
 function renderIndex(target, context) {
   const link = linkFactory(target);
   const lines = [];

package/scripts/validate-run-state-schema.js

@@ -17,8 +17,8 @@ const fs = require("node:fs");
 const path = require("node:path");
 
 const PLUGIN_ROOT = path.resolve(__dirname, "..");
-const TYPES_FILE = path.join(PLUGIN_ROOT, "src", "types", "run.ts");
-const SCHEMA_MODULE = path.join(PLUGIN_ROOT, "dist", "run-state-schema.js");
+const TYPES_FILE = path.join(PLUGIN_ROOT, "src", "core", "state", "types.ts");
+const SCHEMA_MODULE = path.join(PLUGIN_ROOT, "dist", "core", "state", "schema.js");
 
 function main() {
   const errors = [];

package/scripts/version-sync-check.js

@@ -66,10 +66,10 @@ function main() {
   checkJson("plugins/cool-workflow/.claude-plugin/plugin.json", "version", VERSION, checks);
   checkJson("plugins/cool-workflow/.gemini-plugin/plugin.json", "version", VERSION, checks);
   checkJson("plugins/cool-workflow/.opencode-plugin/plugin.json", "version", VERSION, checks);
-  checkIncludes("plugins/cool-workflow/src/version.ts", `CURRENT_COOL_WORKFLOW_VERSION = "${VERSION}"`, checks);
-  checkIncludes("plugins/cool-workflow/src/version.ts", "CURRENT_RUN_STATE_SCHEMA_VERSION = 1", checks);
-  checkIncludes("plugins/cool-workflow/src/mcp-server.ts", "CURRENT_COOL_WORKFLOW_VERSION", checks);
-  checkIncludes("plugins/cool-workflow/src/workflow-app-framework.ts", "CURRENT_COOL_WORKFLOW_VERSION", checks);
+  checkIncludes("plugins/cool-workflow/src/core/version.ts", `CURRENT_COOL_WORKFLOW_VERSION = "${VERSION}"`, checks);
+  checkIncludes("plugins/cool-workflow/src/core/version.ts", "CURRENT_RUN_STATE_SCHEMA_VERSION = 1", checks);
+  checkIncludes("plugins/cool-workflow/src/mcp/server.ts", "CURRENT_COOL_WORKFLOW_VERSION", checks);
+  checkIncludes("plugins/cool-workflow/src/shell/workflow-app-loader.ts", "CURRENT_COOL_WORKFLOW_VERSION", checks);
 
   for (const appId of canonicalApps) {
     checkJson(`plugins/cool-workflow/apps/${appId}/app.json`, "version", VERSION, checks);
@@ -90,9 +90,9 @@ function main() {
   checkIncludes("plugins/cool-workflow/test/mcp-app-surface-smoke.js", VERSION, checks);
   checkIncludes("plugins/cool-workflow/test/canonical-workflow-apps-smoke.js", VERSION, checks);
   checkIncludes("plugins/cool-workflow/test/workflow-app-framework-smoke.js", VERSION, checks);
-  checkIncludes("plugins/cool-workflow/dist/version.js", VERSION, checks);
-  checkIncludes("plugins/cool-workflow/dist/mcp-server.js", "CURRENT_COOL_WORKFLOW_VERSION", checks);
-  checkIncludes("plugins/cool-workflow/dist/workflow-app-framework.js", "CURRENT_COOL_WORKFLOW_VERSION", checks);
+  checkIncludes("plugins/cool-workflow/dist/core/version.js", VERSION, checks);
+  checkIncludes("plugins/cool-workflow/dist/mcp/server.js", "CURRENT_COOL_WORKFLOW_VERSION", checks);
+  checkIncludes("plugins/cool-workflow/dist/shell/workflow-app-loader.js", "CURRENT_COOL_WORKFLOW_VERSION", checks);
 
   // The npm package README (plugins/cool-workflow/README.md) is GENERATED from the GitHub
   // README.md (scripts/sync-readme.js) and conveys the version via the live npm/release shields
@@ -160,37 +160,37 @@ function main() {
   checkIncludes("plugins/cool-workflow/docs/run-retention-reclamation.7.md", VERSION, checks);
   checkIncludes("plugins/cool-workflow/docs/index.md", "run-retention-reclamation.7.md", checks);
   checkIncludes("plugins/cool-workflow/test/run-retention-reclamation-smoke.js", "run-retention-reclamation-smoke", checks);
-  checkIncludes("plugins/cool-workflow/src/capability-registry.ts", "gc.plan", checks);
+  checkIncludes("plugins/cool-workflow/src/core/capability-table.ts", "gc.plan", checks);
   checkIncludes("plugins/cool-workflow/docs/durable-state-and-locking.7.md", "Durable State & Locking", checks);
   checkIncludes("plugins/cool-workflow/docs/durable-state-and-locking.7.md", VERSION, checks);
   checkIncludes("plugins/cool-workflow/docs/index.md", "durable-state-and-locking.7.md", checks);
   checkIncludes("plugins/cool-workflow/test/durable-atomic-write-smoke.js", "durable-atomic-write-smoke", checks);
-  checkIncludes("plugins/cool-workflow/src/state.ts", "withFileLock", checks);
-  checkIncludes("plugins/cool-workflow/src/drive.ts", "driveStep", checks);
-  checkIncludes("plugins/cool-workflow/dist/drive.js", "driveStep", checks);
-  checkIncludes("plugins/cool-workflow/src/capability-registry.ts", "run.drive", checks);
-  checkIncludes("plugins/cool-workflow/src/collaboration.ts", "deriveReviewState", checks);
-  checkIncludes("plugins/cool-workflow/dist/collaboration.js", "deriveReviewState", checks);
-  checkIncludes("plugins/cool-workflow/src/capability-registry.ts", "review.status", checks);
-  checkIncludes("plugins/cool-workflow/src/observability.ts", "deriveMetricsReport", checks);
-  checkIncludes("plugins/cool-workflow/dist/observability.js", "deriveMetricsReport", checks);
-  checkIncludes("plugins/cool-workflow/src/capability-registry.ts", "metrics.show", checks);
+  checkIncludes("plugins/cool-workflow/src/shell/fs-atomic.ts", "withFileLock", checks);
+  checkIncludes("plugins/cool-workflow/src/shell/drive.ts", "driveStep", checks);
+  checkIncludes("plugins/cool-workflow/dist/shell/drive.js", "driveStep", checks);
+  checkIncludes("plugins/cool-workflow/src/core/capability-table.ts", "run.drive", checks);
+  checkIncludes("plugins/cool-workflow/src/shell/collaboration-io.ts", "deriveReviewState", checks);
+  checkIncludes("plugins/cool-workflow/dist/shell/collaboration-io.js", "deriveReviewState", checks);
+  checkIncludes("plugins/cool-workflow/src/core/capability-table.ts", "review.status", checks);
+  checkIncludes("plugins/cool-workflow/src/shell/observability.ts", "deriveMetricsReport", checks);
+  checkIncludes("plugins/cool-workflow/dist/shell/observability.js", "deriveMetricsReport", checks);
+  checkIncludes("plugins/cool-workflow/src/core/capability-table.ts", "metrics.show", checks);
   checkIncludes("plugins/cool-workflow/manifest/pricing.policy.json", "schemaVersion", checks);
-  checkIncludes("plugins/cool-workflow/src/workbench.ts", "buildWorkbenchRunView", checks);
-  checkIncludes("plugins/cool-workflow/dist/workbench.js", "buildWorkbenchRunView", checks);
-  checkIncludes("plugins/cool-workflow/src/capability-registry.ts", "workbench.view", checks);
-  checkIncludes("plugins/cool-workflow/src/execution-backend.ts", "ExecutionBackend", checks);
-  checkIncludes("plugins/cool-workflow/dist/execution-backend.js", "ExecutionBackend", checks);
-  checkIncludes("plugins/cool-workflow/src/capability-registry.ts", "backend.list", checks);
-  checkIncludes("plugins/cool-workflow/src/run-registry.ts", "RunRegistry", checks);
-  checkIncludes("plugins/cool-workflow/dist/run-registry.js", "RunRegistry", checks);
-  checkIncludes("plugins/cool-workflow/src/capability-registry.ts", "registry.refresh", checks);
+  checkIncludes("plugins/cool-workflow/src/shell/workbench.ts", "buildWorkbenchRunView", checks);
+  checkIncludes("plugins/cool-workflow/dist/shell/workbench.js", "buildWorkbenchRunView", checks);
+  checkIncludes("plugins/cool-workflow/src/core/capability-table.ts", "workbench.view", checks);
+  checkIncludes("plugins/cool-workflow/src/shell/execution-backend/registry.ts", "ExecutionBackend", checks);
+  checkIncludes("plugins/cool-workflow/dist/shell/execution-backend/registry.js", "ExecutionBackend", checks);
+  checkIncludes("plugins/cool-workflow/src/core/capability-table.ts", "backend.list", checks);
+  checkIncludes("plugins/cool-workflow/src/shell/run-registry-io.ts", "RunRegistry", checks);
+  checkIncludes("plugins/cool-workflow/dist/shell/run-registry-io.js", "RunRegistry", checks);
+  checkIncludes("plugins/cool-workflow/src/core/capability-table.ts", "registry.refresh", checks);
   checkIncludes("plugins/cool-workflow/package.json", "parity:check", checks);
   checkIncludes("plugins/cool-workflow/scripts/parity-check.js", "buildParityReport", checks);
   checkIncludes("plugins/cool-workflow/test/cli-mcp-parity-smoke.js", "cli-mcp-parity-smoke", checks);
-  checkIncludes("plugins/cool-workflow/src/capability-registry.ts", "CAPABILITY_REGISTRY", checks);
-  checkIncludes("plugins/cool-workflow/src/capability-core.ts", "planSummary", checks);
-  checkIncludes("plugins/cool-workflow/dist/capability-registry.js", "CAPABILITY_REGISTRY", checks);
+  checkIncludes("plugins/cool-workflow/src/core/capability-table.ts", "export const REGISTRY", checks);
+  checkIncludes("plugins/cool-workflow/src/shell/pipeline-cli.ts", "planSummary", checks);
+  checkIncludes("plugins/cool-workflow/dist/core/capability-table.js", "REGISTRY", checks);
   checkIncludes("plugins/cool-workflow/docs/multi-agent-runtime-core.7.md", "Multi-Agent Runtime Core", checks);
   checkIncludes("plugins/cool-workflow/docs/dogfood-one-real-repo.7.md", "Dogfood One Real Repo", checks);
   checkIncludes("plugins/cool-workflow/docs/getting-started.md", "npm run release:check", checks);