specrails-desktop 2.64.1 → 2.65.0

package/server/dist/modules/delivery/runtime/rails-router.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.FLOW_SPEC_LOOP_ID = void 0;
 exports.normalizeRailMode = normalizeRailMode;
 exports.prDeliveryRevisionAllowed = prDeliveryRevisionAllowed;
 exports.createRailsRouter = createRailsRouter;
@@ -28,6 +29,7 @@ const spec_models_1 = require("../../specs/runtime/spec-models");
 const workspace_resolution_1 = require("../../../workspace-resolution");
 const agent_runtime_loader_1 = require("../../agent-runtime/runtime/agent-runtime-loader");
 const loop_factory_1 = require("../../loops/runtime/loop-factory");
+Object.defineProperty(exports, "FLOW_SPEC_LOOP_ID", { enumerable: true, get: function () { return loop_factory_1.FLOW_SPEC_LOOP_ID; } });
 const builtin_loops_1 = require("../../loops/runtime/builtin-loops");
 const loop_constants_1 = require("../../loops/runtime/loop-constants");
 const loop_command_catalog_1 = require("../../loops/runtime/loop-command-catalog");
@@ -36,12 +38,15 @@ const rail_isolation_1 = require("./rail-isolation");
 const rail_pr_store_1 = require("./rail-pr-store");
 const loop_effect_1 = require("../../loops/runtime/loop-effect");
 const review_packet_1 = require("./review-packet");
+const delivery_changes_1 = require("./delivery-changes");
 const delivery_evidence_1 = require("./delivery-evidence");
 const loop_definition_recovery_1 = require("../../loops/runtime/loop-definition-recovery");
 const accept_ladder_1 = require("../../execution/runtime/accept-ladder");
 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 isolated_worktree_1 = require("./isolated-worktree");
+const flow_worktree_handoff_1 = require("./flow-worktree-handoff");
 const rail_relaunch_1 = require("./rail-relaunch");
 const worktree_manager_1 = require("../../../worktree-manager");
 const integration_branch_1 = require("../../../integration-branch");
@@ -58,6 +63,7 @@ const repo_lock_1 = require("../../../repo-lock");
 const agent_chat_registry_1 = require("../../missions/runtime/agent-chat-registry");
 const mission_run_notify_1 = require("../../missions/runtime/mission-run-notify");
 const agent_runtime_controls_router_1 = require("../../agent-runtime/runtime/agent-runtime-controls-router");
+const triage_1 = require("../../specs/domain/triage");
 const ticket_store_1 = require("../../specs/runtime/ticket-store");
 const spec_addenda_1 = require("../../specs/runtime/spec-addenda");
 const process_admission_1 = require("../../../process-admission");
@@ -66,8 +72,19 @@ const VALID_MODES = new Set(['implement', 'freestyle', 'loop']);
  *  ticket in one aggregate run, so stored/agent/mobile `batch-implement` (or
  *  `batch`) requests are normalized to it at the HTTP boundary. */
 const REMOVED_BATCH_MODES = new Set(['batch-implement', 'batch']);
+/** Pre-rename name of Freestyle. Older Companion builds still send
+ *  `mode: 'ultracode'`; accept it so un-updated phones keep launching. */
+const LEGACY_FREESTYLE_MODE = 'ultracode';
 function normalizeRailMode(mode) {
-    return typeof mode === 'string' && REMOVED_BATCH_MODES.has(mode) ? 'implement' : mode;
+    if (typeof mode !== 'string')
+        return mode;
+    if (REMOVED_BATCH_MODES.has(mode))
+        return 'implement';
+    if (mode === LEGACY_FREESTYLE_MODE) {
+        console.info(`[rails-router] legacy mode "${LEGACY_FREESTYLE_MODE}" accepted as "freestyle"`);
+        return 'freestyle';
+    }
+    return mode;
 }
 function prDeliveryContinuesTickets(delivery, ticketIds) {
     if (delivery.decision !== 'pr_draft' && delivery.decision !== 'pr_ready')
@@ -155,6 +172,18 @@ function onReviewTicketIds(c) {
         return new Set();
     }
 }
