specrails-desktop 2.29.1 → 2.29.3

package/server/dist/rail-isolated-launch.js

@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PrContinuationIsolationError = void 0;
 exports.launchIsolatedRail = launchIsolatedRail;
 exports.reconcileRailWorktrees = reconcileRailWorktrees;
 /**
@@ -41,9 +42,10 @@ exports.reconcileRailWorktrees = reconcileRailWorktrees;
  * ledger) into a running parallel rail. Gated OFF by default (rail-isolation's
  * opt-in flag), so this path is inert unless explicitly enabled.
  *
- * Flow: allocate one worktree+branch per ticket → fan out the loop runs IN those
- * worktrees (so concurrent AI CLIs never collide) → when ALL runs settle, run the
- * sequential validated merge-back on the base repo, then clean up worktrees.
+ * Flow: allocate one worktree+branch per independent delivery → fan out the loop
+ * runs IN those worktrees (so concurrent AI CLIs never collide) → when ALL runs
+ * settle, run the sequential validated merge-back on the base repo, then clean
+ * up worktrees. Tickets continuing one PR are grouped into its single checkout.
  *
  * The run spawns with cwd = the worktree (and repoDir = the worktree, so
  * writes/git land there). Because `git worktree add` materializes only TRACKED
@@ -59,6 +61,7 @@ exports.reconcileRailWorktrees = reconcileRailWorktrees;
  * via the executors' base env (see workspace-resolution.resolveLoopBaseEnv).
  */
 const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
 const artifact_registry_1 = require("./artifact-registry");
 const ids_1 = require("./ids");
 const loop_constants_1 = require("./loop-constants");
@@ -82,7 +85,19 @@ const file_story_1 = require("./file-story");
 const providers_1 = require("./providers");
 const pr_publisher_1 = require("./pr-publisher");
 const active_pr_continuation_1 = require("./active-pr-continuation");
+const pr_lifecycle_1 = require("./pr-lifecycle");
 const rail_worktree_release_1 = require("./rail-worktree-release");
