muse-crew 0.15.0 → 0.16.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/package.json

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

package/workflows/bugfix.js

@@ -72,8 +72,14 @@ const CLASSIFY_SURFACE_SRC = crewHome + "/current/lib/classify-surface.js";
 const CLASSIFY_SURFACE = RUN_LIB + "/classify-surface.js";
 const NOTE_VOCAB_SRC = crewHome + "/current/lib/publish-note-vocabulary.js";
 const NOTE_VOCAB = RUN_LIB + "/publish-note-vocabulary.js";
+const QA_DEPLOY_SRC = crewHome + "/current/lib/qa-deploy.mjs";
+const QA_DEPLOY = RUN_LIB + "/qa-deploy.mjs";
+const SERVE_ARTIFACT_SRC = crewHome + "/current/lib/serve-artifact.js";
+const SERVE_ARTIFACT = RUN_LIB + "/serve-artifact.js";
+const QA_DB_SRC = crewHome + "/current/lib/qa-db.js";
+const QA_DB = RUN_LIB + "/qa-db.js";
 // See docs/decisions/qa-reproduce.md#pin-basenames: the pin step materializes the required scripts.
-const PIN_BASENAMES = [LIFECYCLE, MERGE_LOCK, PUBLISH_NPM, CREW_API_PINNED, SCHEMA_SQL_PINNED, COMPUTE_DIFF, CLASSIFY_SURFACE, NOTE_VOCAB].map(function (p) { return p.split("/").pop(); });
+const PIN_BASENAMES = [LIFECYCLE, MERGE_LOCK, PUBLISH_NPM, CREW_API_PINNED, SCHEMA_SQL_PINNED, COMPUTE_DIFF, CLASSIFY_SURFACE, NOTE_VOCAB, QA_DEPLOY, SERVE_ARTIFACT, QA_DB].map(function (p) { return p.split("/").pop(); });
 
 // Project config — passed by dispatcher, falls back to dashboard defaults
 const projectConfig = inputs.project_config || {};
