muse-crew 0.12.0 → 0.13.1

package/lib/crew-api.js

@@ -65,6 +65,20 @@ function validateEnvironmentType(value) {
   throw usageError("environment_type must be 'artifact', 'terminal', or null.");
 }
 
+// already_merged_sha validation (room #16 blocker 11, 2026-09-18): the
+// workflow-verified already-merged sha as structured session control state.
+// undefined means "not provided" (preserves the existing value); explicit
+// null clears the field; otherwise a 7-40 hex string, normalized to
+// lowercase. Anything else is a usage error. The CHECK constraint in
+// schema.sql enforces the same shape at the SQL layer.
+// layer; this is the API-boundary validation.
+function validateAlreadyMergedSha(value) {
+  if (value === undefined || value === null) return null;
+  const s = String(value).trim().toLowerCase();
+  if (/^[0-9a-f]{7,40}$/.test(s)) return s;
+  throw usageError("already_merged_sha must be a 7-40 char hex string or null.");
+}
+
 // ---------------------------------------------------------------------------
 // Crew home resolution (fail closed)
 // ---------------------------------------------------------------------------
@@ -88,12 +102,148 @@ function resolveCrewHome(flagValue) {
 
 const SCHEMA_PATH = join(import.meta.dirname, "schema.sql");
 
+// Provenance shape rules, shared by the writer and the backfill's
+// pre-validation so they can never diverge (room #15, 2026-09-18).
+const PROVENANCE_SOURCE_COMMIT_RE = /^[0-9a-f]{40}$/;
+const PROVENANCE_CREW_RELEASE_RE = /^([0-9a-f]{40}|pkg-\d+\.\d+\.\d+)$/;
+
+// One-time backfill of the legacy crew-home-global provenance triple
+// (config.provenance.*) into the per-project provenance columns (room #15
+// blocker 8, 2026-09-18). Attribution is never fabricated: the legacy base
+// is stamped onto a project ONLY when it is an ancestor of exactly one
+// project's repo HEAD (verified with git, never assumed). Zero or ambiguous
+// matches are recorded as deferred:<reason> and the legacy keys are left
+// untouched — new readers see null (empty-tree first publish) while old
+// readers keep their global triple. Watermarked in config, so it runs at
+// most once per crew home. Benign edge: a legacy key written by the very
+// command whose open triggers the backfill is re-created after the DELETE
+// and lingers in config — inert dead storage, never read by new code.
+function backfillProjectProvenance(db) {
+  let wm = db.prepare("SELECT value FROM config WHERE key = 'provenance.backfill'").get();
+  if (wm && wm.value === "none") {
+    // "none" means "no legacy triple at the last look". A triple that
+    // arrives later (hand-written via update-config — the key space is
+    // open) is new evidence, not a settled state: clear the watermark and
+    // evaluate it. Any other watermark (stamped:*, deferred:*) is terminal.
+    const legacy = db.prepare(
+      "SELECT key FROM config WHERE key LIKE 'provenance.%' AND key != 'provenance.backfill'"
+    ).all();
+    if (legacy.length > 0) {
+      db.prepare("DELETE FROM config WHERE key = 'provenance.backfill'").run();
+      wm = null;
+    } else {
+      return;
+    }
+  }
+  if (wm) return;
+  const setWatermark = (v) =>
+    db.prepare("INSERT OR IGNORE INTO config (key, value) VALUES ('provenance.backfill', ?)").run(v);
+  const rows = db.prepare(
+    "SELECT key, value FROM config WHERE key IN ('provenance.source_commit','provenance.crew_release','provenance.published_at','provenance.task_id')"
+  ).all();
+  const byKey = Object.fromEntries(rows.map((r) => [r.key, r.value]));
+  const sc = byKey["provenance.source_commit"];
+  const cr = byKey["provenance.crew_release"];
+  const pa = byKey["provenance.published_at"];
+  if (!sc && !cr && !pa && !byKey["provenance.task_id"]) {
+    // No legacy provenance at all: nothing to attribute, ever.
+    setWatermark("none");
+    return;
+  }
+  if (!sc || !cr || !pa) {
+    // Incomplete triple (partial hand-write): do NOT watermark — the next
+    // open retries. Watermarking here would strand keys that arrive later.
+    return;
+  }
+  const matches = [];
+  for (const p of db.prepare("SELECT id, repo_path FROM projects").all()) {
+    try {
+      execFileSync("git", ["merge-base", "--is-ancestor", sc, "HEAD"],
+        { cwd: p.repo_path, encoding: "utf8", timeout: 10000, stdio: ["ignore", "pipe", "ignore"] });
+      matches.push(p.id);
+    } catch {
+      // Not an ancestor, or the repo is unreadable: not a match.
+    }
+  }
+  if (matches.length === 1) {
+    // Validate the legacy triple against the writer's shape rules BEFORE
+    // touching the database: a hand-written abbreviated sha passes
+    // `git merge-base --is-ancestor` (git resolves abbreviations) but
+    // violates the storage CHECK — and a throw here would escape openDb
+    // and hard-fail every CLI command against the home. The backfill's
+    // whole contract is best-effort attribution, so a bad shape is a
+    // deferred watermark, never an exception. Legacy keys are retained
+    // read-only for old readers, exactly like the other deferred cases.
+    const shapeProblem =
+      !PROVENANCE_SOURCE_COMMIT_RE.test(sc ?? "")
+        ? `source_commit not 40-char hex (${String(sc).slice(0, 24)})`
+        : !PROVENANCE_CREW_RELEASE_RE.test(cr ?? "")
+          ? `crew_release not 40-char hex or pkg-<semver> (${String(cr).slice(0, 24)})`
+          : null;
+    if (shapeProblem) {
+      setWatermark(`deferred:stamp-failed:${shapeProblem}`);
+    } else {
+      db.exec("BEGIN");
+      try {
+        db.prepare(
+          `UPDATE projects SET provenance_source_commit = ?, provenance_crew_release = ?,
+           provenance_published_at = ?, provenance_task_id = ?, updated_at = ? WHERE id = ?`
+        ).run(sc, cr, pa, byKey["provenance.task_id"] ?? null, now(), matches[0]);
+        db.prepare("DELETE FROM config WHERE key LIKE 'provenance.%' AND key != 'provenance.backfill'").run();
+        setWatermark(`stamped:${matches[0]}`);
+        db.exec("COMMIT");
+      } catch (e) {
+        db.exec("ROLLBACK");
+        const reason = String((e && e.message) || e).replace(/[\r\n]+/g, " ").slice(0, 100);
+        setWatermark(`deferred:stamp-failed:${reason}`);
+      }
+    }
+  } else if (matches.length === 0) {
+    setWatermark(`deferred:no-ancestor-match:${String(sc).slice(0, 7)}`);
+  } else {
+    setWatermark(`deferred:ambiguous:${matches.length}`);
+  }
+}
+
+// Re-run a deferred backfill when the match set may have changed: a new
+// project was just created, and a `deferred:no-ancestor-match` or
+// `deferred:ambiguous` watermark from an earlier look can now resolve —
+// e.g. a home whose legacy triple predates its first project. Only
+// deferred:* watermarks are retried, and only while the legacy keys still
+// exist (a successful stamp deleted them). Returns the stamped project id,
+// or null. Never throws for a bad triple — the evaluation watermarks
+// instead (see above); a throw here means the database itself is broken,
+// and failing project creation is then the honest outcome.
+function retryDeferredBackfill(db) {
+  const wm = db.prepare("SELECT value FROM config WHERE key = 'provenance.backfill'").get();
+  if (!wm || !String(wm.value).startsWith("deferred:")) return null;
+  const legacy = db.prepare(
+    "SELECT key FROM config WHERE key IN ('provenance.source_commit','provenance.crew_release','provenance.published_at')"
+  ).all();
+  if (legacy.length === 0) return null;
+  // Lift the terminal watermark, re-evaluate, and let the evaluation write
+  // the new one. If the re-evaluation throws (it shouldn't — every path
+  // watermarks), restore the old watermark so the deferral isn't lost.
+  const old = wm.value;
+  db.prepare("DELETE FROM config WHERE key = 'provenance.backfill'").run();
+  try {
+    backfillProjectProvenance(db);
+  } catch (e) {
+    db.prepare("INSERT OR IGNORE INTO config (key, value) VALUES ('provenance.backfill', ?)").run(old);
+    throw e;
+  }
+  const wm2 = db.prepare("SELECT value FROM config WHERE key = 'provenance.backfill'").get();
+  const m = wm2 && /^stamped:(.+)$/.exec(String(wm2.value));
+  return m ? m[1] : null;
+}
+
 function openDb(crewHome) {
   const dbPath = join(crewHome, "crew-state.db");
   const fresh = !existsSync(dbPath);
   const db = new DatabaseSync(dbPath);
   db.exec("PRAGMA journal_mode = WAL;");
   db.exec("PRAGMA foreign_keys = ON;");
+  db.exec("PRAGMA busy_timeout = 5000;");
   if (fresh) {
     const schema = readFileSync(SCHEMA_PATH, "utf8");
     db.exec(schema);
@@ -113,6 +263,23 @@ function openDb(crewHome) {
         if (!/duplicate column name/i.test(e.message)) throw e;
       }
     }
+    // Migration: add already_merged_sha column if missing (room #16 blocker
+    // 11, 2026-09-18). The workflow-verified already-merged sha as structured
+    // control state — Build's declaration used to travel to Review only
+    // through session notes, which are hard-capped at 3000 chars
+    // (record-phase below), so a truthful declaration at the report's tail
+    // never arrived. The workflow writes the sha here itself after the
+    // mechanical ancestor check; NULL = no verified declaration. Same
+    // idempotent PRAGMA-check pattern; no backfill (a missing value means
+    // "not verified", never fabricated).
+    if (!cols.some((c) => c.name === "already_merged_sha")) {
+      try {
+        db.exec("ALTER TABLE agent_sessions ADD COLUMN already_merged_sha TEXT CHECK (already_merged_sha IS NULL OR (already_merged_sha NOT GLOB '*[^0-9a-f]*' AND length(already_merged_sha) BETWEEN 7 AND 40))");
+      } catch (e) {
+        // Another process may have added it concurrently; ignore duplicate-column errors.
+        if (!/duplicate column name/i.test(e.message)) throw e;
+      }
+    }
     const projectCols = db.prepare("PRAGMA table_info(projects)").all();
     // Migration: add visual_protocol column if missing (per-project visual
     // protocol toggle, 2026-09-12). Same idempotent PRAGMA-check pattern;
@@ -139,6 +306,29 @@ function openDb(crewHome) {
         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
+    // design — attribution is never fabricated, so there is no backfill step
+    // here beyond the watermarked legacy-triple attribution below.
+    const provMigration = [
+      ["provenance_source_commit", "TEXT CHECK (provenance_source_commit IS NULL OR length(provenance_source_commit) = 40)"],
+      ["provenance_crew_release", "TEXT"],
+      ["provenance_published_at", "TEXT"],
+      ["provenance_task_id", "TEXT"],
+    ];
+    const provColNames = new Set(db.prepare("PRAGMA table_info(projects)").all().map((c) => c.name));
+    for (const [colName, colType] of provMigration) {
+      if (!provColNames.has(colName)) {
+        try {
+          db.exec(`ALTER TABLE projects ADD COLUMN ${colName} ${colType}`);
+        } catch (e) {
+          if (!/duplicate column name/i.test(e.message)) throw e;
+        }
+      }
+    }
+    // Legacy global-provenance backfill (watermarked, runs at most once).
+    backfillProjectProvenance(db);
   }
   return db;
 }
@@ -217,6 +407,10 @@ function mapSession(row) {
     caveats: parseCaveats(row.caveats),
     failure_reason: row.failure_reason,
     last_heartbeat: row.last_heartbeat ?? null,
+    // Room #16 blocker 11: the workflow-verified already-merged sha (NULL
+    // when no verified declaration). Structured control state — Review
+    // hydrates from this field, never from capped prose.
+    already_merged_sha: row.already_merged_sha ?? null,
   };
 }
 
