cool-workflow 0.1.78

package/scripts/release-gate.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# release-gate.sh — deterministic release checks for cool-workflow.
+# Pass = writes .cw-release/gate-<HEAD-sha>.ok
+# This script encodes everything that does NOT need LLM judgment.
+set -euo pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+cd "$REPO_ROOT"
+SHA="$(git rev-parse HEAD)"
+# Resolve the PREVIOUS release tag. When this script runs from CI on a tag push
+# (.github/workflows/release-gate.yml), HEAD already carries the tag being
+# released, so a plain `git describe` returns *that* tag and the diff range
+# collapses to empty — making substance/evidence/cadence false-fail every real
+# release. Exclude any tag that points at HEAD so we always compare against the
+# prior release (the parent commit's nearest tag).
+HEAD_TAGS="$(git tag --points-at HEAD 2>/dev/null || echo "")"
+PREV_TAG="$(git describe --tags --abbrev=0 2>/dev/null || echo "")"
+if [[ -n "$HEAD_TAGS" ]] && printf '%s\n' "$HEAD_TAGS" | grep -qxF "$PREV_TAG"; then
+  PREV_TAG="$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")"
+fi
+MARKER_DIR="$REPO_ROOT/.cw-release"
+mkdir -p "$MARKER_DIR"
+FAIL=0
+
+say() { printf '%s\n' "$*"; }
+fail() { say "GATE FAIL: $*"; FAIL=1; }
+
+# --- 1. Build & tests (run, don't trust pasted output) -----------------
+say "[1/6] build"
+npm run --prefix plugins/cool-workflow build >/dev/null 2>&1 || fail "build failed"
+
+say "[2/6] tests"
+npm test --prefix plugins/cool-workflow >/dev/null 2>&1 || fail "tests failed"
+
+if [[ -n "$PREV_TAG" ]]; then
+  RANGE="$PREV_TAG..HEAD"
+
+  # --- 2. Substance: changes must exist outside src/types/ and dist/ ---
+  # The spec (AGENTS.md / reviewer-agent.md Gate 1) is "at least one changed
+  # file outside src/types/ and dist/" — ANY such file (src, scripts, docs,
+  # workflows, tests). Count every changed path that is not under those two
+  # generated/declaration-only trees; declared-but-unread spec accretion is the
+  # reviewer agent's deeper judgment call, not this deterministic floor.
+  say "[3/6] substance (diff outside src/types/ and dist/)"
+  SUBSTANCE=$(git diff --name-only "$RANGE" \
+    | grep -cvE '^plugins/cool-workflow/(src/types/|dist/)' || true)
+  [[ "$SUBSTANCE" -gt 0 ]] || fail "only types/dist changed since $PREV_TAG (spec accretion)"
+
+  # --- 3. Test evidence: test files must have changed ------------------
+  say "[4/6] test evidence"
+  TESTS_CHANGED=$(git diff --name-only "$RANGE" | grep -cE '\.(test|spec)\.|/tests?/' || true)
+  [[ "$TESTS_CHANGED" -gt 0 ]] || fail "zero test changes since $PREV_TAG"
+
+  # --- 4. Cadence: >=4 cycles logged OR >=24h since previous tag -------
+  say "[5/6] cadence"
+  CYCLES=0
+  if [[ -f ITERATION_LOG.md && -n "$PREV_TAG" ]]; then
+    CYCLES=$(git diff "$RANGE" -- ITERATION_LOG.md | grep -c '^+.*|' || true)
+  fi
+  PREV_TS=$(git log -1 --format=%ct "$PREV_TAG")
+  NOW_TS=$(date +%s)
+  HOURS=$(( (NOW_TS - PREV_TS) / 3600 ))
+  if [[ "$CYCLES" -lt 4 && "$HOURS" -lt 24 ]]; then
+    fail "cadence: only $CYCLES cycles logged and ${HOURS}h since $PREV_TAG (need >=4 cycles or >=24h)"
+  fi
+else
+  say "[3-5/6] no previous tag; substance/evidence/cadence checks skipped"
+fi
+
+# --- 5. Branch naming: forbid version-number branches -------------------
+say "[6/6] branch naming"
+BRANCH="$(git rev-parse --abbrev-ref HEAD)"
+if [[ "$BRANCH" =~ ^feat/(batch-)?v?[0-9]+ ]]; then
+  fail "branch '$BRANCH' is version-number-driven; name the capability instead"
+fi
+
+# --- Verdict ------------------------------------------------------------
+if [[ "$FAIL" -ne 0 ]]; then
+  rm -f "$MARKER_DIR/gate-$SHA.ok"
+  say "RELEASE GATE: REJECTED ($SHA)"
+  exit 1
+fi
+
+date -u +"%Y-%m-%dT%H:%M:%SZ" > "$MARKER_DIR/gate-$SHA.ok"
+say "RELEASE GATE: PASSED ($SHA) — next step: release-reviewer agent must record APPROVED"

