specrails-desktop 2.36.0 → 2.42.2

package/server/dist/rails-router.js

@@ -14,6 +14,7 @@ const loop_runs_store_1 = require("./loop-runs-store");
 const providers_1 = require("./providers");
 const runtime_1 = require("./providers/runtime");
 const agent_defaults_1 = require("./agent-defaults");
+const profile_manager_1 = require("./profile-manager");
 const spec_models_1 = require("./spec-models");
 const workspace_resolution_1 = require("./workspace-resolution");
 const loop_factory_1 = require("./loop-factory");
@@ -29,9 +30,15 @@ const rail_pr_decision_1 = require("./rail-pr-decision");
 const active_pr_continuation_1 = require("./active-pr-continuation");
 const rail_isolated_launch_1 = require("./rail-isolated-launch");
 const worktree_manager_1 = require("./worktree-manager");
+const integration_branch_1 = require("./integration-branch");
 const rail_worktree_release_1 = require("./rail-worktree-release");
 const project_git_1 = require("./project-git");
 const pr_publisher_1 = require("./pr-publisher");
+const project_repositories_1 = require("./project-repositories");
+const multi_repo_checkout_1 = require("./multi-repo-checkout");
+const multi_repo_bases_1 = require("./multi-repo-bases");
+const multi_repo_execution_1 = require("./multi-repo-execution");
+const multi_repo_execution_store_1 = require("./multi-repo-execution-store");
 const ids_1 = require("./ids");
 const repo_lock_1 = require("./repo-lock");
 const agent_chat_registry_1 = require("./agent-chat-registry");