@@ -276,7 +470,7 @@ function requireTask(db, id) {
 
 function requireProject(db, id) {
   const row = db.prepare("SELECT * FROM projects WHERE id = ?").get(id);
-  if (!row) throw notFound("Project not found.");
+  if (!row) throw notFound(`Project not found: "${id}" — check list-projects, or create it with create-project.`);
   return row;
 }
 
@@ -1181,18 +1375,24 @@ commands["upsert-session"] = (db, args) => {
     caveats: args.caveats === undefined ? (current?.caveats ?? "[]") : JSON.stringify(args.caveats),
     failure_reason: args.failure_reason === undefined ? (current?.failure_reason ?? null) : args.failure_reason,
     last_heartbeat: now(),
+    // Room #16 blocker 11: preserve the verified sha across upserts unless
+    // explicitly provided (validated at the API boundary).
+    already_merged_sha: args.already_merged_sha === undefined
+      ? (current?.already_merged_sha ?? null)
+      : validateAlreadyMergedSha(args.already_merged_sha),
   };
   if (current) {
     db.prepare(
       `UPDATE agent_sessions SET task_id=@task_id, identity=@identity, step=@step,
        status=@status, started_at=@started_at, ended_at=@ended_at, notes=@notes,
-       caveats=@caveats, failure_reason=@failure_reason, last_heartbeat=@last_heartbeat WHERE id=@id`).run(row);
+       caveats=@caveats, failure_reason=@failure_reason, last_heartbeat=@last_heartbeat,
+       already_merged_sha=@already_merged_sha WHERE id=@id`).run(row);
   } else {
     db.prepare(
       `INSERT INTO agent_sessions (id, task_id, identity, step, status, started_at,
-        ended_at, notes, caveats, failure_reason, last_heartbeat)
+        ended_at, notes, caveats, failure_reason, last_heartbeat, already_merged_sha)
        VALUES (@id, @task_id, @identity, @step, @status, @started_at,
-        @ended_at, @notes, @caveats, @failure_reason, @last_heartbeat)
+        @ended_at, @notes, @caveats, @failure_reason, @last_heartbeat, @already_merged_sha)
        ON CONFLICT DO NOTHING`).run(row);
   }
   return { session: mapSession(row) };
@@ -1263,16 +1463,27 @@ commands["get-events"] = (db, args) => {
 // against this code's own realpath (the release it is actually running
 // from). Unresolvable or disputed => throw fail-closed BEFORE the claim
 // transaction: provenance is never stamped with an unknown release.
-function resolveActiveRelease(crewHome) {
+//
+// Active-release resolution is split in two (room #15, 2026-09-18):
+// resolveActiveReleaseName (symlink only — for writers) below, and
+// resolveActiveRelease (symlink + self-path cross-check — for verifiers).
+function resolveActiveReleaseName(crewHome) {
   let linkTarget;
   try {
     linkTarget = readlinkSync(join(crewHome, "current"));
   } catch (e) {
     throw usageError(
-      `scan-verification-pending: cannot resolve the active release: ${join(crewHome, "current")} is not a readable symlink (${e.message}). Refusing to verify.`
+      `cannot resolve the active release: ${join(crewHome, "current")} is not a readable symlink (${e.message}).`
     );
   }
-  const activeRelease = basename(resolve(crewHome, linkTarget));
+  return basename(resolve(crewHome, linkTarget));
+}
+// The strict resolver for verifiers (scan-verification-pending): the symlink
+// answer PLUS the self-path cross-check — the running code must provably be
+// the active release's own crew-api.js before it stamps verification claims.
+// Stale cron bodies and mid-deploy swaps throw fail-closed here.
+function resolveActiveRelease(crewHome) {
+  const activeRelease = resolveActiveReleaseName(crewHome);
   const selfPath = new URL(import.meta.url).pathname;
   const selfMatch = selfPath.match(/releases\/([^/]+)\/lib\/crew-api\.js$/);
   if (!selfMatch) {
@@ -1545,6 +1756,10 @@ commands["record-phase"] = (db, args) => {
     caveats: session.caveats === undefined ? "[]" : JSON.stringify(session.caveats),
     failure_reason: session.failure_reason ?? null,
     last_heartbeat: timestamp,
+    // Room #16 blocker 11: the workflow-verified already-merged sha, written
+    // by the workflow itself after the mechanical ancestor check — never
+    // builder prose. Validated at the API boundary; NULL = not verified.
+    already_merged_sha: validateAlreadyMergedSha(session.already_merged_sha),
   };
   const eventRow = {
     id: uuid(), type: event.type, task_id: args.task_id,
@@ -1554,12 +1769,15 @@ commands["record-phase"] = (db, args) => {
   try {
     db.prepare(
       `INSERT INTO agent_sessions (id, task_id, identity, step, status, started_at,
-        ended_at, notes, caveats, failure_reason, last_heartbeat)
+        ended_at, notes, caveats, failure_reason, last_heartbeat, already_merged_sha)
        VALUES (@id, @task_id, @identity, @step, @status, @started_at,
-        @ended_at, @notes, @caveats, @failure_reason, @last_heartbeat)
+        @ended_at, @notes, @caveats, @failure_reason, @last_heartbeat, @already_merged_sha)
+       -- record-phase never clears already_merged_sha: a phase record is not a
+       -- field update, so both undefined and null preserve the existing value.
        ON CONFLICT(id) DO UPDATE SET status=@status, ended_at=@ended_at,
         notes=@notes, caveats=@caveats, failure_reason=@failure_reason,
