specrails-desktop 2.26.1 → 2.27.0

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

@@ -82,6 +82,7 @@ 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 rail_worktree_release_1 = require("./rail-worktree-release");
 /**
  * Ticket data for the conventional branch name (pr-naming): title/labels from
  * the ticket-spec reader, the Jira key resolved with the authoritative
@@ -496,16 +497,33 @@ async function launchIsolatedRail(input, io = {}) {
             // Build-settle: persist the per-unit branch outcomes + this launch's
             // worktree ledger ids on the row (the deferred create-pr / discard actions
             // reconstruct their inputs from these — nothing survives in memory), then
-            // hand the decision to the user. 0 succeeded units → nothing deliverable
-            // → auto-close (per-run settle already reverted the tickets).
+            // hand the decision to the user. 0 succeeded units → nothing deliverable;
+            // 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 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') {
+                    continuationPushFailed = true;
+                    continuationPushFailureReason = pushed.reason;
+                    console.warn(`[rail-isolated] existing PR follow-up push failed for ${settledContinuation.branch}: ${continuationPushFailureReason}`);
+                }
+            }
             const next = anySucceeded
                 ? (settledContinuation
-                    ? (settledContinuation.isDraft === false ? 'pr_ready' : 'pr_draft')
+                    ? (continuationPushFailed
+                        ? 'pr_failed'
+                        : (settledContinuation.isDraft === false ? 'pr_ready' : 'pr_draft'))
                     : 'on_review')
-                : 'discarded';
+                : 'implementation_failed';
             const patch = settledContinuation
                 ? {
                     branches,
@@ -513,17 +531,20 @@ async function launchIsolatedRail(input, io = {}) {
                     branch: settledContinuation.branch,
                     prUrl: settledContinuation.prUrl,
                     prNumber: settledContinuation.prNumber,
-                    prState: 'pr-created',
+                    prState: continuationPushFailed ? 'local-only' : 'pr-created',
                 }
                 : { branches, worktreeIds };
             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 });
+                }
                 broadcastPrState();
                 // Completion driver: refresh the origin conversation's card in place —
                 // on_review asks the question, discarded informs the outcome.
                 syncOriginCard('update');
             }
             if (!anySucceeded) {
-                // AUTO-DISCARD CLEANUP (0 succeeded): unmount every worktree NOW rather
+                // 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

package/server/dist/rail-pr-decision.js

@@ -67,7 +67,9 @@ exports.executePrDecision = executePrDecision;
 const path = __importStar(require("path"));
 const artifact_registry_1 = require("./artifact-registry");
 const worktree_manager_1 = require("./worktree-manager");
+const pr_publisher_1 = require("./pr-publisher");
 const rail_pr_delivery_1 = require("./rail-pr-delivery");
+const rail_worktree_release_1 = require("./rail-worktree-release");
 const pr_naming_1 = require("./pr-naming");
 const pr_body_1 = require("./pr-body");
 const jira_db_1 = require("./jira/jira-db");
@@ -105,7 +107,8 @@ function actionAllowed(action, row) {
             return row.decision === 'pr_draft' && row.pr_url !== null;
         case 'discard':
             return row.decision === 'on_review' || row.decision === 'pr_draft' ||
-                row.decision === 'pr_ready' || row.decision === 'pr_failed';
+                row.decision === 'pr_ready' || row.decision === 'implementation_failed' ||
+                row.decision === 'pr_failed';
         case 'poll-merge':
             return (row.decision === 'pr_draft' || row.decision === 'pr_ready') && row.pr_url !== null;
         case 'merge-local':
@@ -171,6 +174,46 @@ function batchWorktreeRoot(slug) {
     // Mirrors rail-isolated-launch's worktreesRoot — derivable, never stored.
     return path.join((0, artifact_registry_1.resolveHome)(), '.specrails', 'projects', slug, 'worktrees');
 }
+async function resolveExistingPrDecisionAfterPush(deps, row) {
+    if (!row.pr_url)
+        return 'pr_ready';
+    const r = await deps.exec.run('gh', ['pr', 'view', row.pr_url, '--json', 'isDraft,state'], deps.project.path);
+    if (r.code !== 0)
+        return 'pr_ready';
+    try {
+        const parsed = JSON.parse(r.stdout);
+        if (parsed.isDraft === true)
+            return 'pr_draft';
+    }
+    catch {
+        /* fall through to the conservative published/open state */
+    }
+    return 'pr_ready';
+}
+async function retryExistingPrFollowupPush(deps, row) {
+    if (!row.branch || !row.pr_url)
+        return { status: 502, body: { error: 'push_failed', detail: 'missing PR branch/url' } };
+    const pushed = await (0, pr_publisher_1.pushBranch)(deps.exec, {
+        repoDir: deps.project.path,
+        branch: row.branch,
+        baseBranch: row.base_branch,
+    });
+    if (pushed.state === 'local-only') {
+        const conflict = casTransition(deps, row, 'pr_failed', { prState: 'local-only' });
+        if (conflict)
+            return conflict;
+        finalizeTransition(deps, row.id);
+        return { status: 200, body: { ok: true, decision: 'pr_failed', prUrl: row.pr_url, detail: pushed.reason } };
+    }
+    const next = await resolveExistingPrDecisionAfterPush(deps, row);
+    const snap = (0, rail_pr_store_1.toPrDeliverySnapshot)(row);
+    const conflict = casTransition(deps, row, next, { prState: 'pr-created' });
+    if (conflict)
+        return conflict;
+    await (0, rail_worktree_release_1.releaseRailWorktrees)({ db: deps.db, git: deps.git, repoDir: deps.project.path, worktreeIds: snap.worktreeIds });
+    const after = finalizeTransition(deps, row.id);
+    return { status: 200, body: { ok: true, decision: next, prUrl: after?.prUrl ?? row.pr_url, prState: 'pr-created' } };
+}
 /**
  * Load the PR's ticket data (title/labels/description) from the ticket store,
  * with the Jira key resolved PER TICKET: the authoritative `jira_links` row
@@ -240,6 +283,9 @@ async function findRecoverableBranch(deps, unit, baseBranch) {
     return null;
 }
 async function runCreatePr(deps, row) {
+    if (row.decision === 'pr_failed' && row.pr_url && row.branch) {
+        return retryExistingPrFollowupPush(deps, row);
+    }
     const snap = (0, rail_pr_store_1.toPrDeliverySnapshot)(row);
     // Pre-flight: every succeeded unit branch must actually exist before we push
     // it — a missing ref can only degrade to local-only again, so a retry on a
@@ -363,6 +409,9 @@ async function runCreatePr(deps, row) {
     const conflict = casTransition(deps, row, next, patch);
     if (conflict)
         return conflict;
+    if (next === 'pr_draft' && patch.prUrl) {
+        await (0, rail_worktree_release_1.releaseRailWorktrees)({ db: deps.db, git: deps.git, repoDir: deps.project.path, worktreeIds: snap.worktreeIds });
+    }
     const after = finalizeTransition(deps, row.id);
     // Tickets stay on_review — a draft PR is still awaiting the engineer's merge.
     return {
@@ -380,17 +429,25 @@ async function runPublish(deps, row) {
     const r = await deps.exec.run('gh', ['pr', 'ready', row.pr_url], deps.project.path);
     if (r.code !== 0)
         return ghFailed(r); // no transition — the draft is still a draft
+    const snap = (0, rail_pr_store_1.toPrDeliverySnapshot)(row);
     const conflict = casTransition(deps, row, 'pr_ready');
     if (conflict)
         return conflict;
+    await (0, rail_worktree_release_1.releaseRailWorktrees)({ db: deps.db, git: deps.git, repoDir: deps.project.path, worktreeIds: snap.worktreeIds });
     finalizeTransition(deps, row.id);
     return { status: 200, body: { ok: true, decision: 'pr_ready', prUrl: row.pr_url } };
 }
 async function runDiscard(deps, row) {
     const snap = (0, rail_pr_store_1.toPrDeliverySnapshot)(row);
+    const implementationFailed = row.decision === 'implementation_failed';
     // 1. Close the PR (drops its head branch) when one exists. Best-effort — a
     //    gh failure must never leave the discard half-done.
-    if (row.pr_url) {
+    //
+    // Implementation-failed rows are different: the implement run produced no
+    // deliverable update. If the row belongs to an existing-PR continuation it may
+    // still carry that PR's url/branch from launch time; clearing the failed card
+    // must not close or delete the user's existing review branch.
+    if (row.pr_url && !implementationFailed) {
         try {
             const r = await deps.exec.run('gh', ['pr', 'close', row.pr_url, '--delete-branch'], deps.project.path);
             if (r.code !== 0) {
@@ -404,12 +461,13 @@ async function runDiscard(deps, row) {
     // 2. Remove the launch's worktrees (still on disk unless a restart already
     //    swept them) and close their ledger rows — the reconcile-style removal,
     //    branch deletion deferred to step 3 (a checked-out branch can't be -D'd).
-    const branchSet = new Set(snap.branches.map((b) => b.branch));
+    const branchSet = new Set(implementationFailed ? [] : snap.branches.map((b) => b.branch));
     for (const wtId of snap.worktreeIds) {
         const wt = (0, rail_worktrees_store_1.getRailWorktree)(deps.db, wtId);
         if (!wt)
             continue;
-        branchSet.add(wt.branch);
+        if (!implementationFailed)
+            branchSet.add(wt.branch);
         await (0, worktree_manager_1.removeWorktree)(deps.git, {
             repoDir: deps.project.path, worktreePath: wt.worktree_path, branch: wt.branch, deleteBranch: false,
         }).catch(() => { });
@@ -421,22 +479,24 @@ async function runDiscard(deps, row) {
     //    best-effort from the same ticket data the create-pr path names it from
     //    (the delivered head is already covered by row.branch). Missing branches
     //    are tolerated; the integration branch is NEVER deleted.
-    if (row.branch)
-        branchSet.add(row.branch);
-    const succeededUnits = snap.branches.filter((b) => b.succeeded);
-    if (succeededUnits.length > 1) {
-        try {
-            branchSet.add((0, pr_naming_1.batchBranchNameFor)(loadPrTicketData(deps, succeededUnits.map((b) => b.ticketId))));
+    if (!implementationFailed) {
+        if (row.branch)
+            branchSet.add(row.branch);
+        const succeededUnits = snap.branches.filter((b) => b.succeeded);
+        if (succeededUnits.length > 1) {
+            try {
+                branchSet.add((0, pr_naming_1.batchBranchNameFor)(loadPrTicketData(deps, succeededUnits.map((b) => b.ticketId))));
+            }
+            catch {
+                /* best-effort defense-in-depth only */
+            }
         }