@@ -40,7 +47,12 @@ const VALID_MODES = new Set(['implement', 'batch-implement', 'freestyle', 'loop'
 function prDeliveryContinuesTickets(delivery, ticketIds) {
     if (delivery.decision !== 'pr_draft' && delivery.decision !== 'pr_ready')
         return false;
-    if (!delivery.prUrl || !delivery.branch || !delivery.deliverySha || delivery.prState !== 'pr-created')
+    if (delivery.executionManifest && delivery.repositoryDeliveries?.length) {
+        const active = delivery.repositoryDeliveries.filter((repository) => !['merged', 'completed', 'no_changes'].includes(repository.decision));
+        if (!active.length || active.some((repository) => !repository.prUrl || !repository.branch || !repository.deliverySha))
+            return false;
+    }
+    else if (!delivery.prUrl || !delivery.branch || !delivery.deliverySha || delivery.prState !== 'pr-created')
         return false;
     const covered = new Set(delivery.ticketIds);
     const requested = new Set(ticketIds);
@@ -62,11 +74,30 @@ function prDeliveryRevisionAllowed(delivery, revisionOfDeliveryId, ticketIds) {
     const requested = new Set(ticketIds);
     return requested.size > 0 && requested.size === covered.size && [...requested].every((id) => covered.has(id));
 }
+function prDeliveryCheckoutTarget(delivery) {
+    if (delivery.branch && delivery.deliverySha)
+        return { branch: delivery.branch, sha: delivery.deliverySha };
+    // Before Create PR, a single settled unit already has an exact local result.
+    // A batch must first be assembled: checking out its first branch would hide
+    // the rest of the implementation.
+    const units = delivery.branches;
+    if (!delivery.branch && !delivery.deliverySha && units.length === 1 && units[0].succeeded && units[0].finalSha &&
+        units[0].deliveryOutcome !== 'blocked' && units[0].deliveryOutcome !== 'no_changes' &&
+        units[0].implementationOutcome !== 'failed' && units[0].changed !== false) {
+        return { branch: units[0].branch, sha: units[0].finalSha };
+    }
+    return null;
+}
 function prDeliveryCheckoutBlock(delivery) {
+    if ((0, rail_pr_store_1.isTerminalPrDecision)(delivery.decision) || delivery.decision === 'building' ||
+        delivery.decision === 'implementation_failed' || delivery.decision === 'no_changes') {
+        return 'delivery is not awaiting implementation review';
+    }
     if (delivery.deliveryOutcome === 'blocked') {
         return 'delivery is blocked and has no safely checkoutable result';
     }
-    if (!delivery.deliverySha) {
+    const target = prDeliveryCheckoutTarget(delivery);
+    if (!target || !/^[0-9a-f]{40,64}$/i.test(target.sha)) {
         return 'delivery has no verified commit available for checkout';
     }
     return null;
@@ -402,7 +433,7 @@ function createRailsRouter() {
             return;
         }
         let { mode = 'implement' } = req.body ?? {};
-        const { profileName, aiEngine, model, loopId: rawLoopId, reasoning_effort, originConversationId, originSurface, targetPrNumber, revisionOfDeliveryId, revisionNote } = req.body ?? {};
+        const { repositoryIds: rawRepositoryIds, baseDeliveryIds, profileName, aiEngine, model, loopId: rawLoopId, reasoning_effort, originConversationId, originSurface, targetPrNumber, revisionOfDeliveryId, revisionNote, baseBranch: rawBaseBranch } = req.body ?? {};
         // Revision launch (nontech-review-experience Wave 3): the user asked for a
         // change to a delivery that is already awaiting their decision. Shape is
         // validated here; the narrow guard exemption is enforced below.
@@ -425,6 +456,21 @@ function createRailsRouter() {
                 return;
             }
         }
+        // Explicit base branch (premium-milestone-progress): a milestone chain
+        // stacks chunk k+1 on chunk k's delivered branch. Shape-validated here;
+        // resolved locally and isolation-gated below. Never silently ignored.
+        let baseBranch = null;
+        if (rawBaseBranch !== undefined && rawBaseBranch !== null) {
+            if (typeof rawBaseBranch !== 'string' || !(0, integration_branch_1.isValidBranchName)(rawBaseBranch)) {
+                res.status(400).json({ error: 'invalid_base_branch', detail: 'baseBranch must be a valid local branch name' });
+                return;
+            }
+            baseBranch = rawBaseBranch;
+        }
+        if (baseBranch && !(0, feature_flags_1.isLoopsEnabled)()) {
+            res.status(400).json({ error: 'base_branch_requires_isolation', detail: 'baseBranch requires an isolated (worktree) loop launch; loops are disabled' });
+            return;
+        }
         let loopId = rawLoopId;
         // Origin link (safe-pr-review-flow): an agent-chat/MCP launch tags itself so
         // the PR decision can later be posted back into the launching conversation.
@@ -517,6 +563,38 @@ function createRailsRouter() {
             res.status(400).json({ error: 'Rail has no tickets assigned' });
             return;
         }
+        let repositoryIds;
+        const primaryRepository = (0, project_repositories_1.getProjectRepositories)(c.project).find((repository) => repository.isPrimary);
+        try {
+            const requiredRepositoryIds = [...new Set(rail.ticketIds.flatMap((id) => (0, project_repositories_1.validateTicketRepositoryIds)(c.project, c.getTicketSpec?.(id)?.repositoryIds) ?? [primaryRepository.id]))];
+            repositoryIds = (0, project_repositories_1.validateTicketRepositoryIds)(c.project, rawRepositoryIds) ?? requiredRepositoryIds;
+            const missing = requiredRepositoryIds.filter((id) => !repositoryIds.includes(id));
+            if (missing.length) {
+                res.status(400).json({ error: 'repository_scope_incomplete', missingRepositoryIds: missing,
+                    detail: 'The launch must include every repository required by its specs. Edit the spec scope first if its implementation targets have changed.' });
+                return;
+            }
+        }
+        catch (error) {
+            res.status(error instanceof project_repositories_1.RepositoryValidationError ? error.status : 400).json({ error: error instanceof Error ? error.message : 'Invalid repository selection' });
+            return;
+        }
+        let repositoryBases;
+        if (baseDeliveryIds !== undefined) {
+            try {
+                repositoryBases = await (0, multi_repo_bases_1.resolveRepositoryDeliveryBases)(c.db, c.project, repositoryIds, baseDeliveryIds, worktree_manager_1.defaultGitRunner);
+                baseBranch = repositoryBases.repositoryBaseBranches[primaryRepository.id] ?? baseBranch;
+            }
+            catch (error) {
+                res.status(409).json({ error: 'invalid_repository_base', detail: error instanceof Error ? error.message : String(error) });
+                return;
+            }
+        }
+        const requiresRepositoryIsolation = repositoryIds.length !== 1 || repositoryIds[0] !== primaryRepository.id;
+        if (requiresRepositoryIsolation && !(0, feature_flags_1.isLoopsEnabled)()) {
+            res.status(409).json({ error: 'repository_isolation_required' });
+            return;
+        }
         // Per-rail spec cap: a single launch may carry at most
         // MAX_TICKETS_PER_RAIL_LAUNCH specs — bigger batches must be chunked
         // across rails (the milestone launcher does this automatically).
@@ -583,7 +661,7 @@ function createRailsRouter() {
             // Freestyle runs no agent pipeline, so profiles do not apply.
             resolvedProfile = null;
         }
-        else if (railProvider && (0, providers_1.getAdapter)(railProvider).capabilities.profiles !== true) {
+        else if ((0, providers_1.getAdapter)(engineCheck.provider).capabilities.profiles !== true) {
             resolvedProfile = null;
         }
         else if (profileName === null) {
@@ -628,6 +706,11 @@ function createRailsRouter() {
                         res.status(400).json({ error: 'Loop must be published before it can run on a rail' });
                         return;
                     }
+                    const validation = (0, loop_graph_1.validateLoopGraph)(loop.graph);
+                    if (!validation.valid) {
+                        res.status(422).json({ error: 'Loop graph is invalid', errors: validation.errors });
+                        return;
+                    }
                     // A standalone loop (no {{spec.*}} and no ticket command) ignores the
                     // rail's spec — it would just re-run once per ticket. Those belong to
                     // the Loops page "Run" action; reject them here as a defence-in-depth
@@ -661,9 +744,20 @@ function createRailsRouter() {
                 // dashboard factory launches send neither. Read at launch time, so a
                 // settings change applies to the next launch without restart.
                 const globalAgentDefaults = (0, agent_defaults_1.resolveAgentDefaults)(c.desktopDb, loopProvider);
+                let profileModel;
+                if (resolvedProfile) {
+                    try {
+                        const execution = (0, workspace_resolution_1.resolveProjectExecution)({ slug: c.project.slug, path: c.project.path });
+                        profileModel = (0, profile_manager_1.resolveProfile)(execution.cwd, resolvedProfile, loopProvider)?.profile.orchestrator.model;
+                    }
+                    catch (error) {
+                        res.status(400).json({ error: 'invalid_profile', detail: error instanceof Error ? error.message : String(error) });
+                        return;
+                    }
+                }
                 const loopModel = typeof model === 'string' && model
                     ? model
-                    : (globalAgentDefaults?.pipelineModel ?? loopAdapter.defaultModel());
+                    : (profileModel ?? globalAgentDefaults?.pipelineModel ?? loopAdapter.defaultModel());
                 let effort;
                 if (reasoning_effort !== undefined && reasoning_effort !== null) {
                     const allowed = (0, providers_1.reasoningEffortsForModel)(loopAdapter, loopModel);
@@ -693,14 +787,10 @@ function createRailsRouter() {
                 const scope = (0, loop_command_catalog_1.dominantTicketScope)(promptsText);
                 // Parallel isolation (default-on; disable with SPECRAILS_RAIL_WORKTREES=0):
                 // a per-ticket rail on a repo-mutating loop runs each ticket in its own git
-                // worktree, then merges the branches back. Degrades gracefully — a non-git
-                // repo, an unborn HEAD, or a worktree-allocation failure all fall through to
-                // the shared-cwd path below. See rail-isolation.ts.
+                // worktree, then merges the branches back. A non-git repo or an unborn
+                // HEAD uses the explicit shared-cwd fallback; an operational allocation
+                // failure aborts rather than moving execution into the active checkout.
                 let isolationUnavailable;
-                // Human-readable failure detail for the 'error' case — surfaced to the
-                // client so a silent fallback (no delivery row → no implementation
-                // cards) is diagnosable from the UI, not just the server log.
-                let isolationUnavailableDetail;
                 let continuablePrDelivery = null;
                 let revisionRequest = null;
                 // Read-only vs mutating is DERIVED from the loop's nodes (see loop-effect),
@@ -747,15 +837,30 @@ function createRailsRouter() {
                         res.status(409).json({ error: 'pr_decision_pending', prDeliveryId: pendingSnapshot.id });
                         return;
                     }
+                    if (pendingSnapshot?.executionManifest) {
+                        const previousIds = pendingSnapshot.executionManifest.selectedRepositoryIds;
+                        if (previousIds.length !== repositoryIds.length || previousIds.some((id) => !repositoryIds.includes(id))) {
+                            res.status(409).json({ error: 'delivery_repository_scope_changed', detail: 'A follow-up must retain the delivered repository scope.' });
+                            return;
+                        }
+                    }
                     continuablePrDelivery = pendingSnapshot;
                 }
                 const useIsolation = (0, rail_isolation_1.isolationApplies)({
                     loopsEnabled: (0, feature_flags_1.isLoopsEnabled)(), scope, ticketCount: rail.ticketIds.length, readOnly: loopReadOnly,
                 });
+                if (requiresRepositoryIsolation && !useIsolation) {
+                    res.status(409).json({ error: 'repository_isolation_required', detail: 'Selected repositories require worktree isolation for this loop.' });
+                    return;
+                }
                 if (typeof targetPrNumber === 'number' && !useIsolation) {
                     res.status(400).json({ error: 'target_pr_requires_pr_mode', detail: 'targetPrNumber requires an isolated (worktree) launch; this launch would run in the shared checkout' });
                     return;
                 }
+                if (baseBranch && !useIsolation) {
+                    res.status(400).json({ error: 'base_branch_requires_isolation', detail: 'baseBranch requires an isolated (worktree) launch; this launch would run in the shared checkout' });
+                    return;
+                }
                 if (continuablePrDelivery && !loopReadOnly && !useIsolation) {
                     res.status(409).json({
                         error: 'pr_continuation_isolation_required',
@@ -767,8 +872,12 @@ function createRailsRouter() {
                 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);
+                    const status = requiresRepositoryIsolation ? 'ok' : await (0, worktree_manager_1.repoIsolationStatus)(worktree_manager_1.defaultGitRunner, c.project.path);
                     if (status !== 'ok') {
+                        if (baseBranch) {
+                            res.status(400).json({ error: 'base_branch_requires_isolation', detail: `baseBranch requires worktree isolation, which is unavailable (${status})` });
+                            return;
+                        }
                         if (typeof targetPrNumber === 'number') {
                             res.status(400).json({
                                 error: 'target_pr_requires_pr_mode',
@@ -788,13 +897,24 @@ function createRailsRouter() {
                         console.warn(`[rails-router] worktree isolation unavailable (${status}); running shared cwd`);
                     }
                     else {
+                        if (baseBranch) {
+                            // Must resolve as a LOCAL branch — a chain never stacks on a guess.
+                            const verify = await worktree_manager_1.defaultGitRunner.run(['rev-parse', '--verify', '--quiet', `refs/heads/${baseBranch}`], c.project.path);
+                            if (verify.code !== 0) {
+                                res.status(400).json({ error: 'invalid_base_branch', detail: `branch ${baseBranch} does not resolve locally` });
+                                return;
+                            }
+                        }
                         try {
                             const ids = await (0, rail_isolated_launch_1.launchIsolatedRail)({
-                                ctx: c, railIndex, ticketIds: [...rail.ticketIds], loopId, loopName, loopGraph,
+                                ctx: c, railIndex, ticketIds: [...rail.ticketIds], repositoryIds, ...repositoryBases, loopId, loopName, loopGraph,
                                 provider: loopProvider, model: loopModel, effort, scope,
+                                profileName: resolvedProfile,
                                 originSurface: originSurface ?? 'dashboard',
                                 originConversationId: originConversationId ?? null,
-                                ...(continuablePrDelivery ? {
+                                ...(baseBranch ? { baseBranch } : {}),
+                                ...(continuablePrDelivery?.executionManifest && !revisionRequest ? { repositoryContinuation: { deliveryId: continuablePrDelivery.id, decision: continuablePrDelivery.decision } } : {}),
+                                ...(continuablePrDelivery && !continuablePrDelivery.executionManifest ? {
                                     requiredPrContinuation: {
                                         deliveryId: continuablePrDelivery.id,
                                         decision: continuablePrDelivery.decision,
@@ -845,9 +965,13 @@ function createRailsRouter() {
                                 });
                                 return;
                             }
-                            console.error('[rails-router] isolated launch failed; falling back to shared cwd:', err);
-                            isolationUnavailable = 'error';
-                            isolationUnavailableDetail = err instanceof Error ? err.message : String(err);
+                            console.error('[rails-router] isolated launch failed:', err);
+                            res.status(409).json({
+                                error: 'isolation_failed',
+                                detail: err instanceof Error ? err.message : String(err),
+                                action: 'Resolve the worktree allocation error and retry the rail launch.',
+                            });
+                            return;
                         }
                     }
                 }
@@ -900,16 +1024,26 @@ function createRailsRouter() {
                         repoDir: loopExec.relocated ? loopExec.repoDir : undefined,
                         railIndex,
                         ticketId: ticketIds[0],
-                        spec: spec ? { ...spec, ticketIds } : { ticketIds },
+                        spec: {
+                            ...spec,
+                            ticketIds,
+                            ...(ticketIds.length > 1 ? {
+                                tickets: ticketIds.map((id) => {
+                                    const ticket = c.getTicketSpec(id);
+                                    return { id, title: ticket?.title, description: ticket?.description };
+                                }),
+                            } : {}),
+                        },
                         ticketCompletionStatus: loopTicketCompletionStatus,
                         constants: (0, loop_constants_1.loadConstantMap)(c.desktopDb),
                         provider: loopProvider,
                         model: loopModel,
                         effort,
+                        profileName: resolvedProfile,
                     })
                         .then((r) => {
                         recordRunProvenance();
-                        c.onLoopRunFinished(r.runId, r.outcome);
+                        c.onLoopRunFinished(r.runId, r.outcome, r.stallReason ? { stallReason: r.stallReason } : undefined);
                         return r.outcome === 'success';
                     })
                         .catch((err) => {
@@ -939,7 +1073,6 @@ function createRailsRouter() {
                 res.status(202).json({
                     loopRunIds, railIndex, mode,
                     ...(isolationUnavailable ? { isolationUnavailable } : {}),
-                    ...(isolationUnavailableDetail ? { isolationUnavailableDetail } : {}),
                 });
                 return;
             }
@@ -1103,17 +1236,40 @@ function createRailsRouter() {
             return;
         }
         const c = ctx(req);
-        const row = (0, rail_pr_store_1.getPrDelivery)(c.db, req.params.prDeliveryId);
+        let row = (0, rail_pr_store_1.getPrDelivery)(c.db, req.params.prDeliveryId);
         if (!row) {
             res.status(404).json({ error: 'Delivery not found' });
             return;
         }
         try {
-            const packet = (0, review_packet_1.composeReviewPacket)({ db: c.db, row });
+            const parent = row.parent_delivery_id ? (0, rail_pr_store_1.getPrDelivery)(c.db, row.parent_delivery_id) : row;
+            if (!parent) {
+                res.status(404).json({ error: 'Delivery group not found' });
+                return;
+            }
+            const repositoryId = req.query.repositoryId;
+            if (repositoryId !== undefined && (typeof repositoryId !== 'string' || !repositoryId)) {
+                res.status(400).json({ error: 'Invalid repositoryId' });
+                return;
+            }
+            if (repositoryId) {
+                row = (0, multi_repo_execution_1.listRepositoryDeliveries)(c.db, parent.id).find((child) => child.repository_id === repositoryId);
+                if (!row) {
+                    res.status(404).json({ error: 'Repository not in this delivery' });
+                    return;
+                }
+            }
+            const manifest = (0, multi_repo_execution_store_1.readExecutionManifest)(parent.execution_manifest);
+            const frozenRepository = row.repository_id ? manifest?.repositories.find((repository) => repository.repositoryId === row.repository_id && repository.sourcePath === row.repository_path) : undefined;
+            if (row.parent_delivery_id && !frozenRepository) {
+                res.status(409).json({ error: 'Repository delivery has no frozen source path' });
+                return;
+            }
+            const packet = (0, review_packet_1.composeReviewPacket)({ db: c.db, row, ...(frozenRepository ? { repositoryId: frozenRepository.repositoryId, includeLegacyProvenance: frozenRepository.repositoryId === manifest?.primaryRepositoryId } : {}) });
             // Capability probes are read-only and offline; a failure degrades to the
             // confirm-gated local path rather than blocking the packet.
-            const acceptCapability = await (0, accept_ladder_1.resolveAcceptCapability)({ repoDir: c.project.path, exec: pr_publisher_1.defaultExec });
-            res.json({ packet, acceptCapability, snapshot: (0, rail_pr_store_1.toPrDeliverySnapshot)(row) });
+            const acceptCapability = await (0, accept_ladder_1.resolveAcceptCapability)({ repoDir: frozenRepository?.sourcePath ?? c.project.path, exec: pr_publisher_1.defaultExec });
+            res.json({ packet, acceptCapability, snapshot: (0, rail_pr_store_1.toPrDeliverySnapshot)(parent), repositoryId: frozenRepository?.repositoryId ?? null });
         }
         catch (err) {
             console.error('[rails-router] packet composition failed:', err);
@@ -1130,7 +1286,11 @@ function createRailsRouter() {
     // specrails never merges — the engineer owns the merge.
     router.post('/pr-decision', async (req, res) => {
         const c = ctx(req);
-        const { prDeliveryId, action, expectedDecision } = req.body ?? {};
+        const { prDeliveryId, action, expectedDecision, repositoryId } = req.body ?? {};
+        if (repositoryId !== undefined && (typeof repositoryId !== 'string' || !repositoryId)) {
+            res.status(400).json({ error: 'repositoryId must be a nonempty string' });
+            return;
+        }
         if (typeof prDeliveryId !== 'string' || !prDeliveryId) {
             res.status(400).json({ error: 'prDeliveryId is required' });
             return;
@@ -1144,6 +1304,11 @@ function createRailsRouter() {
             return;
         }
         try {
+            const targetDelivery = (0, rail_pr_store_1.getPrDelivery)(c.db, prDeliveryId);
+            if (repositoryId && targetDelivery && !targetDelivery.execution_manifest && !(0, project_repositories_1.resolveProjectRepository)(c.project, repositoryId).isPrimary) {
+                res.status(400).json({ error: 'Repository is not part of this delivery' });
+                return;
+            }
             const admission = (0, process_admission_1.captureProcessAdmission)(c.project.id);
             const execute = () => {
                 admission.assertCurrent();
@@ -1155,13 +1320,13 @@ function createRailsRouter() {
                     broadcast: c.broadcast,
                     jiraSyncManager: c.jiraSyncManager,
                     assertAdmission: () => admission.assertCurrent(),
-                }, { prDeliveryId, action, expectedDecision });
+                }, { prDeliveryId, action, expectedDecision, repositoryId });
             };
             // 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'
+            const result = action === 'merge-local' || !!(0, rail_pr_store_1.getPrDelivery)(c.db, prDeliveryId)?.execution_manifest
                 ? await execute()
                 : await (0, repo_lock_1.withRepoLock)(c.project.path, execute);
             // The durable row is authoritative. Return its post-action snapshot even
@@ -1178,6 +1343,10 @@ function createRailsRouter() {
                 res.status(409).json({ error: 'project_recovery_in_progress' });
                 return;
             }
+            if (err instanceof project_repositories_1.RepositoryValidationError) {
+                res.status(err.status).json({ error: err.message });
+                return;
+            }
             console.error('[rails-router] pr-decision error:', err);
             res.status(500).json({ error: 'pr-decision failed', detail: err.message });
         }
@@ -1210,6 +1379,18 @@ function createRailsRouter() {
             res.status(404).json({ error: 'Unknown prDeliveryId' });
             return;
         }
+        if (!row.execution_manifest && req.body?.repositoryId !== undefined) {
+            try {
+                if (typeof req.body.repositoryId !== 'string' || !(0, project_repositories_1.resolveProjectRepository)(c.project, req.body.repositoryId).isPrimary) {
+                    res.status(400).json({ error: 'Repository is not part of this delivery' });
+                    return;
+                }
+            }
+            catch (error) {
+                res.status(400).json({ error: error instanceof Error ? error.message : 'Invalid repositoryId' });
+                return;
+            }
+        }
         const active = (0, rail_pr_store_1.getActivePrDeliveryByRail)(c.db, row.rail_index);
         if (!active || active.id !== row.id) {
             res.status(409).json({
@@ -1219,16 +1400,34 @@ function createRailsRouter() {
             });
             return;
         }
+        if (row.execution_manifest) {
+            const repositoryId = req.body?.repositoryId;
+            if (repositoryId !== undefined && (typeof repositoryId !== 'string' || !repositoryId)) {
+                res.status(400).json({ error: 'repositoryId must be a nonempty string' });
+                return;
+            }
+            try {
+                const outcome = await (0, multi_repo_checkout_1.checkoutRepositoryDelivery)({
+                    db: c.db, project: c.project, git: worktree_manager_1.defaultGitRunner, exec: pr_publisher_1.defaultExec,
+                    broadcast: c.broadcast, jiraSyncManager: c.jiraSyncManager,
+                    assertAdmission: () => admission.assertCurrent(),
+                }, { prDeliveryId, repositoryId });
+                res.status(outcome.status).json(outcome.body);
+            }
+            catch (error) {
+                res.status(error instanceof process_admission_1.ProcessAdmissionClosedError ? 409 : 500).json({
+                    error: error instanceof process_admission_1.ProcessAdmissionClosedError ? 'project_recovery_in_progress' : 'pr-checkout failed',
+                    detail: error instanceof Error ? error.message : String(error),
+                });
+            }
+            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 outcome = await (0, repo_lock_1.withRepoLock)(c.project.path, async () => {
                 admission.assertCurrent();
@@ -1251,12 +1450,13 @@ function createRailsRouter() {
                         detail: currentCheckoutBlock,
                     };
                 }
-                if (!currentSnap.branch || !currentSnap.prUrl) {
+                const target = prDeliveryCheckoutTarget(currentSnap);
+                if (!target) {
                     return {
                         ok: false,
                         status: 409,
                         error: 'checkout_not_deliverable',
-                        detail: 'The current delivery no longer has an attached PR branch.',
+                        detail: 'The current delivery no longer has a verified local branch.',
                     };
                 }
                 const cleanliness = await (0, project_git_1.inspectProjectCheckoutCleanliness)(c.project.path);
@@ -1268,9 +1468,8 @@ function createRailsRouter() {
                         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.' };
-                }
+                // Compatible local edits are preserved by Git's checkout transaction;
+                // only unreadable status prevents attempting the handoff here.
                 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' };
@@ -1301,30 +1500,25 @@ function createRailsRouter() {
                         }
                     }
                 }
-                if (cleanupWarnings.length > 0) {
-                    return {
-                        ok: false,
-                        status: 409,
-                        error: 'checkout_unavailable',
-                        detail: cleanupWarnings[0],
-                    };
-                }
-                // Cleanup just completed with ZERO warnings — clear any stale
-                // cleanup_incomplete evidence persisted by earlier failed release
-                // attempts, so the card stops claiming "Cleanup is incomplete" after
-                // the condition has been resolved. Same-state patch + live broadcast.
-                if (currentSnap.cleanupWarnings.length > 0 || currentSnap.statusCode === 'cleanup_incomplete') {
+                // A preserved unit worktree need not hold the assembled review branch.
+                // Keep its warnings visible, but let Git decide whether the requested
+                // branch is actually occupied instead of blocking every batch checkout.
+                if (cleanupWarnings.length > 0 || currentSnap.cleanupWarnings.length > 0 || currentSnap.statusCode === 'cleanup_incomplete') {
                     (0, rail_pr_store_1.transitionDecision)(c.db, row.id, currentSnap.decision, currentSnap.decision, {
-                        cleanupWarnings: [],
-                        ...(currentSnap.statusCode === 'cleanup_incomplete' ? { statusCode: null } : {}),
+                        cleanupWarnings,
+                        ...(cleanupWarnings.length > 0 ? { statusCode: 'cleanup_incomplete' }
+                            : currentSnap.statusCode === 'cleanup_incomplete' ? { statusCode: null } : {}),
                     });
                     emitPrDeliveryUpdate(c, row.id);
                 }
-                const checkedOut = await (0, project_git_1.checkoutProjectReviewBranch)(c.project.path, currentSnap.branch, currentSnap.deliverySha);
+                const checkedOut = await (0, project_git_1.checkoutProjectReviewBranch)(c.project.path, target.branch, target.sha);
                 if (!checkedOut.ok) {
-                    return { ok: false, status: 409, error: 'checkout_failed', detail: checkedOut.error };
+                    return {
+                        ok: false, status: 409, error: 'checkout_failed',
+                        detail: [checkedOut.error, ...cleanupWarnings].join('\n'),
+                    };
                 }
-                return { ok: true, git: await (0, project_git_1.getProjectGitInfo)(c.project.path) };
+                return { ok: true, branch: target.branch, git: await (0, project_git_1.getProjectGitInfo)(c.project.path), cleanupWarnings };
             });
             if (!outcome.ok) {
                 res.status(outcome.status).json({ error: outcome.error, detail: outcome.detail });