+/** Spec triage (launch-triage): the loop recommended by the first triaged spec
+ *  of the rail, in rail order (best-effort: an unreadable store ⇒ null). */
+function recommendedLoopForRail(c, ticketIds) {
+    try {
+        const execution = (0, workspace_resolution_1.resolveProjectExecution)({ slug: c.project.slug, path: c.project.path });
+        const store = (0, ticket_store_1.readStore)(execution.relocated ? execution.ticketsPath : (0, ticket_store_1.resolveTicketStoragePath)(c.project.path));
+        return (0, triage_1.recommendedLoopForTickets)(ticketIds.map((id) => store.tickets[String(id)]));
+    }
+    catch {
+        return null;
+    }
+}
 /** Map an engine-availability refusal to the launch's 409 body; rethrow others. */
 async function engineSupportRejection(manager, graph, loopId) {
     try {
@@ -250,7 +279,11 @@ function createRailsRouter() {
                             ? 'on_review'
                             : 'free',
             }));
-            res.json({ rails: railsWithAvailability, activeJobs, activeLoopRuns, prDeliveries });
+            // review-wip-limit: the project's limit and the deliveries counting
+            // against it (absent in bare contexts without the gate).
+            const wip = c.reviewWipGate?.status();
+            const reviewWip = wip ? { limit: wip.limit, pending: wip.pending, reached: wip.limit !== null && wip.pending.length + wip.reserved >= wip.limit } : undefined;
+            res.json({ rails: railsWithAvailability, activeJobs, activeLoopRuns, prDeliveries, ...(reviewWip ? { reviewWip } : {}) });
         }
         catch (err) {
             console.error('[rails-router] get rails error:', err);
@@ -553,6 +586,10 @@ function createRailsRouter() {
         // Non-string values fail the VALID_MODES check below.
         let mode = normalizeRailMode(req.body?.mode ?? 'implement');
         const { repositoryIds: rawRepositoryIds, workspaceSelection: rawWorkspaceSelection, baseDeliveryIds, profileName, aiEngine, model, loopId: rawLoopId, reasoning_effort, originConversationId, originSurface, targetPrNumber, revisionOfDeliveryId, revisionNote, baseBranch: rawBaseBranch, followUp: rawFollowUp } = req.body ?? {};
+        // Per-launch soft cap (USD): > 0 caps this run, 0 waives the default. The
+        // sample-project first run sends it so a newcomer's first run is cost-bounded.
+        const rawRunCap = req.body?.runCapUsd;
+        const runCapUsd = typeof rawRunCap === 'number' && Number.isFinite(rawRunCap) && rawRunCap >= 0 ? rawRunCap : undefined;
         // PR review follow-up (pr-follow-up-fixes): a typed, bounded, FROZEN scope
         // for "resolve these review comments". It rides the delivery row and every
         // ai-step prompt — never the spec, whose description Jira-linked projects
@@ -614,6 +651,43 @@ function createRailsRouter() {
         }
         const explicitLoop = (typeof rawLoopId === 'string' && rawLoopId.length > 0) || req.body?.mode != null;
         let loopId = rawLoopId;
+        // Flow hand-off (Flow mode): the launch adopts the Flow's own worktree.
+        // Only the Flow module starts it, after freezing HEAD; it never combines
+        // with relaunch, revision, PR targets, follow-ups or stacked bases.
+        const rawFlowId = req.body?.flowId;
+        let flowWorktree = null;
+        if (rawFlowId !== undefined && rawFlowId !== null) {
+            if (typeof rawFlowId !== 'string' || !/^[A-Za-z0-9-]{1,64}$/.test(rawFlowId)) {
+                res.status(400).json({ error: 'invalid_flow_id' });
+                return;
+            }
+            if (relaunchSource || revisionOfDeliveryId || targetPrNumber !== undefined && targetPrNumber !== null || followUp || baseBranch || baseDeliveryIds !== undefined) {
+                res.status(400).json({ error: 'flow_handoff_incompatible', detail: 'A Flow hand-off launches the Flow spec on its own worktree only' });
+                return;
+            }
+            if (!(0, feature_flags_1.isLoopsEnabled)()) {
+                res.status(409).json({ error: 'flow_requires_isolation', detail: 'A Flow hand-off needs Loops and worktree isolation' });
+                return;
+            }
+            if (!c.flowHandOff) {
+                res.status(409).json({ error: 'feature_unavailable', detail: 'Flow is not available in this project' });
+                return;
+            }
+            try {
+                flowWorktree = c.flowHandOff.resolve(rawFlowId);
+            }
+            catch (err) {
+                if (err instanceof flow_worktree_handoff_1.FlowHandOffNotReadyError) {
+                    res.status(409).json({ error: err.code, detail: err.message });
+                    return;
+                }
+                throw err;
+            }
+        }
+        else if (rawLoopId === loop_factory_1.FLOW_SPEC_LOOP_ID) {
+            res.status(400).json({ error: 'flow_id_required', detail: 'The Flow -> Spec loop is launched from a Flow hand-off' });
+            return;
+        }
         // 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.
@@ -636,7 +710,7 @@ function createRailsRouter() {
                 res.status(404).json({ error: 'Factory loop not found' });
                 return;
             }
-            loopId = (0, loop_factory_1.getFactoryLoop)(loopId).id; // canonicalize saved legacy aliases
+            loopId = (0, loop_factory_1.canonicalFactoryLoopId)(loopId); // canonicalize saved legacy aliases
             mode = fmode;
         }
         if (relaunchSource)
@@ -688,6 +762,33 @@ function createRailsRouter() {
             }
             throw err;
         }
