muse-crew 0.15.0 → 0.17.0

package/lib/qa-deploy.mjs

@@ -0,0 +1,498 @@
+#!/usr/bin/env node
+// qa-deploy.mjs — deterministic deploy for the QA environment.
+//
+// Ensures the pipeline-owned QA environment (<qa-dir>) serves a client/server
+// bundle built from the repo's merged HEAD. This is a substrate-independent
+// deterministic core: it runs as a plain process with shell and filesystem
+// access (worker layer) and must NEVER be imported or executed inside the
+// workflow sandbox — the sandbox has no child processes. The workflow reaches
+// it only through a thin mechanical agent ferry that runs one exact pinned
+// command and returns stdout verbatim; the ferry carries a single marker
+// line, the full evidence is self-recorded here.
+//
+// The QA environment is SEPARATE from the web artifact directory
+// (~/workspace/ts-spaces/<slug>/). That directory's own house rules forbid
+// building it by hand, and the SDK's client bundler refuses to run outside
+// the artifact pipeline — this module never touches it. The QA dir lives
+// under the crew home (e.g. <crewHome>/qa-envs/<project>/) and is owned
+// entirely by this pipeline: we clone, sync, build, validate, and serve it.
+//
+// Usage:
+//   node qa-deploy.mjs --repo <path> --qa-dir <path> --task <id>
+//       --crew-home <path> --crew-api <path> --serve-artifact <path>
+//       [--ensure] [--hash-only]
+//
+//   --ensure    Idempotent precondition: fast-path (skip sync+build) when the
+//               existing bundle already proves a hash that is a
+//               descendant-or-equal of this task's newest recorded deploy;
+//               otherwise run the full deploy. The servability probe always
+//               runs.
+//   --hash-only Read the bundle's baked hash and print BUNDLE_HASH <sha>|none.
+//               A pure read for QA closeout contamination checks; changes
+//               nothing.
+//
+// Exit codes: 0 = DEPLOY_OK (or hash read), 1 = DEPLOY_FAIL (operational),
+// 2 = usage error. Stdout carries exactly one marker line; all diagnostics
+// go to stderr. Deploy failures are operational and retryable — they never
+// park the task; the workflow marks the step failed for retry.
+//
+// Deploy record (self-recorded via crew-api log-event, type "note"):
+///   deploy: ok hash=<short> built=<full> mode=<full|fast> task=<id>
+//   deploy: fail layer=<layer> reason=<reason> task=<id>
+// The details bypass the ferry; the ferry carries only:
+//   DEPLOY_OK <short-hash>
+//   DEPLOY_FAIL <layer>:<reason>
+
+import { spawn, execFile } from "node:child_process";
+import { existsSync, statSync, readFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const BUILD_TIMEOUT_MS = 600000;
+const INSTALL_TIMEOUT_MS = 600000;
+const SERVE_READY_TIMEOUT_MS = 30000;
+const SERVE_KILL_TIMEOUT_MS = 10000;
+const SHA_RE = /^[0-9a-f]{40}$/;
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--ensure") { out.ensure = true; continue; }
+    if (a === "--hash-only") { out.hash_only = true; continue; }
+    if (a.startsWith("--")) { out[a.slice(2).replace(/-/g, "_")] = argv[++i]; continue; }
+  }
+  return out;
+}
+
+function log(...parts) { process.stderr.write(parts.join(" ") + "\n"); }
+
+// Run a command, capture stdout. Rejects on non-zero exit or spawn error.
+function run(cmd, args, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const env = opts.env || process.env;
+    const child = execFile(cmd, args, {
+      cwd: opts.cwd, timeout: opts.timeout || 120000, maxBuffer: 4 * 1024 * 1024, env,
+    }, (err, stdout, stderr) => {
+      if (err) {
+        const e = new Error(cmd + " " + args.join(" ") + " failed: " +
+          String((stderr || "") + (err.message || "")).slice(0, 300));
+        e.code = err.code; e.stdout = stdout; e.stderr = stderr;
+        reject(e);
+      } else resolve(String(stdout || ""));
+    });
+  });
+}
+
+const git = (repo, ...args) => run("git", ["-C", repo, ...args]);
+
+async function crewApi(crewApiPath, crewHome, command, json) {
+  const out = await run("node", [crewApiPath, "--crew-home", crewHome, command, "--json", JSON.stringify(json)]);
+  return JSON.parse(out);
+}
+
+async function recordDeploy(a, ok, fields) {
+  const msg = ok
+    ? "deploy: ok hash=" + fields.short + " built=" + fields.full + " mode=" + fields.mode + " task=" + a.task
+    : "deploy: fail layer=" + fields.layer + " reason=" + String(fields.reason).replace(/\s+/g, " ").slice(0, 200) + " task=" + a.task;
+  try {
+    await crewApi(a.crew_api, a.crew_home, "log-event",
+      { task_id: a.task, type: "note", identity: "qa-deploy", message: msg });
+  } catch (e) {
+    log("WARN: deploy record not written:", e.message);
+  }
+}
+
+// Newest recorded deploy for this task: { ok, full } or null.
+async function newestDeployRecord(a) {
+  try {
+    const res = await crewApi(a.crew_api, a.crew_home, "get-events", { task_id: a.task, limit: 100 });
+    for (const ev of (res.events || [])) {
+      const m = /^deploy: (ok|fail) /.exec(ev.message || "");
+      if (!m) continue;
+      if (m[1] === "ok") {
+        const h = /built=([0-9a-f]{40})/.exec(ev.message);
+        if (h) return { ok: true, full: h[1] };
+      }
+      return { ok: false };
+    }
+  } catch (e) {
+    log("WARN: cannot read deploy history:", e.message);
+  }
+  return null;
+}
+
+// Read the baked source hash from the built server bundle. The project's own
+// prebuild (bake-binding.mjs) inlines server/src/binding.gen.json — carrying
+// source_commit — into server/dist/actions.js. Corroborate with space.json's
+// build_source_commit (also written by the prebuild). Returns the full SHA or
+// throws with a hash-layer reason.
+function readBundleHash(qaDir) {
+  const bundlePath = join(qaDir, "server", "dist", "actions.js");
+  if (!existsSync(bundlePath)) throw new Error("server bundle missing");
+  const src = readFileSync(bundlePath, "utf8");
+  const found = new Set();
+  // The inlined binding.gen.json may appear as a JSON object ("source_commit")
+  // or as a JS object literal (source_commit) depending on the bundler.
+  const re = /["']?source_commit["']?\s*:\s*["']([0-9a-f]{40})["']/g;
+  let m;
+  while ((m = re.exec(src)) !== null) found.add(m[1]);
+  if (found.size === 0) throw new Error("no source_commit baked in server bundle");
+  if (found.size > 1) throw new Error("ambiguous source_commit in server bundle: " + [...found].join(","));
+  const h = [...found][0];
+  const spaceJsonPath = join(qaDir, "space.json");
+  if (existsSync(spaceJsonPath)) {
+    let sj;
+    try { sj = JSON.parse(readFileSync(spaceJsonPath, "utf8")); }
+    catch (e) { throw new Error("space.json unparseable: " + e.message); }
+    if (sj.build_source_commit && sj.build_source_commit !== h) {
+      throw new Error("space.json build_source_commit " + sj.build_source_commit +
+        " disagrees with bundle " + h);
+    }
+  }
+  return h;
+}
+
+function distPresent(qaDir) {
+  for (const rel of ["client/dist/index.html", "server/dist/actions.js"]) {
+    const p = join(qaDir, rel);
+    if (!existsSync(p)) return { ok: false, missing: rel };
+    try { if (statSync(p).size === 0) return { ok: false, missing: rel + " (empty)" }; }
+    catch (e) { return { ok: false, missing: rel }; }
+  }
+  return { ok: true };
+}
+
+// Layer 1: the repo (source of truth) is a clean tree at a valid HEAD.
+async function checkCleanTree(repo) {
+  let head;
+  try { head = (await git(repo, "rev-parse", "HEAD")).trim(); }
+  catch (e) { throw new Error("not a git repo or HEAD unreadable"); }
+  if (!SHA_RE.test(head)) throw new Error("HEAD is not a full SHA: " + head);
+  const status = await git(repo, "status", "--porcelain");
+  if (status.trim() !== "") throw new Error("dirty tree: " + status.trim().split("\n").slice(0, 3).join("; "));
+  return head;
+}
+
+// Layer 2a: first-time setup of the pipeline-owned QA environment — a local
+// clone of the source repo plus installed dependencies. Idempotent: skips
+// when the qa dir is already a git checkout with node_modules.
+async function setupQaDir(repo, qaDir) {
+  let isRepo = false;
+  try { await git(qaDir, "rev-parse", "HEAD"); isRepo = true; }
+  catch (e) { isRepo = false; }
+  if (!isRepo) {
+    if (existsSync(qaDir)) {
+      throw new Error("qa dir exists but is not a git checkout — refusing to clobber; move it aside");
+    }
+    log("cloning repo into qa dir");
+    try { await run("git", ["clone", repo, qaDir], { timeout: INSTALL_TIMEOUT_MS }); }
+    catch (e) { throw new Error("git clone failed: " + e.message); }
+  }
+  if (!existsSync(join(qaDir, "node_modules"))) {
+    log("installing dependencies in qa dir");
+    try { await run("bun", ["install"], { cwd: qaDir, timeout: INSTALL_TIMEOUT_MS }); }
+    catch (e) { throw new Error("bun install failed: " + e.message); }
+  }
+}
+
+// Layer 2b: sync the QA environment's source to the repo's HEAD via git.
+async function syncSource(repo, qaDir, head) {
+  try {
+    await git(qaDir, "fetch", repo, head);
+  } catch (e) { throw new Error("fetch from repo failed: " + e.message); }
+  try {
+    await git(qaDir, "reset", "--hard", head);
+  } catch (e) { throw new Error("reset --hard failed: " + e.message); }
+  const now = (await git(qaDir, "rev-parse", "HEAD")).trim();
+  if (now !== head) throw new Error("qa dir HEAD " + now + " != " + head + " after reset");
+}
+
+// Layer 2c: reproduce the artifact builder's codegen — extract the
+// `definePrivilegedContracts({...})` block from server/src/privileged.ts into
+// server/.generated/privileged.contract.ts. The project's tsconfig maps
+// `@space/privileged` to that generated file; the directory is gitignored, so
+// a fresh clone lacks it and the server bundle cannot resolve the import.
+// web_artifact_build performs this extraction in the artifact pipeline; our
+// pipeline reproduces it deterministically (verified byte-identical modulo
+// header). The extraction is a pure data copy — the privileged handlers stay
+// in privileged.ts and never enter the action bundle, preserving the
+// platform's security boundary.
+function extractContractBlock(src) {
+  const marker = "export const privileged = definePrivilegedContracts({";
+  const start = src.indexOf(marker);
+  if (start === -1) throw new Error("contract marker not found in server/src/privileged.ts");
+  let i = start + marker.length - 1; // at the opening {
+  let depth = 0;
+  let state = "code"; // code | squote | dquote | tquote | linecomment | blockcomment | regex
+  let tmplDepth = 0;
+  for (; i < src.length; i++) {
+    const c = src[i], n = src[i + 1];
+    if (state === "code") {
+      if (c === "'" ) { state = "squote"; }
+      else if (c === '"') { state = "dquote"; }
+      else if (c === "`") { state = "tquote"; tmplDepth = 0; }
+      else if (c === "/" && n === "/") { state = "linecomment"; i++; }
+      else if (c === "/" && n === "*") { state = "blockcomment"; i++; }
+      else if (c === "/" && isRegexStart(src, i)) { state = "regex"; }
+      else if (c === "{") { depth++; }
+      else if (c === "}") {
+        depth--;
+        if (depth === 0) {
+          // Expect the closing ");" of the definePrivilegedContracts call.
+          const rest = src.slice(i, i + 3);
+          if (rest[1] !== ")" || rest[2] !== ";") {
+            throw new Error("contract block does not end with }); — source shape changed");
+          }
+          return src.slice(start, i + 3);
+        }
+      }
+    } else if (state === "squote" || state === "dquote") {
+      const q = state === "squote" ? "'" : '"';
+      if (c === "\\") i++;
+      else if (c === q) state = "code";
+    } else if (state === "tquote") {
+      if (c === "\\") i++;
+      else if (c === "`" && tmplDepth === 0) state = "code";
+      else if (c === "$" && n === "{") { tmplDepth++; i++; }
+      else if (c === "}" && tmplDepth > 0) tmplDepth--;
+    } else if (state === "linecomment") {
+      if (c === "\n") state = "code";
+    } else if (state === "blockcomment") {
+      if (c === "*" && n === "/") { state = "code"; i++; }
+    } else if (state === "regex") {
+      if (c === "\\") i++;
+      else if (c === "[") { // character class — skip to ]
+        let j = i + 1;
+        if (src[j] === "^") j++;
+        if (src[j] === "]") j++;
+        while (j < src.length && src[j] !== "]") { if (src[j] === "\\") j++; j++; }
+        i = j;
+      }
+      else if (c === "/") state = "code";
+    }
+  }
+  throw new Error("unterminated contract block — source shape changed");
+}
+
+// Heuristic: a / starts a regex (not division) when the previous significant
+// token ends an expression-opener. Conservative: only true for the positions
+// where the contract block uses regexes (after `(` in `.regex(/.../`).
+function isRegexStart(src, i) {
+  let j = i - 1;
+  while (j >= 0 && " \t\n\r".includes(src[j])) j--;
+  if (j < 0) return true;
+  return "(:,=![&|?{;".includes(src[j]);
+}
+
+async function generateContract(qaDir) {
+  const srcPath = join(qaDir, "server", "src", "privileged.ts");
+  const outDir = join(qaDir, "server", ".generated");
+  const outPath = join(outDir, "privileged.contract.ts");
+  let src;
+  try { src = readFileSync(srcPath, "utf8"); }
+  catch (e) { throw new Error("cannot read server/src/privileged.ts: " + e.message); }
+  const block = extractContractBlock(src);
+  const out = "// Generated by qa-deploy from server/src/privileged.ts. Do not edit.\n" +
+    "import { definePrivilegedContracts, z } from \"@hatch/space-sdk\";\n\n" + block + "\n";
+  mkdirSync(outDir, { recursive: true });
+  writeFileSync(outPath, out);
+  log("contract generated: " + outPath);
+}
+
+// Layer 3: deterministic build in the QA environment.
+async function buildQa(qaDir, crewHome) {
+  // The project's client/build.mjs delegates to the SDK's buildClient(),
+  // which requires HATCH_SPACES_BUILD_DRIVER=1. That guard (and the web
+  // artifact's own AGENTS.md) protects the LIVE web artifact directory from
+  // hand-built bundles being mistaken for published ones — this pipeline
+  // never touches that directory. The QA dir is pipeline-owned; our pipeline
+  // IS the build driver here, and the bundle is validated independently
+  // (baked hash == HEAD, servability probe) rather than trusted. Setting the
+  // variable invokes the SDK's canonical bundler; the guard and the
+  // project's build are not modified.
+  //
+  // CREW_HOME selects the dashboard's binding mode: set (to a directory) it
+  // builds the live binding (with source_commit baked); absent it builds a
+  // snapshot with empty data. QA needs the live binding — Hazel tests the
+  // real dashboard against real crew data, and the hash layer needs the
+  // baked source_commit.
+  const env = Object.assign({}, process.env, {
+    HATCH_SPACES_BUILD_DRIVER: "1",
+    CREW_HOME: crewHome,
+  });
+  await new Promise((resolve, reject) => {
+    const child = spawn("bun", ["run", "build"], { cwd: qaDir, stdio: ["ignore", "pipe", "pipe"], env });
+    let out = "", err = "";
+    child.stdout.on("data", (d) => { out += d; });
+    child.stderr.on("data", (d) => { err += d; });
+    const timer = setTimeout(() => {
+      child.kill("SIGKILL");
+      reject(new Error("build timed out after " + (BUILD_TIMEOUT_MS / 1000) + "s"));
+    }, BUILD_TIMEOUT_MS);
+    child.on("error", (e) => { clearTimeout(timer); reject(new Error("cannot start bun: " + e.message)); });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (code === 0) resolve();
+      else reject(new Error("bun run build exited " + code + ": " + (err + out).slice(-500).replace(/\s+/g, " ")));
+    });
+  });
+}
+
+// Layer 6: the servability probe — the built bundle must boot and print READY.
+async function probeServe(serveArtifactPath, qaDir, tag) {
+  await new Promise((resolve, reject) => {
+    const child = spawn("node", [serveArtifactPath, "--space-dir", qaDir, "--port", "0", "--tag", tag],
+      { stdio: ["ignore", "pipe", "pipe"] });
+    let out = "", err = "";
+    const readyTimer = setTimeout(() => {
+      child.kill("SIGKILL");
+      reject(new Error("no READY within " + (SERVE_READY_TIMEOUT_MS / 1000) + "s; stderr: " + err.slice(-300)));
+    }, SERVE_READY_TIMEOUT_MS);
+    const finish = (code) => {
+      clearTimeout(readyTimer);
+      const np = /\{\s*"ok"\s*:\s*false[\s\S]*?"not_possible"\s*:\s*"([^"]*)"/.exec(out);
+      reject(new Error(code === 3 && np
+        ? "NOT POSSIBLE: " + np[1]
+        : "server exited " + code + " before READY: " + (out + err).slice(-300).replace(/\s+/g, " ")));
+    };
+    child.stdout.on("data", (d) => {
+      out += d;
+      const r = /READY port=(\d+)/.exec(out);
+      if (r) {
+        clearTimeout(readyTimer);
+        log("probe READY on port " + r[1] + " — shutting down");
+        child.kill("SIGTERM");
+        const kt = setTimeout(() => child.kill("SIGKILL"), SERVE_KILL_TIMEOUT_MS);
+        child.on("close", () => { clearTimeout(kt); resolve(); });
+      }
+    });
+    child.stderr.on("data", (d) => { err += d; });
+    child.on("error", (e) => {
+      clearTimeout(readyTimer);
+      reject(new Error("cannot start serve-artifact: " + e.message));
+    });
+    child.on("close", (code) => { if (!/READY port=/.test(out)) finish(code); });
+  });
+}
+
+const a = parseArgs(process.argv.slice(2));
+
+// lib/AGENTS.md shebang⇔CLI contract: --help answers with a usage line on
+// stdout and exit 0, handled before required-argument parsing (the release
+// entry gate executes every shebang'd JS entry as `node <file> --help`).
+if (process.argv.includes("--help")) {
+  process.stdout.write("usage: node qa-deploy.mjs --repo <path> --qa-dir <path> --task <id> --crew-home <path> --crew-api <path> --serve-artifact <path> [--ensure] [--hash-only]\n");
+  process.exit(0);
+}
+
+async function main() {
+  // `a` is module-scoped so the top-level catch can self-record.
+  if (a.hash_only) {
+    // Pure read: only --qa-dir is required.
+    if (!a.qa_dir) { process.stderr.write("usage: --qa-dir required\n"); process.exit(2); }
+    try {
+      const h = readBundleHash(a.qa_dir);
+      process.stdout.write("BUNDLE_HASH " + h + "\n");
+    } catch (e) {
+      process.stdout.write("BUNDLE_HASH none\n");
+    }
+    process.exit(0);
+  }
+
+  for (const k of ["repo", "qa_dir", "task", "crew_home", "crew_api", "serve_artifact"]) {
+    if (!a[k]) { process.stderr.write("usage: missing --" + k.replace(/_/g, "-") + "\n"); process.exit(2); }
+  }
+
+  const fail = async (layer, reason) => {
+    log("DEPLOY_FAIL " + layer + ": " + reason);
+    await recordDeploy(a, false, { layer, reason });
+    process.stdout.write("DEPLOY_FAIL " + layer + ":" + String(reason).replace(/[\r\n]+/g, " ").slice(0, 200) + "\n");
+    process.exit(1);
+  };
+
+  // Layer 1: clean tree at HEAD (source of truth).
+  let head;
+  try { head = await checkCleanTree(a.repo); }
+  catch (e) { await fail("clean-tree", e.message); return; }
+  const short = head.slice(0, 7);
+  log("HEAD " + head);
+
+  let mode = "full";
+  if (a.ensure) {
+    // Idempotent precondition: does the existing bundle already prove a hash
+    // that is a descendant-or-equal of this task's newest recorded deploy?
+    // The chain is sound: every recorded deploy built a HEAD that contained
+    // the task's merge (Integrate verified the merge first), so a bundle
+    // descended from a recorded deploy contains the task's work.
+    try {
+      const dp = distPresent(a.qa_dir);
+      if (dp.ok) {
+        const h = readBundleHash(a.qa_dir);
+        const rec = await newestDeployRecord(a);
+        if (rec && rec.ok) {
+          try {
+            await git(a.repo, "merge-base", "--is-ancestor", rec.full, h);
+            mode = "fast";
+            log("fast path: bundle " + h.slice(0, 7) + " descends from recorded deploy " + rec.full.slice(0, 7));
+          } catch (e) {
+            log("bundle " + h.slice(0, 7) + " does not descend from recorded deploy — full deploy");
+          }
+        } else {
+          log("no successful recorded deploy — full deploy");
+        }
+      } else {
+        log("dist missing (" + dp.missing + ") — full deploy");
+      }
+    } catch (e) {
+      log("fast-path check inconclusive (" + e.message + ") — full deploy");
+    }
+  }
+
+  if (mode === "full") {
+    // Layer 2: set up and sync the QA environment.
+    try { await setupQaDir(a.repo, a.qa_dir); }
+    catch (e) { await fail("setup", e.message); return; }
+    try { await syncSource(a.repo, a.qa_dir, head); }
+    catch (e) { await fail("sync", e.message); return; }
+    log("source synced to " + short);
+    // Layer 2c: reproduce the artifact builder's codegen.
+    try { await generateContract(a.qa_dir); }
+    catch (e) { await fail("codegen", e.message); return; }
+    // Layer 3: deterministic build.
+    try { await buildQa(a.qa_dir, a.crew_home); }
+    catch (e) { await fail("build", e.message); return; }
+    log("build ok");
+    // Layer 4: dist present and non-empty.
+    const dp = distPresent(a.qa_dir);
+    if (!dp.ok) { await fail("dist", "missing: " + dp.missing); return; }
+    // Layer 5: the bundle's baked hash reads back equal to HEAD.
+    let h;
+    try { h = readBundleHash(a.qa_dir); }
+    catch (e) { await fail("hash", e.message); return; }
+    if (h !== head) { await fail("hash", "bundle baked " + h + " != HEAD " + head); return; }
+    log("hash ok: bundle proves " + short);
+  }
+
+  // Layer 6: servability probe (always runs, even on the fast path).
+  try {
+    await probeServe(a.serve_artifact, a.qa_dir, a.task + "-deploy");
+  } catch (e) { await fail("serve", e.message); return; }
+  log("serve ok");
+
+  await recordDeploy(a, true, { short, full: head, mode });
+  process.stdout.write("DEPLOY_OK " + short + "\n");
+  process.exit(0);
+}
+
+main().catch(async (e) => {
+  process.stderr.write("unexpected: " + (e && e.stack || e) + "\n");
+  try {
+    if (a.task && a.crew_api && a.crew_home) {
+      await recordDeploy(a, false, { layer: "internal", reason: String((e && e.message) || e).slice(0, 200) });
+    }
+  } catch (recErr) {
+    process.stderr.write("WARN: could not record internal failure: " + recErr.message + "\n");
+  }
+  process.stdout.write("DEPLOY_FAIL internal:unexpected error\n");
+  process.exit(1);
+});