-        last_heartbeat=@last_heartbeat`).run(sessionRow);
+        last_heartbeat=@last_heartbeat,
+        already_merged_sha=COALESCE(@already_merged_sha, already_merged_sha)`).run(sessionRow);
     db.prepare(
       `INSERT INTO events (id, type, task_id, identity, message, timestamp)
        VALUES (@id, @type, @task_id, @identity, @message, @timestamp)`).run(eventRow);
@@ -1575,39 +1793,49 @@ commands["record-phase"] = (db, args) => {
 // the JSON transport and over the 200-line budget. The artifact is built from
 // the repo checkout at registration time, so create-project stamps
 // source_commit = repo HEAD for artifact-deploy projects; the first publish
-// then diffs only the task's own changes. The stamp never clobbers an
-// existing one (provenance storage is crew-home-global, so a second artifact
-// project keeps the first stamp — per-project provenance is a known gap this
-// does not introduce). A skipped stamp is reported, never silent, and never
-// fails project creation.
-function initialProvenancePlan({ deployType, provenanceExists, headSha, releaseName }) {
+// The initial-provenance stamp at create-project time: an artifact project
+// opens with its publish base set to the repo HEAD at registration, so the
+// first publish diffs only the task's own changes. Per-project (room #15
+// blocker 8): the project row was just inserted, so it is unstamped by
+// construction — there is no "already stamped" skip; a second artifact
+// project gets its own row, never the first project's base. A skipped stamp
+// is reported, never silent, and never fails project creation.
+function initialProvenancePlan({ deployType, headSha, releaseName }) {
   if (deployType !== "artifact") return { stamped: false, reason: "deploy_type is not artifact" };
-  if (provenanceExists) return { stamped: false, reason: "provenance already stamped" };
   if (!headSha) return { stamped: false, reason: "repo HEAD is unresolvable (unborn repo?)" };
   if (!releaseName) return { stamped: false, reason: "active crew release is unresolvable" };
   return { stamped: true, source_commit: headSha, crew_release: releaseName };
 }
 
-function tryStampInitialProvenance(db, crewHome, repoPath, deployType) {
-  const keys = db.prepare(
-    "SELECT key FROM config WHERE key IN ('provenance.source_commit','provenance.crew_release','provenance.published_at')"
-  ).all().map((r) => r.key);
-  const provenanceExists = keys.length === 3;
+function tryStampInitialProvenance(db, projectId, crewHome, repoPath, deployType) {
   let headSha = null;
   try {
     headSha = execFileSync("git", ["rev-parse", "HEAD"],
-      { cwd: repoPath, encoding: "utf8", timeout: 10000 }).trim();
+      { cwd: repoPath, encoding: "utf8", timeout: 10000, stdio: ["ignore", "pipe", "ignore"] }).trim();
     if (!/^[0-9a-f]{40}$/.test(headSha)) headSha = null;
   } catch { headSha = null; }
   let releaseName = null;
-  try { releaseName = resolveActiveRelease(crewHome); } catch { releaseName = null; }
-  const plan = initialProvenancePlan({ deployType, provenanceExists, headSha, releaseName });
+  // Symlink-only resolution: the stamp records the crew home's ACTIVE
+  // release — it must not depend on which copy of this file is running.
+  // The strict self-path cross-check lives in resolveActiveRelease, used by
+  // scan-verification-pending; requiring it here silently skipped the stamp
+  // for every setup path that invokes crew-api.js outside the release tree
+  // (room #15: create-project through the npm package's own lib/).
+  try { releaseName = resolveActiveReleaseName(crewHome); } catch { releaseName = null; }
+  const plan = initialProvenancePlan({ deployType, headSha, releaseName });
   if (!plan.stamped) return plan;
-  const upsert = db.prepare(
-    "INSERT INTO config (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value");
-  upsert.run("provenance.source_commit", plan.source_commit);
-  upsert.run("provenance.crew_release", plan.crew_release);
-  upsert.run("provenance.published_at", now());
+  try {
+    stampProvenance(db, {
+      project_id: projectId,
+      source_commit: plan.source_commit,
+      crew_release: plan.crew_release,
+    });
+  } catch (e) {
+    // The stamp is best-effort: a writer rejection (e.g. a release name
+    // outside the stampable shape) skips the stamp, never the project.
+    // Reported via the reason, never silent.
+    return { stamped: false, reason: `initial stamp rejected: ${e.message}` };
+  }
   return plan;
 }
 
@@ -1675,7 +1903,17 @@ commands["create-project"] = (db, args, ctx) => {
       description, simultaneity, quiesced, visual_protocol, environment_type, 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);
-  const initialProvenance = tryStampInitialProvenance(db, ctx.crewHome, repoPath, deployType);
+  // 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
+  // of stranding the triple in config forever. When the backfill stamps
+  // this project, the initial stamp below is skipped — the legacy triple
+  // is a real publish record and must not be overwritten by the
+  // creation-time HEAD.
+  const backfillStampedId = retryDeferredBackfill(db);
+  const initialProvenance = backfillStampedId === id
+    ? { stamped: true, reason: "legacy backfill attributed this project; initial stamp skipped" }
+    : tryStampInitialProvenance(db, id, ctx.crewHome, repoPath, deployType);
   return { project: mapProject(row), initial_provenance: initialProvenance };
 };
 
@@ -1819,35 +2057,48 @@ commands["update-config"] = (db, args) => {
   return { ok: true };
 };
 
-commands["set-provenance"] = (db, args) => {
-  if (!/^[0-9a-f]{40}$/.test(args.source_commit ?? "")) throw usageError("source_commit must be 40-char hex.");
-  if (!/^([0-9a-f]{40}|pkg-\d+\.\d+\.\d+)$/.test(args.crew_release ?? "")) {
+// The single provenance writer (room #15 blocker 8). Every stamp flows
+// through here: set-provenance and create-project's initial stamp are thin
+// shells over it. Per-project by design — a crew home with N artifact
+// projects carries N independent publish bases, and stamping one project
+// never touches another's row.
+function stampProvenance(db, { project_id, source_commit, crew_release, published_at, task_id }) {
+  const pid = String(project_id ?? "").trim();
+  if (!pid) throw usageError("project_id is required — pass the project's id (see list-projects).");
+  requireProject(db, pid);
+  if (!PROVENANCE_SOURCE_COMMIT_RE.test(source_commit ?? "")) throw usageError("source_commit must be 40-char hex.");
+  if (!PROVENANCE_CREW_RELEASE_RE.test(crew_release ?? "")) {
     throw usageError("crew_release must be 40-char hex or pkg-<semver>.");
   }
   // task_id is optional; when present it must be 1-80 chars (matches dashboard contract).
-  const taskId = args.task_id ?? null;
-  if (taskId !== null && (typeof taskId !== "string" || taskId.trim().length < 1 || taskId.length > 80)) {
+  const tid = task_id ?? null;
+  if (tid !== null && (typeof tid !== "string" || tid.trim().length < 1 || tid.length > 80)) {
     throw usageError("task_id must be 1-80 chars when provided.");
   }
-  const upsert = db.prepare(
-    "INSERT INTO config (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value");
-  upsert.run("provenance.source_commit", args.source_commit);
-  upsert.run("provenance.crew_release", args.crew_release);
-  upsert.run("provenance.published_at", args.published_at ?? now());
-  if (taskId !== null) upsert.run("provenance.task_id", taskId);
-  return { ok: true };
+  db.prepare(
+    `UPDATE projects SET provenance_source_commit = ?, provenance_crew_release = ?,
+     provenance_published_at = ?, provenance_task_id = ?, updated_at = ?
+     WHERE id = ?`
+  ).run(source_commit, crew_release, published_at ?? now(), tid, now(), pid);
+  return { ok: true, project_id: pid };
+}
+
+commands["set-provenance"] = (db, args) => {
+  return stampProvenance(db, args ?? {});
 };
 
-commands["get-provenance"] = (db) => {
-  const rows = db.prepare("SELECT key, value FROM config WHERE key LIKE 'provenance.%'").all();
-  const byKey = Object.fromEntries(rows.map((r) => [r.key, r.value]));
-  const sc = byKey["provenance.source_commit"];
-  const cr = byKey["provenance.crew_release"];
-  const pa = byKey["provenance.published_at"];
-  if (!sc || !cr || !pa) return { provenance: null };
+commands["get-provenance"] = (db, args) => {
+  const pid = String((args ?? {}).project_id ?? "").trim();
+  if (!pid) throw usageError("project_id is required — pass the project's id (see list-projects).");
+  const row = requireProject(db, pid);
+  if (!row.provenance_source_commit || !row.provenance_crew_release || !row.provenance_published_at) {
+    return { provenance: null };
+  }
   return { provenance: {
-    source_commit: sc, crew_release: cr, published_at: pa,
-    task_id: byKey["provenance.task_id"] ?? null,
+    source_commit: row.provenance_source_commit,
+    crew_release: row.provenance_crew_release,
+    published_at: row.provenance_published_at,
+    task_id: row.provenance_task_id ?? null,
   } };
 };
 

package/lib/schema.sql

@@ -34,6 +34,18 @@ CREATE TABLE IF NOT EXISTS projects (
   -- deploy_type is NOT reused for this (it names the deployment target, not
   -- the UX surface a user experiences).
   environment_type TEXT CHECK (environment_type IN ('artifact', 'terminal')),
+  -- Per-project provenance (2026-09-18, room #15 blocker 8): each project
+  -- carries its own publish base. Provenance was crew-home-global
+  -- (config.provenance.*), which broke any multi-project home: the first
+  -- artifact project's stamp was read as the second project's base, parking
+  -- the second task with "not an ancestor". Nullable by design: a project
+  -- with no provenance reads null and its first publish diffs from the
+  -- empty tree. Never fabricated — the one-time backfill in openDb stamps
+  -- only an exactly-one-ancestor match, otherwise records deferred.
+  provenance_source_commit TEXT CHECK (provenance_source_commit IS NULL OR length(provenance_source_commit) = 40),
+  provenance_crew_release TEXT,
+  provenance_published_at TEXT,
+  provenance_task_id TEXT,
   created_at    TEXT NOT NULL,
   updated_at    TEXT NOT NULL
 );
@@ -81,7 +93,19 @@ CREATE TABLE IF NOT EXISTS agent_sessions (
   notes          TEXT NOT NULL DEFAULT '',
   caveats        TEXT NOT NULL DEFAULT '[]',
   failure_reason TEXT,
-  last_heartbeat TEXT
+  last_heartbeat TEXT,
+  -- Room #16 blocker 11 (2026-09-18): the workflow-verified already-merged
+  -- sha as structured control state. Build's `repo_diff: none
+  -- (already-merged: <sha>)` declaration used to travel to Review only
+  -- through capped prose (session notes are truncated at 3000 chars), so a
+  -- truthful declaration at the report's tail never arrived. The workflow
+  -- writes the sha here itself after the mechanical ancestor check — the
+  -- column is workflow-owned, never builder prose. NULL = no verified
+  -- declaration for this session. The CHECK enforces the full shape:
+  -- 7-40 lowercase hex chars (NOT GLOB '*[^0-9a-f]*' means no non-hex char
+  -- anywhere — GLOB '[0-9a-f]*' alone would only check the first char).
+  already_merged_sha TEXT CHECK (already_merged_sha IS NULL OR
+    (already_merged_sha NOT GLOB '*[^0-9a-f]*' AND length(already_merged_sha) BETWEEN 7 AND 40))
 );
 
 CREATE TABLE IF NOT EXISTS events (

package/lib/test-worktree-backend.sh

@@ -239,6 +239,35 @@ if git -C "$T5" log --name-only --format= | grep -q '^\.worktrees/'; then
 fi
 rm -rf "$T5"
 
+# post-deploy survives the crew's own gitignored non-empty .worktrees/
+# (2026-09-18, room #15 J3): the old `git add -A -- ':!.worktrees/'`
+# exited 1 on git 2.43.0 whenever setup's `.gitignore` entry ignored a
+# non-empty .worktrees/, and set -e killed post-deploy before "DEPLOYED:".
+T6=/tmp/crew-git-postdeploy-gitignore-test
+rm -rf "$T6"
+mkdir -p "$T6"
+git init -q -b main "$T6"
+git -C "$T6" config user.email test@test.t
+git -C "$T6" config user.name test
+echo base > "$T6/f.txt"
+echo ".worktrees/" > "$T6/.gitignore"
+git -C "$T6" add -A
+git -C "$T6" commit -qm base
+export CREW_REPO="$T6"
+export CREW_LIB="$REPO_DIR/lib"
+# Non-empty ignored .worktrees/, exactly the shape of real integrate state
+mkdir -p "$T6/.worktrees/pd2"
+printf 'task_id=pd2\nholder=test\n' > "$T6/.worktrees/pd2/.merge-lock"
+# A genuine user change the post-deploy commit should pick up
+echo userchange > "$T6/user.txt"
+out=$(bash "$LIFECYCLE" post-deploy "pd2") || fail "postdeploy-gitignore-test: post-deploy failed: $out"
+echo "$out" | grep -q '^DEPLOYED: ' || fail "postdeploy-gitignore-test: no DEPLOYED: line: $out"
+git -C "$T6" log --name-only --format= -1 | grep -q '^user\.txt$' || fail "postdeploy-gitignore-test: user change not committed"
+if git -C "$T6" log --name-only --format= | grep -q '^\.worktrees/'; then
+  fail "postdeploy-gitignore-test: .worktrees/ content committed into main"
+fi
+rm -rf "$T6"
+
 rm -rf "$T2" "$T3" "$T4"
 export CREW_REPO="$T"
 rm -rf "$T"

package/lib/verify-publish.js

@@ -23,7 +23,7 @@
 //   node verify-publish.js --crew-home <path> --task-id <uuid>
 //       --commit <sha> --base <sha> --repo-path <path> --slug <slug>
 //       --crew-release <release> --inspection-id <uuid> --result-file <path>
-//       [--build-agent-id <uuid>]
+//       --project-id <project-id> [--build-agent-id <uuid>]
 //
 // --base is the previously-stamped provenance source_commit (or the
 // empty-tree sha 4b825dc642cb6eb9a060e54bf8d69288fbee4904 for a first
@@ -66,6 +66,7 @@ const inspectionId = arg("--inspection-id");
 const resultFile = arg("--result-file");
 const crewRelease = arg("--crew-release");
 const buildAgentId = arg("--build-agent-id", false);
+const projectId = arg("--project-id");
 
 if (!/^[0-9a-f]{40}$/.test(commit)) fail("usage", "commit must be a 40-char hex sha.", 2);
 if (!/^[0-9a-f]{40}$/.test(base)) fail("usage", "base must be a 40-char hex sha.", 2);
@@ -334,7 +335,7 @@ if (buildAgentId && resultText.includes(buildAgentId)) buildNote = `build-id-cor
 // --- 7. Stamp (only after the machine-checked comparison succeeded) ---------
 let stamp;
 try {
-  stamp = api("set-provenance", { source_commit: commit, crew_release: crewRelease, task_id: taskId });
+  stamp = api("set-provenance", { project_id: projectId, source_commit: commit, crew_release: crewRelease, task_id: taskId });
 } catch (e) {
   terminal("stamp-failed", `set-provenance threw: ${e.message}`);
 }
@@ -342,7 +343,7 @@ if (!stamp || stamp.ok !== true) terminal("stamp-failed", "set-provenance did no
 // Exact read-back: the stamp must match what we intended, or it is fiction.
 let prov;
 try {
-  prov = api("get-provenance", {});
+  prov = api("get-provenance", { project_id: projectId });
 } catch (e) {
   terminal("stamp-failed", `get-provenance threw: ${e.message}`);
 }

package/lib/worktree-lifecycle.sh

@@ -416,9 +416,15 @@ cmd_post_deploy() {
 
   # Commit any changes the artifact builder left behind.
   # The crew's own .worktrees/ dir (merge lock, registry) is crew-owned
-  # state, never user content — exclude it so a stray lock file can never
-  # be committed into main (J1 canary: .merge-lock landed in main via add -A).
-  git add -A -- ':!.worktrees/'
+  # state, never user content — unstage it after the add so a stray lock
+  # file can never be committed into main (J1 canary: .merge-lock landed
+  # in main via add -A). Never use an all-negative pathspec here: on git
+  # 2.43.0 `git add -A -- ':!.worktrees/'` still exits 1 against the
+  # crew's own gitignored .worktrees/ (room #15, J3), and set -e then
+  # kills post-deploy before "DEPLOYED:". A plain add never errors on
+  # ignored paths; the reset covers pre-gitignore-entry repos too.
+  git add -A
+  git reset -q -- .worktrees/ 2>/dev/null || true
   if ! git diff --cached --quiet 2>/dev/null; then
     git commit -m "rebuild: $task_id"
     echo "COMMITTED: artifact builder changes"

package/package.json

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