specrails-desktop 2.64.1 → 2.65.0

package/server/dist/modules/delivery/runtime/rail-isolated-launch.js

@@ -66,16 +66,18 @@ const legacy_launch_telemetry_1 = require("../../loops/runtime/legacy-launch-tel
  */
 const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
-const artifact_registry_1 = require("../../../artifact-registry");
 const ids_1 = require("../../../ids");
 const loop_constants_1 = require("../../loops/runtime/loop-constants");
 const worktree_manager_1 = require("../../../worktree-manager");
 const agent_runtime_paths_1 = require("../../agent-runtime/runtime/agent-runtime-paths");
 const rail_worktrees_store_1 = require("./rail-worktrees-store");
+const flow_worktree_handoff_1 = require("./flow-worktree-handoff");
 const pr_naming_1 = require("./pr-naming");
-const jira_db_1 = require("../../../jira/jira-db");
+const isolated_worktree_1 = require("./isolated-worktree");
 const db_1 = require("../../../db");
+const flow_review_outcome_1 = require("./flow-review-outcome");
 const delivery_evidence_1 = require("./delivery-evidence");
+const phase3_harvest_1 = require("./phase3-harvest");
 const isolated_settlement_store_1 = require("./isolated-settlement-store");
 const loop_runs_store_1 = require("../../loops/runtime/loop-runs-store");
 const loop_definition_recovery_1 = require("../../loops/runtime/loop-definition-recovery");
@@ -97,10 +99,7 @@ const revision_seed_1 = require("../../execution/runtime/revision-seed");
 const pr_follow_up_1 = require("./pr-follow-up");
 const spec_addenda_1 = require("../../specs/runtime/spec-addenda");
 const workspace_resolution_1 = require("../../../workspace-resolution");
-const feature_flags_1 = require("../../../feature-flags");
-const file_provenance_1 = require("../../code/runtime/file-provenance");
 const file_story_1 = require("../../code/runtime/file-story");
-const providers_1 = require("../../../providers");
 const pr_publisher_1 = require("./pr-publisher");
 const active_pr_continuation_1 = require("./active-pr-continuation");
 const pr_lifecycle_1 = require("./pr-lifecycle");
@@ -117,32 +116,6 @@ class PrContinuationIsolationError extends Error {
     }
 }
 exports.PrContinuationIsolationError = PrContinuationIsolationError;
-/**
- * Ticket data for the conventional branch name (pr-naming): title/labels from
- * the ticket-spec reader, the Jira key resolved with the authoritative
- * `jira_links` row prevailing over the ticket's own `jira_key` field (JIRA
- * ALWAYS PREVAILS). Fully failure-tolerant — a missing store/link degrades to
- * the bare local ticket id.
- */
-function unitNamingInput(ctx, ticketId) {
-    let spec;
-    try {
-        spec = ctx.getTicketSpec(ticketId);
-    }
-    catch {
-        /* tolerated */
-    }
-    let jiraKey = spec?.jira_key ?? null;
-    try {
-        const link = (0, jira_db_1.getLinkByLocalId)(ctx.db, ticketId);
-        if (link && !link.tombstoned && link.jiraKey)
-            jiraKey = link.jiraKey;
-    }
-    catch {
-        /* tolerated */
-    }
-    return { ticketId, title: spec?.title ?? null, labels: spec?.labels ?? null, jiraKey };
-}
 /**
  * Assemble the revision briefing from the generation being revised. Reads only
  * durable rows, tolerates every one of them being absent (a legacy row carries
@@ -211,7 +184,7 @@ function buildSpecSnapshot(ctx, ticketIds) {
  * key. Keep the local id as a fallback/cross-reference for Specrails.
  */
 function worktreeCommitMessage(ctx, ticketId, runId, partial = false) {
-    const input = unitNamingInput(ctx, ticketId);
+    const input = (0, isolated_worktree_1.ticketNamingInput)(ctx, ticketId);
     const ref = (0, pr_naming_1.ticketRef)(input);
     const subjectRef = ref === String(ticketId) ? `ticket-${ticketId}` : `${ref} ticket-${ticketId}`;
     return `specrails: ${subjectRef}${partial ? ' partial' : ''} (run ${runId})`;
@@ -295,16 +268,28 @@ async function verifyContinuationWorktree(git, repoDir, handle, target, expected
     }
     return headSha;
 }