+const rail_pr_recovery_git_1 = require("./rail-pr-recovery-git");
+/** A PR follow-up may only run on the verified PR branch in a dedicated
+ * worktree. Routers must surface this error instead of degrading to shared cwd. */
+class PrContinuationIsolationError extends Error {
+    code = 'pr_continuation_isolation_required';
+    constructor(message) {
+        super(message);
+        this.name = 'PrContinuationIsolationError';
+    }
+}
+exports.PrContinuationIsolationError = PrContinuationIsolationError;
 /**
  * Ticket data for the conventional branch name (pr-naming): title/labels from
  * the ticket-spec reader, the Jira key resolved with the authoritative
@@ -125,11 +140,140 @@ function commitFailureSummary(result) {
     const dirty = result.dirty.length > 0 ? `; dirty=${result.dirty.slice(0, 8).join(', ')}` : '';
     return `${result.error ?? 'worktree still has uncommitted deliverable changes'}${dirty}`;
 }
+const COMMIT_SHA_RE = /^[0-9a-f]{40,64}$/i;
+async function recoveryCommitObjectExists(git, repoDir, sha) {
+    if (!COMMIT_SHA_RE.test(sha))
+        return false;
+    try {
+        return (await git.run(['cat-file', '-e', `${sha}^{commit}`], repoDir)).code === 0;
+    }
+    catch {
+        return false;
+    }
+}
+async function isFastForwardRecoveryCommit(git, repoDir, baselineSha, candidateSha) {
+    if (!COMMIT_SHA_RE.test(baselineSha) || !COMMIT_SHA_RE.test(candidateSha))
+        return false;
+    if (baselineSha.toLowerCase() === candidateSha.toLowerCase())
+        return true;
+    try {
+        return (await git.run(['merge-base', '--is-ancestor', baselineSha, candidateSha], repoDir)).code === 0;
+    }
+    catch {
+        return false;
+    }
+}
+async function releaseDeliveredRecoveryLineage(db, git, repoDir, delivery, deliveredSha) {
+    const currentProtection = await (0, rail_pr_recovery_git_1.inspectRecoveryCommitProtection)(git, repoDir, delivery.id);
+    if (currentProtection.kind === 'present' &&
+        currentProtection.sha.toLowerCase() === deliveredSha.toLowerCase()) {
+        await (0, rail_pr_recovery_git_1.releaseRecoveryCommit)(git, repoDir, delivery.id, deliveredSha);
+    }
+    const visited = new Set([delivery.id]);
+    let predecessorId = delivery.supersedes_delivery_id;
+    for (let depth = 0; predecessorId && depth < 32 && !visited.has(predecessorId); depth++) {
+        visited.add(predecessorId);
+        const predecessor = (0, rail_pr_store_1.getPrDelivery)(db, predecessorId);
+        if (!predecessor)
+            break;
+        if (predecessor.decision !== 'discarded' && predecessor.decision !== 'superseded')
+            break;
+        const protection = await (0, rail_pr_recovery_git_1.inspectRecoveryCommitProtection)(git, repoDir, predecessor.id);
+        if (protection.kind === 'present' && await isFastForwardRecoveryCommit(git, repoDir, protection.sha, deliveredSha)) {
+            await (0, rail_pr_recovery_git_1.releaseRecoveryCommit)(git, repoDir, predecessor.id, protection.sha);
+        }
+        predecessorId = predecessor.supersedes_delivery_id;
+    }
+}
+/** Prove that the linked checkout is on the expected PR branch and that its
+ * HEAD is exactly the commit named by refs/heads/<branch>. When expectedHeadSha
+ * is supplied (allocation and pre-push phases), also freeze the checkout to
+ * that immutable object. Post-run verification deliberately omits the old
+ * baseline because a successful implementation is expected to create a new
+ * commit. The handle's branch string alone is insufficient: createWorktree may
+ * reuse a stale mounted path. */
+async function verifyContinuationWorktree(git, repoDir, handle, target, expectedHeadSha) {
+    if (handle.branch !== target.branch) {
+        throw new PrContinuationIsolationError(`PR branch ${target.branch} resolved to mounted branch ${handle.branch}; free the stale worktree and retry`);
+    }
+    const checkedOut = await git.run(['rev-parse', '--abbrev-ref', 'HEAD'], handle.worktreePath);
+    const actualBranch = checkedOut.code === 0 ? checkedOut.stdout.trim() : '';
+    if (actualBranch !== target.branch) {
+        throw new PrContinuationIsolationError(`worktree ${handle.worktreePath} is on ${actualBranch || 'an unverifiable ref'}, expected PR branch ${target.branch}; fix the checkout and retry`);
+    }
+    const [head, branchRef] = await Promise.all([
+        git.run(['rev-parse', '--verify', 'HEAD'], handle.worktreePath),
+        git.run(['rev-parse', '--verify', `refs/heads/${target.branch}`], repoDir),
+    ]);
+    const headSha = head.code === 0 ? head.stdout.trim() : '';
+    const branchSha = branchRef.code === 0 ? branchRef.stdout.trim() : '';
+    if (!COMMIT_SHA_RE.test(headSha) || headSha !== branchSha) {
+        throw new PrContinuationIsolationError(`worktree HEAD does not match refs/heads/${target.branch}; reconcile the PR branch and retry`);
+    }
+    if (expectedHeadSha !== undefined && (!expectedHeadSha || headSha.toLowerCase() !== expectedHeadSha.toLowerCase())) {
+        throw new PrContinuationIsolationError(`local PR branch ${target.branch} is not at the verified continuation commit; preserve or reconcile the local commits before retrying`);
+    }
+    return headSha;
+}
+async function readHeadSha(git, cwd) {
+    try {
+        const result = await git.run(['rev-parse', '--verify', 'HEAD'], cwd);
+        const sha = result.code === 0 ? result.stdout.trim() : '';
+        return COMMIT_SHA_RE.test(sha) ? sha : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function branchHasDelta(git, cwd, baseRef) {
+    try {
+        const result = await git.run(['diff', '--quiet', `${baseRef}...HEAD`, '--'], cwd);
+        if (result.code === 0)
+            return false;
+        if (result.code === 1)
+            return true;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function errorDetail(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function aggregateImplementationOutcome(results) {
+    const succeeded = results.filter((result) => result.implementationOutcome === 'succeeded').length;
+    if (succeeded === results.length && results.length > 0)
+        return 'succeeded';
+    if (succeeded > 0)
+        return 'partially_succeeded';
+    return results.length > 0 ? 'failed' : 'unknown';
+}
+function branchRecords(results) {
+    return results.flatMap((result) => result.run.ticketIds.map((ticketId) => ({
+        ticketId,
+        branch: result.run.handle.branch,
+        // Legacy consumers interpret this as delivery eligibility, not engine truth.
+        succeeded: result.deliveryOutcome === 'ready',
+        runId: result.run.runId,
+        implementationOutcome: result.implementationOutcome,
+        deliveryOutcome: result.deliveryOutcome,
+        initialSha: result.initialSha,
+        finalSha: result.finalSha,
+        ...(result.changed === undefined ? {} : { changed: result.changed }),
+        failureCode: result.failureCode ?? null,
+        branchOwnership: result.run.branchOwnership,
+        worktreePath: result.run.handle.worktreePath,
+        overlayExcludes: result.run.overlayExcludes,
+        overlayCleanupEvidence: result.run.overlayCleanupEvidence,
+    })));
+}
 /**
  * Launch the rail's tickets in isolated worktrees + schedule the merge-back.
- * Returns the loop run ids. Throws if worktree allocation fails (the caller then
- * falls back to the shared-cwd path) — but only after tearing down any partial
- * allocation, so a failure never leaves orphaned worktrees.
+ * Returns the loop run ids. Throws if worktree allocation fails, but only after
+ * tearing down owned partial allocation. A fresh launch may degrade to shared
+ * cwd in the router; a PR continuation raises PrContinuationIsolationError and
+ * must fail closed because shared cwd cannot prove which branch receives work.
  */
 async function launchIsolatedRail(input, io = {}) {
     const { ctx, railIndex, ticketIds, loopId, loopName, loopGraph, provider, model, effort } = input;
@@ -151,23 +295,21 @@ async function launchIsolatedRail(input, io = {}) {
     // every await and late-joining clients hydrate mid-build via GET /rails —
     // and re-broadcast the durable rail.pr_state snapshot on every mutation.
     let prDeliveryId = null;
-    const broadcastPrState = () => {
-        if (!prDeliveryId)
-            return;
-        const row = (0, rail_pr_store_1.getPrDelivery)(ctx.db, prDeliveryId);
-        if (row)
-            ctx.broadcast((0, rail_pr_store_1.toRailPrStateMessage)(ctx.project.id, (0, rail_pr_store_1.toPrDeliverySnapshot)(row)));
-    };
+    let supersededDelivery = null;
     // Origin-conversation card sync: when the launch came from an agent-chat
     // conversation, mirror the row's state into its inline decision card —
     // 'post' at launch (the user sees "working in an isolated worktree" from
     // second zero), 'update' on every later transition (settle, alloc-failure).
     // Null-safe: registry empty in tests / disabled builds; update falls back to
     // post when no card exists yet.
-    const syncOriginCard = (verb) => {
-        if (!prDeliveryId)
+    const broadcastDeliveryState = (deliveryId) => {
+        const row = (0, rail_pr_store_1.getPrDelivery)(ctx.db, deliveryId);
+        if (!row)
             return;
-        const row = (0, rail_pr_store_1.getPrDelivery)(ctx.db, prDeliveryId);
+        ctx.broadcast((0, rail_pr_store_1.toRailPrStateMessage)(ctx.project.id, (0, rail_pr_store_1.toPrDeliverySnapshot)(row)));
+    };
+    const syncDeliveryCard = (deliveryId, verb) => {
+        const row = (0, rail_pr_store_1.getPrDelivery)(ctx.db, deliveryId);
         if (!row?.origin_conversation_id)
             return;
         const mgr = (0, agent_chat_registry_1.getAgentChatManager)();
@@ -179,11 +321,47 @@ async function launchIsolatedRail(input, io = {}) {
         else
             mgr.updatePrDecisionCard(row.origin_conversation_id, envelope);
     };
+    const emitPrDeliveryState = (deliveryId, verb) => {
+        broadcastDeliveryState(deliveryId);
+        syncDeliveryCard(deliveryId, verb);
+    };
+    const broadcastPrState = () => {
+        if (prDeliveryId)
+            broadcastDeliveryState(prDeliveryId);
+    };
+    const syncOriginCard = (verb) => {
+        if (prDeliveryId)
+            syncDeliveryCard(prDeliveryId, verb);
+    };
+    const closeFailedGeneration = (err) => {
+        if (!prDeliveryId || (0, rail_pr_store_1.getPrDelivery)(ctx.db, prDeliveryId)?.decision !== 'building')
+            return;
+        const closed = supersededDelivery
+            ? (0, rail_pr_store_1.failPrDeliveryAndRestoreSuperseded)(ctx.db, prDeliveryId, supersededDelivery)
+            : (0, rail_pr_store_1.transitionDecision)(ctx.db, prDeliveryId, 'building', 'discarded', {
+                implementationOutcome: 'unknown',
+                deliveryOutcome: 'blocked',
+                statusCode: 'delivery_failed',
+                statusDetail: errorDetail(err),
+            });
+        if (!closed)
+            return;
+        try {
+            emitPrDeliveryState(prDeliveryId, 'update');
+        }
+        catch { /* durable row is authoritative */ }
+        if (supersededDelivery) {
+            try {
+                emitPrDeliveryState(supersededDelivery.id, 'update');
+            }
+            catch { /* durable row is authoritative */ }
+        }
+    };
     // Units of isolation: `all` → ONE unit covering every ticket (one worktree, one
     // run — the batch pipeline handles the tickets internally); `per-ticket` → one
     // unit per ticket. The branch/ledger key is the unit's primary (first) ticket.
     const scope = input.scope ?? 'per-ticket';
-    const units = scope === 'all'
+    let units = scope === 'all'
         ? [{ ticketId: ticketIds[0], ticketIds: [...ticketIds] }]
         : ticketIds.map((id) => ({ ticketId: id, ticketIds: [id] }));
     // Effective artifact root for the per-worktree overlay: a RELOCATED project's
@@ -231,187 +409,319 @@ async function launchIsolatedRail(input, io = {}) {
     let integration;
     let launchContinuation = null;
     const allocated = [];
-    await (0, repo_lock_1.withRepoLock)(baseRepo, async () => {
-        // Bring the repo's remote-tracking refs up to date BEFORE resolving the
-        // integration branch or allocating any worktree — otherwise `git worktree
-        // add -b <branch> <path> <bare-name>` resolves against whatever (possibly
-        // stale) commit the user's LOCAL branch happens to be at. `fetchOrigin` only
-        // ever touches `refs/remotes/origin/*`; it never mutates the checked-out
-        // branch/working tree. De-duped per repo for a short TTL so a "Launch all"
-        // batch (N independent launch requests for the same repo, serialized by
-        // this same withRepoLock) performs one real fetch, not one per rail. A
-        // failed fetch (no network / no remote / auth error) never blocks the
-        // launch — resolveWorktreeBaseRef below degrades to the local ref.
-        const fetchResult = await (0, integration_branch_1.fetchOrigin)(git, baseRepo);
-        // Resolve the project's designated integration branch ONCE, and branch every
-        // ticket's worktree off it (not the ambient HEAD). Empty setting → auto-resolve
-        // (repo default → HEAD fallback). See server/integration-branch.ts.
-        integration = await (0, integration_branch_1.resolveIntegrationBranch)(git, {
-            repoDir: baseRepo,
-            projectSetting: (0, db_1.getProjectSettings)(ctx.db).integrationBranch,
-        });
-        // Prefer the freshly-fetched remote-tracking ref (origin/<branch>) over the
-        // bare local name for repo-default/project-setting sources — see
-        // resolveWorktreeBaseRef for the exact fallback policy. `explicit` is left
-        // completely untouched (rare, launch-time-chosen override).
-        const worktreeBaseRef = await (0, integration_branch_1.resolveWorktreeBaseRef)(git, {
-            repoDir: baseRepo, integration, fetchOk: fetchResult.ok,
-        });
-        if (worktreeBaseRef.warning) {
-            console.warn(`[rail-isolated] ${worktreeBaseRef.warning} (repo ${baseRepo})`);
-            try {
-                ctx.broadcast({ type: 'rail.fetch_degraded', projectId: ctx.project.id, railIndex, warning: worktreeBaseRef.warning });
-            }
-            catch { /* non-fatal, mirrors notifyOverlayDegraded's broadcast guard below */ }
-        }
-        // Active-PR continuation: if a ticket is already parked on_review with a
-        // matching OPEN GitHub PR (or a Jira-linked in_progress ticket explicitly
-        // matches an open PR, covering unmapped Jira "Review" statuses), run the next
-        // pass directly on that PR's head branch. Fresh tickets stay on the normal
-        // integration-base path. Keep this deliberately single-target for now: one
-        // rail delivery row can represent one PR URL, so multi-PR batches continue to
-        // use the existing new-work flow instead of silently mixing PRs.
-        const continuationTargets = await (0, active_pr_continuation_1.resolveActivePrContinuationTargets)({
-            db: ctx.db,
-            git,
-            exec,
-            repoDir: baseRepo,
-            ticketIds: units.map((u) => u.ticketId),
-            integrationBranch: integration.branch,
-            fetchOk: fetchResult.ok,
-            getTicketSpec: (ticketId) => {
+    try {
+        await (0, repo_lock_1.withRepoLock)(baseRepo, async () => {
+            // Bring the repo's remote-tracking refs up to date BEFORE resolving the
+            // integration branch or allocating any worktree — otherwise `git worktree
+            // add -b <branch> <path> <bare-name>` resolves against whatever (possibly
+            // stale) commit the user's LOCAL branch happens to be at. `fetchOrigin` only
+            // ever touches `refs/remotes/origin/*`; it never mutates the checked-out
+            // branch/working tree. De-duped per repo for a short TTL so a "Launch all"
+            // batch (N independent launch requests for the same repo, serialized by
+            // this same withRepoLock) performs one real fetch, not one per rail. A
+            // failed fetch (no network / no remote / auth error) never blocks the
+            // launch — resolveWorktreeBaseRef below degrades to the local ref.
+            const fetchResult = await (0, integration_branch_1.fetchOrigin)(git, baseRepo);
+            // Resolve the project's designated integration branch ONCE, and branch every
+            // ticket's worktree off it (not the ambient HEAD). Empty setting → auto-resolve
+            // (repo default → HEAD fallback). See server/integration-branch.ts.
+            integration = await (0, integration_branch_1.resolveIntegrationBranch)(git, {
+                repoDir: baseRepo,
+                projectSetting: (0, db_1.getProjectSettings)(ctx.db).integrationBranch,
+            });
+            // Prefer the freshly-fetched remote-tracking ref (origin/<branch>) over the
+            // bare local name for repo-default/project-setting sources — see
+            // resolveWorktreeBaseRef for the exact fallback policy. `explicit` is left
+            // completely untouched (rare, launch-time-chosen override).
+            const worktreeBaseRef = await (0, integration_branch_1.resolveWorktreeBaseRef)(git, {
+                repoDir: baseRepo, integration, fetchOk: fetchResult.ok,
+            });
+            if (worktreeBaseRef.warning) {
+                console.warn(`[rail-isolated] ${worktreeBaseRef.warning} (repo ${baseRepo})`);
                 try {
-                    return ctx.getTicketSpec(ticketId);
-                }
-                catch {
-                    return undefined;
+                    ctx.broadcast({ type: 'rail.fetch_degraded', projectId: ctx.project.id, railIndex, warning: worktreeBaseRef.warning });
                 }
-            },
-        });
-        const uniqueContinuationKeys = new Set(units
-            .map((u) => continuationTargets.get(u.ticketId))
-            .filter((t) => !!t)
-            .map((t) => `${t.prUrl ?? ''}\n${t.branch}`));
-        if (uniqueContinuationKeys.size === 1 && units.every((u) => continuationTargets.has(u.ticketId))) {
-            launchContinuation = continuationTargets.get(units[0].ticketId) ?? null;
-        }
-        if (prMode) {
-            prDeliveryId = (0, rail_pr_store_1.createPrDelivery)(ctx.db, {
-                railIndex,
-                loopId,
-                railKey: `${railIndex}-${loopId}`,
-                ticketIds: [...ticketIds],
-                baseBranch: launchContinuation?.baseBranch ?? integration.branch,
-                loopName,
-                originSurface: input.originSurface ?? 'dashboard',
-                originConversationId: input.originConversationId ?? null,
-            }).id;
-            input.onPrDeliveryCreated?.(prDeliveryId);
-            if (launchContinuation) {
-                (0, rail_pr_store_1.transitionDecision)(ctx.db, prDeliveryId, 'building', 'building', {
-                    branch: launchContinuation.branch,
-                    prUrl: launchContinuation.prUrl,
-                    prNumber: launchContinuation.prNumber,
-                    prState: 'pr-created',
-                });
+                catch { /* non-fatal, mirrors notifyOverlayDegraded's broadcast guard below */ }
             }
-            broadcastPrState();
-            syncOriginCard('post');
-        }
-        // Conventional branch naming (pr-naming): `<type>/<ref>-<kebab-title>`, the
-        // Jira key prevailing over the local id when linked. Collisions with foreign
-        // branches suffix `-2`… (bounded); a branch a PRIOR rail run allocated for
-        // the SAME ticket is ours to resume, so it is NOT treated as a collision.
-        // The integration branch is never used; exhaustion falls back to the legacy
-        // `sr/<slug>/ticket-<id>` name. Snapshot under the lock so concurrent
-        // launches see each other's just-created branches.
-        const takenBranches = await (0, worktree_manager_1.listLocalBranches)(git, baseRepo);
-        const unitBranchName = (ticketId) => {
-            const continuation = launchContinuation && continuationTargets.get(ticketId);
-            if (continuation) {
-                takenBranches.add(continuation.branch);
-                return continuation.branch;
-            }
-            const preferred = (0, pr_naming_1.ticketBranchName)(unitNamingInput(ctx, ticketId));
-            const branch = (0, pr_naming_1.resolveCollisionFreeName)(preferred, {
-                taken: (name) => takenBranches.has(name) && !(0, rail_worktrees_store_1.railWorktreeBranchExistsForTicket)(ctx.db, ticketId, name),
-                reserved: [integration.branch],
-            }) ?? (0, worktree_manager_1.worktreeBranch)(slug, ticketId);
-            takenBranches.add(branch);
-            return branch;
-        };
-        try {
-            for (const unit of units) {
-                const continuationTarget = launchContinuation ? continuationTargets.get(unit.ticketId) ?? null : null;
-                const handle = await create(git, {
+            // Active-PR continuation: if a ticket is already parked on_review with a
+            // matching OPEN GitHub PR (or a Jira-linked in_progress ticket explicitly
+            // matches an open PR, covering unmapped Jira "Review" statuses), run the next
+            // pass directly on that PR's head branch. Fresh tickets stay on the normal
+            // integration-base path. Keep this deliberately single-target for now: one
+            // rail delivery row can represent one PR URL, so multi-PR batches continue to
+            // use the existing new-work flow instead of silently mixing PRs.
+            const continuationTargets = prMode
+                ? await (0, active_pr_continuation_1.resolveActivePrContinuationTargets)({
+                    db: ctx.db,
+                    git,
+                    exec,
                     repoDir: baseRepo,
-                    worktreesRoot,
-                    slug,
-                    ticketId: unit.ticketId,
-                    baseRef: continuationTarget?.baseRef ?? worktreeBaseRef.baseRef,
-                    branch: unitBranchName(unit.ticketId),
-                    refreshFromBaseRef: Boolean(continuationTarget?.baseRef),
-                });
-                // Per-run overlay: merge-link the framework surface the checkout didn't
-                // bring into the worktree (idempotent; resume-safe via its manifest).
-                let overlayExcludes = [];
-                try {
-                    const res = overlay({
-                        worktreePath: handle.worktreePath,
-                        sourceRoot: overlaySourceRoot,
-                        providerDir: overlayProviderDir,
-                        instructionsFilename: overlayInstructions,
+                    // Continuation authority is scoped to the launch's exact durable ticket
+                    // set. In scope=all there is only one isolation unit, but its primary
+                    // ticket must never stand in for the full batch during PR discovery.
+                    ticketIds: [...ticketIds],
+                    integrationBranch: integration.branch,
+                    fetchOk: fetchResult.ok,
+                    getTicketSpec: (ticketId) => {
+                        try {
+                            return ctx.getTicketSpec(ticketId);
+                        }
+                        catch {
+                            return undefined;
+                        }
+                    },
+                })
+                : new Map();
+            const uniqueContinuationKeys = new Set(ticketIds
+                .map((ticketId) => continuationTargets.get(ticketId))
+                .filter((t) => !!t)
+                .map((t) => `${t.prUrl ?? ''}\n${t.branch}`));
+            if (uniqueContinuationKeys.size === 1 && ticketIds.every((ticketId) => continuationTargets.has(ticketId))) {
+                launchContinuation = continuationTargets.get(ticketIds[0]) ?? null;
+            }
+            if (input.requiredPrContinuation && (!launchContinuation ||
+                launchContinuation.branch !== input.requiredPrContinuation.branch ||
+                launchContinuation.baseBranch !== input.requiredPrContinuation.baseBranch ||
+                launchContinuation.prUrl !== input.requiredPrContinuation.prUrl ||
+                launchContinuation.prNumber !== input.requiredPrContinuation.prNumber ||
+                launchContinuation.deliverySha !== input.requiredPrContinuation.deliverySha)) {
+                const observed = await (0, pr_lifecycle_1.observePrLifecycle)(exec, baseRepo, input.requiredPrContinuation.prUrl, input.requiredPrContinuation.deliverySha);
+                const reason = observed.ok
+                    ? (0, pr_lifecycle_1.matchesRecordedPrIdentity)(observed, input.requiredPrContinuation.branch, input.requiredPrContinuation.baseBranch) && observed.state === 'OPEN' && observed.includesExpectedSha !== true
+                        ? 'the open PR head no longer exposes the previously verified delivery commit; use Retry push'
+                        : observed.state === 'CLOSED' || observed.state === 'MERGED'
+                            ? `the attached PR is ${observed.state.toLowerCase()}; use Verify PR to reconcile it before relaunching`
+                            : `the PR no longer matches its recorded head/base (${observed.state})`
+                    : `GitHub lifecycle could not be confirmed (${observed.detail})`;
+                throw new PrContinuationIsolationError(`cannot safely continue PR branch ${input.requiredPrContinuation.branch}: ${reason}`);
+            }
+            // A git branch can only be checked out by one worktree. When several rail
+            // tickets all continue the same PR, make them one atomic batch run in one
+            // checkout instead of attempting N worktrees for the same branch (the second
+            // `git worktree add` necessarily fails). `ticketIds` preserves the full rail
+            // scope for {{spec.ids}} / ticket commands and completion bookkeeping.
+            if (launchContinuation && units.length > 1) {
+                units = [{
+                        ticketId: units[0].ticketId,
+                        ticketIds: units.flatMap((unit) => unit.ticketIds),
+                    }];
+            }
+            if (prMode) {
+                const generation = (0, rail_pr_store_1.createPrDeliveryGeneration)(ctx.db, {
+                    railIndex,
+                    loopId,
+                    railKey: `${railIndex}-${loopId}`,
+                    ticketIds: [...ticketIds],
+                    baseBranch: launchContinuation?.baseBranch ?? integration.branch,
+                    loopName,
+                    originSurface: input.originSurface ?? 'dashboard',
+                    originConversationId: input.originConversationId ?? null,
+                    isContinuation: Boolean(launchContinuation),
+                    supersedesDeliveryId: launchContinuation?.source === 'rail-pr-delivery'
+                        ? launchContinuation.deliveryId
+                        : null,
+                }, input.requiredPrContinuation
+                    ? { id: input.requiredPrContinuation.deliveryId, decision: input.requiredPrContinuation.decision }
+                    : null);
+                prDeliveryId = generation.delivery.id;
+                supersededDelivery = generation.superseded;
+                input.onPrDeliveryCreated?.(prDeliveryId);
+                if (launchContinuation) {
+                    (0, rail_pr_store_1.transitionDecision)(ctx.db, prDeliveryId, 'building', 'building', {
+                        branch: launchContinuation.branch,
+                        prUrl: launchContinuation.prUrl,
+                        prNumber: launchContinuation.prNumber,
+                        prState: 'pr-created',
+                        // Persist the frozen OPEN head at generation creation, not only after
+                        // settlement. If allocation/process recovery fails, this terminal
+                        // continuation can still prove and resume the same borrowed PR instead
+                        // of shadowing its predecessor with an evidence-less row.
+                        deliverySha: launchContinuation.deliverySha,
+                        isContinuation: true,
+                        supersedesDeliveryId: supersededDelivery?.id ?? launchContinuation.deliveryId,
                     });
-                    overlayExcludes = res.createdPaths;
-                    if (res.warnings.length > 0)
-                        notifyOverlayDegraded(unit.ticketId, res.warnings);
-                }
-                catch (err) {
-                    // applyWorktreeOverlay never throws; this guards injected test doubles
-                    // and future edits — the spawn proceeds regardless.
-                    notifyOverlayDegraded(unit.ticketId, [err instanceof Error ? err.message : String(err)]);
-                }
-                // Code-Explorer provenance: freeze the worktree's pre-run state (HEAD sha
-                // + the overlay's untracked set) so the settle diff attributes exactly
-                // the run's own writes. Best-effort — a snapshot failure only loses
-                // provenance, never the run.
-                let provenanceSnapshot = null;
-                if ((0, feature_flags_1.isCodeExplorerEnabled)()) {
+                }
+                if (supersededDelivery) {
                     try {
-                        provenanceSnapshot = (io.snapshot ?? file_provenance_1.snapshotWorkingTree)(handle.worktreePath);
+                        emitPrDeliveryState(supersededDelivery.id, 'update');
+                    }
+                    catch { /* durable supersession is authoritative */ }
+                }
+                try {
+                    broadcastPrState();
+                }
+                catch { /* hydration can recover */ }
+                try {
+                    syncOriginCard('post');
+                }
+                catch { /* hydration can recover */ }
+            }
+            // Conventional branch naming (pr-naming): `<type>/<ref>-<kebab-title>`, the
+            // Jira key prevailing over the local id when linked. Collisions with foreign
+            // branches suffix `-2`… (bounded); a branch a PRIOR rail run allocated for
+            // the SAME ticket is ours to resume, so it is NOT treated as a collision.
+            // The integration branch is never used; exhaustion falls back to the legacy
+            // `sr/<slug>/ticket-<id>` name. Snapshot under the lock so concurrent
+            // launches see each other's just-created branches.
+            const takenBranches = await (0, worktree_manager_1.listLocalBranches)(git, baseRepo);
+            const preexistingBranches = new Set(takenBranches);
+            const unitBranchName = (ticketId) => {
+                const continuation = launchContinuation && continuationTargets.get(ticketId);
+                if (continuation) {
+                    takenBranches.add(continuation.branch);
+                    return { branch: continuation.branch, ownership: 'borrowed-pr' };
+                }
+                const preferred = (0, pr_naming_1.ticketBranchName)(unitNamingInput(ctx, ticketId));
+                const branch = (0, pr_naming_1.resolveCollisionFreeName)(preferred, {
+                    taken: (name) => takenBranches.has(name) && !(0, rail_worktrees_store_1.railWorktreeBranchExistsForTicket)(ctx.db, ticketId, name),
+                    reserved: [integration.branch],
+                }) ?? (0, worktree_manager_1.worktreeBranch)(slug, ticketId);
+                takenBranches.add(branch);
+                return { branch, ownership: preexistingBranches.has(branch) ? 'preexisting' : 'created' };
+            };
+            try {
+                for (const unit of units) {
+                    const continuationTarget = launchContinuation ? continuationTargets.get(unit.ticketId) ?? null : null;
+                    const branchPlan = unitBranchName(unit.ticketId);
+                    let handle = null;
+                    let branchOwnership = branchPlan.ownership;
+                    let worktreeOwnership = 'created';
+                    let initialSha = null;
+                    try {
+                        handle = await create(git, {
+                            repoDir: baseRepo,
+                            worktreesRoot,
+                            slug,
+                            ticketId: unit.ticketId,
+                            baseRef: continuationTarget?.baseRef ?? worktreeBaseRef.baseRef,
+                            branch: branchPlan.branch,
+                            refreshFromBaseRef: Boolean(continuationTarget?.baseRef),
+                        });
+                        worktreeOwnership = handle.worktreeCreated === false ? 'preexisting' : 'created';
+                        if (!continuationTarget && (handle.branch !== branchPlan.branch || handle.branchCreated === false)) {
+                            branchOwnership = 'preexisting';
+                        }
+                        if (continuationTarget) {
+                            initialSha = await verifyContinuationWorktree(git, baseRepo, handle, continuationTarget, continuationTarget.deliverySha);
+                        }
+                        else {
+                            initialSha = await readHeadSha(git, handle.worktreePath);
+                        }
+                        // Per-run overlay: merge-link the framework surface the checkout didn't
+                        // bring into the worktree (idempotent; resume-safe via its manifest).
+                        let overlayExcludes = [];
+                        let overlayCleanupEvidence = [];
+                        try {
+                            const res = overlay({
+                                worktreePath: handle.worktreePath,
+                                sourceRoot: overlaySourceRoot,
+                                providerDir: overlayProviderDir,
+                                instructionsFilename: overlayInstructions,
+                            });
+                            overlayExcludes = res.createdPaths;
+                            overlayCleanupEvidence = res.cleanupEvidence ?? [];
+                            if (res.warnings.length > 0)
+                                notifyOverlayDegraded(unit.ticketId, res.warnings);
+                        }
+                        catch (err) {
+                            // applyWorktreeOverlay never throws; this guards injected test doubles
+                            // and future edits — the spawn proceeds regardless.
+                            notifyOverlayDegraded(unit.ticketId, [err instanceof Error ? err.message : String(err)]);
+                        }
+                        // Code-Explorer provenance: freeze the worktree's pre-run state (HEAD sha
+                        // + the overlay's untracked set) so the settle diff attributes exactly
+                        // the run's own writes. Best-effort — a snapshot failure only loses
+                        // provenance, never the run.
+                        let provenanceSnapshot = null;
+                        if ((0, feature_flags_1.isCodeExplorerEnabled)()) {
+                            try {
+                                provenanceSnapshot = (io.snapshot ?? file_provenance_1.snapshotWorkingTree)(handle.worktreePath);
+                            }
+                            catch (err) {
+                                console.warn(`[rail-isolated] provenance snapshot failed: ${err.message}`);
+                            }
+                        }
+                        const runId = (0, ids_1.newId)();
+                        const ledgerId = (0, ids_1.newId)();
+                        (0, rail_worktrees_store_1.createRailWorktree)(ctx.db, {
+                            id: ledgerId, railIndex, ticketId: unit.ticketId, runId,
+                            branch: handle.branch, worktreePath: handle.worktreePath,
+                        });
+                        allocated.push({
+                            ticketId: unit.ticketId,
+                            ticketIds: unit.ticketIds,
+                            runId,
+                            ledgerId,
+                            handle,
+                            overlayExcludes,
+                            overlayCleanupEvidence,
+                            provenanceSnapshot,
+                            continuationTarget,
+                            baseRef: continuationTarget?.baseRef ?? worktreeBaseRef.baseRef,
+                            initialSha,
+                            branchOwnership,
+                            worktreeOwnership,
+                        });
                     }
                     catch (err) {
-                        console.warn(`[rail-isolated] provenance snapshot failed: ${err.message}`);
+                        // A handle that never reached `allocated` is still our responsibility,
+                        // but only unmount/delete resources this call actually created.
+                        if (handle && worktreeOwnership === 'created') {
+                            await remove(git, {
+                                repoDir: baseRepo,
+                                worktreePath: handle.worktreePath,
+                                branch: handle.branch,
+                                deleteBranch: branchOwnership === 'created',
+                            }).catch(() => { });
+                        }
+                        throw err;
                     }
                 }
-                const runId = (0, ids_1.newId)();
-                const ledgerId = (0, ids_1.newId)();
-                (0, rail_worktrees_store_1.createRailWorktree)(ctx.db, {
-                    id: ledgerId, railIndex, ticketId: unit.ticketId, runId,
-                    branch: handle.branch, worktreePath: handle.worktreePath,
-                });
-                allocated.push({ ticketId: unit.ticketId, ticketIds: unit.ticketIds, runId, ledgerId, handle, overlayExcludes, provenanceSnapshot, continuationTarget });
             }
-        }
-        catch (err) {
-            for (const a of allocated) {
-                await remove(git, { repoDir: baseRepo, worktreePath: a.handle.worktreePath, branch: a.handle.branch }).catch(() => { });
-            }
-            // Close the just-inserted decision row (kept as 'discarded' for audit, never
-            // deleted) so a wedged 'building' row can never block relaunching the slot.
-            // Router-driven PR continuations may intentionally fall back to shared-cwd
-            // on the same PR branch; in that case the router preserves and updates the
-            // row as the live iteration card instead of showing a false discard.
-            if (!input.preservePrDeliveryOnAllocationFailure && prDeliveryId && (0, rail_pr_store_1.transitionDecision)(ctx.db, prDeliveryId, 'building', 'discarded')) {
-                broadcastPrState();
-                syncOriginCard('update');
+            catch (err) {
+                for (const a of allocated) {
+                    if (a.worktreeOwnership === 'created') {
+                        await remove(git, {
+                            repoDir: baseRepo,
+                            worktreePath: a.handle.worktreePath,
+                            branch: a.handle.branch,
+                            deleteBranch: a.branchOwnership === 'created',
+                        }).catch(() => { });
+                    }
+                    (0, rail_worktrees_store_1.updateRailWorktreeState)(ctx.db, a.ledgerId, 'failed');
+                }
+                // Close the failed generation. A continuation atomically restores the exact
+                // predecessor it superseded; a stale concurrent generation wins instead of
+                // letting this catch overwrite it.
+                closeFailedGeneration(err);
+                if (launchContinuation) {
+                    if (err instanceof PrContinuationIsolationError)
+                        throw err;
+                    const detail = err instanceof Error ? err.message : String(err);
+                    throw new PrContinuationIsolationError(`cannot allocate a verified worktree for PR branch ${launchContinuation.branch}: ${detail}; free the branch checkout and retry`);
+                }
+                throw err;
             }
-            throw err;
+        }); // withRepoLock — allocation done; the fan-out below runs in parallel.
+    }
+    catch (err) {
+        closeFailedGeneration(err);
+        // Auto-detected GitHub continuations do not have a router-side delivery
+        // contract yet. Preserve the fail-closed signal for errors that happen
+        // after detection but before the allocation catch (for example DB setup).
+        // TypeScript does not observe assignments performed inside withRepoLock's
+        // async callback, so retain the explicit runtime type at this boundary.
+        const detectedContinuation = launchContinuation;
+        if (detectedContinuation && !(err instanceof PrContinuationIsolationError)) {
+            const detail = err instanceof Error ? err.message : String(err);
+            throw new PrContinuationIsolationError(`cannot prepare a verified worktree for PR branch ${detectedContinuation.branch}: ${detail}`);
         }
-    }); // withRepoLock — allocation done; the fan-out below runs in parallel.
-    // 2. Fan out: one loop run per ticket, spawning IN its worktree. In PR mode a
-    //    COMPLETED run's tickets park at on_review (the user decides done vs
-    //    discard via the PR flow); failure outcomes ignore the field.
+        throw err;
+    }
+    // 2. Fan out: one loop run per independent worktree. Same-PR tickets form one
+    //    atomic batch run because git cannot mount one branch in multiple linked
+    //    worktrees. In PR mode a COMPLETED run's tickets park at on_review (the
+    //    user decides done vs discard via the PR flow); failures ignore the field.
     const runFinishedOpts = { ticketCompletionStatus: prMode ? 'on_review' : 'done' };
     // Code-Explorer provenance at settle: diff the worktree against its pre-run
     // snapshot and record file_provenance/story rows (keyed by runId), exactly
@@ -427,58 +737,210 @@ async function launchIsolatedRail(input, io = {}) {
         if (provenanceRecorded.has(a.runId))
             return;
         provenanceRecorded.add(a.runId);
-        recordProvenance({
-            db: ctx.db,
-            projectId: ctx.project.id,
-            runId: a.runId,
-            ticketId: a.ticketId,
-            repoDir: a.handle.worktreePath,
-            snapshot: a.provenanceSnapshot,
-            broadcast: (msg) => ctx.broadcast(msg),
-        });
+        try {
+            recordProvenance({
+                db: ctx.db,
+                projectId: ctx.project.id,
+                runId: a.runId,
+                ticketId: a.ticketId,
+                repoDir: a.handle.worktreePath,
+                snapshot: a.provenanceSnapshot,
+                broadcast: (msg) => ctx.broadcast(msg),
+            });
+        }
+        catch (err) {
+            console.warn(`[rail-isolated] provenance recording failed for ${a.runId}: ${errorDetail(err)}`);
+        }
+    };
+    const markWorktree = (a, state) => {
+        try {
+            return (0, rail_worktrees_store_1.updateRailWorktreeState)(ctx.db, a.ledgerId, state)
+                ? null
+                : `worktree ledger ${a.ledgerId} no longer exists`;
+        }
+        catch (err) {
+            return errorDetail(err);
+        }
+    };
+    /** This function resolves for every allocated unit. Engine truth is captured
+     * before any delivery effect and is the only value sent to the deferred
+     * terminal callback. Delivery failures become blocked evidence instead. */
+    const settleAllocatedRun = async (a, enginePromise) => {
+        let actualOutcome = 'failed';
+        let engineFailure;
+        try {
+            const result = await enginePromise;
+            actualOutcome = result.outcome;
+        }
+        catch (err) {
+            engineFailure = errorDetail(err);
+            console.error(`[rail-isolated] loop run ${a.runId} rejected: ${engineFailure}`);
+        }
+        const implementationOutcome = actualOutcome === 'success' ? 'succeeded' : 'failed';
+        recordRunProvenance(a);
+        let callbackFailure;
+        try {
+            ctx.onLoopRunFinished(a.runId, actualOutcome, runFinishedOpts);
+        }
+        catch (err) {
+            callbackFailure = errorDetail(err);
+            console.error(`[rail-isolated] terminal callback failed for ${a.runId}: ${callbackFailure}`);
+        }
+        // The engine may have edited a copied overlay file. Re-authenticate only
+        // automatic-cleanup authority. Allocation-time paths remain conservative
+        // NEVER-COMMIT exclusions, while a modified copy is preserved in the
+        // worktree instead of being silently staged or deleted.
+        if (a.overlayCleanupEvidence.length > 0) {
+            a.overlayCleanupEvidence = (0, worktree_overlay_1.revalidateOverlayCleanupEvidence)({
+                worktreePath: a.handle.worktreePath,
+                sourceRoot: overlaySourceRoot,
+                providerDir: overlayProviderDir,
+                instructionsFilename: overlayInstructions,
+            }, a.overlayCleanupEvidence);
+        }
+        let commit;
+        try {
+            commit = await (0, worktree_manager_1.commitWorktreeAndVerify)(git, a.handle.worktreePath, worktreeCommitMessage(ctx, a.ticketId, a.runId, implementationOutcome === 'failed'), a.overlayExcludes);
+        }
+        catch (err) {
+            commit = { staged: false, committed: false, clean: false, dirty: [], error: errorDetail(err) };
+        }
+        if (!commit.clean) {
+            const detail = commitFailureSummary(commit);
+            console.error(`[rail-isolated] run ${a.runId} left an unsafe worktree: ${detail}`);
+            markWorktree(a, 'needs-review');
+            return {
+                run: a,
+                implementationOutcome,
+                deliveryOutcome: 'blocked',
+                initialSha: a.initialSha,
+                finalSha: await readHeadSha(git, a.handle.worktreePath),
+                failureCode: 'commit_failed',
+                failureDetail: detail,
+                safeToRelease: false,
+            };
+        }
+        let finalSha = null;
+        let verificationFailure;
+        if (a.continuationTarget) {
+            try {
+                finalSha = await verifyContinuationWorktree(git, baseRepo, a.handle, a.continuationTarget);
+            }
+            catch (err) {
+                verificationFailure = errorDetail(err);
+            }
+        }
+        else {
+            finalSha = await readHeadSha(git, a.handle.worktreePath);
+        }
+        const changed = commit.committed || Boolean(a.initialSha && finalSha && a.initialSha !== finalSha);
+        // A successful commit without a provable object is not retryable or safe to
+        // detach. A continuation additionally requires HEAD == refs/heads/<branch>.
+        if (verificationFailure || !finalSha || (!commit.committed && a.branchOwnership === 'created' && !a.initialSha)) {
+            const detail = verificationFailure
+                ?? (!finalSha
+                    ? 'the final HEAD object could not be verified'
+                    : 'the initial HEAD object was not captured, so a no-change result cannot be proven');
+            console.error(`[rail-isolated] run ${a.runId} finished on an unverified ref: ${detail}`);
+            markWorktree(a, 'needs-review');
+            return {
+                run: a,
+                implementationOutcome,
+                deliveryOutcome: 'blocked',
+                initialSha: a.initialSha,
+                finalSha,
+                changed,
+                failureCode: 'branch_verification_failed',
+                failureDetail: detail,
+                safeToRelease: false,
+            };
+        }
+        // Failed clean units remain `building` until aggregate cleanup removes the
+        // mount and atomically terminalizes the ledger as failed. Marking them
+        // terminal first would make idempotent cleanup skip a still-mounted path.
+        const ledgerFailure = implementationOutcome === 'succeeded'
+            ? (markWorktree(a, 'built') ?? undefined)
+            : undefined;
+        const settlementFailure = callbackFailure ?? ledgerFailure;
+        if (settlementFailure) {
+            markWorktree(a, 'needs-review');
+            return {
+                run: a,
+                implementationOutcome,
+                deliveryOutcome: 'blocked',
+                initialSha: a.initialSha,
+                finalSha,
+                changed,
+                failureCode: 'settlement_interrupted',
+                failureDetail: settlementFailure,
+                safeToRelease: false,
+            };
+        }
+        if (implementationOutcome === 'failed') {
+            return {
+                run: a,
+                implementationOutcome,
+                deliveryOutcome: 'not_started',
+                initialSha: a.initialSha,
+                finalSha,
+                changed,
+                ...(engineFailure ? { failureDetail: engineFailure } : {}),
+                safeToRelease: true,
+            };
+        }
+        // A resumed non-PR branch may already contain reviewable commits from an
+        // earlier attempt, even when this iteration itself did not add one.
+        let resumedBranchDelta = null;
+        if (!changed && a.continuationTarget === null && a.branchOwnership === 'preexisting') {
+            resumedBranchDelta = await branchHasDelta(git, a.handle.worktreePath, a.baseRef);
+            if (resumedBranchDelta === null) {
+                const detail = `cannot prove whether resumed branch ${a.handle.branch} has commits ahead of ${a.baseRef}`;
+                markWorktree(a, 'needs-review');
+                return {
+                    run: a,
+                    implementationOutcome,
+                    deliveryOutcome: 'blocked',
+                    initialSha: a.initialSha,
+                    finalSha,
+                    changed,
+                    failureCode: 'branch_verification_failed',
+                    failureDetail: detail,
+                    safeToRelease: false,
+                };
+            }
+        }
+        const noChanges = !changed && Boolean(a.initialSha && finalSha && a.initialSha === finalSha && (a.continuationTarget !== null ||
+            a.branchOwnership === 'created' ||
+            resumedBranchDelta === false));
+        return {
+            run: a,
+            implementationOutcome,
+            deliveryOutcome: noChanges ? 'no_changes' : 'ready',
+            initialSha: a.initialSha,
+            finalSha,
+            changed,
+            safeToRelease: true,
+        };
     };
     const runPromises = [];
     for (const a of allocated) {
-        ctx.railLoopRuns.set(a.runId, { railIndex, ticketIds: a.ticketIds });
+        ctx.railLoopRuns.set(a.runId, {
+            railIndex,
+            ticketIds: a.ticketIds,
+            requiresTerminalIntent: true,
+        });
         const spec = ctx.getTicketSpec(a.ticketId);
-        const p = ctx.loopRunManager
-            .run({
+        const enginePromise = ctx.loopRunManager.run({
             runId: a.runId, loopId, loopName, graph: loopGraph, projectId: ctx.project.id,
             cwd: a.handle.worktreePath, repoDir: a.handle.worktreePath,
             isolation: { branch: a.handle.branch, worktreePath: a.handle.worktreePath },
             railIndex, ticketId: a.ticketId,
             spec: spec ? { ...spec, ticketIds: a.ticketIds } : { ticketIds: a.ticketIds },
+            ticketCompletionStatus: runFinishedOpts.ticketCompletionStatus,
+            deferTerminalOutcome: true,
             constants, provider, model, effort,
-        })
-            .then(async (r) => {
-            const succeeded = r.outcome === 'success';
-            recordRunProvenance(a);
-            // Commit the run's work to its branch so PR creation/merge-back can
-            // trust the branch as the durable source of truth. A "successful" loop
-            // with deliverable local changes still dirty is treated as failed
-            // instead of surfacing a Create PR card that cannot ship the work.
-            const commit = await (0, worktree_manager_1.commitWorktreeAndVerify)(git, a.handle.worktreePath, worktreeCommitMessage(ctx, a.ticketId, a.runId), a.overlayExcludes);
-            const deliverable = succeeded && commit.clean;
-            if (succeeded && !commit.clean) {
-                console.error(`[rail-isolated] run ${a.runId} finished success but commit verification failed: ${commitFailureSummary(commit)}`);
-            }
-            ctx.onLoopRunFinished(r.runId, deliverable ? 'success' : 'failed', runFinishedOpts);
-            (0, rail_worktrees_store_1.updateRailWorktreeState)(ctx.db, a.ledgerId, deliverable ? 'built' : 'failed');
-            return { run: a, succeeded: deliverable };
-        })
-            .catch(async (err) => {
-            console.error('[rail-isolated] loop run failed:', err);
-            ctx.onLoopRunFinished(a.runId, 'failed', runFinishedOpts);
-            recordRunProvenance(a);
-            // Commit partial work too → durable in git → resumable on re-launch.
-            const commit = await (0, worktree_manager_1.commitWorktreeAndVerify)(git, a.handle.worktreePath, worktreeCommitMessage(ctx, a.ticketId, a.runId, true), a.overlayExcludes);
-            if (!commit.clean) {
-                console.error(`[rail-isolated] failed run ${a.runId} left uncommitted deliverable changes: ${commitFailureSummary(commit)}`);
-            }
-            (0, rail_worktrees_store_1.updateRailWorktreeState)(ctx.db, a.ledgerId, 'failed');
-            return { run: a, succeeded: false };
         });
-        runPromises.push(p);
+        runPromises.push(settleAllocatedRun(a, enginePromise));
         try {
             ctx.jiraSyncManager.onRailLaunch(a.ticketIds, a.runId);
         }
@@ -500,11 +962,28 @@ async function launchIsolatedRail(input, io = {}) {
     //       work isolated on its branches and mark the decision row on_review —
     //       the draft PR is only created when the user clicks [Create PR] on the
     //       pr-decision endpoint (ask-first, safe-pr-review-flow).
-    void Promise.allSettled(runPromises).then(async (settled) => {
-        const results = settled.flatMap((s) => (s.status === 'fulfilled' ? [s.value] : []));
-        const branches = results.map((r) => ({
-            ticketId: r.run.ticketId, branch: r.run.handle.branch, succeeded: r.succeeded,
-        }));
+    const guardedRunPromises = runPromises.map((promise, index) => promise.catch(async (err) => {
+        const run = allocated[index];
+        const detail = errorDetail(err);
+        console.error(`[rail-isolated] unexpected settlement rejection for ${run.runId}: ${detail}`);
+        const durable = ctx.db.prepare('SELECT final_outcome FROM loop_runs WHERE id = ?').get(run.runId);
+        const implementationOutcome = durable?.final_outcome === 'success' ? 'succeeded' : 'failed';
+        markWorktree(run, 'needs-review');
+        return {
+            run,
+            implementationOutcome,
+            deliveryOutcome: 'blocked',
+            initialSha: run.initialSha,
+            finalSha: await readHeadSha(git, run.handle.worktreePath),
+            failureCode: 'settlement_interrupted',
+            failureDetail: detail,
+            safeToRelease: false,
+        };
+    }));
+    void Promise.all(guardedRunPromises).then(async (settledResults) => {
+        // Cardinality is invariant: one structured result per allocated unit. The
+        // guarded promises above synthesize a blocked record for any rejection.
+        let results = settledResults;
         if (prMode) {
             // Build-settle: persist the per-unit branch outcomes + this launch's
             // worktree ledger ids on the row (the deferred create-pr / discard actions
@@ -513,71 +992,334 @@ async function launchIsolatedRail(input, io = {}) {
             // keep the implementation card visible as a failed job state with run-log
             // chips instead of silently auto-discarding or leaving it at "building".
             const worktreeIds = allocated.map((a) => a.ledgerId);
-            const anySucceeded = results.some((r) => r.succeeded);
-            const settledContinuation = anySucceeded ? launchContinuation : null;
+            let deliverySha = null;
             let continuationPushFailed = false;
             let continuationPushFailureReason = null;
-            if (settledContinuation) {
-                const pushed = await (0, pr_publisher_1.pushBranch)(exec, {
-                    repoDir: baseRepo,
-                    branch: settledContinuation.branch,
-                    baseBranch: settledContinuation.baseBranch,
-                });
-                if (pushed.state === 'local-only') {
+            let continuationNeedsNewPr = false;
+            let continuationExactPushCompleted = false;
+            let continuationRemoteIsDraft = launchContinuation?.isDraft ?? null;
+            let continuationMergedWithSha = false;
+            let continuationClosedWithSha = false;
+            let continuationLifecycleBlocked = false;
+            const unchangedContinuation = launchContinuation
+                ? results.find((result) => result.run.continuationTarget && result.deliveryOutcome === 'no_changes')
+                : undefined;
+            if (unchangedContinuation?.finalSha)
+                deliverySha = unchangedContinuation.finalSha;
+            // Revalidate immediately before an existing-PR push. Settlement's SHA is
+            // immutable delivery evidence; a moved ref blocks instead of substituting
+            // a newer object behind the user's back.
+            if (launchContinuation) {
+                const candidateIndex = results.findIndex((result) => result.deliveryOutcome === 'ready' && result.run.continuationTarget !== null);
+                if (candidateIndex >= 0) {
+                    const candidate = results[candidateIndex];
+                    try {
+                        const verified = await verifyContinuationWorktree(git, baseRepo, candidate.run.handle, candidate.run.continuationTarget, candidate.finalSha);
+                        if (!candidate.finalSha || verified !== candidate.finalSha) {
+                            throw new PrContinuationIsolationError('PR branch moved after settlement; refusing to push an unverified object');
+                        }
+                        deliverySha = candidate.finalSha;
+                    }
+                    catch (err) {
+                        const detail = errorDetail(err);
+                        markWorktree(candidate.run, 'needs-review');
+                        results = results.map((result, resultIndex) => resultIndex === candidateIndex
+                            ? {
+                                ...result,
+                                deliveryOutcome: 'blocked',
+                                failureCode: 'branch_verification_failed',
+                                failureDetail: detail,
+                                safeToRelease: false,
+                            }
+                            : result);
+                    }
+                }
+            }
+            const implementationOutcome = aggregateImplementationOutcome(results);
+            let ready = results.filter((result) => result.deliveryOutcome === 'ready');
+            let blocked = results.filter((result) => result.deliveryOutcome === 'blocked');
+            let noChanges = results.filter((result) => result.deliveryOutcome === 'no_changes');
+            const continuationHadReadyWork = ready.length > 0;
+            if (launchContinuation && deliverySha && (continuationHadReadyWork || noChanges.length > 0)) {
+                const beforePush = await (0, pr_lifecycle_1.observePrLifecycle)(exec, baseRepo, launchContinuation.prUrl, deliverySha);
+                if (!beforePush.ok) {
                     continuationPushFailed = true;
-                    continuationPushFailureReason = pushed.reason;
-                    console.warn(`[rail-isolated] existing PR follow-up push failed for ${settledContinuation.branch}: ${continuationPushFailureReason}`);
-                }
-            }
-            const next = anySucceeded
-                ? (settledContinuation
-                    ? (continuationPushFailed
-                        ? 'pr_failed'
-                        : (settledContinuation.isDraft === false ? 'pr_ready' : 'pr_draft'))
-                    : 'on_review')
-                : 'implementation_failed';
-            const patch = settledContinuation
-                ? {
-                    branches,
-                    worktreeIds,
-                    branch: settledContinuation.branch,
-                    prUrl: settledContinuation.prUrl,
-                    prNumber: settledContinuation.prNumber,
-                    prState: continuationPushFailed ? 'local-only' : 'pr-created',
-                }
-                : { branches, worktreeIds };
+                    continuationPushFailureReason = `could not confirm the existing PR is open before push: ${beforePush.detail}`;
+                }
+                else if (!(0, pr_lifecycle_1.isExactOpenPr)(beforePush, launchContinuation.branch, launchContinuation.baseBranch)) {
+                    const identityMatches = (0, pr_lifecycle_1.matchesRecordedPrIdentity)(beforePush, launchContinuation.branch, launchContinuation.baseBranch);
+                    if (beforePush.state === 'MERGED' && identityMatches && beforePush.includesExpectedSha === true) {
+                        // Another actor delivered the exact object before our push. Keep the
+                        // old PR attached so poll-merge can apply the terminal ticket effect.
+                        continuationRemoteIsDraft = false;
+                        continuationMergedWithSha = true;
+                    }
+                    else if (beforePush.state === 'CLOSED' && identityMatches &&
+                        beforePush.includesExpectedSha === true && !continuationHadReadyWork) {
+                        // An unchanged iteration may safely offer Reopen when the closed PR
+                        // already contains its exact head. Changed work is never assumed to
+                        // belong to a closed PR before we push it.
+                        continuationClosedWithSha = true;
+                    }
+                    else {
+                        continuationNeedsNewPr = true;
+                        continuationPushFailureReason = beforePush.includesExpectedSha === null
+                            ? `the previous PR is ${beforePush.state.toLowerCase()} and GitHub could not prove it included this implementation; create a new draft PR from the preserved commit`
+                            : `the previous PR is ${beforePush.state.toLowerCase()} without this implementation; create a new draft PR from the preserved commit`;
+                    }
+                }
+                else if (!continuationHadReadyWork) {
+                    // No-change still needs lifecycle truth: the PR may have merged while
+                    // the run was active, and an advanced remote head must not be silently
+                    // dismissed as though it were the verified unchanged object.
+                    if (beforePush.headRefOid?.toLowerCase() !== deliverySha.toLowerCase()) {
+                        continuationLifecycleBlocked = true;
+                        continuationPushFailureReason = 'the open PR head no longer exposes the exact verified commit from this unchanged iteration';
+                    }
+                    else {
+                        continuationRemoteIsDraft = beforePush.isDraft;
+                    }
+                }
+                else {
+                    continuationRemoteIsDraft = beforePush.isDraft;
+                    const pushRemote = await (0, pr_lifecycle_1.verifyPushRemoteForPr)(exec, baseRepo, launchContinuation.prUrl);
+                    if (!pushRemote.ok) {
+                        continuationPushFailed = true;
+                        continuationPushFailureReason = `refusing to push the preserved implementation: ${pushRemote.detail}`;
+                    }
+                    else {
+                        try {
+                            const pushed = await (0, pr_publisher_1.pushBranch)(exec, {
+                                repoDir: baseRepo,
+                                branch: launchContinuation.branch,
+                                baseBranch: launchContinuation.baseBranch,
+                                remote: pushRemote.pushTarget,
+                                sourceSha: deliverySha,
+                            });
+                            if (pushed.state === 'local-only') {
+                                continuationPushFailed = true;
+                                continuationPushFailureReason = pushed.reason;
+                            }
+                            else {
+                                continuationExactPushCompleted = true;
+                                const afterPush = await (0, pr_lifecycle_1.observePrLifecycle)(exec, baseRepo, launchContinuation.prUrl, deliverySha);
+                                if (!afterPush.ok) {
+                                    continuationPushFailed = true;
+                                    continuationPushFailureReason = `exact commit was pushed, but the PR lifecycle could not be confirmed: ${afterPush.detail}`;
+                                }
+                                else if ((0, pr_lifecycle_1.isExactOpenPr)(afterPush, launchContinuation.branch, launchContinuation.baseBranch)) {
+                                    if (afterPush.headRefOid?.toLowerCase() === deliverySha.toLowerCase()) {
+                                        continuationRemoteIsDraft = afterPush.isDraft;
+                                    }
+                                    else {
+                                        // GitHub observation can lag a successful push, or another
+                                        // writer may have moved the remote head. The retry remains
+                                        // safe because it always uses the immutable SHA and a normal
+                                        // non-forced refspec; preserve evidence and keep Retry push.
+                                        continuationPushFailed = true;
+                                        continuationPushFailureReason = 'the exact push completed, but the PR does not yet expose the verified commit as its head; Retry push remains safe and uses the preserved SHA';
+                                    }
+                                }
+                                else if (afterPush.state === 'MERGED' &&
+                                    (0, pr_lifecycle_1.matchesRecordedPrIdentity)(afterPush, launchContinuation.branch, launchContinuation.baseBranch) &&
+                                    afterPush.includesExpectedSha === true) {
+                                    // The PR won the race but demonstrably included this exact SHA.
+                                    continuationRemoteIsDraft = false;
+                                    continuationMergedWithSha = true;
+                                }
+                                else if (afterPush.state === 'CLOSED' &&
+                                    (0, pr_lifecycle_1.matchesRecordedPrIdentity)(afterPush, launchContinuation.branch, launchContinuation.baseBranch) &&
+                                    afterPush.includesExpectedSha === true) {
+                                    continuationClosedWithSha = true;
+                                }
+                                else if (afterPush.state === 'MERGED' || afterPush.state === 'CLOSED') {
+                                    continuationNeedsNewPr = true;
+                                    continuationPushFailureReason = afterPush.includesExpectedSha === null
+                                        ? `the previous PR became ${afterPush.state.toLowerCase()} and GitHub could not prove it included this implementation; create a new draft PR from the preserved commit`
+                                        : `the previous PR became ${afterPush.state.toLowerCase()} without this implementation; create a new draft PR from the preserved commit`;
+                                }
+                                else {
+                                    continuationNeedsNewPr = true;
+                                    continuationPushFailureReason = 'the existing PR no longer matches its recorded head/base after the exact push; create a new draft PR from the preserved commit';
+                                }
+                            }
+                        }
+                        catch (err) {
+                            continuationPushFailed = true;
+                            continuationPushFailureReason = errorDetail(err);
+                        }
+                    }
+                }
+                if (continuationPushFailed) {
+                    console.warn(`[rail-isolated] existing PR follow-up push failed for ${launchContinuation.branch}: ${continuationPushFailureReason}`);
+                }
+            }
+            if (continuationNeedsNewPr && noChanges.length > 0) {
+                // The iteration itself made no new commit, but the old PR did not deliver
+                // its verified head. That head is therefore real work for a fresh PR.
+                const noChangeRuns = new Set(noChanges.map((result) => result.run.runId));
+                results = results.map((result) => noChangeRuns.has(result.run.runId)
+                    ? { ...result, deliveryOutcome: 'ready' }
+                    : result);
+            }
+            if (continuationLifecycleBlocked) {
+                const affectedRuns = new Set(results
+                    .filter((result) => result.run.continuationTarget !== null &&
+                    (result.deliveryOutcome === 'ready' || result.deliveryOutcome === 'no_changes'))
+                    .map((result) => result.run.runId));
+                for (const result of results) {
+                    if (affectedRuns.has(result.run.runId))
+                        markWorktree(result.run, 'needs-review');
+                }
+                results = results.map((result) => affectedRuns.has(result.run.runId)
+                    ? {
+                        ...result,
+                        deliveryOutcome: 'blocked',
+                        failureCode: 'branch_verification_failed',
+                        failureDetail: continuationPushFailureReason ?? 'PR lifecycle verification failed',
+                        safeToRelease: false,
+                    }
+                    : result);
+            }
+            ready = results.filter((result) => result.deliveryOutcome === 'ready');
+            blocked = results.filter((result) => result.deliveryOutcome === 'blocked');
+            noChanges = results.filter((result) => result.deliveryOutcome === 'no_changes');
+            let deliveryOutcome;
+            if (implementationOutcome === 'failed') {
+                deliveryOutcome = blocked.length > 0 ? 'blocked' : 'not_started';
+            }
+            else if (continuationLifecycleBlocked) {
+                deliveryOutcome = 'blocked';
+            }
+            else if (continuationMergedWithSha || continuationClosedWithSha) {
+                deliveryOutcome = 'delivered';
+            }
+            else if (launchContinuation && ready.length > 0) {
+                deliveryOutcome = continuationNeedsNewPr
+                    ? (implementationOutcome === 'partially_succeeded' ? 'partial' : 'ready')
+                    : continuationPushFailed ? 'retryable_failure' : 'delivered';
+            }
+            else if (ready.length > 0) {
+                deliveryOutcome = implementationOutcome === 'partially_succeeded' || blocked.length > 0 ? 'partial' : 'ready';
+            }
+            else if (noChanges.length === results.length && implementationOutcome === 'succeeded') {
+                deliveryOutcome = 'no_changes';
+            }
+            else if (implementationOutcome === 'partially_succeeded') {
+                deliveryOutcome = 'partial';
+            }
+            else {
+                deliveryOutcome = 'blocked';
+            }
+            const next = implementationOutcome === 'failed'
+                ? 'implementation_failed'
+                : continuationLifecycleBlocked
+                    ? 'pr_failed'
+                    : continuationMergedWithSha
+                        ? 'pr_ready'
+                        : continuationClosedWithSha
+                            ? 'pr_closed'
+                            : ready.length > 0
+                                ? (launchContinuation
+                                    ? (continuationNeedsNewPr
+                                        ? 'on_review'
+                                        : continuationPushFailed
+                                            ? 'pr_failed'
+                                            : (continuationRemoteIsDraft === false ? 'pr_ready' : 'pr_draft'))
+                                    : 'on_review')
+                                : deliveryOutcome === 'no_changes'
+                                    ? 'no_changes'
+                                    : 'pr_failed';
+            const firstFailure = results.find((result) => result.failureCode);
+            const statusCode = implementationOutcome === 'failed'
+                ? 'implementation_failed'
+                : continuationLifecycleBlocked
+                    ? 'branch_verification_failed'
+                    : continuationMergedWithSha
+                        ? 'pr_ready'
+                        : continuationClosedWithSha
+                            ? 'pr_closed'
+                            : continuationNeedsNewPr
+                                ? 'ready_for_review'
+                                : continuationPushFailed
+                                    ? 'push_failed'
+                                    : deliveryOutcome === 'no_changes'
+                                        ? 'no_changes'
+                                        : implementationOutcome === 'partially_succeeded'
+                                            ? 'partial_success'
+                                            : firstFailure?.failureCode
+                                                ?? (launchContinuation && ready.length > 0 ? 'existing_pr_updated' : 'ready_for_review');
+            const statusDetail = continuationPushFailureReason ?? firstFailure?.failureDetail ?? null;
+            // Only proven-clean, durably referenced results are automatically
+            // detached. Fresh reviewable worktrees stay mounted for the later PR
+            // decision; dirty/unknown/ref-mismatched work is never passed to --force.
+            const failedSafeIds = results
+                .filter((result) => result.implementationOutcome === 'failed' && result.safeToRelease)
+                .map((result) => result.run.ledgerId);
+            const completedSafeIds = results
+                .filter((result) => result.safeToRelease && (result.deliveryOutcome === 'no_changes' ||
+                (launchContinuation !== null && result.deliveryOutcome === 'ready')))
+                .map((result) => result.run.ledgerId);
+            const settledBranchRecords = branchRecords(results);
+            const expectedHeadByBranch = (0, rail_worktree_release_1.durableBranchHeads)(settledBranchRecords);
+            const overlayEvidenceByBranch = (0, rail_worktree_release_1.durableOverlayCleanupEvidence)(settledBranchRecords);
+            const patch = {
+                branches: settledBranchRecords,
+                worktreeIds,
+                implementationOutcome,
+                deliveryOutcome,
+                statusCode,
+                statusDetail,
+                deliverySha,
+                ...(launchContinuation ? {
+                    branch: launchContinuation.branch,
+                    prUrl: continuationNeedsNewPr ? null : launchContinuation.prUrl,
+                    prNumber: continuationNeedsNewPr ? null : launchContinuation.prNumber,
+                    // A stale CLOSED/MERGED PR is detached from this generation. The exact
+                    // object remains locally or on its recorded branch, ready for Create PR.
+                    prState: continuationNeedsNewPr
+                        ? (continuationExactPushCompleted ? 'pushed' : 'local-only')
+                        : 'pr-created',
+                    // Once detached, this generation owns the lifecycle of the new PR,
+                    // while per-unit branchOwnership still protects the borrowed branch.
+                    isContinuation: !continuationNeedsNewPr,
+                } : {}),
+            };
             if (prDeliveryId && (0, rail_pr_store_1.transitionDecision)(ctx.db, prDeliveryId, 'building', next, patch)) {
-                if (settledContinuation && !continuationPushFailed) {
-                    await (0, rail_worktree_release_1.releaseRailWorktrees)({ db: ctx.db, git, repoDir: baseRepo, worktreeIds });
+                // Persist truthful settlement before cleanup. A crash can leave a
+                // safely-recoverable mount, but can no longer lose no-change/partial/
+                // exact-SHA evidence and regress the card back to `building`.
+                const settledPrDeliveryId = prDeliveryId;
+                const onSafetyArchive = (archive) => {
+                    if (!(0, rail_pr_store_1.appendPrDeliverySafetyArchive)(ctx.db, settledPrDeliveryId, archive)) {
+                        throw new Error(`delivery ${settledPrDeliveryId} disappeared while recording safety archive ${archive}`);
+                    }
+                };
+                const cleanupWarnings = [
+                    ...await (0, rail_worktree_release_1.releaseRailWorktrees)({
+                        db: ctx.db, git, repoDir: baseRepo, worktreeIds: failedSafeIds,
+                        state: 'failed', remove, expectedHeadByBranch, overlayEvidenceByBranch, onSafetyArchive,
+                    }),
+                    ...await (0, rail_worktree_release_1.releaseRailWorktrees)({
+                        db: ctx.db, git, repoDir: baseRepo, worktreeIds: completedSafeIds,
+                        remove, expectedHeadByBranch, overlayEvidenceByBranch, onSafetyArchive,
+                    }),
+                ];
+                if (cleanupWarnings.length > 0) {
+                    (0, rail_pr_store_1.transitionDecision)(ctx.db, prDeliveryId, next, next, { cleanupWarnings });
                 }
                 broadcastPrState();
                 // Completion driver: refresh the origin conversation's card in place —
                 // on_review asks the question, discarded informs the outcome.
                 syncOriginCard('update');
             }
-            if (!anySucceeded) {
-                // FAILED-IMPLEMENTATION CLEANUP (0 succeeded): unmount every worktree NOW rather
-                // than leaving it for a restart's reconcile sweep — a still-mounted
-                // worktree POISONS the next run of the same ticket: the worktree path is
-                // keyed by ticketId, so the next allocation silently reuses this
-                // checkout and its stale branch. BRANCHES are kept: per-run settle
-                // committed partial work to them and a re-launch resumes a kept branch
-                // by name (createWorktree's resume path); user-discard remains the one
-                // explicit branch-deleting action. Ledger rows are already terminal
-                // ('failed') from per-run settle — ensured defensively here.
-                for (const a of allocated) {
-                    await remove(git, {
-                        repoDir: baseRepo, worktreePath: a.handle.worktreePath, branch: a.handle.branch, deleteBranch: false,
-                    }).catch((err) => {
-                        console.warn(`[rail-isolated] failed to remove failed worktree ${a.handle.worktreePath}: ${err.message}`);
-                    });
-                    const wt = (0, rail_worktrees_store_1.getRailWorktree)(ctx.db, a.ledgerId);
-                    if (wt && !(0, rail_worktrees_store_1.isTerminalMergeState)(wt.merge_state))
-                        (0, rail_worktrees_store_1.updateRailWorktreeState)(ctx.db, a.ledgerId, 'failed');
-                }
-            }
             return; // legacy merge-back never runs in PR mode
         }
+        const branches = results.flatMap((result) => result.run.ticketIds.map((ticketId) => ({
+            ticketId,
+            branch: result.run.handle.branch,
+            succeeded: result.deliveryOutcome === 'ready',
+        })));
         try {
             const outcomes = await (0, rail_merge_orchestrator_1.runMergeBack)({
                 git, executor: (0, loop_executors_1.createLoopExecutors)(), baseDir: baseRepo,
@@ -605,33 +1347,674 @@ async function launchIsolatedRail(input, io = {}) {
                 const r = results.find((x) => x.run.ticketId === o.ticketId);
                 if (!r)
                     continue;
+                if (!r.safeToRelease) {
+                    (0, rail_worktrees_store_1.updateRailWorktreeState)(ctx.db, r.run.ledgerId, 'needs-review');
+                    continue;
+                }
                 // Merged → drop the branch; needs-review / skipped → keep the branch for the human.
                 await remove(git, {
                     repoDir: baseRepo, worktreePath: r.run.handle.worktreePath, branch: o.branch,
-                    deleteBranch: o.state === 'merged',
+                    // Legacy merge-back is still an automatic cleanup path. A non-force
+                    // unmount fails closed if anything changed after merge-back, and the
+                    // branch is retained because this path has no durable immutable tip
+                    // evidence with which to authorize a destructive `branch -D`.
+                    deleteBranch: false,
+                    force: false,
+                }).then(() => {
+                    if (r.implementationOutcome === 'failed')
+                        (0, rail_worktrees_store_1.updateRailWorktreeState)(ctx.db, r.run.ledgerId, 'failed');
                 }).catch(() => { });
             }
         }
         catch (err) {
             console.error('[rail-isolated] merge-back failed:', err);
         }
+    }).catch(async (err) => {
+        const detail = errorDetail(err);
+        console.error(`[rail-isolated] aggregate settlement failed: ${detail}`);
+        if (!prMode || !prDeliveryId || (0, rail_pr_store_1.getPrDelivery)(ctx.db, prDeliveryId)?.decision !== 'building')
+            return;
+        const retained = await Promise.all(guardedRunPromises);
+        for (const result of retained)
+            markWorktree(result.run, 'needs-review');
+        if ((0, rail_pr_store_1.transitionDecision)(ctx.db, prDeliveryId, 'building', 'pr_failed', {
+            branches: branchRecords(retained.map((result) => ({
+                ...result,
+                deliveryOutcome: 'blocked',
+                failureCode: result.failureCode ?? 'settlement_interrupted',
+                failureDetail: result.failureDetail ?? detail,
+                safeToRelease: false,
+            }))),
+            worktreeIds: allocated.map((run) => run.ledgerId),
+            implementationOutcome: aggregateImplementationOutcome(retained),
+            deliveryOutcome: 'blocked',
+            statusCode: 'settlement_interrupted',
+            statusDetail: detail,
+        })) {
+            broadcastPrState();
+            syncOriginCard('update');
+        }
     });
     return allocated.map((a) => a.runId);
 }
+function recoveryOverlayExcludes(repoDir, worktreePath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(worktreePath, worktree_overlay_1.OVERLAY_MANIFEST), 'utf8'));
+        const values = Array.isArray(parsed) ? parsed : parsed?.paths;
+        if (!Array.isArray(values))
+            return [];
+        return values.filter((value) => {
+            if (typeof value !== 'string' || value.length === 0 || path.isAbsolute(value))
+                return false;
+            if (value.includes('\\') || value.split('/').includes('..') || /[\0:*?\[\]]/.test(value))
+                return false;
+            if (value === worktree_overlay_1.OVERLAY_MANIFEST)
+                return true;
+            if (!/^\.(?:claude|codex|gemini)\/[^/]+(?:\/[^/]+)*$/.test(value))
+                return false;
+            try {
+                // Manifest contents are worktree-writable and therefore not authority.
+                // Ignore only links that still prove they are overlay scaffolding;
+                // copied/modified files remain recoverable dirty data.
+                const destination = path.join(worktreePath, value);
+                if (!fs.lstatSync(destination).isSymbolicLink())
+                    return false;
+                const linkTarget = fs.readlinkSync(destination);
+                return path.resolve(path.dirname(destination), linkTarget) === path.resolve(repoDir, value);
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    catch {
+        return [];
+    }
+}
+async function authenticatedRecoveryDisplayPath(git, repoDir, ledgerPath, expectedBranch, registeredPaths) {
+    if (!path.isAbsolute(ledgerPath))
+        return null;
+    let realPath;
+    let repoRealPath;
+    try {
+        const stat = fs.lstatSync(ledgerPath);
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            return null;
+        realPath = fs.realpathSync(ledgerPath);
+        repoRealPath = fs.realpathSync(repoDir);
+    }
+    catch {
+        return null;
+    }
+    if (realPath === repoRealPath)
+        return null;
+    const registeredMatches = registeredPaths.filter((registeredPath) => {
+        try {
+            return fs.realpathSync(registeredPath) === realPath;
+        }
+        catch {
+            return false;
+        }
+    });
+    if (registeredMatches.length !== 1)
+        return null;
+    try {
+        const [branch, head] = await Promise.all([
+            git.run(['rev-parse', '--abbrev-ref', 'HEAD'], realPath),
+            git.run(['rev-parse', '--verify', 'HEAD'], realPath),
+        ]);
+        if (branch.code !== 0 || branch.stdout.trim() !== expectedBranch)
+            return null;
+        if (head.code !== 0 || !COMMIT_SHA_RE.test(head.stdout.trim()))
+            return null;
+        return realPath;
+    }
+    catch {
+        return null;
+    }
+}
+async function inspectRecoveryWorktree(git, repoDir, row) {
+    const overlayExcludes = recoveryOverlayExcludes(repoDir, row.worktree_path);
+    try {
+        const [status, actualBranch, head, branchRef] = await Promise.all([
+            git.run([
+                'status', '--porcelain', '--untracked-files=all', '--ignored=matching', '--', '.',
+                ...worktree_manager_1.PR_NEVER_STAGE_PATHS.map((entry) => `:(exclude)${entry}`),
+                ...overlayExcludes.map((entry) => `:(top,exclude,literal)${entry}`),
+            ], row.worktree_path),
+            git.run(['rev-parse', '--abbrev-ref', 'HEAD'], row.worktree_path),
+            git.run(['rev-parse', '--verify', 'HEAD'], row.worktree_path),
+            git.run(['rev-parse', '--verify', `refs/heads/${row.branch}`], repoDir),
+        ]);
+        const sha = head.code === 0 && COMMIT_SHA_RE.test(head.stdout.trim()) ? head.stdout.trim() : null;
+        const refSha = branchRef.code === 0 ? branchRef.stdout.trim() : '';
+        if (status.code !== 0)
+            return { safe: false, sha, detail: 'git status could not verify worktree cleanliness' };
+        if (status.stdout.trim().length > 0)
+            return { safe: false, sha, detail: 'the interrupted worktree contains uncommitted changes' };
+        if (actualBranch.code !== 0 || actualBranch.stdout.trim() !== row.branch) {
+            return { safe: false, sha, detail: `worktree is not on expected branch ${row.branch}` };
+        }
+        if (!sha || refSha !== sha) {
+            return { safe: false, sha, detail: `HEAD does not match refs/heads/${row.branch}` };
+        }
+        return { safe: true, sha };
+    }
+    catch (err) {
+        return { safe: false, sha: null, detail: errorDetail(err) };
+    }
+}
 /**
- * Startup reconciliation: a crash mid-fan-out leaves worktrees on disk and ledger
- * rows stuck in a non-terminal state. Remove each orphan's worktree (best-effort,
- * keeping its branch for inspection) and mark the row `failed`. No-op (no git
- * calls) when there are no stuck rows — so it is free for projects that never used
- * isolation. Returns how many rows were reconciled.
+ * Startup reconciliation is serialized with launch allocation. It proves each
+ * orphan clean and durably referenced before removal; successful, dirty,
+ * unknown, or ref-mismatched work remains mounted as needs-review. Building
+ * delivery generations are then recovered from the durable engine outcomes.
  */
 async function reconcileRailWorktrees(db, repoDir, io = {}) {
     const git = io.git ?? worktree_manager_1.defaultGitRunner;
+    const exec = io.exec ?? pr_publisher_1.defaultExec;
     const remove = io.remove ?? worktree_manager_1.removeWorktree;
-    const stuck = (0, rail_worktrees_store_1.listNonTerminalRailWorktrees)(db);
-    for (const row of stuck) {
-        await remove(git, { repoDir, worktreePath: row.worktree_path, branch: row.branch, deleteBranch: false }).catch(() => { });
-        (0, rail_worktrees_store_1.updateRailWorktreeState)(db, row.id, 'failed');
-    }
-    return stuck.length;
+    return (0, repo_lock_1.withRepoLock)(repoDir, async () => {
+        const stuck = (0, rail_worktrees_store_1.listNonTerminalRailWorktrees)(db);
+        const autoReleaseWorktreeIds = new Set();
+        const settledDeliveries = db.prepare(`
+      SELECT decision, delivery_outcome, worktree_ids FROM rail_pr_deliveries
+       WHERE decision <> 'building'
+         AND delivery_outcome IN ('delivered', 'no_changes', 'retryable_failure')
+    `).all();
+        for (const delivery of settledDeliveries) {
+            try {
+                const ids = JSON.parse(delivery.worktree_ids);
+                if (Array.isArray(ids)) {
+                    for (const id of ids)
+                        if (typeof id === 'string')
+                            autoReleaseWorktreeIds.add(id);
+                }
+            }
+            catch { /* malformed history never authorizes cleanup */ }
+        }
+        const verifiedShaByRun = new Map();
+        for (const row of stuck) {
+            const run = row.run_id
+                ? db.prepare('SELECT status, final_outcome FROM loop_runs WHERE id = ?').get(row.run_id)
+                : undefined;
+            const inspection = await inspectRecoveryWorktree(git, repoDir, row);
+            if (run?.status === 'completed' && run.final_outcome === 'success') {
+                if (inspection.safe && inspection.sha) {
+                    if (row.run_id)
+                        verifiedShaByRun.set(row.run_id, inspection.sha);
+                    if (autoReleaseWorktreeIds.has(row.id)) {
+                        try {
+                            await remove(git, {
+                                repoDir,
+                                worktreePath: row.worktree_path,
+                                branch: row.branch,
+                                deleteBranch: false,
+                                force: false,
+                            });
+                            (0, rail_worktrees_store_1.updateRailWorktreeState)(db, row.id, 'released');
+                        }
+                        catch {
+                            (0, rail_worktrees_store_1.updateRailWorktreeState)(db, row.id, 'built');
+                        }
+                    }
+                    else {
+                        (0, rail_worktrees_store_1.updateRailWorktreeState)(db, row.id, 'built');
+                    }
+                }
+                else {
+                    (0, rail_worktrees_store_1.updateRailWorktreeState)(db, row.id, 'needs-review');
+                }
+                continue;
+            }
+            if (run?.status === 'completed' && inspection.safe) {
+                try {
+                    await remove(git, {
+                        repoDir,
+                        worktreePath: row.worktree_path,
+                        branch: row.branch,
+                        deleteBranch: false,
+                        force: false,
+                    });
+                    (0, rail_worktrees_store_1.updateRailWorktreeState)(db, row.id, 'failed');
+                }
+                catch {
+                    // A failed non-force removal leaves mount state uncertain; retain the ledger as
+                    // needs-review instead of claiming cleanup succeeded.
+                    (0, rail_worktrees_store_1.updateRailWorktreeState)(db, row.id, 'needs-review');
+                }
+                continue;
+            }
+            // Missing/incomplete run evidence, dirty state, status failure, and ref
+            // mismatch are all recoverable uncertainty. Never force-remove them.
+            (0, rail_worktrees_store_1.updateRailWorktreeState)(db, row.id, 'needs-review');
+        }
+        const recovered = (0, rail_pr_store_1.reconcileFailedBuildingPrDeliveries)(db, { startup: true });
+        // Migration 49 repairs legacy false implementation failures before Git is
+        // available. Revisit those already-pr_failed rows here: if their own
+        // durable run/worktree ledger proves one exact clean object, the card can
+        // safely offer Retry push instead of forcing destructive cleanup.
+        const migratedInterrupted = db.prepare(`
+      SELECT id FROM rail_pr_deliveries
+       WHERE decision = 'pr_failed'
+         AND implementation_outcome IN ('succeeded', 'partially_succeeded')
+         AND delivery_outcome = 'blocked'
+         AND status_code IN ('settlement_interrupted', 'recovery_unavailable')
+         AND pr_url IS NOT NULL
+         AND branch IS NOT NULL
+    `).all()
+            .map(({ id }) => (0, rail_pr_store_1.getPrDelivery)(db, id))
+            .filter((delivery) => delivery !== undefined);
+        // Audit rows healed by an earlier release too. Migration 49 left its causal
+        // marker in the unit records even after Retry push changed the top-level
+        // status, which lets a newer build replace a mistakenly frozen old branch
+        // tip with the unique run-owned settlement commit.
+        const previouslyRecovered = db.prepare(`
+      SELECT id FROM rail_pr_deliveries
+       WHERE decision IN ('pr_draft', 'pr_ready')
+         AND implementation_outcome IN ('succeeded', 'partially_succeeded')
+         AND delivery_outcome = 'delivered'
+         AND delivery_sha IS NOT NULL
+         AND pr_url IS NOT NULL
+         AND branch IS NOT NULL
+    `).all()
+            .map(({ id }) => (0, rail_pr_store_1.getPrDelivery)(db, id))
+            .filter((delivery) => {
+            if (!delivery)
+                return false;
+            try {
+                const units = JSON.parse(delivery.branches);
+                return Array.isArray(units) && units.some((unit) => unit?.failureCode === 'settlement_interrupted');
+            }
+            catch {
+                return false;
+            }
+        });
+        const recoveryCandidates = [...new Map([...recovered, ...migratedInterrupted, ...previouslyRecovered].map((delivery) => [delivery.id, delivery])).values()];
+        // `git fsck` can be materially more expensive than the ordinary refs/log
+        // lookup. Defer it until a causally eligible legacy run actually needs
+        // inspection, then share the exact result across every candidate in this
+        // serialized reconciliation pass.
+        let unreachableRecoveryScan = null;
+        const getUnreachableRecoveryScan = () => {
+            if (!unreachableRecoveryScan) {
+                unreachableRecoveryScan = (0, rail_pr_recovery_git_1.scanUnreachableRecoveryCommits)(git, repoDir);
+            }
+            return unreachableRecoveryScan;
+        };
+        let recoveryProtectionScan = null;
+        const getRecoveryProtectionScan = () => {
+            if (!recoveryProtectionScan) {
+                recoveryProtectionScan = (0, rail_pr_recovery_git_1.listRecoveryCommitProtections)(git, repoDir);
+            }
+            return recoveryProtectionScan;
+        };
+        for (const delivery of recoveryCandidates) {
+            if (!['succeeded', 'partially_succeeded'].includes(delivery.implementation_outcome))
+                continue;
+            // Exact-SHA promotion here is specifically an existing-PR retry. A fresh
+            // recovered generation remains on_review/ready and follows normal draft
+            // creation; it must not be relabelled as a failed push merely because its
+            // clean worktree also yielded a verifiable SHA.
+            if (!delivery.pr_url || !delivery.branch)
+                continue;
+            let runIds = [];
+            try {
+                const parsed = JSON.parse(delivery.run_ids);
+                if (Array.isArray(parsed))
+                    runIds = parsed.filter((value) => typeof value === 'string');
+            }
+            catch { /* malformed legacy row remains blocked without a retry SHA */ }
+            let recoveryAwareBranches;
+            const liveRecoveryPaths = [];
+            try {
+                const units = JSON.parse(delivery.branches);
+                const worktreeIds = JSON.parse(delivery.worktree_ids);
+                const ledgers = Array.isArray(worktreeIds)
+                    ? worktreeIds
+                        .filter((value) => typeof value === 'string')
+                        .map((worktreeId) => (0, rail_worktrees_store_1.getRailWorktree)(db, worktreeId))
+                        .filter((worktree) => Boolean(worktree))
+                    : [];
+                if (Array.isArray(units)) {
+                    const registeredPaths = await (0, worktree_manager_1.listWorktrees)(git, repoDir);
+                    recoveryAwareBranches = [];
+                    for (const unit of units) {
+                        const ledger = ledgers.find((candidate) => (candidate.branch === unit.branch &&
+                            (unit.runId ? candidate.run_id === unit.runId : true) &&
+                            fs.existsSync(candidate.worktree_path)));
+                        if (!ledger) {
+                            // A path is device-local, ephemeral evidence. Never keep an old
+                            // pointer merely because a previous reconciliation projected it:
+                            // another computer or later cleanup may no longer have those
+                            // bytes, and the UI must not advertise a historical path as live.
+                            const { worktreePath: _stalePath, ...withoutStalePath } = unit;
+                            recoveryAwareBranches.push(withoutStalePath);
+                            continue;
+                        }
+                        const authenticatedPath = await authenticatedRecoveryDisplayPath(git, repoDir, ledger.worktree_path, unit.branch, registeredPaths);
+                        if (!authenticatedPath) {
+                            const { worktreePath: _stalePath, ...withoutUnauthenticatedPath } = unit;
+                            recoveryAwareBranches.push(withoutUnauthenticatedPath);
+                            continue;
+                        }
+                        liveRecoveryPaths.push(authenticatedPath);
+                        recoveryAwareBranches.push({ ...unit, worktreePath: authenticatedPath });
+                    }
+                }
+            }
+            catch { /* malformed legacy unit/path evidence stays undisclosed */ }
+            const recoveryLocation = [...new Set(liveRecoveryPaths)][0] ?? null;
+            const retainBlockedWithDetail = (detail, deliverySha = null, 
+            // A currently authenticated worktree is actionable local evidence;
+            // without one, repeated Commit promises are misleading. Recheck stays
+            // legal in recovery_unavailable and can still promote a later restored
+            // worktree or newly discovered orphan object.
+            statusCode = recoveryLocation
+                ? 'settlement_interrupted'
+                : 'recovery_unavailable') => {
+                const next = delivery.decision === 'pr_draft' || delivery.decision === 'pr_ready'
+                    ? 'pr_failed'
+                    : delivery.decision;
+                const projectedBranchesUnchanged = recoveryAwareBranches === undefined ||
+                    delivery.branches === JSON.stringify(recoveryAwareBranches);
+                if (delivery.decision === next && delivery.status_detail === detail &&
+                    delivery.delivery_sha === deliverySha && delivery.is_continuation === 1 &&
+                    delivery.status_code === statusCode && projectedBranchesUnchanged)
+                    return;
+                (0, rail_pr_store_1.transitionDecision)(db, delivery.id, delivery.decision, next, {
+                    deliveryOutcome: 'blocked',
+                    statusCode,
+                    statusDetail: detail,
+                    deliverySha,
+                    isContinuation: true,
+                    branches: recoveryAwareBranches,
+                });
+            };
+            const retainRetryableWithDetail = (detail, deliverySha) => {
+                (0, rail_pr_store_1.transitionDecision)(db, delivery.id, delivery.decision, 'pr_failed', {
+                    deliveryOutcome: 'retryable_failure',
+                    statusCode: 'settlement_interrupted',
+                    statusDetail: detail,
+                    deliverySha,
+                    isContinuation: true,
+                    branches: recoveryAwareBranches,
+                });
+            };
+            if (runIds.length === 0) {
+                retainBlockedWithDetail(recoveryLocation
+                    ? `Exact commit recovery is unavailable because this legacy delivery has no durable run identifiers; inspect the preserved worktree at ${recoveryLocation}.`
+                    : 'Exact commit recovery is unavailable because this legacy delivery has no durable run identifiers; no remaining local evidence was deleted.');
+                continue;
+            }
+            const protectionScan = await getRecoveryProtectionScan();
+            const protectedCandidateSha = protectionScan.ok
+                ? protectionScan.protections.get((0, rail_pr_recovery_git_1.recoveryRefForDelivery)(delivery.id)) ?? null
+                : null;
+            const protectedRunSha = protectedCandidateSha && runIds.length === 1 &&
+                await (0, rail_pr_recovery_git_1.commitCarriesRunMarker)(git, repoDir, protectedCandidateSha, runIds[0])
+                ? protectedCandidateSha
+                : null;
+            const ambiguousRunCommits = new Set();
+            const unsafeRunEvidence = new Set();
+            if (protectedCandidateSha && !protectedRunSha)
+                unsafeRunEvidence.add('protected-ref');
+            let unreachableDiscoveryFailed = false;
+            for (const runId of runIds) {
+                let inspectedSha = verifiedShaByRun.get(runId) ?? null;
+                verifiedShaByRun.delete(runId);
+                const ledger = db.prepare(`
+          SELECT branch, worktree_path, merge_state FROM rail_worktrees
+           WHERE run_id = ? AND branch = ?
+           ORDER BY created_at DESC, rowid DESC LIMIT 1
+        `).get(runId, delivery.branch);
+                if (ledger?.merge_state === 'needs-review') {
+                    unsafeRunEvidence.add(runId);
+                }
+                else if (ledger && fs.existsSync(ledger.worktree_path)) {
+                    const inspection = await inspectRecoveryWorktree(git, repoDir, ledger);
+                    if (!inspection.safe || !inspection.sha) {
+                        unsafeRunEvidence.add(runId);
+                    }
+                    else {
+                        inspectedSha = inspection.sha;
+                    }
+                }
+                else if (ledger && !['released', 'failed'].includes(ledger.merge_state) && !inspectedSha) {
+                    unsafeRunEvidence.add(runId);
+                }
+                if (protectedRunSha && runId === runIds[0]) {
+                    if (inspectedSha && inspectedSha.toLowerCase() !== protectedRunSha.toLowerCase()) {
+                        unsafeRunEvidence.add(runId);
+                    }
+                    verifiedShaByRun.set(runId, protectedRunSha);
+                    continue;
+                }
+                const discovery = await (0, rail_pr_recovery_git_1.discoverRunMarkedCommit)(git, repoDir, runId, await getUnreachableRecoveryScan());
+                if (discovery.kind === 'unique') {
+                    if (inspectedSha && inspectedSha.toLowerCase() !== discovery.sha.toLowerCase()) {
+                        unsafeRunEvidence.add(runId);
+                    }
+                    verifiedShaByRun.set(runId, discovery.sha);
+                    continue;
+                }
+                if (discovery.kind === 'ambiguous') {
+                    ambiguousRunCommits.add(runId);
+                    continue;
+                }
+                if (discovery.kind === 'scan_failed') {
+                    unreachableDiscoveryFailed = true;
+                    continue;
+                }
+                const terminal = ledger && ['released', 'failed'].includes(ledger.merge_state) ? ledger : undefined;
+                if (!terminal && !inspectedSha)
+                    continue;
+                try {
+                    let sha = inspectedSha ?? '';
+                    if (!sha && terminal && fs.existsSync(terminal.worktree_path)) {
+                        const inspection = await inspectRecoveryWorktree(git, repoDir, terminal);
+                        if (inspection.safe && inspection.sha)
+                            sha = inspection.sha;
+                    }
+                    else if (!sha && terminal) {
+                        const ref = await git.run(['rev-parse', '--verify', `refs/heads/${terminal.branch}`], repoDir);
+                        sha = ref.code === 0 ? ref.stdout.trim() : '';
+                    }
+                    if (COMMIT_SHA_RE.test(sha) && await (0, rail_pr_recovery_git_1.commitCarriesRunMarker)(git, repoDir, sha, runId)) {
+                        verifiedShaByRun.set(runId, sha);
+                    }
+                }
+                catch { /* exact retry remains blocked */ }
+            }
+            const shas = [...new Set(runIds.map((runId) => verifiedShaByRun.get(runId)).filter((sha) => !!sha))];
+            const hasOneCompleteCandidate = !unreachableDiscoveryFailed &&
+                ambiguousRunCommits.size === 0 && shas.length === 1 &&
+                runIds.every((runId) => verifiedShaByRun.has(runId));
+            let protectedUnsafeCandidate = null;
+            if (unsafeRunEvidence.size > 0 && hasOneCompleteCandidate) {
+                const protection = await (0, rail_pr_recovery_git_1.protectRecoveryCommit)(git, repoDir, delivery.id, shas[0]);
+                if (!protection.ok) {
+                    retainBlockedWithDetail(`${protection.detail}; the unsafe worktree and every user-visible ref were left unchanged.`);
+                    continue;
+                }
+                protectedUnsafeCandidate = shas[0];
+            }
+            if (unsafeRunEvidence.size > 0 || unreachableDiscoveryFailed ||
+                ambiguousRunCommits.size > 0 || shas.length !== 1 ||
+                runIds.some((runId) => !verifiedShaByRun.has(runId))) {
+                retainBlockedWithDetail(unsafeRunEvidence.size > 0
+                    ? recoveryLocation
+                        ? `Exact commit recovery found dirty, needs-review, missing, or mismatched worktree evidence; inspect the preserved worktree at ${recoveryLocation}.`
+                        : 'Exact commit recovery found dirty, needs-review, missing, or mismatched worktree evidence; no remaining local evidence was deleted.'
+                    : ambiguousRunCommits.size > 0 || shas.length > 1
+                        ? recoveryLocation
+                            ? `Exact commit recovery found multiple different commits in this legacy delivery; inspect the preserved worktree at ${recoveryLocation}.`
+                            : 'Exact commit recovery found multiple different commits; no ambiguous object was selected or deleted.'
+                        : recoveryLocation
+                            ? `Exact commit recovery could not prove a run-owned commit; inspect the preserved worktree at ${recoveryLocation}.`
+                            : 'Exact commit recovery could not prove a run-owned commit from this delivery’s refs, reflogs, or unreachable objects; no remaining local evidence was deleted.', protectedUnsafeCandidate, recoveryLocation ? 'settlement_interrupted' : 'recovery_unavailable');
+                continue;
+            }
+            const candidateSha = shas[0];
+            const protectedCommit = await (0, rail_pr_recovery_git_1.protectRecoveryCommit)(git, repoDir, delivery.id, candidateSha);
+            if (!protectedCommit.ok) {
+                retainBlockedWithDetail(`${protectedCommit.detail}; no local evidence was changed or removed.`);
+                continue;
+            }
+            let causallyRecoveredBranches;
+            try {
+                const units = recoveryAwareBranches ?? JSON.parse(delivery.branches);
+                if (Array.isArray(units)) {
+                    causallyRecoveredBranches = units.map((unit) => {
+                        const sha = unit.runId ? verifiedShaByRun.get(unit.runId) : undefined;
+                        if (unit.failureCode !== 'settlement_interrupted' || !sha)
+                            return unit;
+                        const { failureCode: _legacyFailure, ...rest } = unit;
+                        return {
+                            ...rest,
+                            succeeded: true,
+                            deliveryOutcome: 'ready',
+                            finalSha: sha,
+                            changed: true,
+                        };
+                    });
+                }
+            }
+            catch { /* malformed unit evidence stays untouched and conservative */ }
+            const detachFromStalePr = (detail) => {
+                const partial = delivery.implementation_outcome === 'partially_succeeded';
+                (0, rail_pr_store_1.transitionDecision)(db, delivery.id, delivery.decision, 'on_review', {
+                    prUrl: null,
+                    prNumber: null,
+                    prState: 'local-only',
+                    deliveryOutcome: partial ? 'partial' : 'ready',
+                    statusCode: partial ? 'partial_success' : 'ready_for_review',
+                    statusDetail: `${detail}; create a new draft PR from the preserved run-owned commit`,
+                    deliverySha: candidateSha,
+                    branches: causallyRecoveredBranches,
+                    isContinuation: false,
+                });
+            };
+            const observed = await (0, pr_lifecycle_1.observePrLifecycle)(exec, repoDir, delivery.pr_url, candidateSha);
+            if (!observed.ok) {
+                retainRetryableWithDetail(`Recovered the exact run-owned commit, but the recorded PR could not be observed: ${observed.detail}; Retry push will revalidate before any push.`, candidateSha);
+                continue;
+            }
+            const identityMatches = (0, pr_lifecycle_1.matchesRecordedPrIdentity)(observed, delivery.branch, delivery.base_branch);
+            if (observed.state === 'MERGED') {
+                if (identityMatches && observed.includesExpectedSha === true) {
+                    const transitioned = (0, rail_pr_store_1.transitionDecision)(db, delivery.id, delivery.decision, 'pr_ready', {
+                        deliveryOutcome: 'delivered', statusCode: 'pr_ready', statusDetail: null,
+                        deliverySha: candidateSha, branches: causallyRecoveredBranches, isContinuation: true,
+                    });
+                    if (transitioned)
+                        await releaseDeliveredRecoveryLineage(db, git, repoDir, delivery, candidateSha);
+                }
+                else {
+                    detachFromStalePr(observed.includesExpectedSha === true
+                        ? 'the previous PR was merged after its recorded head/base identity changed'
+                        : 'the previous PR was merged without the recovered implementation commit');
+                }
+                continue;
+            }
+            if (observed.state === 'CLOSED') {
+                if (identityMatches && observed.includesExpectedSha === true) {
+                    const transitioned = (0, rail_pr_store_1.transitionDecision)(db, delivery.id, delivery.decision, 'pr_closed', {
+                        deliveryOutcome: 'delivered', statusCode: 'pr_closed', statusDetail: null,
+                        deliverySha: candidateSha, branches: causallyRecoveredBranches, isContinuation: true,
+                    });
+                    if (transitioned)
+                        await releaseDeliveredRecoveryLineage(db, git, repoDir, delivery, candidateSha);
+                }
+                else {
+                    detachFromStalePr(observed.includesExpectedSha === true
+                        ? 'the previous PR was closed after its recorded head/base identity changed'
+                        : 'the previous PR was closed without the recovered implementation commit');
+                }
+                continue;
+            }
+            if (!(0, pr_lifecycle_1.isExactOpenPr)(observed, delivery.branch, delivery.base_branch)) {
+                detachFromStalePr('the previous open PR no longer matches its recorded head/base identity');
+                continue;
+            }
+            if (observed.includesExpectedSha === true) {
+                const next = observed.isDraft ? 'pr_draft' : 'pr_ready';
+                const transitioned = (0, rail_pr_store_1.transitionDecision)(db, delivery.id, delivery.decision, next, {
+                    deliveryOutcome: 'delivered',
+                    statusCode: next === 'pr_ready' ? 'pr_ready' : 'existing_pr_updated',
+                    statusDetail: null,
+                    deliverySha: candidateSha,
+                    branches: causallyRecoveredBranches,
+                    isContinuation: true,
+                });
+                if (transitioned)
+                    await releaseDeliveredRecoveryLineage(db, git, repoDir, delivery, candidateSha);
+                continue;
+            }
+            if (observed.headRefOid && !await recoveryCommitObjectExists(git, repoDir, observed.headRefOid)) {
+                try {
+                    await git.run(['fetch', 'origin', `refs/heads/${delivery.branch}`], repoDir);
+                }
+                catch { /* the immutable object check below remains authoritative */ }
+            }
+            if (!observed.headRefOid ||
+                !await recoveryCommitObjectExists(git, repoDir, observed.headRefOid) ||
+                !await isFastForwardRecoveryCommit(git, repoDir, observed.headRefOid, candidateSha)) {
+                retainBlockedWithDetail(observed.headRefOid && await recoveryCommitObjectExists(git, repoDir, observed.headRefOid)
+                    ? 'Recovered the exact run-owned commit, but it is not a fast-forward of the live PR head. The commit remains protected and nothing was pushed or removed.'
+                    : 'Recovered the exact run-owned commit, but the live PR head object could not be verified locally. The commit remains protected and nothing was pushed or removed.', candidateSha, 'recovery_unavailable');
+                continue;
+            }
+            (0, rail_pr_store_1.transitionDecision)(db, delivery.id, delivery.decision, 'pr_failed', {
+                deliveryOutcome: 'retryable_failure',
+                statusCode: 'settlement_interrupted',
+                statusDetail: 'Recovered a clean exact continuation commit; delivery can be retried safely.',
+                deliverySha: candidateSha,
+                branches: causallyRecoveredBranches,
+                isContinuation: true,
+            });
+        }
+        // Internal refs are deliberately released only after the durable row proves
+        // exact delivery/no-change. If a previous process crashed after that row
+        // transition but before `update-ref -d`, retry the idempotent exact cleanup
+        // now, including discarded/superseded predecessor refs whose objects are
+        // ancestors of the delivered successor.
+        const settledRecoveryRefs = db.prepare(`
+      SELECT id FROM rail_pr_deliveries
+       WHERE delivery_sha IS NOT NULL
+         AND (delivery_outcome IN ('delivered','no_changes') OR decision IN ('merged','completed'))
+    `).all()
+            .map(({ id }) => (0, rail_pr_store_1.getPrDelivery)(db, id))
+            .filter((row) => Boolean(row?.delivery_sha));
+        if (settledRecoveryRefs.length > 0) {
+            const protectionScan = await getRecoveryProtectionScan();
+            if (protectionScan.ok && protectionScan.protections.size > 0) {
+                for (const settled of settledRecoveryRefs) {
+                    const visited = new Set();
+                    let lineage = settled;
+                    let hasProtectedLineage = false;
+                    for (let depth = 0; lineage && depth < 32 && !visited.has(lineage.id); depth++) {
+                        visited.add(lineage.id);
+                        if (protectionScan.protections.has((0, rail_pr_recovery_git_1.recoveryRefForDelivery)(lineage.id))) {
+                            hasProtectedLineage = true;
+                            break;
+                        }
+                        lineage = lineage.supersedes_delivery_id
+                            ? (0, rail_pr_store_1.getPrDelivery)(db, lineage.supersedes_delivery_id)
+                            : undefined;
+                    }
+                    if (hasProtectedLineage) {
+                        await releaseDeliveredRecoveryLineage(db, git, repoDir, settled, settled.delivery_sha);
+                    }
+                }
+            }
+        }
+        for (const delivery of recoveryCandidates) {
+            try {
+                io.onDeliveryRecovered?.(delivery.id);
+            }
+            catch { /* durable state wins over advisory surfaces */ }
+        }
+        return stuck.length;
+    });
 }