+        // Daily budget (rail-loop-budget-guard): the same project/app-wide budget
+        // state the queue auto-pause enforces. Every launch door (dashboard Play,
+        // Launch all, mission cards, MCP launch/launch_all, mobile, milestone
+        // chains, relaunch) reaches this route, so one check spawns nothing.
+        const budgetRejection = c.dailyBudgetRejection?.() ?? null;
+        if (budgetRejection) {
+            res.status(409).json(budgetRejection);
+            return;
+        }
+        // Review WIP limit (review-wip-limit): same doors, same "spawn nothing"
+        // contract. Continuations of an existing delivery add no review work and
+        // pass; a new delivery holds a slot until this request has answered (its
+        // delivery row then exists), so parallel launches cannot overshoot.
+        const reviewWip = c.reviewWipGate?.admit(railIndex, {
+            revisionOfDeliveryId: typeof revisionOfDeliveryId === 'string' ? revisionOfDeliveryId : null,
+            relaunchOfDelivery: Boolean(relaunchSource?.delivery),
+            targetsExistingPr: typeof targetPrNumber === 'number' || Boolean(followUp),
+            railHasActiveDelivery: Boolean((0, rail_pr_store_1.getActivePrDeliveryByRail)(c.db, railIndex)),
+        });
+        if (reviewWip && !reviewWip.ok) {
+            res.status(409).json(reviewWip.rejection);
+            return;
+        }
+        if (reviewWip) {
+            res.once('finish', reviewWip.release);
+            res.once('close', reviewWip.release);
+        }
         const storedRail = (0, rails_store_1.getRail)(c.db, railIndex);
         const rail = relaunchSource ? { ...storedRail, ticketIds: [...relaunchSource.ticketIds],
             profileName: typeof profileName === 'string' ? profileName : null,
@@ -701,6 +802,10 @@ function createRailsRouter() {
             res.status(400).json({ error: 'Rail has no tickets assigned' });
             return;
         }
+        if (flowWorktree && (rail.ticketIds.length !== 1 || rail.ticketIds[0] !== flowWorktree.ticketId)) {
+            res.status(409).json({ error: 'flow_rail_mismatch', detail: 'The rail must carry exactly the Flow spec' });
+            return;
+        }
         // A durable delta defaults to Quick SDD when the caller has not chosen a workflow.
         // Revision is a delivery-continuation mechanism, not the implementation loop.
         const launchAddenda = (0, spec_addenda_1.planSpecAddendaAt)((0, spec_addenda_1.ticketStorePathForProject)(c.project), rail.ticketIds);
@@ -910,6 +1015,11 @@ function createRailsRouter() {
                     // last Published snapshot while an edit is Draft); otherwise the
                     // current code default for this Core.
                     const f = builtinSelection;
+                    // Flow -> Spec exists only on a Core that advertises `deriveChange`.
+                    if (!f && loopId === loop_factory_1.FLOW_SPEC_LOOP_ID) {
+                        res.status(409).json({ error: 'engine_unsupported', detail: 'Update Core to run the Flow → Spec loop (derive-change).' });
+                        return;
+                    }
                     if (!f) {
                         res.status(404).json({ error: 'Factory loop not found' });
                         return;
@@ -1159,6 +1269,15 @@ function createRailsRouter() {
                     res.status(409).json({ error: 'repository_isolation_required', detail: 'Selected repositories require worktree isolation for this loop.' });
                     return;
                 }
+                // A Flow runs in exactly its own repository: the primary (no group), or
+                // the one non-primary member its worktree belongs to.
+                const flowRepositoryScope = !flowWorktree ? true : flowWorktree.repositoryId
+                    ? repositoryIds.length === 1 && repositoryIds[0] === flowWorktree.repositoryId
+                    : !requiresRepositoryIsolation;
+                if (flowWorktree && (!useIsolation || !flowRepositoryScope)) {
+                    res.status(409).json({ error: 'flow_requires_isolation', detail: 'A Flow hand-off runs only on its own worktree, in the repository it belongs to.' });
+                    return;
+                }
                 if (relaunchSource?.delivery && !useIsolation) {
                     res.status(409).json({ error: 'relaunch_isolation_required', detail: 'The original attempt was isolated; its retry must also use an isolated worktree.',
                         action: 'Restore worktree isolation and the original workflow before retrying.' });
@@ -1185,6 +1304,10 @@ function createRailsRouter() {
                     // unborn HEAD can't be branched). Fall back (with a message) otherwise.
                     const status = requiresRepositoryIsolation ? 'ok' : await (0, worktree_manager_1.repoIsolationStatus)(worktree_manager_1.defaultGitRunner, c.project.path);
                     if (status !== 'ok') {
+                        if (flowWorktree) {
+                            res.status(409).json({ error: 'flow_requires_isolation', detail: `worktree isolation is unavailable (${status})` });
+                            return;
+                        }
                         if (baseBranch) {
                             res.status(400).json({ error: 'base_branch_requires_isolation', detail: `baseBranch requires worktree isolation, which is unavailable (${status})` });
                             return;
@@ -1221,11 +1344,13 @@ function createRailsRouter() {
                                 broadcastRailUpdated(c, railIndex, 'tickets');
                             const ids = await (0, rail_isolated_launch_1.launchIsolatedRail)({
                                 launchConfig,
+                                loopChoice: { recommendedLoop: recommendedLoopForRail(c, rail.ticketIds), chosenLoop: loopId },
                                 runtimeProviderOverride,
                                 ctx: c, railIndex, ticketIds: [...rail.ticketIds], repositoryIds, workspaceSelection, ...repositoryBases, loopId, loopName, loopGraph,
                                 provider: loopProvider, model: loopModel, effort, scope,
                                 ...(deciderEngine ? { deciderEngine } : {}),
                                 profileName: resolvedProfile,
+                                ...(runCapUsd !== undefined ? { runCapUsd } : {}),
                                 originSurface: originSurface ?? 'dashboard',
                                 originConversationId: originConversationId ?? null,
                                 ...(baseBranch ? { baseBranch } : {}),
@@ -1252,6 +1377,7 @@ function createRailsRouter() {
                                 ...(revisionRequest ? { revision: revisionRequest } : {}),
                                 ...(retryOfDelivery ? { retryOfDelivery } : {}),
                                 ...(followUp ? { followUp } : {}),
+                                ...(flowWorktree ? { requiredFlowWorktree: flowWorktree } : {}),
                             });
                             res.status(202).json({ loopRunIds: ids, railIndex, mode, loopId, prDeliveryId: (0, rail_pr_store_1.getActivePrDeliveryByRail)(c.db, railIndex)?.id ?? null, isolated: true, ...(followUp ? { followUp: { id: followUp.id, version: followUp.version, hash: followUp.hash } } : {}) });
                             return;
@@ -1271,6 +1397,14 @@ function createRailsRouter() {
                             // Explicit-target validation failures are the USER's answer being
                             // unusable — fail closed with the machine-readable code; never
                             // fall back to a fresh shared-cwd run next to the designated PR.
+                            if (err instanceof isolated_worktree_1.RepositoryHasNoCommitsError) {
+                                res.status(409).json({ error: err.code, detail: err.message });
+                                return;
+                            }
+                            if (err instanceof flow_worktree_handoff_1.FlowWorktreeMismatchError) {
+                                res.status(409).json({ error: err.code, detail: err.message });
+                                return;
+                            }
                             if (err instanceof active_pr_continuation_1.ExplicitPrTargetError) {
                                 res.status(err.code === 'target_pr_not_found' ? 404 : 409).json({
                                     error: err.code,
@@ -1394,6 +1528,7 @@ function createRailsRouter() {
                         effort,
                         ...(deciderEngine ? { deciderEngine } : {}),
                         profileName: resolvedProfile,
+                        ...(runCapUsd !== undefined ? { runCapUsd } : {}),
                         ...(claimedAddenda.briefing ? { addenda: { ids: claimedAddenda.snapshot.map((e) => e.id), briefing: claimedAddenda.briefing } } : {}),
                     })
                         .then((r) => {
@@ -1647,7 +1782,7 @@ function createRailsRouter() {
                 if (existing) {
                     const pipelineDir = path_1.default.join((0, workspace_resolution_1.resolveProjectExecution)({ slug: c.project.slug, path: c.project.path }).specrailsDir, 'pipeline');
                     const definitionStatuses = await (0, loop_definition_recovery_1.probeDefinitionRuns)({ db: c.db, cwd: c.project.path, env: process.env }, existing.units.filter(unit => !unit.runtime && unit.runId && (0, loop_runs_store_1.getLoopRun)(c.db, unit.runId)?.engine_version === 2).map(unit => unit.runId), true);
-                    const healed = (0, delivery_evidence_1.healRuntimeEvidence)(existing, pipelineDir, {}, definitionStatuses);
+                    const healed = (0, delivery_evidence_1.healRuntimeEvidence)(existing, pipelineDir, {}, definitionStatuses, { reviewBrief: await (0, delivery_evidence_1.coreAnnouncesReviewBrief)() });
                     if (healed) {
                         (0, rail_pr_store_1.updatePrDeliverySettleEvidence)(c.db, row.id, healed);
                         row = { ...row, settle_evidence: JSON.stringify(healed) };
@@ -1657,7 +1792,7 @@ function createRailsRouter() {
             catch (err) {
                 console.warn('[rails-router] packet evidence heal skipped:', err instanceof Error ? err.message : String(err));
             }
-            const packet = (0, review_packet_1.composeReviewPacket)({ db: c.db, row, ...(frozenRepository ? { repositoryId: frozenRepository.repositoryId, includeLegacyProvenance: frozenRepository.repositoryId === manifest?.primaryRepositoryId } : {}) });
+            const packet = (0, review_packet_1.composeReviewPacket)({ db: c.db, row, flowSettlement: c.flow?.settlementForDelivery(row.id) ?? null, ...(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: frozenRepository?.sourcePath ?? c.project.path, exec: pr_publisher_1.defaultExec });
@@ -1668,6 +1803,87 @@ function createRailsRouter() {
             res.status(500).json({ error: 'packet composition failed', detail: err.message });
         }
     });
+    // GET /rails/pr-deliveries/:id/changes[?repositoryId=&source=] — the review
+    // packet's Changes tab: the delivery's head vs its merge-base with the base
+    // branch (file list + counts + hashes) and the annotations the delivery already
+    // holds. GET .../changes/file?path=&full=1 parses ONE file lazily. Read-only;
+    // `path` is a lookup key against the diff's own listing, never a pathspec.
+    const changesScope = (req, res) => {
+        if (!(0, feature_flags_1.isReviewPacketEnabled)()) {
+            res.status(404).json({ error: 'Not Found' });
+            return null;
+        }
+        const c = ctx(req);
+        let row = (0, rail_pr_store_1.getPrDelivery)(c.db, req.params.prDeliveryId);
+        if (!row) {
+            res.status(404).json({ error: 'Delivery not found' });
+            return null;
+        }
+        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 null;
+        }
+        const repositoryId = req.query.repositoryId;
+        if (repositoryId !== undefined && (typeof repositoryId !== 'string' || !repositoryId)) {
+            res.status(400).json({ error: 'Invalid repositoryId' });
+            return null;
+        }
+        const source = req.query.source;
+        if (source !== undefined && (typeof source !== 'string' || !/^(delivery|ticket:\d+)$/.test(source))) {
+            res.status(400).json({ error: 'Invalid source' });
+            return null;
+        }
+        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 null;
+            }
+        }
+        const manifest = (0, multi_repo_execution_store_1.readExecutionManifest)(parent.execution_manifest);
+        const frozen = row.repository_id ? manifest?.repositories.find((repository) => repository.repositoryId === row.repository_id && repository.sourcePath === row.repository_path) : undefined;
+        if (row.parent_delivery_id && !frozen) {
+            res.status(409).json({ error: 'Repository delivery has no frozen source path' });
+            return null;
+        }
+        return { c, row, repoDir: frozen?.sourcePath ?? c.project.path, repositoryId: frozen?.repositoryId ?? null, source: source ?? null };
+    };
+    router.get('/pr-deliveries/:prDeliveryId/changes', async (req, res) => {
+        const scope = changesScope(req, res);
+        if (!scope)
+            return;
+        try {
+            const changes = await (0, delivery_changes_1.composeDeliveryChanges)({ row: scope.row, repoDir: scope.repoDir, sourceId: scope.source, repositoryId: scope.repositoryId });
+            res.json({ prDeliveryId: scope.row.id, repositoryId: scope.repositoryId, changes });
+        }
+        catch (err) {
+            console.error('[rails-router] changes composition failed:', err);
+            res.status(500).json({ error: 'changes composition failed' });
+        }
+    });
+    router.get('/pr-deliveries/:prDeliveryId/changes/file', async (req, res) => {
+        const scope = changesScope(req, res);
+        if (!scope)
+            return;
+        const filePath = req.query.path;
+        if (typeof filePath !== 'string' || !filePath || filePath.length > 1000 || filePath.includes('\0')) {
+            res.status(400).json({ error: 'Invalid path' });
+            return;
+        }
+        try {
+            const result = await (0, delivery_changes_1.composeFileDiff)({ row: scope.row, repoDir: scope.repoDir, sourceId: scope.source, repositoryId: scope.repositoryId, path: filePath, full: req.query.full === '1' });
+            if (!result.ok) {
+                res.status(result.status).json({ error: result.error });
+                return;
+            }
+            res.json({ prDeliveryId: scope.row.id, diff: result.diff });
+        }
+        catch (err) {
+            console.error('[rails-router] file diff failed:', err);
+            res.status(500).json({ error: 'file diff failed' });
+        }
+    });
     // 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/dismiss | poll/reopen | merge-local |
@@ -1764,6 +1980,52 @@ function createRailsRouter() {
             res.status(500).json({ error: 'pr-decision failed', detail: err.message });
         }
     });
+    // POST /rails/pr-local-changes/{restore,bring-back,discard-branch} — the
+    // person's uncommitted work "Integrate locally" saved as a stash (by commit
+    // sha). "restore" re-applies it (a clean apply drops it; a conflict keeps it
+    // and Specrails restores it on its own branch + worktree). "bring-back"
+    // fast-forwards the target to the reviewed restore commit and only then
+    // drops the stash; "discard-branch" removes the restore branch, keeping the
+    // stash. Each takes the repository lock and refuses while a decision lease
+    // is held (proactive-local-integration).
+    const localChangesActions = {
+        restore: rail_pr_decision_1.runRestoreLocalChanges,
+        'bring-back': rail_pr_decision_1.runBringBackLocalChanges,
+        'discard-branch': rail_pr_decision_1.runDiscardRestoreBranch,
+    };
+    for (const [action, run] of Object.entries(localChangesActions)) {
+        router.post(`/pr-local-changes/${action}`, async (req, res) => {
+            const c = ctx(req);
+            const { prDeliveryId } = req.body ?? {};
+            if (typeof prDeliveryId !== 'string' || !prDeliveryId) {
+                res.status(400).json({ error: 'prDeliveryId is required' });
+                return;
+            }
+            try {
+                const admission = (0, process_admission_1.captureProcessAdmission)(c.project.id);
+                const result = await run({
+                    db: c.db,
+                    project: { id: c.project.id, slug: c.project.slug, path: c.project.path },
+                    git: worktree_manager_1.defaultGitRunner,
+                    exec: pr_publisher_1.defaultExec,
+                    broadcast: c.broadcast,
+                    jiraSyncManager: c.jiraSyncManager,
+                    assertAdmission: () => admission.assertCurrent(),
+                }, prDeliveryId);
+                const current = (0, rail_pr_store_1.getPrDelivery)(c.db, prDeliveryId);
+                const shown = current?.parent_delivery_id ? (0, rail_pr_store_1.getPrDelivery)(c.db, current.parent_delivery_id) : current;
+                res.status(result.status).json({ ...result.body, ...(shown ? { snapshot: (0, rail_pr_store_1.toPrDeliverySnapshot)(shown) } : {}) });
+            }
+            catch (err) {
+                if (err instanceof process_admission_1.ProcessAdmissionClosedError) {
+                    res.status(409).json({ error: 'project_recovery_in_progress' });
+                    return;
+                }
+                console.error(`[rails-router] local changes ${action} error:`, err);
+                res.status(500).json({ error: `${action} failed`, detail: err.message });
+            }
+        });
+    }
     // POST /rails/pr-checkout — move the user's main checkout to the delivered PR
     // branch. This is intentionally separate from PR decisions: it does not accept,
     // publish, discard, or merge anything. It only releases Specrails-managed

package/server/dist/modules/delivery/runtime/review-brief.js

@@ -0,0 +1,208 @@
+"use strict";
+/**
+ * The reviewer's risk brief (Core capability `reviewBrief: 1`, contract 5.3):
+ * an advisory "what to look at" record the runtime reviewer writes next to its
+ * verdict. Desktop harvests it at settle into `settle_evidence`, renders it
+ * first in the review packet, summarizes it in the PR body and shows the top
+ * risk on the mission / delivery cards.
+ *
+ * Pure module: tolerant normalization and summaries only. Every field is
+ * optional on the wire (older reviewers, custom reviewer definitions), so a
+ * malformed entry is dropped and counted rather than failing the harvest; the
+ * approval gate never reads the brief, and neither does any Desktop decision.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REVIEW_RISK_SEVERITIES = exports.REVIEW_BRIEF_RISK_LIMIT = exports.REVIEW_BRIEF_FILE = void 0;
+exports.normalizeReviewBrief = normalizeReviewBrief;
+exports.sortRisks = sortRisks;
+exports.isEmptyReviewBrief = isEmptyReviewBrief;
+exports.parseReviewBriefRecord = parseReviewBriefRecord;
+exports.reviewBriefFromReviewerOutput = reviewBriefFromReviewerOutput;
+exports.summarizeReviewBriefs = summarizeReviewBriefs;
+exports.buildWhatToLookAt = buildWhatToLookAt;
+exports.REVIEW_BRIEF_FILE = 'review-brief.json';
+exports.REVIEW_BRIEF_RISK_LIMIT = 5;
+const LIST_LIMIT = 20;
+const TEXT_LIMIT = 2000;
+const DIAGNOSTIC_LIMIT = 600;
+exports.REVIEW_RISK_SEVERITIES = ['high', 'medium', 'low'];
+const INVARIANT_STATUSES = ['kept', 'changed', 'at-risk'];
+const SEVERITY_RANK = { high: 0, medium: 1, low: 2 };
+function isRecord(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+function text(value, cap = TEXT_LIMIT) {
+    return typeof value === 'string' && value.trim() ? value.trim().slice(0, cap) : null;
+}
+function list(value, parse, counter) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        counter.dropped++;
+        return [];
+    }
+    const out = [];
+    for (const item of value) {
+        const parsed = parse(item);
+        if (parsed === null)
+            counter.dropped++;
+        else if (out.length < LIST_LIMIT)
+            out.push(parsed);
+    }
+    return out;
+}
+/**
+ * Tolerant normalization of a brief object. Returns null when the value is not
+ * an object at all; otherwise a brief with every list present. Entries missing
+ * their key text (or carrying an unknown severity) are dropped and counted —
+ * a risk without a severity cannot be ordered honestly.
+ */
+function normalizeReviewBrief(value) {
+    if (!isRecord(value))
+        return null;
+    const counter = { dropped: 0 };
+    const behaviourChanges = list(value.behaviourChanges, (item) => {
+        if (!isRecord(item))
+            return null;
+        const what = text(item.what);
+        return what ? { what, where: text(item.where), userVisible: typeof item.userVisible === 'boolean' ? item.userVisible : null } : null;
+    }, counter);
+    const invariantsTouched = list(value.invariantsTouched, (item) => {
+        if (!isRecord(item))
+            return null;
+        const invariant = text(item.invariant);
+        const status = INVARIANT_STATUSES.includes(item.status) ? item.status : null;
+        return invariant ? { invariant, evidence: text(item.evidence), status } : null;
+    }, counter);
+    const untested = list(value.untested, (item) => {
+        if (!isRecord(item))
+            return null;
+        const filePath = text(item.path);
+        return filePath ? { path: filePath, why: text(item.why) } : null;
+    }, counter);
+    const risks = list(value.risks, (item) => {
+        if (!isRecord(item))
+            return null;
+        const whatToLookAt = text(item.whatToLookAt);
+        if (!whatToLookAt || !exports.REVIEW_RISK_SEVERITIES.includes(item.severity))
+            return null;
+        return { severity: item.severity, area: text(item.area, 40), whatToLookAt, ref: text(item.ref) };
+    }, counter);
+    const humanChecks = list(value.humanChecks, (item) => text(item), counter);
+    const divergences = list(value.divergences, (item) => {
+        if (!isRecord(item))
+            return null;
+        const capability = text(item.capability), requirement = text(item.requirement), observed = text(item.observed);
+        return capability && requirement && observed ? { capability, requirement, observed } : null;
+    }, counter);
+    return {
+        brief: { behaviourChanges, invariantsTouched, untested, risks: sortRisks(risks).slice(0, exports.REVIEW_BRIEF_RISK_LIMIT), humanChecks, divergences },
+        dropped: counter.dropped,
+    };
+}
+/** Stable severity order: high, medium, low; original order within a severity. */
+function sortRisks(risks) {
+    return risks.map((risk, index) => ({ risk, index }))
+        .sort((a, b) => SEVERITY_RANK[a.risk.severity] - SEVERITY_RANK[b.risk.severity] || a.index - b.index)
+        .map((entry) => entry.risk);
+}
+function isEmptyReviewBrief(brief) {
+    return brief.behaviourChanges.length === 0 && brief.invariantsTouched.length === 0 && brief.untested.length === 0
+        && brief.risks.length === 0 && brief.humanChecks.length === 0 && brief.divergences.length === 0;
+}
+function score(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+/**
+ * Read Core's `review-brief.json` record (`{schemaVersion:1, change, approved,
+ * score, recordedAt, brief|null, diagnostic?}`). Returns null when there is no
+ * record; an unreadable or unknown-version record becomes a record without a
+ * brief whose diagnostic says so, so the packet never silently loses it.
+ */
+function parseReviewBriefRecord(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return unreadableRecord('pipeline', 'The review brief file is not valid JSON.');
+    }
+    if (!isRecord(parsed) || parsed.schemaVersion !== 1) {
+        return unreadableRecord('pipeline', 'The review brief file has an unsupported schema version.');
+    }
+    return recordFrom('pipeline', parsed.brief, parsed.diagnostic, {
+        approved: typeof parsed.approved === 'boolean' ? parsed.approved : null,
+        score: score(parsed.score),
+        recordedAt: text(parsed.recordedAt, 64),
+    });
+}
+function unreadableRecord(source, diagnostic) {
+    return { source, approved: null, score: null, recordedAt: null, brief: null, diagnostic, droppedEntries: 0 };
+}
+function recordFrom(source, rawBrief, rawDiagnostic, verdict) {
+    const normalized = rawBrief === null || rawBrief === undefined ? null : normalizeReviewBrief(rawBrief);
+    const malformed = rawBrief !== null && rawBrief !== undefined && normalized === null;
+    return {
+        source,
+        ...verdict,
+        brief: normalized?.brief ?? null,
+        diagnostic: text(rawDiagnostic, DIAGNOSTIC_LIMIT) ?? (malformed ? 'The review brief is not an object.' : null),
+        droppedEntries: normalized?.dropped ?? 0,
+    };
+}
+/**
+ * Brief carried by a reviewer output object (engine 2 piece output `review`,
+ * a reviewer implementation step, or a reviewer role turn). Returns null when
+ * the output carries neither a brief nor a brief diagnostic (older Core).
+ */
+function reviewBriefFromReviewerOutput(output, source = 'definition') {
+    if (!isRecord(output))
+        return null;
+    if (!('brief' in output) && !('briefDiagnostic' in output))
+        return null;
+    return recordFrom(source, output.brief, output.briefDiagnostic, {
+        approved: typeof output.approved === 'boolean' ? output.approved : null,
+        score: score(output.score),
+        recordedAt: null,
+    });
+}
+/** Summarize the brief records of one delivery; null when no unit carries one. */
+function summarizeReviewBriefs(records) {
+    const present = records.filter((record) => !!record);
+    if (present.length === 0)
+        return null;
+    const risks = sortRisks(present.flatMap((record) => record.brief?.risks ?? []));
+    return {
+        highCount: risks.filter((risk) => risk.severity === 'high').length,
+        mediumCount: risks.filter((risk) => risk.severity === 'medium').length,
+        lowCount: risks.filter((risk) => risk.severity === 'low').length,
+        top: risks[0] ?? null,
+        diagnostic: present.some((record) => record.diagnostic !== null),
+    };
+}
+/** Merge every unit's brief into the packet section; null when there is nothing to show. */
+function buildWhatToLookAt(units) {
+    const out = { risks: [], behaviourChanges: [], invariantsTouched: [], untested: [], humanChecks: [], divergences: [], diagnostics: [], droppedEntries: 0 };
+    for (const unit of units) {
+        const record = unit.reviewBrief;
+        if (!record)
+            continue;
+        const ticketId = unit.ticketId;
+        if (record.diagnostic)
+            out.diagnostics.push({ ticketId, message: record.diagnostic });
+        out.droppedEntries += record.droppedEntries || 0;
+        const brief = record.brief;
+        if (!brief)
+            continue;
+        out.risks.push(...brief.risks.map((entry) => ({ ...entry, ticketId })));
+        out.behaviourChanges.push(...brief.behaviourChanges.map((entry) => ({ ...entry, ticketId })));
+        out.invariantsTouched.push(...brief.invariantsTouched.map((entry) => ({ ...entry, ticketId })));
+        out.untested.push(...brief.untested.map((entry) => ({ ...entry, ticketId })));
+        out.humanChecks.push(...brief.humanChecks.map((entry) => ({ text: entry, ticketId })));
+        out.divergences.push(...brief.divergences.map((entry) => ({ ...entry, ticketId })));
+    }
+    out.risks = sortRisks(out.risks);
+    const empty = out.risks.length + out.behaviourChanges.length + out.invariantsTouched.length + out.untested.length
+        + out.humanChecks.length + out.divergences.length + out.diagnostics.length === 0;
+    return empty ? null : out;
+}