package/lib/schema.sql

@@ -281,3 +281,22 @@ CREATE TABLE IF NOT EXISTS builder_reports (
 );
 CREATE INDEX IF NOT EXISTS builder_reports_task_id_idx ON builder_reports(task_id);
 CREATE INDEX IF NOT EXISTS builder_reports_version_idx ON builder_reports(version);
+
+-- Worker-layer run ledger (Piece 1, 2026-09-26): every worker-layer
+-- orchestration run (dispatcher, and later workflow phases) records its
+-- start/finish here. The sandboxed workflow runtime keeps writing
+-- workflow_runs; this table is the worker-layer counterpart. Timestamps
+-- are written by SQLite (strftime), never by worker JS — the determinism
+-- guard forbids wall-clock in orchestration code (G3).
+CREATE TABLE IF NOT EXISTS worker_runs (
+  id         INTEGER PRIMARY KEY AUTOINCREMENT,
+  task_id    TEXT REFERENCES tasks(id) ON DELETE CASCADE,
+  phase      TEXT NOT NULL,
+  executor   TEXT NOT NULL DEFAULT 'worker' CHECK (executor = 'worker'),
+  status     TEXT NOT NULL CHECK (status IN ('running', 'completed', 'failed')),
+  error      TEXT,
+  started_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  ended_at   TEXT
+);
+CREATE INDEX IF NOT EXISTS worker_runs_task_id_idx ON worker_runs(task_id);
+CREATE INDEX IF NOT EXISTS worker_runs_phase_idx ON worker_runs(phase);

