specrails-desktop 2.26.2 → 2.27.0

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

@@ -1,8 +1,42 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.jobsTools = jobsTools;
 const zod_1 = require("zod");
 const types_1 = require("./types");
+const path_1 = __importDefault(require("path"));
+const transient_children_1 = require("../../transient-children");
+function resolveBackgroundCwd(projectRoot, cwd) {
+    const resolved = path_1.default.resolve(projectRoot, cwd && cwd.trim() ? cwd : '.');
+    const root = path_1.default.resolve(projectRoot);
+    if (resolved !== root && !resolved.startsWith(root + path_1.default.sep)) {
+        throw new Error('background_start cwd must stay within the selected project.');
+    }
+    return resolved;
+}
+function backgroundHooks(broadcast) {
+    return {
+        onStarted: (process) => broadcast({
+            type: 'background_process.started',
+            process,
+            projectId: process.projectId,
+            timestamp: new Date().toISOString(),
+        }),
+        onOutput: (event) => broadcast({
+            type: 'background_process.output',
+            ...event,
+            timestamp: new Date().toISOString(),
+        }),
+        onExited: (process) => broadcast({
+            type: 'background_process.exited',
+            process,
+            projectId: process.projectId,
+            timestamp: new Date().toISOString(),
+        }),
+    };
+}
 /**
  * Jobs domain facade. Maps every in-scope jobs/queue action to its REST
  * endpoint on the loopback API (server/project-router-jobs.ts, plus the
@@ -20,6 +54,7 @@ function jobsTools() {
             title: 'Jobs & Queue',
             description: 'Manage a project\'s AI-pipeline job queue and individual jobs. ' +
                 'Actions: list, get, queue, spawn (ai-spawn — enqueues an arbitrary slash-command job, returns {jobId,position}, async; from the in-app agent chat the engine defaults to your conversation\'s provider — pass aiEngine to override), ' +
+                'background_start (operate-level shell command tied to the current agent chat; requires explicit user confirmation before use), background_kill, ' +
                 'cancel (destructive — cancels a running/queued job or deletes a terminal one), ' +
                 'purge (destructive — bulk-delete persisted job rows in a date range), ' +
                 'pause / resume (queue), reorder (queued-job order), priority (change a queued job\'s priority), ' +
@@ -34,7 +69,7 @@ function jobsTools() {
                 const action = a.action;
                 if (['cancel', 'purge'].includes(action))
                     return 'destructive';
-                if (['spawn', 'interactive_turn'].includes(action))
+                if (['spawn', 'interactive_turn', 'background_start', 'background_kill'].includes(action))
                     return 'ai-spawn';
                 if (['pause', 'resume', 'reorder', 'priority', 'finalize'].includes(action))
                     return 'write';
@@ -64,6 +99,8 @@ function jobsTools() {
                     'default_spec_model',
                     'interactive_turn',
                     'finalize',
+                    'background_start',
+                    'background_kill',
                 ])
                     .describe('Operation to perform'),
                 projectId: zod_1.z.string().optional().describe('Project id (defaults to the active project)'),
@@ -99,6 +136,9 @@ function jobsTools() {
                     .describe('reorder: exact set of currently-queued job ids in the desired order; compare: exactly 2 job ids'),
                 // ── interactive_turn ──
                 text: zod_1.z.string().optional().describe('Prompt text for interactive_turn'),
+                chatId: zod_1.z.string().optional().describe('Agent chat conversation id for background_start/background_kill ownership; defaults to the in-app agent conversation that called the tool'),
+                cwd: zod_1.z.string().optional().describe('Optional cwd for background_start; resolved inside the selected project root'),
+                pid: zod_1.z.number().optional().describe('Background process pid for background_kill'),
                 // ── export ──
                 format: zod_1.z.enum(['json', 'csv']).optional().describe('Export format (default json)'),
                 // ── default_spec_model ──
@@ -270,6 +310,31 @@ function jobsTools() {
                             throw new Error('finalize requires a "jobId".');
                         return (0, types_1.apiCall)(ctx, 'POST', `${base}/jobs/${encodeURIComponent(id)}/finalize`);
                     }
+                    case 'background_start': {
+                        const command = args.command;
+                        if (!command || !command.trim())
+                            throw new Error('background_start requires a "command".');
+                        const chatId = args.chatId ?? ctx.originConversationId ?? undefined;
+                        if (!chatId || !chatId.trim())
+                            throw new Error('background_start requires a "chatId".');
+                        const projectCtx = (0, types_1.requireProject)(ctx, args.projectId);
+                        const cwd = resolveBackgroundCwd(projectCtx.project.path, args.cwd);
+                        const process = (0, transient_children_1.startBackgroundProcess)(command.trim(), cwd, chatId.trim(), projectCtx.project.id, backgroundHooks(ctx.broadcast));
+                        return { ok: true, process };
+                    }
+                    case 'background_kill': {
+                        const pid = args.pid;
+                        if (typeof pid !== 'number' || !Number.isFinite(pid))
+                            throw new Error('background_kill requires a numeric "pid".');
+                        const chatId = args.chatId ?? ctx.originConversationId ?? undefined;
+                        if (!chatId || !chatId.trim())
+                            throw new Error('background_kill requires a "chatId".');
+                        const projectCtx = (0, types_1.requireProject)(ctx, args.projectId);
+                        const killed = (0, transient_children_1.killOwnedBackgroundProcess)(pid, { projectId: projectCtx.project.id, chatId: chatId.trim() });
+                        if (!killed)
+                            throw new Error('background_kill requires a registered pid in the same project/chat.');
+                        return { ok: true, pid, status: 'killing' };
+                    }
                     default:
                         throw new Error(`Unknown action "${action}".`);
                 }

package/server/dist/path-resolver.js

@@ -11,6 +11,8 @@ exports.resolveStartupPath = resolveStartupPath;
 exports.parseLoginShellOutput = parseLoginShellOutput;
 exports.augmentPathFromLoginShell = augmentPathFromLoginShell;
 exports.parseLoginShellEnv = parseLoginShellEnv;
+exports.augmentEnvFromLoginShell = augmentEnvFromLoginShell;
+exports.augmentEnvFromLoginShellSync = augmentEnvFromLoginShellSync;
 exports.augmentAuthEnvFromLoginShell = augmentAuthEnvFromLoginShell;
 exports.getPathDiagnostic = getPathDiagnostic;
 exports.__resetPathResolverForTest = __resetPathResolverForTest;
@@ -464,6 +466,24 @@ exports.AUTH_ENV_VARS = [
     'GOOGLE_CLOUD_LOCATION',
     'GOOGLE_APPLICATION_CREDENTIALS',
 ];
+const LOGIN_SHELL_ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const loginShellEnvProbeCache = new Set();
+function normalizeLoginShellEnvNames(names) {
+    const out = [];
+    for (const raw of names) {
+        const name = String(raw).trim();
+        if (!LOGIN_SHELL_ENV_NAME_RE.test(name) || out.includes(name))
+            continue;
+        out.push(name);
+    }
+    return out;
+}
+function buildLoginShellEnvCommand(names) {
+    // `printf` reuses POSIX positional `$VAR` expansion (works in sh/bash/zsh).
+    const fmt = ENV_BEGIN + names.map((v) => `${v}=%s\n`).join('') + ENV_END;
+    const refs = names.map((v) => `"$${v}"`).join(' ');
+    return `printf '${fmt}' ${refs}`;
+}
 /** Parse the `KEY=value` block emitted between the env sentinels. */
 function parseLoginShellEnv(stdout) {
     const begin = stdout.indexOf(ENV_BEGIN);
@@ -486,27 +506,23 @@ function parseLoginShellEnv(stdout) {
     }
     return out;
 }