@@ -265,7 +271,7 @@ function attemptKey(base, reworkCount) {
 function pinLifecycle(key) {
   return agent(
     "Snapshot lifecycle scripts for version pinning.\n" +
-    "Run: mkdir -p " + RUN_LIB + " && cp " + LIFECYCLE_SRC + " " + LIFECYCLE + " && cp " + MERGE_LOCK_SRC + " " + MERGE_LOCK + " && cp " + PUBLISH_NPM_SRC + " " + PUBLISH_NPM + " && cp " + CREW_API_SRC + " " + CREW_API_PINNED + " && cp " + SCHEMA_SQL_SRC + " " + SCHEMA_SQL_PINNED + " && cp " + COMPUTE_DIFF_SRC + " " + COMPUTE_DIFF + " && cp " + CLASSIFY_SURFACE_SRC + " " + CLASSIFY_SURFACE + " && cp " + NOTE_VOCAB_SRC + " " + NOTE_VOCAB + " && chmod +x " + LIFECYCLE + " " + MERGE_LOCK + " " + PUBLISH_NPM + " && ls -1 " + RUN_LIB + "\n" +
+    "Run: mkdir -p " + RUN_LIB + " && cp " + LIFECYCLE_SRC + " " + LIFECYCLE + " && cp " + MERGE_LOCK_SRC + " " + MERGE_LOCK + " && cp " + PUBLISH_NPM_SRC + " " + PUBLISH_NPM + " && cp " + CREW_API_SRC + " " + CREW_API_PINNED + " && cp " + SCHEMA_SQL_SRC + " " + SCHEMA_SQL_PINNED + " && cp " + COMPUTE_DIFF_SRC + " " + COMPUTE_DIFF + " && cp " + CLASSIFY_SURFACE_SRC + " " + CLASSIFY_SURFACE + " && cp " + NOTE_VOCAB_SRC + " " + NOTE_VOCAB + " && cp " + QA_DEPLOY_SRC + " " + QA_DEPLOY + " && cp " + SERVE_ARTIFACT_SRC + " " + SERVE_ARTIFACT + " && cp " + QA_DB_SRC + " " + QA_DB + " && chmod +x " + LIFECYCLE + " " + MERGE_LOCK + " " + PUBLISH_NPM + " && ls -1 " + RUN_LIB + "\n" +
     "Return the verbatim output of the ls -1 command as { \"listing\": \"<verbatim output>\" } and nothing else.",
     { key: key, label: "Pinning lifecycle scripts",
       schema: { type: "object", properties: { listing: { type: "string" } }, required: ["listing"] } }
@@ -563,17 +569,28 @@ function decideIntegrateRetry(o) {
   if (rec.malformed) return "park";
   return ancestor ? "skip-to-publish" : "proceed";
 }
-// QA version gate (issue #3): S=footer build, R=required. S>=R proves the
-// bundle is at/past the merge (single-branch: version order = containment).
-// Pure — pinned by tests/version-gate.test.js. Null = unreadable/missing.
-function decideVersionGate(S, R) {
-  if (!(R > 0)) return { proceed: false, reason: "qa-version-missing",
-    remedy: "no build version recorded — re-run Integrate or record dashboard-version." };
-  if (!(S > 0)) return { proceed: false, reason: "qa-version-unreadable",
-    remedy: "no readable build number in bundle footer — rebuild from versioned source." };
-  if (S >= R) return { proceed: true };
-  return { proceed: false, reason: "qa-bundle-stale",
-    remedy: "bundle build " + S + " behind required " + R + " — builder did not rebuild from current source." };
+// parseDeployResult: pure, fails closed. Ferry returns qa-deploy.mjs stdout
+// verbatim; the marker line is the only machine-read signal.
+function parseDeployResult(output) {
+  var m = /^DEPLOY_OK ([0-9a-f]{7})$/m.exec(String(output || "").trim());
+  if (m) return { ok: true, hash: m[1] };
+  var f = /^DEPLOY_FAIL ([a-z-]+):(.{1,200})$/m.exec(String(output || "").trim());
+  if (f) return { ok: false, reason: f[1] + ": " + f[2].trim() };
+  return { ok: false, reason: "unrecognized deploy output" };
+}
+// QA_ENV_DIR: pipeline-owned, under the crew home. Never the web artifact dir.
+var QA_ENV_DIR = crewHome + "/qa-envs/" + LAUNCH_PROJECT_ID;
+// runDeployFerry: thin mechanical agent, one pinned command, stdout verbatim
+function runDeployFerry(mode) {
+  var cmd = "node " + QA_DEPLOY + " --repo " + REPO_PATH + " --qa-dir " + QA_ENV_DIR +
+    " --task " + taskId + " --crew-home " + crewHome + " --crew-api " + CREW_API_PINNED +
+    " --serve-artifact " + SERVE_ARTIFACT + (mode === "--ensure" ? " --ensure" : "") + " 2>&1";
+  return agent(
+    "Run in shell and return the stdout verbatim:\n" + cmd + "\n" +
+    "Return JSON { \"output\": \"<the command's full stdout, trimmed>\" } and nothing else.",
+    { key: "qa-deploy-" + mode.replace(/-/g, "") + "-" + taskId, label: "Deploying QA environment",
+      schema: { type: "object", properties: { output: { type: "string" } }, required: ["output"] } }
+  );
 }
 // On a dispatcher retry resumed at Integrate, the run-local releaseDecision
 // is null (Build doesn't re-run). Hydrate it from the merge record so the
@@ -1367,25 +1384,28 @@ while (i < STEPS.length) {
   // verdicts.jsonl). No parent verdict gate remains.
   var qaArtifact = false;
   var qaTerminal = false;
-  var qaRequiredVersion = null;
+  var qaBundleHash = null;
   if (step.name === "QA") {
     var qaExp = (await resolveExperiential()) === "yes";
     qaArtifact = qaExp && SURFACE_ARTIFACT;
     qaTerminal = qaExp && SURFACE_TERMINAL;
     if (qaArtifact && projectConfig.versioned_build === true) {
-      var vfile = projectConfig.version_file || "client/src/buildNumber.ts";
-      var vgPre = await agent(
-        "Return ONLY JSON. 1. Run, return stdout verbatim:\n" + crewCmd("get-events", { task_id: taskId }) + "\n" +
-        "R = integer after `dashboard-version: ` in newest matching note. 2. If none, run, return stdout verbatim:\n" + crewCmd("get-provenance", { project_id: LAUNCH_PROJECT_ID }) + "\n" +
-        "R = BUILD_NUMBER from: cd " + REPO_PATH + " && git show <source_commit>:" + vfile + " | grep -o 'BUILD_NUMBER = [0-9]*'. If unknown: {\"ok\":false,\"park\":\"qa-version-missing: no build version recorded — re-run Integrate or record dashboard-version.\"}. " +
-        "3. cd " + REPO_PATH + " && git fetch origin && V=$(grep -o 'BUILD_NUMBER = [0-9]*' " + vfile + " | grep -o '[0-9]*'|head -1); if [ $V -lt R ]; then git pull --ff-only; V=$(grep -o 'BUILD_NUMBER = [0-9]*' " + vfile + " | grep -o '[0-9]*'|head -1); fi; " +
-        "if [ $V -lt R ]: {\"ok\":false,\"park\":\"qa-bundle-stale: checkout \" + V + \" < required \" + R + \" — sync past the merge, re-run QA.\"}. 4. Else {\"ok\":true,\"R\":R}.",
-        { key: "qa-version-pre-" + taskId, label: "QA version-gate pre-check",
-          schema: { type: "object", required: ["ok"],
-            properties: { ok: { type: "boolean" }, R: { type: "integer" }, park: { type: "string" } } } }
-      );
-      if (!vgPre.ok) return await parkTask(vgPre.park);
-      qaRequiredVersion = vgPre.R;
+      // ensure-deployed: idempotent precondition. Fast path when bundle is
+      // current. Failed deploy = operational failure (retryable), never a park.
+      var ensureOut = "";
+      try {
+        var ensureResult = await runDeployFerry("--ensure");
+        ensureOut = (ensureResult.output || "").trim();
+      } catch (e) {
+        ensureOut = "";
+      }
+      var ensureParsed = parseDeployResult(ensureOut);
+      if (!ensureParsed.ok) {
+        log("QA ensure-deployed failed for task " + taskId + ": " + ensureParsed.reason + " — returning failed for dispatcher retry");
+        return { status: "failed", task_id: taskId, reason: "QA ensure-deployed failed: " + ensureParsed.reason };
+      }
+      qaBundleHash = ensureParsed.hash;
+      log("QA ensure-deployed ok for task " + taskId + ": bundle " + qaBundleHash);
     }
   }
 
@@ -1715,14 +1735,6 @@ while (i < STEPS.length) {
       "R5-PUSH (manual R5 resolution only — the normal path pushed inline). Run: " + LIFECYCLE_ENV + LIFECYCLE + " push-target " + taskId + "\n" +
       "PUSHED — report the merged hash (detached prints PUSHED: origin/main (refspec HEAD:main)), VERDICT: PASS; PUSH_SKIPPED — no push attempted (no record + no lock); NO_REMOTE_PUSH — no remote; VERDICT: PASS; ERROR or CONFLICT — report it, VERDICT: FAIL.\n" +
       "NEVER force-push.\n\n" +
-      (projectConfig.versioned_build === true ?
-      "VERSION BUMP (issue #3): after MERGED+PUSHED, bump so QA can prove the bundle contains this fix — QA parks without it.\n" +
-      "1. cd " + REPO_PATH + " && git fetch origin; BR=<branch-from-integration-target>; F=" + (projectConfig.version_file || "client/src/buildNumber.ts") + "\n" +
-      "2. N=$(git show origin/$BR:$F | grep -o 'BUILD_NUMBER = [0-9]*' | grep -o '[0-9]*'); if missing/unparsable: VERDICT: FAIL.\n" +
-      "3. Edit $F: `export const BUILD_NUMBER = $N;` → `export const BUILD_NUMBER = $((N+1));` (keep header comment).\n" +
-      "4. git add $F && git commit -m \"build-number: $((N+1)) - QA version gate\" (SEPARATE commit, never amend).\n" +
-      "5. git push origin $BR; if rejected retry 3x (fetch, re-read N, re-bump, re-commit, push). NEVER force-push. Push MUST succeed or VERDICT: FAIL.\n" +
-      "6. Run, return stdout verbatim:\n" + crewCmd("log-event", { task_id: taskId, type: "note", identity: step.identity, message: "dashboard-version: <new> — QA must test a bundle built from source at or after the merge that recorded this (build <new> or later)." }) + "\n(substitute <new>).\n\n" : "") +
       "Report what happened at each step, ending with exactly one line: VERDICT: PASS or VERDICT: FAIL.";
 
 } else if (step.name === "Publish") {
@@ -2176,8 +2188,6 @@ while (i < STEPS.length) {
         "c3. Start with: SEE_ACT_ARCHIVE_DIR=" + crewHome + "/task-evidence/" + taskId + "/postchange/ node " + crewHome + "/current/lib/see-act.js --url http://localhost:<N>/ aria — read the JSON, log the step. Then: SEE_ACT_ARCHIVE_DIR=" + crewHome + "/task-evidence/" + taskId + "/postchange/ node " + crewHome + "/current/lib/see-act.js --url http://localhost:<N>/ shot — READ the screenshot, log the step. Act on what you see: click, scroll, type, then re-observe, logging each step. Prefer aria (cheap text) to find controls; screenshot when the view changes and for your final verdict frames (one desktop, one mobile). If a click exits non-zero, do NOT retry the same ref blindly: re-run aria first (refs go stale between invocations), then click the fresh ref exactly once. If it still fails, log the failure and move on — a flaky control is a finding, not a loop.\n" +
         "d. Reach: with the session protocol, any flow reachable by N in-page actions is drivable — open the dialog, then confirm it, then judge the result. Without a session (one-shot invocations), anything reachable by (navigate, one action) is testable and sequences needing prior in-page state are not — use a session for those. Report NOT POSSIBLE only when the tooling itself fails (session-start exits 3): a flow you could not reach is not NOT POSSIBLE — name the exact step that stopped you in verdict.json's missing evidence and continue with the mechanical checks.\n" +
         "e. Judge as a user against the task description: is the reported bug fixed AND is nothing else visibly broken? Look for broken layout, overflow, missing or wrong content, stale data, and console errors. Compare against the task's expected behavior, never against source code (you are code-blind). Every frame you captured is already archived under " + crewHome + "/task-evidence/" + taskId + "/postchange/ and indexed in ooda-log.jsonl. A frame you did not read is not evidence. Loading, error, or blank frames never pass. If you cannot complete the loop, say exactly which steps are missing — unknown is not PASS.\n" +
-        (projectConfig.versioned_build === true ?
-        "e2. VERSION (issue #3): footer shows `build <n>` — report `footer_build: <n>` on its own line, or `footer_build: unreadable`. Required — the gate cannot pass without it.\n" : "") +
         "f. Kill ONLY the server you started: pkill -f 'serve-artifact[.]js.*--tag " + taskId + "-qa' — never another task's server. (The [.] keeps pkill from matching its own command line.) Do not leave it running.\n" +
         "Then continue with the mechanical checks below. Your VERDICT covers both the visual and the mechanical checks.\n\n" +
         "MECHANICAL CHECKS:\n" +
@@ -2659,20 +2669,24 @@ while (i < STEPS.length) {
   // never a park. No automatic FAIL override: if the QA agent still
   // reports FAIL, it stands — finding attribution informs follow-up
   // filing only.
-  if (step.name === "QA") {
-    if (projectConfig.versioned_build === true && qaArtifact && qaRequiredVersion !== null) {
-      var vgM = /footer_build:\s*(\d+|unreadable)/i.exec(workerText || "");
-      var vgS = (vgM && /^\d+$/.test(vgM[1])) ? parseInt(vgM[1], 10) : null;
-      var vgD = decideVersionGate(vgS, qaRequiredVersion);
-      if (!vgD.proceed) {
-        return await parkTask(vgD.reason + ": " + vgD.remedy + " [built=" + vgS + " required=" + qaRequiredVersion + "]");
-      }
-      await agent(
-        "Run in shell and return the stdout verbatim:\n" + crewCmd("log-event", {
-          task_id: taskId, type: "note", identity: step.identity,
-          message: "version-check: built=" + vgS + " >= required=" + qaRequiredVersion + " → testing now" }),
-        { key: "record-version-check-" + taskId, label: "Recording version-gate pass" }
+  if (step.name === "QA" && qaBundleHash !== null) {
+    // Closeout: bundle Hazel tested must match ensure-deployed hash from QA
+    // start. Mismatch/unreadable = operational failure, never a park.
+    var closeHash = "";
+    try {
+      var closeResult = await agent(
+        "Run: node " + QA_DEPLOY + " --hash-only --qa-dir " + QA_ENV_DIR + " 2>&1\n" +
+        "Return JSON { \"output\": \"<stdout, trimmed>\" } and nothing else.",
+        { key: "qa-closeout-hash-" + taskId, label: "Reading QA bundle hash",
+          schema: { type: "object", properties: { output: { type: "string" } }, required: ["output"] } }
       );
+      var chm = /BUNDLE_HASH ([0-9a-f]{40})/.exec(String(closeResult.output || ""));
+      closeHash = chm ? chm[1].slice(0, 7) : "";
+    } catch (e) {}
+    if (closeHash !== qaBundleHash) {
+      log("QA closeout hash mismatch for task " + taskId + " — marking failed for retry");
+      stepResult.summary = (stepResult.summary || "") + "\nqa_closeout: FAILED — bundle hash " + (closeHash ? "changed during QA" : "unreadable");
+      passed = false;
     }
     var contentFindings = extractContentFindings(workerText);
     if (!contentFindings.ok) {
@@ -2803,6 +2817,26 @@ while (i < STEPS.length) {
     }
     if (/^VERIFIED:/m.test(integrateVerifyOut)) {
       log("Integrate verified for task " + taskId + ": task branch tip is an ancestor of the integration target");
+      // QA deploy: after verified merge, ensure QA env serves a bundle from
+      // merged source. Failed deploy = operational failure, never a park.
+      if (projectConfig.versioned_build === true && SURFACE_ARTIFACT) {
+        var deployOut = "";
+        try {
+          var deployResult = await runDeployFerry("");
+          deployOut = (deployResult.output || "").trim();
+        } catch (e) {
+          deployOut = "";
+        }
+        var deployParsed = parseDeployResult(deployOut);
+        if (deployParsed.ok) {
+          log("QA deploy ok for task " + taskId + ": bundle " + deployParsed.hash);
+          stepResult.summary = (stepResult.summary || "") + "\ndeploy: ok " + deployParsed.hash;
+        } else {
+          log("QA deploy failed for task " + taskId + ": " + deployParsed.reason + " — marking failed for retry");
+          stepResult.summary = (stepResult.summary || "") + "\ndeploy: FAILED — " + deployParsed.reason;
+          passed = false;
+        }
+      }
     } else {
       var integrateVerifyReason = integrateVerifyOut
         ? integrateVerifyOut.split("\n")[0].slice(0, 200)

package/workflows/chore.js

@@ -136,8 +136,14 @@ const CLASSIFY_SURFACE_SRC = crewHome + "/current/lib/classify-surface.js";
 const CLASSIFY_SURFACE = RUN_LIB + "/classify-surface.js";
 const NOTE_VOCAB_SRC = crewHome + "/current/lib/publish-note-vocabulary.js";
 const NOTE_VOCAB = RUN_LIB + "/publish-note-vocabulary.js";
+const QA_DEPLOY_SRC = crewHome + "/current/lib/qa-deploy.mjs";
+const QA_DEPLOY = RUN_LIB + "/qa-deploy.mjs";
+const SERVE_ARTIFACT_SRC = crewHome + "/current/lib/serve-artifact.js";
+const SERVE_ARTIFACT = RUN_LIB + "/serve-artifact.js";
+const QA_DB_SRC = crewHome + "/current/lib/qa-db.js";
+const QA_DB = RUN_LIB + "/qa-db.js";
 // See docs/decisions/qa-reproduce.md#pin-basenames: the pin step materializes the required scripts.
-const PIN_BASENAMES = [LIFECYCLE, MERGE_LOCK, PUBLISH_NPM, CREW_API_PINNED, SCHEMA_SQL_PINNED, COMPUTE_DIFF, CLASSIFY_SURFACE, NOTE_VOCAB].map(function (p) { return p.split("/").pop(); });
+const PIN_BASENAMES = [LIFECYCLE, MERGE_LOCK, PUBLISH_NPM, CREW_API_PINNED, SCHEMA_SQL_PINNED, COMPUTE_DIFF, CLASSIFY_SURFACE, NOTE_VOCAB, QA_DEPLOY, SERVE_ARTIFACT, QA_DB].map(function (p) { return p.split("/").pop(); });
 
 // Project config — passed by dispatcher, falls back to dashboard defaults
 const projectConfig = inputs.project_config || {};
@@ -275,7 +281,7 @@ function attemptKey(base, reworkCount) {
 function pinLifecycle(key) {
   return agent(
     "Snapshot lifecycle scripts for version pinning.\n" +
-    "Run: mkdir -p " + RUN_LIB + " && cp " + LIFECYCLE_SRC + " " + LIFECYCLE + " && cp " + MERGE_LOCK_SRC + " " + MERGE_LOCK + " && cp " + PUBLISH_NPM_SRC + " " + PUBLISH_NPM + " && cp " + CREW_API_SRC + " " + CREW_API_PINNED + " && cp " + SCHEMA_SQL_SRC + " " + SCHEMA_SQL_PINNED + " && cp " + COMPUTE_DIFF_SRC + " " + COMPUTE_DIFF + " && cp " + CLASSIFY_SURFACE_SRC + " " + CLASSIFY_SURFACE + " && cp " + NOTE_VOCAB_SRC + " " + NOTE_VOCAB + " && chmod +x " + LIFECYCLE + " " + MERGE_LOCK + " " + PUBLISH_NPM + " && ls -1 " + RUN_LIB + "\n" +
+    "Run: mkdir -p " + RUN_LIB + " && cp " + LIFECYCLE_SRC + " " + LIFECYCLE + " && cp " + MERGE_LOCK_SRC + " " + MERGE_LOCK + " && cp " + PUBLISH_NPM_SRC + " " + PUBLISH_NPM + " && cp " + CREW_API_SRC + " " + CREW_API_PINNED + " && cp " + SCHEMA_SQL_SRC + " " + SCHEMA_SQL_PINNED + " && cp " + COMPUTE_DIFF_SRC + " " + COMPUTE_DIFF + " && cp " + CLASSIFY_SURFACE_SRC + " " + CLASSIFY_SURFACE + " && cp " + NOTE_VOCAB_SRC + " " + NOTE_VOCAB + " && cp " + QA_DEPLOY_SRC + " " + QA_DEPLOY + " && cp " + SERVE_ARTIFACT_SRC + " " + SERVE_ARTIFACT + " && cp " + QA_DB_SRC + " " + QA_DB + " && chmod +x " + LIFECYCLE + " " + MERGE_LOCK + " " + PUBLISH_NPM + " && ls -1 " + RUN_LIB + "\n" +
     "Return the verbatim output of the ls -1 command as { \"listing\": \"<verbatim output>\" } and nothing else.",
     { key: key, label: "Pinning lifecycle scripts",
       schema: { type: "object", properties: { listing: { type: "string" } }, required: ["listing"] } }

package/workflows/crew-dispatch.js

@@ -477,10 +477,9 @@ for (var pi = 0; pi < projects.length; pi++) {
     // terminal | null=unclassified). Carried alongside deploy_type — it is a
     // separate axis, not a redeclaration of the deployment target.
     environment_type: proj.environment_type || null,
-    // QA staleness gate (emojimanegg1/muse-crew#3): versioned_build opts the
-    // project into the Integrate version bump + QA bundle-freshness gate;
-    // version_file is the repo-relative path of the TS file exporting
-    // BUILD_NUMBER (null when unversioned).
+    // QA deploy (replaces the issue #3 version gate): versioned_build opts the
+    // project into the post-Integrate QA deploy + pre-QA ensure-deployed;
+    // version_file is retained for compatibility but no longer consumed.
     versioned_build: !!proj.versioned_build,
     version_file: proj.version_file || null
   };

package/workflows/standard.js

@@ -80,8 +80,14 @@ const CLASSIFY_SURFACE_SRC = crewHome + "/current/lib/classify-surface.js";
 const CLASSIFY_SURFACE = RUN_LIB + "/classify-surface.js";
 const NOTE_VOCAB_SRC = crewHome + "/current/lib/publish-note-vocabulary.js";
 const NOTE_VOCAB = RUN_LIB + "/publish-note-vocabulary.js";
+const QA_DEPLOY_SRC = crewHome + "/current/lib/qa-deploy.mjs";
+const QA_DEPLOY = RUN_LIB + "/qa-deploy.mjs";
+const SERVE_ARTIFACT_SRC = crewHome + "/current/lib/serve-artifact.js";
+const SERVE_ARTIFACT = RUN_LIB + "/serve-artifact.js";
+const QA_DB_SRC = crewHome + "/current/lib/qa-db.js";
+const QA_DB = RUN_LIB + "/qa-db.js";
 // See docs/decisions/qa-reproduce.md#pin-basenames: the pin step materializes the required scripts.
-const PIN_BASENAMES = [LIFECYCLE, MERGE_LOCK, PUBLISH_NPM, CREW_API_PINNED, SCHEMA_SQL_PINNED, COMPUTE_DIFF, CLASSIFY_SURFACE, NOTE_VOCAB].map(function (p) { return p.split("/").pop(); });
+const PIN_BASENAMES = [LIFECYCLE, MERGE_LOCK, PUBLISH_NPM, CREW_API_PINNED, SCHEMA_SQL_PINNED, COMPUTE_DIFF, CLASSIFY_SURFACE, NOTE_VOCAB, QA_DEPLOY, SERVE_ARTIFACT, QA_DB].map(function (p) { return p.split("/").pop(); });
 
 // Project config — passed by dispatcher, falls back to dashboard defaults
 const projectConfig = inputs.project_config || {};
@@ -273,7 +279,7 @@ function attemptKey(base, reworkCount) {
 function pinLifecycle(key) {
   return agent(
     "Snapshot lifecycle scripts for version pinning.\n" +
-    "Run: mkdir -p " + RUN_LIB + " && cp " + LIFECYCLE_SRC + " " + LIFECYCLE + " && cp " + MERGE_LOCK_SRC + " " + MERGE_LOCK + " && cp " + PUBLISH_NPM_SRC + " " + PUBLISH_NPM + " && cp " + CREW_API_SRC + " " + CREW_API_PINNED + " && cp " + SCHEMA_SQL_SRC + " " + SCHEMA_SQL_PINNED + " && cp " + COMPUTE_DIFF_SRC + " " + COMPUTE_DIFF + " && cp " + CLASSIFY_SURFACE_SRC + " " + CLASSIFY_SURFACE + " && cp " + NOTE_VOCAB_SRC + " " + NOTE_VOCAB + " && chmod +x " + LIFECYCLE + " " + MERGE_LOCK + " " + PUBLISH_NPM + " && ls -1 " + RUN_LIB + "\n" +
+    "Run: mkdir -p " + RUN_LIB + " && cp " + LIFECYCLE_SRC + " " + LIFECYCLE + " && cp " + MERGE_LOCK_SRC + " " + MERGE_LOCK + " && cp " + PUBLISH_NPM_SRC + " " + PUBLISH_NPM + " && cp " + CREW_API_SRC + " " + CREW_API_PINNED + " && cp " + SCHEMA_SQL_SRC + " " + SCHEMA_SQL_PINNED + " && cp " + COMPUTE_DIFF_SRC + " " + COMPUTE_DIFF + " && cp " + CLASSIFY_SURFACE_SRC + " " + CLASSIFY_SURFACE + " && cp " + NOTE_VOCAB_SRC + " " + NOTE_VOCAB + " && cp " + QA_DEPLOY_SRC + " " + QA_DEPLOY + " && cp " + SERVE_ARTIFACT_SRC + " " + SERVE_ARTIFACT + " && cp " + QA_DB_SRC + " " + QA_DB + " && chmod +x " + LIFECYCLE + " " + MERGE_LOCK + " " + PUBLISH_NPM + " && ls -1 " + RUN_LIB + "\n" +
     "Return the verbatim output of the ls -1 command as { \"listing\": \"<verbatim output>\" } and nothing else.",
     { key: key, label: "Pinning lifecycle scripts",
       schema: { type: "object", properties: { listing: { type: "string" } }, required: ["listing"] } }
@@ -571,17 +577,37 @@ function decideIntegrateRetry(o) {
   if (rec.malformed) return "park";
   return ancestor ? "skip-to-publish" : "proceed";
 }
-// QA version gate (issue #3): S=footer build, R=required. S>=R proves the
-// bundle is at/past the merge (single-branch: version order = containment).
-// Pure — pinned by tests/version-gate.test.js. Null = unreadable/missing.
-function decideVersionGate(S, R) {
-  if (!(R > 0)) return { proceed: false, reason: "qa-version-missing",
-    remedy: "no build version recorded — re-run Integrate or record dashboard-version." };
-  if (!(S > 0)) return { proceed: false, reason: "qa-version-unreadable",
-    remedy: "no readable build number in bundle footer — rebuild from versioned source." };
-  if (S >= R) return { proceed: true };
-  return { proceed: false, reason: "qa-bundle-stale",
-    remedy: "bundle build " + S + " behind required " + R + " — builder did not rebuild from current source." };
+// QA deploy result parser (replaces the version gate, issue #3): the ferry
+// returns qa-deploy.mjs's stdout verbatim; the marker line is the only
+// machine-read signal. Pure — fails closed on anything unrecognized.
+// Returns { ok, hash } or { ok:false, reason }.
+function parseDeployResult(output) {
+  var m = /^DEPLOY_OK ([0-9a-f]{7})$/m.exec(String(output || "").trim());
+  if (m) return { ok: true, hash: m[1] };
+  var f = /^DEPLOY_FAIL ([a-z-]+):(.{1,200})$/m.exec(String(output || "").trim());
+  if (f) return { ok: false, reason: f[1] + ": " + f[2].trim() };
+  return { ok: false, reason: "unrecognized deploy output" };
+}
+// QA environment dir — pipeline-owned, under the crew home. The web artifact
+// directory (~/workspace/ts-spaces/<slug>/) is never built by hand (its own
+// AGENTS.md forbids it); this separate dir is cloned, synced, built, and
+// validated by qa-deploy.mjs. Named by project id (deploy_slug is an
+// artifact-system concern; the QA env is ours).
+var QA_ENV_DIR = crewHome + "/qa-envs/" + LAUNCH_PROJECT_ID;
+// Run the deploy ferry: a thin mechanical agent that runs one exact pinned
+// command and returns stdout verbatim. No identity, no judgment — the
+// module self-records the full evidence via the Crew API; the ferry carries
+// only the marker line.
+function runDeployFerry(mode) {
+  var cmd = "node " + QA_DEPLOY + " --repo " + REPO_PATH + " --qa-dir " + QA_ENV_DIR +
+    " --task " + taskId + " --crew-home " + crewHome + " --crew-api " + CREW_API_PINNED +
+    " --serve-artifact " + SERVE_ARTIFACT + (mode === "--ensure" ? " --ensure" : "") + " 2>&1";
+  return agent(
+    "Run in shell and return the stdout verbatim:\n" + cmd + "\n" +
+    "Return JSON { \"output\": \"<the command's full stdout, trimmed>\" } and nothing else.",
+    { key: "qa-deploy-" + mode.replace(/-/g, "") + "-" + taskId, label: "Deploying QA environment",
+      schema: { type: "object", properties: { output: { type: "string" } }, required: ["output"] } }
+  );
 }
 // On a dispatcher retry resumed at Integrate, the run-local releaseDecision
 // is null (Build doesn't re-run). Hydrate it from the merge record so the
@@ -1310,23 +1336,27 @@ while (i < STEPS.length) {
   // experiential-loop guard (a PASS with missing experiential evidence is
   // never terminal).
   var qaExperiential = false;
+  var qaBundleHash = null;
   if (step.name === "QA") {
     qaExperiential = (await resolveExperiential()) === "yes" && SURFACE_CLASSIFIED;
-    var qaRequiredVersion = null;
     if (qaExperiential && SURFACE_ARTIFACT && projectConfig.versioned_build === true) {
-      var vfileStd = projectConfig.version_file || "client/src/buildNumber.ts";
-      var vgPreStd = await agent(
-        "Return ONLY JSON. 1. Run, return stdout verbatim:\n" + crewCmd("get-events", { task_id: taskId }) + "\n" +
-        "R = integer after `dashboard-version: ` in newest matching note. 2. If none, run, return stdout verbatim:\n" + crewCmd("get-provenance", { project_id: LAUNCH_PROJECT_ID }) + "\n" +
-        "R = BUILD_NUMBER from: cd " + REPO_PATH + " && git show <source_commit>:" + vfileStd + " | grep -o 'BUILD_NUMBER = [0-9]*'. If unknown: {\"ok\":false,\"park\":\"qa-version-missing: no build version recorded — re-run Integrate or record dashboard-version.\"}. " +
-        "3. cd " + REPO_PATH + " && git fetch origin && V=$(grep -o 'BUILD_NUMBER = [0-9]*' " + vfileStd + " | grep -o '[0-9]*'|head -1); if [ $V -lt R ]; then git pull --ff-only; V=$(grep -o 'BUILD_NUMBER = [0-9]*' " + vfileStd + " | grep -o '[0-9]*'|head -1); fi; " +
-        "if [ $V -lt R ]: {\"ok\":false,\"park\":\"qa-bundle-stale: checkout \" + V + \" < required \" + R + \" — sync past the merge, re-run QA.\"}. 4. Else {\"ok\":true,\"R\":R}.",
-        { key: "qa-version-pre-" + taskId, label: "QA version-gate pre-check",
-          schema: { type: "object", required: ["ok"],
-            properties: { ok: { type: "boolean" }, R: { type: "integer" }, park: { type: "string" } } } }
-      );
-      if (!vgPreStd.ok) return await parkTask(vgPreStd.park);
-      qaRequiredVersion = vgPreStd.R;
+      // ensure-deployed: idempotent precondition. Fast path when the bundle
+      // is already current. Failed deploy = operational failure (retryable),
+      // never a park. The module self-records the bundle hash to the event log.
+      var ensureOut = "";
+      try {
+        var ensureResult = await runDeployFerry("--ensure");
+        ensureOut = (ensureResult.output || "").trim();
+      } catch (e) {
+        ensureOut = "";
+      }
+      var ensureParsed = parseDeployResult(ensureOut);
+      if (!ensureParsed.ok) {
+        log("QA ensure-deployed failed for task " + taskId + ": " + ensureParsed.reason + " — returning failed for dispatcher retry");
+        return { status: "failed", task_id: taskId, reason: "QA ensure-deployed failed: " + ensureParsed.reason };
+      }
+      qaBundleHash = ensureParsed.hash;
+      log("QA ensure-deployed ok for task " + taskId + ": bundle " + qaBundleHash);
     }
   }
 
@@ -1604,14 +1634,6 @@ while (i < STEPS.length) {
       "R5-PUSH (manual R5 resolution only — the normal path pushed inline). Run: " + LIFECYCLE_ENV + LIFECYCLE + " push-target " + taskId + "\n" +
       "PUSHED — report the merged hash (detached prints PUSHED: origin/main (refspec HEAD:main)), VERDICT: PASS; PUSH_SKIPPED — no push attempted (no record + no lock); NO_REMOTE_PUSH — no remote; VERDICT: PASS; ERROR or CONFLICT — report it, VERDICT: FAIL.\n" +
       "NEVER force-push.\n\n" +
-      (projectConfig.versioned_build === true ?
-      "VERSION BUMP (issue #3): after MERGED+PUSHED, bump so QA can prove the bundle contains this fix — QA parks without it.\n" +
-      "1. cd " + REPO_PATH + " && git fetch origin; BR=<branch-from-integration-target>; F=" + (projectConfig.version_file || "client/src/buildNumber.ts") + "\n" +
-      "2. N=$(git show origin/$BR:$F | grep -o 'BUILD_NUMBER = [0-9]*' | grep -o '[0-9]*'); if missing/unparsable: VERDICT: FAIL.\n" +
-      "3. Edit $F: `export const BUILD_NUMBER = $N;` → `export const BUILD_NUMBER = $((N+1));` (keep header comment).\n" +
-      "4. git add $F && git commit -m \"build-number: $((N+1)) - QA version gate\" (SEPARATE commit, never amend).\n" +
-      "5. git push origin $BR; if rejected retry 3x (fetch, re-read N, re-bump, re-commit, push). NEVER force-push. Push MUST succeed or VERDICT: FAIL.\n" +
-      "6. Run, return stdout verbatim:\n" + crewCmd("log-event", { task_id: taskId, type: "note", identity: step.identity, message: "dashboard-version: <new> — QA must test a bundle built from source at or after the merge that recorded this (build <new> or later)." }) + "\n(substitute <new>).\n\n" : "") +
       "Report what happened at each step, ending with exactly one line: VERDICT: PASS or VERDICT: FAIL.";
 
 } else if (step.name === "Publish") {
@@ -2065,8 +2087,6 @@ while (i < STEPS.length) {
         "c3. Start with: SEE_ACT_ARCHIVE_DIR=" + crewHome + "/task-evidence/" + taskId + "/postchange/ node " + crewHome + "/current/lib/see-act.js --url http://localhost:<N>/ aria — read the JSON, log the step. Then: SEE_ACT_ARCHIVE_DIR=" + crewHome + "/task-evidence/" + taskId + "/postchange/ node " + crewHome + "/current/lib/see-act.js --url http://localhost:<N>/ shot — READ the screenshot, log the step. Act on what you see: click, scroll, type, then re-observe, logging each step. Prefer aria (cheap text) to find controls; screenshot when the view changes and for your final verdict frames (one desktop, one mobile). If a click exits non-zero, do NOT retry the same ref blindly: re-run aria first (refs go stale between invocations), then click the fresh ref exactly once. If it still fails, log the failure and move on — a flaky control is a finding, not a loop.\n" +
         "d. Reach: with the session protocol, any flow reachable by N in-page actions is drivable — open the deck, then click Study, then judge the study view. Without a session (one-shot invocations), anything reachable by (navigate, one action) is testable and sequences needing prior in-page state are not — use a session for those. Report NOT POSSIBLE only when the tooling itself fails (session-start exits 3): a flow you could not reach is not NOT POSSIBLE — name the exact step that stopped you in verdict.json's missing evidence and judge what you did reach.\n" +
         "e. Judge as a user against the task description: does the change render correctly? Look for broken layout, overflow, missing or wrong content, stale data, and console errors. Compare against the task's expected behavior, never against source code (you are code-blind). Every frame you captured is already archived under " + crewHome + "/task-evidence/" + taskId + "/postchange/ and indexed in ooda-log.jsonl. A frame you did not read is not evidence. Loading, error, or blank frames never pass. If you cannot complete the loop, say exactly which steps are missing — unknown is not PASS.\n" +
-        (projectConfig.versioned_build === true ?
-        "e2. VERSION (issue #3): footer shows `build <n>` — report `footer_build: <n>` on its own line, or `footer_build: unreadable`. Required — the gate cannot pass without it.\n" : "") +
         "f. Kill ONLY the server you started: pkill -f 'serve-artifact[.]js.*--tag " + taskId + "-qa' — never another task's server. (The [.] keeps pkill from matching its own command line.) Do not leave it running.\n" +
         "Then continue with the mechanical checks below. Your VERDICT covers both the visual and the mechanical checks.\n\n" +
         "STEP 2: Verify data integrity via the crew API.\n" +
@@ -2411,20 +2431,24 @@ while (i < STEPS.length) {
   // never a park. No automatic FAIL override: if the QA agent still
   // reports FAIL, it stands — finding attribution informs follow-up
   // filing only.
-  if (step.name === "QA") {
-    if (projectConfig.versioned_build === true && SURFACE_ARTIFACT && qaRequiredVersion !== null) {
-      var vgM = /footer_build:\s*(\d+|unreadable)/i.exec(workerText || "");
-      var vgS = (vgM && /^\d+$/.test(vgM[1])) ? parseInt(vgM[1], 10) : null;
-      var vgD = decideVersionGate(vgS, qaRequiredVersion);
-      if (!vgD.proceed) {
-        return await parkTask(vgD.reason + ": " + vgD.remedy + " [built=" + vgS + " required=" + qaRequiredVersion + "]");
-      }
-      await agent(
-        "Run in shell and return the stdout verbatim:\n" + crewCmd("log-event", {
-          task_id: taskId, type: "note", identity: step.identity,
-          message: "version-check: built=" + vgS + " >= required=" + qaRequiredVersion + " → testing now" }),
-        { key: "record-version-check-" + taskId, label: "Recording version-gate pass" }
+  if (step.name === "QA" && qaBundleHash !== null) {
+    // Closeout: the bundle Hazel tested must match the ensure-deployed hash
+    // from QA start. Mismatch/unreadable = operational failure, never a park.
+    var closeHash = "";
+    try {
+      var closeResult = await agent(
+        "Run: node " + QA_DEPLOY + " --hash-only --qa-dir " + QA_ENV_DIR + " 2>&1\n" +
+        "Return JSON { \"output\": \"<stdout, trimmed>\" } and nothing else.",
+        { key: "qa-closeout-hash-" + taskId, label: "Reading QA bundle hash",
+          schema: { type: "object", properties: { output: { type: "string" } }, required: ["output"] } }
       );
+      var hm = /BUNDLE_HASH ([0-9a-f]{40})/.exec(String(closeResult.output || ""));
+      closeHash = hm ? hm[1].slice(0, 7) : "";
+    } catch (e) {}
+    if (closeHash !== qaBundleHash) {
+      log("QA closeout hash mismatch for task " + taskId + " — marking failed for retry");
+      stepResult.summary = (stepResult.summary || "") + "\nqa_closeout: FAILED — bundle hash " + (closeHash ? "changed during QA" : "unreadable");
+      passed = false;
     }
     var contentFindings = extractContentFindings(workerText);
     if (!contentFindings.ok) {
@@ -2555,6 +2579,29 @@ while (i < STEPS.length) {
     }
     if (/^VERIFIED:/m.test(integrateVerifyOut)) {
       log("Integrate verified for task " + taskId + ": task branch tip is an ancestor of the integration target");
+      // QA deploy (replaces the version gate): after a verified merge, ensure
+      // the QA environment serves a bundle built from merged source. Runs for
+      // versioned_build projects on a classified artifact surface; experiential
+      // tasks are the ones Hazel serves the bundle to. A failed deploy is an
+      // operational failure (retryable under the dispatcher's cap), never a park.
+      if (projectConfig.versioned_build === true && SURFACE_ARTIFACT) {
+        var deployOut = "";
+        try {
+          var deployResult = await runDeployFerry("");
+          deployOut = (deployResult.output || "").trim();
+        } catch (e) {
+          deployOut = "";
+        }
+        var deployParsed = parseDeployResult(deployOut);
+        if (deployParsed.ok) {
+          log("QA deploy ok for task " + taskId + ": bundle " + deployParsed.hash);
+          stepResult.summary = (stepResult.summary || "") + "\ndeploy: ok " + deployParsed.hash;
+        } else {
+          log("QA deploy failed for task " + taskId + ": " + deployParsed.reason + " — marking failed for retry");
+          stepResult.summary = (stepResult.summary || "") + "\ndeploy: FAILED — " + deployParsed.reason;
+          passed = false;
+        }
+      }
     } else {
       var integrateVerifyReason = integrateVerifyOut
         ? integrateVerifyOut.split("\n")[0].slice(0, 200)