@mstar-harness/engine 3.9.3 → 3.10.0

package/dist/audit.js

@@ -1,53 +1,90 @@
 // src/audit.ts
 import { execFileSync as execFileSync2 } from "node:child_process";
-import { existsSync as existsSync5, mkdirSync as mkdirSync4, readdirSync as readdirSync4, readFileSync as readFileSync5, rmdirSync as rmdirSync2, rmSync, writeFileSync as writeFileSync4 } from "node:fs";
-import { basename as basename3, join as join7, resolve as resolve7, sep as sep2 } from "node:path";
-
-// src/core.ts
-import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
-import { randomUUID } from "node:crypto";
-import { basename, dirname, join, resolve } from "node:path";
-function readJson(filePath) {
-  if (!existsSync(filePath))
-    return {};
-  const content = readFileSync(filePath, "utf8").trim();
-  if (!content)
-    return {};
-  try {
-    return JSON.parse(content);
-  } catch (error) {
-    throw new Error(`Invalid JSON in ${filePath}: ${error.message}`);
-  }
-}
-function writeJson(filePath, value) {
-  const parent = dirname(filePath);
-  mkdirSync(parent, { recursive: true });
-  const tmp = join(parent, `.${basename(filePath)}.${process.pid}.${randomUUID()}.tmp`);
-  try {
-    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}
-`, "utf8");
-    renameSync(tmp, filePath);
-  } catch (error) {
-    try {
-      unlinkSync(tmp);
-    } catch {}
-    throw error;
-  }
-}
+import { existsSync as existsSync7, mkdirSync as mkdirSync5, readdirSync as readdirSync5, readFileSync as readFileSync7, rmdirSync as rmdirSync3, writeFileSync as writeFileSync4 } from "node:fs";
+import { basename as basename5, join as join9, resolve as resolve9, sep as sep3 } from "node:path";
 
 // src/lease.ts
-import { mkdirSync as mkdirSync2, rmdirSync, statSync, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2 } from "node:fs";
-import { dirname as dirname2, isAbsolute, join as join2, resolve as resolve2 } from "node:path";
+import { mkdirSync, rmdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 import { AsyncLocalStorage } from "node:async_hooks";
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function violation(severity, code, message, fix) {
+  return { ok: false, severity, code, message, fix };
+}
+function validateNonEmptyString(violations, value, field, missingCode, invalidCode) {
+  if (value === undefined) {
+    violations.push(violation("high", missingCode, `missing required field: ${field}`));
+  } else if (typeof value !== "string" || value.trim() === "") {
+    violations.push(violation("medium", invalidCode, `${field} must be a non-empty string`));
+  }
+}
 var DATE_PART = String.raw`\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])`;
 var RFC3339_Z_RE = new RegExp(String.raw`^${DATE_PART}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$`);
 var DATE_ONLY_RE = new RegExp(String.raw`^${DATE_PART}$`);
+function isValidClaimedAt(value) {
+  return typeof value === "string" && (RFC3339_Z_RE.test(value) || DATE_ONLY_RE.test(value));
+}
+function validateExecutionLease(lease) {
+  const violations = [];
+  if (!isPlainObject(lease)) {
+    return {
+      ok: false,
+      violations: [
+        violation("high", "lease.execution-lease.invalid", "execution_lease must be an object — null and tombstone objects are invalid; writers delete the key on release")
+      ]
+    };
+  }
+  validateNonEmptyString(violations, lease.holder, "holder", "lease.execution-lease.missing-holder", "lease.execution-lease.invalid-holder");
+  if (lease.claimed_at === undefined) {
+    violations.push(violation("high", "lease.execution-lease.missing-claimed-at", "missing required field: claimed_at"));
+  } else if (!isValidClaimedAt(lease.claimed_at)) {
+    violations.push(violation("medium", "lease.execution-lease.invalid-claimed-at", "claimed_at must be an RFC 3339 UTC timestamp with explicit Z (e.g. 2026-07-22T02:30:00Z) or a YYYY-MM-DD date"));
+  }
+  if (lease.worktree_path === undefined) {
+    violations.push(violation("high", "lease.execution-lease.missing-worktree-path", "missing required field: worktree_path"));
+  } else if (typeof lease.worktree_path !== "string" || lease.worktree_path.trim() === "") {
+    violations.push(violation("medium", "lease.execution-lease.invalid-worktree-path", "worktree_path must be a non-empty string"));
+  } else if (!isAbsolute(lease.worktree_path)) {
+    violations.push(violation("medium", "lease.execution-lease.invalid-worktree-path", "worktree_path must be an absolute path — it identifies the dedicated feature-worktree root (a Git checkout distinct from the main worktree and the integration worktree)"));
+  }
+  validateNonEmptyString(violations, lease.working_branch, "working_branch", "lease.execution-lease.missing-working-branch", "lease.execution-lease.invalid-working-branch");
+  if (lease.session_label !== undefined && typeof lease.session_label !== "string") {
+    violations.push(violation("medium", "lease.execution-lease.invalid-session-label", "session_label must be a string (display only — never used for ownership comparison)"));
+  }
+  return { ok: violations.length === 0, violations };
+}
+function validateIntegrationMergeLease(lease) {
+  const violations = [];
+  if (!isPlainObject(lease)) {
+    return {
+      ok: false,
+      violations: [
+        violation("high", "lease.merge-lease.invalid", "integration_merge_lease must be an object — absent means unclaimed; null and tombstone objects are invalid; writers delete the key on release")
+      ]
+    };
+  }
+  validateNonEmptyString(violations, lease.holder, "holder", "lease.merge-lease.missing-holder", "lease.merge-lease.invalid-holder");
+  if (lease.claimed_at === undefined) {
+    violations.push(violation("high", "lease.merge-lease.missing-claimed-at", "missing required field: claimed_at"));
+  } else if (!isValidClaimedAt(lease.claimed_at)) {
+    violations.push(violation("medium", "lease.merge-lease.invalid-claimed-at", "claimed_at must be an RFC 3339 UTC timestamp with explicit Z (e.g. 2026-07-22T04:00:00Z) or a YYYY-MM-DD date"));
+  }
+  validateNonEmptyString(violations, lease.plan_id, "plan_id", "lease.merge-lease.missing-plan-id", "lease.merge-lease.invalid-plan-id");
+  validateNonEmptyString(violations, lease.source_branch, "source_branch", "lease.merge-lease.missing-source-branch", "lease.merge-lease.invalid-source-branch");
+  validateNonEmptyString(violations, lease.target_branch, "target_branch", "lease.merge-lease.missing-target-branch", "lease.merge-lease.invalid-target-branch");
+  if (lease.session_label !== undefined && typeof lease.session_label !== "string") {
+    violations.push(violation("medium", "lease.merge-lease.invalid-session-label", "session_label must be a string (display only — never used for ownership comparison)"));
+  }
+  return { ok: violations.length === 0, violations };
+}
 var STATUS_WRITE_LOCKDIR = ".status-write.lockdir";
 var LOCKDIR_HOLDER_PID = "holder.pid";
 var heldLockDirs = new AsyncLocalStorage;
 async function withStatusWriteLock(statusPath, fn, opts = {}) {
-  const lockDir = join2(dirname2(resolve2(statusPath)), STATUS_WRITE_LOCKDIR);
+  const lockDir = join(dirname(resolve(statusPath)), STATUS_WRITE_LOCKDIR);
   const held = heldLockDirs.getStore();
   if (held !== undefined && held.has(lockDir)) {
     throw new Error(`${lockDir} is already held by this process in this async context — withStatusWriteLock is not reentrant; a nested acquisition on the same status.json is a bug`);
@@ -58,7 +95,7 @@ async function withStatusWriteLock(statusPath, fn, opts = {}) {
   let acquired = null;
   for (;; ) {
     try {
-      mkdirSync2(lockDir);
+      mkdirSync(lockDir);
       const st = statSync(lockDir);
       acquired = { dev: st.dev, ino: st.ino };
       break;
@@ -72,7 +109,7 @@ async function withStatusWriteLock(statusPath, fn, opts = {}) {
     }
   }
   try {
-    writeFileSync2(join2(lockDir, LOCKDIR_HOLDER_PID), String(process.pid), "utf8");
+    writeFileSync(join(lockDir, LOCKDIR_HOLDER_PID), String(process.pid), "utf8");
   } catch {}
   const owns = held ?? new Set;
   owns.add(lockDir);
@@ -84,7 +121,7 @@ async function withStatusWriteLock(statusPath, fn, opts = {}) {
       const current = statSync(lockDir);
       if (acquired !== null && current.dev === acquired.dev && current.ino === acquired.ino) {
         try {
-          unlinkSync2(join2(lockDir, LOCKDIR_HOLDER_PID));
+          unlinkSync(join(lockDir, LOCKDIR_HOLDER_PID));
         } catch {}
         rmdirSync(lockDir);
       }
@@ -92,14 +129,384 @@ async function withStatusWriteLock(statusPath, fn, opts = {}) {
   }
 }
 
+// src/coordination-write.ts
+import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { basename, dirname as dirname2, isAbsolute as isAbsolute2, join as join2, resolve as resolve2 } from "node:path";
+class CoordinationError extends Error {
+  code;
+  details;
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "CoordinationError";
+    this.code = code;
+    this.details = details;
+  }
+}
+function isPlainObject2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+function artifactVersion(bytes) {
+  return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+function readArtifactBytes(filePath) {
+  if (!existsSync(filePath))
+    return;
+  const bytes = readFileSync(filePath);
+  const version = artifactVersion(bytes);
+  let payload;
+  try {
+    payload = JSON.parse(bytes.toString("utf8"));
+  } catch (error) {
+    throw new CoordinationError("coordination.store", `Invalid JSON in ${filePath}: ${error.message}`, {
+      path: filePath
+    });
+  }
+  return { payload, version };
+}
+function canonicalTarget(target) {
+  const abs = resolve2(target);
+  let dir = abs;
+  const tail = [];
+  for (;; ) {
+    if (existsSync(dir)) {
+      try {
+        return join2(realpathSync(dir), ...tail);
+      } catch {
+        return abs;
+      }
+    }
+    const parent = dirname2(dir);
+    if (parent === dir)
+      return abs;
+    tail.unshift(basename(dir));
+    dir = parent;
+  }
+}
+var writeAuthorizations = new AsyncLocalStorage2;
+async function withProtectedWrite(target, operation, fn) {
+  const inherited = writeAuthorizations.getStore() ?? [];
+  return writeAuthorizations.run([...inherited, { target: canonicalTarget(target), operation }], async () => fn());
+}
+function isWriteAuthorized(target, operation) {
+  const active = writeAuthorizations.getStore();
+  if (active === undefined || active.length === 0)
+    return false;
+  const canonical = canonicalTarget(target);
+  return active.some((entry) => entry.target === canonical && entry.operation === operation);
+}
+function assertProtectedWriteAuthorized(target, operation, kind) {
+  const canonical = canonicalTarget(target);
+  if (isWriteAuthorized(canonical, operation))
+    return;
+  throw new CoordinationError("coordination.direct-write-refused", `${canonical} is a protected coordination document (${kind}) — a raw store.${operation} is refused; use the coordination API (bind/prepare/progress/residual/handoff/accept/return/complete) or the locked writer`, { path: canonical, operation, kind });
+}
+var HANDOFF_STATES = [
+  "submitted",
+  "accepted",
+  "returned",
+  "integrating",
+  "merged",
+  "completed"
+];
+var PLAN_PROGRESS_STATUSES = ["InProgress", "InReview", "Blocked"];
+var SHA256_HEX = /^[0-9a-f]{64}$/;
+var GIT_SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+var HASH_RE = /^sha256:[0-9a-f]{64}$/;
+function invalid(code, message) {
+  return { ok: false, severity: "high", code, message };
+}
+function validateBinding(value, what) {
+  if (!isPlainObject2(value))
+    return [invalid("coordination.row.binding-shape", `${what} must be an object`)];
+  const violations = [];
+  const extra = Object.keys(value).filter((key) => !["session_id", "session_file", "bound_at"].includes(key));
+  if (extra.length > 0) {
+    violations.push(invalid("coordination.row.binding-field", `${what} has unexpected key(s): ${extra.join(", ")}`));
+  }
+  if (!isNonEmptyString(value.session_id)) {
+    violations.push(invalid("coordination.row.binding-field", `${what}.session_id must be a non-empty string`));
+  }
+  if (!isNonEmptyString(value.session_file) || !isAbsolute2(String(value.session_file))) {
+    violations.push(invalid("coordination.row.binding-field", `${what}.session_file must be an absolute path`));
+  }
+  if (!isNonEmptyString(value.bound_at)) {
+    violations.push(invalid("coordination.row.binding-field", `${what}.bound_at must be a timestamp`));
+  }
+  return violations;
+}
+function validateEvidenceRef(value, what) {
+  if (!isPlainObject2(value))
+    return [invalid("coordination.row.evidence-shape", `${what} must be a hash-pinned reference`)];
+  const violations = [];
+  const extra = Object.keys(value).filter((key) => !["path", "sha256"].includes(key));
+  if (extra.length > 0) {
+    violations.push(invalid("coordination.row.evidence-field", `${what} has unexpected key(s): ${extra.join(", ")}`));
+  }
+  if (!isNonEmptyString(value.path) || !isAbsolute2(String(value.path))) {
+    violations.push(invalid("coordination.row.evidence-field", `${what}.path must be an absolute path`));
+  }
+  if (!isNonEmptyString(value.sha256) || !SHA256_HEX.test(String(value.sha256))) {
+    violations.push(invalid("coordination.row.evidence-field", `${what}.sha256 must be 64 lowercase hex`));
+  }
+  return violations;
+}
+function validatePlanProgress(value, what = "coordination.progress") {
+  if (!isPlainObject2(value))
+    return [invalid("coordination.row.progress-shape", `${what} must be an object`)];
+  const violations = [];
+  const extra = Object.keys(value).filter((key) => !["status", "summary", "evidence_paths", "track_branches"].includes(key));
+  if (extra.length > 0) {
+    violations.push(invalid("coordination.row.progress-field", `${what} has unexpected key(s): ${extra.join(", ")}`));
+  }
+  if (!PLAN_PROGRESS_STATUSES.includes(value.status)) {
+    violations.push(invalid("coordination.row.progress-field", `${what}.status must be one of ${PLAN_PROGRESS_STATUSES.join(", ")}`));
+  }
+  if (!isNonEmptyString(value.summary)) {
+    violations.push(invalid("coordination.row.progress-field", `${what}.summary must be a non-empty string`));
+  }
+  if (!Array.isArray(value.evidence_paths) || !value.evidence_paths.every(isNonEmptyString)) {
+    violations.push(invalid("coordination.row.progress-field", `${what}.evidence_paths must be an array of paths`));
+  }
+  if (value.track_branches !== undefined) {
+    if (!Array.isArray(value.track_branches) || !value.track_branches.every(isNonEmptyString)) {
+      violations.push(invalid("coordination.row.progress-field", `${what}.track_branches must be an array of branch names`));
+    }
+  }
+  return violations;
+}
+function validatePlanHandoff(value, what = "coordination.handoff") {
+  if (!isPlainObject2(value))
+    return [invalid("coordination.row.handoff-shape", `${what} must be an object`)];
+  const allowed = [
+    "id",
+    "attempt",
+    "state",
+    "submitted_by",
+    "submitted_at",
+    "source_branch",
+    "source_sha",
+    "worktree_path",
+    "review_base",
+    "review_head",
+    "qc",
+    "qa",
+    "accepted_by",
+    "accepted_at",
+    "returned_at",
+    "return_reason",
+    "integration",
+    "completed_at"
+  ];
+  const violations = [];
+  const extra = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (extra.length > 0) {
+    violations.push(invalid("coordination.row.handoff-field", `${what} has unexpected key(s): ${extra.join(", ")}`));
+  }
+  const required = [
+    "id",
+    "attempt",
+    "state",
+    "submitted_by",
+    "submitted_at",
+    "source_branch",
+    "source_sha",
+    "worktree_path",
+    "review_base",
+    "review_head"
+  ];
+  for (const key of required) {
+    if (value[key] === undefined) {
+      violations.push(invalid("coordination.row.handoff-field", `${what}.${key} is required`));
+    }
+  }
+  if (!Number.isInteger(value.attempt) || value.attempt < 1) {
+    violations.push(invalid("coordination.row.handoff-field", `${what}.attempt must be a positive integer`));
+  }
+  if (!HANDOFF_STATES.includes(value.state)) {
+    violations.push(invalid("coordination.row.handoff-field", `${what}.state must be one of ${HANDOFF_STATES.join(", ")}`));
+  }
+  if (value.id !== undefined && !isNonEmptyString(value.id)) {
+    violations.push(invalid("coordination.row.handoff-field", `${what}.id must be a non-empty string`));
+  }
+  for (const key of ["source_sha", "review_base", "review_head"]) {
+    if (value[key] !== undefined && !GIT_SHA.test(String(value[key]))) {
+      violations.push(invalid("coordination.row.handoff-field", `${what}.${key} must be a 40-hex git object id`));
+    }
+  }
+  for (const key of ["submitted_at", "accepted_at", "returned_at", "completed_at"]) {
+    if (value[key] !== undefined && !isNonEmptyString(value[key])) {
+      violations.push(invalid("coordination.row.handoff-field", `${what}.${key} must be a timestamp`));
+    }
+  }
+  if (value.worktree_path !== undefined && (!isNonEmptyString(value.worktree_path) || !isAbsolute2(String(value.worktree_path)))) {
+    violations.push(invalid("coordination.row.handoff-field", `${what}.worktree_path must be an absolute path`));
+  }
+  if (value.qc !== undefined) {
+    if (!isPlainObject2(value.qc)) {
+      violations.push(invalid("coordination.row.handoff-shape", `${what}.qc must be an object`));
+    } else {
+      const qc = value.qc;
+      const qcExtra = Object.keys(qc).filter((key) => !["decision", "reports", "consolidated"].includes(key));
+      if (qcExtra.length > 0) {
+        violations.push(invalid("coordination.row.handoff-field", `${what}.qc has unexpected key(s): ${qcExtra.join(", ")}`));
+      }
+      if (!isNonEmptyString(qc.decision)) {
+        violations.push(invalid("coordination.row.handoff-field", `${what}.qc.decision must be a non-empty string`));
+      }
+      if (!Array.isArray(qc.reports) || qc.reports.length === 0) {
+        violations.push(invalid("coordination.row.handoff-field", `${what}.qc.reports must be a non-empty array`));
+      } else {
+        qc.reports.forEach((ref, index) => {
+          violations.push(...validateEvidenceRef(ref, `${what}.qc.reports[${index}]`));
+        });
+      }
+      violations.push(...validateEvidenceRef(qc.consolidated, `${what}.qc.consolidated`));
+    }
+  }
+  if (value.qa !== undefined) {
+    if (!isPlainObject2(value.qa)) {
+      violations.push(invalid("coordination.row.handoff-shape", `${what}.qa must be an object`));
+    } else {
+      const qa = value.qa;
+      const qaExtra = Object.keys(qa).filter((key) => !["gate", "decision", "report"].includes(key));
+      if (qaExtra.length > 0) {
+        violations.push(invalid("coordination.row.handoff-field", `${what}.qa has unexpected key(s): ${qaExtra.join(", ")}`));
+      }
+      if (!isNonEmptyString(qa.gate)) {
+        violations.push(invalid("coordination.row.handoff-field", `${what}.qa.gate must be a non-empty string`));
+      }
+      if (!isNonEmptyString(qa.decision)) {
+        violations.push(invalid("coordination.row.handoff-field", `${what}.qa.decision must be a non-empty string`));
+      }
+      violations.push(...validateEvidenceRef(qa.report, `${what}.qa.report`));
+    }
+  }
+  if (value.integration !== undefined) {
+    if (!isPlainObject2(value.integration)) {
+      violations.push(invalid("coordination.row.handoff-shape", `${what}.integration must be an object`));
+    } else {
+      const integration = value.integration;
+      const integrationAllowed = [
+        "target_branch",
+        "worktree_path",
+        "base_sha",
+        "started_at",
+        "result_sha",
+        "verified_at"
+      ];
+      const integrationExtra = Object.keys(integration).filter((key) => !integrationAllowed.includes(key));
+      if (integrationExtra.length > 0) {
+        violations.push(invalid("coordination.row.handoff-field", `${what}.integration has unexpected key(s): ${integrationExtra.join(", ")}`));
+      }
+      for (const key of ["target_branch", "worktree_path", "base_sha", "started_at"]) {
+        if (!isNonEmptyString(integration[key])) {
+          violations.push(invalid("coordination.row.handoff-field", `${what}.integration.${key} is required`));
+        }
+      }
+      for (const key of ["base_sha", "result_sha"]) {
+        if (integration[key] !== undefined && !GIT_SHA.test(String(integration[key]))) {
+          violations.push(invalid("coordination.row.handoff-field", `${what}.integration.${key} must be a 40-hex git object id`));
+        }
+      }
+      if (integration.result_sha !== undefined && integration.verified_at === undefined) {
+        violations.push(invalid("coordination.row.handoff-field", `${what}.integration.result_sha requires verified_at`));
+      }
+    }
+  }
+  if ((value.state === "integrating" || value.state === "merged" || value.state === "completed") && value.integration === undefined) {
+    violations.push(invalid("coordination.row.handoff-field", `${what}.state ${String(value.state)} requires integration`));
+  }
+  return violations;
+}
+function validatePreparedCoordination(value, what = "coordination.prepared") {
+  if (!isPlainObject2(value))
+    return [invalid("coordination.row.prepared-shape", `${what} must be an object`)];
+  const allowed = [
+    "assignment_path",
+    "assignment_sha256",
+    "plan_sha256",
+    "qa_gate",
+    "findings_cleanup",
+    "prepared_by",
+    "prepared_at"
+  ];
+  const violations = [];
+  const extra = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (extra.length > 0) {
+    violations.push(invalid("coordination.row.prepared-field", `${what} has unexpected key(s): ${extra.join(", ")}`));
+  }
+  for (const key of allowed) {
+    if (!isNonEmptyString(value[key])) {
+      violations.push(invalid("coordination.row.prepared-field", `${what}.${key} is required`));
+    }
+  }
+  if (value.assignment_path !== undefined && !isAbsolute2(String(value.assignment_path))) {
+    violations.push(invalid("coordination.row.prepared-field", `${what}.assignment_path must be absolute`));
+  }
+  for (const key of ["assignment_sha256", "plan_sha256"]) {
+    if (value[key] !== undefined && !SHA256_HEX.test(String(value[key]))) {
+      violations.push(invalid("coordination.row.prepared-field", `${what}.${key} must be 64 lowercase hex`));
+    }
+  }
+  return violations;
+}
+function validateRowCoordination(value, what = "coordination") {
+  if (!isPlainObject2(value))
+    return [invalid("coordination.row.shape", `${what} must be an object`)];
+  const allowed = ["revision", "prepared", "session", "progress", "handoff"];
+  const violations = [];
+  const extra = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (extra.length > 0) {
+    violations.push(invalid("coordination.row.field", `${what} has unexpected key(s): ${extra.join(", ")}`));
+  }
+  if (!Number.isInteger(value.revision) || value.revision < 0) {
+    violations.push(invalid("coordination.row.revision", `${what}.revision must be a non-negative integer`));
+  }
+  if (value.prepared !== undefined)
+    violations.push(...validatePreparedCoordination(value.prepared, `${what}.prepared`));
+  if (value.session !== undefined)
+    violations.push(...validateBinding(value.session, `${what}.session`));
+  if (value.progress !== undefined)
+    violations.push(...validatePlanProgress(value.progress, `${what}.progress`));
+  if (value.handoff !== undefined)
+    violations.push(...validatePlanHandoff(value.handoff, `${what}.handoff`));
+  if (value.handoff !== undefined && value.session === undefined) {
+    violations.push(invalid("coordination.row.handoff-field", `${what}.handoff requires a bound plan session`));
+  }
+  return violations;
+}
+function validateSnapshotCoordination(value, what = "coordination") {
+  if (!isPlainObject2(value))
+    return [invalid("coordination.snapshot.shape", `${what} must be an object`)];
+  const violations = [];
+  const extra = Object.keys(value).filter((key) => key !== "coordinator");
+  if (extra.length > 0) {
+    violations.push(invalid("coordination.snapshot.field", `${what} has unexpected key(s): ${extra.join(", ")}`));
+  }
+  if (value.coordinator === undefined) {
+    violations.push(invalid("coordination.snapshot.field", `${what}.coordinator is required`));
+  } else {
+    violations.push(...validateBinding(value.coordinator, `${what}.coordinator`));
+  }
+  return violations;
+}
+function isArtifactVersion(value) {
+  return typeof value === "string" && (value === "absent" || HASH_RE.test(value));
+}
+
 // src/path.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync3, readdirSync as readdirSync3, readFileSync as readFileSync4, realpathSync as realpathSync2, statSync as statSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { existsSync as existsSync6, mkdirSync as mkdirSync4, readdirSync as readdirSync4, readFileSync as readFileSync6, realpathSync as realpathSync3, statSync as statSync3, writeFileSync as writeFileSync3 } from "node:fs";
 import { execFileSync } from "node:child_process";
-import { basename as basename2, dirname as dirname5, isAbsolute as isAbsolute4, join as join6, relative as relative2, resolve as resolve6 } from "node:path";
+import { basename as basename4, dirname as dirname6, isAbsolute as isAbsolute6, join as join8, relative as relative2, resolve as resolve8 } from "node:path";
 
 // src/mstarc.ts
 import { readFileSync as readFileSync2, statSync as statSync2 } from "node:fs";
-import { dirname as dirname3, isAbsolute as isAbsolute2, join as join3, relative, resolve as resolve3 } from "node:path";
+import { dirname as dirname3, isAbsolute as isAbsolute3, join as join3, relative, resolve as resolve3 } from "node:path";
 var MSTARC_FILE = ".mstarc";
 var MSTARC_SECTION = "config";
 var MSTARC_HARNESS_DIR_KEY = "harness_dir";
@@ -183,21 +590,53 @@ function loadMstarc(startDir, boundary) {
 }
 function isAtOrBelow(dir, root) {
   const rel = relative(root, dir);
-  return rel === "" || !rel.startsWith("..") && !isAbsolute2(rel);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute3(rel);
+}
+
+// src/core.ts
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync3, renameSync, unlinkSync as unlinkSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { basename as basename2, dirname as dirname4, join as join4, resolve as resolve4 } from "node:path";
+function readJson(filePath) {
+  if (!existsSync2(filePath))
+    return {};
+  const content = readFileSync3(filePath, "utf8").trim();
+  if (!content)
+    return {};
+  try {
+    return JSON.parse(content);
+  } catch (error) {
+    throw new Error(`Invalid JSON in ${filePath}: ${error.message}`);
+  }
+}
+function writeJson(filePath, value) {
+  const parent = dirname4(filePath);
+  mkdirSync2(parent, { recursive: true });
+  const tmp = join4(parent, `.${basename2(filePath)}.${process.pid}.${randomUUID()}.tmp`);
+  try {
+    writeFileSync2(tmp, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+    renameSync(tmp, filePath);
+  } catch (error) {
+    try {
+      unlinkSync2(tmp);
+    } catch {}
+    throw error;
+  }
 }
 
 // src/status.ts
-import { existsSync as existsSync3, readFileSync as readFileSync3, readdirSync as readdirSync2, realpathSync } from "node:fs";
-import { dirname as dirname4, join as join5, resolve as resolve5, sep } from "node:path";
+import { existsSync as existsSync5, readFileSync as readFileSync5, readdirSync as readdirSync3, realpathSync as realpathSync2 } from "node:fs";
+import { dirname as dirname5, join as join7, resolve as resolve7, sep as sep2 } from "node:path";
 
 // src/store.ts
-import { existsSync as existsSync2, readdirSync, unlinkSync as unlinkSync3 } from "node:fs";
-import { isAbsolute as isAbsolute3, join as join4, resolve as resolve4 } from "node:path";
+import { existsSync as existsSync3, readdirSync, unlinkSync as unlinkSync3 } from "node:fs";
+import { basename as basename3, isAbsolute as isAbsolute4, join as join5, resolve as resolve5, sep } from "node:path";
 var PLAN_SHAPED_KEY_RE = /^[0-9]{8}-[a-z0-9-]+$/;
 function resolveArtifactPath(harnessRoot, ref) {
   const { kind, key } = ref;
   if (kind === "json") {
-    if (!isAbsolute3(key)) {
+    if (!isAbsolute4(key)) {
       throw new Error(`ArtifactStore json key must be an absolute path — got ${JSON.stringify(key)}`);
     }
     if (key.split(/[\\/]+/).includes("..")) {
@@ -210,18 +649,18 @@ function resolveArtifactPath(harnessRoot, ref) {
     if (key !== "root") {
       throw new Error(`ArtifactStore status key must be "root" — got ${JSON.stringify(key)}`);
     }
-    return join4(harnessRoot, "status.json");
+    return join5(harnessRoot, "status.json");
   }
   if (kind === "snapshot") {
-    return join4(resolveWorkflowDir(harnessRoot, { harnessDir: harnessRoot }), key, "snapshot.json");
+    return join5(resolveWorkflowDir(harnessRoot, { harnessDir: harnessRoot }), key, "snapshot.json");
   }
   if (kind === "residuals") {
-    return join4(resolveProjectDir(harnessRoot, { harnessDir: harnessRoot }), key, "residuals.json");
+    return join5(resolveProjectDir(harnessRoot, { harnessDir: harnessRoot }), key, "residuals.json");
   }
   if (PLAN_SHAPED_KEY_RE.test(key)) {
-    return join4(harnessRoot, "sdd", key, "review", "report.json");
+    return join5(harnessRoot, "sdd", key, "review", "report.json");
   }
-  return join4(harnessRoot, "sdd", "_reviews", `${key}.json`);
+  return join5(harnessRoot, "sdd", "_reviews", `${key}.json`);
 }
 function listDirNames(dir) {
   return readDirEntries(dir).filter((entry) => entry.isDirectory()).map((entry) => entry.name);
@@ -239,6 +678,26 @@ function readDirEntries(dir) {
     throw error;
   }
 }
+function protectedKindOf(root, ref, filePath) {
+  if (ref.kind === "status")
+    return "root";
+  if (ref.kind === "snapshot")
+    return "snapshot";
+  if (ref.kind === "residuals")
+    return "register";
+  if (ref.kind !== "json")
+    return null;
+  const canonical = canonicalTarget(filePath);
+  if (canonical === canonicalTarget(resolveArtifactPath(root, { kind: "status", key: "root" })))
+    return "root";
+  const workflowDir = canonicalTarget(resolveWorkflowDir(root, { harnessDir: root }));
+  if (basename3(canonical) === "snapshot.json" && canonical.startsWith(`${workflowDir}${sep}`))
+    return "snapshot";
+  const projectDir = canonicalTarget(resolveProjectDir(root, { harnessDir: root }));
+  if (basename3(canonical) === "residuals.json" && canonical.startsWith(`${projectDir}${sep}`))
+    return "register";
+  return null;
+}
 function tryResolveGetPath(root, kind, key) {
   try {
     return resolveArtifactPath(root, { kind, key });
@@ -247,24 +706,31 @@ function tryResolveGetPath(root, kind, key) {
   }
 }
 function createFsStore(harnessRoot) {
-  const root = resolve4(harnessRoot);
+  const root = resolve5(harnessRoot);
   return {
     root,
     async put(doc) {
       if (doc.schema !== undefined) {
         throw new Error("FsStore does not persist schema ids — omit --schema or inject a store module that persists it");
       }
-      writeJson(resolveArtifactPath(root, doc), doc.payload);
+      const filePath = resolveArtifactPath(root, doc);
+      const protectedKind = protectedKindOf(root, doc, filePath);
+      if (protectedKind !== null)
+        assertProtectedWriteAuthorized(filePath, "put", protectedKind);
+      writeJson(filePath, doc.payload);
     },
     async get(ref) {
       const filePath = resolveArtifactPath(root, ref);
-      if (!existsSync2(filePath))
+      if (!existsSync3(filePath))
         return;
       return readJson(filePath);
     },
     async delete(ref) {
       const filePath = resolveArtifactPath(root, ref);
-      if (existsSync2(filePath))
+      const protectedKind = protectedKindOf(root, ref, filePath);
+      if (protectedKind !== null)
+        assertProtectedWriteAuthorized(filePath, "delete", protectedKind);
+      if (existsSync3(filePath))
         unlinkSync3(filePath);
     },
     async list(kind) {
@@ -273,18 +739,18 @@ function createFsStore(harnessRoot) {
       }
       const keys = [];
       if (kind === "status") {
-        if (existsSync2(resolveArtifactPath(root, { kind, key: "root" })))
+        if (existsSync3(resolveArtifactPath(root, { kind, key: "root" })))
           keys.push("root");
       } else if (kind === "snapshot" || kind === "residuals") {
         const baseDir = kind === "snapshot" ? resolveWorkflowDir(root, { harnessDir: root }) : resolveProjectDir(root, { harnessDir: root });
         for (const name of listDirNames(baseDir)) {
           const getPath = tryResolveGetPath(root, kind, name);
-          if (getPath !== undefined && existsSync2(getPath))
+          if (getPath !== undefined && existsSync3(getPath))
             keys.push(name);
         }
       } else {
-        const sddDir = join4(root, "sdd");
-        for (const key of listJsonKeys(join4(sddDir, "_reviews"))) {
+        const sddDir = join5(root, "sdd");
+        for (const key of listJsonKeys(join5(sddDir, "_reviews"))) {
           if (!PLAN_SHAPED_KEY_RE.test(key) && tryResolveGetPath(root, kind, key) !== undefined) {
             keys.push(key);
           }
@@ -292,7 +758,7 @@ function createFsStore(harnessRoot) {
         for (const name of listDirNames(sddDir)) {
           if (PLAN_SHAPED_KEY_RE.test(name)) {
             const getPath = tryResolveGetPath(root, kind, name);
-            if (getPath !== undefined && existsSync2(getPath))
+            if (getPath !== undefined && existsSync3(getPath))
               keys.push(name);
           }
         }
@@ -307,7 +773,7 @@ function getArtifactStore() {
     return injectedStore;
   const root = resolveHarnessDir(process.cwd());
   if (root === null) {
-    throw new Error(`harness dir not found from ${resolve4(process.cwd())} — cannot create the default FsStore (run \`mstar harness scaffold\`, pass opts.harnessDir, or set MSTAR_HARNESS_DIR)`);
+    throw new Error(`harness dir not found from ${resolve5(process.cwd())} — cannot create the default FsStore (run \`mstar harness scaffold\`, pass opts.harnessDir, or set MSTAR_HARNESS_DIR)`);
   }
   return createFsStore(root);
 }