package/scripts/sync-project-index.js

@@ -0,0 +1,387 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const pluginRoot = path.resolve(__dirname, "..");
+const repoRoot = path.resolve(pluginRoot, "..", "..");
+const packageJson = readJson(path.join(pluginRoot, "package.json"));
+const repoRemote = git(["config", "--get", "remote.origin.url"]).trim();
+const repoUrl = normalizeGitRemote(repoRemote) || "https://github.com/coo1white/cool-workflow";
+const wikiDir = process.env.CW_GITHUB_WIKI_DIR || path.resolve(repoRoot, "..", "cool-workflow.wiki");
+const obsidianVault = process.env.CW_OBSIDIAN_VAULT || detectObsidianVault();
+const obsidianDir = obsidianVault ? path.join(obsidianVault, "Cool Workflow") : "";
+const generatedDate = new Date().toISOString().slice(0, 10);
+
+// --check  : verify the committed docs/project-index.md still matches a fresh
+//            scan of the source tree, write nothing, exit non-zero on drift.
+// --repo-only : write ONLY the committed repo doc; skip the optional personal
+//            sync targets (Obsidian vault, GitHub wiki working tree).
+// CW_PROJECT_INDEX_PATH : override the doc path that --check compares against
+//            (used by the smoke to point at throwaway fixtures).
+const CHECK = process.argv.includes("--check");
+const REPO_ONLY = process.argv.includes("--repo-only");
+const indexPathOverride = process.env.CW_PROJECT_INDEX_PATH || "";
+
+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."]
+  ],
+  "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."]
+  ],
+  "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."]
+  ],
+  "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."]
+  ],
+  "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."]
+  ]
+};
+
+function main() {
+  const apps = listApps();
+  const docs = listMarkdown(path.join(pluginRoot, "docs"));
+  const sourceFiles = listFiles(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 };
+
+  // Fail closed if the hand-maintained moduleCatalog references a src module that
+  // no longer exists. Without this the generator emits a dead `../src/<file>` link
+  // and --check would bless it: the catalog region renders identically from the
+  // (stale) constant on both sides, so it is invisible to the diff. This closes
+  // the STRUCTURAL half of the catalog blind spot. Responsibility-PROSE staleness
+  // (a cataloged file whose contents changed) is not auto-derivable from source
+  // and remains out of scope by design — see the PR notes.
+  const catalogedFiles = Object.values(moduleCatalog).flat().map(([file]) => file);
+  const missingCataloged = catalogedFiles.filter((file) => !sourceFiles.includes(file));
+  if (missingCataloged.length > 0) {
+    process.stderr.write(
+      `project-index FAILED: moduleCatalog references src module(s) that no longer exist: ${missingCataloged.join(", ")}.\n` +
+      `A rename/delete must be reflected in moduleCatalog (scripts/sync-project-index.js).\n`
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const repoDoc = indexPathOverride
+    ? path.resolve(indexPathOverride)
+    : path.join(pluginRoot, "docs", "project-index.md");
+  const rendered = renderIndex("repo", context);
+
+  // Gate mode: compare the committed doc against a fresh render and exit
+  // non-zero on drift. Writes nothing and never touches the personal targets.
+  // Deliberately reads the WORKING TREE (not git HEAD like version-sync-check.js):
+  // this gate is meant to catch "you changed source but forgot to regenerate the
+  // index" BEFORE you commit. CI checks out a clean HEAD, so working tree == HEAD
+  // there; there is no concurrent-mutation race here (unlike the release-cut flow).
+  if (CHECK) {
+    checkInSync(repoDoc, rendered);
+    return;
+  }
+
+  const outputs = [];
+  writeFile(repoDoc, rendered);
+  outputs.push(repoDoc);
+
+  if (!REPO_ONLY && obsidianDir) {
+    fs.mkdirSync(obsidianDir, { recursive: true });
+    const obsidianDoc = path.join(obsidianDir, "CW Project Index.md");
+    writeFile(obsidianDoc, renderIndex("obsidian", context));
+    ensureLine(
+      path.join(obsidianDir, "Cool Workflow - MOC.md"),
+      "- [[CW Project Index]]",
+      "## 核心笔记"
+    );
+    outputs.push(obsidianDoc);
+  }
+
+  if (!REPO_ONLY && fs.existsSync(wikiDir)) {
+    const wikiDoc = path.join(wikiDir, "Project-Index.md");
+    writeFile(wikiDoc, renderIndex("wiki", context));
+    ensureLine(path.join(wikiDir, "_Sidebar.md"), "- [[Project Index]]", "# Cool Workflow");
+    outputs.push(wikiDoc);
+  }
+
+  process.stdout.write(`${JSON.stringify({
+    ok: true,
+    generatedDate,
+    package: packageJson.name,
+    version: packageJson.version,
+    sourceModules: sourceFiles.length,
+    workflowApps: apps.length,
+    docs: docs.length,
+    smokeTests: smokeTests.length,
+    outputs: outputs.map((file) => path.relative(repoRoot, file))
+  }, null, 2)}\n`);
+}
+
+function listApps() {
+  const appsDir = path.join(pluginRoot, "apps");
+  return fs.readdirSync(appsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => {
+      const appDir = path.join(appsDir, entry.name);
+      const manifest = readJson(path.join(appDir, "app.json"));
+      return {
+        id: manifest.id,
+        title: manifest.title,
+        summary: manifest.summary,
+        version: manifest.version,
+        inputs: (manifest.inputs || []).map((input) => input.name),
+        sandboxProfiles: manifest.sandboxProfiles || [],
+        canonical: Boolean(manifest.metadata && manifest.metadata.canonical),
+        example: Boolean(manifest.metadata && manifest.metadata.example),
+        manifestPath: path.relative(pluginRoot, path.join(appDir, "app.json")),
+        workflowPath: path.relative(pluginRoot, path.join(appDir, manifest.workflow && manifest.workflow.entrypoint || "workflow.js"))
+      };
+    })
+    .sort((a, b) => a.id.localeCompare(b.id));
+}
+
+function listMarkdown(dir) {
+  return fs.readdirSync(dir)
+    .filter((file) => file.endsWith(".md"))
+    .sort()
+    .map((file) => {
+      const absolute = path.join(dir, file);
+      const text = fs.readFileSync(absolute, "utf8");
+      const title = (text.match(/^#\s+(.+)$/m) || [null, file])[1];
+      return { file, title };
+    });
+}
+
+function listFiles(dir, extension) {
+  return fs.readdirSync(dir)
+    .filter((file) => file.endsWith(extension))
+    .sort();
+}
+
+function renderIndex(target, context) {
+  const link = linkFactory(target);
+  const lines = [];
+  lines.push("# Cool Workflow Project Index");
+  lines.push("");
+  lines.push(`Generated from the current repository code on ${generatedDate} by \`npm run sync:project-index\`.`);
+  lines.push("");
+  lines.push("## Snapshot");
+  lines.push("");
+  lines.push(`- Package: \`${packageJson.name}\``);
+  lines.push(`- Version: \`${packageJson.version}\``);
+  lines.push(`- Source modules: \`${context.sourceFiles.length}\``);
+  lines.push(`- Workflow apps: \`${context.apps.length}\``);
+  lines.push(`- Docs: \`${context.docs.length}\``);
+  lines.push(`- Smoke tests: \`${context.smokeTests.length}\``);
+  lines.push(`- Repository: ${repoUrl}`);
+  lines.push("");
+  lines.push("## Architecture");
+  lines.push("");
+  lines.push("```text");
+  lines.push("workflow app -> runner -> dispatch -> isolated workers");
+  lines.push("    -> results -> feedback/candidates -> verifier gate");
+  lines.push("    -> commit/checkpoint -> report/trust audit");
+  lines.push("");
+  lines.push("multi-agent host -> topology -> blackboard/coordinator");
+  lines.push("    -> fanout/fanin -> candidate score/select");
+  lines.push("```");
+  lines.push("");
+  lines.push("## Source Map");
+  lines.push("");
+  for (const [area, modules] of Object.entries(moduleCatalog)) {
+    lines.push(`### ${area}`);
+    lines.push("");
+    lines.push("| Module | Responsibility |");
+    lines.push("| --- | --- |");
+    for (const [file, responsibility] of modules) {
+      lines.push(`| ${link(`src/${file}`, file)} | ${responsibility} |`);
+    }
+    lines.push("");
+  }
+  const cataloged = new Set(Object.values(moduleCatalog).flat().map(([file]) => file));
+  const uncataloged = context.sourceFiles.filter((file) => !cataloged.has(file));
+  if (uncataloged.length > 0) {
+    lines.push("### Other Source Modules");
+    lines.push("");
+    for (const file of uncataloged) lines.push(`- ${link(`src/${file}`, file)}`);
+    lines.push("");
+  }
+  lines.push("## Workflow Apps");
+  lines.push("");
+  lines.push("| App | Type | Inputs | Sandbox | Source |");
+  lines.push("| --- | --- | --- | --- | --- |");
+  for (const app of context.apps) {
+    const type = app.canonical ? "canonical" : app.example ? "example" : "userland";
+    lines.push(`| \`${app.id}\` - ${app.summary} | ${type} | ${inlineList(app.inputs)} | ${inlineList(app.sandboxProfiles)} | ${link(app.manifestPath, "manifest")} / ${link(app.workflowPath, "workflow")} |`);
+  }
+  lines.push("");
+  lines.push("## Documentation Map");
+  lines.push("");
+  for (const doc of context.docs) {
+    lines.push(`- ${link(`docs/${doc.file}`, doc.title)}`);
+  }
+  lines.push("");
+  lines.push("## Test Surface");
+  lines.push("");
+  lines.push("Smoke tests mirror the public contracts. The high-signal suites are:");
+  lines.push("");
+  for (const file of context.smokeTests) lines.push(`- ${link(`test/${file}`, file)}`);
+  lines.push("");
+  lines.push("## Sync Targets");
+  lines.push("");
+  // Keep absolute / personal local paths OUT of the committed doc: describe the
+  // optional sync targets generically. The actual destinations are resolved at
+  // run time from CW_OBSIDIAN_VAULT / CW_GITHUB_WIKI_DIR (see top of this file).
+  lines.push(`- Repository docs: ${link("docs/project-index.md", "docs/project-index.md")}`);
+  lines.push("- Obsidian vault (optional): set `CW_OBSIDIAN_VAULT` to your local vault path.");
+  lines.push("- GitHub Wiki: the `cool-workflow.wiki` working tree (override with `CW_GITHUB_WIKI_DIR`).");
+  lines.push("");
+  lines.push("## Maintenance");
+  lines.push("");
+  lines.push("Run this after changing source modules, workflow app manifests, public docs, or smoke test coverage:");
+  lines.push("");
+  lines.push("```bash");
+  lines.push("cd plugins/cool-workflow");
+  lines.push("npm run sync:project-index");
+  lines.push("```");
+  lines.push("");
+  lines.push("Then review the Obsidian page and GitHub Wiki working tree before publishing wiki changes.");
+  lines.push("");
+  return lines.join("\n");
+}
+
+function linkFactory(target) {
+  if (target === "repo") {
+    return (relativePath, label) => `[${label}](${relativeLinkFromDocs(relativePath)})`;
+  }
+  if (target === "wiki") {
+    return (relativePath, label) => `[${label}](${repoUrl}/blob/main/plugins/cool-workflow/${relativePath})`;
+  }
+  return (relativePath, label) => `[${label}](${path.join(pluginRoot, relativePath)})`;
+}
+
+function relativeLinkFromDocs(relativePath) {
+  if (relativePath.startsWith("docs/")) return relativePath.slice("docs/".length);
+  return `../${relativePath}`;
+}
+
+function inlineList(values) {
+  if (!values || values.length === 0) return "-";
+  return values.map((value) => `\`${value}\``).join(", ");
+}
+
+function ensureLine(file, line, afterHeading) {
+  if (!fs.existsSync(file)) return;
+  const text = fs.readFileSync(file, "utf8");
+  if (text.includes(line)) return;
+  const lines = text.split(/\r?\n/);
+  const index = lines.findIndex((entry) => entry.trim() === afterHeading);
+  if (index === -1) {
+    lines.push("", line);
+  } else {
+    lines.splice(index + 1, 0, line);
+  }
+  writeFile(file, lines.join("\n").replace(/\n{3,}/g, "\n\n"));
+}
+
+function detectObsidianVault() {
+  const candidate = path.join(process.env.HOME || "", "Documents", "Nick");
+  return fs.existsSync(path.join(candidate, ".obsidian")) ? candidate : "";
+}
+
+function readJson(file) {
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+function writeFile(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, text, "utf8");
+}
+
+function git(args) {
+  const result = spawnSync("git", args, { cwd: repoRoot, encoding: "utf8" });
+  return result.status === 0 ? result.stdout : "";
+}
+
+function normalizeGitRemote(remote) {
+  if (!remote) return "";
+  if (remote.endsWith(".git")) remote = remote.slice(0, -4);
+  const sshMatch = remote.match(/^git@github\.com:(.+)$/);
+  if (sshMatch) return `https://github.com/${sshMatch[1]}`;
+  return remote;
+}
+
+function normalizeForCompare(text) {
+  // Strip ONLY the values derived from the runtime ENVIRONMENT (not the source
+  // tree), so the gate compares purely source-derived content — it can neither
+  // false-RED across machines/forks nor false-GREEN by over-normalizing. Mirrors
+  // the parity payload-identity rule: normalize now/env-derived fields, nothing
+  // else. Exactly two such fields exist in the rendered index:
+  //   1. the generated date ("Generated on <date>") — changes every day;
+  //   2. the Repository URL — derived from `git remote get-url origin`, so it
+  //      differs on every fork/mirror clone of an otherwise in-sync tree.
+  // The Snapshot COUNTS are source-derived and MUST NOT be normalized — a wrong
+  // count is exactly the drift this gate exists to catch.
+  return text
+    .replace(/\r\n/g, "\n")
+    .replace(
+      /(Generated from the current repository code on )\d{4}-\d{2}-\d{2}( by)/,
+      "$1<DATE>$2"
+    )
+    .replace(/^(- Repository: ).*$/m, "$1<REPO>");
+}
+
+function checkInSync(repoDoc, rendered) {
+  const rel = path.relative(repoRoot, repoDoc);
+  if (!fs.existsSync(repoDoc)) {
+    process.stderr.write(`project-index check FAILED: ${rel} does not exist.\nRun: (cd plugins/cool-workflow && npm run sync:project-index)\n`);
+    process.exitCode = 1;
+    return;
+  }
+  const committed = normalizeForCompare(fs.readFileSync(repoDoc, "utf8"));
+  const fresh = normalizeForCompare(rendered);
+  if (committed === fresh) {
+    process.stdout.write(`${JSON.stringify({ ok: true, check: true, version: packageJson.version, doc: rel }, null, 2)}\n`);
+    return;
+  }
+  const a = committed.split("\n");
+  const b = fresh.split("\n");
+  let i = 0;
+  while (i < a.length && i < b.length && a[i] === b[i]) i++;
+  process.stderr.write(
+    `project-index check FAILED: ${rel} is stale (does not match a fresh source scan).\n` +
+    `First difference at line ${i + 1}:\n` +
+    `  committed: ${JSON.stringify(a[i] ?? "<missing>")}\n` +
+    `  expected:  ${JSON.stringify(b[i] ?? "<missing>")}\n` +
+    `Regenerate with: (cd plugins/cool-workflow && npm run sync:project-index)\n`
+  );
+  process.exitCode = 1;
+}
+
+main();

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

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+// validate-run-state-schema.js — fail-closed build gate for ABI consistency.
+//
+// BSD discipline (mechanism, not policy):
+//  - Extracts REQUIRED_TOP_LEVEL_KEYS from the compiled run-state-schema module.
+//  - Parses the TypeScript source of WorkflowRun to extract interface keys.
+//  - Cross-checks: every required (non-optional) key in the type MUST appear
+//    in the schema. Every optional key in the schema MUST match the type.
+//  - FAIL CLOSED on any mismatch — this gates the release.
+//
+// From v0.1.53: prevents silent three-point drift between WorkflowRun,
+// normalizeRunState, and validateMigratedRunState.
+
+"use strict";
+
+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");
+
+function main() {
+  const errors = [];
+
+  // ---- 1. Extract WorkflowRun keys from the TypeScript interface source ----
+  const typeSource = fs.readFileSync(TYPES_FILE, "utf8");
+  const runKeys = extractInterfaceKeys(typeSource, "WorkflowRun");
+  if (runKeys.size === 0) {
+    console.error("validate-run-state-schema: FATAL — could not extract WorkflowRun keys from types/run.ts");
+    process.exit(1);
+  }
+
+  // ---- 2. Load the schema module (compiled dist) --------------------------
+  let schema;
+  try {
+    schema = require(SCHEMA_MODULE);
+  } catch (e) {
+    console.error(`validate-run-state-schema: FATAL — cannot load ${SCHEMA_MODULE}. Run 'npm run build' first.`);
+    process.exit(1);
+  }
+
+  const requiredKeys = new Set(schema.REQUIRED_TOP_LEVEL_KEYS || []);
+  const optionalKeys = new Set(schema.OPTIONAL_TOP_LEVEL_KEYS || []);
+
+  // ---- 3. Cross-check: every type key must be either required or optional ----
+  for (const key of runKeys) {
+    if (requiredKeys.has(key)) continue;
+    if (optionalKeys.has(key)) continue;
+    errors.push(
+      `Drift: WorkflowRun key "${key}" is NOT in REQUIRED_TOP_LEVEL_KEYS or OPTIONAL_TOP_LEVEL_KEYS in run-state-schema.ts. ` +
+      `Add it to the appropriate list.`
+    );
+  }
+
+  // ---- 4. Reverse check: every declared key must exist in the type ---------
+  for (const key of requiredKeys) {
+    if (!runKeys.has(key)) {
+      errors.push(`Drift: REQUIRED_TOP_LEVEL_KEYS contains "${key}" but it is not in WorkflowRun.`);
+    }
+  }
+  for (const key of optionalKeys) {
+    if (!runKeys.has(key)) {
+      errors.push(`Drift: OPTIONAL_TOP_LEVEL_KEYS contains "${key}" but it is not in WorkflowRun.`);
+    }
+  }
+
+  // ---- Report ------------------------------------------------------------
+  if (errors.length) {
+    console.error("validate-run-state-schema: FAIL CLOSED — schema drift detected.");
+    for (const e of errors) console.error(`  ${e}`);
+    console.error(
+      `\nFix: update REQUIRED_TOP_LEVEL_KEYS and/or OPTIONAL_TOP_LEVEL_KEYS in ` +
+      `src/run-state-schema.ts, then update normalizeRunState() and validateMigratedRunState() ` +
+      `in src/state-migrations.ts to handle any new required fields.`
+    );
+    process.exit(1);
+  }
+
+  const total = requiredKeys.size + optionalKeys.size;
+  console.error(
+    `validate-run-state-schema: ok — ${runKeys.size} WorkflowRun keys accounted for ` +
+    `(${requiredKeys.size} required + ${optionalKeys.size} optional = ${total})`
+  );
+}
+
+/**
+ * Extract top-level keys from a TypeScript interface definition.
+ * Uses brace-depth tracking to skip keys inside nested object types.
+ */
+function extractInterfaceKeys(source, interfaceName) {
+  const startIdx = source.indexOf(`export interface ${interfaceName} {`);
+  if (startIdx < 0) return new Set();
+
+  const braceStart = source.indexOf("{", startIdx);
+  let depth = 0;
+  let endIdx = -1;
+  for (let i = braceStart; i < source.length; i++) {
+    if (source[i] === "{") depth++;
+    if (source[i] === "}") depth--;
+    if (depth === 0) { endIdx = i; break; }
+  }
+  if (endIdx < 0) return new Set();
+
+  const body = source.slice(braceStart + 1, endIdx);
+  const keys = new Set();
+  let braceDepth = 0;
+
+  for (const line of body.split("\n")) {
+    const m = line.match(/^\s*(\w+)\??\s*:/);
+    if (m) {
+      // Key is top-level only when current brace depth is 0
+      if (braceDepth === 0) keys.add(m[1]);
+    }
+    // Update brace depth from this line's braces
+    for (const ch of line) {
+      if (ch === "{") braceDepth++;
+      if (ch === "}") braceDepth--;
+    }
+    if (braceDepth < 0) braceDepth = 0;
+  }
+
+  return keys;
+}
+
+main();

package/scripts/verify-container-selfref.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+"use strict";
+
+// verify-container-selfref — the v0.1.34 self-referential acceptance check.
+//
+// Runs CW's own `node dist/cli.js list` through the `node` backend AND the
+// `container` backend, and asserts result + evidence are byte-IDENTICAL after
+// provenance is excluded (backendId/handle/attestation differ by design). This is
+// the bar that proves a delegated run is backend-agnostic.
+//
+// Requires a RUNNING container daemon and a pullable node image. Not part of
+// release:check (CI has no daemon); run it manually before tagging v0.1.34.
+//
+//   node scripts/verify-container-selfref.js
+//   CW_CONTAINER_IMAGE=node:22-slim node scripts/verify-container-selfref.js
+//
+// Exit: 0 PASS · 1 FAIL (evidence differs) · 2 node backend did not complete ·
+//       3 SKIP (container refused — daemon down / image not pullable).
+
+const path = require("node:path");
+
+const pluginRoot = path.resolve(__dirname, "..");
+const { runBackend } = require(path.join(pluginRoot, "dist/execution-backend.js"));
+const { showBundledSandboxProfile, sandboxContextForValidation } = require(path.join(pluginRoot, "dist/sandbox-profile.js"));
+
+const image = (process.env.CW_CONTAINER_IMAGE || "node:lts-slim").trim();
+const cli = path.join(pluginRoot, "dist", "cli.js");
+const ctx = sandboxContextForValidation(pluginRoot);
+const policy = showBundledSandboxProfile("default", ctx);
+
+const common = { schemaVersion: 1, command: "node", args: [cli, "list"], cwd: pluginRoot, sandboxPolicy: policy, label: "cw-self-verify" };
+const nodeEnv = runBackend({ ...common, backendId: "node" });
+const containerEnv = runBackend({ ...common, backendId: "container", delegation: { image } });
+
+const line = (label, e) => `  ${label.padEnd(9)} status=${e.status} backend=${e.provenance.backendId} evidence=${JSON.stringify(e.evidence)}`;
+process.stdout.write(`verify-container-selfref (image: ${image})\n${line("node", nodeEnv)}\n${line("container", containerEnv)}\n`);
+
+if (nodeEnv.status !== "completed") {
+  process.stderr.write(`\n✗ node backend did not complete (${nodeEnv.status}) — cannot compare.\n`);
+  process.exit(2);
+}
+if (containerEnv.status === "refused") {
+  process.stderr.write(
+    `\n⚠ SKIP — container refused (${containerEnv.evidence[0]}).\n` +
+      `  ${containerEnv.result.summary}\n` +
+      `  Start the container daemon and ensure the image is pullable (e.g. \`docker pull ${image}\`), then re-run.\n`
+  );
+  process.exit(3);
+}
+
+const sameResult = JSON.stringify(nodeEnv.result) === JSON.stringify(containerEnv.result);
+const sameEvidence = JSON.stringify(nodeEnv.evidence) === JSON.stringify(containerEnv.evidence);
+if (containerEnv.status === "completed" && sameResult && sameEvidence) {
+  process.stdout.write("\n✓ PASS — container result + evidence are byte-identical to node (provenance differs, as designed).\n");
+  process.exit(0);
+}
+
+process.stderr.write(
+  `\n✗ FAIL — container output differs from node (status=${containerEnv.status}):\n` +
+    `  node      evidence: ${JSON.stringify(nodeEnv.evidence)}\n` +
+    `  container evidence: ${JSON.stringify(containerEnv.evidence)}\n` +
+    `  (a node-version difference in the image can change stdout; pin CW_CONTAINER_IMAGE to a matching node.)\n`
+);
+process.exit(1);