feature-factory 0.10.1 → 0.10.2

package/README.md

@@ -265,8 +265,9 @@ waves too, but refuses when another slice is blocked or an exhausted post-merge
 scopes reopen only the named slice after exact owner, snapshot, REJECT, evidence, base, current clean head,
 and immutable attempt archives. A legacy run missing one prepares it without granting, then requires a
 fresh snapshot and a second grant invocation. Exhaustion parks with reason `blocked-after-retries` rather
-than terminalizing `partial`. The grant moves the prior canonical snapshot away, so restore cannot recover
-pre-grant authority; run `factory snapshot <run-id> --repo <operator>` and requalify it before the separate
+than terminalizing `partial`. The grant durably fences the prior canonical snapshot before committing its
+manifest, then removes it only after the commit is proved; restore and parked mutations refuse any
+interrupted fence. Run `factory snapshot <run-id> --repo <operator>` and requalify it before the separate
 explicit resume. Restored blocked slices whose physical refs were intentionally cleared do not qualify.
 
 `resolve` and `verify` are consumed now, and the run's recorded `publishing_identity` is compared at the publication guards. Step 6 resolves one selection: a nonblank inherited `FACTORY_PUBLISHING_COMMAND` selects its exact string; that variable set blank or whitespace selects the default; when it is unset, configured `publish` wins if present; otherwise the default wins. Only a selected nondefault command replaces `gh pr create`, after the factory-owned exact push and post-push identity guard. It receives exact `PR_BASE`, `FEATURE_BRANCH`, `PR_DRAFT`, `PR_TITLE`, and absolute `PR_BODY_FILE` environment values. Only exit zero with an absolute HTTPS URL on the last nonempty stdout line is recordable; every other result parks with exact reason `selected publishing command outcome indeterminate; re-observe whether the pull request exists before retry` and no fallback.

package/WORKFLOW.md

@@ -236,8 +236,9 @@ an archive gets a preparation-only refusal: publish the changed plane and invoke
 append the durable authorization, preserve worktree, branch and `base_ref`, clear only the live attempt-bound
 refs, and record `running@(N+1)` while top-level status and `terminal_result` remain parked.
 
-The grant atomically moves the old canonical snapshot away so restore cannot recover pre-grant authority.
-Do not dispatch or resume yet. Republish the updated live plane, then require qualified status
+The grant durably fences the old canonical snapshot before committing `run.json`, then removes it only
+when the manifest commit is proved. Restore and parked mutations refuse an interrupted fence; `factory
+snapshot` reconciles exact pre-commit or post-commit state under the run lock. Do not dispatch or resume yet. Republish the updated live plane, then require qualified status
 to report the refreshed `park_snapshot`, unchanged owner, the chosen new effective limit, and only the named
 slice at `running@(N+1)`. Only then run the ordinary explicit
 `factory resume "$R" --session "$SESSION_ID" --repo "$RUN_REPO"` and dispatch that attempt. Resume refreshes

package/bin/factory.js

@@ -12,13 +12,14 @@ 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 } from "../core/run-lock.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 { 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";
@@ -81,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);
 }
 
