muse-crew 0.14.13 → 0.16.0

package/API.md

@@ -489,6 +489,8 @@ Register a new project.
 | `quiesced` | boolean | no | Start paused; defaults to false |
 | `visual_protocol` | boolean or null | no | Tri-state: `null` = inherit crew default (off), `true` = enable for this project, `false` = explicit off. Defaults to null. |
 | `environment_type` | `artifact` · `terminal` · null | no | User-facing surface for experiential QA routing: `artifact` = a rendered web UI (Hazel drives it with the see-act browser loop), `terminal` = a CLI (Hazel drives it herself, keeping transcripts). `null` = unclassified: no experiential QA. `deploy_type` names the deployment target, but `deploy_type: "artifact"` remains a legacy artifact-surface signal so pre-field projects keep today's experiential QA (the migration does not backfill the column); on conflicting config artifact wins. Omitted means auto-classify from `repo_path` (see surface classification below); an explicit value, including explicit `null`, always wins. |
+| `versioned_build` | boolean | no | Opt-in to the QA staleness gate (issue #3): when true, Integrate bumps `BUILD_NUMBER` in `version_file` after each merge (separate commit, pushed), and QA verifies the tested bundle's footer `build <n>` is at/past the recorded version before testing. Defaults to false (unversioned); the migration does not backfill. |
+| `version_file` | string or null | no | Repo-relative path of the TypeScript file exporting `BUILD_NUMBER` (e.g. `client/src/buildNumber.ts`). Only meaningful when `versioned_build` is true; defaults to `client/src/buildNumber.ts` when omitted. |
 
 **Surface classification (repo-derived defaults):** when `repo_path` is provided and `environment_type` is omitted, `create-project` mechanically classifies the repo at registration via `lib/classify-surface.js` — `space.json` present → `artifact`; else a non-empty `package.json` `bin` → `terminal`; otherwise unclassified (`null`). The classifier never throws: bad paths and malformed files classify as unclassified. Classification only fills omitted fields — an explicitly supplied `environment_type` (including explicit `null`) always wins, and deploy defaults follow the *effective* surface, so an explicit `"terminal"` never triggers artifact deploy defaults.
 

package/lib/crew-api.js

@@ -73,6 +73,21 @@ function validateEnvironmentType(value) {
   if (value === "artifact" || value === "terminal") return value;
   throw usageError("environment_type must be 'artifact', 'terminal', or null.");
 }
+// versioned_build validation: boolean. undefined means "not provided"
+// (create: defaults to false; update: leaves the field alone). Coerces
+// truthy/falsy to 1/0 for the INTEGER column.
+function validateVersionedBuild(value) {
+  if (value === undefined) return undefined;
+  return value ? 1 : 0;
+}
+// version_file validation: string or null. undefined means "not provided"
+// (create: defaults to null; update: leaves the field alone). Empty string
+// is rejected — use null to clear.
+function validateVersionFile(value) {
+  if (value === undefined || value === null) return null;
+  if (typeof value === "string" && value.length > 0) return value;
+  throw usageError("version_file must be a non-empty string or null.");
+}
 
 // already_merged_sha validation (room #16 blocker 11, 2026-09-18): the
 // workflow-verified already-merged sha as structured session control state.
@@ -315,6 +330,24 @@ function openDb(crewHome) {
         if (!/duplicate column name/i.test(e.message)) throw e;
       }
     }
+    // Migration: add versioned_build + version_file columns if missing (QA
+    // staleness gate, emojimanegg1/muse-crew#3, 2026-09-24). Same idempotent
+    // PRAGMA-check pattern; versioned_build defaults 0 (unversioned by
+    // design, no backfill), version_file stays NULL.
+    if (!projectCols.some((c) => c.name === "versioned_build")) {
+      try {
+        db.exec("ALTER TABLE projects ADD COLUMN versioned_build INTEGER NOT NULL DEFAULT 0 CHECK (versioned_build IN (0, 1))");
+      } catch (e) {
+        if (!/duplicate column name/i.test(e.message)) throw e;
+      }
+    }
+    if (!projectCols.some((c) => c.name === "version_file")) {
+      try {
+        db.exec("ALTER TABLE projects ADD COLUMN version_file TEXT");
+      } catch (e) {
+        if (!/duplicate column name/i.test(e.message)) throw e;
+      }
+    }
     // Migration: per-project provenance columns (room #15 blocker 8,
     // 2026-09-18). Same idempotent PRAGMA-check pattern; ADD COLUMN without
     // a default leaves existing rows NULL, which is "no provenance yet" by
@@ -446,6 +479,9 @@ function mapProject(row) {
     // environment_type: 'artifact' | 'terminal' | null (unclassified).
     // Null stays null — no coercion, no default.
     environment_type: row.environment_type == null ? null : row.environment_type,
+    // versioned_build: 0/1 INTEGER → boolean. version_file: string or null.
+    versioned_build: !!row.versioned_build,
+    version_file: row.version_file == null ? null : row.version_file,
     created_at: row.created_at,
     updated_at: row.updated_at,
   };
