specrails-desktop 2.26.0 → 2.26.2

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

@@ -0,0 +1,324 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.supportTools = supportTools;
+const zod_1 = require("zod");
+const mcp_tiers_1 = require("../mcp-tiers");
+const types_1 = require("./types");
+const projects_1 = require("./projects");
+const SUPPORT_TOPICS = [
+    'installation',
+    'project_setup',
+    'provider_cli',
+    'mcp_connection',
+    'agent_chat',
+    'framework_install',
+    'specs_backlog',
+    'rails_jobs',
+    'git_pr',
+    'analytics_costs',
+    'plugins_integrations',
+    'general_usage',
+];
+/**
+ * Support triage and repair entry point. This is intentionally NOT a spec
+ * creation path: it keeps user-help requests in the conversation and routes
+ * framework repairs through explicit support actions.
+ */
+function supportTools() {
+    return [
+        {
+            name: 'specrails_support',
+            title: 'Support & troubleshooting',
+            description: 'Support and troubleshooting for Specrails installation and usage problems. Use this when the user needs help setting up Specrails, adding/provisioning a project, fixing missing agents/skills/commands from the global specrails-core framework, provider CLI/MCP/agent-chat issues, rails/jobs/specs, or GitHub/PR/cost/plugin questions. ' +
+                'Actions: triage (read-only support playbook + diagnostics), core_update_status/check/apply (global specrails-core framework update). ' +
+                'This tool never creates specs; repair actions require the normal permission tier and explicit user confirmation.',
+            tier: (a) => (String(a.action) === 'core_update_apply' ? 'ai-spawn' : 'read'),
+            hintTier: 'read',
+            inputSchema: {
+                action: zod_1.z
+                    .enum([
+                    'triage',
+                    'core_update_status',
+                    'core_update_check',
+                    'core_update_apply',
+                ])
+                    .describe('Support operation to perform'),
+                question: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('The user-facing problem or question to triage, in the user wording when possible'),
+                topic: zod_1.z
+                    .enum(SUPPORT_TOPICS)
+                    .optional()
+                    .describe('Optional explicit support topic; omit to infer from question'),
+                projectId: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('Optional project id when the issue is project-specific; defaults to the active project when selected'),
+                version: zod_1.z
+                    .string()
+                    .optional()
+                    .describe('core_update_apply: optional target specrails-core version; omit to use the latest version found by core_update_check'),
+                includeDiagnostics: zod_1.z
+                    .boolean()
+                    .optional()
+                    .describe('When true or omitted, include read-only local diagnostics such as prerequisites, providers, settings, and projects. Project setup checkpoints are skipped for specrails-core installation triage because they are not a core health signal.'),
+            },
+            async handler(ctx, args) {
+                const action = String(args.action);
+                switch (action) {
+                    case 'core_update_status':
+                        return (0, types_1.apiCall)(ctx, 'GET', '/core-update/status');
+                    case 'core_update_check':
+                        return (0, types_1.apiCall)(ctx, 'POST', '/core-update/check', {});
+                    case 'core_update_apply': {
+                        const body = typeof args.version === 'string' && args.version.trim()
+                            ? { version: args.version.trim() }
+                            : {};
+                        const r = await (0, types_1.apiCall)(ctx, 'POST', '/core-update/update', body);
+                        return {
+                            ...(typeof r === 'object' && r !== null ? r : { result: r }),
+                            hint: 'Core update is async and app-global. Progress streams as core_update.progress / framework.updated. This updates the global specrails-core framework; it is not a per-project setup/install action.',
+                        };
+                    }
+                    case 'triage':
+                        break;
+                    default:
+                        throw new Error(`Unknown action "${action}".`);
+                }
+                const question = typeof args.question === 'string' ? args.question.trim() : '';
+                const topic = isSupportTopic(args.topic) ? args.topic : inferTopic(question);
+                const includeDiagnostics = args.includeDiagnostics !== false;
+                const diagnostics = includeDiagnostics
+                    ? await collectDiagnostics(ctx, args.projectId, topic)
+                    : { skipped: true };
+                return {
+                    mode: 'support-triage',
+                    doNotCreateSpec: true,
+                    topic,
+                    question: question || null,
+                    supportPrompt: [
+                        'Treat this as a help/support conversation, not product backlog intake.',
+                        'Answer in the user language and solve the immediate setup or usage problem with concrete steps.',
+                        'Do not create or propose a spec unless the user explicitly pivots from troubleshooting to new product work.',
+                        'Prefer read-only diagnostics first. Ask at most two targeted questions if the next step depends on missing local context.',
+                        'If a fix requires write, ai-spawn, or destructive permissions, explain the exact action and ask for confirmation before calling another tool.',
+                        'For missing agents, skills, slash commands, or specrails-core framework files during a job, explain that these definitions live in the app-global specrails-core framework. Do not use project setup checkpoints as evidence of core health or as a reason to run project setup.',
+                    ],
+                    localDiagnostics: diagnostics,
+                    recommendedNextSteps: nextSteps(topic),
+                    suggestedReadTools: suggestedTools(topic),
+                    availableRepairActions: repairActions(topic),
+                    responseChecklist: [
+                        'State what the diagnostics show, including any unknowns or failed probes.',
+                        'Give the smallest next action the user can take in the app or terminal.',
+                        'Name the exact Specrails surface when relevant: Add Project, Setup, Settings > MCP, Agent Chat, Rails board, Job Detail, Analytics, Integrations.',
+                        'If the issue is already resolved by state, say so and explain how to verify it.',
+                    ],
+                };
+            },
+        },
+    ];
+}
+function isSupportTopic(value) {
+    return typeof value === 'string' && SUPPORT_TOPICS.includes(value);
+}
+function inferTopic(question) {
+    const q = question.toLowerCase();
+    if (/\b(mcp|claude desktop|cursor|external ai|token|settings.*mcp)\b/.test(q))
+        return 'mcp_connection';
+    if (/\b(agent chat|chat panel|shift\+tab|permission level|observe|operate|autonomous)\b/.test(q))
+        return 'agent_chat';
+    if (/\b(specrails-core|core framework|missing agents?|missing skills?|no agents?|no skills?|slash command|command not found|propose-feature|opsx|framework files?|reinstall)\b/.test(q))
+        return 'framework_install';
+    if (/\b(claude|codex|gemini|provider|engine|cli|auth|login|api key|path)\b/.test(q))
+        return 'provider_cli';
+    if (/\b(add project|project setup|setup wizard|provision|checkpoint|install config)\b/.test(q))
+        return 'project_setup';
+    if (/\b(install|installation|setup|prerequisite|node|npm|npx|git)\b/.test(q))
+        return 'installation';
+    if (/\b(rail|job|launch|run|queue|stuck|failed|logs?)\b/.test(q))
+        return 'rails_jobs';
+    if (/\b(github|git|pr|pull request|remote|branch|merge|integrate locally)\b/.test(q))
+        return 'git_pr';
+    if (/\b(cost|spend|budget|analytics|tokens?)\b/.test(q))
+        return 'analytics_costs';
+    if (/\b(plugin|integration|serena|marketplace)\b/.test(q))
+        return 'plugins_integrations';
+    if (/\b(spec|ticket|backlog|draft|todo|done|review)\b/.test(q))
+        return 'specs_backlog';
+    return 'general_usage';
+}
+async function collectDiagnostics(ctx, projectId, topic) {
+    const projects = ctx.registry.listContexts().map((c) => (0, projects_1.serializeProject)(c.project));
+    const selectedProjectId = projectId ?? (0, types_1.getActiveProject)(ctx) ?? undefined;
+    const out = {
+        mcp: {
+            enabled: (0, mcp_tiers_1.isMcpEnabled)(ctx.desktopDb),
+            tierWrite: (0, mcp_tiers_1.isTierEnabled)(ctx.desktopDb, 'write'),
+            tierAiSpawn: (0, mcp_tiers_1.isTierEnabled)(ctx.desktopDb, 'ai-spawn'),
+            tierDestructive: (0, mcp_tiers_1.isTierEnabled)(ctx.desktopDb, 'destructive'),
+        },
+        activeProjectId: (0, types_1.getActiveProject)(ctx),
+        projectCount: projects.length,
+        projects,
+        prerequisites: await safeDiagnostic(() => (0, types_1.apiCall)(ctx, 'GET', '/setup-prerequisites?diagnostic=1')),
+        availableProviders: await safeDiagnostic(() => (0, types_1.apiCall)(ctx, 'GET', '/available-providers')),
+        coreUpdate: await safeDiagnostic(() => (0, types_1.apiCall)(ctx, 'GET', '/core-update/status')),
+    };
+    if (!selectedProjectId) {
+        out.project = {
+            ok: false,
+            error: 'No active project or projectId was provided. Project-specific diagnostics need specrails_select_project or projectId.',
+        };
+        return out;
+    }
+    const project = safeLocal(() => (0, projects_1.serializeProject)((0, types_1.requireProject)(ctx, selectedProjectId).project));
+    out.project = project;
+    if (project.ok && topic !== 'framework_install') {
+        out.setupCheckpoints = await safeDiagnostic(() => (0, types_1.apiCall)(ctx, 'GET', `/projects/${selectedProjectId}/setup/checkpoints`));
+    }
+    else if (topic === 'framework_install') {
+        out.setupCheckpoints = {
+            skipped: true,
+            reason: 'Skipped intentionally: project setup checkpoints are not a specrails-core health check. Pending checkpoints or 0 agent/command counts must not be used to diagnose global core installation.',
+        };
+    }
+    return out;
+}
+async function safeDiagnostic(fn) {
+    try {
+        return { ok: true, data: await fn() };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+function safeLocal(fn) {
+    try {
+        return { ok: true, data: fn() };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+function nextSteps(topic) {
+    switch (topic) {
+        case 'installation':
+            return [
+                'Read prerequisites and availableProviders from localDiagnostics.',
+                'If Node/npm/npx/git are missing, tell the user to install them, restart Specrails, then recheck.',
+                'If a provider CLI is missing, install and authenticate that CLI before retrying project setup.',
+            ];
+        case 'project_setup':
+            return [
+                'Check whether the project is registered and whether setupCheckpoints.isInstalling is still true.',
+                'If setup is running, tell the user to wait or poll checkpoints; if failed, surface the last log lines and retry only the failed setup step.',
+                'If no project is selected, ask for the repo path and provider choices before using specrails_setup.',
+            ];
+        case 'provider_cli':
+            return [
+                'Compare availableProviders with the providers installed on the project.',
+                'Ask the user to verify the provider CLI in a fresh terminal only when the local probe is missing or ambiguous.',
+                'For auth failures, direct them to the provider CLI login/API-key flow, then re-open or retry Specrails setup.',
+            ];
+        case 'mcp_connection':
+            return [
+                'Check localDiagnostics.mcp.enabled and explain that external clients also need the Settings > MCP config and token.',
+                'If MCP is off, tell the user to enable it in Settings > MCP; do not try to mutate the MCP enable flag through this tool.',
+                'If a tier blocks an action, name the exact tier to enable in Settings > MCP.',
+            ];
+        case 'agent_chat':
+            return [
+                'Explain the in-app permission ladder: observe, edit, operate, autonomous.',
+                'If a tool was refused, tell the user which level to switch to with Shift+Tab.',
+                'If Agent Chat cannot operate, check MCP enabled state and installed provider state first.',
+            ];
+        case 'framework_install':
+            return [
+                'For specrails-core installation questions, evaluate only global core status and prerequisites. Do not treat project setup checkpoints as evidence of a core problem.',
+                'If global core status is current/healthy and the user has not provided an actual job error, say the core installation looks healthy and ask for the concrete failing job/error before recommending repair.',
+                'If a job explicitly reports missing agents, missing skills, unresolved slash commands, or missing /specrails:* commands, explain that those definitions come from the app-global specrails-core framework.',
+                'If an update is available, offer core_update_check followed by core_update_apply with confirmation. If no update is available but the job still fails with missing core definitions, give the manual fallback: run `npx specrails-core@latest update` from the project root, then retry, or collect the job diagnostic for a framework-loading bug.',
+                'Never recommend specrails_setup(install) or a project reinstall solely because setup/checkpoints show pending or 0 agents/commands.',
+            ];
+        case 'rails_jobs':
+            return [
+                'Use read tools for rails/jobs status before guessing: specrails_rails, specrails_jobs, and specrails_watch only when the user asks to wait.',
+                'For a failed or stuck job, inspect the Job Detail logs and report the real failure.',
+                'Do not relaunch or stop anything without confirmation and the required permission level.',
+            ];
+        case 'git_pr':
+            return [
+                'Use specrails_git read-only diagnostics for remote, status, branch, gh_auth, gh_repo, and PR questions.',
+                'Explain that PR creation/integration belongs to the rail PR-decision surface, not this support tool.',
+                'If there is no GitHub remote, explain local-only delivery and Integrate locally.',
+            ];
+        case 'analytics_costs':
+            return [
+                'Use specrails_analytics(spending) for actual cost questions.',
+                'Distinguish app-wide budget settings from per-project analytics budget caps.',
+                'Prefix cost with ~ when the provider reports estimates.',
+            ];
+        case 'plugins_integrations':
+            return [
+                'Use specrails_plugins read actions before suggesting install/uninstall.',
+                'For degraded plugins, report health details and avoid blocking rail launches.',
+                'Mutating plugin actions need explicit confirmation and the matching permission level.',
+            ];
+        case 'specs_backlog':
+            return [
+                'Use specrails_specs list/get to explain current backlog state.',
+                'Only create or edit specs if the user asks for backlog work, not when they are asking how Specrails works.',
+                'Do not patch pipeline-managed statuses unless the user explicitly asks and understands the consequence.',
+            ];
+        case 'general_usage':
+            return [
+                'Use specrails_guide and specrails_search to find the relevant domain.',
+                'Explain the UI path first, then offer to perform safe read/write actions from chat when appropriate.',
+                'Keep the answer short and operational; ask one targeted question if the requested surface is unclear.',
+            ];
+    }
+}
+function suggestedTools(topic) {
+    switch (topic) {
+        case 'installation':
+            return ['specrails_support', 'specrails_setup(prerequisites)', 'specrails_setup(available_providers)'];
+        case 'project_setup':
+            return ['specrails_projects(list|get)', 'specrails_setup(checkpoints)', 'specrails_setup(prerequisites)'];
+        case 'provider_cli':
+            return ['specrails_setup(available_providers)', 'specrails_setup(prerequisites)', 'specrails_projects(get)'];
+        case 'mcp_connection':
+            return ['specrails_settings(get)', 'specrails_guide', 'specrails_describe'];
+        case 'agent_chat':
+            return ['specrails_settings(get)', 'specrails_projects(list|get)', 'specrails_guide'];
+        case 'framework_install':
+            return ['specrails_support(triage|core_update_status|core_update_check)', 'specrails_jobs(get)', 'specrails_jobs(diagnostic)'];
+        case 'rails_jobs':
+            return ['specrails_rails', 'specrails_jobs', 'specrails_watch'];
+        case 'git_pr':
+            return ['specrails_git(remote|status|branch|gh_auth|gh_repo|gh_pr_list|gh_pr_view)'];
+        case 'analytics_costs':
+            return ['specrails_analytics(spending)', 'specrails_settings(get)'];
+        case 'plugins_integrations':
+            return ['specrails_plugins(list|health|preview)', 'specrails_projects(get)'];
+        case 'specs_backlog':
+            return ['specrails_specs(list|get)', 'specrails_guide'];
+        case 'general_usage':
+            return ['specrails_guide', 'specrails_search', 'specrails_describe'];
+    }
+}
+function repairActions(topic) {
+    if (topic === 'framework_install') {
+        return [
+            'specrails_support(core_update_check) then specrails_support(core_update_apply) - apply requires operate/ai-spawn and only makes sense when a newer global specrails-core framework is available.',
+            'Manual fallback when no update is available but a real job still cannot load core definitions: run `npx specrails-core@latest update` from the project root, then retry or collect a job diagnostic.',
+        ];
+    }
+    if (topic !== 'project_setup' && topic !== 'installation')
+        return [];
+    return [
+        'specrails_setup(install, projectId) - operate/ai-spawn: use only for actual project setup/provisioning, not for specrails-core global installation questions.',
+        'specrails_support(core_update_check) then specrails_support(core_update_apply) - apply requires operate/ai-spawn: updates the app-global specrails-core framework when a newer version is available.',
+    ];
+}

package/server/dist/pr-publisher.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defaultExec = void 0;
 exports.parsePrUrl = parsePrUrl;
+exports.pushBranch = pushBranch;
 exports.publishDraftPr = publishDraftPr;
 /**
  * App-owned "deliver a mutating loop's result as a DRAFT PR" primitive.
@@ -46,32 +47,33 @@ function parsePrUrl(stdout) {
     const m = stdout.match(/https?:\/\/\S+\/pull\/\d+/);
     return m ? m[0] : undefined;
 }
-async function publishDraftPr(exec, input) {
+/** Push a committed delivery branch, including the gh-credential retry used by
+ *  draft PR creation. This is also used for follow-up commits on an existing PR:
+ *  that path must update the same remote PR branch without trying to create a
+ *  second PR. */
+async function pushBranch(exec, input) {
     const remote = input.remote ?? 'origin';
     const { repoDir, branch, baseBranch } = input;
-    // 1. Push the branch (set upstream). Failure → local-only, never throw.
-    //    Guardrail: never force-push, never push the integration branch itself.
     const pushArgs = ['push', '-u', remote, branch];
     (0, git_guardrails_1.assertGitAllowed)('git', pushArgs, { protectedBranch: baseBranch });
     let push = await exec.run('git', pushArgs, repoDir);
     if (push.code !== 0 && isCredentialFailure(push)) {
-        // The push failed authenticating over HTTPS — typically the machine's
-        // configured credential helper (e.g. git-credential-osxkeychain) is not on
-        // the app's PATH (GUI-launch PATH divergence: the sidecar inherits launchd's
-        // PATH, not the user's login shell). Retry borrowing gh's credentials — the
-        // SAME auth we use for `gh pr create` below, so if the PR can be created the
-        // push can succeed — instead of depending on a machine credential helper.
-        // `-c credential.helper=` first RESETS the (broken) inherited helper list,
-        // then adds gh's. Harmless for SSH remotes (git ignores credential.helper).
-        // The semantic push (refspec/remote) is unchanged, so the guardrail asserted
-        // above still holds; no-op when gh is absent (retry fails the same way).
         const retry = await exec.run('git', ['-c', 'credential.helper=', '-c', 'credential.helper=!gh auth git-credential', ...pushArgs], repoDir);
         if (retry.code === 0)
             push = retry;
     }
-    if (push.code !== 0) {
+    if (push.code !== 0)
         return { state: 'local-only', branch, reason: reasonFrom(push) };
-    }
+    return { state: 'pushed', branch };
+}
+async function publishDraftPr(exec, input) {
+    const remote = input.remote ?? 'origin';
+    const { repoDir, branch, baseBranch } = input;
+    // 1. Push the branch (set upstream). Failure → local-only, never throw.
+    //    Guardrail: never force-push, never push the integration branch itself.
+    const pushed = await pushBranch(exec, { repoDir, branch, baseBranch, remote });
+    if (pushed.state === 'local-only')
+        return pushed;
     // 2. Open a DRAFT PR. Failure (no gh / not authed / perms) → pushed, never throw.
     const pr = await exec.run('gh', ['pr', 'create', '--draft', '--base', baseBranch, '--head', branch, '--title', input.title, '--body', input.body], repoDir);
     if (pr.code !== 0) {

package/server/dist/project-git.js

@@ -4,8 +4,10 @@ exports.parseWorktreePorcelain = parseWorktreePorcelain;
 exports.getProjectGitInfo = getProjectGitInfo;
 exports.compactCheckoutError = compactCheckoutError;
 exports.checkoutProjectBranch = checkoutProjectBranch;
+exports.checkoutProjectReviewBranch = checkoutProjectReviewBranch;
 const child_process_1 = require("child_process");
 const file_provenance_1 = require("./file-provenance");
+const integration_branch_1 = require("./integration-branch");
 // ─── Project git info + branch switch (Agent-Mode git bar) ────────────────────
 //
 // Read the repo's current branch / last commit / local branches, and check out
@@ -145,3 +147,58 @@ async function checkoutProjectBranch(repoDir, branch) {
         return { ok: false, error: compactCheckoutError(err instanceof Error ? err.message : 'git checkout failed') };
     }
 }
+async function remoteBranchExists(repoDir, branch) {
+    try {
+        await git(repoDir, ['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${branch}`]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Checkout a PR/review branch into the user's main repo. Unlike the small
+ *  AgentGitBar switcher, this path may materialize a local tracking branch from
+ *  `origin/<branch>` because a PR delivery can be remote-only after worktree
+ *  cleanup or a fresh clone. It never overwrites dirty local work. */
+async function checkoutProjectReviewBranch(repoDir, branch) {
+    const target = branch.trim();
+    if (!(0, integration_branch_1.isValidBranchName)(target))
+        return { ok: false, error: `Invalid branch name: ${branch}` };
+    let dirty = false;
+    try {
+        dirty = (await git(repoDir, ['status', '--porcelain'])) !== '';
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : 'git status failed' };
+    }
+    if (dirty)
+        return { ok: false, error: 'Working tree has uncommitted changes. Commit or stash them before checkout.' };
+    // Best effort: refresh remote-tracking refs before deciding whether a branch
+    // can be materialized. Failure degrades to local-only checkout.
+    await git(repoDir, ['fetch', 'origin']).catch(() => { });
+    let branches;
+    try {
+        branches = await listLocalBranches(repoDir);
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : 'git failed' };
+    }
+    try {
+        if (branches.includes(target)) {
+            await git(repoDir, ['checkout', target]);
+        }
+        else if (await remoteBranchExists(repoDir, target)) {
+            await git(repoDir, ['checkout', '-b', target, '--track', `origin/${target}`]);
+        }
+        else {
+            return { ok: false, error: `Unknown branch: ${target}` };
+        }
+    }
+    catch (err) {
+        return { ok: false, error: compactCheckoutError(err instanceof Error ? err.message : 'git checkout failed') };
+    }
+    // A failed ff-only pull should not undo a successful checkout; the branch is
+    // already where the user can inspect/fix it. Surface only hard checkout errors.
+    await git(repoDir, ['pull', '--ff-only']).catch(() => { });
+    return { ok: true };
+}

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

@@ -82,6 +82,7 @@ const file_story_1 = require("./file-story");
 const providers_1 = require("./providers");
 const pr_publisher_1 = require("./pr-publisher");
 const active_pr_continuation_1 = require("./active-pr-continuation");
+const rail_worktree_release_1 = require("./rail-worktree-release");
 /**
  * Ticket data for the conventional branch name (pr-naming): title/labels from
  * the ticket-spec reader, the Jira key resolved with the authoritative
@@ -301,6 +302,7 @@ async function launchIsolatedRail(input, io = {}) {
                 originSurface: input.originSurface ?? 'dashboard',
                 originConversationId: input.originConversationId ?? null,
             }).id;
+            input.onPrDeliveryCreated?.(prDeliveryId);
             if (launchContinuation) {
                 (0, rail_pr_store_1.transitionDecision)(ctx.db, prDeliveryId, 'building', 'building', {
                     branch: launchContinuation.branch,
@@ -393,7 +395,10 @@ async function launchIsolatedRail(input, io = {}) {
             }
             // Close the just-inserted decision row (kept as 'discarded' for audit, never
             // deleted) so a wedged 'building' row can never block relaunching the slot.
-            if (prDeliveryId && (0, rail_pr_store_1.transitionDecision)(ctx.db, prDeliveryId, 'building', 'discarded')) {
+            // Router-driven PR continuations may intentionally fall back to shared-cwd
+            // on the same PR branch; in that case the router preserves and updates the
+            // row as the live iteration card instead of showing a false discard.
+            if (!input.preservePrDeliveryOnAllocationFailure && prDeliveryId && (0, rail_pr_store_1.transitionDecision)(ctx.db, prDeliveryId, 'building', 'discarded')) {
                 broadcastPrState();
                 syncOriginCard('update');
             }
@@ -497,9 +502,25 @@ async function launchIsolatedRail(input, io = {}) {
             const worktreeIds = allocated.map((a) => a.ledgerId);
             const anySucceeded = results.some((r) => r.succeeded);
             const settledContinuation = anySucceeded ? launchContinuation : null;
+            let continuationPushFailed = false;
+            let continuationPushFailureReason = null;
+            if (settledContinuation) {
+                const pushed = await (0, pr_publisher_1.pushBranch)(exec, {
+                    repoDir: baseRepo,
+                    branch: settledContinuation.branch,
+                    baseBranch: settledContinuation.baseBranch,
+                });
+                if (pushed.state === 'local-only') {
+                    continuationPushFailed = true;
+                    continuationPushFailureReason = pushed.reason;
+                    console.warn(`[rail-isolated] existing PR follow-up push failed for ${settledContinuation.branch}: ${continuationPushFailureReason}`);
+                }
+            }
             const next = anySucceeded
                 ? (settledContinuation
-                    ? (settledContinuation.isDraft === false ? 'pr_ready' : 'pr_draft')
+                    ? (continuationPushFailed
+                        ? 'pr_failed'
+                        : (settledContinuation.isDraft === false ? 'pr_ready' : 'pr_draft'))
                     : 'on_review')
                 : 'discarded';
             const patch = settledContinuation
@@ -509,10 +530,13 @@ async function launchIsolatedRail(input, io = {}) {
                     branch: settledContinuation.branch,
                     prUrl: settledContinuation.prUrl,
                     prNumber: settledContinuation.prNumber,
-                    prState: 'pr-created',
+                    prState: continuationPushFailed ? 'local-only' : 'pr-created',
                 }
                 : { branches, worktreeIds };
             if (prDeliveryId && (0, rail_pr_store_1.transitionDecision)(ctx.db, prDeliveryId, 'building', next, patch)) {
+                if (settledContinuation && !continuationPushFailed) {
+                    await (0, rail_worktree_release_1.releaseRailWorktrees)({ db: ctx.db, git, repoDir: baseRepo, worktreeIds });
+                }
                 broadcastPrState();
                 // Completion driver: refresh the origin conversation's card in place —
                 // on_review asks the question, discarded informs the outcome.

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

@@ -67,7 +67,9 @@ exports.executePrDecision = executePrDecision;
 const path = __importStar(require("path"));
 const artifact_registry_1 = require("./artifact-registry");
 const worktree_manager_1 = require("./worktree-manager");
+const pr_publisher_1 = require("./pr-publisher");
 const rail_pr_delivery_1 = require("./rail-pr-delivery");
+const rail_worktree_release_1 = require("./rail-worktree-release");
 const pr_naming_1 = require("./pr-naming");
 const pr_body_1 = require("./pr-body");
 const jira_db_1 = require("./jira/jira-db");
@@ -171,6 +173,46 @@ function batchWorktreeRoot(slug) {
     // Mirrors rail-isolated-launch's worktreesRoot — derivable, never stored.
     return path.join((0, artifact_registry_1.resolveHome)(), '.specrails', 'projects', slug, 'worktrees');
 }
+async function resolveExistingPrDecisionAfterPush(deps, row) {
+    if (!row.pr_url)
+        return 'pr_ready';
+    const r = await deps.exec.run('gh', ['pr', 'view', row.pr_url, '--json', 'isDraft,state'], deps.project.path);
+    if (r.code !== 0)
+        return 'pr_ready';
+    try {
+        const parsed = JSON.parse(r.stdout);
+        if (parsed.isDraft === true)
+            return 'pr_draft';
+    }
+    catch {
+        /* fall through to the conservative published/open state */
+    }
+    return 'pr_ready';
+}
+async function retryExistingPrFollowupPush(deps, row) {
+    if (!row.branch || !row.pr_url)
+        return { status: 502, body: { error: 'push_failed', detail: 'missing PR branch/url' } };
+    const pushed = await (0, pr_publisher_1.pushBranch)(deps.exec, {
+        repoDir: deps.project.path,
+        branch: row.branch,
+        baseBranch: row.base_branch,
+    });
+    if (pushed.state === 'local-only') {
+        const conflict = casTransition(deps, row, 'pr_failed', { prState: 'local-only' });
+        if (conflict)
+            return conflict;
+        finalizeTransition(deps, row.id);
+        return { status: 200, body: { ok: true, decision: 'pr_failed', prUrl: row.pr_url, detail: pushed.reason } };
+    }
+    const next = await resolveExistingPrDecisionAfterPush(deps, row);
+    const snap = (0, rail_pr_store_1.toPrDeliverySnapshot)(row);
+    const conflict = casTransition(deps, row, next, { prState: 'pr-created' });
+    if (conflict)
+        return conflict;
+    await (0, rail_worktree_release_1.releaseRailWorktrees)({ db: deps.db, git: deps.git, repoDir: deps.project.path, worktreeIds: snap.worktreeIds });
+    const after = finalizeTransition(deps, row.id);
+    return { status: 200, body: { ok: true, decision: next, prUrl: after?.prUrl ?? row.pr_url, prState: 'pr-created' } };
+}
 /**
  * Load the PR's ticket data (title/labels/description) from the ticket store,
  * with the Jira key resolved PER TICKET: the authoritative `jira_links` row
@@ -240,6 +282,9 @@ async function findRecoverableBranch(deps, unit, baseBranch) {
     return null;
 }
 async function runCreatePr(deps, row) {
+    if (row.decision === 'pr_failed' && row.pr_url && row.branch) {
+        return retryExistingPrFollowupPush(deps, row);
+    }
     const snap = (0, rail_pr_store_1.toPrDeliverySnapshot)(row);
     // Pre-flight: every succeeded unit branch must actually exist before we push
     // it — a missing ref can only degrade to local-only again, so a retry on a
@@ -363,6 +408,9 @@ async function runCreatePr(deps, row) {
     const conflict = casTransition(deps, row, next, patch);
     if (conflict)
         return conflict;
+    if (next === 'pr_draft' && patch.prUrl) {
+        await (0, rail_worktree_release_1.releaseRailWorktrees)({ db: deps.db, git: deps.git, repoDir: deps.project.path, worktreeIds: snap.worktreeIds });
+    }
     const after = finalizeTransition(deps, row.id);
     // Tickets stay on_review — a draft PR is still awaiting the engineer's merge.
     return {
@@ -380,9 +428,11 @@ async function runPublish(deps, row) {
     const r = await deps.exec.run('gh', ['pr', 'ready', row.pr_url], deps.project.path);
     if (r.code !== 0)
         return ghFailed(r); // no transition — the draft is still a draft
+    const snap = (0, rail_pr_store_1.toPrDeliverySnapshot)(row);
     const conflict = casTransition(deps, row, 'pr_ready');
     if (conflict)
         return conflict;
+    await (0, rail_worktree_release_1.releaseRailWorktrees)({ db: deps.db, git: deps.git, repoDir: deps.project.path, worktreeIds: snap.worktreeIds });
     finalizeTransition(deps, row.id);
     return { status: 200, body: { ok: true, decision: 'pr_ready', prUrl: row.pr_url } };
 }
@@ -467,11 +517,29 @@ async function runPollMerge(deps, row) {
         // Not merged (OPEN/CLOSED/unknown) → observation only, nothing changes.
         return { status: 200, body: { ok: true, decision: row.decision, merged: false } };
     }
+    const snap = (0, rail_pr_store_1.toPrDeliverySnapshot)(row);
+    const branchSet = new Set(snap.branches.map((b) => b.branch));
+    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 cleanup only */
+        }
+    }
+    await (0, rail_worktree_release_1.releaseRailWorktrees)({ db: deps.db, git: deps.git, repoDir: deps.project.path, worktreeIds: snap.worktreeIds, state: 'merged' });
+    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, 'merged');
     if (conflict)
         return conflict;
     finalizeTransition(deps, row.id);
-    const snap = (0, rail_pr_store_1.toPrDeliverySnapshot)(row);
     const changed = applyTicketTransition(deps, snap.ticketIds, 'done');
     try {
         deps.jiraSyncManager?.onRailMerged(changed, row.id, row.pr_url);