-/**
- * Spawn the user's login shell once and backfill any provider auth env vars it
- * exposes into `process.env` (only when not already set — never override an
- * explicit value). POSIX-only and runs REGARDLESS of bundle state (unlike the
- * PATH augmentation, which is skipped when the bundle is active): macOS desktop
- * builds bundle node/git, so the PATH login-shell probe is skipped, yet we still
- * need to recover the gemini key. Async, fire-and-forget — must not block
- * startup. No-op on Windows (GUI inherits user env) and in tests.
- */
-async function augmentAuthEnvFromLoginShell(opts = {}) {
+/** Backfill arbitrary, pre-validated environment variable names from the user's
+ * login shell into `process.env` (only when not already set — never override an
+ * explicit value). POSIX-only and runs regardless of bundle state, so macOS GUI
+ * launches can recover tokens exported in `.zshrc`/`.bashrc` without hardcoding
+ * every possible package-manager/provider variable. No-op on Windows and tests. */
+async function augmentEnvFromLoginShell(names, opts = {}) {
     if (process.platform === 'win32')
         return;
     if (process.env.NODE_ENV === 'test' || process.env.VITEST === 'true')
         return;
+    const wanted = normalizeLoginShellEnvNames(names).filter((name) => !process.env[name]);
+    if (wanted.length === 0)
+        return;
     const spawnFn = opts.spawnFn ?? child_process_1.spawn;
     const timeoutMs = opts.timeoutMs ?? LOGIN_SHELL_TIMEOUT_MS;
     const shell = process.env.SHELL || '/bin/sh';
-    // `printf` reuses POSIX positional `$VAR` expansion (works in sh/bash/zsh).
-    const fmt = ENV_BEGIN + exports.AUTH_ENV_VARS.map((v) => `${v}=%s\n`).join('') + ENV_END;
-    const refs = exports.AUTH_ENV_VARS.map((v) => `"$${v}"`).join(' ');
-    const command = `printf '${fmt}' ${refs}`;
+    const command = buildLoginShellEnvCommand(wanted);
     await new Promise((resolve) => {
         let child;
         try {
@@ -536,7 +552,7 @@ async function augmentAuthEnvFromLoginShell(opts = {}) {
         child.on('error', finish);
         child.on('close', () => {
             const recovered = parseLoginShellEnv(stdout);
-            for (const key of exports.AUTH_ENV_VARS) {
+            for (const key of wanted) {
                 const val = recovered[key];
                 // Backfill only when unset/empty — never clobber an explicit value.
                 if (val && !process.env[key])
@@ -546,6 +562,48 @@ async function augmentAuthEnvFromLoginShell(opts = {}) {
         });
     });
 }
+/** Synchronous, cached variant for spawn-time env assembly. It probes each
+ * missing name at most once per process to keep loops from paying the login
+ * shell timeout on every step. */
+function augmentEnvFromLoginShellSync(names, opts = {}) {
+    if (process.platform === 'win32')
+        return;
+    if (process.env.NODE_ENV === 'test' || process.env.VITEST === 'true')
+        return;
+    const wanted = normalizeLoginShellEnvNames(names).filter((name) => !process.env[name] && !loginShellEnvProbeCache.has(name));
+    if (wanted.length === 0)
+        return;
+    for (const name of wanted)
+        loginShellEnvProbeCache.add(name);
+    const spawnSyncFn = opts.spawnSyncFn ?? child_process_1.spawnSync;
+    const timeoutMs = opts.timeoutMs ?? LOGIN_SHELL_TIMEOUT_MS;
+    const shell = process.env.SHELL || '/bin/sh';
+    const command = buildLoginShellEnvCommand(wanted);
+    let res;
+    try {
+        res = spawnSyncFn(shell, ['-l', '-i', '-c', command], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: timeoutMs,
+        });
+    }
+    catch {
+        return;
+    }
+    if (res.error)
+        return;
+    const stdout = typeof res.stdout === 'string' ? res.stdout : res.stdout?.toString('utf8') ?? '';
+    const recovered = parseLoginShellEnv(stdout);
+    for (const key of wanted) {
+        const val = recovered[key];
+        if (val && !process.env[key])
+            process.env[key] = val;
+    }
+}
+/** Startup backfill for the built-in provider auth variables. */
+async function augmentAuthEnvFromLoginShell(opts = {}) {
+    await augmentEnvFromLoginShell(exports.AUTH_ENV_VARS, opts);
+}
 function mergeLoginShellPath(rawPath) {
     const current = splitPath(process.env.PATH);
     const currentSet = new Set(current);
@@ -582,4 +640,5 @@ function __resetPathResolverForTest() {
     diagnostic = { pathSegments: [], pathSources: [], loginShellStatus: 'skipped' };
     warnedLoginShell = false;
     bundledRuntimesActive = false;
+    loginShellEnvProbeCache.clear();
 }

package/server/dist/project-env.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveWorktreeEnvPassthrough = resolveWorktreeEnvPassthrough;
+exports.applyWorktreeEnvPassthrough = applyWorktreeEnvPassthrough;
+const db_1 = require("./db");
+const path_resolver_1 = require("./path-resolver");
+/** Resolve the per-project env passthrough overlay for a spawn.
+ *
+ * The project setting stores names only. Values are read from `sourceEnv` at
+ * spawn time so credentials can rotate without touching SQLite. When the
+ * source is `process.env`, missing configured names get one bounded login-shell
+ * recovery attempt first; unresolved names are still ignored instead of
+ * blocking the run.
+ */
+function resolveWorktreeEnvPassthrough(db, sourceEnv = process.env) {
+    const out = {};
+    const names = (0, db_1.getProjectSettings)(db).worktreeEnvPassthrough;
+    if (sourceEnv === process.env)
+        (0, path_resolver_1.augmentEnvFromLoginShellSync)(names);
+    for (const name of names) {
+        const value = sourceEnv[name];
+        if (value !== undefined)
+            out[name] = value;
+    }
+    return out;
+}
+function applyWorktreeEnvPassthrough(db, env, sourceEnv = process.env) {
+    const passthrough = resolveWorktreeEnvPassthrough(db, sourceEnv);
+    return Object.keys(passthrough).length === 0 ? env : { ...env, ...passthrough };
+}

package/server/dist/project-registry.js

@@ -29,6 +29,7 @@ const transient_children_1 = require("./transient-children");
 const telemetry_receiver_1 = require("./telemetry-receiver");
 const artifact_registry_1 = require("./artifact-registry");
 const workspace_resolution_1 = require("./workspace-resolution");
+const project_env_1 = require("./project-env");
 const workspace_manager_1 = require("./workspace-manager");
 const ticket_store_1 = require("./ticket-store");
 const jira_sync_manager_1 = require("./jira/jira-sync-manager");
@@ -689,9 +690,10 @@ class ProjectRegistry {
         // `${ENV:-legacy}` defaults resolve inside the worktree, where only tracked
         // files exist — still reads the real project state. SPECRAILS_REPO_DIR stays
         // per-run (the worktree for isolated runs). Legacy projects keep process.env
-        // byte-identical. See resolveLoopBaseEnv.
+        // byte-identical except for the explicit per-project passthrough overlay.
+        // See resolveLoopBaseEnv.
         const loopRunManager = new loop_run_manager_1.LoopRunManager(db, boundBroadcast, (0, loop_executors_1.createLoopExecutors)({
-            env: () => (0, workspace_resolution_1.resolveLoopBaseEnv)({ slug: project.slug, path: project.path }),
+            env: () => (0, workspace_resolution_1.resolveLoopBaseEnv)({ slug: project.slug, path: project.path }, undefined, (0, project_env_1.applyWorktreeEnvPassthrough)(db, process.env)),
         }));
         const getTicketSpec = (ticketId) => {
             try {

package/server/dist/project-router-jobs.js

@@ -1,6 +1,10 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerJobsRoutes = registerJobsRoutes;
+const path_1 = __importDefault(require("path"));
 const db_1 = require("./db");
 const queue_manager_1 = require("./queue-manager");
 const feature_flags_1 = require("./feature-flags");
@@ -12,6 +16,7 @@ const provider_selection_1 = require("./provider-selection");
 const loop_runs_store_1 = require("./loop-runs-store");
 const metrics_1 = require("./metrics");
 const ticket_store_1 = require("./ticket-store");
+const transient_children_1 = require("./transient-children");
 const project_router_helpers_1 = require("./project-router-helpers");
 function registerJobsRoutes(deps) {
     const { router, registry, ctx, ticketPath } = deps;
@@ -86,6 +91,77 @@ function registerJobsRoutes(deps) {
             },
         });
     });
+    router.get('/:projectId/background-processes', (req, res) => {
+        const c = ctx(req);
+        const chatId = typeof req.query.chatId === 'string' && req.query.chatId.trim() ? req.query.chatId.trim() : undefined;
+        res.json({
+            processes: (0, transient_children_1.listBackgroundProcesses)({
+                projectId: c.project.id,
+                ...(chatId ? { chatId } : {}),
+            }),
+        });
+    });
+    router.post('/:projectId/background-processes', (req, res) => {
+        const { command, cwd, chatId } = req.body ?? {};
+        const c = ctx(req);
+        if (!command || typeof command !== 'string' || !command.trim()) {
+            res.status(400).json({ error: 'command is required' });
+            return;
+        }
+        if (!chatId || typeof chatId !== 'string' || !chatId.trim()) {
+            res.status(400).json({ error: 'chatId is required' });
+            return;
+        }
+        const resolvedCwd = path_1.default.resolve(c.project.path, typeof cwd === 'string' && cwd.trim() ? cwd : '.');
+        const root = path_1.default.resolve(c.project.path);
+        if (resolvedCwd !== root && !resolvedCwd.startsWith(root + path_1.default.sep)) {
+            res.status(400).json({ error: 'cwd must stay within the project' });
+            return;
+        }
+        try {
+            const process = (0, transient_children_1.startBackgroundProcess)(command.trim(), resolvedCwd, chatId.trim(), c.project.id, {
+                onStarted: (process) => c.broadcast({
+                    type: 'background_process.started',
+                    process,
+                    projectId: process.projectId,
+                    timestamp: new Date().toISOString(),
+                }),
+                onOutput: (event) => c.broadcast({
+                    type: 'background_process.output',
+                    ...event,
+                    timestamp: new Date().toISOString(),
+                }),
+                onExited: (process) => c.broadcast({
+                    type: 'background_process.exited',
+                    process,
+                    projectId: process.projectId,
+                    timestamp: new Date().toISOString(),
+                }),
+            });
+            res.status(202).json({ ok: true, process });
+        }
+        catch (err) {
+            res.status(500).json({ error: err instanceof Error ? err.message : 'background process failed to start' });
+        }
+    });
+    router.delete('/:projectId/background-processes/:pid', (req, res) => {
+        const c = ctx(req);
+        const pid = Number(req.params.pid);
+        const chatId = typeof req.query.chatId === 'string' ? req.query.chatId : '';
+        if (!Number.isFinite(pid)) {
+            res.status(400).json({ error: 'pid must be numeric' });
+            return;
+        }
+        if (!chatId.trim()) {
+            res.status(400).json({ error: 'chatId is required' });
+            return;
+        }
+        if (!(0, transient_children_1.killOwnedBackgroundProcess)(pid, { projectId: c.project.id, chatId: chatId.trim() })) {
+            res.status(404).json({ error: 'background process not found for project/chat' });
+            return;
+        }
+        res.json({ ok: true, pid, status: 'killing' });
+    });
     // Returns the resolved default model for Add Spec + the full provider
     // allow-list so the modal can render its picker without maintaining its
     // own copy of the model lists. Source of truth is `server/spec-models.ts`.

package/server/dist/project-router-settings.js

@@ -76,7 +76,7 @@ function registerSettingsRoutes(deps) {
         res.json({ scope: merged });
     });
     router.patch('/:projectId/settings', (req, res) => {
-        const { pipelineTelemetryEnabled, orchestratorModel, prePrompt, freestylePrePrompt } = req.body ?? {};
+        const { pipelineTelemetryEnabled, orchestratorModel, prePrompt, freestylePrePrompt, worktreeEnvPassthrough } = req.body ?? {};
         const patch = {};
         if (pipelineTelemetryEnabled !== undefined) {
             patch.pipelineTelemetryEnabled = Boolean(pipelineTelemetryEnabled);
@@ -103,6 +103,15 @@ function registerSettingsRoutes(deps) {
             }
             patch.freestylePrePrompt = freestylePrePrompt;
         }
+        if (worktreeEnvPassthrough !== undefined) {
+            try {
+                patch.worktreeEnvPassthrough = (0, db_1.normalizeWorktreeEnvPassthrough)(worktreeEnvPassthrough);
+            }
+            catch (err) {
+                res.status(400).json({ error: err instanceof Error ? err.message : 'invalid worktreeEnvPassthrough' });
+                return;
+            }
+        }
         if (req.body?.integrationBranch !== undefined) {
             const ib = req.body.integrationBranch;
             if (typeof ib !== 'string') {

package/server/dist/queue-manager.js

@@ -33,6 +33,7 @@ const binary_probe_1 = require("./binary-probe");
 const workspace_manager_1 = require("./workspace-manager");
 const claude_trust_1 = require("./claude-trust");
 const workspace_resolution_1 = require("./workspace-resolution");
+const project_env_1 = require("./project-env");
 const framework_manager_1 = require("./framework-manager");
 const openspec_shim_1 = require("./openspec-shim");
 const artifact_registry_1 = require("./artifact-registry");
@@ -1650,6 +1651,13 @@ class QueueManager {
         // claude honours OTEL_* env vars natively; codex does not and instead
         // gets signals synthesised by the codex-otel-bridge attached below.
         let spawnEnv = process.env;
+        // Per-project worktree/job env passthrough. The setting stores names only;
+        // values are read from the server env (with login-shell recovery for missing
+        // names) at spawn time. Apply this before Specrails' own env overlays so
+        // internal SPECRAILS_* control-plane values always win.
+        if (this._db) {
+            spawnEnv = (0, project_env_1.applyWorktreeEnvPassthrough)(this._db, spawnEnv);
+        }
         const telemetryEnabled = !!(this._projectId && this._db && (0, db_1.getProjectSettings)(this._db).pipelineTelemetryEnabled);
         // Resolve the framework version ONCE at spawn time — `framework/current`
         // is read from `~/.specrails/framework/current`. A concurrent atomic swap
@@ -1668,7 +1676,7 @@ class QueueManager {
             if (frameworkVersion)
                 extra['specrails.framework_version'] = frameworkVersion;
             spawnEnv = {
-                ...process.env,
+                ...spawnEnv,
                 ...buildTelemetryEnv(jobId, this._projectId, this._desktopPort, extra, adapter.id),
             };
         }

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

@@ -497,8 +497,9 @@ async function launchIsolatedRail(input, io = {}) {
             // Build-settle: persist the per-unit branch outcomes + this launch's
             // worktree ledger ids on the row (the deferred create-pr / discard actions
             // reconstruct their inputs from these — nothing survives in memory), then
-            // hand the decision to the user. 0 succeeded units → nothing deliverable
-            // → auto-close (per-run settle already reverted the tickets).
+            // hand the decision to the user. 0 succeeded units → nothing deliverable;
+            // keep the implementation card visible as a failed job state with run-log
+            // chips instead of silently auto-discarding or leaving it at "building".
             const worktreeIds = allocated.map((a) => a.ledgerId);
             const anySucceeded = results.some((r) => r.succeeded);
             const settledContinuation = anySucceeded ? launchContinuation : null;
@@ -522,7 +523,7 @@ async function launchIsolatedRail(input, io = {}) {
                         ? 'pr_failed'
                         : (settledContinuation.isDraft === false ? 'pr_ready' : 'pr_draft'))
                     : 'on_review')
-                : 'discarded';
+                : 'implementation_failed';
             const patch = settledContinuation
                 ? {
                     branches,
@@ -543,7 +544,7 @@ async function launchIsolatedRail(input, io = {}) {
                 syncOriginCard('update');
             }
             if (!anySucceeded) {
-                // AUTO-DISCARD CLEANUP (0 succeeded): unmount every worktree NOW rather
+                // FAILED-IMPLEMENTATION CLEANUP (0 succeeded): unmount every worktree NOW rather
                 // than leaving it for a restart's reconcile sweep — a still-mounted
                 // worktree POISONS the next run of the same ticket: the worktree path is
                 // keyed by ticketId, so the next allocation silently reuses this

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

@@ -107,7 +107,8 @@ function actionAllowed(action, row) {
             return row.decision === 'pr_draft' && row.pr_url !== null;
         case 'discard':
             return row.decision === 'on_review' || row.decision === 'pr_draft' ||
-                row.decision === 'pr_ready' || row.decision === 'pr_failed';
+                row.decision === 'pr_ready' || row.decision === 'implementation_failed' ||
+                row.decision === 'pr_failed';
         case 'poll-merge':
             return (row.decision === 'pr_draft' || row.decision === 'pr_ready') && row.pr_url !== null;
         case 'merge-local':
@@ -438,9 +439,15 @@ async function runPublish(deps, row) {
 }
 async function runDiscard(deps, row) {
     const snap = (0, rail_pr_store_1.toPrDeliverySnapshot)(row);
+    const implementationFailed = row.decision === 'implementation_failed';
     // 1. Close the PR (drops its head branch) when one exists. Best-effort — a
     //    gh failure must never leave the discard half-done.
-    if (row.pr_url) {
+    //
+    // Implementation-failed rows are different: the implement run produced no
+    // deliverable update. If the row belongs to an existing-PR continuation it may
+    // still carry that PR's url/branch from launch time; clearing the failed card
+    // must not close or delete the user's existing review branch.
+    if (row.pr_url && !implementationFailed) {
         try {
             const r = await deps.exec.run('gh', ['pr', 'close', row.pr_url, '--delete-branch'], deps.project.path);
             if (r.code !== 0) {
@@ -454,12 +461,13 @@ async function runDiscard(deps, row) {
     // 2. Remove the launch's worktrees (still on disk unless a restart already
     //    swept them) and close their ledger rows — the reconcile-style removal,
     //    branch deletion deferred to step 3 (a checked-out branch can't be -D'd).
-    const branchSet = new Set(snap.branches.map((b) => b.branch));
+    const branchSet = new Set(implementationFailed ? [] : snap.branches.map((b) => b.branch));
     for (const wtId of snap.worktreeIds) {
         const wt = (0, rail_worktrees_store_1.getRailWorktree)(deps.db, wtId);
         if (!wt)
             continue;
-        branchSet.add(wt.branch);
+        if (!implementationFailed)
+            branchSet.add(wt.branch);
         await (0, worktree_manager_1.removeWorktree)(deps.git, {
             repoDir: deps.project.path, worktreePath: wt.worktree_path, branch: wt.branch, deleteBranch: false,
         }).catch(() => { });
@@ -471,22 +479,24 @@ async function runDiscard(deps, row) {
     //    best-effort from the same ticket data the create-pr path names it from
     //    (the delivered head is already covered by row.branch). Missing branches
     //    are tolerated; the integration branch is NEVER deleted.
-    if (row.branch)
-        branchSet.add(row.branch);
-    const succeededUnits = snap.branches.filter((b) => b.succeeded);
-    if (succeededUnits.length > 1) {
-        try {
-            branchSet.add((0, pr_naming_1.batchBranchNameFor)(loadPrTicketData(deps, succeededUnits.map((b) => b.ticketId))));
+    if (!implementationFailed) {
+        if (row.branch)
+            branchSet.add(row.branch);
+        const succeededUnits = snap.branches.filter((b) => b.succeeded);
+        if (succeededUnits.length > 1) {
+            try {
+                branchSet.add((0, pr_naming_1.batchBranchNameFor)(loadPrTicketData(deps, succeededUnits.map((b) => b.ticketId))));
+            }
+            catch {
+                /* best-effort defense-in-depth only */
+            }
         }
-        catch {
-            /* best-effort defense-in-depth only */
+        for (const branch of branchSet) {
+            if (!branch || branch === row.base_branch)
+                continue;
+            await deps.git.run(['branch', '-D', branch], deps.project.path).catch(() => { });
         }
     }
-    for (const branch of branchSet) {
-        if (!branch || branch === row.base_branch)
-            continue;
-        await deps.git.run(['branch', '-D', branch], deps.project.path).catch(() => { });
-    }
     const conflict = casTransition(deps, row, 'discarded');
     if (conflict)
         return conflict;

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

@@ -6,6 +6,7 @@ exports.createPrDelivery = createPrDelivery;
 exports.getPrDelivery = getPrDelivery;
 exports.getActivePrDeliveryByRail = getActivePrDeliveryByRail;
 exports.listActivePrDeliveries = listActivePrDeliveries;
+exports.reconcileFailedBuildingPrDeliveries = reconcileFailedBuildingPrDeliveries;
 exports.transitionDecision = transitionDecision;
 exports.toPrDeliverySnapshot = toPrDeliverySnapshot;
 exports.toRailPrStateMessage = toRailPrStateMessage;
@@ -19,6 +20,7 @@ exports.ACTIVE_PR_DECISIONS = new Set([
     'on_review',
     'pr_draft',
     'pr_ready',
+    'implementation_failed',
     'pr_failed',
 ]);
 function isTerminalPrDecision(s) {
@@ -60,6 +62,40 @@ function listActivePrDeliveries(db) {
        ORDER BY rail_index, created_at DESC, rowid DESC`)
         .all();
 }
+/**
+ * Recover implementation cards stranded at `building` after the loop process
+ * already settled all associated run ids without a success. This covers server
+ * restarts and the settle gap where loop_runs/worktrees mark failure but the
+ * PR-delivery row never receives its final card state.
+ */
+function reconcileFailedBuildingPrDeliveries(db) {
+    const rows = db
+        .prepare(`SELECT * FROM rail_pr_deliveries WHERE decision = 'building' ORDER BY created_at ASC, rowid ASC`)
+        .all();
+    const reconciled = [];
+    for (const row of rows) {
+        const runIds = parseJsonArray(row.run_ids ?? '[]');
+        if (runIds.length === 0)
+            continue;
+        const uniqueRunIds = [...new Set(runIds)];
+        const placeholders = uniqueRunIds.map(() => '?').join(',');
+        const runs = db
+            .prepare(`SELECT id, status, final_outcome FROM loop_runs WHERE id IN (${placeholders})`)
+            .all(...uniqueRunIds);
+        if (runs.length !== uniqueRunIds.length)
+            continue;
+        if (runs.some((run) => run.status !== 'completed'))
+            continue;
+        if (runs.some((run) => run.final_outcome === 'success'))
+            continue;
+        if (transitionDecision(db, row.id, 'building', 'implementation_failed')) {
+            const updated = getPrDelivery(db, row.id);
+            if (updated)
+                reconciled.push(updated);
+        }
+    }
+    return reconciled;
+}
 // 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.

package/server/dist/rails-router.js

@@ -53,6 +53,11 @@ function emitPrDeliveryUpdate(c, prDeliveryId) {
         (0, agent_chat_registry_1.getAgentChatManager)()?.updatePrDecisionCard(row.origin_conversation_id, (0, rail_pr_store_1.toPrDecisionCardEnvelope)(c.project.id, snap));
     }
 }
+function reconcileAndEmitFailedPrDeliveries(c) {
+    for (const row of (0, rail_pr_store_1.reconcileFailedBuildingPrDeliveries)(c.db)) {
+        emitPrDeliveryUpdate(c, row.id);
+    }
+}
 function createRailsRouter() {
     const router = (0, express_1.Router)({ mergeParams: true });
     function ctx(req) {
@@ -116,6 +121,7 @@ function createRailsRouter() {
             // (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.
+            reconcileAndEmitFailedPrDeliveries(c);
             const prDeliveries = {};
             for (const row of (0, rail_pr_store_1.listActivePrDeliveries)(c.db)) {
                 if (!(row.rail_index in prDeliveries))
@@ -684,7 +690,7 @@ function createRailsRouter() {
                                 if (current.pr_state === 'pr-created' && current.pr_url && current.branch) {
                                     const succeeded = settled.every((s) => s.status === 'fulfilled' && s.value === true);
                                     if (!succeeded) {
-                                        if ((0, rail_pr_store_1.transitionDecision)(c.db, fallbackPrDeliveryId, 'building', 'pr_failed', { prState: 'local-only' })) {
+                                        if ((0, rail_pr_store_1.transitionDecision)(c.db, fallbackPrDeliveryId, 'building', 'implementation_failed')) {
                                             emitPrDeliveryUpdate(c, fallbackPrDeliveryId);
                                         }
                                         return;