@@ -3074,6 +3110,8 @@ commands["create-project"] = (db, args, ctx) => {
     quiesced: args.quiesced ? 1 : 0,
     visual_protocol: visualProtocol == null ? null : (visualProtocol ? 1 : 0),
     environment_type: environmentType,
+    versioned_build: validateVersionedBuild(args.versioned_build) ?? 0,
+    version_file: validateVersionFile(args.version_file),
     created_at: timestamp, updated_at: timestamp,
   };
   if (!Number.isInteger(row.simultaneity) || row.simultaneity < 1 || row.simultaneity > 100) {
@@ -3081,9 +3119,9 @@ commands["create-project"] = (db, args, ctx) => {
   }
   db.prepare(
     `INSERT INTO projects (id, display_name, repo_path, deploy_type, deploy_slug,
-      description, simultaneity, quiesced, visual_protocol, environment_type, created_at, updated_at)
+      description, simultaneity, quiesced, visual_protocol, environment_type, versioned_build, version_file, created_at, updated_at)
      VALUES (@id, @display_name, @repo_path, @deploy_type, @deploy_slug,
-      @description, @simultaneity, @quiesced, @visual_protocol, @environment_type, @created_at, @updated_at)`).run(row);
+      @description, @simultaneity, @quiesced, @visual_protocol, @environment_type, @versioned_build, @version_file, @created_at, @updated_at)`).run(row);
   // A deferred backfill (zero/ambiguous matches at the last look) gets one
   // more evaluation now that the match set changed: a new project whose
   // repo descends from the legacy commit inherits the attribution instead
@@ -3142,6 +3180,15 @@ commands["update-project"] = (db, args) => {
   if (args.environment_type !== undefined) {
     patch.environment_type = validateEnvironmentType(args.environment_type);
   }
+  // versioned_build / version_file are NOT covered by the context-change guard:
+  // like environment_type, they are read once from launch args at dispatch
+  // time, so a mid-run change only affects future launches.
+  if (args.versioned_build !== undefined) {
+    patch.versioned_build = validateVersionedBuild(args.versioned_build) ?? 0;
+  }
+  if (args.version_file !== undefined) {
+    patch.version_file = validateVersionFile(args.version_file);
+  }
 
   const contextChanged =
     (args.repo_path !== undefined && args.repo_path !== current.repo_path) ||

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

@@ -46,6 +46,13 @@ CREATE TABLE IF NOT EXISTS projects (
   provenance_crew_release TEXT,
   provenance_published_at TEXT,
   provenance_task_id TEXT,
+  -- versioned_build: the QA staleness gate (emojimanegg1/muse-crew#3). When 1,
+  -- Integrate bumps the version file and QA verifies the tested bundle is at
+  -- or past the required version. version_file is the repo-relative path to
+  -- the TS file exporting BUILD_NUMBER. Both nullable/0 by design: existing
+  -- rows stay unversioned (no backfill).
+  versioned_build INTEGER NOT NULL DEFAULT 0 CHECK (versioned_build IN (0, 1)),
+  version_file TEXT,
   created_at    TEXT NOT NULL,
   updated_at    TEXT NOT NULL
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "muse-crew",
-  "version": "0.14.13",
+  "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,6 +569,29 @@ function decideIntegrateRetry(o) {
   if (rec.malformed) return "park";
   return ancestor ? "skip-to-publish" : "proceed";
 }
+// 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
 // npm Publish gate doesn't park a publishable merge. Pure — pinned by
@@ -1355,10 +1384,29 @@ while (i < STEPS.length) {
   // verdicts.jsonl). No parent verdict gate remains.
   var qaArtifact = false;
   var qaTerminal = false;
+  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) {
+      // 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);
+    }
   }
 
   // Reproduce-layer routing (2026-09-16): Sage's Triage classifies the bug's
@@ -2621,7 +2669,25 @@ 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 (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) {
       // Unknown attribution fails closed: a missing or malformed
@@ -2751,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

@@ -476,7 +476,12 @@ for (var pi = 0; pi < projects.length; pi++) {
     // The user-facing surface for experiential QA routing (artifact |
     // 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
+    environment_type: proj.environment_type || null,
+    // 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,6 +577,38 @@ function decideIntegrateRetry(o) {
   if (rec.malformed) return "park";
   return ancestor ? "skip-to-publish" : "proceed";
 }
+// 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
 // npm Publish gate doesn't park a publishable merge. Pure — pinned by
@@ -1298,8 +1336,28 @@ 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;
+    if (qaExperiential && SURFACE_ARTIFACT && projectConfig.versioned_build === true) {
+      // 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);
+    }
   }
 
   // Step-specific instructions
@@ -2373,7 +2431,25 @@ 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 (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) {
       // Unknown attribution fails closed: a missing or malformed
@@ -2503,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)