-        catch {
-            /* best-effort defense-in-depth only */
+        for (const branch of branchSet) {
+            if (!branch || branch === row.base_branch)
+                continue;
+            await deps.git.run(['branch', '-D', branch], deps.project.path).catch(() => { });
         }
     }
-    for (const branch of branchSet) {
-        if (!branch || branch === row.base_branch)
-            continue;
-        await deps.git.run(['branch', '-D', branch], deps.project.path).catch(() => { });
-    }
     const conflict = casTransition(deps, row, 'discarded');
     if (conflict)
         return conflict;
@@ -467,11 +527,29 @@ async function runPollMerge(deps, row) {
         // Not merged (OPEN/CLOSED/unknown) → observation only, nothing changes.
         return { status: 200, body: { ok: true, decision: row.decision, merged: false } };
     }
+    const snap = (0, rail_pr_store_1.toPrDeliverySnapshot)(row);
+    const branchSet = new Set(snap.branches.map((b) => b.branch));
+    if (row.branch)
+        branchSet.add(row.branch);
+    const succeededUnits = snap.branches.filter((b) => b.succeeded);
+    if (succeededUnits.length > 1) {
+        try {
+            branchSet.add((0, pr_naming_1.batchBranchNameFor)(loadPrTicketData(deps, succeededUnits.map((b) => b.ticketId))));
+        }
+        catch {
+            /* best-effort cleanup only */
+        }
+    }
+    await (0, rail_worktree_release_1.releaseRailWorktrees)({ db: deps.db, git: deps.git, repoDir: deps.project.path, worktreeIds: snap.worktreeIds, state: 'merged' });
+    for (const branch of branchSet) {
+        if (!branch || branch === row.base_branch)
+            continue;
+        await deps.git.run(['branch', '-D', branch], deps.project.path).catch(() => { });
+    }
     const conflict = casTransition(deps, row, 'merged');
     if (conflict)
         return conflict;
     finalizeTransition(deps, row.id);