@@ -316,23 +782,302 @@ function assertFsStorePath(store, ref, expectedPath) {
   if (typeof root !== "string")
     return;
   const storePath = resolveArtifactPath(root, ref);
-  const expected = resolve4(expectedPath);
+  const expected = resolve5(expectedPath);
   if (storePath !== expected) {
     throw new Error(`routed writer path mismatch: the active FsStore resolves ${ref.kind}/${JSON.stringify(ref.key)} to ${JSON.stringify(storePath)} but the caller's target is ${JSON.stringify(expected)} — call setArtifactStore(createFsStore(<root>)) first when the write target differs from the active store's root`);
   }
 }
 
 // src/workflow.ts
+import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync4, readdirSync as readdirSync2, rmdirSync as rmdirSync2 } from "node:fs";
+import { isAbsolute as isAbsolute5, join as join6, resolve as resolve6 } from "node:path";
 var WORKFLOW_SNAPSHOT_FILE = "snapshot.json";
+var WORKFLOW_LIFECYCLE_STATUSES = ["running", "paused", "completed", "failed", "stopped"];
 var WORKFLOW_TERMINAL_STATUSES = ["completed", "failed", "stopped"];
 var WORKFLOW_LIFECYCLE_TYPES = ["plan", "iteration"];
+var WORKFLOW_DELIVERY_KINDS = ["development", "verification/report-only"];
+var WORKFLOW_COMPOUND_OUTCOMES = ["created", "updated", "skipped"];
+function stableJson(value) {
+  if (Array.isArray(value))
+    return `[${value.map(stableJson).join(",")}]`;
+  if (isPlainObject2(value)) {
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "undefined";
+}
+function violation2(severity, code, message, fix) {
+  return { ok: false, severity, code, message, fix };
+}
+function validateNonEmptyString2(violations, value, field, missingCode, invalidCode) {
+  if (value === undefined) {
+    violations.push(violation2("high", missingCode, `missing required field: ${field}`));
+  } else if (typeof value !== "string" || value.trim() === "") {
+    violations.push(violation2("medium", invalidCode, `${field} must be a non-empty string`));
+  }
+}
+function validateWorktreePathValue(violations, value, field) {
+  if (typeof value !== "string" || value.trim() === "" || !isAbsolute5(value)) {
+    violations.push(violation2("high", "workflow.snapshot.invalid-integration-worktree-path", `${field} must be a non-empty absolute path — got ${JSON.stringify(value)}`, "record the absolute integration checkout path (integration_worktree_path)"));
+  }
+}
+function deliveryEvidenceViolations(value, what) {
+  const violations = [];
+  const invalid2 = (message) => {
+    violations.push(violation2("medium", "workflow.snapshot.invalid-delivery-evidence", `${what}: ${message}`));
+  };
+  if (!isPlainObject2(value)) {
+    invalid2("must be an object");
+    return violations;
+  }
+  const members = ["compound", "pr", "merge", "completion"];
+  const unknownMembers = Object.keys(value).filter((key) => !members.includes(key));
+  if (unknownMembers.length > 0)
+    invalid2(`unknown member(s) ${unknownMembers.join(", ")} — expected ${members.join(" | ")}`);
+  const compound = value.compound;
+  if (compound !== undefined) {
+    if (!isPlainObject2(compound))
+      invalid2("compound must be an object");
+    else {
+      const unknown = Object.keys(compound).filter((key) => key !== "outcome" && key !== "reason");
+      if (unknown.length > 0)
+        invalid2(`compound has unknown key(s) ${unknown.join(", ")}`);
+      if (typeof compound.outcome !== "string" || !WORKFLOW_COMPOUND_OUTCOMES.includes(compound.outcome)) {
+        invalid2(`compound.outcome must be one of ${WORKFLOW_COMPOUND_OUTCOMES.join(" | ")} — got ${JSON.stringify(compound.outcome)}`);
+      } else if (compound.outcome === "skipped" && (typeof compound.reason !== "string" || compound.reason.trim() === "")) {
+        invalid2("compound reason is required when the disposition outcome is 'skipped' (contract §4c)");
+      } else if (compound.reason !== undefined && (typeof compound.reason !== "string" || compound.reason.trim() === "")) {
+        invalid2("compound.reason must be a non-empty string when given");
+      }
+    }
+  }
+  const stringMembers = {
+    pr: ["repo", "head", "target"],
+    merge: ["provider", "evidence"],
+    completion: ["policy", "evidence"]
+  };
+  for (const member of ["pr", "merge", "completion"]) {
+    const block = value[member];
+    if (block === undefined)
+      continue;
+    if (!isPlainObject2(block)) {
+      invalid2(`${member} must be an object`);
+      continue;
+    }
+    const fields = stringMembers[member];
+    const unknown = Object.keys(block).filter((key) => !fields.includes(key));
+    if (unknown.length > 0)
+      invalid2(`${member} has unknown key(s) ${unknown.join(", ")}`);
+    for (const field of fields) {
+      if (typeof block[field] !== "string" || block[field].trim() === "") {
+        invalid2(`${member}.${field} must be a non-empty string`);
+      }
+    }
+  }
+  return violations;
+}
+function validateWorkflowSnapshot(doc) {
+  const violations = [];
+  if (!isPlainObject2(doc)) {
+    return {
+      ok: false,
+      violations: [violation2("high", "workflow.snapshot.invalid", "workflow snapshot must be an object")]
+    };
+  }
+  if (doc.schema_version === undefined) {
+    violations.push(violation2("high", "workflow.snapshot.missing-schema-version", "missing required field: schema_version"));
+  } else if (doc.schema_version !== 1) {
+    violations.push(violation2("high", "workflow.snapshot.invalid-schema-version", `schema_version must be 1 — got ${JSON.stringify(doc.schema_version)} (version is reserved for the root file discriminator)`));
+  }
+  if (doc.version !== undefined) {
+    violations.push(violation2("medium", "workflow.snapshot.reserved-version", `top-level version is reserved for the root status.json discriminator — snapshots use schema_version; remove the version key (got ${JSON.stringify(doc.version)})`, "remove the version key from the snapshot"));
+  }
+  validateNonEmptyString2(violations, doc.id, "id", "workflow.snapshot.missing-id", "workflow.snapshot.invalid-id");
+  if (doc.type === undefined) {
+    violations.push(violation2("high", "workflow.snapshot.missing-type", "missing required field: type"));
+  } else if (typeof doc.type !== "string" || !WORKFLOW_LIFECYCLE_TYPES.includes(doc.type)) {
+    violations.push(violation2("medium", "workflow.snapshot.invalid-type", `type must be one of ${WORKFLOW_LIFECYCLE_TYPES.join(" | ")} — got ${JSON.stringify(doc.type)}`));
+  }
+  if (doc.status === undefined) {
+    violations.push(violation2("high", "workflow.snapshot.missing-status", "missing required field: status"));
+  } else if (typeof doc.status !== "string" || !WORKFLOW_LIFECYCLE_STATUSES.includes(doc.status)) {
+    violations.push(violation2("medium", "workflow.snapshot.invalid-status", `status must be one of ${WORKFLOW_LIFECYCLE_STATUSES.join(" | ")} — got ${JSON.stringify(doc.status)}`));
+  }
+  validateNonEmptyString2(violations, doc.started_at, "started_at", "workflow.snapshot.missing-started-at", "workflow.snapshot.invalid-started-at");
+  validateNonEmptyString2(violations, doc.updated_at, "updated_at", "workflow.snapshot.missing-updated-at", "workflow.snapshot.invalid-updated-at");
+  if (doc.ended_at !== undefined) {
+    validateNonEmptyString2(violations, doc.ended_at, "ended_at", "workflow.snapshot.missing-ended-at", "workflow.snapshot.invalid-ended-at");
+  }
+  if (doc.phase !== undefined && typeof doc.phase !== "string") {
+    violations.push(violation2("medium", "workflow.snapshot.invalid-phase", "phase must be a string (free-form phase machine label)"));
+  }
+  if (doc.plans === undefined) {
+    violations.push(violation2("high", "workflow.snapshot.missing-plans", "missing required field: plans"));
+  } else if (!Array.isArray(doc.plans)) {
+    violations.push(violation2("high", "workflow.snapshot.invalid-plans", "plans must be an array of legacy plan rows"));
+  } else {
+    for (const row of doc.plans) {
+      violations.push(...validatePlanRow(row).violations);
+      if (isPlainObject2(row) && row.execution_lease !== undefined) {
+        violations.push(...validateExecutionLease(row.execution_lease).violations);
+      }
+      if (isPlainObject2(row) && row.coordination !== undefined) {
+        violations.push(...validateRowCoordination(row.coordination, `plans[${String(row.id)}].coordination`));
+      }
+    }
+  }
+  if (doc.coordination !== undefined) {
+    violations.push(...validateSnapshotCoordination(doc.coordination));
+  }
+  if (doc.execution_policy !== undefined) {
+    if (!isPlainObject2(doc.execution_policy)) {
+      violations.push(violation2("medium", "workflow.snapshot.invalid-execution-policy", "execution_policy must be an object"));
+    }
+  }
+  if (doc.integration_merge_lease !== undefined) {
+    violations.push(...validateIntegrationMergeLease(doc.integration_merge_lease).violations);
+  }
+  if (doc.branch !== undefined) {
+    if (!isPlainObject2(doc.branch)) {
+      violations.push(violation2("medium", "workflow.snapshot.invalid-branch", "branch must be an object"));
+    } else {
+      for (const key of ["base", "source", "integration", "target"]) {
+        if (doc.branch[key] !== undefined && (typeof doc.branch[key] !== "string" || doc.branch[key].trim() === "")) {
+          violations.push(violation2("medium", "workflow.snapshot.invalid-branch", `branch.${key} must be a non-empty string`));
+        }
+      }
+    }
+  }
+  const legacyWorktreePath = doc.control_worktree_path;
+  const canonicalWorktreePath = doc.integration_worktree_path;
+  if (legacyWorktreePath !== undefined && canonicalWorktreePath !== undefined) {
+    violations.push(violation2("high", "workflow.snapshot.conflicting-worktree-paths", "both integration_worktree_path and the legacy control_worktree_path key are present — the canonical snapshot carries only integration_worktree_path (refused even when the values are equal)", "remove the legacy control_worktree_path key"));
+  } else {
+    if (canonicalWorktreePath !== undefined) {
+      validateWorktreePathValue(violations, canonicalWorktreePath, "integration_worktree_path");
+    }
+    if (legacyWorktreePath !== undefined) {
+      violations.push(violation2("medium", "workflow.snapshot.legacy-control-worktree-path", "legacy control_worktree_path is present — the canonical reader normalizes it to integration_worktree_path in memory; migrate on the next authorized write (writers emit only the canonical key)", "rename control_worktree_path to integration_worktree_path on the next authorized write"));
+      validateWorktreePathValue(violations, legacyWorktreePath, "control_worktree_path (legacy alias)");
+    }
+  }
+  if (doc.legacy_metadata !== undefined && !isPlainObject2(doc.legacy_metadata)) {
+    violations.push(violation2("medium", "workflow.snapshot.invalid-legacy-metadata", "legacy_metadata must be an object"));
+  }
+  if (doc.compass_ref !== undefined) {
+    validateNonEmptyString2(violations, doc.compass_ref, "compass_ref", "workflow.snapshot.missing-compass-ref", "workflow.snapshot.invalid-compass-ref");
+  }
+  if (doc.delivery_kind !== undefined) {
+    if (typeof doc.delivery_kind !== "string" || !WORKFLOW_DELIVERY_KINDS.includes(doc.delivery_kind)) {
+      violations.push(violation2("medium", "workflow.snapshot.invalid-delivery-kind", `delivery_kind must be one of ${WORKFLOW_DELIVERY_KINDS.join(" | ")} — got ${JSON.stringify(doc.delivery_kind)}`));
+    }
+  }
+  if (doc.project !== undefined) {
+    validateNonEmptyString2(violations, doc.project, "project", "workflow.snapshot.missing-project", "workflow.snapshot.invalid-project");
+  }
+  if (doc.completion_policy !== undefined) {
+    validateNonEmptyString2(violations, doc.completion_policy, "completion_policy", "workflow.snapshot.missing-completion-policy", "workflow.snapshot.invalid-completion-policy");
+  }
+  if (doc.delivery !== undefined) {
+    violations.push(...deliveryEvidenceViolations(doc.delivery, "delivery"));
+  }
+  const terminal = typeof doc.status === "string" && WORKFLOW_TERMINAL_STATUSES.includes(doc.status);
+  if (terminal) {
+    if (doc.ended_at === undefined) {
+      violations.push(violation2("high", "workflow.snapshot.missing-ended-at", `terminal status ${JSON.stringify(doc.status)} requires ended_at — a terminal snapshot must record when the lifecycle ended`));
+    }
+    if (Array.isArray(doc.plans)) {
+      for (const row of doc.plans) {
+        if (isPlainObject2(row) && row.execution_lease !== undefined) {
+          violations.push(violation2("high", "workflow.snapshot.terminal-dangling-execution-lease", `terminal snapshot must not carry a row execution_lease (dangling lease) — release every lease before the lifecycle ends`));
+        }
+      }
+    }
+    if (doc.integration_merge_lease !== undefined) {
+      violations.push(violation2("high", "workflow.snapshot.terminal-dangling-merge-lease", "terminal snapshot must not carry integration_merge_lease (dangling lease) — release the merge lease before the lifecycle ends"));
+    }
+  }
+  return { ok: violations.length === 0, violations };
+}
+async function writeWorkflowSnapshot(snapshot, dir, opts = {}) {
+  const gate = validateWorkflowSnapshot(snapshot);
+  if (!gate.ok) {
+    const detail = gate.violations.map((v) => v.message).join("; ");
+    throw new Error(`refusing to write invalid workflow snapshot: ${detail}`);
+  }
+  if (opts.expectedVersion !== undefined && !isArtifactVersion(opts.expectedVersion)) {
+    throw new CoordinationError("coordination.invalid-input", `expectedVersion must be "absent" or sha256:<64 hex> — got ${JSON.stringify(opts.expectedVersion)}`, { expected: opts.expectedVersion });
+  }
+  if (opts.createOnly === true && opts.expectedVersion !== undefined && opts.expectedVersion !== "absent") {
+    throw new CoordinationError("coordination.invalid-input", `createOnly implies expectedVersion "absent" — got ${JSON.stringify(opts.expectedVersion)}`, { expected: opts.expectedVersion });
+  }
+  const snapshotPath = join6(dir, WORKFLOW_SNAPSHOT_FILE);
+  const store = getArtifactStore();
+  assertFsStorePath(store, { kind: "snapshot", key: snapshot.id }, snapshotPath);
+  mkdirSync3(dir, { recursive: true });
+  await withStatusWriteLock(snapshotPath, async () => {
+    const current = readArtifactBytes(snapshotPath);
+    const currentVersion = current?.version ?? "absent";
+    const required = opts.createOnly === true ? "absent" : opts.expectedVersion ?? "absent";
+    if (required !== currentVersion) {
+      const missingToken = opts.createOnly !== true && opts.expectedVersion === undefined;
+      throw new CoordinationError(missingToken ? "coordination.expected-version-required" : "coordination.version-conflict", missingToken ? `snapshot ${snapshotPath} already exists — replace it with an explicit expectedVersion (its current version is ${currentVersion}) or write a new snapshot` : `snapshot ${snapshotPath} is at ${currentVersion}, writer required ${required}`, { path: snapshotPath, expected: required, actual: currentVersion });
+    }
+    const payload = current === undefined ? snapshot : mergePhaseProjection(current.payload, snapshot);
+    assertCoordinatedSnapshotWriter(current?.payload, snapshotPath, opts.sessionPath);
+    await withProtectedWrite(snapshotPath, "put", () => store.put({ kind: "snapshot", key: snapshot.id, payload }));
+  });
+}
+function assertCoordinatedSnapshotWriter(stored, snapshotPath, sessionPath, action = "replacement") {
+  const coordination = isPlainObject2(stored) ? stored.coordination : undefined;
+  if (coordination === undefined)
+    return;
+  const bound = isPlainObject2(coordination) && isPlainObject2(coordination.coordinator) ? coordination.coordinator.session_file : undefined;
+  if (sessionPath === undefined || typeof bound !== "string" || canonicalTarget(sessionPath) !== canonicalTarget(bound)) {
+    throw new CoordinationError("coordination.session-mismatch", `snapshot ${snapshotPath} is coordinated — ${action} requires --session <coordinator envelope>`, { path: snapshotPath, expected: bound, actual: sessionPath });
+  }
+}
+function mergePhaseProjection(stored, incoming) {
+  if (!isPlainObject2(stored)) {
+    throw new CoordinationError("coordination.version-conflict", "stored workflow snapshot is not an object — refusing a field-scoped rewrite over it", {});
+  }
+  const allowed = ["phase", "updated_at"];
+  const keys = new Set([...Object.keys(stored), ...Object.keys(incoming)]);
+  const drifted = [...keys].filter((key) => !allowed.includes(key) && stableJson(stored[key]) !== stableJson(incoming[key]));
+  if (drifted.length > 0) {
+    throw new CoordinationError("coordination.direct-write-refused", `refusing snapshot write: field(s) ${drifted.join(", ")} differ from disk — this writer may only change ${allowed.join(", ")}`, { fields: drifted, allowed });
+  }
+  const next = { ...stored };
+  for (const key of allowed) {
+    const value = incoming[key];
+    if (value === undefined)
+      delete next[key];
+    else
+      next[key] = value;
+  }
+  return next;
+}
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+function assertDeliveryRegistrationCoherence(kind, evidence, what) {
+  if (kind === "development" && (!nonEmptyString(evidence.branchSource) || !nonEmptyString(evidence.branchTarget))) {
+    throw new Error(`${what}: a development workflow requires its delivery source and target branches (--branch-source/--branch-target) — missing branch fields are incomplete registration, not an exempt workflow (contract §1/§4a)`);
+  }
+  if (kind === "verification/report-only" && !nonEmptyString(evidence.completionPolicy)) {
+    throw new Error(`${what}: a verification/report-only workflow requires the completion policy (--completion-policy) naming the evidence that completes it (contract §1)`);
+  }
+  for (const [field, value] of Object.entries({ branchSource: evidence.branchSource, branchTarget: evidence.branchTarget, completionPolicy: evidence.completionPolicy })) {
+    if (value !== undefined && !nonEmptyString(value)) {
+      throw new Error(`${what}: ${field} must be a non-empty string when given`);
+    }
+  }
+}
 
 // src/status.ts
 var DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
-function isPlainObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function violation(severity, code, message, fix) {
+var PLAN_STATUSES = ["Todo", "InProgress", "InReview", "Blocked", "Done"];
+function violation3(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
 }
 function todayString() {
@@ -341,12 +1086,49 @@ function todayString() {
   const day = String(now.getDate()).padStart(2, "0");
   return `${now.getFullYear()}-${month}-${day}`;
 }
-function validateNonEmptyString(violations, value, field, missingCode, invalidCode) {
+function validateNonEmptyString3(violations, value, field, missingCode, invalidCode) {
   if (value === undefined) {
-    violations.push(violation("high", missingCode, `missing required field: ${field}`));
+    violations.push(violation3("high", missingCode, `missing required field: ${field}`));
   } else if (typeof value !== "string" || value.trim() === "") {
-    violations.push(violation("medium", invalidCode, `${field} must be a non-empty string`));
+    violations.push(violation3("medium", invalidCode, `${field} must be a non-empty string`));
+  }
+}
+function validatePlanRow(row) {
+  const violations = [];
+  if (!isPlainObject2(row)) {
+    return { ok: false, violations: [violation3("high", "status.plan-row.invalid", "plan row must be an object")] };
+  }
+  const { id, plan_id: planId, title, file, status, metadata, execution_lease } = row;
+  if (id === undefined && planId === undefined) {
+    violations.push(violation3("high", "status.plan-row.missing-id", "missing required field: id (or legacy plan_id)"));
+  } else {
+    if (id !== undefined) {
+      validateNonEmptyString3(violations, id, "id", "status.plan-row.missing-id", "status.plan-row.invalid-id");
+    }
+    if (planId !== undefined) {
+      validateNonEmptyString3(violations, planId, "plan_id", "status.plan-row.missing-plan-id", "status.plan-row.invalid-plan-id");
+    }
+    if (id !== undefined && planId !== undefined && id !== planId) {
+      violations.push(violation3("medium", "status.plan-row.dual-id", "row has both id and plan_id with different values — write one canonical key (prefer id)"));
+    }
+  }
+  validateNonEmptyString3(violations, title, "title", "status.plan-row.missing-title", "status.plan-row.invalid-title");
+  validateNonEmptyString3(violations, file, "file", "status.plan-row.missing-file", "status.plan-row.invalid-file");
+  if (status === undefined) {
+    violations.push(violation3("high", "status.plan-row.missing-status", "missing required field: status"));
+  } else if (typeof status !== "string" || !PLAN_STATUSES.includes(status)) {
+    violations.push(violation3("medium", "status.plan-row.invalid-status", `status must be one of ${PLAN_STATUSES.join(" | ")} — got ${JSON.stringify(status)}`));
+  }
+  if (metadata !== undefined && !isPlainObject2(metadata)) {
+    violations.push(violation3("medium", "status.plan-row.invalid-metadata", "metadata must be an object"));
+  }
+  if (execution_lease !== undefined && !isPlainObject2(execution_lease)) {
+    violations.push(violation3("medium", "status.plan-row.invalid-execution-lease", "execution_lease must be an object"));
+  }
+  if (status === "Done" && execution_lease !== undefined) {
+    violations.push(violation3("medium", "status.plan-row.done-with-lease", 'plan status Done must not carry an execution_lease — the Done authority deletes the lease in the same complete-file update as status: "Done" (status-and-residuals.md § Hold, release, and override)', 'delete plans[].execution_lease in the same update that sets status: "Done"'));
   }
+  return { ok: violations.length === 0, violations };
 }
 function isHarnessRelativePath(dir) {
   if (dir.startsWith("/") || dir.startsWith("\\"))
@@ -357,25 +1139,25 @@ function isHarnessRelativePath(dir) {
 }
 function validateWorkflowEntry(entry) {
   const violations = [];
-  if (!isPlainObject(entry)) {
+  if (!isPlainObject2(entry)) {
     return {
       ok: false,
-      violations: [violation("high", "status.workflow.invalid", "workflow entry must be an object")]
+      violations: [violation3("high", "status.workflow.invalid", "workflow entry must be an object")]
     };
   }
-  validateNonEmptyString(violations, entry.id, "id", "status.workflow.missing-id", "status.workflow.invalid-id");
+  validateNonEmptyString3(violations, entry.id, "id", "status.workflow.missing-id", "status.workflow.invalid-id");
   if (entry.type === undefined) {
-    violations.push(violation("high", "status.workflow.missing-type", "missing required field: type"));
+    violations.push(violation3("high", "status.workflow.missing-type", "missing required field: type"));
   } else if (typeof entry.type !== "string" || !WORKFLOW_LIFECYCLE_TYPES.includes(entry.type)) {
-    violations.push(violation("medium", "status.workflow.invalid-type", `type must be one of ${WORKFLOW_LIFECYCLE_TYPES.join(" | ")} — got ${JSON.stringify(entry.type)}`));
+    violations.push(violation3("medium", "status.workflow.invalid-type", `type must be one of ${WORKFLOW_LIFECYCLE_TYPES.join(" | ")} — got ${JSON.stringify(entry.type)}`));
   }
-  validateNonEmptyString(violations, entry.started_at, "started_at", "status.workflow.missing-started-at", "status.workflow.invalid-started-at");
+  validateNonEmptyString3(violations, entry.started_at, "started_at", "status.workflow.missing-started-at", "status.workflow.invalid-started-at");
   if (entry.dir === undefined) {
-    violations.push(violation("high", "status.workflow.missing-dir", "missing required field: dir"));
+    violations.push(violation3("high", "status.workflow.missing-dir", "missing required field: dir"));
   } else if (typeof entry.dir !== "string" || entry.dir.trim() === "") {
-    violations.push(violation("medium", "status.workflow.invalid-dir", "dir must be a non-empty string"));
+    violations.push(violation3("medium", "status.workflow.invalid-dir", "dir must be a non-empty string"));
   } else if (!isHarnessRelativePath(entry.dir)) {
-    violations.push(violation("medium", "status.workflow.invalid-dir", `dir must be a harness-relative path (no absolute paths, no ".." segments) — got ${JSON.stringify(entry.dir)}`));
+    violations.push(violation3("medium", "status.workflow.invalid-dir", `dir must be a harness-relative path (no absolute paths, no ".." segments) — got ${JSON.stringify(entry.dir)}`));
   }
   return { ok: violations.length === 0, violations };
 }
@@ -385,24 +1167,24 @@ function validateStatusV2(docOrPath, opts = {}) {
   if (typeof docOrPath === "string") {
     try {
       doc = readJson(docOrPath);
-      harnessDir = dirname4(resolve5(docOrPath));
+      harnessDir = dirname5(resolve7(docOrPath));
     } catch (error) {
       return {
         ok: false,
-        violations: [violation("high", "status.invalid-json", error.message)]
+        violations: [violation3("high", "status.invalid-json", error.message)]
       };
     }
   } else {
     doc = docOrPath;
   }
-  if (!isPlainObject(doc)) {
-    return { ok: false, violations: [violation("high", "status.invalid-doc", "status document must be an object")] };
+  if (!isPlainObject2(doc)) {
+    return { ok: false, violations: [violation3("high", "status.invalid-doc", "status document must be an object")] };
   }
   if (doc.version !== 2) {
     return {
       ok: false,
       violations: [
-        violation("high", "status.migration-required", `status.json schema version 2 required — got ${JSON.stringify(doc.version)} (v1 or unknown version); run \`mstar migrate\` to convert the tree`, "run `mstar migrate`")
+        violation3("high", "status.migration-required", `status.json schema version 2 required — got ${JSON.stringify(doc.version)} (v1 or unknown version); run \`mstar migrate\` to convert the tree`, "run `mstar migrate`")
       ]
     };
   }
@@ -410,7 +1192,7 @@ function validateStatusV2(docOrPath, opts = {}) {
     return {
       ok: false,
       violations: [
-        violation("high", "status.migration-required", "v1-shaped status.json (root plans[]) is not a v2 document — run `mstar migrate` to convert the tree", "run `mstar migrate`")
+        violation3("high", "status.migration-required", "v1-shaped status.json (root plans[]) is not a v2 document — run `mstar migrate` to convert the tree", "run `mstar migrate`")
       ]
     };
   }
@@ -418,27 +1200,27 @@ function validateStatusV2(docOrPath, opts = {}) {
     return {
       ok: false,
       violations: [
-        violation("high", "status.migration-required", "v1-shaped status.json (root residual_findings) is not a v2 document — run `mstar migrate` to convert the tree", "run `mstar migrate`")
+        violation3("high", "status.migration-required", "v1-shaped status.json (root residual_findings) is not a v2 document — run `mstar migrate` to convert the tree", "run `mstar migrate`")
       ]
     };
   }
   const violations = [];
   if (doc.updated_at === undefined) {
-    violations.push(violation("high", "status.missing-updated-at", "missing required field: updated_at"));
+    violations.push(violation3("high", "status.missing-updated-at", "missing required field: updated_at"));
   } else if (typeof doc.updated_at !== "string" || !DATE_RE.test(doc.updated_at)) {
-    violations.push(violation("medium", "status.invalid-updated-at", "updated_at must be YYYY-MM-DD"));
+    violations.push(violation3("medium", "status.invalid-updated-at", "updated_at must be YYYY-MM-DD"));
   }
   if (doc.workflows === undefined) {
-    violations.push(violation("high", "status.missing-workflows", "missing required field: workflows"));
+    violations.push(violation3("high", "status.missing-workflows", "missing required field: workflows"));
   } else if (!Array.isArray(doc.workflows)) {
-    violations.push(violation("high", "status.invalid-workflows", "workflows must be an array"));
+    violations.push(violation3("high", "status.invalid-workflows", "workflows must be an array"));
   } else {
     const seen = new Set;
     for (const entry of doc.workflows) {
       violations.push(...validateWorkflowEntry(entry).violations);
-      if (isPlainObject(entry) && typeof entry.id === "string") {
+      if (isPlainObject2(entry) && typeof entry.id === "string") {
         if (seen.has(entry.id)) {
-          violations.push(violation("medium", "status.workflow.duplicate-id", `duplicate workflow id in workflows[]: ${JSON.stringify(entry.id)}`));
+          violations.push(violation3("medium", "status.workflow.duplicate-id", `duplicate workflow id in workflows[]: ${JSON.stringify(entry.id)}`));
         }
         seen.add(entry.id);
       }
@@ -447,47 +1229,47 @@ function validateStatusV2(docOrPath, opts = {}) {
   if (harnessDir !== undefined && Array.isArray(doc.workflows)) {
     let realHarnessDir = null;
     try {
-      realHarnessDir = realpathSync(harnessDir);
+      realHarnessDir = realpathSync2(harnessDir);
     } catch {}
     for (const entry of doc.workflows) {
-      if (!isPlainObject(entry) || typeof entry.dir !== "string")
+      if (!isPlainObject2(entry) || typeof entry.dir !== "string")
         continue;
-      const relSnapshot = join5(entry.dir, WORKFLOW_SNAPSHOT_FILE);
-      const snapshotPath = join5(harnessDir, relSnapshot);
+      const relSnapshot = join7(entry.dir, WORKFLOW_SNAPSHOT_FILE);
+      const snapshotPath = join7(harnessDir, relSnapshot);
       const label = typeof entry.id === "string" ? entry.id : relSnapshot;
       let physical;
       try {
-        physical = realpathSync(snapshotPath);
+        physical = realpathSync2(snapshotPath);
       } catch {
-        violations.push(violation("high", "status.workflow.snapshot-missing", `workflows[] lists ${JSON.stringify(label)} but its snapshot does not exist at ${JSON.stringify(relSnapshot)} — the root holds active lifecycles only; unregister the id when its snapshot is removed`));
+        violations.push(violation3("high", "status.workflow.snapshot-missing", `workflows[] lists ${JSON.stringify(label)} but its snapshot does not exist at ${JSON.stringify(relSnapshot)} — the root holds active lifecycles only; unregister the id when its snapshot is removed`));
         continue;
       }
-      if (realHarnessDir !== null && physical !== realHarnessDir && !physical.startsWith(`${realHarnessDir}${sep}`)) {
-        violations.push(violation("high", "status.workflow.snapshot-outside-harness", `workflows[] lists ${JSON.stringify(label)} but its snapshot resolves outside the harness dir (${JSON.stringify(physical)}) — symlinked snapshot paths are rejected; the snapshot must physically live under ${JSON.stringify(harnessDir)}`));
+      if (realHarnessDir !== null && physical !== realHarnessDir && !physical.startsWith(`${realHarnessDir}${sep2}`)) {
+        violations.push(violation3("high", "status.workflow.snapshot-outside-harness", `workflows[] lists ${JSON.stringify(label)} but its snapshot resolves outside the harness dir (${JSON.stringify(physical)}) — symlinked snapshot paths are rejected; the snapshot must physically live under ${JSON.stringify(harnessDir)}`));
         continue;
       }
       let snapshot;
       try {
         snapshot = readJson(snapshotPath);
       } catch (error) {
-        violations.push(violation("high", "status.workflow.snapshot-invalid", `snapshot at ${JSON.stringify(relSnapshot)} is not valid JSON: ${error.message}`));
+        violations.push(violation3("high", "status.workflow.snapshot-invalid", `snapshot at ${JSON.stringify(relSnapshot)} is not valid JSON: ${error.message}`));
         continue;
       }
       if (typeof snapshot.status === "string" && WORKFLOW_TERMINAL_STATUSES.includes(snapshot.status)) {
-        violations.push(violation("high", "status.workflow.terminal-listed", `workflows[] lists ${JSON.stringify(label)} whose snapshot status is terminal (${snapshot.status}) — removal-at-terminal: terminal writers unregister AFTER the snapshot write`));
+        violations.push(violation3("high", "status.workflow.terminal-listed", `workflows[] lists ${JSON.stringify(label)} whose snapshot status is terminal (${snapshot.status}) — removal-at-terminal: terminal writers unregister AFTER the snapshot write`));
       }
       if (typeof entry.type === "string" && typeof snapshot.type === "string" && entry.type !== snapshot.type) {
-        violations.push(violation("medium", "status.workflow.mismatched-type", `workflows[] entry ${JSON.stringify(label)} type ${JSON.stringify(entry.type)} does not match its snapshot type ${JSON.stringify(snapshot.type)} — the root entry mirrors the snapshot; align them`));
+        violations.push(violation3("medium", "status.workflow.mismatched-type", `workflows[] entry ${JSON.stringify(label)} type ${JSON.stringify(entry.type)} does not match its snapshot type ${JSON.stringify(snapshot.type)} — the root entry mirrors the snapshot; align them`));
       }
       if (typeof entry.started_at === "string" && typeof snapshot.started_at === "string" && entry.started_at !== snapshot.started_at) {
-        violations.push(violation("medium", "status.workflow.mismatched-started-at", `workflows[] entry ${JSON.stringify(label)} started_at ${JSON.stringify(entry.started_at)} does not match its snapshot started_at ${JSON.stringify(snapshot.started_at)} — workflow ${JSON.stringify(label)} collided with another writer (e.g. a concurrent/re-run \`audit promote\` with the same workflow id rewrote the snapshot); the root entry mirrors the snapshot — align them or remove the colliding workflow`));
+        violations.push(violation3("medium", "status.workflow.mismatched-started-at", `workflows[] entry ${JSON.stringify(label)} started_at ${JSON.stringify(entry.started_at)} does not match its snapshot started_at ${JSON.stringify(snapshot.started_at)} — workflow ${JSON.stringify(label)} collided with another writer (e.g. a concurrent/re-run \`audit promote\` with the same workflow id rewrote the snapshot); the root entry mirrors the snapshot — align them or remove the colliding workflow`));
       }
     }
   }
   return { ok: violations.length === 0, violations };
 }
 async function registerWorkflowEntryLocked(statusPath, entry) {
-  const harnessDir = dirname4(statusPath);
+  const harnessDir = dirname5(statusPath);
   const store = getArtifactStore();
   assertFsStorePath(store, { kind: "status", key: "root" }, statusPath);
   const current = readJson(statusPath);
@@ -497,41 +1279,72 @@ async function registerWorkflowEntryLocked(statusPath, entry) {
     throw new Error("refusing to modify status.json: workflows must be an array — a v1 root must be migrated first (run `mstar migrate`)");
   }
   const existing = doc.workflows.findIndex((wf) => wf.id === entry.id);
-  if (existing >= 0) {
-    doc.workflows[existing] = entry;
-  } else {
+  const commit = async () => {
+    doc.updated_at = todayString();
+    const gate = validateStatusV2(doc, { harnessDir });
+    if (!gate.ok) {
+      throw new Error(`refusing to write invalid status.json: ${gate.violations.map((v) => v.message).join("; ")}`);
+    }
+    await withProtectedWrite(statusPath, "put", () => store.put({ kind: "status", key: "root", payload: doc }));
+    return doc;
+  };
+  if (existing < 0) {
     doc.workflows.push(entry);
+    return commit();
+  }
+  const prior = doc.workflows[existing];
+  return withRegisteredSnapshotLock(harnessDir, prior, async (snapshot) => {
+    const priorCoordination = snapshot?.coordination;
+    if (isPlainObject2(priorCoordination) && isPlainObject2(priorCoordination.coordinator)) {
+      const drifted = ["dir", "type", "started_at"].filter((field) => prior[field] !== entry[field]);
+      if (drifted.length > 0) {
+        throw new CoordinationError("coordination.invalid-transition", `refusing to re-register workflow ${JSON.stringify(entry.id)}: it is coordinated and its ${drifted.join("/")} must not change`, { workflow_id: entry.id, fields: [...drifted] });
+      }
+    }
+    doc.workflows[existing] = entry;
+    return commit();
+  });
+}
+async function withRegisteredSnapshotLock(harnessDir, entry, fn) {
+  if (typeof entry.dir !== "string")
+    return fn(undefined);
+  const snapshotPath = join7(harnessDir, entry.dir, WORKFLOW_SNAPSHOT_FILE);
+  if (!existsSync5(snapshotPath))
+    return fn(undefined);
+  return withStatusWriteLock(snapshotPath, () => fn(readRegisteredSnapshot(snapshotPath)));
+}
+function readRegisteredSnapshot(snapshotPath) {
+  if (!existsSync5(snapshotPath))
+    return;
+  try {
+    const parsed = JSON.parse(readFileSync5(snapshotPath, "utf8"));
+    return isPlainObject2(parsed) ? parsed : undefined;
+  } catch {
+    return;
   }
-  doc.updated_at = todayString();
-  const gate = validateStatusV2(doc, { harnessDir });
-  if (!gate.ok) {
-    throw new Error(`refusing to write invalid status.json: ${gate.violations.map((v) => v.message).join("; ")}`);
-  }
-  await store.put({ kind: "status", key: "root", payload: doc });
-  return doc;
 }
 
 // src/path.ts
 function resolveHarnessDir(startDir = process.cwd(), opts = {}) {
-  const start = resolve6(startDir);
+  const start = resolve8(startDir);
   const explicit = opts.harnessDir ?? process.env.MSTAR_HARNESS_DIR;
   if (explicit)
-    return resolve6(start, explicit);
-  const boundary = resolve6(start, opts.workspaceRoot ?? defaultWorkspaceRoot(start));
+    return resolve8(start, explicit);
+  const boundary = resolve8(start, opts.workspaceRoot ?? defaultWorkspaceRoot(start));
   const rc = loadMstarc(start, boundary);
   if (rc !== null && rc.config.harnessDir)
-    return resolve6(rc.dir, rc.config.harnessDir);
+    return resolve8(rc.dir, rc.config.harnessDir);
   let dir = start;
   for (;; ) {
     if (!isAtOrBelow2(dir, boundary))
       return null;
-    for (const candidate of [join6(dir, ".mstar"), join6(dir, ".agents"), join6(dir, ".plans"), join6(dir, "plans")]) {
+    for (const candidate of [join8(dir, ".mstar"), join8(dir, ".agents"), join8(dir, ".plans"), join8(dir, "plans")]) {
       if (isDirectory(candidate))
         return candidate;
     }
     if (dir === boundary)
       return null;
-    const parent = dirname5(dir);
+    const parent = dirname6(dir);
     if (parent === dir)
       return null;
     dir = parent;
@@ -549,21 +1362,21 @@ function defaultWorkspaceRoot(startDir) {
     let boundary = startDir;
     for (const segment of cdup.split(/[\\/]/)) {
       if (segment && segment !== ".")
-        boundary = dirname5(boundary);
+        boundary = dirname6(boundary);
     }
-    return resolve6(boundary);
+    return resolve8(boundary);
   } catch {}
   return startDir;
 }
 function isAtOrBelow2(dir, root) {
   const rel = relative2(root, dir);
-  return rel === "" || !rel.startsWith("..") && !isAbsolute4(rel);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute6(rel);
 }
 function mstarcDirOverride(harnessDir, key) {
-  const dir = resolve6(harnessDir);
-  const rc = loadMstarc(dir, dirname5(dir));
+  const dir = resolve8(harnessDir);
+  const rc = loadMstarc(dir, dirname6(dir));
   const declared = rc?.config[key];
-  return declared ? resolve6(rc.dir, declared) : null;
+  return declared ? resolve8(rc.dir, declared) : null;
 }
 function assertSafePathComponent(value, what) {
   if (value === "" || value === "." || value === ".." || !/^[A-Za-z0-9._-]+$/.test(value)) {
@@ -573,10 +1386,10 @@ function assertSafePathComponent(value, what) {
 function resolveHarnessSubdir(startDir, opts, key, fallback) {
   const harness = resolveHarnessDir(startDir, opts);
   if (harness === null) {
-    throw new Error(`harness dir not found from ${resolve6(startDir)} — cannot resolve the ${fallback} dir (run \`mstar harness scaffold\`, pass opts.harnessDir, or set MSTAR_HARNESS_DIR)`);
+    throw new Error(`harness dir not found from ${resolve8(startDir)} — cannot resolve the ${fallback} dir (run \`mstar harness scaffold\`, pass opts.harnessDir, or set MSTAR_HARNESS_DIR)`);
   }
   const declared = mstarcDirOverride(harness, key);
-  return declared !== null ? declared : join6(resolve6(harness), fallback);
+  return declared !== null ? declared : join8(resolve8(harness), fallback);
 }
 function resolveWorkflowDir(startDir = process.cwd(), opts = {}) {
   return resolveHarnessSubdir(startDir, opts, "workflowDir", "workflows");
@@ -618,7 +1431,7 @@ function isDirectory(dir) {
 }
 
 // src/audit.ts
-function violation2(severity, code, message, fix) {
+function violation4(severity, code, message, fix) {
   return { ok: false, severity, code, message, fix };
 }
 var AUDIT_PRIORITIES = ["P1", "P2", "P3"];
@@ -663,14 +1476,14 @@ function validateAuditStatusBlocks(planText) {
   const violations = [];
   const blocks = parseStatusBlocks(planText);
   if (blocks.length === 0) {
-    violations.push(violation2("medium", "audit.status.missing-block", "no `## Status` block found — audit plan files carry the Status block fields (mstar-audit SKILL.md § Plan output)", "add a `## Status` block with Priority, Effort, Risk, Depends on, Category, Planned at"));
+    violations.push(violation4("medium", "audit.status.missing-block", "no `## Status` block found — audit plan files carry the Status block fields (mstar-audit SKILL.md § Plan output)", "add a `## Status` block with Priority, Effort, Risk, Depends on, Category, Planned at"));
     return { ok: false, violations };
   }
   blocks.forEach((block, index) => {
     const label = blocks.length > 1 ? ` #${index + 1}` : "";
     for (const field of AUDIT_STATUS_FIELDS) {
       if (!block.fields.has(field)) {
-        violations.push(violation2("medium", "audit.status.missing-field", `Status block${label} missing required field "${field}" (mstar-audit SKILL.md § Plan output)`, `add \`- **${field}**: <value>\` to the Status block`));
+        violations.push(violation4("medium", "audit.status.missing-field", `Status block${label} missing required field "${field}" (mstar-audit SKILL.md § Plan output)`, `add \`- **${field}**: <value>\` to the Status block`));
       }
     }
     const check = (field, pattern, code, expected) => {
@@ -678,7 +1491,7 @@ function validateAuditStatusBlocks(planText) {
       if (value === undefined)
         return;
       if (!pattern.test(value)) {
-        violations.push(violation2("medium", code, `Status block${label} "${field}" = "${value}" — expected ${expected} (mstar-audit SKILL.md § Plan output)`, `fix \`- **${field}**:\` to one of: ${expected}`));
+        violations.push(violation4("medium", code, `Status block${label} "${field}" = "${value}" — expected ${expected} (mstar-audit SKILL.md § Plan output)`, `fix \`- **${field}**:\` to one of: ${expected}`));
       }
     };
     check("Priority", /^P[123]$/, "audit.status.invalid-priority", "P1 | P2 | P3");
@@ -913,12 +1726,12 @@ function scanSecrets(files) {
   for (const file of files) {
     let text;
     try {
-      text = readFileSync5(file, "utf8");
+      text = readFileSync7(file, "utf8");
     } catch {
       unreadableFiles++;
       continue;
     }
-    const base = basename3(file);
+    const base = basename5(file);
     for (const entry of NEVER_COMMIT_FILENAMES) {
       if (entry.re.test(base))
         findings.push({ file, line: 1, type: entry.type });
@@ -970,12 +1783,12 @@ var LOCKFILE_NAMES = [
 function rootLockfiles(root) {
   let entries;
   try {
-    entries = readdirSync4(root, { withFileTypes: true });
+    entries = readdirSync5(root, { withFileTypes: true });
   } catch {
     return [];
   }
   const names = new Set(LOCKFILE_NAMES);
-  const present = entries.filter((entry) => entry.isFile() && names.has(entry.name)).map((entry) => join7(root, entry.name));
+  const present = entries.filter((entry) => entry.isFile() && names.has(entry.name)).map((entry) => join9(root, entry.name));
   if (present.length === 0)
     return [];
   try {
@@ -984,7 +1797,7 @@ function rootLockfiles(root) {
       encoding: "utf8",
       stdio: ["ignore", "pipe", "ignore"]
     }).split("\x00").filter((f) => f !== ""));
-    return present.filter((p) => tracked.has(basename3(p)));
+    return present.filter((p) => tracked.has(basename5(p)));
   } catch {
     return present;
   }
@@ -995,26 +1808,26 @@ function supplyChainChecks(repoRoot) {
   const lockfiles = rootLockfiles(repoRoot);
   if (lockfiles.length === 0) {
     findings.push({ kind: "lockfile-missing", file: repoRoot });
-    violations.push(violation2("medium", "audit.supply.lockfile-missing", `no recognized lockfile at ${repoRoot}`, "commit a lockfile (package-lock.json, pnpm-lock.yaml, yarn.lock, bun.lock, …)"));
+    violations.push(violation4("medium", "audit.supply.lockfile-missing", `no recognized lockfile at ${repoRoot}`, "commit a lockfile (package-lock.json, pnpm-lock.yaml, yarn.lock, bun.lock, …)"));
   } else if (lockfiles.length > 1) {
     findings.push({ kind: "lockfile-duplicate", file: lockfiles.map((f) => f.replace(`${repoRoot}/`, "")).join(", ") });
-    violations.push(violation2("medium", "audit.supply.lockfile-duplicate", `multiple lockfiles at ${repoRoot}: ${lockfiles.join(", ")}`, "keep exactly one lockfile per package manager"));
+    violations.push(violation4("medium", "audit.supply.lockfile-duplicate", `multiple lockfiles at ${repoRoot}: ${lockfiles.join(", ")}`, "keep exactly one lockfile per package manager"));
   }
-  const workflowsDir = join7(repoRoot, ".github", "workflows");
+  const workflowsDir = join9(repoRoot, ".github", "workflows");
   let wfEntries = [];
   try {
-    wfEntries = readdirSync4(workflowsDir, { withFileTypes: true });
+    wfEntries = readdirSync5(workflowsDir, { withFileTypes: true });
   } catch {
     wfEntries = [];
   }
   for (const entry of wfEntries) {
     if (!entry.isFile() || !/\.(?:ya?ml)$/.test(entry.name))
       continue;
-    const wfPath = join7(workflowsDir, entry.name);
+    const wfPath = join9(workflowsDir, entry.name);
     const relPath = `.github/workflows/${entry.name}`;
     let text;
     try {
-      text = readFileSync5(wfPath, "utf8");
+      text = readFileSync7(wfPath, "utf8");
     } catch {
       continue;
     }
@@ -1054,12 +1867,12 @@ function supplyChainChecks(repoRoot) {
         const versionLike = /^v\d+(?:\.\d+)*$/.test(ref);
         if (!shaLike && !versionLike) {
           findings.push({ kind: "action-unpinned", file: relPath, line: i + 1 });
-          violations.push(violation2("high", "audit.supply.action-unpinned", `${relPath}:${i + 1} uses \`${uses[1]}@${ref}\` — mutable ref`, "pin the action to a full commit SHA"));
+          violations.push(violation4("high", "audit.supply.action-unpinned", `${relPath}:${i + 1} uses \`${uses[1]}@${ref}\` — mutable ref`, "pin the action to a full commit SHA"));
         }
       }
       if (hasPrt && prtHeadSteps.has(i)) {
         findings.push({ kind: "pull_request_target-head", file: relPath, line: i + 1 });
-        violations.push(violation2("high", "audit.supply.pull_request_target-head", `${relPath}:${i + 1} checks out the PR head under pull_request_target`, "check out the base ref or use a pull_request trigger for untrusted code"));
+        violations.push(violation4("high", "audit.supply.pull_request_target-head", `${relPath}:${i + 1} checks out the PR head under pull_request_target`, "check out the base ref or use a pull_request trigger for untrusted code"));
       }
     }
   }
@@ -1112,7 +1925,7 @@ function redactFinding(finding) {
   };
 }
 function readPlanFileSummary(filePath) {
-  const text = readFileSync5(filePath, "utf8");
+  const text = readFileSync7(filePath, "utf8");
   const title = (text.match(/^# (.+)$/m) ?? [])[1] ?? filePath;
   const blocks = parseStatusBlocks(text);
   return { title: title.trim(), fields: blocks.length > 0 ? blocks[0].fields : new Map };
@@ -1166,10 +1979,10 @@ function renderIndex(params) {
 function scaffoldAuditPlan(outDir, findings, options = {}) {
   const date = options.date ?? new Date().toISOString().slice(0, 10);
   const plannedAt = options.plannedAt ?? { commit: options.repoShortSha ?? "unknown", date };
-  mkdirSync4(outDir, { recursive: true });
-  const existingReadme = join7(outDir, "README.md");
-  const carried = existsSync5(existingReadme) ? extractSecurityDispositionSections(readFileSync5(existingReadme, "utf8")) : { needsVerification: [], hardeningChecked: [] };
-  const existing = readdirSync4(outDir).filter((f) => /^\d{3}-.*\.md$/.test(f));
+  mkdirSync5(outDir, { recursive: true });
+  const existingReadme = join9(outDir, "README.md");
+  const carried = existsSync7(existingReadme) ? extractSecurityDispositionSections(readFileSync7(existingReadme, "utf8")) : { needsVerification: [], hardeningChecked: [] };
+  const existing = readdirSync5(outDir).filter((f) => /^\d{3}-.*\.md$/.test(f));
   let next = existing.reduce((max, f) => Math.max(max, Number(f.slice(0, 3))), 0) + 1;
   const redactedFindings = findings.map(redactFinding);
   const written = [];
@@ -1185,13 +1998,13 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
     }
     usedSlugs.add(slug);
     const file = `${num}-${slug}.md`;
-    writeFileSync4(join7(outDir, file), renderPlanFile(finding, plannedAt));
+    writeFileSync4(join9(outDir, file), renderPlanFile(finding, plannedAt));
     written.push(file);
     next++;
   }
   const all = [...existing, ...written].sort();
   const rows = all.map((file) => {
-    const summary = readPlanFileSummary(join7(outDir, file));
+    const summary = readPlanFileSummary(join9(outDir, file));
     const fields = summary.fields;
     return {
       num: file.slice(0, 3),
@@ -1225,7 +2038,7 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
   });
   const needsVerificationLines = options.needsVerification !== undefined ? options.needsVerification.map((nv) => `- ${escapeCell(redactText(nv.lead))}: ${escapeCell(redactText(nv.how))}${nv.evidence ? ` (${escapeCell(redactText(nv.evidence))})` : ""}`) : carried.needsVerification;
   const hardeningCheckedLines = options.hardeningChecked !== undefined ? options.hardeningChecked.map((hc) => `- ${hc.kind}: ${escapeCell(redactText(hc.text))}`) : carried.hardeningChecked;
-  writeFileSync4(join7(outDir, "README.md"), renderIndex({
+  writeFileSync4(join9(outDir, "README.md"), renderIndex({
     date,
     repoName: options.repoName ?? "repo",
     repoShortSha: options.repoShortSha ?? "unknown",
@@ -1234,7 +2047,7 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
     needsVerification: needsVerificationLines,
     hardeningChecked: hardeningCheckedLines
   }));
-  return { outDir: resolve7(outDir), date, files: written, nextNumber: next };
+  return { outDir: resolve9(outDir), date, files: written, nextNumber: next };
 }
 async function promoteAuditPlans(outDir, selected, options) {
   if (selected.length === 0) {
@@ -1243,19 +2056,24 @@ async function promoteAuditPlans(outDir, selected, options) {
   if (typeof options.harnessDir !== "string" || options.harnessDir.trim() === "") {
     throw new Error("promoteAuditPlans: options.harnessDir is required (must contain status.json + workflows/)");
   }
-  const workflowId = options.workflowId ?? basename3(resolve7(outDir));
+  if (typeof options.deliveryKind !== "string" || !WORKFLOW_DELIVERY_KINDS.includes(options.deliveryKind)) {
+    throw new Error(`promoteAuditPlans: options.deliveryKind must be one of ${WORKFLOW_DELIVERY_KINDS.join(" | ")} — got ${JSON.stringify(options.deliveryKind)} (a promoted plan workflow declares its delivery kind at registration; it is never inferred and never defaulted)`);
+  }
+  assertDeliveryRegistrationCoherence(options.deliveryKind, options, "promoteAuditPlans");
+  const workflowId = options.workflowId ?? basename5(resolve9(outDir));
   assertSafePathComponent(workflowId, "workflow id");
-  const harnessDir = resolve7(options.harnessDir);
-  const statusPath = join7(harnessDir, "status.json");
-  const workflowDir = join7(harnessDir, "workflows", workflowId);
-  const snapshotPath = join7(workflowDir, WORKFLOW_SNAPSHOT_FILE);
+  const harnessDir = resolve9(options.harnessDir);
+  const statusPath = join9(harnessDir, "status.json");
+  const workflowDir = join9(harnessDir, "workflows", workflowId);
+  const snapshotPath = join9(workflowDir, WORKFLOW_SNAPSHOT_FILE);
+  const store = getArtifactStore();
   const planFiles = resolveSelectedPlanFiles(outDir, selected);
   const indexRows = readExecutionOrderIndex(outDir);
   const plans = planFiles.map((planFile) => {
     const stem = planFile.replace(/\.md$/, "");
     const num = stem.slice(0, 3);
     const indexRow = indexRows.get(num);
-    const title = indexRow?.title ?? readPlanFileSummary(join7(outDir, planFile)).title;
+    const title = indexRow?.title ?? readPlanFileSummary(join9(outDir, planFile)).title;
     return {
       id: stem,
       title,
@@ -1271,8 +2089,17 @@ async function promoteAuditPlans(outDir, selected, options) {
     status: "running",
     started_at: now.toISOString(),
     updated_at: now.toISOString().slice(0, 10),
-    plans
+    plans,
+    delivery_kind: options.deliveryKind
   };
+  if (options.branchSource !== undefined || options.branchTarget !== undefined) {
+    snapshot.branch = {
+      ...options.branchSource !== undefined ? { source: options.branchSource } : {},
+      ...options.branchTarget !== undefined ? { target: options.branchTarget } : {}
+    };
+  }
+  if (options.completionPolicy !== undefined)
+    snapshot.completion_policy = options.completionPolicy;
   const entry = {
     id: workflowId,
     type: "plan",
@@ -1284,18 +2111,29 @@ async function promoteAuditPlans(outDir, selected, options) {
     throw new Error(`refusing to register invalid workflow entry: ${entryGate.violations.map((v) => v.message).join("; ")}`);
   }
   await withStatusWriteLock(statusPath, async () => {
-    if (existsSync5(snapshotPath)) {
+    if (existsSync7(snapshotPath)) {
       throw new Error(`refusing to promote audit plans: workflow ${JSON.stringify(workflowId)} already exists ` + `(snapshot at ${snapshotPath}) — re-promote would drop its registered plan rows; ` + `remove that workflow before promoting again`);
     }
-    mkdirSync4(workflowDir, { recursive: true });
+    let createdVersion;
     try {
-      writeJson(snapshotPath, snapshot);
+      await writeWorkflowSnapshot(snapshot, workflowDir, { createOnly: true });
+      createdVersion = readArtifactBytes(snapshotPath)?.version;
       await registerWorkflowEntryLocked(statusPath, entry);
     } catch (error) {
-      rmSync(snapshotPath, { force: true });
+      if (createdVersion !== undefined) {
+        await withStatusWriteLock(snapshotPath, async () => {
+          const current = readArtifactBytes(snapshotPath);
+          if (current === undefined || current.version !== createdVersion)
+            return;
+          const remove = store.delete?.bind(store);
+          if (remove !== undefined) {
+            await withProtectedWrite(snapshotPath, "delete", () => remove({ kind: "snapshot", key: workflowId }));
+          }
+        });
+      }
       try {
-        if (readdirSync4(workflowDir).length === 0) {
-          rmdirSync2(workflowDir);
+        if (readdirSync5(workflowDir).length === 0) {
+          rmdirSync3(workflowDir);
         }
       } catch {}
       throw error;
@@ -1305,7 +2143,7 @@ async function promoteAuditPlans(outDir, selected, options) {
   return { workflowId, snapshotPath };
 }
 function resolveSelectedPlanFiles(outDir, selected) {
-  const files = readdirSync4(outDir).filter((f) => /^\d{3}-.*\.md$/.test(f)).sort();
+  const files = readdirSync5(outDir).filter((f) => /^\d{3}-.*\.md$/.test(f)).sort();
   const byNum = new Map;
   const byStem = new Map;
   for (const file of files) {
@@ -1320,7 +2158,7 @@ function resolveSelectedPlanFiles(outDir, selected) {
   for (const id of selected) {
     const file = byNum.get(id) ?? byStem.get(id) ?? byStem.get(id.replace(/\.md$/, ""));
     if (file === undefined) {
-      throw new Error(`promoteAuditPlans: selected plan ${JSON.stringify(id)} does not match any NNN-*.md file in ${resolve7(outDir)}`);
+      throw new Error(`promoteAuditPlans: selected plan ${JSON.stringify(id)} does not match any NNN-*.md file in ${resolve9(outDir)}`);
     }
     if (!seen.has(file)) {
       seen.add(file);
@@ -1330,10 +2168,10 @@ function resolveSelectedPlanFiles(outDir, selected) {
   return resolved;
 }
 function readExecutionOrderIndex(outDir) {
-  const readmePath = join7(outDir, "README.md");
+  const readmePath = join9(outDir, "README.md");
   let text;
   try {
-    text = readFileSync5(readmePath, "utf8");
+    text = readFileSync7(readmePath, "utf8");
   } catch {
     return new Map;
   }
@@ -1359,11 +2197,11 @@ function readExecutionOrderIndex(outDir) {
   return rows;
 }
 function planFileRel(outDir, planFile) {
-  const resolved = resolve7(outDir);
-  const parts = resolved.split(sep2);
+  const resolved = resolve9(outDir);
+  const parts = resolved.split(sep3);
   const plansIdx = parts.lastIndexOf("plans");
   if (plansIdx >= 0) {
-    return `${parts.slice(plansIdx + 1).join(sep2)}${sep2}${planFile}`;
+    return `${parts.slice(plansIdx + 1).join(sep3)}${sep3}${planFile}`;
   }
   return planFile;
 }