@@ -213,6 +232,7 @@ 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 {
+    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;
@@ -241,12 +261,23 @@ function qualifyRetryGrant(repo, runDir, runId, state, sliceId, { requireSnapsho
   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) : null;
+  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`);
+  }
+}
+
 function runDirFor(flags, runId) {
   if (!runId) throw new CliError("a <run-id> is required");
   return join(resolve(flags.repo ?? process.cwd()), CONTROL_PLANE, runId);
@@ -367,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,
@@ -377,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 };
 }
 
@@ -491,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,
@@ -541,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) {
@@ -812,7 +846,18 @@ const HANDLERS = {
     const next = await transition(runDir, {
       participants: [{ familyId: "envelope", mode }, { familyId: "slices", mode }],
       reobservers: new Map([["envelope", async () => recheck()]]),
-      finalGuard: () => { recheck(); renameSync(qualified.snapshot, priorSnapshot); },
+      // 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);
@@ -1119,7 +1164,7 @@ const HANDLERS = {
       : null;
 
     const { evidence, ancestry } = await writeObservedEvidence({
-      runDir, runId, subject,
+      repo, runDir, runId, subject,
       attempt,
       branch: flags.repositoryVerify ? run.branch : flags.branch ?? null,
       baseRef: flags.base, worktree, status: flags.status ?? "completed",
@@ -1420,9 +1465,11 @@ 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, source }) => {
         if (!readFileSync(join(runDir, "run.json")).equals(boundRunBytes) || !isDeepStrictEqual(state, current)) {
@@ -1436,7 +1483,8 @@ const HANDLERS = {
       },
       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,

package/bin/restore.js

@@ -286,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`);

package/bin/snapshot.js

@@ -6,11 +6,13 @@
 // the plane is worse than none -- `status` reports a path, an operator believes the run is recoverable,
 // and the copy is found partial only when it is needed -- so verify-before-commit cannot be delegated to
 // prose for a caller that is not the driver.
-import { mkdirSync, readFileSync, realpathSync, renameSync, rmSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { CONTROL_PLANE, validateRun } from "../state/schema.js";
+import { hasRetryGrantTransaction, isRetryGrantTransition, reconcileRetryGrantTransaction } from "../state/retry-grant-transaction.js";
 import { RUN_JSON_LOCK_DIR, withRunJsonLock } from "../core/run-lock.js";
-import { assertRetryExtensionBindings, copySnapshot, entryState, inventory } from "./restore.js";
+import { assertRetryExtensionBindings, copySnapshot, entryState, inventory, inventoryEntries } from "./restore.js";
 
 // The two root entries excluded from publication are coordination, not run state: `factory.lock` is session
 // liveness and `run-json.lock` serializes this copy with state transitions. Only those exact root paths are
@@ -23,15 +25,57 @@ export class SnapshotError extends Error {
 
 const ID = /^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/u;
 
-// Removing a residual `.prior-$R` is preflight, not rollback: it is the trace of an earlier publication
-// whose cleanup did not finish, not a snapshot to preserve. Failing to remove it stops before anything is
-// staged, because publishing over an unknown residual would make the rollback path ambiguous.
-function preflight(staging, prior) {
+// Version 0.10.1 also used `.prior-$R` as its grant seam. Exact old bytes prove its grant did not
+// commit; the grant contracts plus the bound snapshot digest prove that it did. Anything else is
+// preserved and refused. New grants use a distinct durable fence and never overload this path.
+function preflight(staging, prior, canonical, plane, runId) {
   if (entryState(staging)) throw new SnapshotError(`residual staging tree '${staging}' must be removed before publishing`);
-  if (entryState(prior)) {
-    try { rmSync(prior, { recursive: true, force: true }); }
-    catch (error) { throw new SnapshotError(`residual '${prior}' could not be removed`, { cause: error }); }
+  const cleanup = `${prior}.cleanup`;
+  if (entryState(cleanup)) rmSync(cleanup, { recursive: true, force: true });
+  const priorState = entryState(prior);
+  if (!priorState) return;
+  if (priorState.isSymbolicLink() || !priorState.isDirectory()) {
+    throw new SnapshotError(`residual '${prior}' has an unsafe type`);
   }
+  if (!entryState(canonical)) {
+    const before = qualifyManifest(prior, runId, "prior park manifest");
+    const current = qualifyManifest(plane, runId, "run manifest");
+    if (readFileSync(join(prior, "run.json")).equals(readFileSync(join(plane, "run.json")))) {
+      removeAbandonedGrantCandidate(plane, prior, before);
+      if (inventory(plane, LIVENESS) !== inventory(prior, LIVENESS)) {
+        throw new SnapshotError("interrupted retry grant live plane changed from its prior snapshot");
+      }
+      renameSync(prior, canonical);
+      return;
+    }
+    if (!isCommittedRetryGrant(before, current, prior)) {
+      throw new SnapshotError(`residual '${prior}' is not a recoverable retry-grant transaction`);
+    }
+  } else {
+    qualifyManifest(canonical, runId, "canonical park manifest");
+  }
+  try { renameSync(prior, cleanup); rmSync(cleanup, { recursive: true, force: true }); }
+  catch (error) { throw new SnapshotError(`residual '${prior}' could not be quarantined`, { cause: error }); }
+}
+
+function removeAbandonedGrantCandidate(plane, prior, before) {
+  const candidates = readdirSync(plane).filter((name) => /^\.[0-9a-f-]{36}\.tmp$/u.test(name)
+    && !entryState(join(prior, name)));
+  if (candidates.length === 0) return;
+  if (candidates.length !== 1) throw new SnapshotError("interrupted retry grant has ambiguous atomic candidates");
+  const candidatePath = join(plane, candidates[0]), state = entryState(candidatePath);
+  let candidate;
+  try { candidate = state?.isFile() && !state.isSymbolicLink()
+    ? validateRun(JSON.parse(readFileSync(candidatePath, "utf8"))) : null; } catch { candidate = null; }
+  if (!candidate || !isCommittedRetryGrant(before, candidate, prior)) {
+    throw new SnapshotError("interrupted retry grant has an unbound atomic candidate");
+  }
+  rmSync(candidatePath);
+}
+
+function isCommittedRetryGrant(before, after, prior) {
+  const digest = `sha256:${createHash("sha256").update(Buffer.from(inventoryEntries(prior).join("\n"))).digest("hex")}`;
+  return isRetryGrantTransition(before, after, digest);
 }
 
 // Applied to the live plane before staging and to the staged tree before the commit. The same schema and
@@ -58,73 +102,72 @@ export async function dispatchSnapshot(positional, flags, operations = {}) {
   if (flags.repo !== undefined && (typeof flags.repo !== "string" || !flags.repo.trim())) throw new SnapshotError("--repo must name a directory");
   const runId = positional[0], operatorInput = resolve(flags.repo ?? process.cwd());
   if (!entryState(operatorInput)) throw new SnapshotError(`operator repository '${operatorInput}' is not observable`);
-  const operatorRoot = realpathSync(operatorInput);
+  const operatorRoot = realpathSync(operatorInput), parked = join(operatorRoot, CONTROL_PLANE, ".parked");
+  const canonical = join(parked, runId), fenced = hasRetryGrantTransaction(canonical, runId);
   const candidates = [join(operatorRoot, CONTROL_PLANE, runId), join(operatorRoot, ".factory-sandboxes", runId, CONTROL_PLANE, runId)]
-    .filter((candidate) => entryState(join(candidate, "run.json")));
+    .filter((candidate) => entryState(join(candidate, "run.json"))
+      || (fenced && entryState(candidate)?.isDirectory() && !entryState(candidate).isSymbolicLink()));
   if (candidates.length !== 1) throw new SnapshotError(candidates.length
     ? `factory snapshot found ambiguous live manifests for '${runId}'`
     : `control plane for '${runId}' is not observable`);
   const plane = candidates[0];
-  qualifyManifest(plane, runId, "run manifest");
 
   return withRunJsonLock(plane, async () => {
-  qualifyManifest(plane, runId, "run manifest");
-
-  // Created one directory at a time, never written through a symlinked parent: the snapshot must land
-  // under the operator's own control plane and nowhere a link could redirect it.
-  const parked = join(operatorRoot, CONTROL_PLANE, ".parked");
-  for (const parent of [join(operatorRoot, CONTROL_PLANE), parked]) {
-    const present = entryState(parent);
-    if (present && (present.isSymbolicLink() || !present.isDirectory())) {
-      throw new SnapshotError(`'${parent}' must be a real directory to publish a snapshot`);
+    // Created one directory at a time, never written through a symlinked parent: the snapshot must land
+    // under the operator's own control plane and nowhere a link could redirect it.
+    for (const parent of [join(operatorRoot, CONTROL_PLANE), parked]) {
+      const present = entryState(parent);
+      if (present && (present.isSymbolicLink() || !present.isDirectory())) {
+        throw new SnapshotError(`'${parent}' must be a real directory to publish a snapshot`);
+      }
+      if (!present) mkdirSync(parent);
     }
-    if (!present) mkdirSync(parent);
-  }
-  const canonical = join(parked, runId);
-  const staging = join(parked, `.staging-${runId}`);
-  const prior = join(parked, `.prior-${runId}`);
-  preflight(staging, prior);
+    const staging = join(parked, `.staging-${runId}`), prior = join(parked, `.prior-${runId}`);
+    try { reconcileRetryGrantTransaction({ canonical, runDir: plane, runId }); }
+    catch (error) { throw new SnapshotError(`factory snapshot could not reconcile retry-grant transaction for '${runId}'`, { cause: error }); }
+    qualifyManifest(plane, runId, "run manifest");
+    preflight(staging, prior, canonical, plane, runId);
 
-  let committed = false;
-  try {
-    (operations.copy ?? copySnapshot)(plane, staging, LIVENESS);
-    // Verify before the commit point. An unverified staging tree is never published, so a copy that
-    // raced a write is discarded rather than published as evidence of a run it does not describe.
-    if (inventory(plane, LIVENESS) !== inventory(staging, LIVENESS)) {
-      throw new SnapshotError("staged snapshot does not match the live control plane; nothing was published");
-    }
-    // Equality alone cannot catch a manifest replaced between qualification and copy: both trees then
-    // hold the same unvalidated bytes and compare equal. Qualify what is about to be renamed.
-    qualifyManifest(staging, runId, "staged run manifest");
-    await operations.beforeCommit?.({ plane, staging, canonical });
-    if (!entryState(canonical)) {
-      renameSync(staging, canonical);          // commit point, with no snapshot present
-      committed = true;
-    } else {
-      renameSync(canonical, prior);
-      try {
-        renameSync(staging, canonical);        // commit point, replacing a previous snapshot
+    let committed = false;
+    try {
+      (operations.copy ?? copySnapshot)(plane, staging, LIVENESS);
+      // Verify before the commit point. An unverified staging tree is never published, so a copy that
+      // raced a write is discarded rather than published as evidence of a run it does not describe.
+      if (inventory(plane, LIVENESS) !== inventory(staging, LIVENESS)) {
+        throw new SnapshotError("staged snapshot does not match the live control plane; nothing was published");
+      }
+      // Equality alone cannot catch a manifest replaced between qualification and copy: both trees then
+      // hold the same unvalidated bytes and compare equal. Qualify what is about to be renamed.
+      qualifyManifest(staging, runId, "staged run manifest");
+      await operations.beforeCommit?.({ plane, staging, canonical });
+      if (!entryState(canonical)) {
+        renameSync(staging, canonical);          // commit point, with no snapshot present
         committed = true;
-      } catch (error) {
-        // The first rename succeeded and the second did not: put the previous snapshot back and report
-        // that nothing was committed, rather than leaving the canonical path empty.
-        renameSync(prior, canonical);
-        throw new SnapshotError("snapshot commit failed; the previous snapshot was restored", { cause: error });
+      } else {
+        renameSync(canonical, prior);
+        try {
+          renameSync(staging, canonical);        // commit point, replacing a previous snapshot
+          committed = true;
+        } catch (error) {
+          // The first rename succeeded and the second did not: put the previous snapshot back and report
+          // that nothing was committed, rather than leaving the canonical path empty.
+          renameSync(prior, canonical);
+          throw new SnapshotError("snapshot commit failed; the previous snapshot was restored", { cause: error });
+        }
       }
+    } finally {
+      // Before the commit point every failure removes only the staging tree. After it the published
+      // snapshot is authoritative and is never rolled back.
+      if (!committed) rmSync(staging, { recursive: true, force: true });
     }
-  } finally {
-    // Before the commit point every failure removes only the staging tree. After it the published
-    // snapshot is authoritative and is never rolled back.
-    if (!committed) rmSync(staging, { recursive: true, force: true });
-  }
 
-  // Cleanup, not publication: a residual `.prior-$R` is reported and left for the next preflight rather
-  // than turning a completed publication into a failure.
-  let residual = null;
-  if (entryState(prior)) {
-    try { rmSync(prior, { recursive: true, force: true }); }
-    catch { residual = prior; }
-  }
-  return { run_id: runId, park_snapshot: canonical, residual };
+    // Cleanup, not publication: a residual `.prior-$R` is reported and left for the next preflight rather
+    // than turning a completed publication into a failure.
+    let residual = null;
+    if (entryState(prior)) {
+      try { rmSync(prior, { recursive: true, force: true }); }
+      catch { residual = prior; }
+    }
+    return { run_id: runId, park_snapshot: canonical, residual };
   }, { nonExpiring: true });
 }

package/core/atomic-write.js

@@ -7,7 +7,7 @@
 // become readable. beforeCommit is the last race seam used by CAS and create-only tests.
 import { lstat, open, realpath, rename as fsRename, unlink } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
-import { isAbsolute, join, resolve, sep } from "node:path";
+import { basename, isAbsolute, join, resolve, sep } from "node:path";
 
 export class ProtectedWriteError extends Error {
   constructor(message, cause) {
@@ -23,14 +23,16 @@ export function writeProtectedJsonAtomic(rootDir, relativePath, value, options =
 export async function writeProtectedFileAtomic(rootDir, relativePath, data, options = {}) {
   const targetPath = resolveProtectedPath(rootDir, relativePath), parentDir = resolve(targetPath, "..");
   const createOnly = options.createOnly === true, beforeCommit = options.hooks?.beforeCommit;
+  const afterRename = options.hooks?.afterRename;
   const openFile = options.fsOps?.open ?? open;
   const bytes = Buffer.isBuffer(data) ? Buffer.from(data) : Buffer.from(String(data), "utf8");
-  await assertSafeParent(rootDir, parentDir);
+  const tempParent = options.tempDirectory === undefined ? parentDir : resolveProtectedPath(rootDir, options.tempDirectory);
+  for (const parent of new Set([parentDir, tempParent])) await assertSafeParent(rootDir, parent);
   await assertSafeTarget(targetPath, createOnly);
   if (createOnly) return writeProtectedCreate(rootDir, parentDir, targetPath, bytes, beforeCommit, openFile);
 
-  const tempPath = join(parentDir, `.${randomUUID()}.tmp`), rename = options.fsOps?.rename ?? fsRename;
-  let handle = null, published = false, targetLinked = false;
+  const tempPath = join(tempParent, `.${basename(targetPath)}.${randomUUID()}.tmp`), rename = options.fsOps?.rename ?? fsRename;
+  let handle = null, published = false, renamed = false;
   try {
     handle = await openFile(tempPath, "wx+", 0o600);
     await handle.writeFile(bytes);
@@ -40,15 +42,17 @@ export async function writeProtectedFileAtomic(rootDir, relativePath, data, opti
     await assertSafeTarget(targetPath, false);
     await assertPublishedInode(handle, tempPath, bytes);
     await rename(tempPath, targetPath);
-    targetLinked = true;
+    renamed = true;
+    if (typeof afterRename === "function") await afterRename({ source: tempPath, destination: targetPath });
     await assertPublishedInode(handle, targetPath, bytes);
     await handle.close();
     handle = null;
     published = true;
   } catch (error) {
     if (handle) try { await handle.close(); } catch { /* the original error is primary */ }
-    if (targetLinked && !published) try { await unlink(targetPath); } catch { /* integrity failure is primary */ }
-    if (!published) try { await unlink(tempPath); } catch (cleanupError) {
+    // Once rename succeeds the target is the only durable after-image. Preserve it for validation or
+    // transaction recovery instead of converting a post-commit verification failure into lost state.
+    if (!published && !renamed) try { await unlink(tempPath); } catch (cleanupError) {
       if (cleanupError?.code !== "ENOENT") throw new ProtectedWriteError("protected temporary file cleanup is indeterminate", cleanupError);
     }
     throw error instanceof ProtectedWriteError ? error : new ProtectedWriteError("protected file commit failed", error);

package/core/run-lock.js

@@ -2,11 +2,12 @@
 // The 0c spike reused this lock as-is, which is why it is lifted rather than
 // rewritten: hand-rolling lock reclaim and steal logic is where subtle crash bugs
 // live. Only the imports and the extracted constants below are new.
+import { AsyncLocalStorage } from "node:async_hooks";
 import { constants } from "node:fs";
 import { lstat, mkdir, open, rename, rm, stat, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { hostname } from "node:os";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 
 const DEFAULT_LOCK_TIMEOUT_MS = 1000;
 const DEFAULT_LOCK_RETRY_DELAY_MS = 10;
@@ -15,11 +16,14 @@ const DEFAULT_MISSING_OWNER_STEAL_MS = 5000;
 export const RUN_JSON_LOCK_DIR = "run-json.lock";
 const LOCK_DIR = RUN_JSON_LOCK_DIR;
 const LOCK_OWNER_FILE = "owner.json";
+const LOCK_CONTEXT = new AsyncLocalStorage();
 
 export async function withRunJsonLock(runDir, fn, options = {}) {
   if (typeof fn !== "function") throw new Error("withRunJsonLock requires a callback");
-  const { onBeforeSteal, nonExpiring } = options;
-  if (nonExpiring !== undefined && typeof nonExpiring !== "boolean") throw new Error("nonExpiring must be boolean");
+  const key = resolve(runDir), inherited = LOCK_CONTEXT.getStore()?.get(key);
+  if (options.reentrant === true && inherited?.active === true) return fn(inherited);
+  const { allowReentrant, onBeforeSteal, nonExpiring, reentrant } = options;
+  if ([allowReentrant, reentrant, nonExpiring].some((value) => value !== undefined && typeof value !== "boolean")) throw new Error("run lock boolean options must be boolean");
   if (onBeforeSteal !== undefined && typeof onBeforeSteal !== "function") {
     throw new Error("onBeforeSteal must be a function");
   }
@@ -32,6 +36,7 @@ export async function withRunJsonLock(runDir, fn, options = {}) {
   let stealAttempted = false;
   let createdIdentity = null;
   let owner = null;
+  let context = null;
   let ownerPublished = false;
   let publishedEvidence = null;
 
@@ -68,8 +73,13 @@ export async function withRunJsonLock(runDir, fn, options = {}) {
     publishedEvidence = await readLockOwnerEvidence(ownerPath);
     if (!sameLockOwner(owner, publishedEvidence?.owner)) throw new Error(`run.json lock owner publication failed at ${lockDir}`);
     ownerPublished = true;
-    return await fn({ lock_dir: lockDir, owner });
+    const lease = { lock_dir: lockDir, owner, active: true };
+    if (!allowReentrant) return await fn(lease);
+    context = lease;
+    const locks = new Map(LOCK_CONTEXT.getStore() ?? []); locks.set(key, context);
+    return await LOCK_CONTEXT.run(locks, () => fn(context));
   } finally {
+    if (context) context.active = false;
     if (ownerPublished) {
       await releaseOwnedRunJsonLock(runDir, lockDir, createdIdentity, publishedEvidence);
     } else if (!ownerPublished && !(await lockOwnerEntryExists(ownerPath))) {

package/core/write-core.js

@@ -14,6 +14,8 @@ export async function coordinateRunJsonTransition(runDir, options) {
     reobservers = new Map(),
     atomicWriteHooks,
     finalGuard,
+    commitFailureGuard,
+    afterCommit,
   } = options ?? {};
   const registry = contractRegistry(contracts);
   const participants = participantRegistry(descriptor, registry);
@@ -70,16 +72,27 @@ export async function coordinateRunJsonTransition(runDir, options) {
           // Only the synchronous final guard may run between this line and the rename.
           const finalObserved = deepFreeze(await readRunState(runDir, validateRun));
           assertUnchanged(finalObserved, initial);
+          let guarded = false;
           if (typeof finalGuard === "function") {
-            const guarded = finalGuard({ state: finalObserved, candidate, source });
-            if (guarded && typeof guarded.then === "function") throw new Error("final commit guard must be synchronous");
+            const result = finalGuard({ state: finalObserved, candidate, source });
+            if (result && typeof result.then === "function") throw new Error("final commit guard must be synchronous");
+            guarded = true;
+          }
+          try {
+            await rename(source, destination);
+          } catch (error) {
+            if (guarded && typeof commitFailureGuard === "function") {
+              const result = commitFailureGuard({ state: finalObserved, candidate, source, error });
+              if (result && typeof result.then === "function") throw new Error("commit failure guard must be synchronous");
+            }
+            throw error;
           }
-          await rename(source, destination);
         },
       },
     });
+    if (typeof afterCommit === "function") await afterCommit({ state: initial, candidate });
     return candidate;
-  });
+  }, { reentrant: true });
 }
 
 function assertUnchanged(observed, initial) {

package/observe/repair-reverification.js

@@ -66,7 +66,7 @@ function removeDetached(repo, temporary) {
   }
 }
 
-export async function reverifyRepair({ repo, runDir, runId, recordId, at }) {
+export async function reverifyRepair({ repo, runDir, runId, recordId, at, beforeWrite = () => {} }) {
   const parsedAt = typeof at === "string" ? Date.parse(at) : NaN;
   if (!Number.isFinite(parsedAt) || new Date(parsedAt).toISOString() !== at) throw new Error("repair re-verification timestamp is not canonical");
   const preread = readRepairState({ repo, runDir, runId, recordId });
@@ -84,7 +84,7 @@ export async function reverifyRepair({ repo, runDir, runId, recordId, at }) {
   let reservation;
   try {
     reservation = await withRunJsonLock(runDir, async () => {
-      const current = readRepairState({ repo, runDir, runId, recordId });
+      const current = readRepairState({ repo, runDir, runId, recordId }); beforeWrite();
       assertEnvelope(current.run);
       assertDetached(temporary.worktree, current.selected.repair_commit);
       const history = current.selectedHistory;
@@ -131,7 +131,7 @@ export async function reverifyRepair({ repo, runDir, runId, recordId, at }) {
   removeDetached(repo, temporary);
 
   const completed = await withRunJsonLock(runDir, async () => {
-    const current = readRepairState({ repo, runDir, runId, recordId });
+    const current = readRepairState({ repo, runDir, runId, recordId }); beforeWrite();
     assertEnvelope(current.run);
     if (!current.runBytes.equals(reservation.runBytes) || !current.journalBytes.equals(reservation.journalBytes)) {
       throw new Error("run or repair journal bytes changed during re-verification");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feature-factory",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "description": "Durable, observed control plane for /feature runs. Host-agnostic: no opencode dependency.",
   "type": "module",
   "license": "MIT",

package/state/retry-grant-transaction.js

@@ -0,0 +1,194 @@
+import { createHash } from "node:crypto";
+import { closeSync, fsyncSync, lstatSync, openSync, readFileSync, readdirSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { FAMILY_CONTRACTS } from "../core/contracts.js";
+import { validateRun } from "./schema.js";
+import { inventoryEntries } from "../bin/restore.js";
+
+const VERSION = 1;
+const UUID_TEMP = /^\.run\.json\.[0-9a-f-]{36}\.tmp$/u;
+const sha256 = (bytes) => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+const state = (path) => { try { return lstatSync(path); } catch (error) { if (error?.code === "ENOENT") return null; throw error; } };
+const paths = (canonical, runId) => { const fence = join(dirname(canonical), `.grant-retry-${runId}.json`);
+  return { fence, staging: `${fence}.staging`, revoked: join(dirname(canonical), `.revoked-grant-retry-${runId}`) }; };
+const snapshotDigest = (path) => sha256(Buffer.from(inventoryEntries(path).join("\n")));
+
+export function hasRetryGrantTransaction(canonical, runId) {
+  const { fence, staging } = paths(canonical, runId);
+  return Boolean(state(staging) || state(fence));
+}
+
+export function prepareRetryGrantTransaction({ canonical, runDir, runId, source, expectedSnapshotDigest }) {
+  const { fence, staging, revoked } = paths(canonical, runId);
+  if (state(fence) || state(staging) || state(revoked)) throw new Error("retry-grant transaction already exists");
+  const beforeBytes = readFileSync(join(runDir, "run.json")), afterBytes = readFileSync(source);
+  const before = validateRun(JSON.parse(beforeBytes)), after = validateRun(JSON.parse(afterBytes));
+  if (snapshotDigest(canonical) !== expectedSnapshotDigest
+    || sha256(readFileSync(join(canonical, "run.json"))) !== sha256(beforeBytes)
+    || !isRetryGrantTransition(before, after, expectedSnapshotDigest)) {
+    throw new Error("retry-grant transaction does not bind the qualified snapshot and candidate");
+  }
+  const record = { version: VERSION, run_id: runId, before_sha256: sha256(beforeBytes), after_sha256: sha256(afterBytes),
+    snapshot_digest: expectedSnapshotDigest, snapshot_run_sha256: sha256(beforeBytes),
+    before_state_sha256: sha256(Buffer.from(JSON.stringify(before))), before_run: before };
+  let fd, published = false;
+  try {
+    fd = openSync(staging, "wx", 0o600);
+    writeFileSync(fd, `${JSON.stringify(record, null, 2)}\n`);
+    fsyncSync(fd); closeSync(fd); fd = undefined;
+    renameSync(staging, fence); published = true;
+    syncDir(dirname(canonical));
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+    if (!published) rmSync(staging, { force: true });
+  }
+}
+
+export function reconcileRetryGrantTransaction({ canonical, runDir, runId }) {
+  const { fence, staging, revoked } = paths(canonical, runId);
+  const fenceState = state(fence), stagingState = state(staging); const revokedState = state(revoked);
+  if (fenceState && stagingState) throw new Error("retry-grant transaction has duplicate fences");
+  if (!fenceState && stagingState && revokedState) throw new Error("retry-grant transaction has impossible staging and revocation artifacts");
+  if (!fenceState) {
+    if (stagingState) {
+      reconcileStagingTransaction({ canonical, runDir, runId, staging, stagingState });
+      return "rolled-back";
+    }
+    // X is non-authoritative cleanup after J was removed; an interrupted recursive removal is resumable.
+    if (revokedState) rmSync(revoked, { recursive: true, force: true });
+    return "none";
+  }
+  if (!fenceState.isFile() || fenceState.isSymbolicLink()) throw new Error("retry-grant transaction fence has an unsafe type");
+  let record;
+  try { record = JSON.parse(readFileSync(fence, "utf8")); } catch { throw new Error("retry-grant transaction fence is malformed"); }
+  validateRecord(record, runId);
+  const runPath = join(runDir, "run.json"); let runState = state(runPath);
+  if (!runState) {
+    const candidates = readdirSync(runDir).filter((name) => UUID_TEMP.test(name) && !state(join(canonical, name)));
+    if (candidates.length !== 1 || sha256(readCandidate(runDir, candidates[0])) !== record.after_sha256) {
+      throw new Error("retry-grant transaction has no recoverable live run manifest");
+    }
+    renameSync(join(runDir, candidates[0]), runPath); syncDir(runDir); runState = state(runPath);
+  }
+  if (!runState?.isFile() || runState.isSymbolicLink()) throw new Error("retry-grant transaction has no safe live run manifest");
+  const liveBytes = readFileSync(runPath), liveDigest = sha256(liveBytes);
+  if (liveDigest === record.before_sha256) {
+    if (revokedState || !qualifiedSnapshot(canonical, record)) throw new Error("pre-commit retry-grant transaction has lost its qualified snapshot");
+    removeAbandonedCandidate(runDir, canonical, record.after_sha256);
+    const livePlaneDigest = sha256(Buffer.from(inventoryEntries(runDir, new Set(["factory.lock", "run-json.lock"])).join("\n")));
+    if (livePlaneDigest !== record.snapshot_digest) throw new Error("pre-commit retry-grant live plane changed from its qualified snapshot");
+    unlinkSync(fence); syncDir(dirname(canonical));
+    return "rolled-back";
+  }
+  if (liveDigest !== record.after_sha256) throw new Error("retry-grant transaction does not bind the live run manifest");
+  const after = validateRun(JSON.parse(liveBytes));
+  if (!isRetryGrantTransition(record.before_run, after, record.snapshot_digest)) throw new Error("retry-grant transaction candidate is not an authorized grant");
+  syncDir(runDir);
+  const canonicalState = state(canonical);
+  if (canonicalState && revokedState) throw new Error("retry-grant transaction has ambiguous snapshot copies");
+  if (!canonicalState && !revokedState) throw new Error("retry-grant transaction has lost its fenced snapshot");
+  if (canonicalState) {
+    if (!qualifiedSnapshot(canonical, record)) throw new Error("retry-grant transaction canonical snapshot changed");
+    renameSync(canonical, revoked); syncDir(dirname(canonical));
+  } else if (revokedState && !qualifiedSnapshot(revoked, record)) {
+    throw new Error("retry-grant transaction revoked snapshot changed");
+  }
+  // C is now unreachable as recovery authority. Remove J before best-effort quarantine cleanup so a
+  // process death during recursive removal cannot wedge an otherwise committed grant.
+  unlinkSync(fence); syncDir(dirname(canonical));
+  if (state(revoked)) rmSync(revoked, { recursive: true, force: true });
+  return "committed";
+}
+
+export function isRetryGrantTransition(before, after, expectedSnapshotDigest) {
+  const audit = after.retry_extensions.at(-1), scope = audit?.scope;
+  if (!["slice", "all"].includes(scope) || audit.snapshot_digest !== expectedSnapshotDigest) return false;
+  const mode = scope === "all" ? "grant-retry-all" : "grant-retry-slice";
+  try {
+    for (const contract of FAMILY_CONTRACTS) {
+      const prior = contract.project(before), next = contract.project(after);
+      contract.validateProjection(prior); contract.validateProjection(next);
+      contract.validateTransition({ mode: ["envelope", "slices"].includes(contract.id) ? mode : undefined,
+        before: prior, after: next, current: before, candidate: after });
+    }
+    return true;
+  } catch { return false; }
+}
+
+function reconcileStagingTransaction({ canonical, runDir, runId, staging, stagingState }) {
+  if (!stagingState.isFile() || stagingState.isSymbolicLink()) {
+    throw new Error("retry-grant transaction staging fence has an unsafe type");
+  }
+  let record; try { record = JSON.parse(readFileSync(staging, "utf8")); validateRecord(record, runId); }
+  catch { record = null; }
+  const canonicalState = state(canonical), liveBytes = readFileSync(join(runDir, "run.json"));
+  if (!canonicalState?.isDirectory() || canonicalState.isSymbolicLink()
+    || !readFileSync(join(canonical, "run.json")).equals(liveBytes)) {
+    throw new Error("retry-grant staging transaction has lost its pre-commit snapshot");
+  }
+  const before = validateRun(JSON.parse(liveBytes)), digest = snapshotDigest(canonical);
+  const candidates = readdirSync(runDir).filter((name) => UUID_TEMP.test(name) && !state(join(canonical, name)));
+  if (candidates.length > 1 || (!record && candidates.length === 0)) {
+    throw new Error("retry-grant transaction staging fence is malformed or ambiguous");
+  }
+  if (record && (record.before_sha256 !== sha256(liveBytes) || !qualifiedSnapshot(canonical, record))) {
+    throw new Error("retry-grant staging transaction record does not bind its pre-commit snapshot");
+  }
+  if (candidates.length === 1) {
+    const candidateBytes = readCandidate(runDir, candidates[0]);
+    let after; try { after = validateRun(JSON.parse(candidateBytes)); } catch { after = null; }
+    if (!after || (record && sha256(candidateBytes) !== record.after_sha256)
+      || !isRetryGrantTransition(before, after, digest)) {
+      throw new Error("retry-grant staging transaction has an unbound atomic candidate");
+    }
+  }
+  const skipped = new Set(["factory.lock", "run-json.lock", ...candidates]);
+  if (sha256(Buffer.from(inventoryEntries(runDir, skipped).join("\n"))) !== digest) {
+    throw new Error("retry-grant staging transaction live plane changed from its qualified snapshot");
+  }
+  if (candidates.length) unlinkSync(join(runDir, candidates[0]));
+  unlinkSync(staging); syncDir(dirname(canonical));
+}
+
+function qualifiedSnapshot(path, record) {
+  const value = state(path);
+  return Boolean(value?.isDirectory() && !value.isSymbolicLink()
+    && snapshotDigest(path) === record.snapshot_digest
+    && sha256(readFileSync(join(path, "run.json"))) === record.snapshot_run_sha256);
+}
+
+function removeAbandonedCandidate(runDir, canonical, afterDigest) {
+  const candidates = readdirSync(runDir).filter((name) => UUID_TEMP.test(name) && !state(join(canonical, name)));
+  if (!candidates.length) return;
+  if (candidates.length !== 1 || sha256(readCandidate(runDir, candidates[0])) !== afterDigest) {
+    throw new Error("retry-grant transaction has an ambiguous atomic candidate");
+  }
+  unlinkSync(join(runDir, candidates[0])); syncDir(runDir);
+}
+
+function readCandidate(runDir, name) {
+  const path = join(runDir, name), value = state(path);
+  if (!value?.isFile() || value.isSymbolicLink()) throw new Error("retry-grant atomic candidate has an unsafe type");
+  return readFileSync(path);
+}
+
+function validateRecord(record, runId) {
+  const keys = ["after_sha256", "before_run", "before_sha256", "before_state_sha256", "run_id", "snapshot_digest", "snapshot_run_sha256", "version"];
+  if (!record || typeof record !== "object" || Array.isArray(record) || Object.keys(record).sort().join() !== keys.join()
+    || record.version !== VERSION || record.run_id !== runId || record.before_run?.run_id !== runId
+    || record.before_sha256 !== record.snapshot_run_sha256
+    || ![record.after_sha256, record.before_sha256, record.before_state_sha256, record.snapshot_digest,
+      record.snapshot_run_sha256].every((value) => /^sha256:[0-9a-f]{64}$/u.test(value))) {
+    throw new Error("retry-grant transaction fence is invalid");
+  }
+  validateRun(record.before_run);
+  if (sha256(Buffer.from(JSON.stringify(record.before_run))) !== record.before_state_sha256) {
+    throw new Error("retry-grant transaction before state is not bound to its fence");
+  }
+}
+
+function syncDir(path) {
+  let fd; try { fd = openSync(path, "r"); fsyncSync(fd); }
+  catch (error) { if (!["EINVAL", "EPERM", "EISDIR", "EACCES", "ENOTSUP"].includes(error?.code)) throw error; }
+  finally { if (fd !== undefined) closeSync(fd); }
+}

package/state/session-lock.js

@@ -7,7 +7,7 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { writeProtectedJsonAtomic } from "../core/atomic-write.js";
 import { rm } from "node:fs/promises";
-import { withRunJsonLock } from "../core/run-lock.js";
+import { RUN_JSON_LOCK_DIR, withRunJsonLock } from "../core/run-lock.js";
 
 export const SESSION_LOCK_FILE = "factory.lock";
 export const DEFAULT_SESSION_TTL_MS = 30 * 60 * 1000;
@@ -65,7 +65,7 @@ export async function claimSessionLock(runDir, { session, runId, branch, now, tt
       claimed_at: observed.owner?.session === session ? observed.owner.claimed_at : at,
       heartbeat_at: at,
     };
-    await writeProtectedJsonAtomic(runDir, SESSION_LOCK_FILE, owner);
+    await writeProtectedJsonAtomic(runDir, SESSION_LOCK_FILE, owner, { tempDirectory: RUN_JSON_LOCK_DIR });
     return { ...owner, stolen_from: observed.state === "stale" || force ? observed.owner : null };
   });
 }
@@ -77,7 +77,7 @@ export async function refreshSessionLock(runDir, { session, now } = {}) {
     // Refreshing someone else's lock would silently extend a run you do not own.
     if (session && owner.session !== session) throw new SessionLockHeldError(owner);
     const next = { ...owner, heartbeat_at: new Date(now ?? Date.now()).toISOString() };
-    await writeProtectedJsonAtomic(runDir, SESSION_LOCK_FILE, next);
+    await writeProtectedJsonAtomic(runDir, SESSION_LOCK_FILE, next, { tempDirectory: RUN_JSON_LOCK_DIR });
     return next;
   });
 }

package/state/transition.js

@@ -10,7 +10,7 @@ import { validateRun } from "./schema.js";
 import { coordinateRunJsonTransition } from "../core/write-core.js";
 import { FAMILY_CONTRACTS } from "../core/contracts.js";
 
-export async function transition(runDir, { participants, apply, reobservers, hooks, finalGuard } = {}) {
+export async function transition(runDir, { participants, apply, reobservers, hooks, finalGuard, commitFailureGuard, afterCommit } = {}) {
   const descriptor = Object.freeze({
     participants: Object.freeze((participants ?? []).map((entry) => Object.freeze({ ...entry }))),
     apply,
@@ -22,5 +22,7 @@ export async function transition(runDir, { participants, apply, reobservers, hoo
     reobservers: reobservers ?? new Map(),
     atomicWriteHooks: hooks,
     finalGuard,
+    commitFailureGuard,
+    afterCommit,
   });
 }