specrails-desktop 2.29.1 → 2.29.3

package/server/dist/rails-router.js

@@ -27,7 +27,9 @@ const rail_worktree_release_1 = require("./rail-worktree-release");
 const project_git_1 = require("./project-git");
 const pr_publisher_1 = require("./pr-publisher");
 const ids_1 = require("./ids");
+const repo_lock_1 = require("./repo-lock");
 const agent_chat_registry_1 = require("./agent-chat-registry");
+const process_admission_1 = require("./process-admission");
 const VALID_MODES = new Set(['implement', 'batch-implement', 'freestyle', 'loop']);
 // Models the freestyle picker exposes (Claude aliases). Mirrors the client
 // RailModelSelector options and the project-router orchestrator-model allow-list.
@@ -38,10 +40,20 @@ const VALID_REASONING_EFFORTS = new Set(['low', 'medium', 'high']);
 function prDeliveryContinuesTickets(delivery, ticketIds) {
     if (delivery.decision !== 'pr_draft' && delivery.decision !== 'pr_ready')
         return false;
-    if (!delivery.prUrl || !delivery.branch || delivery.prState !== 'pr-created')
+    if (!delivery.prUrl || !delivery.branch || !delivery.deliverySha || delivery.prState !== 'pr-created')
         return false;
     const covered = new Set(delivery.ticketIds);
-    return ticketIds.length > 0 && ticketIds.every((id) => covered.has(id));
+    const requested = new Set(ticketIds);
+    return requested.size > 0 && requested.size === covered.size && [...requested].every((id) => covered.has(id));
+}
+function prDeliveryCheckoutBlock(delivery) {
+    if (delivery.deliveryOutcome === 'blocked') {
+        return 'delivery is blocked and has no safely checkoutable result';
+    }
+    if (!delivery.deliverySha) {
+        return 'delivery has no verified commit available for checkout';
+    }
+    return null;
 }
 function emitPrDeliveryUpdate(c, prDeliveryId) {
     const row = (0, rail_pr_store_1.getPrDelivery)(c.db, prDeliveryId);
@@ -53,11 +65,6 @@ function emitPrDeliveryUpdate(c, prDeliveryId) {
         (0, agent_chat_registry_1.getAgentChatManager)()?.updatePrDecisionCard(row.origin_conversation_id, (0, rail_pr_store_1.toPrDecisionCardEnvelope)(c.project.id, snap));
     }
 }