-    const snap = (0, rail_pr_store_1.toPrDeliverySnapshot)(row);
     const changed = applyTicketTransition(deps, snap.ticketIds, 'done');
     try {
         deps.jiraSyncManager?.onRailMerged(changed, row.id, row.pr_url);

package/server/dist/rail-pr-store.js

@@ -6,6 +6,7 @@ exports.createPrDelivery = createPrDelivery;
 exports.getPrDelivery = getPrDelivery;
 exports.getActivePrDeliveryByRail = getActivePrDeliveryByRail;
 exports.listActivePrDeliveries = listActivePrDeliveries;
+exports.reconcileFailedBuildingPrDeliveries = reconcileFailedBuildingPrDeliveries;
 exports.transitionDecision = transitionDecision;
 exports.toPrDeliverySnapshot = toPrDeliverySnapshot;
 exports.toRailPrStateMessage = toRailPrStateMessage;
@@ -19,6 +20,7 @@ exports.ACTIVE_PR_DECISIONS = new Set([
     'on_review',
     'pr_draft',
     'pr_ready',
+    'implementation_failed',
     'pr_failed',
 ]);
 function isTerminalPrDecision(s) {
@@ -60,6 +62,40 @@ function listActivePrDeliveries(db) {
        ORDER BY rail_index, created_at DESC, rowid DESC`)
         .all();
 }
+/**
+ * Recover implementation cards stranded at `building` after the loop process
+ * already settled all associated run ids without a success. This covers server
+ * restarts and the settle gap where loop_runs/worktrees mark failure but the
+ * PR-delivery row never receives its final card state.
+ */
+function reconcileFailedBuildingPrDeliveries(db) {
+    const rows = db
+        .prepare(`SELECT * FROM rail_pr_deliveries WHERE decision = 'building' ORDER BY created_at ASC, rowid ASC`)
+        .all();
+    const reconciled = [];
+    for (const row of rows) {
+        const runIds = parseJsonArray(row.run_ids ?? '[]');
+        if (runIds.length === 0)
+            continue;
+        const uniqueRunIds = [...new Set(runIds)];
+        const placeholders = uniqueRunIds.map(() => '?').join(',');
+        const runs = db
+            .prepare(`SELECT id, status, final_outcome FROM loop_runs WHERE id IN (${placeholders})`)
+            .all(...uniqueRunIds);
+        if (runs.length !== uniqueRunIds.length)
+            continue;
+        if (runs.some((run) => run.status !== 'completed'))
+            continue;
+        if (runs.some((run) => run.final_outcome === 'success'))
+            continue;
+        if (transitionDecision(db, row.id, 'building', 'implementation_failed')) {
+            const updated = getPrDelivery(db, row.id);
+            if (updated)
+                reconciled.push(updated);
+        }
+    }
+    return reconciled;
+}
 // Column allow-list — patch keys are interpolated into the SET clause, so gate
 // them to prevent any future caller injecting SQL via an object key (values
 // are always parameterized). Mirrors loop-runs-store's COUNTER_COLUMNS.

package/server/dist/rail-worktree-release.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.releaseRailWorktrees = releaseRailWorktrees;
+const rail_worktrees_store_1 = require("./rail-worktrees-store");
+const worktree_manager_1 = require("./worktree-manager");
+/** Remove Specrails-managed linked worktrees while keeping their local branches.
+ *  PR deliveries use this once the work has a durable remote branch/PR: the
+ *  branch remains available for local checkout, but the internal worktree stops
+ *  blocking `git switch <branch>` in the user's main checkout. */
+async function releaseRailWorktrees(input) {
+    const state = input.state ?? 'released';
+    for (const wtId of input.worktreeIds) {
+        const wt = (0, rail_worktrees_store_1.getRailWorktree)(input.db, wtId);
+        if (!wt)
+            continue;
+        await (0, worktree_manager_1.removeWorktree)(input.git, {
+            repoDir: input.repoDir,
+            worktreePath: wt.worktree_path,
+            branch: wt.branch,
+            deleteBranch: false,
+        }).catch(() => { });
+        if (!(0, rail_worktrees_store_1.isTerminalMergeState)(wt.merge_state))
+            (0, rail_worktrees_store_1.updateRailWorktreeState)(input.db, wt.id, state);
+    }
+}

package/server/dist/rail-worktrees-store.js

@@ -12,7 +12,7 @@ exports.deleteRailWorktree = deleteRailWorktree;
 exports.listRailWorktreesForTicket = listRailWorktreesForTicket;
 exports.railWorktreeBranchExistsForTicket = railWorktreeBranchExistsForTicket;
 /** States after which the worktree is done (eligible for cleanup/reconciliation). */
-exports.TERMINAL_MERGE_STATES = new Set(['merged', 'needs-review', 'failed']);
+exports.TERMINAL_MERGE_STATES = new Set(['merged', 'needs-review', 'failed', 'released']);
 function isTerminalMergeState(s) {
     return exports.TERMINAL_MERGE_STATES.has(s);
 }
@@ -46,7 +46,7 @@ function listRailWorktrees(db, railIndex) {
  *  process (mark failed + sweep). */
 function listNonTerminalRailWorktrees(db) {
     return db
-        .prepare(`SELECT * FROM rail_worktrees WHERE merge_state NOT IN ('merged','needs-review','failed') ORDER BY rail_index, ticket_id`)
+        .prepare(`SELECT * FROM rail_worktrees WHERE merge_state NOT IN ('merged','needs-review','failed','released') ORDER BY rail_index, ticket_id`)
         .all();
 }
 function deleteRailWorktree(db, id) {

package/server/dist/rails-router.js

@@ -23,6 +23,8 @@ const loop_effect_1 = require("./loop-effect");
 const rail_pr_decision_1 = require("./rail-pr-decision");
 const rail_isolated_launch_1 = require("./rail-isolated-launch");
 const worktree_manager_1 = require("./worktree-manager");
+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 agent_chat_registry_1 = require("./agent-chat-registry");
@@ -36,7 +38,7 @@ 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)
+    if (!delivery.prUrl || !delivery.branch || delivery.prState !== 'pr-created')
         return false;
     const covered = new Set(delivery.ticketIds);
     return ticketIds.length > 0 && ticketIds.every((id) => covered.has(id));
@@ -51,6 +53,11 @@ 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) {
@@ -114,6 +121,7 @@ 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))
@@ -674,15 +682,43 @@ function createRailsRouter() {
                         if ((0, rail_pr_store_1.transitionDecision)(c.db, fallbackPrDeliveryId, 'building', 'building', { runIds: loopRunIds })) {
                             emitPrDeliveryUpdate(c, fallbackPrDeliveryId);
                         }
-                        void Promise.allSettled(sharedRunSettles).then(() => {
-                            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) {
-                                if ((0, rail_pr_store_1.transitionDecision)(c.db, fallbackPrDeliveryId, 'building', 'pr_ready')) {
-                                    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;
+                                    }
+                                    await (0, worktree_manager_1.commitWorktree)(worktree_manager_1.defaultGitRunner, c.project.path, `specrails: PR follow-up (${loopRunIds.join(', ')})`);
+                                    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);
+                                    }
+                                }
+                            });
                         });
                     }
                 }
@@ -883,5 +919,55 @@ function createRailsRouter() {
             res.status(500).json({ error: 'pr-decision failed', detail: err.message });
         }
     });
+    // POST /rails/pr-checkout — move the user's main checkout to the delivered PR
+    // branch. This is intentionally separate from PR decisions: it does not accept,
+    // publish, discard, or merge anything. It only releases Specrails-managed
+    // worktrees for this delivery (keeping branches) and then checks out the PR
+    // branch in the real project repo so the user can test/edit locally.
+    router.post('/pr-checkout', async (req, res) => {
+        const c = ctx(req);
+        const { prDeliveryId } = req.body ?? {};
+        if (typeof prDeliveryId !== 'string' || !prDeliveryId) {
+            res.status(400).json({ error: 'prDeliveryId is required' });
+            return;
+        }
+        const row = (0, rail_pr_store_1.getPrDelivery)(c.db, prDeliveryId);
+        if (!row) {
+            res.status(404).json({ error: 'Unknown prDeliveryId' });
+            return;
+        }
+        const snap = (0, rail_pr_store_1.toPrDeliverySnapshot)(row);
+        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 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 });
+                return;
+            }
+            res.json({ ok: true, git: await (0, project_git_1.getProjectGitInfo)(c.project.path) });
+        }
+        catch (err) {
+            console.error('[rails-router] pr-checkout error:', err);
+            res.status(500).json({ error: 'pr-checkout failed', detail: err.message });
+        }
+    });
     return router;
 }