opencode-ship 1.1.2-rc.2 → 1.1.2

package/dist/core.js

@@ -1,4 +1,4 @@
-// opencode-ship/core v1.1.2-rc.2
+// opencode-ship/core v1.1.2
 
 // src/adapter.js
 import { readFile, writeFile, mkdir, rename } from "node:fs/promises";
@@ -195,8 +195,8 @@ async function loadAdapter(repoRoot) {
   }
   const v = validateAdapter(parsed);
   if (!v.ok) return { ok: false, error: { kind: "contract", path, issues: v.issues } };
-  const sha256 = createHash("sha256").update(raw).digest("hex");
-  return { ok: true, adapter: v.adapter, path, sha256 };
+  const sha2563 = createHash("sha256").update(raw).digest("hex");
+  return { ok: true, adapter: v.adapter, path, sha256: sha2563 };
 }
 async function writeLock(repoRoot, adapterSha256) {
   const lockPath = resolve(repoRoot, ".opencode", LOCK_FILENAME);
@@ -292,7 +292,7 @@ function transition(m, to, opts) {
 function createManifest(input) {
   const now = (input.now ?? (() => /* @__PURE__ */ new Date()))();
   return {
-    schemaVersion: 1,
+    schemaVersion: 2,
     taskId: input.taskId,
     repoIdentity: input.repoIdentity,
     issueNumber: input.issueNumber,
@@ -304,6 +304,7 @@ function createManifest(input) {
     lastPrHeadSha: input.lastPrHeadSha ?? null,
     lastReviewerSha: input.lastReviewerSha ?? null,
     lastVerifierSha: input.lastVerifierSha ?? null,
+    workflowId: input.workflowId ?? null,
     owner: input.owner,
     state: "issue-linked",
     transitionLog: [],
@@ -331,6 +332,7 @@ import { join as join4, resolve as resolve4 } from "node:path";
 // src/state/git-common-dir.js
 import { spawn } from "node:child_process";
 import { resolve as resolve2, join as join2 } from "node:path";
+var STATE_DIRNAME = "opencode-ship";
 async function resolveGitCommonDir(repoRoot) {
   if (typeof repoRoot !== "string" || repoRoot.length === 0) {
     throw new Error("resolveGitCommonDir: repoRoot must be a non-empty string");
@@ -366,6 +368,12 @@ async function resolveGitCommonDir(repoRoot) {
     });
   });
 }
+function opencodeShipStateDir(commonDir, ...segments) {
+  if (typeof commonDir !== "string" || commonDir.length === 0) {
+    throw new Error("opencodeShipStateDir: commonDir must be a non-empty string");
+  }
+  return join2(commonDir, STATE_DIRNAME, ...segments);
+}
 
 // src/state/durable-store.js
 import {
@@ -379,8 +387,10 @@ import {
   unlink,
   stat
 } from "node:fs/promises";
+import { existsSync as existsSync2 } from "node:fs";
 import { dirname as dirname2, join as join3, resolve as resolve3 } from "node:path";
 import { createHash as createHash2, randomBytes } from "node:crypto";
+import { hostname as osHostname } from "node:os";
 var STALE_LOCK_MS = 120 * 1e3;
 function randomToken() {
   return randomBytes(8).toString("hex");
@@ -417,6 +427,159 @@ async function atomicReplaceJson(path, value) {
   await rename2(tmp, target);
   await fsyncDir(parent);
 }
+async function publishImmutableJson(path, value) {
+  if (typeof path !== "string" || path.length === 0) {
+    throw new Error("publishImmutableJson: path must be a non-empty string");
+  }
+  const target = resolve3(path);
+  const parent = dirname2(target);
+  await mkdir2(parent, { recursive: true });
+  if (existsSync2(target)) {
+    throw new Error(`publishImmutableJson: target already exists: ${target}`);
+  }
+  const tmp = `${target}.${randomToken()}.immutable.tmp`;
+  const handle = await fsOpen(tmp, "w", 384);
+  try {
+    await handle.writeFile(ensureString(value), "utf8");
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  const attempt = await tryHardLink(tmp, target);
+  if (attempt === "exists") {
+    await unlink(tmp).catch(() => null);
+    throw new Error(`publishImmutableJson: target already exists: ${target}`);
+  }
+  if (attempt === "linked") {
+    await unlink(tmp).catch(() => null);
+  } else {
+    try {
+      await rename2(tmp, target);
+    } catch (err) {
+      await unlink(tmp).catch(() => null);
+      if (err && err.code === "EEXIST") {
+        throw new Error(`publishImmutableJson: target already exists: ${target}`);
+      }
+      throw err;
+    }
+  }
+  await fsyncDir(parent);
+}
+async function tryHardLink(src, dst) {
+  try {
+    await link(src, dst);
+    return "linked";
+  } catch (err) {
+    if (err && err.code === "EEXIST") return "exists";
+    if (err && (err.code === "ENOTSUP" || err.code === "EPERM" || err.code === "ENOSYS" || err.code === "EOPNOTSUPP" || err.code === "EXDEV")) {
+      return "fallback";
+    }
+    throw err;
+  }
+}
+async function withResourceLock(stateDir, resourceKey, input) {
+  if (typeof stateDir !== "string" || stateDir.length === 0) {
+    throw new Error("withResourceLock: stateDir must be a non-empty string");
+  }
+  if (typeof resourceKey !== "string" || resourceKey.length === 0) {
+    throw new Error("withResourceLock: resourceKey must be a non-empty string");
+  }
+  const callback = typeof input === "function" ? input : input?.callback;
+  const options = typeof input === "function" ? {} : input?.options ?? {};
+  if (typeof callback !== "function") {
+    throw new Error("withResourceLock: callback must be a function");
+  }
+  const acquireMode = options.acquire ?? "wait";
+  const waitMs = Number.isInteger(options.waitMs) && options.waitMs >= 0 ? options.waitMs : 30 * 1e3;
+  const pollMs = Number.isInteger(options.pollMs) && options.pollMs > 0 ? options.pollMs : 25;
+  const keyHash = createHash2("sha256").update(resourceKey).digest("hex");
+  const lockDir = join3(stateDir, "locks", keyHash);
+  const ownerPath = join3(lockDir, "owner.json");
+  await mkdir2(stateDir, { recursive: true });
+  const deadline = Date.now() + waitMs;
+  let acquired = false;
+  let quarantinedThisAcquire = false;
+  while (!acquired) {
+    try {
+      await mkdir2(lockDir, { recursive: true });
+      const handle = await fsOpen(ownerPath, "wx", 384);
+      try {
+        const owner = {
+          pid: process.pid,
+          hostname: osHostname(),
+          resource: resourceKey,
+          startedAt: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        await handle.writeFile(JSON.stringify(owner, null, 2) + "\n", "utf8");
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+      acquired = true;
+    } catch (err) {
+      if (err && err.code === "EEXIST") {
+        const claimed = await maybeQuarantineStaleLock(lockDir, ownerPath, resourceKey);
+        if (claimed) {
+          quarantinedThisAcquire = true;
+          continue;
+        }
+        if (acquireMode === "try") {
+          throw new Error(`withResourceLock: resource is busy: ${resourceKey}`);
+        }
+        if (Date.now() >= deadline) {
+          throw new Error(`withResourceLock: timed out waiting for ${resourceKey}`);
+        }
+        await new Promise((r) => setTimeout(r, pollMs));
+        continue;
+      }
+      throw err;
+    }
+  }
+  try {
+    return await callback();
+  } finally {
+    await unlink(ownerPath).catch(() => null);
+    if (!quarantinedThisAcquire) {
+      await unlink(lockDir).catch(() => null);
+    }
+  }
+}
+async function maybeQuarantineStaleLock(lockDir, ownerPath, resourceKey) {
+  let raw;
+  try {
+    raw = await readFile2(ownerPath, "utf8");
+  } catch {
+    return false;
+  }
+  let owner;
+  try {
+    owner = JSON.parse(raw);
+  } catch {
+    return false;
+  }
+  if (!owner || typeof owner !== "object") return false;
+  if (!Number.isInteger(owner.pid) || owner.pid <= 0) return false;
+  if (typeof owner.startedAt !== "string") return false;
+  const start = Date.parse(owner.startedAt);
+  if (!Number.isFinite(start)) return false;
+  if (Date.now() - start < STALE_LOCK_MS) return false;
+  if (owner.hostname !== osHostname()) return false;
+  let alive = true;
+  try {
+    process.kill(owner.pid, 0);
+  } catch (e) {
+    alive = e?.code === "EPERM";
+  }
+  if (alive) return false;
+  const stamp = new Date(start).toISOString().replace(/[:.]/g, "-");
+  const quarantinePath = join3(lockDir, `stale-${stamp}-${resourceKey.replace(/[^A-Za-z0-9._-]+/g, "_")}.owner.json`);
+  try {
+    await rename2(ownerPath, quarantinePath);
+  } catch {
+    return false;
+  }
+  return "quarantined";
+}
 
 // src/state/manifest-store.js
 var SHIP_DIRNAME = "opencode-ship";
@@ -488,7 +651,7 @@ async function deleteManifest(repoRoot, taskId) {
 // src/drivers/git.js
 import { spawnSync } from "node:child_process";
 import { resolve as resolve5 } from "node:path";
-import { existsSync as existsSync2 } from "node:fs";
+import { existsSync as existsSync3 } from "node:fs";
 var WorktreeRecord = {
   path: "",
   branch: "",
@@ -548,7 +711,7 @@ function isRebaseInProgress(cwd) {
 }
 function safeExists(p) {
   try {
-    return existsSync2(p);
+    return existsSync3(p);
   } catch {
     return false;
   }
@@ -1012,6 +1175,7 @@ function recoverManifestAfterCrash(manifest) {
 }
 
 // src/doctor.js
+import { access } from "node:fs/promises";
 import { spawnSync as spawnSync2 } from "node:child_process";
 import { resolve as resolve6 } from "node:path";
 function runVersion(argv) {
@@ -1454,6 +1618,77 @@ function createWorktreeTool(deps) {
 
 // src/tools/delivery-verify.js
 import { spawn as spawn4 } from "node:child_process";
+
+// src/workflow/gate-receipts.js
+import { createHash as createHash3 } from "node:crypto";
+import { mkdir as mkdir3, readFile as readFile4 } from "node:fs/promises";
+import { existsSync as existsSync4 } from "node:fs";
+import { join as join5 } from "node:path";
+
+// src/installer/json-pointer.js
+function isObject(v) {
+  return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  if (isObject(value)) {
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+function canonicalJson(value) {
+  return stableStringify(value);
+}
+
+// src/workflow/gate-receipts.js
+var SAFE_ID_RE = /^[A-Za-z0-9._-]{1,128}$/;
+var HASH_RE = /^[0-9a-f]{64}$/;
+var HEAD_RE = /^[0-9a-f]{40}$/;
+function validateIdentity(taskId, kind, headSha, receiptHash = null) {
+  if (!SAFE_ID_RE.test(taskId) || !SAFE_ID_RE.test(kind) || !HEAD_RE.test(headSha)) {
+    throw new Error("invalid gate receipt identity");
+  }
+  if (receiptHash !== null && !HASH_RE.test(receiptHash)) throw new Error("invalid gate receipt hash");
+}
+function hashGateReceipt(receipt) {
+  const { receiptHash: _receiptHash, ...payload } = receipt;
+  return createHash3("sha256").update(canonicalJson(payload), "utf8").digest("hex");
+}
+async function publishGateReceipt(repoRoot, taskId, kind, input) {
+  validateIdentity(taskId, kind, input?.headSha);
+  const receipt = { ...input, kind, taskId };
+  receipt.receiptHash = hashGateReceipt(receipt);
+  const commonDir = await resolveGitCommonDir(repoRoot);
+  const dir = join5(opencodeShipStateDir(commonDir), "gate-receipts", taskId, kind, receipt.headSha);
+  await mkdir3(dir, { recursive: true });
+  const path = join5(dir, `${receipt.receiptHash}.json`);
+  if (!existsSync4(path)) await publishImmutableJson(path, receipt);
+  return { receipt, path };
+}
+async function readGateReceipt(repoRoot, taskId, kind, receiptHash) {
+  if (!SAFE_ID_RE.test(taskId) || !SAFE_ID_RE.test(kind) || !HASH_RE.test(receiptHash)) {
+    throw new Error("invalid gate receipt lookup");
+  }
+  const commonDir = await resolveGitCommonDir(repoRoot);
+  const root = join5(opencodeShipStateDir(commonDir), "gate-receipts", taskId, kind);
+  if (!existsSync4(root)) return null;
+  const { readdir: readdir4 } = await import("node:fs/promises");
+  for (const head of await readdir4(root)) {
+    validateIdentity(taskId, kind, head, receiptHash);
+    const path = join5(root, head, `${receiptHash}.json`);
+    if (!existsSync4(path)) continue;
+    const receipt = JSON.parse(await readFile4(path, "utf8"));
+    if (receipt.kind !== kind || receipt.taskId !== taskId || hashGateReceipt(receipt) !== receipt.receiptHash) {
+      throw new Error(`invalid ${kind} gate receipt`);
+    }
+    return receipt;
+  }
+  return null;
+}
+
+// src/tools/delivery-verify.js
+import { createHash as createHash4 } from "node:crypto";
 function runCommand(argv, cwd, timeoutMs) {
   return new Promise((resolveP, rejectP) => {
     const proc = spawn4(argv[0], argv.slice(1), {
@@ -1520,8 +1755,16 @@ function createVerifyTool(deps) {
         headSha: head
       };
     }
+    const { receipt } = await publishGateReceipt(deps.repoRoot, m.taskId, "verification", {
+      headSha: head,
+      commandId: cmd.id,
+      argv: cmd.argv,
+      exitCode: 0,
+      stdoutSha256: createHash4("sha256").update(result.stdout, "utf8").digest("hex"),
+      stderrSha256: createHash4("sha256").update(result.stderr, "utf8").digest("hex")
+    });
     const t = transition(
-      { ...m, lastVerifierSha: head },
+      { ...m, lastVerifierSha: head, lastVerificationHash: receipt.receiptHash },
       "validating",
       { reason: `verify ok (${cmd.id})` }
     );
@@ -1529,6 +1772,7 @@ function createVerifyTool(deps) {
     const next = {
       ...m,
       lastVerifierSha: head,
+      lastVerificationHash: receipt.receiptHash,
       state: t.to,
       transitionLog: [
         ...m.transitionLog,
@@ -1544,6 +1788,7 @@ function createVerifyTool(deps) {
       stdoutTail,
       stderrTail,
       headSha: head,
+      verificationHash: receipt.receiptHash,
       manifestPath
     };
   };
@@ -1699,6 +1944,476 @@ function createPrTool(deps) {
   };
 }
 
+// src/workflow/run-controller.js
+import { createHash as createHash5 } from "node:crypto";
+import { readFile as readFile5, writeFile as writeFile3, mkdir as mkdir4, readdir as readdir3 } from "node:fs/promises";
+import { existsSync as existsSync5 } from "node:fs";
+import { join as join6 } from "node:path";
+async function readSnapshotFromDisk(repoRoot, workflowId) {
+  const common = await resolveGitCommonDir(repoRoot);
+  const runPath = join6(opencodeShipStateDir(common), "runs", workflowId, "run.json");
+  if (!existsSync5(runPath)) return null;
+  try {
+    const raw = await readFile5(runPath, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+async function readEventsFromDisk(repoRoot, workflowId) {
+  const common = await resolveGitCommonDir(repoRoot);
+  const dir = join6(opencodeShipStateDir(common), "runs", workflowId, "events");
+  if (!existsSync5(dir)) return [];
+  const entries = await readdir3(dir);
+  const sorted = entries.filter((n) => n.endsWith(".json")).sort();
+  const out = [];
+  for (const name of sorted) {
+    const raw = await readFile5(join6(dir, name), "utf8");
+    out.push(JSON.parse(raw));
+  }
+  return out;
+}
+var STATES2 = Object.freeze({
+  CREATED: "created",
+  RUNNING: "running",
+  COMMIT_PENDING: "commit-pending",
+  COMMITTED: "committed",
+  FIX_PENDING: "fix-pending",
+  REVISION_REQUIRED: "revision-required",
+  BLOCKED: "blocked",
+  ALL_TASKS_DONE: "all-tasks-done",
+  READY_PENDING: "ready-pending",
+  READY: "ready",
+  MERGED: "merged",
+  DONE: "done"
+});
+var EVENT_KINDS = Object.freeze({
+  RUN_START: "run-start",
+  TASK_DISPATCH: "task-dispatch",
+  TASK_REPORT: "task-report",
+  TASK_REVIEW: "task-review",
+  COMMIT: "commit",
+  TASK_COMPLETE: "task-complete",
+  ALL_TASKS_DONE: "all-tasks-done",
+  FINAL_REVIEW: "final-review",
+  READY_PENDING: "ready-pending",
+  READY: "ready",
+  MERGE: "merge",
+  DONE: "done",
+  BLOCKED: "blocked"
+});
+var MAX_FIX_ROUNDS = 3;
+function sha256(value) {
+  return createHash5("sha256").update(value, "utf8").digest("hex");
+}
+function canonicalize(value) {
+  const seen = /* @__PURE__ */ new WeakSet();
+  const sort = (v) => {
+    if (v === null || typeof v !== "object") return v;
+    if (seen.has(v)) return null;
+    seen.add(v);
+    if (Array.isArray(v)) return v.map(sort);
+    const out = {};
+    for (const k of Object.keys(v).sort()) out[k] = sort(v[k]);
+    return out;
+  };
+  return JSON.stringify(sort(value));
+}
+function nextRound(failures) {
+  return (failures ?? 0) + 1;
+}
+function nextSequence(events) {
+  return events.length + 1;
+}
+function appendEvent(state, recorded) {
+  const prev = state.events[state.events.length - 1];
+  const priorHash = prev?.hash ?? "0".repeat(64);
+  const hash = sha256(canonicalize({ kind: recorded.kind, data: recorded.data, at: recorded.at, sequence: recorded.sequence, priorHash }));
+  const withHash = { ...recorded, priorHash, hash };
+  return [...state.events, withHash];
+}
+function normalizeState(state) {
+  return {
+    ...state,
+    completedTasks: Array.isArray(state.completedTasks) ? state.completedTasks : [],
+    taskReady: state.taskReady ?? null,
+    events: Array.isArray(state.events) ? state.events : [],
+    round: Number.isInteger(state.round) ? state.round : 0,
+    failures: Number.isInteger(state.failures) ? state.failures : 0
+  };
+}
+function ensureActiveTask(state, taskId) {
+  if (state.activeTask === null) return;
+  if (state.activeTask !== taskId) {
+    throw new Error(`run reducer: another task is active (${state.activeTask}), refusing ${taskId}`);
+  }
+}
+function reduce(state, event) {
+  const ev = { ...event, at: event.at ?? (/* @__PURE__ */ new Date()).toISOString() };
+  const sequence = nextSequence(state.events);
+  const recorded = (kind, data) => ({ sequence, kind, at: ev.at, data });
+  const nextState = (extra) => ({ ...state, ...extra, events: appendEvent(state, recorded(event.kind, event.data)) });
+  switch (event.kind) {
+    case EVENT_KINDS.RUN_START: {
+      if (state.state !== STATES2.CREATED) {
+        throw new Error(`run reducer: RUN_START requires state=created, got ${state.state}`);
+      }
+      return {
+        state: nextState({ state: STATES2.RUNNING, activeTask: null, round: 0, completedTasks: [] }),
+        event: recorded(EVENT_KINDS.RUN_START, { revision: event.data.revision, sha256: event.data.sha256 })
+      };
+    }
+    case EVENT_KINDS.TASK_DISPATCH: {
+      if (state.state !== STATES2.RUNNING && state.state !== STATES2.FIX_PENDING) {
+        throw new Error(`run reducer: TASK_DISPATCH requires state=running|fix-pending, got ${state.state}`);
+      }
+      if (state.activeTask !== null) {
+        throw new Error(`run reducer: TASK_DISPATCH while another task is active (${state.activeTask})`);
+      }
+      const round = state.round > 0 ? state.round : 1;
+      return {
+        state: nextState({ state: STATES2.RUNNING, activeTask: event.data.taskId, round }),
+        event: recorded(EVENT_KINDS.TASK_DISPATCH, { taskId: event.data.taskId, briefHash: event.data.briefHash, round })
+      };
+    }
+    case EVENT_KINDS.TASK_REPORT: {
+      if (state.state !== STATES2.RUNNING && state.state !== STATES2.FIX_PENDING || state.activeTask === null) {
+        throw new Error(`run reducer: TASK_REPORT requires running with active task`);
+      }
+      ensureActiveTask(state, event.data.taskId);
+      return {
+        state: nextState({ state: STATES2.RUNNING, taskReady: { taskId: event.data.taskId, reportHash: event.data.reportHash } }),
+        event: recorded(EVENT_KINDS.TASK_REPORT, { taskId: event.data.taskId, reportHash: event.data.reportHash })
+      };
+    }
+    case EVENT_KINDS.TASK_REVIEW: {
+      if (state.state !== STATES2.RUNNING && state.state !== STATES2.FIX_PENDING || state.activeTask === null) {
+        throw new Error(`run reducer: TASK_REVIEW requires running with active task`);
+      }
+      ensureActiveTask(state, event.data.taskId);
+      const failures = event.data.verdict === "pass" ? 0 : nextRound(state.failures);
+      if (event.data.verdict === "pass") {
+        return {
+          state: nextState({ state: STATES2.COMMIT_PENDING, round: state.round, taskReady: { ...state.taskReady ?? {}, taskId: event.data.taskId, reviewHash: event.data.reviewHash } }),
+          event: recorded(EVENT_KINDS.TASK_REVIEW, { taskId: event.data.taskId, verdict: "pass", reviewHash: event.data.reviewHash })
+        };
+      }
+      const next = nextRound(state.round);
+      if (failures >= MAX_FIX_ROUNDS) {
+        return {
+          state: nextState({ state: STATES2.REVISION_REQUIRED, failures, round: next, activeTask: null }),
+          event: recorded(EVENT_KINDS.TASK_REVIEW, { taskId: event.data.taskId, verdict: "fail", failures })
+        };
+      }
+      return {
+        state: nextState({ state: STATES2.FIX_PENDING, failures, round: next, activeTask: null, taskReady: null }),
+        event: recorded(EVENT_KINDS.TASK_REVIEW, { taskId: event.data.taskId, verdict: "fail", round: next, failures })
+      };
+    }
+    case EVENT_KINDS.COMMIT: {
+      if (state.state !== STATES2.COMMIT_PENDING) {
+        throw new Error(`run reducer: COMMIT requires state=commit-pending, got ${state.state}`);
+      }
+      const taskId = state.taskReady?.taskId;
+      const completedTasks = taskId ? state.completedTasks.includes(taskId) ? state.completedTasks : [...state.completedTasks, taskId] : state.completedTasks;
+      return {
+        state: nextState({ state: STATES2.COMMITTED, activeTask: null, round: 0, failures: 0, completedTasks }),
+        event: recorded(EVENT_KINDS.COMMIT, { taskId, commitSha: event.data.commitSha })
+      };
+    }
+    case EVENT_KINDS.TASK_COMPLETE: {
+      if (state.state !== STATES2.COMMITTED) {
+        throw new Error(`run reducer: TASK_COMPLETE requires state=committed, got ${state.state}`);
+      }
+      const moreTasks = event.data.moreTasks === false ? false : true;
+      const nextStateObj = moreTasks ? { state: STATES2.RUNNING, activeTask: null, taskReady: null, round: 0, failures: 0 } : { state: STATES2.ALL_TASKS_DONE, activeTask: null, taskReady: null };
+      return {
+        state: nextState(nextStateObj),
+        event: recorded(EVENT_KINDS.TASK_COMPLETE, { taskId: event.data.taskId, moreTasks, nextTaskId: event.data.nextTaskId ?? null })
+      };
+    }
+    case EVENT_KINDS.FINAL_REVIEW: {
+      if (state.state !== STATES2.ALL_TASKS_DONE && state.state !== STATES2.READY_PENDING) {
+        throw new Error(`run reducer: FINAL_REVIEW requires state=all-tasks-done|ready-pending, got ${state.state}`);
+      }
+      const incomingHash = event.data.packageHash;
+      const incomingHead = event.data.headSha;
+      const incomingMergeBase = event.data.mergeBaseSha;
+      const finalReview = { ...state.finalReview ?? {} };
+      if (state.state === STATES2.ALL_TASKS_DONE) {
+        finalReview.packageHash = incomingHash;
+        finalReview.headSha = incomingHead;
+        finalReview.mergeBaseSha = incomingMergeBase;
+      } else {
+        if (finalReview.packageHash !== incomingHash) {
+          throw new Error(`run reducer: FINAL_REVIEW axis ${event.data.axis} disagrees with package hash`);
+        }
+        if (finalReview.headSha !== incomingHead) {
+          throw new Error(`run reducer: FINAL_REVIEW axis ${event.data.axis} disagrees with HEAD`);
+        }
+        if (finalReview.mergeBaseSha !== incomingMergeBase) {
+          throw new Error(`run reducer: FINAL_REVIEW axis ${event.data.axis} disagrees with merge-base`);
+        }
+      }
+      finalReview[event.data.axis] = event.data.review;
+      return {
+        state: nextState({
+          state: STATES2.READY_PENDING,
+          finalReview
+        }),
+        event: recorded(EVENT_KINDS.FINAL_REVIEW, {
+          axis: event.data.axis,
+          verdict: event.data.verdict,
+          headSha: incomingHead,
+          mergeBaseSha: incomingMergeBase,
+          packageHash: incomingHash,
+          sessionID: event.data.sessionID,
+          review: event.data.review
+        })
+      };
+    }
+    case EVENT_KINDS.READY: {
+      if (state.state !== STATES2.COMMITTED && state.state !== STATES2.READY_PENDING) {
+        throw new Error(`run reducer: READY requires state=committed|ready-pending, got ${state.state}`);
+      }
+      if (state.state === STATES2.READY_PENDING && (!state.finalReview?.standards || !state.finalReview?.spec)) {
+        throw new Error(`run reducer: READY requires both Standards and Spec final reviews`);
+      }
+      if (state.state === STATES2.READY_PENDING && state.finalReview.headSha && event.data.headSha && state.finalReview.headSha !== event.data.headSha) {
+        throw new Error(`run reducer: READY head drift (finalReview=${state.finalReview.headSha.slice(0, 8)}, ready=${event.data.headSha.slice(0, 8)})`);
+      }
+      return {
+        state: nextState({ state: STATES2.READY, activeTask: null, completedTasks: state.completedTasks }),
+        event: recorded(EVENT_KINDS.READY, { headSha: event.data.headSha })
+      };
+    }
+    case EVENT_KINDS.MERGE: {
+      if (state.state !== STATES2.READY) {
+        throw new Error(`run reducer: MERGE requires state=ready, got ${state.state}`);
+      }
+      return {
+        state: nextState({ state: STATES2.MERGED, mergedAt: ev.at, mergeSha: event.data.mergeSha }),
+        event: recorded(EVENT_KINDS.MERGE, { mergeSha: event.data.mergeSha })
+      };
+    }
+    case EVENT_KINDS.DONE: {
+      if (state.state !== STATES2.MERGED) {
+        throw new Error(`run reducer: DONE requires state=merged, got ${state.state}`);
+      }
+      return {
+        state: nextState({ state: STATES2.DONE, activeTask: null }),
+        event: recorded(EVENT_KINDS.DONE, { taskId: event.data.taskId })
+      };
+    }
+    case EVENT_KINDS.BLOCKED: {
+      return {
+        state: nextState({ state: STATES2.BLOCKED, blockedReason: event.data.reason }),
+        event: recorded(EVENT_KINDS.BLOCKED, { reason: event.data.reason })
+      };
+    }
+    default:
+      throw new Error(`run reducer: unknown event kind ${event.kind}`);
+  }
+}
+function createInitialState(workflowId, revision, sha2563) {
+  return {
+    workflowId,
+    revision,
+    sha256: sha2563,
+    state: STATES2.CREATED,
+    activeTask: null,
+    taskReady: null,
+    round: 0,
+    failures: 0,
+    completedTasks: [],
+    events: []
+  };
+}
+var RUN_EVENT_KINDS = EVENT_KINDS;
+function snapshotFields(state) {
+  return {
+    workflowId: state.workflowId,
+    revision: state.revision,
+    sha256: state.sha256,
+    state: state.state,
+    activeTask: state.activeTask,
+    taskReady: state.taskReady ?? null,
+    failures: state.failures,
+    round: state.round,
+    completedTasks: state.completedTasks,
+    finalReview: state.finalReview ?? null
+  };
+}
+function replayPersistedRun(workflowId, snapshot, events) {
+  if (!snapshot || events.length === 0) {
+    throw new Error("run state has no immutable event ledger");
+  }
+  const first = events[0];
+  if (first.kind !== EVENT_KINDS.RUN_START) {
+    throw new Error("run event ledger must begin with run-start");
+  }
+  let state = createInitialState(workflowId, first.data?.revision, first.data?.sha256);
+  let priorHash = "0".repeat(64);
+  for (let index = 0; index < events.length; index += 1) {
+    const persisted = events[index];
+    if (persisted.sequence !== index + 1 || persisted.priorHash !== priorHash) {
+      throw new Error(`run event ledger chain mismatch at sequence ${index + 1}`);
+    }
+    const expectedHash = sha256(canonicalize({
+      kind: persisted.kind,
+      data: persisted.data,
+      at: persisted.at,
+      sequence: persisted.sequence,
+      priorHash
+    }));
+    if (persisted.hash !== expectedHash) {
+      throw new Error(`run event ledger hash mismatch at sequence ${index + 1}`);
+    }
+    const reduced = reduce(state, { kind: persisted.kind, data: persisted.data, at: persisted.at });
+    const replayedEvent = reduced.state.events.at(-1);
+    if (replayedEvent.hash !== persisted.hash) {
+      throw new Error(`run event ledger replay mismatch at sequence ${index + 1}`);
+    }
+    state = reduced.state;
+    priorHash = persisted.hash;
+  }
+  if (canonicalize(snapshotFields(state)) !== canonicalize(snapshotFields(snapshot))) {
+    throw new Error("run snapshot does not match immutable event ledger");
+  }
+  return state;
+}
+async function runDir(repoRoot, workflowId) {
+  const common = await resolveGitCommonDir(repoRoot);
+  return join6(opencodeShipStateDir(common), "runs", workflowId);
+}
+async function appendRunEvent(repoRoot, workflowId, state, event) {
+  const common = await resolveGitCommonDir(repoRoot);
+  const dir = join6(opencodeShipStateDir(common), "runs", workflowId, "events");
+  await mkdir4(dir, { recursive: true });
+  const lockKey = `run:${workflowId}`;
+  return withResourceLock(opencodeShipStateDir(common), lockKey, async () => {
+    const persistedEvents = await readEventsFromDisk(repoRoot, workflowId);
+    const persistedSnapshot = await readSnapshotFromDisk(repoRoot, workflowId);
+    const liveState = persistedEvents.length > 0 ? replayPersistedRun(workflowId, persistedSnapshot, persistedEvents) : normalizeState(state);
+    const { state: next, event: recorded } = reduce(liveState, event);
+    const chainedEvent = next.events.at(-1);
+    const sequence = String(recorded.sequence).padStart(8, "0");
+    const path = join6(dir, `${sequence}.json`);
+    await publishImmutableJson(path, chainedEvent);
+    const runPath = join6(opencodeShipStateDir(common), "runs", workflowId, "run.json");
+    const snapshot = {
+      ...snapshotFields(next),
+      lastEvent: chainedEvent,
+      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await writeFile3(runPath, JSON.stringify(snapshot, null, 2), "utf8");
+    return { state: next, event: chainedEvent };
+  });
+}
+async function readRunState(repoRoot, workflowId) {
+  const dir = await runDir(repoRoot, workflowId);
+  const runPath = join6(dir, "run.json");
+  if (!existsSync5(runPath)) return null;
+  const snapshot = JSON.parse(await readFile5(runPath, "utf8"));
+  const eventsDir = join6(dir, "events");
+  const events = existsSync5(eventsDir) ? await Promise.all(
+    (await readdir3(eventsDir)).filter((n) => n.endsWith(".json")).sort().map(async (n) => JSON.parse(await readFile5(join6(eventsDir, n), "utf8")))
+  ) : [];
+  return replayPersistedRun(workflowId, snapshot, events);
+}
+
+// src/workflow/final-review-store.js
+import { readFile as readFile6 } from "node:fs/promises";
+import { existsSync as existsSync6 } from "node:fs";
+import { join as join7 } from "node:path";
+
+// src/workflow/final-review.js
+import { createHash as createHash6 } from "node:crypto";
+function hashFinalReviewPackage(pkg) {
+  const { packageHash: _packageHash, ...payload } = pkg;
+  return sha2562(canonicalJson(payload));
+}
+function hashAxisRecord(record) {
+  const { reviewHash: _reviewHash, ...payload } = record;
+  return sha2562(canonicalJson(payload));
+}
+function bindFinalReview(standards, spec) {
+  if (standards.headSha !== spec.headSha) {
+    return { ok: false, reason: `head-mismatch: standards=${standards.headSha} spec=${spec.headSha}` };
+  }
+  if (standards.mergeBaseSha !== spec.mergeBaseSha) {
+    return { ok: false, reason: `merge-base-mismatch: standards=${standards.mergeBaseSha} spec=${spec.mergeBaseSha}` };
+  }
+  if (standards.packageHash !== spec.packageHash) {
+    return { ok: false, reason: `package-mismatch: standards=${standards.packageHash} spec=${spec.packageHash}` };
+  }
+  if (standards.verdict !== "pass" || spec.verdict !== "pass") {
+    return { ok: false, reason: `verdict: standards=${standards.verdict} spec=${spec.verdict}` };
+  }
+  const blocking = [...standards.findings ?? [], ...spec.findings ?? []].filter((f) => f.severity === "blocking");
+  if (blocking.length > 0) {
+    return { ok: false, reason: `blocking-findings: ${blocking.length}` };
+  }
+  return { ok: true, headSha: standards.headSha };
+}
+function sha2562(text) {
+  return createHash6("sha256").update(text, "utf8").digest("hex");
+}
+
+// src/workflow/final-review-store.js
+async function readFinalReviewEvidence(repoRoot, workflowId) {
+  const commonDir = await resolveGitCommonDir(repoRoot);
+  const root = join7(opencodeShipStateDir(commonDir), "runs", workflowId, "final-review");
+  const paths = {
+    package: join7(root, "package.json"),
+    standards: join7(root, "standards", "review.json"),
+    spec: join7(root, "spec", "review.json")
+  };
+  for (const [kind, path] of Object.entries(paths)) {
+    if (!existsSync6(path)) throw new Error(`canonical final review ${kind} record is missing`);
+  }
+  const [pkg, standards, spec, runState] = await Promise.all([
+    readJson(paths.package),
+    readJson(paths.standards),
+    readJson(paths.spec),
+    readRunState(repoRoot, workflowId)
+  ]);
+  if (hashFinalReviewPackage(pkg) !== pkg.packageHash) {
+    throw new Error("canonical final review package hash is invalid");
+  }
+  const [verification, ci] = await Promise.all([
+    readGateReceipt(repoRoot, pkg.gateTaskId, "verification", pkg.verificationHash),
+    readGateReceipt(repoRoot, pkg.gateTaskId, "ci", pkg.ciHash)
+  ]);
+  if (!verification || verification.headSha !== pkg.headSha || verification.exitCode !== 0) {
+    throw new Error("canonical verification receipt does not match the final review package");
+  }
+  if (!ci || ci.headSha !== pkg.headSha || ci.checks?.some((check) => check.bucket !== "pass")) {
+    throw new Error("canonical CI receipt does not match the final review package");
+  }
+  for (const [axis, record] of [["standards", standards], ["spec", spec]]) {
+    if (record.axis !== axis || hashAxisRecord(record) !== record.reviewHash) {
+      throw new Error(`canonical ${axis} review record hash is invalid`);
+    }
+    if (record.packageHash !== pkg.packageHash || record.headSha !== pkg.headSha || record.mergeBaseSha !== pkg.mergeBaseSha) {
+      throw new Error(`canonical ${axis} review does not match the final review package`);
+    }
+  }
+  const binding = bindFinalReview(standards, spec);
+  if (!binding.ok) throw new Error(`canonical final review is not passing: ${binding.reason}`);
+  if (!runState || !["ready-pending", "ready", "merged", "done"].includes(runState.state)) {
+    throw new Error(`workflow is not final-review complete (state=${runState?.state ?? "missing"})`);
+  }
+  const summary = runState.finalReview;
+  if (summary?.packageHash !== pkg.packageHash || summary?.headSha !== pkg.headSha || summary?.mergeBaseSha !== pkg.mergeBaseSha || summary?.standards?.reviewHash !== standards.reviewHash || summary?.spec?.reviewHash !== spec.reviewHash) {
+    throw new Error("workflow final-review summary does not match immutable review records");
+  }
+  return { package: pkg, standards, spec, verification, ci, runState };
+}
+async function readJson(path) {
+  return JSON.parse(await readFile6(path, "utf8"));
+}
+
 // src/tools/delivery-ready.js
 function createReadyTool(deps) {
   return async function ready(input) {
@@ -1721,8 +2436,32 @@ function createReadyTool(deps) {
       branch: m.branch,
       required: deps.adapter?.ci?.requiredChecks ?? []
     }) : [];
+    let runState = null;
+    let gateManifest = m;
+    const suppliedWorkflowId = input.workflowId ? String(input.workflowId) : null;
+    if (m.workflowId && suppliedWorkflowId && m.workflowId !== suppliedWorkflowId) {
+      return { kind: "workflow-mismatch", expected: m.workflowId, received: suppliedWorkflowId };
+    }
+    const workflowId = m.workflowId ?? suppliedWorkflowId;
+    if (m.schemaVersion >= 2 && !workflowId) {
+      return { kind: "missing-workflow-link", taskId: m.taskId };
+    }
+    let finalEvidence = null;
+    if (workflowId) {
+      try {
+        finalEvidence = await readFinalReviewEvidence(deps.repoRoot, workflowId);
+      } catch (err) {
+        return { kind: "invalid-final-review-evidence", workflowId, reason: String(err?.message ?? err) };
+      }
+      runState = finalEvidence.runState;
+      gateManifest = {
+        ...m,
+        finalStandardsReview: finalEvidence.standards,
+        finalSpecReview: finalEvidence.spec
+      };
+    }
     const result = checkGates({
-      manifest: { ...m, adapter: deps.adapter },
+      manifest: { ...gateManifest, adapter: deps.adapter },
       prHead,
       checks,
       requires: required
@@ -1738,6 +2477,10 @@ function createReadyTool(deps) {
     if (!t.ok) return { kind: "lifecycle", reason: t.reason };
     const next = {
       ...m,
+      workflowId: workflowId ?? null,
+      finalReviewPackageHash: finalEvidence?.package.packageHash ?? m.finalReviewPackageHash ?? null,
+      finalStandardsReview: finalEvidence?.standards ?? m.finalStandardsReview ?? null,
+      finalSpecReview: finalEvidence?.spec ?? m.finalSpecReview ?? null,
       lastPrHeadSha: prHead,
       state: t.to,
       transitionLog: [
@@ -1747,7 +2490,13 @@ function createReadyTool(deps) {
       updatedAt: (/* @__PURE__ */ new Date()).toISOString()
     };
     const path = await writeManifest(deps.repoRoot, next);
-    return { contractVersion: 1, manifestPath: path, pr: m.prNumber };
+    if (runState && workflowId) {
+      await appendRunEvent(deps.repoRoot, workflowId, runState, {
+        kind: RUN_EVENT_KINDS.READY,
+        data: { headSha: prHead, taskId: input.taskId }
+      });
+    }
+    return { contractVersion: 1, manifestPath: path, pr: m.prNumber, workflowId };
   };
 }
 
@@ -1768,6 +2517,16 @@ function createMergeTool(deps) {
       return { kind: "wrong-base", base: pr.baseRefName };
     }
     const freshGates = deps.adapter?.merge?.requireFreshGates !== false;
+    let finalEvidence = null;
+    if (m.workflowId) {
+      try {
+        finalEvidence = await readFinalReviewEvidence(deps.repoRoot, m.workflowId);
+      } catch (err) {
+        return { kind: "invalid-final-review-evidence", workflowId: m.workflowId, reason: String(err?.message ?? err) };
+      }
+    } else if (m.schemaVersion >= 2) {
+      return { kind: "missing-workflow-link", taskId: m.taskId };
+    }
     if (freshGates) {
       const required = deps.adapter?.ready?.requires ?? [
         "review",
@@ -1782,7 +2541,12 @@ function createMergeTool(deps) {
         required: deps.adapter?.ci?.requiredChecks ?? []
       }) : [];
       const result = checkGates({
-        manifest: { ...m, adapter: deps.adapter },
+        manifest: {
+          ...m,
+          finalStandardsReview: finalEvidence?.standards ?? m.finalStandardsReview,
+          finalSpecReview: finalEvidence?.spec ?? m.finalSpecReview,
+          adapter: deps.adapter
+        },
         prHead: pr.headSha,
         checks,
         requires: required
@@ -1822,6 +2586,12 @@ function createMergeTool(deps) {
       updatedAt: (/* @__PURE__ */ new Date()).toISOString()
     };
     const path = await writeManifest(deps.repoRoot, next);
+    if (finalEvidence && m.workflowId) {
+      await appendRunEvent(deps.repoRoot, m.workflowId, finalEvidence.runState, {
+        kind: RUN_EVENT_KINDS.MERGE,
+        data: { mergeSha: merged.mergeSha ?? merged.mergeCommitSha ?? merged.headSha }
+      });
+    }
     return { kind: "merge", contractVersion: 1, manifestPath: path, pr: m.prNumber, taskId: m.taskId };
   };
 }
@@ -1902,6 +2672,14 @@ function createCleanupTool(deps) {
       };
     }
     const isBootstrapRecovery = m.state === "cleanup-pending" && m.prNumber === null;
+    let workflowRun = null;
+    if (!isBootstrapRecovery && m.schemaVersion >= 2) {
+      if (!m.workflowId) return { kind: "missing-workflow-link", taskId: m.taskId };
+      workflowRun = await readRunState(deps.repoRoot, m.workflowId);
+      if (!workflowRun || workflowRun.state !== "merged") {
+        return { kind: "workflow-not-merged", workflowId: m.workflowId, state: workflowRun?.state ?? null };
+      }
+    }
     if (!isBootstrapRecovery && m.prNumber === null) {
       return { kind: "missing-pr" };
     }
@@ -1952,6 +2730,12 @@ function createCleanupTool(deps) {
     if (branchResult.status !== 0 && branchStillExists(deps.repoRoot, m.branch)) {
       return { kind: "branch-delete-failed", stderr: branchResult.stderr };
     }
+    if (workflowRun && m.workflowId) {
+      await appendRunEvent(deps.repoRoot, m.workflowId, workflowRun, {
+        kind: RUN_EVENT_KINDS.DONE,
+        data: { taskId: m.taskId }
+      });
+    }
     const tCleanup = transition(m, "cleanup-pending", { reason: "worktree removed" });
     const candidate = tCleanup.ok ? {
       ...m,