-function reconcileAndEmitFailedPrDeliveries(c) {
-    for (const row of (0, rail_pr_store_1.reconcileFailedBuildingPrDeliveries)(c.db)) {
-        emitPrDeliveryUpdate(c, row.id);
-    }
-}
 function createRailsRouter() {
     const router = (0, express_1.Router)({ mergeParams: true });
     function ctx(req) {
@@ -121,7 +128,6 @@ function createRailsRouter() {
             // (non-terminal) delivery per rail slot, so a refreshed client re-renders
             // the decision surface without waiting for a broadcast. The store lists
             // newest-first within each rail — keep the first per index.
-            reconcileAndEmitFailedPrDeliveries(c);
             const prDeliveries = {};
             for (const row of (0, rail_pr_store_1.listActivePrDeliveries)(c.db)) {
                 if (!(row.rail_index in prDeliveries))
@@ -166,10 +172,11 @@ function createRailsRouter() {
             res.status(500).json({ error: 'Failed to create rail' });
         }
     });
-    // DELETE /rails/:railIndex — remove a rail slot. Guarded: the rail must
-    // exist, hold no tickets, have no active job/loop run, no undecided PR
-    // delivery, and must not be the last remaining rail. Indices are identity —
-    // deleting a middle rail leaves a gap (never re-numbered).
+    // DELETE /rails/:railIndex — remove a rail slot and release its ticket
+    // assignments as one transaction. All rejection guards run before the
+    // delete, so a failed last/active/pending-PR deletion cannot strand tickets
+    // in an unassigned intermediate state. Indices are identity — deleting a
+    // middle rail leaves a gap (never re-numbered).
     router.delete('/:railIndex', (req, res) => {
         const railIndex = parseInt(req.params.railIndex, 10);
         if (isNaN(railIndex) || railIndex < 0 || railIndex >= rails_store_1.MAX_RAILS) {
@@ -192,10 +199,6 @@ function createRailsRouter() {
                 res.status(409).json({ error: 'rail_active' });
                 return;
             }
-            if ((0, rails_store_1.getRail)(c.db, railIndex).ticketIds.length > 0) {
-                res.status(409).json({ error: 'rail_not_empty' });
-                return;
-            }
             const pending = (0, rail_pr_store_1.getActivePrDeliveryByRail)(c.db, railIndex);
             if (pending) {
                 res.status(409).json({ error: 'pr_decision_pending', prDeliveryId: pending.id });
@@ -405,6 +408,16 @@ function createRailsRouter() {
         // capability) decides, so the launch no longer passes an explicit flag. A
         // legacy `interactive` body param is accepted and ignored (wire compat).
         const c = ctx(req);
+        try {
+            (0, process_admission_1.assertProcessAdmission)(c.project.id);
+        }
+        catch (err) {
+            if (err instanceof process_admission_1.ProcessAdmissionClosedError) {
+                res.status(409).json({ error: 'project_recovery_in_progress' });
+                return;
+            }
+            throw err;
+        }
         const rail = (0, rails_store_1.getRail)(c.db, railIndex);
         if (rail.ticketIds.length === 0) {
             res.status(400).json({ error: 'Rail has no tickets assigned' });
@@ -543,31 +556,47 @@ function createRailsRouter() {
                 // client so a silent fallback (no delivery row → no implementation
                 // cards) is diagnosable from the UI, not just the server log.
                 let isolationUnavailableDetail;
-                let continuablePrDeliveryForFallback = null;
-                let fallbackPrDeliveryId = null;
+                let continuablePrDelivery = null;
                 // Read-only vs mutating is DERIVED from the loop's nodes (see loop-effect),
                 // not a user flag — a content-read-only loop (no ai-step/shell) never writes,
                 // so it is not isolated; anything that can write is.
                 const loopReadOnly = (0, loop_effect_1.classifyLoopEffect)(loopGraph) === 'read-only';
-                if ((0, rail_isolation_1.isolationApplies)({ loopsEnabled: (0, feature_flags_1.isLoopsEnabled)(), scope, ticketCount: rail.ticketIds.length, readOnly: loopReadOnly })) {
-                    // Relaunch collision (ask-first PR delivery): a delivery that has not
-                    // produced a real PR yet still needs a user decision before more work
-                    // can safely append to its branches. Once a draft/published PR exists
-                    // and covers this rail's tickets, relaunch is intentional continuation
-                    // of that PR head branch (resolved inside launchIsolatedRail).
-                    if ((0, rail_isolation_1.isRailPrDeliveryEnabled)()) {
-                        const pending = (0, rail_pr_store_1.getActivePrDeliveryByRail)(c.db, railIndex);
-                        const pendingSnapshot = pending ? (0, rail_pr_store_1.toPrDeliverySnapshot)(pending) : null;
-                        if (pendingSnapshot && !prDeliveryContinuesTickets(pendingSnapshot, rail.ticketIds)) {
-                            res.status(409).json({ error: 'pr_decision_pending', prDeliveryId: pendingSnapshot.id });
-                            return;
-                        }
-                        continuablePrDeliveryForFallback = pendingSnapshot;
+                // Relaunch collision (ask-first PR delivery): this guard must run even
+                // when the worktree kill-switch is off. Otherwise a published PR follow-
+                // up silently drops to shared cwd and can commit on the ambient branch.
+                if ((0, rail_isolation_1.isRailPrDeliveryEnabled)()) {
+                    const pending = (0, rail_pr_store_1.getActivePrDeliveryByRail)(c.db, railIndex);
+                    const pendingSnapshot = pending ? (0, rail_pr_store_1.toPrDeliverySnapshot)(pending) : null;
+                    if (pendingSnapshot && !prDeliveryContinuesTickets(pendingSnapshot, rail.ticketIds)) {
+                        res.status(409).json({ error: 'pr_decision_pending', prDeliveryId: pendingSnapshot.id });
+                        return;
                     }
+                    continuablePrDelivery = pendingSnapshot;
+                }
+                const useIsolation = (0, rail_isolation_1.isolationApplies)({
+                    loopsEnabled: (0, feature_flags_1.isLoopsEnabled)(), scope, ticketCount: rail.ticketIds.length, readOnly: loopReadOnly,
+                });
+                if (continuablePrDelivery && !loopReadOnly && !useIsolation) {
+                    res.status(409).json({
+                        error: 'pr_continuation_isolation_required',
+                        detail: `Cannot continue PR branch ${continuablePrDelivery.branch} while worktree isolation is disabled.`,
+                        action: 'Enable rail worktrees and retry; PR continuations never run in the shared project checkout.',
+                    });
+                    return;
+                }
+                if (useIsolation) {
                     // Worktree isolation needs a git repo WITH at least one commit (an
                     // unborn HEAD can't be branched). Fall back (with a message) otherwise.
                     const status = await (0, worktree_manager_1.repoIsolationStatus)(worktree_manager_1.defaultGitRunner, c.project.path);
                     if (status !== 'ok') {
+                        if (continuablePrDelivery) {
+                            res.status(409).json({
+                                error: 'pr_continuation_isolation_required',
+                                detail: `Cannot continue PR branch ${continuablePrDelivery.branch} because worktree isolation is unavailable (${status}).`,
+                                action: 'Restore a git repository with a committed HEAD, ensure the PR branch is free for a dedicated worktree, then retry.',
+                            });
+                            return;
+                        }
                         isolationUnavailable = status; // 'no-git' | 'no-commits'
                         console.warn(`[rails-router] worktree isolation unavailable (${status}); running shared cwd`);
                     }
@@ -578,13 +607,38 @@ function createRailsRouter() {
                                 provider: loopProvider, model: loopModel, effort, scope,
                                 originSurface: originSurface ?? 'dashboard',
                                 originConversationId: originConversationId ?? null,
-                                preservePrDeliveryOnAllocationFailure: Boolean(continuablePrDeliveryForFallback),
-                                onPrDeliveryCreated: (id) => { fallbackPrDeliveryId = id; },
+                                ...(continuablePrDelivery ? {
+                                    requiredPrContinuation: {
+                                        deliveryId: continuablePrDelivery.id,
+                                        decision: continuablePrDelivery.decision,
+                                        branch: continuablePrDelivery.branch,
+                                        baseBranch: continuablePrDelivery.baseBranch,
+                                        prUrl: continuablePrDelivery.prUrl,
+                                        prNumber: continuablePrDelivery.prNumber,
+                                        deliverySha: continuablePrDelivery.deliverySha,
+                                    },
+                                } : {}),
                             });
                             res.status(202).json({ loopRunIds: ids, railIndex, mode, isolated: true });
                             return;
                         }
                         catch (err) {
+                            if (err instanceof rail_pr_store_1.PrDeliveryGenerationConflict) {
+                                res.status(409).json({
+                                    error: 'pr_delivery_generation_conflict',
+                                    prDeliveryId: err.currentId,
+                                });
+                                return;
+                            }
+                            if (continuablePrDelivery || err instanceof rail_isolated_launch_1.PrContinuationIsolationError) {
+                                const detail = err instanceof Error ? err.message : String(err);
+                                res.status(409).json({
+                                    error: 'pr_continuation_isolation_required',
+                                    detail,
+                                    action: 'Ensure the PR branch is available for a dedicated git worktree, then retry.',
+                                });
+                                return;
+                            }
                             console.error('[rails-router] isolated launch failed; falling back to shared cwd:', err);
                             isolationUnavailable = 'error';
                             isolationUnavailableDetail = err instanceof Error ? err.message : String(err);
@@ -596,9 +650,9 @@ function createRailsRouter() {
                 // via SPECRAILS_REPO_DIR + `--add-dir` exactly like QueueManager.
                 const loopExec = (0, workspace_resolution_1.resolveProjectExecution)({ slug: c.project.slug, path: c.project.path });
                 const loopRunIds = [];
-                const sharedRunSettles = [];
+                const loopTicketCompletionStatus = (0, rail_isolation_1.isRailPrDeliveryEnabled)() ? 'on_review' : 'done';
                 const launchLoopRun = (runId, ticketIds, spec) => {
-                    c.railLoopRuns.set(runId, { railIndex, ticketIds });
+                    c.railLoopRuns.set(runId, { railIndex, ticketIds, requiresTerminalIntent: true });
                     // Code-Explorer provenance for shared-cwd loop runs (isolated runs
                     // record inside rail-isolated-launch): snapshot the REPO before the
                     // run, diff + record at settle. Loop runs settle outside QueueManager,
@@ -641,6 +695,7 @@ function createRailsRouter() {
                         railIndex,
                         ticketId: ticketIds[0],
                         spec: spec ? { ...spec, ticketIds } : { ticketIds },
+                        ticketCompletionStatus: loopTicketCompletionStatus,
                         constants: (0, loop_constants_1.loadConstantMap)(c.desktopDb),
                         provider: loopProvider,
                         model: loopModel,
@@ -657,7 +712,7 @@ function createRailsRouter() {
                         c.onLoopRunFinished(runId, 'failed');
                         return false;
                     });
-                    sharedRunSettles.push(runPromise);
+                    void runPromise;
                     loopRunIds.push(runId);
                     try {
                         c.jiraSyncManager.onRailLaunch(ticketIds, runId);
@@ -675,60 +730,6 @@ function createRailsRouter() {
                         launchLoopRun((0, ids_1.newId)(), [ticketId], c.getTicketSpec(ticketId));
                     }
                 }
-                if (fallbackPrDeliveryId) {
-                    const row = (0, rail_pr_store_1.getPrDelivery)(c.db, fallbackPrDeliveryId);
-                    const isExistingPrIteration = row?.decision === 'building' && row.pr_state === 'pr-created' && Boolean(row.pr_url && row.branch);
-                    if (isExistingPrIteration) {
-                        if ((0, rail_pr_store_1.transitionDecision)(c.db, fallbackPrDeliveryId, 'building', 'building', { runIds: loopRunIds })) {
-                            emitPrDeliveryUpdate(c, fallbackPrDeliveryId);
-                        }
-                        void Promise.allSettled(sharedRunSettles).then((settled) => {
-                            void (async () => {
-                                const current = (0, rail_pr_store_1.getPrDelivery)(c.db, fallbackPrDeliveryId);
-                                if (current?.decision !== 'building')
-                                    return;
-                                if (current.pr_state === 'pr-created' && current.pr_url && current.branch) {
-                                    const succeeded = settled.every((s) => s.status === 'fulfilled' && s.value === true);
-                                    if (!succeeded) {
-                                        if ((0, rail_pr_store_1.transitionDecision)(c.db, fallbackPrDeliveryId, 'building', 'implementation_failed')) {
-                                            emitPrDeliveryUpdate(c, fallbackPrDeliveryId);
-                                        }
-                                        return;
-                                    }
-                                    const commit = await (0, worktree_manager_1.commitWorktreeAndVerify)(worktree_manager_1.defaultGitRunner, c.project.path, `specrails: PR follow-up (${loopRunIds.join(', ')})`);
-                                    if (!commit.clean) {
-                                        console.error(`[rails-router] existing PR fallback commit verification failed: ${commit.error ?? 'dirty worktree'}${commit.dirty.length > 0 ? `; dirty=${commit.dirty.slice(0, 8).join(', ')}` : ''}`);
-                                        if ((0, rail_pr_store_1.transitionDecision)(c.db, fallbackPrDeliveryId, 'building', 'implementation_failed')) {
-                                            emitPrDeliveryUpdate(c, fallbackPrDeliveryId);
-                                        }
-                                        return;
-                                    }
-                                    const pushed = await (0, pr_publisher_1.pushBranch)(pr_publisher_1.defaultExec, {
-                                        repoDir: c.project.path,
-                                        branch: current.branch,
-                                        baseBranch: current.base_branch,
-                                    });
-                                    if (pushed.state === 'local-only') {
-                                        if ((0, rail_pr_store_1.transitionDecision)(c.db, fallbackPrDeliveryId, 'building', 'pr_failed', { prState: 'local-only' })) {
-                                            emitPrDeliveryUpdate(c, fallbackPrDeliveryId);
-                                        }
-                                        return;
-                                    }
-                                    if ((0, rail_pr_store_1.transitionDecision)(c.db, fallbackPrDeliveryId, 'building', 'pr_ready', { prState: 'pr-created' })) {
-                                        emitPrDeliveryUpdate(c, fallbackPrDeliveryId);
-                                    }
-                                }
-                            })().catch((err) => {
-                                console.error('[rails-router] existing PR fallback push failed:', err);
-                                if (fallbackPrDeliveryId) {
-                                    if ((0, rail_pr_store_1.transitionDecision)(c.db, fallbackPrDeliveryId, 'building', 'pr_failed', { prState: 'local-only' })) {
-                                        emitPrDeliveryUpdate(c, fallbackPrDeliveryId);
-                                    }
-                                }
-                            });
-                        });
-                    }
-                }
                 res.status(202).json({
                     loopRunIds, railIndex, mode,
                     ...(isolationUnavailable ? { isolationUnavailable } : {}),
@@ -890,7 +891,8 @@ function createRailsRouter() {
     });
     // POST /rails/pr-decision — the ONE decision action (safe-pr-review-flow) both
     // surfaces (dashboard rail row + agent-chat card) call on a rail_pr_deliveries
-    // row: create-pr | publish | discard | poll-merge, compare-and-set-guarded by
+    // row: create-pr | publish | discard/dismiss | poll/reopen | merge-local |
+    // acknowledge-no-changes | recover-and-retry, compare-and-set-guarded by
     // expectedDecision (a raced concurrent answer loses with 409 stale_decision).
     // Replaces the stateless v1 POST /rails/pr-review passthrough. The route only
     // validates and delegates — the action logic lives in rail-pr-decision.ts.
@@ -903,7 +905,7 @@ function createRailsRouter() {
             return;
         }
         if (!(0, rail_pr_decision_1.isPrDecisionAction)(action)) {
-            res.status(400).json({ error: "action must be 'create-pr', 'publish', 'discard' or 'poll-merge'" });
+            res.status(400).json({ error: `action must be one of: ${rail_pr_decision_1.PR_DECISION_ACTIONS.join(', ')}` });
             return;
         }
         if (typeof expectedDecision !== 'string' || !expectedDecision) {
@@ -911,17 +913,40 @@ function createRailsRouter() {
             return;
         }
         try {
-            const result = await (0, rail_pr_decision_1.executePrDecision)({
-                db: c.db,
-                project: { id: c.project.id, slug: c.project.slug, path: c.project.path },
-                git: worktree_manager_1.defaultGitRunner,
-                exec: pr_publisher_1.defaultExec,
-                broadcast: c.broadcast,
-                jiraSyncManager: c.jiraSyncManager,
-            }, { prDeliveryId, action, expectedDecision });
-            res.status(result.status).json(result.body);
+            const admission = (0, process_admission_1.captureProcessAdmission)(c.project.id);
+            const execute = () => {
+                admission.assertCurrent();
+                return (0, rail_pr_decision_1.executePrDecision)({
+                    db: c.db,
+                    project: { id: c.project.id, slug: c.project.slug, path: c.project.path },
+                    git: worktree_manager_1.defaultGitRunner,
+                    exec: pr_publisher_1.defaultExec,
+                    broadcast: c.broadcast,
+                    jiraSyncManager: c.jiraSyncManager,
+                    assertAdmission: () => admission.assertCurrent(),
+                }, { prDeliveryId, action, expectedDecision });
+            };
+            // Every decision that can touch refs/worktrees shares the same project
+            // mutex as startup reconciliation, launch allocation and checkout. Local
+            // merge already acquires it internally to keep its guarded read/advance
+            // sequence atomic, so avoid nesting that non-reentrant lock.
+            const result = action === 'merge-local'
+                ? await execute()
+                : await (0, repo_lock_1.withRepoLock)(c.project.path, execute);
+            // The durable row is authoritative. Return its post-action snapshot even
+            // when the WebSocket broadcast is dropped or another surface won the
+            // race; clients can converge immediately without optimistic inference.
+            const current = (0, rail_pr_store_1.getPrDelivery)(c.db, prDeliveryId);
+            res.status(result.status).json({
+                ...result.body,
+                ...(current ? { snapshot: (0, rail_pr_store_1.toPrDeliverySnapshot)(current) } : {}),
+            });
         }
         catch (err) {
+            if (err instanceof process_admission_1.ProcessAdmissionClosedError) {
+                res.status(409).json({ error: 'project_recovery_in_progress' });
+                return;
+            }
             console.error('[rails-router] pr-decision error:', err);
             res.status(500).json({ error: 'pr-decision failed', detail: err.message });
         }
@@ -938,38 +963,131 @@ function createRailsRouter() {
             res.status(400).json({ error: 'prDeliveryId is required' });
             return;
         }
+        let admission;
+        try {
+            admission = (0, process_admission_1.captureProcessAdmission)(c.project.id);
+        }
+        catch (err) {
+            if (err instanceof process_admission_1.ProcessAdmissionClosedError) {
+                res.status(409).json({ error: 'project_recovery_in_progress' });
+                return;
+            }
+            throw err;
+        }
         const row = (0, rail_pr_store_1.getPrDelivery)(c.db, prDeliveryId);
         if (!row) {
             res.status(404).json({ error: 'Unknown prDeliveryId' });
             return;
         }
+        const active = (0, rail_pr_store_1.getActivePrDeliveryByRail)(c.db, row.rail_index);
+        if (!active || active.id !== row.id) {
+            res.status(409).json({
+                error: 'stale_decision',
+                current: active?.decision ?? null,
+                currentPrDeliveryId: active?.id ?? null,
+            });
+            return;
+        }
         const snap = (0, rail_pr_store_1.toPrDeliverySnapshot)(row);
+        const checkoutBlock = prDeliveryCheckoutBlock(snap);
+        if (checkoutBlock) {
+            res.status(409).json({ error: 'checkout_not_deliverable', detail: checkoutBlock });
+            return;
+        }
         if (!snap.branch || !snap.prUrl) {
             res.status(409).json({ error: 'checkout_unavailable', detail: 'delivery has no PR branch' });
             return;
         }
         try {
-            const info = await (0, project_git_1.getProjectGitInfo)(c.project.path);
-            if (!info.git) {
-                res.status(409).json({ error: 'checkout_unavailable', detail: 'project is not a git repository' });
-                return;
-            }
-            if (info.dirty) {
-                res.status(409).json({ error: 'checkout_dirty', detail: 'Working tree has uncommitted changes. Commit or stash them before checkout.' });
-                return;
-            }
-            await (0, rail_worktree_release_1.releaseRailWorktrees)({
-                db: c.db,
-                git: worktree_manager_1.defaultGitRunner,
-                repoDir: c.project.path,
-                worktreeIds: snap.worktreeIds,
+            const outcome = await (0, repo_lock_1.withRepoLock)(c.project.path, async () => {
+                admission.assertCurrent();
+                const current = (0, rail_pr_store_1.getActivePrDeliveryByRail)(c.db, row.rail_index);
+                if (!current || current.id !== row.id) {
+                    return {
+                        ok: false,
+                        status: 409,
+                        error: 'stale_decision',
+                        detail: 'The delivery generation changed before checkout.',
+                    };
+                }
+                const currentSnap = (0, rail_pr_store_1.toPrDeliverySnapshot)(current);
+                const currentCheckoutBlock = prDeliveryCheckoutBlock(currentSnap);
+                if (currentCheckoutBlock) {
+                    return {
+                        ok: false,
+                        status: 409,
+                        error: 'checkout_not_deliverable',
+                        detail: currentCheckoutBlock,
+                    };
+                }
+                if (!currentSnap.branch || !currentSnap.prUrl) {
+                    return {
+                        ok: false,
+                        status: 409,
+                        error: 'checkout_not_deliverable',
+                        detail: 'The current delivery no longer has an attached PR branch.',
+                    };
+                }
+                const cleanliness = await (0, project_git_1.inspectProjectCheckoutCleanliness)(c.project.path);
+                if (!cleanliness.ok) {
+                    return {
+                        ok: false,
+                        status: 409,
+                        error: 'checkout_safety_unknown',
+                        detail: cleanliness.detail,
+                    };
+                }
+                if (!cleanliness.clean) {
+                    return { ok: false, status: 409, error: 'checkout_dirty', detail: 'Working tree has uncommitted changes. Commit or stash them before checkout.' };
+                }
+                const info = await (0, project_git_1.getProjectGitInfo)(c.project.path);
+                if (!info.git) {
+                    return { ok: false, status: 409, error: 'checkout_unavailable', detail: 'project is not a git repository' };
+                }
+                let archived = false;
+                const cleanupWarnings = await (0, rail_worktree_release_1.releaseRailWorktrees)({
+                    db: c.db,
+                    git: worktree_manager_1.defaultGitRunner,
+                    repoDir: c.project.path,
+                    worktreeIds: currentSnap.worktreeIds,
+                    expectedHeadByBranch: (0, rail_worktree_release_1.durableBranchHeads)(currentSnap.branches),
+                    overlayEvidenceByBranch: (0, rail_worktree_release_1.durableOverlayCleanupEvidence)(currentSnap.branches),
+                    onSafetyArchive: (archive) => {
+                        archived = true;
+                        if (!(0, rail_pr_store_1.appendPrDeliverySafetyArchive)(c.db, row.id, archive)) {
+                            throw new Error(`delivery ${row.id} disappeared while recording safety archive ${archive}`);
+                        }
+                    },
+                });
+                if (archived) {
+                    const archivedRow = (0, rail_pr_store_1.getPrDelivery)(c.db, row.id);
+                    if (archivedRow) {
+                        const archivedSnap = (0, rail_pr_store_1.toPrDeliverySnapshot)(archivedRow);
+                        c.broadcast((0, rail_pr_store_1.toRailPrStateMessage)(c.project.id, archivedSnap));
+                        if (archivedRow.origin_conversation_id) {
+                            (0, agent_chat_registry_1.getAgentChatManager)()?.updatePrDecisionCard(archivedRow.origin_conversation_id, (0, rail_pr_store_1.toPrDecisionCardEnvelope)(c.project.id, archivedSnap));
+                        }
+                    }
+                }
+                if (cleanupWarnings.length > 0) {
+                    return {
+                        ok: false,
+                        status: 409,
+                        error: 'checkout_unavailable',
+                        detail: cleanupWarnings[0],
+                    };
+                }
+                const checkedOut = await (0, project_git_1.checkoutProjectReviewBranch)(c.project.path, currentSnap.branch, currentSnap.deliverySha);
+                if (!checkedOut.ok) {
+                    return { ok: false, status: 409, error: 'checkout_failed', detail: checkedOut.error };
+                }
+                return { ok: true, git: await (0, project_git_1.getProjectGitInfo)(c.project.path) };
             });
-            const result = await (0, project_git_1.checkoutProjectReviewBranch)(c.project.path, snap.branch);
-            if (!result.ok) {
-                res.status(409).json({ error: 'checkout_failed', detail: result.error });
+            if (!outcome.ok) {
+                res.status(outcome.status).json({ error: outcome.error, detail: outcome.detail });
                 return;
             }
-            res.json({ ok: true, git: await (0, project_git_1.getProjectGitInfo)(c.project.path) });
+            res.json(outcome);
         }
         catch (err) {
             console.error('[rails-router] pr-checkout error:', err);

package/server/dist/rails-store.js

@@ -8,6 +8,10 @@ exports.railExists = railExists;
 exports.getRails = getRails;
 exports.getRail = getRail;
 exports.setRailTickets = setRailTickets;
+exports.claimRailTickets = claimRailTickets;
+exports.claimTicketOutcomeOwners = claimTicketOutcomeOwners;
+exports.ticketOutcomeOwner = ticketOutcomeOwner;
+exports.releaseRailTicketsOwnedBy = releaseRailTicketsOwnedBy;
 exports.setRailProfile = setRailProfile;
 exports.setRailEngine = setRailEngine;
 exports.createRail = createRail;
@@ -116,9 +120,107 @@ function setRailTickets(db, railIndex, ticketIds, mode, profileName, aiEngine) {
         for (let i = 0; i < ticketIds.length; i++) {
             insertStmt.run(railIndex, ticketIds[i], i, resolvedMode, resolvedProfile, resolvedEngine);
         }
+        if (ticketIds.length === 0) {
+            db.prepare('DELETE FROM rail_ticket_ownership WHERE rail_index = ?').run(railIndex);
+        }
+        else {
+            const placeholders = ticketIds.map(() => '?').join(', ');
+            db.prepare(`DELETE FROM rail_ticket_ownership
+          WHERE rail_index = ? AND ticket_id NOT IN (${placeholders})`).run(railIndex, ...ticketIds);
+        }
     })();
     return { railIndex, ticketIds, mode: resolvedMode, profileName: resolvedProfile, aiEngine: resolvedEngine };
 }
+/** Claim the exact rail assignments for a concrete launch. Relaunching the
+ * same ticket advances its generation and replaces owner_id, so a delayed
+ * terminal replay from an older job/run cannot remove the new assignment. */
+function claimRailTickets(db, railIndex, ticketIds, ownerId) {
+    const claim = db.prepare(`
+    INSERT INTO rail_ticket_ownership (
+      rail_index, ticket_id, owner_id, generation, claimed_at
+    ) VALUES (?, ?, ?, 1, datetime('now'))
+    ON CONFLICT(rail_index, ticket_id) DO UPDATE SET
+      owner_id = excluded.owner_id,
+      generation = rail_ticket_ownership.generation + 1,
+      claimed_at = excluded.claimed_at
+  `);
+    db.transaction(() => {
+        for (const ticketId of [...new Set(ticketIds)]) {
+            claim.run(railIndex, ticketId, ownerId);
+        }
+    })();
+}
+/** Project-wide causal owner for ticket terminal effects. Unlike the JSON
+ * applied-effect marker, this claim participates in the same SQLite commit as
+ * queue/loop admission, so a hard crash cannot create a ghost filesystem owner
+ * or admit work without ownership. */
+function claimTicketOutcomeOwners(db, ticketIds, ownerId) {
+    const claim = db.prepare(`
+    INSERT INTO ticket_outcome_ownership (
+      ticket_id, owner_id, generation, claimed_at
+    ) VALUES (?, ?, 1, datetime('now'))
+    ON CONFLICT(ticket_id) DO UPDATE SET
+      owner_id = excluded.owner_id,
+      generation = ticket_outcome_ownership.generation + 1,
+      claimed_at = excluded.claimed_at
+  `);
+    for (const ticketId of [...new Set(ticketIds)])
+        claim.run(ticketId, ownerId);
+}
+function ticketOutcomeOwner(db, ticketId) {
+    try {
+        const row = db.prepare(`
+      SELECT owner_id FROM ticket_outcome_ownership WHERE ticket_id = ?
+    `).get(ticketId);
+        return row?.owner_id ?? null;
+    }
+    catch (err) {
+        // Compatibility only for isolated pre-migration schemas. Every other DB
+        // error must fail closed; treating corruption/closed handles as "legacy"
+        // would authorize a stale callback.
+        if (String(err?.message ?? err).includes('no such table: ticket_outcome_ownership')) {
+            return null;
+        }
+        throw err;
+    }
+}
+/** Release only assignments still owned by `ownerId`. `allowUnowned` exists
+ * solely for pre-migration live/recovery rows; new launches always claim and
+ * therefore fail closed when another generation has taken ownership. */
+function releaseRailTicketsOwnedBy(db, ownerId, ticketIds, opts) {
+    const wanted = new Set(ticketIds);
+    if (wanted.size === 0)
+        return [];
+    const rails = opts?.railIndex == null ? getRails(db) : [getRail(db, opts.railIndex)];
+    const released = [];
+    db.transaction(() => {
+        for (const rail of rails) {
+            const removed = [];
+            for (const ticketId of rail.ticketIds) {
+                if (!wanted.has(ticketId))
+                    continue;
+                const claim = db.prepare(`
+          SELECT owner_id FROM rail_ticket_ownership
+           WHERE rail_index = ? AND ticket_id = ?
+        `).get(rail.railIndex, ticketId);
+                if (claim?.owner_id === ownerId || (!claim && opts?.allowUnowned === true)) {
+                    removed.push(ticketId);
+                }
+            }
+            if (removed.length === 0)
+                continue;
+            const remaining = rail.ticketIds.filter((id) => !removed.includes(id));
+            const next = setRailTickets(db, rail.railIndex, remaining, rail.mode, rail.profileName, rail.aiEngine);
+            db.prepare(`
+        DELETE FROM rail_ticket_ownership
+         WHERE rail_index = ? AND owner_id = ?
+           AND ticket_id IN (${removed.map(() => '?').join(', ')})
+      `).run(rail.railIndex, ownerId, ...removed);
+            released.push({ rail: { ...next, name: rail.name }, releasedTicketIds: removed });
+        }
+    })();
+    return released;
+}
 /**
  * Update only the profile for a rail, preserving tickets and mode.
  * No-op (returns current state) when the rail has no tickets yet — the
@@ -167,14 +269,15 @@ function createRail(db, name) {
     return { railIndex, ticketIds: [], mode: 'implement', profileName: null, aiEngine: null, name: value };
 }
 /**
- * Delete a rail's identity + ticket rows. Pure mechanism — the router enforces
- * the guards (rail exists, empty, idle, no pending PR decision, not the last
- * rail). Deleting a middle rail leaves a sparse index gap on purpose: indices
+ * Delete a rail's identity + ticket assignments atomically. Pure mechanism —
+ * the router enforces the guards (rail exists, idle, no pending PR decision,
+ * not the last rail) before calling it. Deleting a middle rail leaves a sparse index gap on purpose: indices
  * are IDENTITY (metrics / pr-deliveries / worktree maps key by railIndex), so
  * they are never compacted/re-numbered.
  */
 function deleteRail(db, railIndex) {
     db.transaction(() => {
+        db.prepare('DELETE FROM rail_ticket_ownership WHERE rail_index = ?').run(railIndex);
         db.prepare('DELETE FROM rail_meta WHERE rail_index = ?').run(railIndex);
         db.prepare('DELETE FROM rails WHERE rail_index = ?').run(railIndex);
     })();