-async function readHeadSha(git, cwd) {
+function canonicalPath(value) {
     try {
-        const result = await git.run(['rev-parse', '--verify', 'HEAD'], cwd);
-        const sha = result.code === 0 ? result.stdout.trim() : '';
-        return COMMIT_SHA_RE.test(sha) ? sha : null;
+        return fs.realpathSync.native(value);
     }
     catch {
-        return null;
+        return path.resolve(value);
     }
 }
+/** The adopted mount must be the Flow's own path, on its branch, at its frozen HEAD. */
+async function verifyFlowWorktree(git, mounted, required) {
+    if (canonicalPath(mounted.worktreePath) !== canonicalPath(required.worktreePath)) {
+        throw new flow_worktree_handoff_1.FlowWorktreeMismatchError(`The Flow worktree is not mounted at ${required.worktreePath}`);
+    }
+    if (mounted.branch !== required.branch) {
+        throw new flow_worktree_handoff_1.FlowWorktreeMismatchError(`The Flow worktree is on ${mounted.branch}, not ${required.branch}`);
+    }
+    const head = await (0, isolated_worktree_1.readHeadSha)(git, mounted.worktreePath);
+    if (!head || head !== required.headSha) {
+        throw new flow_worktree_handoff_1.FlowWorktreeMismatchError(`The Flow worktree HEAD ${head ?? 'unknown'} does not match the frozen ${required.headSha}`);
+    }
+    return head;
+}
 async function branchHasDelta(git, cwd, baseRef) {
     try {
         const result = await git.run(['diff', '--quiet', `${baseRef}...HEAD`, '--'], cwd);
@@ -419,7 +404,7 @@ function createIsolatedRunSettlement(ports) {
         if (isAborted?.()) {
             // The coordinator never started. Do not commit incidental edits or
             // release a mount borrowed from a previous delivery while rolling back.
-            const finalSha = await readHeadSha(git, a.handle.worktreePath);
+            const finalSha = await (0, isolated_worktree_1.readHeadSha)(git, a.handle.worktreePath);
             if (a.worktreeOwnership !== 'created')
                 markWorktree(a, 'needs-review');
             return {
@@ -445,7 +430,7 @@ function createIsolatedRunSettlement(ports) {
             markWorktree(a, 'needs-review');
             return {
                 run: a, implementationOutcome, deliveryOutcome: 'blocked',
-                initialSha: a.initialSha, finalSha: await readHeadSha(git, a.handle.worktreePath),
+                initialSha: a.initialSha, finalSha: await (0, isolated_worktree_1.readHeadSha)(git, a.handle.worktreePath),
                 failureCode: 'settlement_interrupted',
                 failureDetail: 'Programmatic workflow stopped before delivery; partial changes stay in its original worktree. The run log names the failing step. A resumable step offers Resume on the job page; a raised loop limit (such as a step\'s Maximum turns) needs a new launch.',
                 safeToRelease: false,
@@ -487,7 +472,7 @@ function createIsolatedRunSettlement(ports) {
                 implementationOutcome,
                 deliveryOutcome: 'blocked',
                 initialSha: a.initialSha,
-                finalSha: await readHeadSha(git, a.handle.worktreePath),
+                finalSha: await (0, isolated_worktree_1.readHeadSha)(git, a.handle.worktreePath),
                 failureCode: 'commit_failed',
                 failureDetail: detail,
                 safeToRelease: false,
@@ -509,7 +494,7 @@ function createIsolatedRunSettlement(ports) {
             }
         }
         else {
-            finalSha = await readHeadSha(git, a.handle.worktreePath);
+            finalSha = await (0, isolated_worktree_1.readHeadSha)(git, a.handle.worktreePath);
         }
         const changed = commit.committed || Boolean(a.initialSha && finalSha && a.initialSha !== finalSha);
         // A successful commit without a provable object is not retryable or safe to
@@ -569,7 +554,8 @@ function createIsolatedRunSettlement(ports) {
         // A resumed non-PR branch may already contain reviewable commits from an
         // earlier attempt, even when this iteration itself did not add one.
         let resumedBranchDelta = null;
-        if (!changed && a.continuationTarget === null && a.branchOwnership === 'preexisting') {
+        // An adopted Flow branch already carries the Flow's commits ahead of base.
+        if (!changed && a.continuationTarget === null && (a.branchOwnership === 'preexisting' || a.branchOwnership === 'adopted')) {
             resumedBranchDelta = await branchHasDelta(git, a.handle.worktreePath, a.baseRef);
             if (resumedBranchDelta === null) {
                 const detail = `cannot prove whether resumed branch ${a.handle.branch} has commits ahead of ${a.baseRef}`;
@@ -625,13 +611,11 @@ async function launchIsolatedRail(input, io = {}) {
     }
     const git = io.git ?? worktree_manager_1.defaultGitRunner;
     const exec = io.exec ?? pr_publisher_1.defaultExec;
-    const create = io.create ?? worktree_manager_1.createWorktree;
     const remove = io.remove ?? worktree_manager_1.removeWorktree;
-    const overlay = io.overlay ?? worktree_overlay_1.applyWorktreeOverlay;
     const resolveExecution = io.resolveExecution ?? workspace_resolution_1.resolveProjectExecution;
     const baseRepo = ctx.project.path;
     const slug = ctx.project.slug;
-    const worktreesRoot = path.join((0, artifact_registry_1.resolveHome)(), '.specrails', 'projects', slug, 'worktrees', ...(input.repositoryExecution ? [input.repositoryExecution.repositoryId] : []));
+    const worktreesRoot = (0, isolated_worktree_1.isolatedWorktreesRoot)(slug, input.repositoryExecution?.repositoryId);
     // A revision run is seeded with a full briefing (the instruction PLUS the
     // frozen spec, the branch that carries the work and what the previous run
     // actually reported) rather than the bare sentence — the run starts a FRESH
@@ -708,16 +692,25 @@ async function launchIsolatedRail(input, io = {}) {
         if (!row?.origin_conversation_id)
             return;
         const snapshot = (0, rail_pr_store_1.toPrDeliverySnapshot)(row);
-        const envelope = (0, rail_pr_store_1.toPrDecisionCardEnvelope)(ctx.project.id, snapshot);
         const primaryRunId = runId ?? snapshot.runIds[0] ?? deliveryId;
+        // A Flow → Spec run that failed outright goes back to its Flow on its own
+        // (flow module, `rail.pr_state` observer); the Flow's return card and
+        // automatic turn carry the failure, so the mission gets only the card
+        // update — no second trace row, no second briefing turn.
+        const flowCrash = row.loop_id === flow_review_outcome_1.FLOW_SPEC_DELIVERY_LOOP_ID && failure.code === 'implementation_failed';
         void (async () => {
             const summary = runId ? await (0, agent_runtime_controls_router_1.runtimeRunSummary)(ctx, runId).catch(() => null) : null;
+            // Re-read after the await: the delivery may have moved on meanwhile
+            // (Back to Flow closes it) and the card must never regress to the old decision.
+            const current = (0, rail_pr_store_1.getPrDelivery)(ctx.db, deliveryId) ?? row;
+            const envelope = (0, rail_pr_store_1.toPrDecisionCardEnvelope)(ctx.project.id, (0, rail_pr_store_1.toPrDeliverySnapshot)(current));
             await (0, mission_run_notify_1.notifyMissionRunFailure)({
                 originConversationId: row.origin_conversation_id,
                 projectId: ctx.project.id, runId: primaryRunId, railIndex, ticketIds: [...ticketIds],
                 railName: getRailName(ctx, railIndex),
                 failure, envelope, summary, hasDelivery: true, prDeliveryId: deliveryId,
                 tickets: ticketIds.map((id) => ({ id, title: ctx.getTicketSpec(id)?.title ?? null })),
+                ...(flowCrash ? { cardOnly: true } : {}),
             });
         })().catch((err) => console.error('[rail-isolated] mission failure notify failed:', err));
     };
@@ -753,36 +746,11 @@ async function launchIsolatedRail(input, io = {}) {
     let units = input.repositoryExecution && ticketIds.length === 0 ? [{ ticketId: 0, ticketIds: [] }] : scope === 'all'
         ? [{ ticketId: ticketIds[0], ticketIds: [...ticketIds] }]
         : ticketIds.map((id) => ({ ticketId: id, ticketIds: [id] }));
-    // Effective artifact root for the per-worktree overlay: a RELOCATED project's
-    // framework surface (slash commands, sr-* agents, skills, rules, .mcp.json,
-    // instruction file) lives in the WORKSPACE, not the repo — and `git worktree
-    // add` materializes only TRACKED files, so without the overlay a relocated
-    // worktree spawn has no `/specrails:*` commands at all. Legacy projects
-    // overlay their repo's own untracked on-disk entries instead. Resolved ONCE
-    // per launch; a resolution failure degrades to the legacy (repo) source.
-    let overlaySourceRoot = baseRepo;
-    let overlayFallbackRoots;
-    try {
-        const exec = resolveExecution({ slug, path: baseRepo });
-        if (exec.relocated && exec.workspaceDir) {
-            overlaySourceRoot = exec.workspaceDir;
-            // The repo as FALLBACK root: repo-resident untracked carve-outs
-            // (OpenSpec's `/opsx:*` commands, `openspec-*` skills, user extras)
-            // are absent from both the checkout (untracked) and the workspace
-            // (the framework ships only `specrails/`), so without this the claude
-            // CLI reports `Unknown command: /opsx:ff` inside isolated rails.
-            overlayFallbackRoots = [baseRepo];
-        }
-    }
-    catch { /* legacy fallback */ }
-    let overlayProviderDir = '.claude';
-    let overlayInstructions = 'CLAUDE.md';
-    try {
-        const adapter = (0, providers_1.getAdapter)(input.provider);
-        overlayProviderDir = adapter.projectDirName;
-        overlayInstructions = adapter.instructionsFilename;
-    }
-    catch { /* unknown provider — claude-shaped defaults */ }
+    // Effective artifact root for the per-worktree overlay (relocated workspace
+    // vs the repo's own untracked entries, plus the provider's dir/instruction
+    // file). Resolved ONCE per launch; see resolveOverlaySources.
+    const overlaySources = (0, isolated_worktree_1.resolveOverlaySources)({ slug, baseRepo, provider: input.provider }, resolveExecution);
+    const { sourceRoot: overlaySourceRoot, fallbackSourceRoots: overlayFallbackRoots, providerDir: overlayProviderDir, instructionsFilename: overlayInstructions, } = overlaySources;
     // Degraded overlay = the run may be missing native commands/agents. Never
     // aborts the rail (a partial surface beats no run) but MUST be visible:
     // stderr-style server log + a project-scoped WS event.
@@ -836,6 +804,8 @@ async function launchIsolatedRail(input, io = {}) {
             const worktreeBaseRef = await (0, integration_branch_1.resolveWorktreeBaseRef)(git, {
                 repoDir: baseRepo, integration, fetchOk: fetchResult.ok,
             });
+            // Unborn HEAD: refuse before the decision row, branches or worktrees exist.
+            await (0, isolated_worktree_1.assertRepositoryHasCommits)(git, baseRepo, worktreeBaseRef.baseRef);
             if (worktreeBaseRef.warning) {
                 console.warn(`[rail-isolated] ${worktreeBaseRef.warning} (repo ${baseRepo})`);
                 try {
@@ -923,9 +893,23 @@ async function launchIsolatedRail(input, io = {}) {
                         ticketIds: units.flatMap((unit) => unit.ticketIds),
                     }];
             }
+            // A Flow hand-off adopts ONE existing worktree for the Flow's single spec.
+            // It never combines with continuation, revision or retry contracts. Checked
+            // before the delivery row exists, so a rejection leaves nothing behind.
+            const flowWorktree = input.requiredFlowWorktree ?? null;
+            // A Flow in a non-primary repository runs as the ONE child of a
+            // single-repository group: only that repository's leg may adopt it.
+            const flowRepositoryLeg = !input.repositoryExecution
+                ? !flowWorktree?.repositoryId
+                : Boolean(flowWorktree?.repositoryId) && input.repositoryExecution.repositoryId === flowWorktree?.repositoryId;
+            if (flowWorktree && (units.length !== 1 || launchContinuation || input.requiredPrContinuation || input.revision ||
+                input.retryOfDelivery || !flowRepositoryLeg || input.explicitPrTarget)) {
+                throw new flow_worktree_handoff_1.FlowWorktreeMismatchError('A Flow hand-off launches exactly its own spec on a fresh delivery');
+            }
             if (prMode) {
                 const generation = (0, rail_pr_store_1.createPrDeliveryGeneration)(ctx.db, {
                     launchConfig: input.launchConfig,
+                    loopChoice: input.loopChoice ?? null,
                     parentDeliveryId: input.repositoryExecution?.parentDeliveryId,
                     repositoryId: input.repositoryExecution?.repositoryId,
                     repositoryPath: input.repositoryExecution ? baseRepo : undefined,
@@ -1011,6 +995,10 @@ async function launchIsolatedRail(input, io = {}) {
                 }
             }
             const unitBranchName = (ticketId) => {
+                if (flowWorktree) {
+                    takenBranches.add(flowWorktree.branch);
+                    return { branch: flowWorktree.branch, ownership: 'adopted' };
+                }
                 const revisionBranch = revisionBranches.get(ticketId);
                 if (revisionBranch)
                     return { branch: revisionBranch.branch, ownership: 'preexisting' };
@@ -1019,7 +1007,7 @@ async function launchIsolatedRail(input, io = {}) {
                     takenBranches.add(continuation.branch);
                     return { branch: continuation.branch, ownership: 'borrowed-pr' };
                 }
-                const preferred = (0, pr_naming_1.ticketBranchName)(unitNamingInput(ctx, ticketId));
+                const preferred = (0, pr_naming_1.ticketBranchName)((0, isolated_worktree_1.ticketNamingInput)(ctx, ticketId));
                 const branch = (0, pr_naming_1.resolveCollisionFreeName)(preferred, {
                     // A run can reuse a branch only through the exact revision/PR
                     // evidence above. An accepted predecessor may now lag the integration
@@ -1049,95 +1037,64 @@ async function launchIsolatedRail(input, io = {}) {
                                 throw new Error(`Revision branch ${revisionBranch.branch} no longer matches its recorded delivery commit`);
                             }
                         }
-                        handle = await create(git, {
+                        const prepared = await (0, isolated_worktree_1.materializeIsolatedWorktree)({
                             repoDir: baseRepo,
                             worktreesRoot: path.join(worktreesRoot, runId),
                             slug,
                             ticketId: unit.ticketId,
-                            baseRef: revisionBranch?.sha ?? continuationTarget?.baseRef ?? worktreeBaseRef.baseRef,
+                            baseRef: flowWorktree?.baseSha ?? revisionBranch?.sha ?? continuationTarget?.baseRef ?? worktreeBaseRef.baseRef,
                             branch: branchPlan.branch,
+                            branchOwnership: branchPlan.ownership,
+                            pinBranchOwnership: Boolean(continuationTarget || flowWorktree),
                             refreshFromBaseRef: Boolean(continuationTarget?.baseRef),
-                            fresh: !revisionBranch && !continuationTarget,
-                            reuseBranchWorktree: Boolean(revisionBranch || continuationTarget),
-                        });
-                        worktreeOwnership = handle.worktreeCreated === false ? 'preexisting' : 'created';
-                        if (!continuationTarget && (handle.branch !== branchPlan.branch || handle.branchCreated === false)) {
-                            branchOwnership = 'preexisting';
-                        }
-                        if (continuationTarget) {
-                            initialSha = await verifyContinuationWorktree(git, baseRepo, handle, continuationTarget, continuationTarget.deliverySha);
-                        }
-                        else {
-                            initialSha = await readHeadSha(git, handle.worktreePath);
-                            if (expectedRepositoryBaseSha && initialSha !== expectedRepositoryBaseSha)
-                                throw new Error('The repository base changed before its worktree could be frozen');
-                            if (revisionBranch && (handle.branch !== revisionBranch.branch || initialSha !== revisionBranch.sha)) {
-                                throw new Error(`Revision checkout does not expose the exact recorded branch ${revisionBranch.branch}`);
-                            }
-                        }
-                        // Per-run overlay: merge-link the framework surface the checkout didn't
-                        // bring into the worktree (idempotent; resume-safe via its manifest).
-                        let overlayExcludes = [];
-                        let overlayCleanupEvidence = [];
-                        try {
-                            const res = overlay({
-                                worktreePath: handle.worktreePath,
-                                sourceRoot: overlaySourceRoot,
-                                fallbackSourceRoots: overlayFallbackRoots,
-                                providerDir: overlayProviderDir,
-                                instructionsFilename: overlayInstructions,
-                            });
-                            overlayExcludes = res.createdPaths;
-                            overlayCleanupEvidence = res.cleanupEvidence ?? [];
-                            if (res.warnings.length > 0)
-                                notifyOverlayDegraded(unit.ticketId, res.warnings);
-                        }
-                        catch (err) {
-                            // applyWorktreeOverlay never throws; this guards injected test doubles
-                            // and future edits — the spawn proceeds regardless.
-                            notifyOverlayDegraded(unit.ticketId, [err instanceof Error ? err.message : String(err)]);
-                        }
-                        // Warm-dependency reuse: link the base checkout's node_modules trees
-                        // into the fresh worktree (best-effort; a failure just leaves the run
-                        // on the legacy cold start). Linked paths join the overlay exclusion
-                        // list so they inherit the commit-time guarantees.
-                        let warmLinkEvidence = [];
-                        try {
-                            const nm = (io.linkNodeModules ?? worktree_node_modules_1.linkNodeModulesIntoWorktree)(baseRepo, handle.worktreePath);
-                            // `authenticated` (not `linked`) is the authorized set: it also covers
-                            // links a previous pass created, which a resumed launch would
-                            // otherwise leave both un-excluded from the commit and unauthorized
-                            // for release.
-                            const authorized = nm.authenticated ?? nm.linked ?? [];
-                            if (authorized.length > 0)
-                                overlayExcludes = overlayExcludes.concat(authorized);
-                            warmLinkEvidence = nm.evidence ?? [];
-                            if (nm.warnings.length > 0)
-                                notifyOverlayDegraded(unit.ticketId, nm.warnings);
-                        }
-                        catch (err) {
-                            notifyOverlayDegraded(unit.ticketId, [err instanceof Error ? err.message : String(err)]);
-                        }
-                        // Code-Explorer provenance: freeze the worktree's pre-run state (HEAD sha
-                        // + the overlay's untracked set) so the settle diff attributes exactly
-                        // the run's own writes. Best-effort — a snapshot failure only loses
-                        // provenance, never the run.
-                        let provenanceSnapshot = null;
-                        if ((0, feature_flags_1.isCodeExplorerEnabled)()) {
-                            try {
-                                provenanceSnapshot = (io.snapshot ?? file_provenance_1.snapshotWorkingTree)(handle.worktreePath);
-                            }
-                            catch (err) {
-                                console.warn(`[rail-isolated] provenance snapshot failed: ${err.message}`);
-                            }
-                        }
+                            fresh: !revisionBranch && !continuationTarget && !flowWorktree,
+                            reuseBranchWorktree: Boolean(revisionBranch || continuationTarget || flowWorktree),
+                            verifyHead: async (mounted) => {
+                                if (flowWorktree)
+                                    return verifyFlowWorktree(git, mounted, flowWorktree);
+                                if (continuationTarget) {
+                                    return verifyContinuationWorktree(git, baseRepo, mounted, continuationTarget, continuationTarget.deliverySha);
+                                }
+                                const headSha = await (0, isolated_worktree_1.readHeadSha)(git, mounted.worktreePath);
+                                if (expectedRepositoryBaseSha && headSha !== expectedRepositoryBaseSha)
+                                    throw new Error('The repository base changed before its worktree could be frozen');
+                                if (revisionBranch && (mounted.branch !== revisionBranch.branch || headSha !== revisionBranch.sha)) {
+                                    throw new Error(`Revision checkout does not expose the exact recorded branch ${revisionBranch.branch}`);
+                                }
+                                return headSha;
+                            },
+                            overlay: overlaySources,
+                            onDegraded: (warnings) => notifyOverlayDegraded(unit.ticketId, warnings),
+                        }, io);
+                        handle = prepared.handle;
+                        branchOwnership = prepared.branchOwnership;
+                        // The verified Flow mount pre-existed by construction; the rail adopts it.
+                        worktreeOwnership = flowWorktree && prepared.worktreeOwnership === 'preexisting' ? 'adopted' : prepared.worktreeOwnership;
+                        initialSha = prepared.initialSha;
+                        const { overlayExcludes, overlayCleanupEvidence, warmLinkEvidence, provenanceSnapshot } = prepared;
                         const ledgerId = (0, ids_1.newId)();
-                        (0, rail_worktrees_store_1.createRailWorktree)(ctx.db, {
+                        const ledgerRow = {
                             id: ledgerId, railIndex, ticketId: unit.ticketId, runId,
                             repositoryId: input.repositoryExecution?.repositoryId,
                             repositoryPath: input.repositoryExecution ? baseRepo : undefined,
                             branch: handle.branch, worktreePath: handle.worktreePath,
-                        });
+                        };
+                        if (flowWorktree) {
+                            // Ownership transfer: the rail ledger row and the Flow's handed_off
+                            // state commit together or not at all.
+                            const adoptedHead = initialSha;
+                            if (!adoptedHead)
+                                throw new flow_worktree_handoff_1.FlowWorktreeMismatchError('The Flow worktree HEAD could not be verified');
+                            ctx.db.transaction(() => {
+                                (0, rail_worktrees_store_1.createRailWorktree)(ctx.db, ledgerRow);
+                                // A repository leg reports the GROUP delivery: the Flow settles on
+                                // the parent's `rail.pr_state`, which is the only one broadcast.
+                                flowWorktree.adopt({ railIndex, runId, ledgerId, deliveryId: input.repositoryExecution?.parentDeliveryId ?? prDeliveryId, headSha: adoptedHead });
+                            })();
+                        }
+                        else {
+                            (0, rail_worktrees_store_1.createRailWorktree)(ctx.db, ledgerRow);
+                        }
                         allocated.push({
                             ticketId: unit.ticketId,
                             ticketIds: unit.ticketIds,
@@ -1149,8 +1106,8 @@ async function launchIsolatedRail(input, io = {}) {
                             warmLinkEvidence,
                             provenanceSnapshot,
                             continuationTarget,
-                            baseRef: continuationTarget?.baseRef ?? worktreeBaseRef.baseRef,
-                            hygieneBaseSha,
+                            baseRef: flowWorktree?.baseSha ?? continuationTarget?.baseRef ?? worktreeBaseRef.baseRef,
+                            hygieneBaseSha: flowWorktree?.baseSha ?? hygieneBaseSha,
                             initialSha,
                             branchOwnership,
                             worktreeOwnership,
@@ -1200,6 +1157,20 @@ async function launchIsolatedRail(input, io = {}) {
                 for (const a of allocated) {
                     if (claimedAddendaByRun.has(a.runId))
                         (0, spec_addenda_1.broadcastSpecAddendaChange)(msg => ctx.broadcast(msg), ctx.project.id, (0, spec_addenda_1.settleSpecAddendaAt)(addendaStorePath, a.ticketIds, a.runId, 'failed'));
+                    if (a.worktreeOwnership === 'adopted' && flowWorktree) {
+                        // Never remove an adopted Flow worktree on rollback: give it back.
+                        try {
+                            ctx.db.transaction(() => {
+                                (0, rail_worktrees_store_1.deleteRailWorktree)(ctx.db, a.ledgerId);
+                                flowWorktree.release(errorDetail(err));
+                            })();
+                        }
+                        catch (releaseError) {
+                            console.error(`[rail-isolated] could not return Flow worktree ${a.handle.worktreePath}: ${errorDetail(releaseError)}`);
+                            (0, rail_worktrees_store_1.updateRailWorktreeState)(ctx.db, a.ledgerId, 'needs-review');
+                        }
+                        continue;
+                    }
                     if (a.worktreeOwnership === 'created') {
                         await remove(git, {
                             repoDir: baseRepo,
@@ -1327,8 +1298,11 @@ async function launchIsolatedRail(input, io = {}) {
             deferTerminalOutcome: true,
             constants, provider, model, effort, ...(deciderEngine ? { deciderEngine } : {}),
             profileName: input.profileName,
+            ...(input.runCapUsd !== undefined ? { runCapUsd: input.runCapUsd } : {}),
             ...(input.followUp ? { followUp: { id: input.followUp.id, version: input.followUp.version, hash: input.followUp.hash, openspecChangeName: input.followUp.openspecChangeName ?? null, briefing: (0, pr_follow_up_1.renderFollowUpBriefing)(input.followUp, { prNumber: launchContinuation?.prNumber ?? input.explicitPrTarget?.prNumber ?? null, ticketIds }) } } : {}),
             ...(claimedAddenda.briefing ? { addenda: { ids: claimedAddenda.snapshot.map((e) => e.id), briefing: claimedAddenda.briefing } } : {}),
+            // Flow hand-off: Core derives the change from the Flow reservation commit.
+            ...(input.requiredFlowWorktree ? { flowDerivation: { baseSha: input.requiredFlowWorktree.baseSha ?? null, summary: input.requiredFlowWorktree.summary ?? '', ...(input.requiredFlowWorktree.changeId ? { changeId: input.requiredFlowWorktree.changeId } : {}) } } : {}),
         });
         runPromises.push(settleAllocatedRun(a, enginePromise).then(async (result) => {
             if (prDeliveryId && (0, loop_graph_1.isDefinitionGraph)(loopGraph))
@@ -1373,7 +1347,7 @@ async function launchIsolatedRail(input, io = {}) {
             implementationOutcome,
             deliveryOutcome: 'blocked',
             initialSha: run.initialSha,
-            finalSha: await readHeadSha(git, run.handle.worktreePath),
+            finalSha: await (0, isolated_worktree_1.readHeadSha)(git, run.handle.worktreePath),
             failureCode: 'settlement_interrupted',
             failureDetail: detail,
             safeToRelease: false,
@@ -1673,7 +1647,9 @@ async function launchIsolatedRail(input, io = {}) {
             let settleEvidence;
             try {
                 const definitionEvidence = await (0, loop_definition_recovery_1.probeDefinitionRuns)({ db: ctx.db, cwd: ctx.project.path, env: process.env }, results.filter(result => (0, loop_runs_store_1.getLoopRun)(ctx.db, result.run.runId)?.engine_version === 2).map(result => result.run.runId), true);
-                settleEvidence = harvest({ readEvents: (runId) => (0, db_1.getJobEvents)(ctx.db, runId) }, results.map((result) => ({
+                const reviewBrief = await (io.reviewBriefCapability ?? delivery_evidence_1.coreAnnouncesReviewBrief)();
+                const phase3 = await (0, phase3_harvest_1.phase3HarvestOptions)({ db: ctx.db, project: ctx.project, capabilities: io.phase3Capabilities });
+                settleEvidence = harvest({ readEvents: (runId) => (0, db_1.getJobEvents)(ctx.db, runId), reviewBrief, ...phase3 }, results.map((result) => ({
                     ticketId: result.run.ticketId,
                     runId: result.run.runId,
                     definitionStatus: definitionEvidence.get(result.run.runId),
@@ -1689,14 +1665,25 @@ async function launchIsolatedRail(input, io = {}) {
                 console.warn(`[rail-isolated] evidence harvest failed: ${e instanceof Error ? e.message : String(e)}`);
                 settleEvidence = undefined;
             }
+            // Flow -> Spec: a run that stopped because the work still needs changes
+            // (review rejected / checks failing after the repair rounds) is not an
+            // opaque implementation failure. Say so, with the reviewer's own words.
+            const flowReview = (0, flow_review_outcome_1.flowReviewOutcome)({ loopId, implementationOutcome, evidence: settleEvidence });
+            const settledStatusCode = flowReview ? 'review_changes_requested' : statusCode;
+            const settledStatusDetail = flowReview ? (0, flow_review_outcome_1.flowReviewStatusDetail)(flowReview) : statusDetail;
+            if (flowReview) {
+                for (const unit of settledBranchRecords)
+                    if (unit.failureCode === 'settlement_interrupted')
+                        unit.failureCode = 'review_changes_requested';
+            }
             const patch = {
                 settleEvidence,
                 branches: settledBranchRecords,
                 worktreeIds,
                 implementationOutcome,
                 deliveryOutcome,
-                statusCode,
-                statusDetail,
+                statusCode: settledStatusCode,
+                statusDetail: settledStatusDetail,
                 deliverySha,
                 ...(launchContinuation ? {
                     branch: launchContinuation.branch,
@@ -1745,8 +1732,8 @@ async function launchIsolatedRail(input, io = {}) {
                 if (implementationOutcome === 'failed') {
                     const failedUnit = results.find((result) => result.implementationOutcome === 'failed') ?? results[0];
                     notifyOriginRunFailure(prDeliveryId, {
-                        code: 'implementation_failed',
-                        detail: statusDetail,
+                        code: flowReview ? 'review_changes_requested' : 'implementation_failed',
+                        detail: settledStatusDetail,
                         stepId: null,
                     }, failedUnit?.run.runId ?? null);
                 }
@@ -1940,8 +1927,12 @@ async function reattachIsolatedSettlement(ctx, deliveryId, runId, io = {}) {
             const partial = complete && ready.length > 0 && results.some(item => item.implementationOutcome !== 'succeeded' || !['ready', 'no_changes'].includes(item.deliveryOutcome));
             const next = !complete ? 'building' : !successes.length ? 'implementation_failed' : row.pr_url ? 'pr_failed' : ready.length ? 'on_review' : noChanges ? 'no_changes' : 'pr_failed';
             const definitionEvidence = await (0, loop_definition_recovery_1.probeDefinitionRuns)({ db: ctx.db, cwd: ctx.project.path, env: process.env }, results.map(item => item.run.runId), true);
-            const evidence = (io.harvestEvidence ?? delivery_evidence_1.harvestDeliveryEvidence)({ readEvents: id => (0, db_1.getJobEvents)(ctx.db, id) }, results.map(item => ({
+            const reviewBrief = await (io.reviewBriefCapability ?? delivery_evidence_1.coreAnnouncesReviewBrief)();
+            const phase3 = await (0, phase3_harvest_1.phase3HarvestOptions)({ db: ctx.db, project: ctx.project, capabilities: io.phase3Capabilities });
+            const evidence = (io.harvestEvidence ?? delivery_evidence_1.harvestDeliveryEvidence)({ readEvents: id => (0, db_1.getJobEvents)(ctx.db, id), reviewBrief, ...phase3 }, results.map(item => ({
                 ticketId: item.run.ticketId, runId: item.run.runId, worktreePath: item.run.handle.worktreePath,
+                // Phase-3 run records only (spec trace, baseline); runtime evidence keeps its probe.
+                recordsDir: path.join((io.resolveExecution ?? workspace_resolution_1.resolveProjectExecution)(ctx.project).specrailsDir, 'pipeline', item.run.runId),
                 definitionStatus: definitionEvidence.get(item.run.runId),
                 reviewerStepId: (0, loop_runs_store_1.readDefinitionRun)(ctx.db, item.run.runId)?.request.graph.config.reviewerStepId,
             })));
@@ -1967,8 +1958,20 @@ async function reattachIsolatedSettlement(ctx, deliveryId, runId, io = {}) {
     }
     for (const row of allRows) {
         const latest = (0, rail_pr_store_1.getPrDelivery)(ctx.db, row.id);
-        if (latest)
-            ctx.broadcast((0, rail_pr_store_1.toRailPrStateMessage)(ctx.project.id, (0, rail_pr_store_1.toPrDeliverySnapshot)(latest)));
+        if (!latest)
+            continue;
+        const snapshot = (0, rail_pr_store_1.toPrDeliverySnapshot)(latest);
+        ctx.broadcast((0, rail_pr_store_1.toRailPrStateMessage)(ctx.project.id, snapshot));
+        // A recovered settlement (server restart mid-run, then resume/reattach)
+        // has no launch closure left to refresh the origin mission card. Without
+        // this the persisted card stays `building` after the delivery reached
+        // review, and every client hydration faithfully re-reads the stale card.
+        if (latest.origin_conversation_id) {
+            try {
+                (0, agent_chat_registry_1.getAgentChatManager)()?.updatePrDecisionCard(latest.origin_conversation_id, (0, rail_pr_store_1.toPrDecisionCardEnvelope)(ctx.project.id, snapshot));
+            }
+            catch { /* the durable row is authoritative; startup reprojection heals */ }
+        }
     }
 }
 function recoveryOverlayExcludes(repoDir, worktreePath) {

package/server/dist/modules/delivery/runtime/rail-launch-parser.js

@@ -75,8 +75,11 @@ function coerceRailLaunchProposal(value) {
     const mode = modeRaw === 'batch' || modeRaw === 'batch-implement' ? 'implement' : modeRaw;
     if (!exports.RAIL_LAUNCH_MODES.includes(mode))
         return { ok: false, reason: 'invalid_mode' };
-    const repositoryIds = value.repositoryIds;
-    const workspaceSelection = value.workspaceSelection;
+    // Agents (Codex in particular) spell "no restriction" as null or an empty
+    // map. Treat exactly those as omitted; any other malformed selection still
+    // rejects the card so a bad selection can never broaden the scope.
+    const repositoryIds = value.repositoryIds === null ? undefined : value.repositoryIds;
+    const workspaceSelection = value.workspaceSelection === null || (isRecord(value.workspaceSelection) && Object.keys(value.workspaceSelection).length === 0) ? undefined : value.workspaceSelection;
     if (repositoryIds !== undefined && (!Array.isArray(repositoryIds) || !repositoryIds.length || repositoryIds.length > 50 || repositoryIds.some(id => typeof id !== 'string' || !id.trim()) || new Set(repositoryIds).size !== repositoryIds.length))
         return { ok: false, reason: 'invalid_workspace_selection' };
     if (workspaceSelection !== undefined && (!isRecord(workspaceSelection) || !Object.keys(workspaceSelection).length || Object.keys(workspaceSelection).length > 50 || Object.entries(workspaceSelection).some(([id, paths]) => !id.trim() || !Array.isArray(paths) || !paths.length || paths.length > 50 || paths.some(item => typeof item !== 'string' || !item.trim() || item.length > 4096) || new Set(paths).size !== paths.length)))

package/server/dist/modules/delivery/runtime/rail-pr-decision.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.sweepMergedChainAncestors = exports.executePrDecision = exports.actionAllowed = exports.isPrDecisionAction = exports.PR_DECISION_ACTIONS = void 0;
+exports.waitForLocalRestores = exports.recoverLocalStashes = exports.runDiscardRestoreBranch = exports.runBringBackLocalChanges = exports.runRestoreLocalChanges = exports.sweepMergedChainAncestors = exports.executePrDecision = exports.actionAllowed = exports.isPrDecisionAction = exports.PR_DECISION_ACTIONS = void 0;
 /** Compatibility entry point; decision workflows have capability-owned implementations. */
 var __1 = require("..");
 Object.defineProperty(exports, "PR_DECISION_ACTIONS", { enumerable: true, get: function () { return __1.PR_DECISION_ACTIONS; } });
@@ -10,3 +10,9 @@ var dispatch_1 = require("../adapters/decisions/dispatch");
 Object.defineProperty(exports, "executePrDecision", { enumerable: true, get: function () { return dispatch_1.executePrDecision; } });
 var chains_1 = require("../adapters/decisions/chains");
 Object.defineProperty(exports, "sweepMergedChainAncestors", { enumerable: true, get: function () { return chains_1.sweepMergedChainAncestors; } });
+var local_changes_1 = require("../adapters/decisions/local-changes");
+Object.defineProperty(exports, "runRestoreLocalChanges", { enumerable: true, get: function () { return local_changes_1.runRestoreLocalChanges; } });
+Object.defineProperty(exports, "runBringBackLocalChanges", { enumerable: true, get: function () { return local_changes_1.runBringBackLocalChanges; } });
+Object.defineProperty(exports, "runDiscardRestoreBranch", { enumerable: true, get: function () { return local_changes_1.runDiscardRestoreBranch; } });
+Object.defineProperty(exports, "recoverLocalStashes", { enumerable: true, get: function () { return local_changes_1.recoverLocalStashes; } });
+Object.defineProperty(exports, "waitForLocalRestores", { enumerable: true, get: function () { return local_changes_1.waitForLocalRestores; } });