specrails-desktop 2.48.0 → 2.49.0

package/server/dist/mcp/guide.js

@@ -335,6 +335,13 @@ can run Contract Refine require AI-spawn, including Explore conversions.
   \`summary\`, \`provenance\`, \`diff\`. There is no MCP write path to files.
   Start with content search to find behavior and tests, then read exact ranges.
   Truncated scans or skipped files do not prove that a symbol is absent.
+- **Run failures & recovery**: \`specrails_jobs(runtime_runs, jobId)\` reads
+  why a run stopped and what it offers (\`canResume\`, \`recoverableSteps\`,
+  \`pendingApproval\`, \`pendingQuestion\`); \`runtime_evidence\` the durable
+  evidence. Act only on the user's confirmation: \`runtime_resume\` /
+  \`runtime_recover\` (ai-spawn), \`runtime_approve\` / \`runtime_settle\` /
+  \`runtime_dismiss\` (write), \`runtime_cancel\` (destructive). In the in-app
+  mission, a failed run also updates its card and posts a briefing turn.
 - **Execution evidence**: \`specrails_jobs(phase_breakdown)\` explains phases;
   job events are paginated. \`specrails_rails(pr_candidates)\` finds existing
   PR targets; \`review_packet(prDeliveryId)\` reads verification evidence.

package/server/dist/mcp/tools/jobs.js

@@ -37,15 +37,22 @@ function jobsTools() {
                 'pipeline (read a pipeline\'s jobs + statuses — use after composing dependent spawns), ' +
                 'activity (recent activity feed), stats, metrics, phase_breakdown (per-phase timing and token use for jobId), default_spec_model, ' +
                 'interactive_turn (ai-spawn — send a steering prompt to any running interactive job; claude jobs are interactive by default), ' +
-                'finalize (settle a running interactive job now — Freestyle jobs otherwise wait for it, others auto-settle).',
+                'finalize (settle a running interactive job now — Freestyle jobs otherwise wait for it, others auto-settle), ' +
+                'runtime_runs (read the programmatic runtime state of jobId — or every run when omitted — status, nextStep, canResume, recoverableSteps, pendingApproval, pendingQuestion; THIS is how you learn why a run failed and what recovery it offers), ' +
+                'runtime_evidence (read the durable runtime evidence of jobId), ' +
+                'runtime_resume (ai-spawn — continue a resumable run: optional approve/recover/invalidate step-id lists + answer for a pending question; act ONLY after the user confirmed on the card), ' +
+                'runtime_recover (ai-spawn — shorthand for runtime_resume with recover:[stepIds] over the recoverable steps), ' +
+                'runtime_approve (write — shorthand for runtime_resume with approve:[stepId] for a pending approval), ' +
+                'runtime_settle (write — prepare delivery for a succeeded-but-unsettled run), runtime_dismiss (write — dismiss a settled continuation from the rail card), ' +
+                'runtime_cancel (destructive — cancel an active runtime continuation).',
             hintTier: 'read',
             tier: (a) => {
                 const action = a.action;
-                if (['cancel', 'purge', 'background_start', 'background_kill'].includes(action))
+                if (['cancel', 'purge', 'background_start', 'background_kill', 'runtime_cancel'].includes(action))
                     return 'destructive';
-                if (['spawn', 'interactive_turn'].includes(action))
+                if (['spawn', 'interactive_turn', 'runtime_resume', 'runtime_recover'].includes(action))
                     return 'ai-spawn';
-                if (['pause', 'resume', 'reorder', 'priority', 'finalize'].includes(action))
+                if (['pause', 'resume', 'reorder', 'priority', 'finalize', 'runtime_approve', 'runtime_settle', 'runtime_dismiss'].includes(action))
                     return 'write';
                 return 'read';
             },
@@ -78,6 +85,14 @@ function jobsTools() {
                     'background_list',
                     'background_logs',
                     'background_kill',
+                    'runtime_runs',
+                    'runtime_evidence',
+                    'runtime_resume',
+                    'runtime_recover',
+                    'runtime_approve',
+                    'runtime_settle',
+                    'runtime_dismiss',
+                    'runtime_cancel',
                 ])
                     .describe('Operation to perform'),
                 projectId: zod_1.z.string().optional().describe('Project id (defaults to the active project)'),
@@ -129,6 +144,13 @@ function jobsTools() {
                 format: zod_1.z.enum(['json', 'csv']).optional().describe('Export format (default json)'),
                 // ── default_spec_model ──
                 provider: zod_1.z.string().optional().describe('Provider to resolve the default spec model for (default_spec_model)'),
+                // ── runtime_* (mission-rail-cards: the agent's eyes + hands on a failed run) ──
+                railIndex: zod_1.z.number().int().nonnegative().optional().describe('runtime_runs: only the latest continuation of this rail (0-based)'),
+                approve: zod_1.z.array(zod_1.z.string()).optional().describe('runtime_resume/runtime_approve: step ids to approve'),
+                recover: zod_1.z.array(zod_1.z.string()).optional().describe('runtime_resume/runtime_recover: step ids to recover (default for runtime_recover: every recoverableStep)'),
+                invalidate: zod_1.z.array(zod_1.z.string()).optional().describe('runtime_resume: step ids whose results must be discarded before continuing'),
+                answer: zod_1.z.string().optional().describe('runtime_resume: the answer to the run\'s pending question'),
+                stepId: zod_1.z.string().optional().describe('runtime_approve/runtime_recover: the single step id (alternative to the arrays)'),
             },
             async handler(ctx, args) {
                 const base = (0, types_1.projectPath)(ctx, args.projectId);
@@ -321,6 +343,71 @@ function jobsTools() {
                             throw new Error('finalize requires a "jobId".');
                         return (0, types_1.apiCall)(ctx, 'POST', `${base}/jobs/${encodeURIComponent(id)}/finalize`);
                     }
+                    case 'runtime_runs': {
+                        const id = args.jobId;
+                        if (id)
+                            return (0, types_1.apiCall)(ctx, 'GET', `${base}/agent-runtime/runs/${encodeURIComponent(id)}`);
+                        const railIndex = args.railIndex;
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/agent-runtime/runs${typeof railIndex === 'number' ? `?railIndex=${railIndex}` : ''}`);
+                    }
+                    case 'runtime_evidence': {
+                        const id = args.jobId;
+                        if (!id)
+                            throw new Error('runtime_evidence requires a "jobId".');
+                        return (0, types_1.apiCall)(ctx, 'GET', `${base}/agent-runtime/runs/${encodeURIComponent(id)}/evidence`);
+                    }
+                    case 'runtime_resume':
+                    case 'runtime_recover':
+                    case 'runtime_approve': {
+                        const id = args.jobId;
+                        if (!id)
+                            throw new Error(`${action} requires a "jobId".`);
+                        const single = typeof args.stepId === 'string' && args.stepId.trim() ? [args.stepId.trim()] : undefined;
+                        const body = {};
+                        if (action === 'runtime_recover') {
+                            let recover = args.recover ?? single;
+                            if (!recover?.length) {
+                                const state = await (0, types_1.apiCall)(ctx, 'GET', `${base}/agent-runtime/runs/${encodeURIComponent(id)}`);
+                                recover = state.runs?.[0]?.recoverableSteps ?? [];
+                            }
+                            if (!recover.length)
+                                throw new Error('runtime_recover: the run has no recoverable steps — read runtime_runs and use runtime_resume instead.');
+                            body.recover = recover;
+                        }
+                        else if (action === 'runtime_approve') {
+                            const approve = args.approve ?? single;
+                            if (!approve?.length)
+                                throw new Error('runtime_approve requires "stepId" or "approve".');
+                            body.approve = approve;
+                        }
+                        else {
+                            for (const key of ['approve', 'recover', 'invalidate'])
+                                if (Array.isArray(args[key]))
+                                    body[key] = args[key];
+                            if (typeof args.answer === 'string')
+                                body.answer = args.answer;
+                        }
+                        const r = await (0, types_1.apiCall)(ctx, 'POST', `${base}/agent-runtime/runs/${encodeURIComponent(id)}/resume`, body);
+                        return { ...r, hint: 'Resume accepted (202) — it is not completion. Progress streams into the mission run card; verify with runtime_runs or specrails_watch.' };
+                    }
+                    case 'runtime_settle': {
+                        const id = args.jobId;
+                        if (!id)
+                            throw new Error('runtime_settle requires a "jobId".');
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/agent-runtime/runs/${encodeURIComponent(id)}/settle`);
+                    }
+                    case 'runtime_dismiss': {
+                        const id = args.jobId;
+                        if (!id)
+                            throw new Error('runtime_dismiss requires a "jobId".');
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/agent-runtime/runs/${encodeURIComponent(id)}/dismiss`);
+                    }
+                    case 'runtime_cancel': {
+                        const id = args.jobId;
+                        if (!id)
+                            throw new Error('runtime_cancel requires a "jobId".');
+                        return (0, types_1.apiCall)(ctx, 'POST', `${base}/agent-runtime/runs/${encodeURIComponent(id)}/cancel`);
+                    }
                     case 'background_start': {
                         const command = args.command;
                         if (!command || !command.trim())

package/server/dist/mcp/tools/rails.js

@@ -40,7 +40,7 @@ function railsTools() {
             description: 'List and configure a project\'s rail launch slots, then launch or stop the AI pipeline for a rail. ' +
                 'A rail holds assigned ticket IDs plus a mode/profile/engine/name. Rails are DYNAMIC: create_rail adds a new slot (up to 12), so when every rail is busy or holds other work, create a fresh one and proceed — never wait for a slot. ' +
                 'Parallel launches normally run in isolated git worktrees; verify the returned isolated flag. Legacy or non-git runs may use shared project files and have no delivery card. ' +
-                'Actions: list (rails + active jobs/loop runs), pr_candidates (read compatible open PR targets for railIndex), review_packet (read durable evidence, verification and acceptance capability by prDeliveryId), create_rail (add a new rail slot; returns its railIndex), set_tickets (assign ticket IDs), set_profile (default agent profile, null=legacy), ' +
+                'Actions: list (rails + active jobs/loop runs; every rail carries availability free|busy|pending_decision|on_review — prefer a free rail when proposing a launch card, else create_rail), pr_candidates (read compatible open PR targets for railIndex), review_packet (read durable evidence, verification and acceptance capability by prDeliveryId), create_rail (add a new rail slot; returns its railIndex), set_tickets (assign ticket IDs), set_profile (default agent profile, null=legacy), ' +
                 'set_engine (provider override, null=primary), set_name (display label, null clears), ' +
                 'launch (ai-spawn — spawns the selected installed provider CLI job(s), including Kimi when installed, that WRITE CODE, RUN TESTS, COMMIT, and INCUR TOKEN COST; returns 202 with jobId/jobIds/loopRunIds), ' +
                 'launch_all (ai-spawn — launches EVERY rail that has tickets and no active run/uncontinuable pending PR decision, in parallel, using each rail\'s stored mode/engine/profile; returns per-rail outcomes with skip reasons), ' +
@@ -301,7 +301,7 @@ function railsTools() {
                             return {
                                 ...r,
                                 railLabel,
-                                hint: `Launch accepted (202) on ${railLabel}, but WORKTREE ISOLATION IS UNAVAILABLE because ${why}. The run proceeds on the SHARED working tree and writes changes DIRECTLY into the user's files — there is NO PR-decision/implementation card and NO branch. Do NOT tell the user to look for a PR card; tell them the run writes to their files in place, and explain why. ${fix} When it finishes, the spec parks at on_review — the user accepts it by moving it to Done on the board (the changes are already in their files) or reverts the spec's status (which does NOT undo the file changes).`,
+                                hint: `Launch accepted (202) on ${railLabel}, but WORKTREE ISOLATION IS UNAVAILABLE because ${why}. The run proceeds on the SHARED working tree and writes changes DIRECTLY into the user's files — there is NO branch and NO PR phase — the mission shows a RUN card (progress, log, failure + recovery) but never a PR-decision card. Do NOT promise a PR card; tell them the run writes to their files in place, and explain why. ${fix} When it finishes, the spec parks at on_review — the user accepts it by moving it to Done on the board (the changes are already in their files) or reverts the spec's status (which does NOT undo the file changes).`,
                             };
                         }
                         if (r.isolated !== true) {

package/server/dist/mission-run-notify.js

@@ -0,0 +1,170 @@
+"use strict";
+// ─── Mission run cards + the failure trigger (mission-rail-cards) ────────────
+// ONE chokepoint through which every mission-originated run reports to the
+// conversation that launched it:
+//   - `postRunCard` / `settleRunCard`: the run card for SHARED-CWD launches
+//     (no git repo / no commits — no `rail_pr_deliveries` row, so before this
+//     change the mission had NO object for the run at all). The card reuses
+//     the PR-decision envelope keyed on a synthetic `run:<runId>` id with
+//     `hasDelivery:false`, so cold-load / pinning / rendering are shared.
+//   - `notifyMissionRunFailure`: on failed / stalled / provider-limit / stuck
+//     outcomes: (a) update the card in place with the failure as TEXT,
+//     (b) insert the compact `run-failure` system row, (c) start ONE bounded
+//     automatic agent turn with the briefing. Untagged launches → no-op.
+// Never throws — it runs inside settle paths.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RUN_CARD_ID_PREFIX = void 0;
+exports.runCardId = runCardId;
+exports.isRunCardId = isRunCardId;
+exports.buildRunCardEnvelope = buildRunCardEnvelope;
+exports.failureForLoopOutcome = failureForLoopOutcome;
+exports.runtimeFromSummary = runtimeFromSummary;
+exports.postRunCard = postRunCard;
+exports.settleRunCard = settleRunCard;
+exports.notifyMissionRunFailure = notifyMissionRunFailure;
+const agent_chat_registry_1 = require("./agent-chat-registry");
+const feature_flags_1 = require("./feature-flags");
+const agent_failure_briefing_1 = require("./agent-failure-briefing");
+exports.RUN_CARD_ID_PREFIX = 'run:';
+function runCardId(runId) { return `${exports.RUN_CARD_ID_PREFIX}${runId}`; }
+function isRunCardId(prDeliveryId) { return prDeliveryId.startsWith(exports.RUN_CARD_ID_PREFIX); }
+/** The envelope of a delivery-less (shared-cwd) run card. */
+function buildRunCardEnvelope(id, state) {
+    const now = new Date().toISOString();
+    const failed = state.decision === 'implementation_failed';
+    return {
+        kind: 'pr_decision',
+        prDeliveryId: runCardId(id.runId),
+        railIndex: id.railIndex,
+        projectId: id.projectId,
+        baseBranch: '',
+        ticketIds: id.ticketIds,
+        decision: state.decision,
+        implementationOutcome: state.decision === 'building' ? 'running' : state.decision === 'completed' ? 'succeeded' : failed ? 'failed' : 'unknown',
+        deliveryOutcome: 'not_started',
+        statusCode: state.statusCode ?? (failed ? 'implementation_failed' : state.decision === 'discarded' ? 'cancelled' : null),
+        statusDetail: state.statusDetail ?? null,
+        deliverySha: null,
+        isContinuation: false,
+        supersedesDeliveryId: null,
+        restoredFromDeliveryId: null,
+        operation: null,
+        cleanupWarnings: [],
+        safetyArchives: [],
+        units: id.ticketIds.map((ticketId) => ({ ticketId, branch: '', succeeded: state.decision === 'completed', runId: id.runId })),
+        prUrl: null,
+        prNumber: null,
+        prState: 'none',
+        branch: null,
+        runIds: [id.runId],
+        createdAt: now,
+        updatedAt: now,
+        hasDelivery: false,
+        phase: state.phase,
+        railName: id.railName ?? null,
+        runtime: state.runtime ?? null,
+    };
+}
+/** Map a loop outcome (+ stall reason) to a card failure; null when not a failure. */
+function failureForLoopOutcome(outcome, stallReason, detail) {
+    if (outcome === 'success')
+        return null;
+    if (stallReason === 'provider_limit')
+        return { code: 'provider_limit', detail: detail ?? null, stepId: null };
+    if (outcome === 'stalled')
+        return { code: 'stalled', detail: detail ?? (stallReason ? `reason: ${stallReason}` : null), stepId: null };
+    if (outcome === 'stopped')
+        return { code: 'cancelled', detail: detail ?? null, stepId: null };
+    if (outcome === 'blocked')
+        return { code: 'blocked', detail: detail ?? (stallReason ?? null), stepId: null };
+    return { code: 'implementation_failed', detail: detail ?? (stallReason ?? null), stepId: null };
+}
+function runtimeFromSummary(summary, failure) {
+    const status = summary
+        ? (summary.active ? 'running' : summary.status === 'succeeded' ? 'succeeded' : summary.status === 'cancelled' ? 'cancelled' : summary.status === 'stalled' ? 'stalled' : failure ? 'failed' : 'unknown')
+        : failure ? (failure.code === 'stalled' ? 'stalled' : failure.code === 'cancelled' ? 'cancelled' : 'failed') : 'unknown';
+    return {
+        status,
+        currentStep: summary?.nextStep ?? null,
+        canResume: summary?.canResume ?? false,
+        recoverableSteps: summary?.recoverableSteps ?? [],
+        pendingApproval: Boolean(summary?.pendingApproval),
+        failure: failure ? { ...failure, stepId: failure.stepId ?? summary?.pendingApproval?.stepId ?? null } : null,
+        at: new Date().toISOString(),
+    };
+}
+/** Post the run card at launch (shared-cwd path). */
+function postRunCard(originConversationId, id) {
+    if (!originConversationId || !(0, feature_flags_1.isMissionRailCardsEnabled)())
+        return;
+    const mgr = (0, agent_chat_registry_1.getAgentChatManager)();
+    if (!mgr)
+        return;
+    try {
+        mgr.postPrDecisionCard(originConversationId, buildRunCardEnvelope(id, { phase: 'running', decision: 'building' }));
+    }
+    catch (err) {
+        console.error('[mission-run] postRunCard failed:', err);
+    }
+}
+/** Settle a shared-cwd run card: success → completed, cancel → discarded; failures go through notifyMissionRunFailure. */
+function settleRunCard(originConversationId, id, outcome, summary = null) {
+    if (!originConversationId || !(0, feature_flags_1.isMissionRailCardsEnabled)())
+        return;
+    const mgr = (0, agent_chat_registry_1.getAgentChatManager)();
+    if (!mgr)
+        return;
+    try {
+        const decision = outcome === 'success' ? 'completed' : outcome === 'stopped' ? 'discarded' : 'implementation_failed';
+        const runtime = runtimeFromSummary(summary, failureForLoopOutcome(outcome));
+        if (outcome === 'success' && !summary)
+            runtime.status = 'succeeded';
+        mgr.updatePrDecisionCard(originConversationId, buildRunCardEnvelope(id, { phase: 'settled', decision, runtime }));
+    }
+    catch (err) {
+        console.error('[mission-run] settleRunCard failed:', err);
+    }
+}
+const SKIPPED = { card: false, row: null, turn: 'skipped' };
+/**
+ * The failure trigger job → card → agent. Resolves to what actually happened
+ * so callers/tests can assert; NEVER throws.
+ */
+async function notifyMissionRunFailure(input) {
+    if (!input.originConversationId || !(0, feature_flags_1.isMissionRailCardsEnabled)())
+        return SKIPPED;
+    const mgr = (0, agent_chat_registry_1.getAgentChatManager)();
+    if (!mgr)
+        return SKIPPED;
+    const origin = input.originConversationId;
+    const runtime = runtimeFromSummary(input.summary ?? null, input.failure);
+    const hasDelivery = input.hasDelivery ?? Boolean(input.envelope && input.envelope.hasDelivery !== false);
+    const envelope = input.envelope
+        ? { ...input.envelope, phase: input.envelope.decision === 'building' ? 'running' : input.envelope.phase ?? 'settled', runtime, railName: input.railName ?? input.envelope.railName ?? null }
+        : buildRunCardEnvelope(input, { phase: 'settled', decision: input.failure.code === 'cancelled' ? 'discarded' : 'implementation_failed', runtime, statusCode: input.failure.code, statusDetail: input.failure.detail });
+    let card = false;
+    try {
+        mgr.updatePrDecisionCard(origin, envelope);
+        card = true;
+    }
+    catch (err) {
+        console.error('[mission-run] card update failed:', err);
+    }
+    const rowPayload = {
+        kind: 'run-failure', runId: input.runId, railIndex: input.railIndex, projectId: input.projectId,
+        prDeliveryId: envelope.prDeliveryId, ticketIds: input.ticketIds,
+        code: input.failure.code, detail: input.failure.detail, stepId: runtime.failure?.stepId ?? null, at: new Date().toISOString(),
+    };
+    const row = mgr.postRunFailureRow(origin, rowPayload);
+    // A cancelled run is the user's own decision — no briefing turn for it.
+    if (input.failure.code === 'cancelled')
+        return { card, row, turn: 'skipped' };
+    const briefing = (0, agent_failure_briefing_1.buildFailureBriefing)({
+        runId: input.runId, railIndex: input.railIndex, railName: input.railName, ticketIds: input.ticketIds, tickets: input.tickets,
+        failure: runtime.failure ?? input.failure, outputTail: input.outputTail,
+        recovery: { canResume: runtime.canResume, recoverableSteps: runtime.recoverableSteps, pendingApproval: runtime.pendingApproval, pendingQuestion: input.summary?.pendingQuestion?.question ?? null },
+        hasDelivery, prDeliveryId: hasDelivery ? envelope.prDeliveryId : null,
+    });
+    const turn = await mgr.startSystemTurn(origin, briefing, { runId: input.runId, ref: (0, agent_failure_briefing_1.failureBriefingRef)(input.runId, input.railIndex, input.failure.code) });
+    return { card, row, turn };
+}

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

@@ -80,6 +80,9 @@ const multi_repo_execution_store_1 = require("./multi-repo-execution-store");
 const rail_isolation_1 = require("./rail-isolation");
 const rail_pr_store_1 = require("./rail-pr-store");
 const agent_chat_registry_1 = require("./agent-chat-registry");
+const mission_run_notify_1 = require("./mission-run-notify");
+const rails_store_1 = require("./rails-store");
+const agent_runtime_controls_router_1 = require("./agent-runtime-controls-router");
 const rail_merge_orchestrator_1 = require("./rail-merge-orchestrator");
 const loop_executors_1 = require("./loop-executors");
 const worktree_overlay_1 = require("./worktree-overlay");
@@ -378,6 +381,14 @@ function branchRecords(results) {
  * tearing down owned partial allocation. The router refuses shared-cwd
  * fallback for these errors; execution stays bound to a verified worktree.
  */
+function getRailName(ctx, railIndex) {
+    try {
+        return (0, rails_store_1.getRail)(ctx.db, railIndex).name ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 async function launchIsolatedRail(input, io = {}) {
     const { ctx, railIndex, ticketIds, loopId, loopName, loopGraph, provider, model, effort, deciderEngine } = input;
     let expectedRepositoryBaseSha = input.repositoryExecution?.expectedBaseSha;
@@ -467,6 +478,27 @@ async function launchIsolatedRail(input, io = {}) {
         if (prDeliveryId)
             syncDeliveryCard(prDeliveryId, verb);
     };
+    // mission-rail-cards: the failure trigger for isolated launches. Reads the
+    // durable row (origin link + latest envelope) so the notification reflects
+    // the exact persisted state; fire-and-forget, never throws into settle.
+    const notifyOriginRunFailure = (deliveryId, failure, runId) => {
+        const row = (0, rail_pr_store_1.getPrDelivery)(ctx.db, deliveryId);
+        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;
+        void (async () => {
+            const summary = runId ? await (0, agent_runtime_controls_router_1.runtimeRunSummary)(ctx, runId).catch(() => null) : null;
+            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 })),
+            });
+        })().catch((err) => console.error('[rail-isolated] mission failure notify failed:', err));
+    };
     const closeFailedGeneration = (err) => {
         if (!prDeliveryId || (0, rail_pr_store_1.getPrDelivery)(ctx.db, prDeliveryId)?.decision !== 'building')
             return;
@@ -484,6 +516,7 @@ async function launchIsolatedRail(input, io = {}) {
             emitPrDeliveryState(prDeliveryId, 'update');
         }
         catch { /* durable row is authoritative */ }
+        notifyOriginRunFailure(prDeliveryId, { code: 'launch_failed', detail: errorDetail(err), stepId: null }, null);
         if (supersededDelivery) {
             try {
                 emitPrDeliveryState(supersededDelivery.id, 'update');
@@ -1544,6 +1577,9 @@ async function launchIsolatedRail(input, io = {}) {
                     runId: result.run.runId,
                     worktreePath: result.run.handle.worktreePath,
                     loopId,
+                    // Programmatic-runtime evidence (host-run verification, reviewer
+                    // verdict) lives in the workspace pipeline dir, not the worktree.
+                    runtimeDir: path.join(resolveExecution(ctx.project).specrailsDir, 'pipeline', result.run.runId),
                 })));
             }
             catch (e) {
@@ -1600,6 +1636,17 @@ async function launchIsolatedRail(input, io = {}) {
                 // Completion driver: refresh the origin conversation's card in place —
                 // on_review asks the question, discarded informs the outcome.
                 syncOriginCard('update');
+                // mission-rail-cards: an implementation failure also wakes the origin
+                // mission (failure row + ONE bounded agent turn). Delivery failures
+                // (pr_failed) keep the card's retry controls and stay silent.
+                if (implementationOutcome === 'failed') {
+                    const failedUnit = results.find((result) => result.implementationOutcome === 'failed') ?? results[0];
+                    notifyOriginRunFailure(prDeliveryId, {
+                        code: 'implementation_failed',
+                        detail: statusDetail,
+                        stepId: null,
+                    }, failedUnit?.run.runId ?? null);
+                }
             }
             return; // legacy merge-back never runs in PR mode
         }

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

@@ -0,0 +1,182 @@
+"use strict";
+// ─── Rail launch proposal protocol (mission-rail-cards) ──────────────────────
+// The operator agent proposes "assign these specs to a rail and launch" as ONE
+// fenced ```rail-launch JSON block instead of prose. The mission renders it as
+// an editable launch card (client/src/components/agent-chat/AgentRailLaunchCard).
+// This module is the parser HALF shared by server and client — the client copy
+// lives at client/src/lib/rail-launch-draft.ts and MUST stay byte-identical
+// except for its import path (a parity test guards that).
+//
+// Tolerance (spec-draft precedent + snapshot hardening): unknown keys are
+// dropped, a malformed block is reported in `rejected[]` (never silent), a
+// string-aware tolerant JSON repair runs before rejecting, an open trailing
+// fence is cut while streaming (`pending`) and reported `truncated` once the
+// turn settled. Every VALID block is kept in order (one card per block: a
+// batch proposal is N blocks).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RAIL_LAUNCH_MODES = exports.RAIL_LAUNCH_PROPOSAL_VERSION = exports.RAIL_LAUNCH_FENCE = void 0;
+exports.coerceRailLaunchProposal = coerceRailLaunchProposal;
+exports.extractRailLaunchProposals = extractRailLaunchProposals;
+exports.looksLikeRailLaunch = looksLikeRailLaunch;
+const json_tolerant_1 = require("./json-tolerant");
+exports.RAIL_LAUNCH_FENCE = 'rail-launch';
+exports.RAIL_LAUNCH_PROPOSAL_VERSION = 1;
+exports.RAIL_LAUNCH_MODES = ['implement', 'batch-implement', 'freestyle', 'loop'];
+const FENCE_RE = /```rail-launch[^\S\n]*\n([\s\S]*?)\n[^\S\n]*```/g;
+const OPEN_FENCE = '```rail-launch';
+const EXCERPT_MAX = 160;
+function isRecord(v) {
+    return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+function optString(v, max = 200) {
+    if (typeof v !== 'string')
+        return null;
+    const t = v.trim();
+    return t ? t.slice(0, max) : null;
+}
+function optInt(v, min = 0) {
+    if (typeof v === 'number' && Number.isInteger(v) && v >= min)
+        return v;
+    if (typeof v === 'string' && /^\d+$/.test(v.trim())) {
+        const n = Number(v.trim());
+        return n >= min ? n : null;
+    }
+    return null;
+}
+function coerceTicketIds(v) {
+    if (!Array.isArray(v))
+        return [];
+    const out = [];
+    for (const item of v) {
+        // Accept 12, "12" and "#12" — models mirror the user's `#12` vocabulary.
+        const n = typeof item === 'number' ? item : typeof item === 'string' ? Number(item.trim().replace(/^#/, '')) : NaN;
+        if (Number.isInteger(n) && n > 0 && !out.includes(n))
+            out.push(n);
+    }
+    return out;
+}
+function excerpt(raw) {
+    const t = raw.replace(/\s+/g, ' ').trim();
+    return t.length > EXCERPT_MAX ? `${t.slice(0, EXCERPT_MAX - 1)}…` : t;
+}
+/** Validate ONE parsed payload; returns the proposal or a rejection reason. */
+function coerceRailLaunchProposal(value) {
+    if (!isRecord(value))
+        return { ok: false, reason: 'not_object' };
+    const version = optInt(value.version, 1) ?? optInt(value.blueprintVersion, 1);
+    if (version !== null && version !== exports.RAIL_LAUNCH_PROPOSAL_VERSION)
+        return { ok: false, reason: 'unsupported_version' };
+    const ticketIds = coerceTicketIds(value.ticketIds ?? value.specs ?? value.tickets);
+    if (ticketIds.length === 0)
+        return { ok: false, reason: 'no_tickets' };
+    const modeRaw = optString(value.mode)?.toLowerCase().replace(/_/g, '-') ?? 'implement';
+    const mode = modeRaw === 'batch' ? 'batch-implement' : modeRaw;
+    if (!exports.RAIL_LAUNCH_MODES.includes(mode))
+        return { ok: false, reason: 'invalid_mode' };
+    const newRailRaw = value.newRail;
+    const newRail = newRailRaw === true
+        ? { name: null }
+        : isRecord(newRailRaw) ? { name: optString(newRailRaw.name, 80) } : null;
+    // The agent may say railIndex 1-based by mistake ("Rail 2"); we cannot know,
+    // so we trust the number and let the card reconcile against live rails.
+    const railIndex = newRail ? null : optInt(value.railIndex, 0);
+    return {
+        ok: true,
+        proposal: {
+            version: 1,
+            railIndex,
+            newRail,
+            ticketIds,
+            mode: mode,
+            loopId: optString(value.loopId, 120),
+            aiEngine: optString(value.aiEngine ?? value.provider ?? value.engine, 80),
+            model: optString(value.model, 120),
+            reasoningEffort: optString(value.reasoningEffort ?? value.reasoning_effort ?? value.effort, 20),
+            profileName: optString(value.profileName ?? value.profile, 80),
+            targetPrNumber: optInt(value.targetPrNumber, 1),
+            baseBranch: optString(value.baseBranch, 200),
+            railName: optString(value.railName ?? value.name, 80),
+            rationale: optString(value.rationale ?? value.reason ?? value.why, 400),
+        },
+    };
+}
+function tidy(body) {
+    return body.replace(/\n{3,}/g, '\n\n').trim();
+}
+/**
+ * Extract every rail-launch block from assistant content.
+ * `streaming` cuts an open fence from the body instead of reporting truncation.
+ */
+function extractRailLaunchProposals(content, streaming = false) {
+    const empty = { body: content ?? '', proposals: [], rejected: [], pending: false, truncated: false, repaired: false };
+    if (!content || !content.includes(OPEN_FENCE))
+        return empty;
+    const proposals = [];
+    const rejected = [];
+    let repaired = false;
+    let stripped = '';
+    let cursor = 0;
+    FENCE_RE.lastIndex = 0;
+    let match;
+    const consume = (raw) => {
+        const parsed = (0, json_tolerant_1.parseJsonTolerant)(raw);
+        if (!parsed.ok) {
+            rejected.push({ reason: 'invalid_json', excerpt: excerpt(raw) });
+            return;
+        }
+        if (parsed.repaired)
+            repaired = true;
+        const result = coerceRailLaunchProposal(parsed.value);
+        if (result.ok)
+            proposals.push(result.proposal);
+        else
+            rejected.push({ reason: result.reason, excerpt: excerpt(raw) });
+    };
+    while ((match = FENCE_RE.exec(content)) !== null) {
+        stripped += content.slice(cursor, match.index);
+        cursor = match.index + match[0].length;
+        consume(match[1]);
+    }
+    stripped += content.slice(cursor);
+    let pending = false;
+    let truncated = false;
+    const openIdx = stripped.indexOf(OPEN_FENCE);
+    if (openIdx !== -1) {
+        const tail = stripped
+            .slice(openIdx + OPEN_FENCE.length)
+            .replace(/^[^\S\n]*\n?/, '')
+            .replace(/\s*(?:```)?\s*$/, '');
+        const parsed = tail.trim() ? (0, json_tolerant_1.parseJsonTolerant)(tail) : null;
+        if (parsed && parsed.ok) {
+            if (parsed.repaired)
+                repaired = true;
+            const result = coerceRailLaunchProposal(parsed.value);
+            if (result.ok)
+                proposals.push(result.proposal);
+            else
+                rejected.push({ reason: result.reason, excerpt: excerpt(tail) });
+            stripped = stripped.slice(0, openIdx);
+        }
+        else if (streaming) {
+            stripped = stripped.slice(0, openIdx);
+            pending = true;
+        }
+        else {
+            // Settled and unreadable: cut the raw JSON (never leak protocol text) and
+            // say so — the card shows the muted "unreadable" note.
+            stripped = stripped.slice(0, openIdx);
+            truncated = true;
+            rejected.push({ reason: 'invalid_json', excerpt: excerpt(tail) });
+        }
+    }
+    return { body: tidy(stripped), proposals, rejected, pending, truncated, repaired };
+}
+/** Shape detector for the generic-fence promotion pass (small local models). */
+function looksLikeRailLaunch(value) {
+    if (!isRecord(value))
+        return false;
+    const tickets = value.ticketIds ?? value.specs ?? value.tickets;
+    if (!Array.isArray(tickets) || tickets.length === 0)
+        return false;
+    return 'railIndex' in value || 'newRail' in value || 'mode' in value || 'loopId' in value || 'aiEngine' in value || 'railName' in value;
+}

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

@@ -25,9 +25,11 @@ exports.transitionClaimedDecision = transitionClaimedDecision;
 exports.claimPrDeliveryOperation = claimPrDeliveryOperation;
 exports.releasePrDeliveryOperation = releasePrDeliveryOperation;
 exports.clearOrphanedPrDeliveryOperations = clearOrphanedPrDeliveryOperations;
+exports.updatePrDeliverySettleEvidence = updatePrDeliverySettleEvidence;
 exports.toPrDeliverySnapshot = toPrDeliverySnapshot;
 exports.toRailPrStateMessage = toRailPrStateMessage;
 exports.toPrDecisionCardEnvelope = toPrDecisionCardEnvelope;
+exports.missionPhaseForDecision = missionPhaseForDecision;
 const ids_1 = require("./ids");
 const multi_repo_execution_store_1 = require("./multi-repo-execution-store");
 /** Defensive per-ticket cap; contract-layer specs run long but bounded. */
@@ -557,6 +559,10 @@ function parseJsonArray(raw) {
         return [];
     }
 }
+/** Rewrite ONLY the settle_evidence column (evidence heal) — no decision change. */
+function updatePrDeliverySettleEvidence(db, id, evidence) {
+    return db.prepare('UPDATE rail_pr_deliveries SET settle_evidence = ? WHERE id = ?').run(JSON.stringify(evidence), id).changes > 0;
+}
 function toPrDeliverySnapshot(row) {
     const units = parseJsonArray(row.branches);
     return {
@@ -669,5 +675,19 @@ function toPrDecisionCardEnvelope(projectId, snap) {
         runIds: snap.runIds,
         createdAt: snap.createdAt,
         updatedAt: snap.updatedAt,
+        // mission-rail-cards: coarse phase so the card renders the run header
+        // before the delivery controls; failure decisions carry a runtime snapshot
+        // with the reason as TEXT (the card used to hide statusDetail on discarded).
+        phase: missionPhaseForDecision(snap.decision),
+        ...(snap.decision === 'implementation_failed' || (snap.decision === 'discarded' && snap.statusCode === 'delivery_failed')
+            ? { runtime: { status: 'failed', currentStep: null, canResume: false, recoverableSteps: [], pendingApproval: false, at: snap.updatedAt ?? new Date().toISOString(), failure: { code: snap.statusCode ?? snap.decision, detail: snap.statusDetail, stepId: null } } }
+            : {}),
     };
 }
+function missionPhaseForDecision(decision) {
+    if (decision === 'building')
+        return 'running';
+    if (decision === 'implementation_failed' || decision === 'discarded' || decision === 'completed')
+        return 'settled';
+    return 'delivery';
+}