cool-workflow 0.1.98 → 0.2.1

package/scripts/agents/agent-adapter-core.js

@@ -18,7 +18,7 @@ cw:result block that EXACTLY follows this schema:
   "findings": [
     {
       "id": "unique-kebab-id",
-      "title": "short risk title",
+      "title": "short finding title",
       "severity": "P0",
       "classification": "real",
       "evidence": ["path/to/file.ts:42"]
@@ -471,6 +471,25 @@ function persistStderr(resultPath, text) {
   }
 }
 
+// Build the failure-path diagnostic string for a non-zero exit. Real OS-level
+// stderr wins when present (the common case: a crash, a killed process, a
+// vendor CLI that DOES write to stderr) — byte-identical to before this
+// helper existed. When stderr is EMPTY, fall back to whatever partial/
+// structured text the wrapper already parsed from stdout before the child
+// died (a stream-json `result` event with is_error:true is how claude
+// reports terminal errors like an auth failure — that text was being parsed
+// and then silently thrown away). If there is no partial text either, say so
+// plainly instead of just repeating the bare exit code. Never throws; always
+// returns a non-empty string.
+function buildFailureDetail({ label, code, childStderr, partialText }) {
+  const stderrText = String(childStderr || "").trim();
+  if (stderrText) return stderrText;
+  const partial = String(partialText || "").trim();
+  const codeText = `${label} exited ${code === null ? "(timeout/killed)" : code}`;
+  if (partial) return `${codeText} — ${label} stdout (no stderr) said: ${partial}`;
+  return codeText;
+}
+
 module.exports = {
   RESULT_CONTRACT,
   buildPrompt,
@@ -485,5 +504,6 @@ module.exports = {
   flushJsonLines,
   writeResult,
   emitReport,
-  persistStderr // save a failed agent's stderr to <workerDir>/logs/agent-stderr.log (shared by all wrappers)
+  persistStderr, // save a failed agent's stderr to <workerDir>/logs/agent-stderr.log (shared by all wrappers)
+  buildFailureDetail // fold in parsed partial stdout text when real stderr is empty (shared by all wrappers)
 };

package/scripts/agents/claude-p-agent.js

@@ -34,7 +34,7 @@ const { spawn, spawnSync } = require("node:child_process");
 // wrappers instead of carrying a private copy. A drifted inline copy (ASCII
 // hyphens silently became em-dashes here) meant claude was sent a different
 // instruction text than the other providers for the same contract.
-const { buildPrompt, createRenderer, persistStderr, toolLabel, summarizeToolResult } = require("./agent-adapter-core");
+const { buildPrompt, createRenderer, persistStderr, toolLabel, summarizeToolResult, buildFailureDetail } = require("./agent-adapter-core");
 
 const inputPath = process.argv[2];
 const resultPath = process.argv[3];
@@ -179,9 +179,14 @@ child.on("close", (code) => {
   render.finishLive(); // stop the spinner + restore the cursor BEFORE any further output
   render.writeTranscript(transcriptPath); // full narration + tool I/O always saved
   if (code !== 0) {
-    const detail = childStderr.trim() || `claude exited ${code === null ? "(timeout/killed)" : code}`;
+    const stderrText = childStderr.trim();
+    // childStderr is the OS-level stream; claude's real failure reason (auth,
+    // rate limit, relay error) is often reported as a stream-json `result`
+    // event on STDOUT instead, already parsed into `resultText` above — fold
+    // it in here so a silent-stderr failure still leaves a readable reason.
+    const detail = buildFailureDetail({ label: "claude", code, childStderr: stderrText, partialText: resultText });
     persistStderr(resultPath, detail);
-    if (childStderr.trim()) process.stderr.write(`${childStderr.trim()}\n`);
+    if (stderrText) process.stderr.write(`${stderrText}\n`);
     process.stderr.write(`claude exited ${code === null ? "(timeout/killed)" : code}\n`);
     process.exit(code === null ? 1 : code);
   }

package/scripts/agents/cw-attest-wrap.js

@@ -12,7 +12,7 @@
 //
 // It signs the EXACT same canonical payload CW verifies — {usage, runId, taskId,
 // promptDigest} — sharing the canonicalization with the verifier via
-// dist/telemetry-attestation.js, so signer and verifier can never drift.
+// dist/core/trust/telemetry-attestation.js, so signer and verifier can never drift.
 //
 // Usage (wrap any agent that prints a {model, usage} JSON report on stdout):
 //   node cw-attest-wrap.js --manifest {{manifest}} -- <agent-cmd> [agent-args...]
@@ -32,7 +32,7 @@ const crypto = require("node:crypto");
 const path = require("node:path");
 const { spawnSync } = require("node:child_process");
 
-const ta = require(path.resolve(__dirname, "..", "..", "dist", "telemetry-attestation.js"));
+const ta = require(path.resolve(__dirname, "..", "..", "dist", "core", "trust", "telemetry-attestation.js"));
 
 function fail(message) {
   process.stderr.write(`cw-attest-wrap: ${message}\n`);

package/scripts/agents/gemini-agent.js

@@ -17,6 +17,7 @@
 const path = require("node:path");
 const { spawn } = require("node:child_process");
 const {
+  buildFailureDetail,
   buildPrompt,
   createRenderer,
   emitReport,
@@ -94,7 +95,10 @@ child.on("close", (code) => {
   render.finishLive();
   render.writeTranscript(transcriptPath);
   if (code !== 0) {
-    const detail = childStderr.trim() || `gemini exited ${code === null ? "(timeout/killed)" : code}`;
+    // gemini's real failure reason is often only in the NDJSON text/result
+    // fragments already parsed into `state`, not in raw OS-level stderr.
+    const partial = state.finalResult || state.textFragments.join("\n\n");
+    const detail = buildFailureDetail({ label: "gemini", code, childStderr: childStderr.trim(), partialText: partial });
     persistStderr(resultPath, detail);
     process.stderr.write(`${detail}\n`);
     process.exit(code === null ? 1 : code);

package/scripts/agents/opencode-agent.js

@@ -22,6 +22,7 @@
 const path = require("node:path");
 const { spawn } = require("node:child_process");
 const {
+  buildFailureDetail,
   buildPrompt,
   createRenderer,
   emitReport,
@@ -147,7 +148,10 @@ child.on("close", (code) => {
   render.finishLive();
   render.writeTranscript(transcriptPath);
   if (code !== 0) {
-    const detail = childStderr.trim() || `opencode exited ${code === null ? "(timeout/killed)" : code}`;
+    // opencode's real failure reason is often only in the JSONL text/result
+    // fragments already parsed into `state`, not in raw OS-level stderr.
+    const partial = state.finalResult || state.lastMessageText || state.textFragments.join("\n\n");
+    const detail = buildFailureDetail({ label: "opencode", code, childStderr: childStderr.trim(), partialText: partial });
     persistStderr(resultPath, detail);
     process.stderr.write(`${detail}\n`);
     process.exit(code === null ? 1 : code);

package/scripts/bump-version.js

@@ -89,8 +89,9 @@ function main() {
     note("server.json");
   }
 
-  // 3. src/version.ts runtime constant
-  const versionTs = path.join(pluginRoot, "src", "version.ts");
+  // 3. src/core/version.ts runtime constant (v2 moved it from the old flat
+  //    src/version.ts into the core state layer)
+  const versionTs = path.join(pluginRoot, "src", "core", "version.ts");
   const vtsText = fs.readFileSync(versionTs, "utf8");
   const vtsNext = vtsText.replace(
     /(CURRENT_COOL_WORKFLOW_VERSION\s*=\s*)"[^"]*"/,
@@ -98,7 +99,7 @@ function main() {
   );
   if (vtsNext !== vtsText) {
     fs.writeFileSync(versionTs, vtsNext);
-    note("src/version.ts");
+    note("src/core/version.ts");
   }
 
   // 4. manifest/plugin.manifest.json (identity.version) — gen:manifests then

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.98",
+      "Cool Workflow v0.2.1",
       "--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.98");
+    assert.equal(summary.version, "0.2.1");
 
     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.98");
+    assert.equal(shown.app.version, "0.2.1");
     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.98");
+    assert.equal(state.workflow.app.version, "0.2.1");
     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-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.98";
+const TARGET_VERSION = "0.2.1";
 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.98");
+    assert.equal(appValidation.summary.version, "0.2.1");
 
     const plan = runJson(
       [
@@ -42,7 +42,7 @@ function main() {
         "--repo",
         tmp,
         "--question",
-        "Prove the deterministic v0.1.98 end-to-end golden path."
+        "Prove the deterministic v0.2.1 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.98");
+    assert.equal(state.workflow.app.version, "0.2.1");
     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\.98/);
+    assert.match(report, /Workflow App: end-to-end-golden-path@0\.2\.1/);
     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") },

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 = [];