package/lib/spawn-boundary.js

@@ -0,0 +1,101 @@
+// lib/spawn-boundary.js — fail-closed spawn bounds validator (G1a).
+//
+// Piece 1 of the sandbox exit. Every creative-agent spawn on the worker
+// layer goes through this module BEFORE the orchestrator emits NEED_SPAWN.
+// It does not perform the spawn — the worker agent does that — it validates
+// the bounds and FAILS CLOSED (throws, no spawn) unless every rule holds.
+//
+// Rules (DESIGN-v2 G1a):
+// - prompt_file, schema_file, cwd, env, workdir, crewHome must ALL be declared.
+//   No spawn without declared bounds. Ever.
+// - prompt_file and schema_file must be co-located (same directory).
+// - cwd must resolve inside workdir (the task's own worktree or a designated
+//   scratch dir). `..` escapes fail closed.
+// - cwd must NOT contain denied fragments (defense in depth): crew-state
+//   databases, crew homes, observer state, dispatch logs.
+// - env must be an object; no key may match a denied sensitive pattern.
+//
+// This module is import-safe: no side effects on import, bare `node` exits 0.
+
+import { resolve, dirname, relative } from "node:path";
+
+const DENIED_PATH_FRAGMENTS = [
+  "crew-state.db",
+  ".crew-soak-gate2",
+  ".observer",
+  ".tick-releases.jsonl",
+  ".dispatch-decisions.jsonl",
+];
+
+const DENIED_ENV_PATTERNS = [
+  "KEY",
+  "TOKEN",
+  "SECRET",
+  "PASSWORD",
+  "PRIVATE",
+  "CREDENTIAL",
+  "AUTH",
+];
+
+function fail(violation) {
+  const err = new Error("spawn-boundary: BOUNDS_REJECTED: " + violation);
+  err.code = "BOUNDS_REJECTED";
+  throw err;
+}
+
+// Validate spawn bounds. Returns { cwd, env } (resolved/normalized) on
+// success. Throws with code BOUNDS_REJECTED on any violation.
+export function validateSpawnBounds(bounds) {
+  if (!bounds || typeof bounds !== "object") fail("bounds must be an object");
+
+  const { prompt_file, schema_file, cwd, env, workdir, crewHome } = bounds;
+
+  if (typeof prompt_file !== "string" || prompt_file.length === 0)
+    fail("prompt_file must be a declared non-empty string");
+  if (typeof schema_file !== "string" || schema_file.length === 0)
+    fail("schema_file must be a declared non-empty string");
+  if (typeof cwd !== "string" || cwd.length === 0)
+    fail("cwd must be a declared non-empty string");
+  if (!env || typeof env !== "object" || Array.isArray(env))
+    fail("env must be a declared object");
+  if (typeof workdir !== "string" || workdir.length === 0)
+    fail("workdir must be a declared non-empty string");
+  if (typeof crewHome !== "string" || crewHome.length === 0)
+    fail("crewHome must be a declared non-empty string");
+
+  // Schema co-location: prompt and schema travel together.
+  if (dirname(resolve(prompt_file)) !== dirname(resolve(schema_file)))
+    fail("prompt_file and schema_file must be co-located (same directory)");
+
+  // cwd must resolve inside workdir — no `..` escapes.
+  const resolvedCwd = resolve(cwd);
+  const resolvedWorkdir = resolve(workdir);
+  const rel = relative(resolvedWorkdir, resolvedCwd);
+  if (rel === ".." || rel.startsWith("../") || resolve(resolvedWorkdir, rel) !== resolvedCwd)
+    fail("cwd must resolve inside workdir (got " + cwd + ")");
+
+  // Defense in depth: denied fragments anywhere in the resolved cwd.
+  for (const frag of DENIED_PATH_FRAGMENTS) {
+    if (resolvedCwd.includes(frag)) fail("cwd inside denied path: " + frag);
+  }
+  // The crew home itself is never a spawn cwd, even without a fragment hit.
+  const crewRel = relative(resolve(crewHome), resolvedCwd);
+  if (crewRel === "" || (!crewRel.startsWith("../") && crewRel !== ".."))
+    fail("cwd must not be inside crewHome");
+
+  // Sensitive environment denied by default.
+  for (const key of Object.keys(env)) {
+    const upper = String(key).toUpperCase();
+    for (const pat of DENIED_ENV_PATTERNS) {
+      if (upper.includes(pat)) fail("env key denied: " + key);
+    }
+  }
+
+  return { cwd: resolvedCwd, env: { ...env } };
+}
+
+// Declared constants for tests and for orchestrators that build bounds.
+export const BOUNDARY = {
+  DENIED_PATH_FRAGMENTS: [...DENIED_PATH_FRAGMENTS],
+  DENIED_ENV_PATTERNS: [...DENIED_ENV_PATTERNS],
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "muse-crew",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Opinionated orchestration for Muse — workflows, identities, and tooling for autonomous software development.",
   "license": "UNLICENSED",
   "private": false,

package/seed/cron-body-template.md

@@ -43,6 +43,10 @@ The failures below are settled and recorded in the Gate 1 OODA state. The author
 
 2. **Load the workflow registry:** Read the file "{crewHome}/workflows/registry.json" with the read tool and keep its RAW TEXT — do NOT parse it, do NOT re-emit it as a JSON object. Pass the text verbatim: never reformat, summarize, or hand-transcribe it (room #26: 15+ launch rejections 09-19→09-21 from garbled nested-object args, and one hallucinated registry that passed validation). If the file does not exist (the live release predates the registry), proceed without it — omit the `registryText` arg and the dispatcher will load the registry the slow way and log a warning. If the read FAILS on a file that exists (transient read error — observed 2026-09-13; the file itself was healthy and later ticks read it fine), retry the read once; if it still fails, write the error text into your run summary (observability — never silently swallow a failed read) and proceed without the registry the same way.
 
+2.5. **Shadow dispatch (Piece 1, 2026-09-26):** the worker-layer dispatcher (`lib/crew-dispatch-worker.js`) is the sandbox exit's replacement for the sandboxed dispatcher in Step 3. It is NOT authoritative yet — Step 3's sandboxed dispatcher still owns every launch decision. Run the worker dispatcher in read-only shadow mode BEFORE Step 3 (both must read the same board state; the shadow never mutates it). Run in shell:
+  `node {crewHome}/lib/crew-dispatch-worker.js --crew-home {crewHome} --read-only`
+  The last stdout line is a JSON result (`{status, claims, ...}`); lines before it are the decision log. The script appends its own shadow evidence to `{crewHome}/.dispatch-shadow.jsonl` — do NOT transcribe or re-emit the claims yourself. If the script exits non-zero, log `SHADOW_FAIL <stderr tail>` and continue to Step 3 (the shadow is evidence, never a gate). A zero exit with claims is normal — the claims are recommendations only; NOTHING is launched from them. Every claim carries `executor: "worker"`; the shadow comparison ignores it.
+
 3. **Run the dispatcher:** Call workflow_launch with scriptPath "{crewHome}/workflows/crew-dispatch.js" and args {"crewHome": "{crewHome}", "registryText": <raw registry file text, or omit the key when the file was missing>}. The dispatcher parses the text itself — a nested-object `registry` arg is not accepted. If the launch is rejected, retry once with only {"crewHome": "{crewHome}"} (the sanctioned fallback — the dispatcher loads the registry the slow way); a second rejection is a platform problem, not an args problem — write it in your run summary and move on.
 
    Wait for it to complete. It reads the crew's task state, determines eligibility, claims tasks, acknowledges the poll, and returns structured results.
@@ -106,6 +110,10 @@ The failures below are settled and recorded in the Gate 1 OODA state. The author
    - `timeouts` = fully handled by code — take NO action, just log. The 2-hour total budget from first issuance is exhausted with no acknowledgement; code writes the terminal `publish: version-timeout` note — parked for human attention. `timeouts` is terminal-budget exhaustion only — a window expiry is a `reissued`, never a timeout.
    - `reissued` = fresh intents for the next attempt — a 30-minute window expired with no acknowledgement, so code re-issued with a fresh version (by derivation), immediately claimable (no backoff). This tick does NOT issue them; the NEXT tick's `scan-publish-intent` claims them. Log only.
    - `skipped` = window still open or evidence absent — log only, take no action.
+
+4.6. **Shadow verdict (Piece 1, 2026-09-26):** after the Step-3 dispatcher's decision is recorded, pair its decision with the Step-2.5 shadow evidence. Run in shell:
+  `node {crewHome}/lib/compare-dispatch-shadow.js --crew-home {crewHome}`
+  Log every `SHADOW_*` line verbatim. `SHADOW_MATCH` means the worker layer agreed with the sandbox on this tick's claims. `SHADOW_DIVERGE` names the differing claim triples (`task_id|workflow|step`) — log them; divergence is evidence for the cutover review, not a tick failure, so continue the tick. `SHADOW_UNPAIRED` means the authoritative decision line is missing (the Step-3 dispatcher died after the shadow ran) — log it loudly and continue. `SHADOW_NO_EVIDENCE` on the first shadowed tick is normal. Verdicts append to `{crewHome}/.dispatch-shadow-verdicts.jsonl`; the cutover decision after ~100-200 ticks is made from that file, never from a single tick.
    - Never stamp provenance from prose. Never infer a verdict from an inspector's summary text. The exact version string is the sole positive signal.
 
 5. **Monitor launched workflows until terminal (stay-alive — 2026-09-13):** The platform ties async workflow `agent()` authorization to the launcher's lifetime: if THIS tick ends while a workflow is still running, the workflow's next `agent()` call fails with "subagent bootstrap is no longer authorized" / "subagent reservation owner is terminal". Prevention beats recovery here, so this tick is configured with a 90-minute execution timeout (`timeout_secs: 5400` in seed/crons.json) and you MUST stay alive until every launched run reaches a terminal state. Do not exit early while a launched run is still `running` — your death is what kills it.