specrails-desktop 2.21.0 → 2.22.0

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

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACTIVE_PR_DECISIONS = exports.TERMINAL_PR_DECISIONS = void 0;
+exports.isTerminalPrDecision = isTerminalPrDecision;
+exports.createPrDelivery = createPrDelivery;
+exports.getPrDelivery = getPrDelivery;
+exports.getActivePrDeliveryByRail = getActivePrDeliveryByRail;
+exports.listActivePrDeliveries = listActivePrDeliveries;
+exports.transitionDecision = transitionDecision;
+exports.toPrDeliverySnapshot = toPrDeliverySnapshot;
+exports.toRailPrStateMessage = toRailPrStateMessage;
+exports.toPrDecisionCardEnvelope = toPrDecisionCardEnvelope;
+const ids_1 = require("./ids");
+/** States after which the delivery is closed (no further decision possible). */
+exports.TERMINAL_PR_DECISIONS = new Set(['merged', 'discarded']);
+/** States in which the delivery still awaits (or is executing) a user decision. */
+exports.ACTIVE_PR_DECISIONS = new Set([
+    'building',
+    'on_review',
+    'pr_draft',
+    'pr_ready',
+    'pr_failed',
+]);
+function isTerminalPrDecision(s) {
+    return exports.TERMINAL_PR_DECISIONS.has(s);
+}
+/**
+ * Insert a new delivery row for a rail launch. The row starts at
+ * decision='building', pr_state='none' with empty branches/worktree_ids —
+ * settle patches those via transitionDecision.
+ */
+function createPrDelivery(db, input) {
+    const id = input.id ?? (0, ids_1.newId)();
+    db.prepare(`INSERT INTO rail_pr_deliveries (
+       id, rail_index, loop_id, rail_key, ticket_ids, base_branch,
+       loop_name, origin_surface, origin_conversation_id
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, input.railIndex, input.loopId ?? null, input.railKey, JSON.stringify(input.ticketIds), input.baseBranch, input.loopName, input.originSurface, input.originConversationId ?? null);
+    return getPrDelivery(db, id);
+}
+function getPrDelivery(db, id) {
+    return db.prepare('SELECT * FROM rail_pr_deliveries WHERE id = ?').get(id);
+}
+/**
+ * The newest non-terminal delivery for a rail slot (a slot can be relaunched;
+ * older terminal rows are history). Used by the relaunch-collision guard and
+ * the GET /rails snapshot.
+ */
+function getActivePrDeliveryByRail(db, railIndex) {
+    return db
+        .prepare(`SELECT * FROM rail_pr_deliveries
+       WHERE rail_index = ? AND decision NOT IN ('merged','discarded')
+       ORDER BY created_at DESC, rowid DESC LIMIT 1`)
+        .get(railIndex);
+}
+/** Every non-terminal delivery — hydrates the GET /rails prDeliveries snapshot. */
+function listActivePrDeliveries(db) {
+    return db
+        .prepare(`SELECT * FROM rail_pr_deliveries
+       WHERE decision NOT IN ('merged','discarded')
+       ORDER BY rail_index, created_at DESC, rowid DESC`)
+        .all();
+}
+// 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.
+const PATCH_COLUMNS = {
+    branch: 'branch',
+    prUrl: 'pr_url',
+    prNumber: 'pr_number',
+    prState: 'pr_state',
+    branches: 'branches',
+    worktreeIds: 'worktree_ids',
+    runIds: 'run_ids',
+};
+function patchValue(key, patch) {
+    const raw = patch[key];
+    if (key === 'branches' || key === 'worktreeIds' || key === 'runIds')
+        return JSON.stringify(raw);
+    return raw;
+}
+/**
+ * COMPARE-AND-SET decision transition: one atomic
+ * `UPDATE … WHERE id = ? AND decision = ?` (no read-modify-write), so two
+ * surfaces racing on the same delivery cannot both win. Returns `false` (row
+ * untouched) when `expected` is stale — the caller maps that to a 409.
+ * `patch` may set delivery columns alongside the transition; `updated_at` is
+ * always bumped.
+ */
+function transitionDecision(db, id, expected, next, patch = {}) {
+    const keys = Object.keys(patch).filter((k) => patch[k] !== undefined);
+    const patchClause = keys.map((k) => `, ${PATCH_COLUMNS[k]} = ?`).join('');
+    const values = keys.map((k) => patchValue(k, patch));
+    return (db
+        .prepare(`UPDATE rail_pr_deliveries
+         SET decision = ?, updated_at = datetime('now')${patchClause}
+         WHERE id = ? AND decision = ?`)
+        .run(next, ...values, id, expected).changes > 0);
+}
+function parseJsonArray(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+function toPrDeliverySnapshot(row) {
+    return {
+        id: row.id,
+        railIndex: row.rail_index,
+        loopId: row.loop_id,
+        railKey: row.rail_key,
+        ticketIds: parseJsonArray(row.ticket_ids),
+        baseBranch: row.base_branch,
+        branch: row.branch,
+        prUrl: row.pr_url,
+        prNumber: row.pr_number,
+        prState: row.pr_state,
+        decision: row.decision,
+        branches: parseJsonArray(row.branches),
+        loopName: row.loop_name,
+        worktreeIds: parseJsonArray(row.worktree_ids),
+        runIds: parseJsonArray(row.run_ids ?? '[]'),
+        originSurface: row.origin_surface,
+        originConversationId: row.origin_conversation_id,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+/**
+ * Build the durable `rail.pr_state` broadcast payload from a delivery snapshot
+ * — the ONE message shape every mutation of the row re-broadcasts (launch
+ * insert, build-settle, decision-endpoint transitions), so both decision
+ * surfaces converge on the same state.
+ */
+function toRailPrStateMessage(projectId, snap) {
+    return {
+        type: 'rail.pr_state',
+        projectId,
+        railIndex: snap.railIndex,
+        prDeliveryId: snap.id,
+        railKey: snap.railKey,
+        ticketIds: snap.ticketIds,
+        baseBranch: snap.baseBranch,
+        branch: snap.branch,
+        prUrl: snap.prUrl,
+        prNumber: snap.prNumber,
+        prState: snap.prState,
+        decision: snap.decision,
+        runIds: snap.runIds,
+        originConversationId: snap.originConversationId,
+    };
+}
+/**
+ * Build the agent-chat PR-decision card envelope from a delivery snapshot —
+ * the ONE mapper both card writers (rail-isolated-launch's origin-card sync
+ * and rail-pr-decision's finalizeTransition) share, so the persisted card and
+ * the `agent_pr_decision` broadcast can never drift between the two sites.
+ */
+function toPrDecisionCardEnvelope(projectId, snap) {
+    return {
+        kind: 'pr_decision',
+        prDeliveryId: snap.id,
+        railIndex: snap.railIndex,
+        projectId,
+        baseBranch: snap.baseBranch,
+        ticketIds: snap.ticketIds,
+        decision: snap.decision,
+        prUrl: snap.prUrl,
+        prState: snap.prState,
+        branch: snap.branch,
+        runIds: snap.runIds,
+    };
+}

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

@@ -9,6 +9,8 @@ exports.setRailWorktreeRunId = setRailWorktreeRunId;
 exports.listRailWorktrees = listRailWorktrees;
 exports.listNonTerminalRailWorktrees = listNonTerminalRailWorktrees;
 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']);
 function isTerminalMergeState(s) {
@@ -50,3 +52,19 @@ function listNonTerminalRailWorktrees(db) {
 function deleteRailWorktree(db, id) {
     return db.prepare('DELETE FROM rail_worktrees WHERE id = ?').run(id).changes > 0;
 }
+/** Every rail allocation ever made for a ticket, newest first — the recovery
+ *  input for create-pr's pre-flight: when a delivery row records a branch that
+ *  no longer exists, any OTHER branch a rail allocated for the same ticket that
+ *  still exists with commits ahead of base is the real carrier of the work. */
+function listRailWorktreesForTicket(db, ticketId) {
+    return db
+        .prepare('SELECT * FROM rail_worktrees WHERE ticket_id = ? ORDER BY created_at DESC, rowid DESC')
+        .all(ticketId);
+}
+/** True when a prior rail allocation for this ticket used exactly this branch —
+ *  i.e. an existing branch of that name is OURS to resume (partial work from a
+ *  stopped run), not a foreign collision to suffix away from. */
+function railWorktreeBranchExistsForTicket(db, ticketId, branch) {
+    return (db.prepare('SELECT 1 FROM rail_worktrees WHERE ticket_id = ? AND branch = ? LIMIT 1').get(ticketId, branch) !==
+        undefined);
+}

package/server/dist/rails-router.js

@@ -6,6 +6,8 @@ const rails_store_1 = require("./rails-store");
 const queue_manager_1 = require("./queue-manager");
 const provider_selection_1 = require("./provider-selection");
 const feature_flags_1 = require("./feature-flags");
+const file_provenance_1 = require("./file-provenance");
+const file_story_1 = require("./file-story");
 const loops_store_1 = require("./loops-store");
 const loop_runs_store_1 = require("./loop-runs-store");
 const providers_1 = require("./providers");
@@ -16,7 +18,9 @@ const loop_constants_1 = require("./loop-constants");
 const loop_command_catalog_1 = require("./loop-command-catalog");
 const loop_graph_1 = require("./loop-graph");
 const rail_isolation_1 = require("./rail-isolation");
+const rail_pr_store_1 = require("./rail-pr-store");
 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 pr_publisher_1 = require("./pr-publisher");
@@ -87,17 +91,103 @@ function createRailsRouter() {
                 const counts = (0, loop_runs_store_1.getRunEventCounts)(c.db, run.id);
                 activeLoopRuns[run.rail_index] = { loopRunId: run.id, loopId: run.loop_id, loopName: run.loop_name, provider: run.provider, model: run.model, iteration: run.iteration_count, startedAt: run.started_at, steps: counts.steps, lines: counts.lines };
             }
-            res.json({ rails, activeJobs, activeLoopRuns });
+            // Pending ask-first PR decisions (safe-pr-review-flow): the newest ACTIVE
+            // (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.
+            const prDeliveries = {};
+            for (const row of (0, rail_pr_store_1.listActivePrDeliveries)(c.db)) {
+                if (!(row.rail_index in prDeliveries))
+                    prDeliveries[row.rail_index] = (0, rail_pr_store_1.toPrDeliverySnapshot)(row);
+            }
+            res.json({ rails, activeJobs, activeLoopRuns, prDeliveries });
         }
         catch (err) {
             console.error('[rails-router] get rails error:', err);
             res.status(500).json({ error: 'Failed to fetch rails' });
         }
     });
+    // POST /rails — create a new rail slot (dynamic rails). Body: { name? }.
+    // Allocates the lowest free index; capped at MAX_RAILS per project so the
+    // railIndex-keyed maps (metrics, PR deliveries, worktree progress) stay
+    // bounded. Broadcast rides the existing rail.updated shape (changed:'name')
+    // so every client — including the mobile companion — adopts the new slot
+    // without a new wire message.
+    router.post('/', (req, res) => {
+        const c = ctx(req);
+        const body = req.body ?? {};
+        const name = body.name;
+        if (name !== undefined && name !== null && typeof name !== 'string') {
+            res.status(400).json({ error: 'name must be a string or null' });
+            return;
+        }
+        if (typeof name === 'string' && name.length > 60) {
+            res.status(400).json({ error: 'name must be 60 characters or fewer' });
+            return;
+        }
+        try {
+            if ((0, rails_store_1.railCount)(c.db) >= rails_store_1.MAX_RAILS) {
+                res.status(400).json({ error: 'rail_limit_reached', maxRails: rails_store_1.MAX_RAILS });
+                return;
+            }
+            const rail = (0, rails_store_1.createRail)(c.db, typeof name === 'string' ? name : null);
+            broadcastRailUpdated(c, rail.railIndex, 'name');
+            res.status(201).json({ rail });
+        }
+        catch (err) {
+            console.error('[rails-router] create rail error:', err);
+            res.status(500).json({ error: 'Failed to create rail' });
+        }
+    });
+    // DELETE /rails/:railIndex — remove a rail slot. Guarded: the rail must
+    // exist, hold no tickets, have no active job/loop run, no undecided PR
+    // delivery, and must not be the last remaining rail. Indices are identity —
+    // deleting a middle rail leaves a gap (never re-numbered).
+    router.delete('/:railIndex', (req, res) => {
+        const railIndex = parseInt(req.params.railIndex, 10);
+        if (isNaN(railIndex) || railIndex < 0 || railIndex >= rails_store_1.MAX_RAILS) {
+            res.status(400).json({ error: 'Invalid rail index' });
+            return;
+        }
+        const c = ctx(req);
+        try {
+            if (!(0, rails_store_1.railExists)(c.db, railIndex)) {
+                res.status(404).json({ error: 'Rail not found' });
+                return;
+            }
+            if ((0, rails_store_1.railCount)(c.db) <= 1) {
+                res.status(400).json({ error: 'cannot_delete_last_rail' });
+                return;
+            }
+            const hasActiveJob = Array.from(c.railJobs.values()).some((m) => m.railIndex === railIndex);
+            const hasActiveRun = Array.from(c.railLoopRuns.values()).some((m) => m.railIndex === railIndex);
+            if (hasActiveJob || hasActiveRun) {
+                res.status(409).json({ error: 'rail_active' });
+                return;
+            }
+            if ((0, rails_store_1.getRail)(c.db, railIndex).ticketIds.length > 0) {
+                res.status(409).json({ error: 'rail_not_empty' });
+                return;
+            }
+            const pending = (0, rail_pr_store_1.getActivePrDeliveryByRail)(c.db, railIndex);
+            if (pending) {
+                res.status(409).json({ error: 'pr_decision_pending', prDeliveryId: pending.id });
+                return;
+            }
+            (0, rails_store_1.deleteRail)(c.db, railIndex);
+            const msg = { type: 'rail.removed', projectId: c.project.id, railIndex };
+            c.broadcast(msg);
+            res.json({ ok: true, railIndex });
+        }
+        catch (err) {
+            console.error('[rails-router] delete rail error:', err);
+            res.status(500).json({ error: 'Failed to delete rail' });
+        }
+    });
     // PUT /rails/:railIndex/tickets — set ticket assignments for a rail
     router.put('/:railIndex/tickets', (req, res) => {
         const railIndex = parseInt(req.params.railIndex, 10);
-        if (isNaN(railIndex) || railIndex < 0) {
+        if (isNaN(railIndex) || railIndex < 0 || railIndex >= rails_store_1.MAX_RAILS) {
             res.status(400).json({ error: 'Invalid rail index' });
             return;
         }
@@ -132,7 +222,7 @@ function createRailsRouter() {
     // Body: { profileName: string | null } (null = force legacy mode for this rail)
     router.put('/:railIndex/profile', (req, res) => {
         const railIndex = parseInt(req.params.railIndex, 10);
-        if (isNaN(railIndex) || railIndex < 0) {
+        if (isNaN(railIndex) || railIndex < 0 || railIndex >= rails_store_1.MAX_RAILS) {
             res.status(400).json({ error: 'Invalid rail index' });
             return;
         }
@@ -161,7 +251,7 @@ function createRailsRouter() {
     // Body: { aiEngine: string | null } (null = use the project's primary provider)
     router.put('/:railIndex/engine', (req, res) => {
         const railIndex = parseInt(req.params.railIndex, 10);
-        if (isNaN(railIndex) || railIndex < 0) {
+        if (isNaN(railIndex) || railIndex < 0 || railIndex >= rails_store_1.MAX_RAILS) {
             res.status(400).json({ error: 'Invalid rail index' });
             return;
         }
@@ -194,7 +284,7 @@ function createRailsRouter() {
     // Body: { name: string | null } (empty/null clears it back to the default label)
     router.put('/:railIndex/name', (req, res) => {
         const railIndex = parseInt(req.params.railIndex, 10);
-        if (isNaN(railIndex) || railIndex < 0) {
+        if (isNaN(railIndex) || railIndex < 0 || railIndex >= rails_store_1.MAX_RAILS) {
             res.status(400).json({ error: 'Invalid rail index' });
             return;
         }
@@ -227,16 +317,29 @@ function createRailsRouter() {
     // POST /rails/:railIndex/launch — launch job(s) for a rail
     router.post('/:railIndex/launch', async (req, res) => {
         const railIndex = parseInt(req.params.railIndex, 10);
-        if (isNaN(railIndex) || railIndex < 0) {
+        if (isNaN(railIndex) || railIndex < 0 || railIndex >= rails_store_1.MAX_RAILS) {
             res.status(400).json({ error: 'Invalid rail index' });
             return;
         }
         let { mode = 'implement' } = req.body ?? {};
-        const { profileName, aiEngine, model, loopId, reasoning_effort } = req.body ?? {};
+        const { profileName, aiEngine, model, loopId: rawLoopId, reasoning_effort, originConversationId, originSurface } = req.body ?? {};
+        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.
+        // Both fields are optional; malformed values are rejected outright.
+        if (originConversationId !== undefined && originConversationId !== null) {
+            if (typeof originConversationId !== 'string' || !/^[A-Za-z0-9-]{1,64}$/.test(originConversationId)) {
+                res.status(400).json({ error: 'originConversationId must be 1-64 chars of [A-Za-z0-9-]' });
+                return;
+            }
+        }
+        if (originSurface !== undefined && originSurface !== 'dashboard' && originSurface !== 'agent-chat') {
+            res.status(400).json({ error: "originSurface must be 'dashboard' or 'agent-chat'" });
+            return;
+        }
         // rails-as-loops: a FACTORY loop id (`factory:implement` etc.) maps to its
-        // legacy mode and runs through the EXISTING engine (QueueManager) — the rail
-        // "picks a Loop", the plumbing is unchanged. A CUSTOM loop id keeps mode='loop'
-        // (LoopRunManager). Legacy callers that still send a bare `mode` are unchanged.
+        // legacy mode for validation/back-compat; the loop branch below still runs
+        // it through the LoopRunManager. A CUSTOM loop id keeps mode='loop'.
         if (typeof loopId === 'string' && (0, loop_factory_1.isFactoryLoopId)(loopId)) {
             const fmode = (0, loop_factory_1.factoryLoopMode)(loopId);
             if (!fmode) {
@@ -249,6 +352,15 @@ function createRailsRouter() {
             res.status(400).json({ error: 'mode must be "implement", "batch-implement", "ultracode" or "loop"' });
             return;
         }
+        // A bare legacy mode (MCP tools, mobile, direct REST — no loopId) must run
+        // through the SAME factory loop the dashboard sends, so worktree isolation
+        // and the ask-first PR flow apply identically regardless of the launch door.
+        // Without this, an agent-launched implement lands in the bare QueueManager
+        // branch: shared cwd, SPECRAILS_GIT_AUTO=false, no delivery row — stranded
+        // uncommitted work. Loops off ⇒ legacy QueueManager path, unchanged.
+        if ((0, feature_flags_1.isLoopsEnabled)() && (typeof loopId !== 'string' || !loopId) && mode !== 'loop') {
+            loopId = (0, loop_factory_1.factoryLoopForMode)(mode)?.id;
+        }
         if (mode === 'loop' && !(0, feature_flags_1.isLoopsEnabled)()) {
             res.status(403).json({ error: 'Loops are disabled on this server' });
             return;
@@ -261,8 +373,9 @@ function createRailsRouter() {
                 return;
             }
         }
-        // Interactive in-job chat is ON by default for every Freestyle (ultracode)
-        // job whenever the feature is enabled — the per-rail toggle is gone. A
+        // Interactive in-job chat is ON by default for EVERY claude job — the
+        // spawn-time gate in QueueManager (kill-switch + persistent-stdin
+        // capability) decides, so the launch no longer passes an explicit flag. A
         // legacy `interactive` body param is accepted and ignored (wire compat).
         const c = ctx(req);
         const rail = (0, rails_store_1.getRail)(c.db, railIndex);
@@ -270,6 +383,24 @@ function createRailsRouter() {
             res.status(400).json({ error: 'Rail has no tickets assigned' });
             return;
         }
+        // Concurrent-launch safety (parallel rails): a ticket already worked by an
+        // ACTIVE run — this rail relaunched mid-run, or the same ticket sitting on
+        // two rails — must not spawn a second concurrent writer. The per-ticket
+        // worktree path is keyed by ticketId, so a duplicate launch would silently
+        // reuse (and corrupt) the in-flight run's checkout. 409 so Launch-all and
+        // agent-driven fan-outs surface a clean per-rail skip instead of a clash.
+        const inFlightTickets = new Set();
+        for (const meta of c.railJobs.values())
+            for (const id of meta.ticketIds)
+                inFlightTickets.add(id);
+        for (const meta of c.railLoopRuns.values())
+            for (const id of meta.ticketIds)
+                inFlightTickets.add(id);
+        const inFlightOverlap = rail.ticketIds.filter((id) => inFlightTickets.has(id));
+        if (inFlightOverlap.length > 0) {
+            res.status(409).json({ error: 'tickets_in_flight', ticketIds: inFlightOverlap });
+            return;
+        }
         // AI engine precedence: explicit body param > stored rail engine > primary.
         // `undefined`/empty in both means "run on the project's primary provider".
         const requestedEngine = aiEngine === undefined ? (rail.aiEngine ?? undefined) : aiEngine;
@@ -386,6 +517,17 @@ function createRailsRouter() {
                 // so it is not isolated; anything that can write is.
                 const loopReadOnly = (0, loop_effect_1.classifyLoopEffect)(loopGraph) === 'read-only';
                 if ((0, rail_isolation_1.isolationApplies)({ loopsEnabled: (0, feature_flags_1.isLoopsEnabled)(), scope, ticketCount: rail.ticketIds.length, readOnly: loopReadOnly })) {
+                    // Relaunch collision (ask-first PR delivery): a still-undecided
+                    // delivery on this slot references the slot's ticket branches, and a
+                    // relaunch would append new commits to them (createWorktree resumes
+                    // existing branches). Block until the user resolves or discards it.
+                    if ((0, rail_isolation_1.isRailPrDeliveryEnabled)()) {
+                        const pending = (0, rail_pr_store_1.getActivePrDeliveryByRail)(c.db, railIndex);
+                        if (pending) {
+                            res.status(409).json({ error: 'pr_decision_pending', prDeliveryId: pending.id });
+                            return;
+                        }
+                    }
                     // 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);
@@ -397,7 +539,9 @@ function createRailsRouter() {
                         try {
                             const ids = await (0, rail_isolated_launch_1.launchIsolatedRail)({
                                 ctx: c, railIndex, ticketIds: [...rail.ticketIds], loopId, loopName, loopGraph,
-                                provider: loopProvider, model: loopModel, effort,
+                                provider: loopProvider, model: loopModel, effort, scope,
+                                originSurface: originSurface ?? 'dashboard',
+                                originConversationId: originConversationId ?? null,
                             });
                             res.status(202).json({ loopRunIds: ids, railIndex, mode, isolated: true });
                             return;
@@ -415,6 +559,36 @@ function createRailsRouter() {
                 const loopRunIds = [];
                 const launchLoopRun = (runId, ticketIds, spec) => {
                     c.railLoopRuns.set(runId, { railIndex, ticketIds });
+                    // Code-Explorer provenance for shared-cwd loop runs (isolated runs
+                    // record inside rail-isolated-launch): snapshot the REPO before the
+                    // run, diff + record at settle. Loop runs settle outside QueueManager,
+                    // so without this they leave no file_provenance at all. Best-effort;
+                    // diffs the repo (never the workspace) exactly like QueueManager.
+                    const provenanceRepoDir = loopExec.relocated && loopExec.repoDir ? loopExec.repoDir : loopExec.cwd;
+                    let provenanceSnapshot = null;
+                    if ((0, feature_flags_1.isCodeExplorerEnabled)()) {
+                        try {
+                            provenanceSnapshot = (0, file_provenance_1.snapshotWorkingTree)(provenanceRepoDir);
+                        }
+                        catch (err) {
+                            console.warn(`[rails-router] provenance snapshot failed: ${err.message}`);
+                        }
+                    }
+                    let provenanceRecorded = false;
+                    const recordRunProvenance = () => {
+                        if (provenanceRecorded)
+                            return;
+                        provenanceRecorded = true;
+                        (0, file_story_1.recordLoopRunProvenance)({
+                            db: c.db,
+                            projectId: c.project.id,
+                            runId,
+                            ticketId: ticketIds[0] ?? null,
+                            repoDir: provenanceRepoDir,
+                            snapshot: provenanceSnapshot,
+                            broadcast: (msg) => c.broadcast(msg),
+                        });
+                    };
                     c.loopRunManager
                         .run({
                         runId,
@@ -432,9 +606,13 @@ function createRailsRouter() {
                         model: loopModel,
                         effort,
                     })
-                        .then((r) => c.onLoopRunFinished(r.runId, r.outcome))
+                        .then((r) => {
+                        recordRunProvenance();
+                        c.onLoopRunFinished(r.runId, r.outcome);
+                    })
                         .catch((err) => {
                         console.error('[rails-router] loop run failed:', err);
+                        recordRunProvenance();
                         c.onLoopRunFinished(runId, 'failed');
                     });
                     loopRunIds.push(runId);
@@ -481,7 +659,9 @@ function createRailsRouter() {
                         profileName: null,
                         provider: 'claude',
                         ...(ultracodeModel ? { model: ultracodeModel } : {}),
-                        ...((0, feature_flags_1.isInteractiveJobsEnabled)() ? { interactive: true } : {}),
+                        // No explicit `interactive` — QueueManager's spawn-time default
+                        // (kill-switch + persistent-stdin capability) covers it, and the
+                        // decision survives a restart that way.
                     });
                     jobIds.push(job.id);
                     c.railJobs.set(job.id, { railIndex, mode, ticketIds: [ticketId] });
@@ -544,7 +724,7 @@ function createRailsRouter() {
     // POST /rails/:railIndex/stop — kill the running job for a rail
     router.post('/:railIndex/stop', (req, res) => {
         const railIndex = parseInt(req.params.railIndex, 10);
-        if (isNaN(railIndex) || railIndex < 0) {
+        if (isNaN(railIndex) || railIndex < 0 || railIndex >= rails_store_1.MAX_RAILS) {
             res.status(400).json({ error: 'Invalid rail index' });
             return;
         }
@@ -607,35 +787,42 @@ function createRailsRouter() {
         }
         res.json({ ok: true, jobIds: targetJobIds, loopRunIds: targetLoopRunIds, canceled: canceledCount });
     });
-    // POST /rails/pr-review — the product builder's Approve / Discard action on a
-    // draft PR a rail delivered (safe-pr-workflow). Approve promotes the draft to
-    // ready-for-review (hands off to the engineer's GitHub review); Discard closes
-    // it and drops the branch. specrails never merges — the engineer owns the merge.
-    router.post('/pr-review', async (req, res) => {
+    // POST /rails/pr-decision — the ONE decision action (safe-pr-review-flow) both
+    // surfaces (dashboard rail row + agent-chat card) call on a rail_pr_deliveries
+    // row: create-pr | publish | discard | poll-merge, compare-and-set-guarded by
+    // expectedDecision (a raced concurrent answer loses with 409 stale_decision).
+    // Replaces the stateless v1 POST /rails/pr-review passthrough. The route only
+    // validates and delegates — the action logic lives in rail-pr-decision.ts.
+    // specrails never merges — the engineer owns the merge.
+    router.post('/pr-decision', async (req, res) => {
         const c = ctx(req);
-        const prUrl = (req.body ?? {}).prUrl;
-        const action = (req.body ?? {}).action;
-        if (typeof prUrl !== 'string' || !/^https?:\/\/[^\s]+\/pull\/\d+$/.test(prUrl)) {
-            res.status(400).json({ error: 'prUrl must be a valid pull-request URL' });
+        const { prDeliveryId, action, expectedDecision } = req.body ?? {};
+        if (typeof prDeliveryId !== 'string' || !prDeliveryId) {
+            res.status(400).json({ error: 'prDeliveryId is required' });
             return;
         }
-        if (action !== 'ready' && action !== 'discard') {
-            res.status(400).json({ error: "action must be 'ready' or 'discard'" });
+        if (!(0, rail_pr_decision_1.isPrDecisionAction)(action)) {
+            res.status(400).json({ error: "action must be 'create-pr', 'publish', 'discard' or 'poll-merge'" });
+            return;
+        }
+        if (typeof expectedDecision !== 'string' || !expectedDecision) {
+            res.status(400).json({ error: 'expectedDecision is required' });
             return;
         }
-        const args = action === 'ready'
-            ? ['pr', 'ready', prUrl]
-            : ['pr', 'close', prUrl, '--delete-branch'];
         try {
-            const r = await pr_publisher_1.defaultExec.run('gh', args, c.project.path);
-            if (r.code !== 0) {
-                res.status(502).json({ error: `gh pr ${action} failed`, detail: (r.stderr.trim() || r.stdout.trim()).split('\n')[0] || `exit ${r.code}` });
-                return;
-            }
-            res.json({ ok: true, action });
+            const result = await (0, rail_pr_decision_1.executePrDecision)({
+                db: c.db,
+                project: { id: c.project.id, slug: c.project.slug, path: c.project.path },
+                git: worktree_manager_1.defaultGitRunner,
+                exec: pr_publisher_1.defaultExec,
+                broadcast: c.broadcast,
+                jiraSyncManager: c.jiraSyncManager,
+            }, { prDeliveryId, action, expectedDecision });
+            res.status(result.status).json(result.body);
         }
         catch (err) {
-            res.status(500).json({ error: 'pr-review failed', detail: err.message });
+            console.error('[rails-router] pr-decision error:', err);
+            res.status(500).json({ error: 'pr-decision failed', detail: err.message });
         }
     });
     return router;