feature-factory 0.10.0 → 0.10.2

package/bin/factory.js

@@ -4,7 +4,7 @@
 // The orchestrator calls this CLI instead of writing control-plane state directly.
 // Flags are declared per command; unknown options fail rather than becoming missing fields.
 // Schema validation surrounds every state write.
-import { existsSync, lstatSync, mkdirSync, readdirSync, readlinkSync, realpathSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readlinkSync, realpathSync, renameSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { createHash } from "node:crypto";
@@ -12,17 +12,21 @@ import { isDeepStrictEqual } from "node:util";
 import { readFileSync } from "node:fs";
 import { nextAction, nextActionRecord, readRun, readRunUnchecked } from "../state/index.js";
 import { transition } from "../state/transition.js";
+import { RUN_JSON_LOCK_DIR, withRunJsonLock } from "../core/run-lock.js";
 import { buildEvidence, deriveReviewReady, EVIDENCE_KEYS, evidenceRef, git, observeAncestry, observeCleanliness, observeTrackedCleanliness, observeWorktree, privilegedPaths, proveInitContainment, resolveWorktree, runBootstrap, unownedPaths } from "../observe/index.js";
 import { assertPublicationReady, assertReviewBinding, isApproving, observeMergeProof, readEvidence, readReview, readValidatorReview } from "../observe/review.js";
 import { readRepositoryConfig, RepositoryConfigError } from "../observe/repository-config.js";
 import { reverifyRepair } from "../observe/repair-reverification.js";
-import { archiveReviewAttempt } from "../state/review-archive.js";
+import { readRepairState } from "../observe/repair-record.js";
+import { archiveReviewAttempt, publishAttemptArchive, qualifyAttemptArchive } from "../state/review-archive.js";
+import { hasRetryGrantTransaction, prepareRetryGrantTransaction, reconcileRetryGrantTransaction } from "../state/retry-grant-transaction.js";
 import { writeProtectedFileAtomic, writeProtectedJsonAtomic } from "../core/atomic-write.js";
 import { enforceEffectivePushTarget } from "../core/effective-push.js";
 import { resolveSpawnExecutable } from "../core/executable.js";
 import { dispatchInitPublication } from "./init-publication.js";
-import { dispatchRestore, readRestoreRecord } from "./restore.js";
-import { CONTROL_PLANE, SCHEMA_VERSION, GATE_NAMES, GATE_STATUSES, MODES, SLICE_STATUSES, STEP_STATUSES, TERMINAL_STATUSES, repositoryRelativePath, validateRun } from "../state/schema.js";
+import { assertRetryExtensionBindings, dispatchRestore, readRestoreRecord } from "./restore.js";
+import { dispatchSnapshot } from "./snapshot.js";
+import { CONTROL_PLANE, SCHEMA_VERSION, GATE_NAMES, GATE_STATUSES, MODES, RETRY_EXTENSION_SCOPES, SLICE_STATUSES, STEP_STATUSES, TERMINAL_STATUSES, effectiveRetryLimit, repositoryRelativePath, validateRun } from "../state/schema.js";
 import {
   claimSessionLock, inspectSessionLock, refreshSessionLock, releaseSessionLock, SESSION_LOCK_FILE, SessionLockHeldError,
 } from "../state/session-lock.js";
@@ -36,7 +40,9 @@ export const COMMANDS = Object.freeze({
   status: Object.freeze(["--repo", "--json"]),
   "amend-paths": Object.freeze(["--repo", "--add", "--reason", "--session", "--now", "--json"]),
   resume: Object.freeze(["--repo", "--session", "--now", "--json"]),
+  "grant-retry": Object.freeze(["--repo", "--scope", "--reason", "--session", "--now", "--json"]),
   restore: Object.freeze(["--repo", "--from", "--now", "--json"]),
+  snapshot: Object.freeze(["--repo", "--json"]),
   decide: Object.freeze(["--repo", "--text", "--session", "--now", "--json"]),
   // No --force: `lock <id> steal` is the same operation with a name that says what it
   // does, and two spellings of "take someone else's lock" is one too many.
@@ -76,6 +82,24 @@ export async function run(argv) {
   if (!Object.hasOwn(COMMANDS, command)) throw new CliError(`unknown command '${command}' (try --help)`);
   const { positional, flags } = parse(command, rest);
   const handler = HANDLERS[command];
+  if (["init", "status", "snapshot", "lock", "heartbeat", "effective-push"].includes(command)) return handler(positional, flags);
+  const repo = resolve(flags.repo ?? process.cwd()), runId = positional[0];
+  if (command === "restore") {
+    const live = [join(repo, CONTROL_PLANE, runId), join(repo, ".factory-sandboxes", runId, CONTROL_PLANE, runId)]
+      .find((candidate) => existsSync(join(candidate, "run.json")));
+    if (!live) { assertNoRetryGrantTransaction(repo, runId, command); return handler(positional, flags); }
+    return withRunJsonLock(live, async () => { assertNoRetryGrantTransaction(repo, runId, command); return handler(positional, flags); },
+      { nonExpiring: true });
+  }
+  if (["resume", "observe", "reverify-repair"].includes(command)) { assertNoRetryGrantTransaction(repo, runId, command); return handler(positional, flags); }
+  if (typeof runId === "string" && /^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/u.test(runId)
+    && existsSync(join(repo, CONTROL_PLANE, runId, "run.json"))) {
+    return withRunJsonLock(join(repo, CONTROL_PLANE, runId), async () => {
+      assertNoRetryGrantTransaction(repo, runId, command);
+      return handler(positional, flags);
+    }, { allowReentrant: true, nonExpiring: true });
+  }
+  assertNoRetryGrantTransaction(repo, runId, command);
   return handler(positional, flags);
 }
 
@@ -179,18 +203,18 @@ function briefDigestFor(decision, state, runDir) {
 // conclusion was wrong. Both caught in review.
 // Every path component is checked with `lstat` and never followed, since `lstat` on the final entry alone
 // still follows intermediate symlinks.
-function planeInventory(root) {
+function planeInventory(root, skipped = new Set()) {
   const entries = [];
   const record = (rel, full) => {
-    // The session lock is liveness, not run state, and it is the one entry in the plane designed to change
-    // on a timer. Comparing it made every snapshot invalid within one heartbeat: a live park published a
+    // The session lock is liveness, not run state. Exact additional root entries are supplied only while a
+    // protected transition owns its coordination lock and atomic temp. Comparing factory.lock made every snapshot invalid within one heartbeat: a live park published a
     // complete, byte-correct plane and `status` reported `park_snapshot: null` eleven seconds later,
     // because the copy held `heartbeat_at` 23:28:25 and the plane had moved to 23:28:36. The whole point
     // of the field was to answer "did the driver publish it", and it answered "no" for a snapshot that was
     // there -- the same disagree-with-your-own-description defect the 0.8.3 work existed to remove,
     // reintroduced by the check built to remove it. Every existing test publishes and reads back with no
     // heartbeat in between, which is why three review rounds and a real park all missed it.
-    if (rel === SESSION_LOCK_FILE) return;
+    if (rel === SESSION_LOCK_FILE || skipped.has(rel)) return;
     const stat = lstatSync(full);
     const mode = (stat.mode & 0o7777).toString(8);
     if (stat.isSymbolicLink()) entries.push(`${rel} l ${mode} ${readlinkSync(full)}`);
@@ -204,19 +228,53 @@ function planeInventory(root) {
   return entries.sort().join("\n");
 }
 
-function observedParkSnapshot(repo, runId, runDir) {
-  const container = dirname(repo);
-  if (basename(container) !== ".factory-sandboxes" || basename(repo) !== runId) return null;
-  const operatorRoot = dirname(container);
-  const candidate = join(operatorRoot, CONTROL_PLANE, ".parked", runId);
+function observedParkSnapshot(repo, runId, runDir, liveSkipped = new Set()) {
+  const container = dirname(repo), sandbox = basename(container) === ".factory-sandboxes" && basename(repo) === runId;
+  const operatorRoot = sandbox ? dirname(container) : repo, candidate = join(operatorRoot, CONTROL_PLANE, ".parked", runId);
   try {
-    for (const component of [join(operatorRoot, CONTROL_PLANE), join(operatorRoot, CONTROL_PLANE, ".parked"), candidate]) {
-      if (!lstatSync(component).isDirectory()) return null;
-    }
-    if (planeInventory(candidate) !== planeInventory(runDir)) return null;
+    if (hasRetryGrantTransaction(candidate, runId)) return null;
+    const live = [join(operatorRoot, CONTROL_PLANE, runId), join(operatorRoot, ".factory-sandboxes", runId, CONTROL_PLANE, runId)]
+      .filter((plane) => existsSync(join(plane, "run.json")));
+    if (live.length !== 1 || realpathSync(live[0]) !== realpathSync(runDir)) return null;
+    assertRetryExtensionBindings(runDir, readRun(runDir));
+    assertRetryExtensionBindings(candidate, readRun(candidate));
+    for (const component of [join(operatorRoot, CONTROL_PLANE), join(operatorRoot, CONTROL_PLANE, ".parked"), candidate]) if (!lstatSync(component).isDirectory()) return null;
+    if (planeInventory(candidate) !== planeInventory(runDir, liveSkipped)) return null;
     return readFileSync(join(candidate, "run.json")).equals(readFileSync(join(runDir, "run.json"))) ? candidate : null;
-  } catch {
-    return null;
+  } catch { return null; }
+}
+
+function qualifyRetryGrant(repo, runDir, runId, state, sliceId, { requireSnapshot = true } = {}) {
+  const slice = state.slices.find((entry) => entry.id === sliceId);
+  if (!slice) throw new CliError(`unknown slice '${sliceId}'`);
+  const limit = effectiveRetryLimit(state, slice);
+  if (slice.status !== "blocked" || slice.attempts !== limit) throw new CliError(`grant-retry requires slice '${sliceId}' blocked at effective retry limit ${limit}`);
+  if (!slice.review_ref || !slice.evidence_ref) throw new CliError(`grant-retry requires slice '${sliceId}' recorded review and evidence`);
+  const review = readReview(runDir, slice.review_ref), evidence = readEvidence(runDir, slice.evidence_ref, { runId });
+  if (review.subject !== sliceId || review.attempt !== slice.attempts || review.verdict !== "REJECT") throw new CliError(`slice '${sliceId}' attempt ${slice.attempts} does not have a matching REJECT review`);
+  if (evidence.subject !== sliceId || evidence.attempt !== slice.attempts || evidence.base_ref !== slice.base_ref || review.reviewed_commit !== evidence.commit) throw new CliError(`slice '${sliceId}' REJECT does not bind its recorded evidence and base`);
+  const worktree = resolveWorktree(repo, slice.worktree ?? "");
+  if (!worktree) throw new CliError(`slice '${sliceId}' recorded worktree is unavailable`);
+  const branch = git(worktree, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
+  if (!branch.ok || branch.stdout.trim() !== slice.branch) throw new CliError(`slice '${sliceId}' worktree is not on recorded branch '${slice.branch}'`);
+  const cleanliness = observeCleanliness(worktree);
+  if (!cleanliness.clean) throw new CliError(`slice '${sliceId}' ${cleanliness.reason}`);
+  const observed = observeWorktree(worktree, slice.base_ref, { ref: slice.branch });
+  if (!observed.diff_observed || observed.commit !== evidence.commit) throw new CliError(`slice '${sliceId}' REJECT does not bind the live branch head`);
+  const snapshot = requireSnapshot ? observedParkSnapshot(repo, runId, runDir, new Set([RUN_JSON_LOCK_DIR])) : null;
+  if (requireSnapshot && !snapshot) throw new CliError(`grant-retry requires a complete current park snapshot for run '${runId}'`);
+  return { slice, limit, review, evidence, worktree, snapshot,
+    snapshotDigest: snapshot ? planDigest(Buffer.from(planeInventory(snapshot))) : null };
+}
+
+function assertNoRetryGrantTransaction(repo, runId, command) {
+  if (typeof runId !== "string" || !/^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/u.test(runId)) return;
+  const canonicalRepo = existsSync(repo) ? realpathSync(repo) : repo;
+  const container = dirname(canonicalRepo), sandbox = basename(container) === ".factory-sandboxes" && basename(canonicalRepo) === runId;
+  const operatorRoot = sandbox ? dirname(container) : canonicalRepo;
+  const canonical = join(operatorRoot, CONTROL_PLANE, ".parked", runId);
+  if (hasRetryGrantTransaction(canonical, runId)) {
+    throw new CliError(`factory ${command} refuses an interrupted retry-grant transaction for '${runId}'; run factory snapshot first`);
   }
 }
 
@@ -340,7 +398,7 @@ function branchPoint(run) {
   return base;
 }
 
-async function writeObservedEvidence({ runDir, runId, subject, attempt, branch, baseRef, worktree, status, blockedReason, claim, testCommand, skipReason, shellCommand, testTimeoutMs }) {
+async function writeObservedEvidence({ repo, runDir, runId, subject, attempt, branch, baseRef, worktree, status, blockedReason, claim, testCommand, skipReason, shellCommand, testTimeoutMs }) {
   const evidence = buildEvidence({
     subject, attempt, branch, baseRef, worktree, status, blockedReason, claim, runId,
     testCommand, skipReason, shellCommand, testTimeoutMs,
@@ -350,7 +408,10 @@ async function writeObservedEvidence({ runDir, runId, subject, attempt, branch,
     evidence.review_ready = false;
     evidence.blocked_reason = evidence.blocked_reason ?? `base ${baseRef} is ${ancestry} of HEAD`;
   }
-  await writeProtectedJsonAtomic(runDir, evidenceRef(subject), evidence);
+  await withRunJsonLock(runDir, async () => {
+    assertNoRetryGrantTransaction(repo, runId, "observe");
+    await writeProtectedJsonAtomic(runDir, evidenceRef(subject), evidence);
+  }, { nonExpiring: true, reentrant: true });
   return { evidence, ancestry };
 }
 
@@ -464,7 +525,7 @@ async function runRepositoryVerifyAttempts({ repo, runDir, runId, run, mergeComm
   // False-green enforcement: one invocation gets at most two executions, never an unbounded recovery loop.
   for (let attempt = 1; attempt <= 2; attempt += 1) {
     const { evidence } = await writeObservedEvidence({
-      runDir, runId, subject: "test-verifier", attempt, branch: run.branch,
+      repo, runDir, runId, subject: "test-verifier", attempt, branch: run.branch,
       baseRef, worktree: attemptIntegration.worktree, status: "completed", blockedReason: null,
       claim: null, testCommand: verify.command, skipReason: null, shellCommand: true,
       testTimeoutMs: verify.timeoutMs,
@@ -502,6 +563,7 @@ async function verifyRecordedMerge({ repo, runDir, runId, mergeCommit }) {
 
 const HANDLERS = {
   restore: dispatchRestore,
+  snapshot: async (positional, flags) => emit(flags, await dispatchSnapshot(positional, flags)),
 
   async ["reverify-repair"](positional, flags) {
     if (positional.length !== 2) throw new CliError("factory reverify-repair requires exactly <run-id> <repair-record-id>");
@@ -513,7 +575,7 @@ const HANDLERS = {
     const at = stamp(flags);
     const repo = resolve(flags.repo ?? process.cwd());
     const runDir = runDirFor(flags, runId);
-    return emit(flags, await reverifyRepair({ repo, runDir, runId, recordId, at }));
+    return emit(flags, await reverifyRepair({ repo, runDir, runId, recordId, at, beforeWrite: () => assertNoRetryGrantTransaction(repo, runId, "reverify-repair") }));
   },
 
   "effective-push"(positional) {
@@ -630,6 +692,7 @@ const HANDLERS = {
             worktree: null,
             branch: null,
             attempts: 1,
+            extra_attempts: 0,
             // The ratification point: the gate approved these paths and this test plan,
             // so they are the set every later merge is judged against and the decision
             // about whether this slice may ship without an observed test run.
@@ -732,6 +795,93 @@ const HANDLERS = {
       terminal_result: next.terminal_result, amendment: row.path_amendments.at(-1) });
   },
 
+  async ["grant-retry"](positional, flags) {
+    if (positional.length !== 2) throw new CliError("factory grant-retry requires exactly <run-id> <slice-id>");
+    const [runId, sliceId] = positional;
+    if (!RETRY_EXTENSION_SCOPES.includes(flags.scope)) throw new CliError(`factory grant-retry requires --scope ${RETRY_EXTENSION_SCOPES.join("|")}`);
+    if (typeof flags.reason !== "string" || !flags.reason.trim()) throw new CliError("factory grant-retry requires nonblank --reason <text>");
+    if (typeof flags.session !== "string" || !flags.session.trim()) throw new CliError("factory grant-retry requires nonblank --session <id>");
+    const runDir = runDirFor(flags, runId), repo = resolve(flags.repo ?? process.cwd());
+    const boundBytes = readFileSync(join(runDir, "run.json")), current = validateRun(JSON.parse(boundBytes.toString("utf8")));
+    if (current.status !== "needs-human") throw new CliError(`factory grant-retry requires current status needs-human; found '${current.status}'`);
+    const owner = assertFreshSessionOwner(runDir, runId, flags.session, "grant-retry"), at = stamp(flags);
+    if (Date.parse(at) <= Date.parse(current.updated_at)) throw new CliError("grant-retry must move updated_at forwards");
+    const qualified = qualifyRetryGrant(repo, runDir, runId, current, sliceId);
+    if (flags.scope === "all") {
+      const otherBlocked = current.slices.filter((slice) => slice.id !== sliceId && slice.status === "blocked");
+      if (otherBlocked.length) throw new CliError(`grant-retry --scope all refuses while other slices are blocked: ${otherBlocked.map((slice) => slice.id).join(", ")}`);
+      const repairs = readRepairState({ runDir, state: current, runId, repo });
+      if (repairs.records.some((record) => record.status === "exhausted")) throw new CliError("grant-retry --scope all refuses an exhausted post-merge repair bound to the current run-wide limit");
+    }
+    const reviewArchive = qualifyAttemptArchive(runDir, qualified.slice.review_ref, `slice '${sliceId}' review`);
+    const evidenceArchive = qualifyAttemptArchive(runDir, qualified.slice.evidence_ref, `slice '${sliceId}' evidence`);
+    if (!reviewArchive.exists || !evidenceArchive.exists) {
+      if (!reviewArchive.exists) await publishAttemptArchive(runDir, reviewArchive);
+      if (!evidenceArchive.exists) await publishAttemptArchive(runDir, evidenceArchive);
+      throw new CliError(`grant-retry prepared missing immutable attempt archives for slice '${sliceId}'; publish a fresh snapshot and retry; no retry was granted`);
+    }
+    if (!isDeepStrictEqual(reviewArchive.record, qualified.review) || !isDeepStrictEqual(evidenceArchive.record, qualified.evidence)) throw new CliError(`slice '${sliceId}' attempt archives do not bind the qualified review and evidence`);
+    const priorSnapshot = join(dirname(qualified.snapshot), `.prior-${runId}`);
+    if (existsSync(priorSnapshot)) throw new CliError(`grant-retry requires snapshot residual '${priorSnapshot}' to be cleared by factory snapshot`);
+    const recheck = () => {
+      if (!readFileSync(join(runDir, "run.json")).equals(boundBytes)) throw new CliError("grant-retry refused because run.json changed after qualification");
+      if (!sameSessionOwner(runDir, owner)) throw new CliError("grant-retry refused because session ownership changed after qualification");
+      if (planDigest(Buffer.from(planeInventory(qualified.snapshot))) !== qualified.snapshotDigest) throw new CliError("grant-retry refused because the qualified park snapshot changed");
+      const observed = qualifyRetryGrant(repo, runDir, runId, current, sliceId, { requireSnapshot: false });
+      if (!isDeepStrictEqual(observed.review, qualified.review) || !isDeepStrictEqual(observed.evidence, qualified.evidence)) throw new CliError("grant-retry refused because the qualified review or evidence changed");
+      const observedReviewArchive = qualifyAttemptArchive(runDir, qualified.slice.review_ref, `slice '${sliceId}' review`);
+      const observedEvidenceArchive = qualifyAttemptArchive(runDir, qualified.slice.evidence_ref, `slice '${sliceId}' evidence`);
+      if (!observedReviewArchive.exists || observedReviewArchive.archive !== reviewArchive.archive
+        || !observedEvidenceArchive.exists || observedEvidenceArchive.archive !== evidenceArchive.archive) {
+        throw new CliError(`slice '${sliceId}' qualified attempt archives changed before grant-retry commit`);
+      }
+      if (flags.scope === "all") {
+        const repairs = readRepairState({ runDir, state: current, runId, repo });
+        if (repairs.records.some((record) => record.status === "exhausted")) {
+          throw new CliError("grant-retry --scope all refuses an exhausted post-merge repair bound to the current run-wide limit");
+        }
+      }
+    };
+    const mode = flags.scope === "all" ? "grant-retry-all" : "grant-retry-slice";
+    const next = await transition(runDir, {
+      participants: [{ familyId: "envelope", mode }, { familyId: "slices", mode }],
+      reobservers: new Map([["envelope", async () => recheck()]]),
+      // Enforcement: the durable fence is published while the qualified snapshot is still canonical.
+      // It hides stale recovery authority across process death until the manifest outcome is reconciled.
+      finalGuard: ({ source }) => {
+        recheck();
+        prepareRetryGrantTransaction({ canonical: qualified.snapshot, runDir, runId, source,
+          expectedSnapshotDigest: qualified.snapshotDigest });
+      },
+      commitFailureGuard: () => reconcileRetryGrantTransaction({ canonical: qualified.snapshot, runDir, runId }),
+      afterCommit: () => {
+        try { return reconcileRetryGrantTransaction({ canonical: qualified.snapshot, runDir, runId }); }
+        catch (error) { throw new CliError("grant-retry committed; snapshot revocation cleanup is pending", { cause: error }); }
+      },
+      apply: (state) => {
+        if (!isDeepStrictEqual(state, current)) throw new CliError("grant-retry refused because run state changed after qualification");
+        const existing = state.slices.find((slice) => slice.id === sliceId), previousLimit = effectiveRetryLimit(state, existing);
+        const row = { ...existing, status: "running", attempts: existing.attempts + 1,
+          ...(flags.scope === "slice" ? { extra_attempts: (existing.extra_attempts ?? 0) + 1 } : {}),
+          evidence_ref: null, review_ref: null };
+        const maxRetries = state.max_retries + (flags.scope === "all" ? 1 : 0), newLimit = maxRetries + (row.extra_attempts ?? 0);
+        const audit = { scope: flags.scope, slice_id: sliceId, base_ref: existing.base_ref, attempt: row.attempts, previous_limit: previousLimit,
+          new_limit: newLimit, previous_max_retries: state.max_retries, max_retries: maxRetries,
+          session: flags.session, reason: flags.reason.trim(), at, snapshot_digest: qualified.snapshotDigest,
+          review_ref: reviewArchive.archive, review_sha256: reviewArchive.digest,
+          evidence_ref: evidenceArchive.archive, evidence_sha256: evidenceArchive.digest };
+        return { ...state, updated_at: at, max_retries: maxRetries,
+          retry_extensions: [...(state.retry_extensions ?? []), audit],
+          slices: state.slices.map((slice) => slice.id === sliceId ? row : slice) };
+      },
+    });
+    const row = next.slices.find((slice) => slice.id === sliceId), audit = next.retry_extensions.at(-1);
+    return emit(flags, { run_id: runId, slice: sliceId, scope: flags.scope, status: next.status,
+      attempts: row.attempts, retry_limit: effectiveRetryLimit(next, row), max_retries: next.max_retries,
+      review_archive: audit.review_ref, evidence_archive: audit.evidence_ref, park_snapshot: null,
+      next_action: "republish park snapshot, then resume explicitly" });
+  },
+
   async slice([runId, sliceId, status], flags) {
     if (!SLICE_STATUSES.includes(status)) throw new CliError(`status must be one of ${SLICE_STATUSES.join(" | ")}`);
     const runDir = runDirFor(flags, runId);
@@ -751,9 +901,15 @@ const HANDLERS = {
     let observedBase = null;
     if (status === "running") {
       const current = readRun(runDir);
-      const head = integrationHead(repo, current);
-      if (!head.commit) throw new CliError(`could not observe the head of '${current.branch}' to bind the slice base`);
-      observedBase = head.commit;
+      const existing = current.slices.find((slice) => slice.id === sliceId);
+      if (!existing) throw new CliError(`unknown slice '${sliceId}'`);
+      // The base is the historical branch point. Integration HEAD may move after sibling merges,
+      // so only a fresh activation observes it; retries preserve the exact recorded value.
+      if (existing.status === "pending") {
+        const head = integrationHead(repo, current);
+        if (!head.commit) throw new CliError(`could not observe the head of '${current.branch}' to bind the slice base`);
+        observedBase = existing.base_ref ?? head.commit;
+      }
     }
     if (status === "merged" && !flags.mergeCommit) throw new CliError("recording a merge requires --merge-commit");
 
@@ -875,21 +1031,48 @@ const HANDLERS = {
       });
     }
 
+    let retryReviewRef = null;
+    let retryEvidenceRef = null;
     const next = await transition(runDir, {
       participants: [{ familyId: "slices", mode: status === "merged" ? "merge" : "record" }],
       reobservers,
       apply: (state) => {
         const existing = state.slices.find((slice) => slice.id === sliceId);
         if (!existing) throw new Error(`unknown slice '${sliceId}'`);
+        const attempts = flags.attempts === undefined ? existing.attempts : integer(flags.attempts, 1, "--attempts");
+        const advances = attempts === existing.attempts + 1;
+        const blocks = status === "blocked";
+        const closesRejectedReview = existing.status === "review" && (advances || blocks);
+        // Enforcement: only a bound merit REJECT may spend N+1 or terminalize an exhausted review.
+        if (advances && (existing.status !== "review" || status !== "running")) throw new CliError(`slice '${sliceId}' attempts may advance only from review to running`);
+        if (blocks && existing.status !== "review") throw new CliError(`slice '${sliceId}' may block only from review`);
+        const retryLimit = effectiveRetryLimit(state, existing);
+        if (blocks && existing.attempts < retryLimit) throw new CliError(`slice '${sliceId}' cannot block before effective retry limit (${retryLimit})`);
+        if (advances && (flags.worktree !== undefined || flags.branch !== undefined || flags.evidenceRef !== undefined || flags.reviewRef !== undefined)) throw new CliError("a slice retry reuses its recorded worktree, branch, and base; omit worktree, branch, evidence, and review flags");
+        if (closesRejectedReview) {
+          if (!existing.review_ref) throw new CliError(`slice '${sliceId}' retry requires its recorded review`);
+          const review = readReview(runDir, existing.review_ref);
+          if (review.subject !== sliceId || review.attempt !== existing.attempts || review.verdict !== "REJECT") throw new CliError(`slice '${sliceId}' attempt ${existing.attempts} does not have a matching REJECT review`);
+          if (!existing.evidence_ref) throw new CliError(`slice '${sliceId}' retry requires its recorded evidence`);
+          const evidence = readEvidence(runDir, existing.evidence_ref, { runId });
+          const worktree = resolveWorktree(repo, existing.worktree ?? "");
+          if (!worktree) throw new CliError(`slice '${sliceId}' recorded worktree is unavailable`);
+          const observedHead = observeWorktree(worktree, existing.base_ref, { ref: existing.branch }).commit;
+          if (evidence.subject !== sliceId || evidence.attempt !== existing.attempts || evidence.base_ref !== existing.base_ref || review.reviewed_commit !== evidence.commit || observedHead !== evidence.commit) throw new CliError(`slice '${sliceId}' REJECT does not bind its recorded evidence and branch head`);
+          if (advances) {
+            retryReviewRef = existing.review_ref;
+            retryEvidenceRef = existing.evidence_ref;
+          }
+        }
         const row = {
           ...existing,
           status,
-          attempts: flags.attempts === undefined ? existing.attempts : integer(flags.attempts, 1, "--attempts"),
-          worktree: flags.worktree ?? existing.worktree,
-          branch: flags.branch ?? existing.branch,
-          base_ref: observedBase ?? existing.base_ref,
-          evidence_ref: flags.evidenceRef ?? existing.evidence_ref,
-          review_ref: flags.reviewRef ?? existing.review_ref,
+          attempts,
+          worktree: advances ? existing.worktree : flags.worktree ?? existing.worktree,
+          branch: advances ? existing.branch : flags.branch ?? existing.branch,
+          base_ref: advances ? existing.base_ref : observedBase ?? existing.base_ref,
+          evidence_ref: advances ? null : flags.evidenceRef ?? existing.evidence_ref,
+          review_ref: advances ? null : flags.reviewRef ?? existing.review_ref,
           merge_commit: flags.mergeCommit ?? existing.merge_commit,
         };
         return { ...state, updated_at: at, slices: state.slices.map((slice) => (slice.id === sliceId ? row : slice)) };
@@ -902,7 +1085,8 @@ const HANDLERS = {
     // expose it — so the documented path could not be followed at all.
     if (status === "merged") await verifyRecordedMerge({ repo, runDir, runId, mergeCommit: row.merge_commit });
     // Slice attempts are budgeted the same way, so their rejected verdicts vanish the same way.
-    const sliceReviewArchive = await archiveReviewAttempt(runDir, row.review_ref);
+    const sliceReviewArchive = await archiveReviewAttempt(runDir, retryReviewRef ?? row.review_ref);
+    await archiveReviewAttempt(runDir, retryEvidenceRef ?? row.evidence_ref);
     return emit(flags, { ...mergedPayload(runId, sliceId, row), review_archive: sliceReviewArchive });
   },
 
@@ -960,7 +1144,14 @@ const HANDLERS = {
     //
     // A subject with no slice row - test-verifier, an agent step - has no ratified
     // waiver and so has none: its tests must be observed.
-    const slice = run.slices.find((entry) => entry.id === subject);
+    const slice = flags.repositoryVerify ? null : run.slices.find((entry) => entry.id === subject);
+    const attempt = flags.attempt === undefined ? 1 : integer(flags.attempt, 1, "--attempt");
+    if (slice && slice.status !== "running") throw new CliError(`slice '${subject}' must be running before observation; found '${slice.status}'`);
+    if (slice && attempt !== slice.attempts) {
+      // Enforcement: writing canonical evidence for another attempt lets a stale review cycle
+      // bypass the retry transition and its max_retries bound.
+      throw new CliError(`--attempt ${attempt} does not match slice '${subject}' attempt ${slice.attempts}`);
+    }
     if (slice && flags.testCmd !== undefined
       && !slice.test_plan.some((entry) => entry === flags.testCmd)) {
       throw new CliError(
@@ -973,8 +1164,8 @@ const HANDLERS = {
       : null;
 
     const { evidence, ancestry } = await writeObservedEvidence({
-      runDir, runId, subject,
-      attempt: flags.attempt === undefined ? 1 : integer(flags.attempt, 1, "--attempt"),
+      repo, runDir, runId, subject,
+      attempt,
       branch: flags.repositoryVerify ? run.branch : flags.branch ?? null,
       baseRef: flags.base, worktree, status: flags.status ?? "completed",
       blockedReason: flags.blockedReason ?? null, claim,
@@ -1038,7 +1229,9 @@ const HANDLERS = {
       // is unchanged; only the shape is. Breaking for anyone parsing the strings, which is safe here
       // because an exact-match `FACTORY_VERSION` pin already forces consumers to move deliberately.
       steps: run.steps.map((step) => ({ agent: step.agent, status: step.status, attempts: step.attempts })),
-      slices: run.slices.map((slice) => ({ id: slice.id, status: slice.status, attempts: slice.attempts })),
+      slices: run.slices.map((slice) => ({ id: slice.id, status: slice.status, attempts: slice.attempts,
+        extra_attempts: slice.extra_attempts ?? 0, retry_limit: effectiveRetryLimit(run, slice) })),
+      retry_extensions: run.retry_extensions ?? [],
       // Same narrowing: the record carries `report`, `reviewed_head` and `loops`, and only the verdict
       // came out. `loops` says whether validation is converging; `reviewed_head` says what it judged.
       validator: run.validator
@@ -1272,19 +1465,26 @@ const HANDLERS = {
       if (!isDeepStrictEqual(state, current)) throw new CliError("factory resume bootstrap refused: run.json bytes changed while bootstrap ran; current state was preserved");
       if (!sameSessionOwner(runDir, boundOwner)) throw new CliError("factory resume bootstrap refused: factory.lock is absent, stale, or no longer names the same owner; current state and owner were preserved");
     };
-    // Enforcement: never unpark a driver that would keep reading an obsolete staged contract.
-    if (success) await writeProtectedFileAtomic(runDir, "WORKFLOW.md", readFileSync(new URL("../WORKFLOW.md", import.meta.url)));
-    const next = await transition(runDir, {
+    // Enforcement: bootstrap permits its bound session heartbeat; serialize every later effect with grants.
+    const next = await withRunJsonLock(runDir, async () => {
+      assertNoRetryGrantTransaction(repo, runId, "resume"); assertBinding({ state: validateRun(JSON.parse(readFileSync(join(runDir, "run.json")))) });
+      if (success) await writeProtectedFileAtomic(runDir, "WORKFLOW.md", readFileSync(new URL("../WORKFLOW.md", import.meta.url)));
+      return transition(runDir, {
       participants: [{ familyId: "envelope", mode: success ? "resume-needs-human" : "record-bootstrap" }],
-      reobservers: new Map([["envelope", assertBinding]]), finalGuard: ({ state }) => {
+      reobservers: new Map([["envelope", assertBinding]]), finalGuard: ({ state, source }) => {
         if (!readFileSync(join(runDir, "run.json")).equals(boundRunBytes) || !isDeepStrictEqual(state, current)) {
           throw new CliError("factory resume bootstrap refused: run.json bytes changed while bootstrap ran; current state was preserved");
         }
         if (!sameSessionOwner(runDir, boundOwner)) throw new CliError("factory resume bootstrap refused: factory.lock is absent, stale, or no longer names the same owner; current state and owner were preserved");
+        if ((current.retry_extensions?.length ?? 0) > 0
+          && !observedParkSnapshot(repo, runId, runDir, new Set([RUN_JSON_LOCK_DIR, basename(source)]))) {
+          throw new CliError("factory resume requires a complete current park snapshot after grant-retry");
+        }
       },
       apply: (state) => ({ ...state, ...(success ? { status: "running" } : {}), updated_at: at,
         ...(outcome ? { bootstrap_command: config.bootstrapCommand, bootstrap_exit: outcome.exit } : {}) }),
-    });
+      });
+    }, { allowReentrant: true, nonExpiring: true });
     if (outcome?.refusal) throw new CliError(`${outcome.refusal}; run remains needs-human and its historical terminal result is preserved`);
     return emit(flags, {
       run_id: runId, status: next.status, terminal_result: next.terminal_result,
@@ -1588,6 +1788,7 @@ function preflightInit(positional, flags) {
       mode: flags.mode ?? "interactive",
       max_parallel_slices: integer(flags.maxParallelSlices, 3, "--max-parallel-slices"),
       max_retries: integer(flags.maxRetries, 3, "--max-retries"),
+      retry_extensions: [],
       gates: {},
       steps: [],
       slices: [],
@@ -1662,9 +1863,11 @@ function usage() {
   factory init <run-id> [--branch B=feature/<run-id>] [--worktree W=.] [--pr-base TARGET] [--issue KEY] [--mode interactive|headless|autonomous]
   factory status <run-id> [--json]
   factory amend-paths <run-id> <slice-id> --add PATH [--add PATH ...] --reason TEXT --session ID [--now ISO]
+  factory grant-retry <run-id> <slice-id> --scope slice|all --reason TEXT --session ID [--now ISO]
   factory decide <run-id> --text TEXT --session ID [--now ISO]
   factory resume <run-id> --session ID [--now ISO]
   factory restore <run-id> --repo OPERATOR --from refs/remotes/REMOTE/BRANCH [--now ISO]
+  factory snapshot <run-id> --repo OPERATOR
   factory reverify-repair <run-id> <repair-record-id> [--repo PATH] [--now ISO] [--json]
   factory lock <run-id> <claim|steal|release> --session ID [--ttl-ms N]
   factory heartbeat <run-id> --session ID

package/bin/restore.js

@@ -24,9 +24,9 @@ function exactDirectory(path, description) {
   if (stat.isSymbolicLink() || !stat.isDirectory() || realpathSync(path) !== path) throw new RestoreError(`${description} '${path}' is not an exact canonical directory`);
 }
 
-function entryState(path) { try { return lstatSync(path); } catch (error) { if (error?.code === "ENOENT") return null; throw error; } }
+export function entryState(path) { try { return lstatSync(path); } catch (error) { if (error?.code === "ENOENT") return null; throw error; } }
 
-function inventoryEntries(root, skipped = new Set()) {
+export function inventoryEntries(root, skipped = new Set()) {
   const entries = [];
   const visit = (relative, full) => {
     if (skipped.has(relative)) return;
@@ -41,11 +41,11 @@ function inventoryEntries(root, skipped = new Set()) {
   visit(".", root);
   return entries.sort();
 }
-const inventory = (root, skipped = new Set()) => JSON.stringify(inventoryEntries(root, skipped));
+export const inventory = (root, skipped = new Set()) => JSON.stringify(inventoryEntries(root, skipped));
 
-function copySnapshot(source, target) {
+export function copySnapshot(source, target, skipped = SKIPPED_ENTRIES) {
   const copy = (relative, from, to) => {
-    if (SKIPPED_ENTRIES.has(relative)) return;
+    if (skipped.has(relative)) return;
     const stat = lstatSync(from), mode = stat.mode & 0o7777, present = entryState(to);
     if (stat.isDirectory()) {
       if (present && (present.isSymbolicLink() || !present.isDirectory())) throw new RestoreError(`restore target '${to}' has an unsafe type`);
@@ -91,13 +91,31 @@ function jsonAt(runDir, ref, description) {
 
 function safeReview(runDir, ref) { assertRegularRecord(runDir, ref, "review"); return readReview(runDir, ref); }
 function safeEvidence(runDir, ref, runId) { assertRegularRecord(runDir, ref, "evidence"); return readEvidence(runDir, ref, { runId }); }
+const fileDigest = (path) => `sha256:${createHash("sha256").update(readFileSync(path)).digest("hex")}`;
+
+export function assertRetryExtensionBindings(runDir, run) {
+  for (const extension of run.retry_extensions ?? []) {
+    const slice = run.slices.find((entry) => entry.id === extension.slice_id), priorAttempt = extension.attempt - 1;
+    const review = safeReview(runDir, extension.review_ref), evidence = safeEvidence(runDir, extension.evidence_ref, run.run_id);
+    if (fileDigest(join(runDir, extension.review_ref)) !== extension.review_sha256
+      || fileDigest(join(runDir, extension.evidence_ref)) !== extension.evidence_sha256) {
+      throw new RestoreError(`retry extension for slice '${extension.slice_id}' archive digest does not match`);
+    }
+    if (!slice || slice.base_ref !== extension.base_ref || review.subject !== slice.id || review.attempt !== priorAttempt || review.verdict !== "REJECT"
+      || evidence.subject !== slice.id || evidence.attempt !== priorAttempt || evidence.base_ref !== extension.base_ref
+      || evidence.commit !== review.reviewed_commit) {
+      throw new RestoreError(`retry extension for slice '${extension.slice_id}' does not bind its rejected attempt archives`);
+    }
+  }
+}
 
 function transformRun(source, at, head, worktree, sourceRunDir) {
   const resetSlices = [];
   const slices = source.slices.map((slice) => {
-    if (slice.status === "merged") return { ...slice, worktree: null };
+    if (["merged", "blocked"].includes(slice.status)) return slice.status === "merged" ? { ...slice, worktree: null } : { ...slice, worktree: null, branch: null, evidence_ref: null, review_ref: null, merge_commit: null };
     if (slice.status !== "pending" || [slice.worktree, slice.branch, slice.base_ref, slice.evidence_ref, slice.review_ref, slice.merge_commit].some((value) => value !== null)) resetSlices.push(slice.id);
-    return { ...slice, status: "pending", worktree: null, branch: null, base_ref: null, evidence_ref: null, review_ref: null, merge_commit: null };
+    const retryBase = source.retry_extensions?.some((entry) => entry.slice_id === slice.id) ? slice.base_ref : null;
+    return { ...slice, status: "pending", worktree: null, branch: null, base_ref: retryBase, evidence_ref: null, review_ref: null, merge_commit: null };
   });
   const invalidated = [];
   const verifierState = source.steps.some((step) => step.agent === "test-verifier" && (step.status === "accepted" || step.review_ref || step.evidence_ref))
@@ -176,6 +194,7 @@ function qualifySource(operatorRoot, runId) {
   const bytes = readFileSync(manifest), run = validateRun(JSON.parse(bytes.toString("utf8")));
   if (run.run_id !== runId) throw new RestoreError(`park snapshot run_id '${run.run_id}' does not match requested '${runId}'`);
   if (run.status !== "needs-human") throw new RestoreError(`factory restore requires a needs-human snapshot; found '${run.status}'`);
+  assertRetryExtensionBindings(source, run);
   const entries = inventoryEntries(source), skipped = [...SKIPPED_ENTRIES];
   return { source, bytes, run, inventory: JSON.stringify(entries),
     copied: JSON.stringify(entries.filter((entry) => !skipped.some((name) => entry.startsWith(`${name} `) || entry.startsWith(`${name}/`)))) };
@@ -267,6 +286,7 @@ export async function dispatchRestore(positional, flags, operations = {}) {
   // Test seam only: production supplies no hook. The final guard below must catch any intervening writer.
   if (operations.beforeManifest) await operations.beforeManifest({ runDir, sandbox });
   const finalGuard = () => {
+    if ([`.grant-retry-${runId}.json`, `.grant-retry-${runId}.json.staging`].some((name) => entryState(join(dirname(qualified.source), name)))) throw new RestoreError("restore refuses an interrupted retry-grant transaction");
     if (!readFileSync(join(qualified.source, "run.json")).equals(qualified.bytes) || inventory(qualified.source) !== qualified.inventory) throw new RestoreError("park snapshot changed while restore was running; run.json was not published");
     if (inventory(runDir) !== preparedInventory) throw new RestoreError("restored control plane changed before manifest publication; run.json was not published");
     if (entryState(legacyManifest)) throw new RestoreError(`live run manifest appeared at '${legacyManifest}' while restore was running`);