feature-factory 0.10.1 → 0.10.3

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/agents/backend-builder.md

@@ -106,7 +106,9 @@ Use exactly these field names and exactly this `status` vocabulary. The orchestr
 block to `factory observe --claim`, which compares each field against what it observes itself and
 records every disagreement as a review finding. `completed` is the word the evidence uses; any
 other spelling reads as a disagreement about status and blocks your own slice. `files_changed`
-must list every path, and `tests.exit` must be the real exit code — a claimed zero against an
+must list every path changed since the slice's `base_ref`, not since your last attempt — on a retry
+the observer diffs the whole slice, because that is what merges, and a list of only this attempt's
+edits is a disagreement. `tests.exit` must be the real exit code — a claimed zero against an
 observed failure is the single most important disagreement this mechanism catches.
 
 If the brief is wrong or impossible as written (e.g. the entity doesn't support it), stop, set `status: blocked` with the reason in `blockers`, and report the conflict — do not silently improvise a different design.

package/agents/frontend-builder.md

@@ -114,7 +114,9 @@ Use exactly these field names and exactly this `status` vocabulary. The orchestr
 block to `factory observe --claim`, which compares each field against what it observes itself and
 records every disagreement as a review finding. `completed` is the word the evidence uses; any
 other spelling reads as a disagreement about status and blocks your own slice. `files_changed`
-must list every path, and `tests.exit` must be the real exit code — a claimed zero against an
+must list every path changed since the slice's `base_ref`, not since your last attempt — on a retry
+the observer diffs the whole slice, because that is what merges, and a list of only this attempt's
+edits is a disagreement. `tests.exit` must be the real exit code — a claimed zero against an
 observed failure is the single most important disagreement this mechanism catches.
 
 If the design brief and the brief conflict, or a token/component the design needs doesn't exist, stop, set `status: blocked` with the reason in `blockers`, and report — don't hardcode around it.

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/index.js

@@ -123,10 +123,16 @@ export function runTests(worktree, command, { runner = spawnSync, skipReason = n
   return { cmd: shellCommand ? command : command.join(" "), exit, observed: exit !== null, skipped_reason: null };
 }
 
-// Readiness requires completed, clean, changed, observed-diff evidence and tests
-// observed passing or ratified as explicitly skipped with a reason.
+// Readiness requires completed, clean, changed, observed-diff evidence, no disagreement between
+// the builder's claim and the observation, and tests observed passing or ratified as explicitly
+// skipped with a reason.
 export function deriveReviewReady(evidence) {
   if (evidence.status !== "completed") return false;
+  // Enforcement (false green): a claim that disagrees with observation is itself the finding. It
+  // lives here, not beside the writer, because `readEvidence` recomputes readiness from this
+  // function alone; with the term only at write time, every mismatched record read back as
+  // tampered and wedged its slice where `slice blocked` could never record it.
+  if (evidence.claim_reconciliation?.mismatches?.length > 0) return false;
   // A tree with uncommitted changes cannot produce evidence about the commit it
   // claims, whatever the tests said.
   if (evidence.worktree_clean !== true) return false;
@@ -250,11 +256,8 @@ export function buildEvidence({ subject, runId, attempt, branch, baseRef, worktr
     review_ready: false,
     claim_reconciliation: { claimed: false, mismatches: [] },
   };
-  evidence.review_ready = deriveReviewReady(evidence);
   evidence.claim_reconciliation = reconcileClaim(claim, evidence);
-  // A claim that disagrees with what we observed cannot be review-ready: the
-  // disagreement is itself the finding.
-  if (evidence.claim_reconciliation.mismatches.length > 0) evidence.review_ready = false;
+  evidence.review_ready = deriveReviewReady(evidence);
   return evidence;
 }
 

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.3",
   "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,
   });
 }