specrails-desktop 2.26.2 → 2.28.0

package/server/dist/agent-chat-router.js

@@ -12,6 +12,7 @@ const providers_1 = require("./providers");
 const agent_tier_1 = require("./agent-tier");
 const attachment_manager_1 = require("./attachment-manager");
 const agent_store_1 = require("./agent-store");
+const transient_children_1 = require("./transient-children");
 function isAgentChatEnabled() {
     return process.env.SPECRAILS_AGENT_CHAT !== 'false';
 }
@@ -235,6 +236,7 @@ function createAgentChatRouter(deps) {
     router.delete('/conversations/:id', (req, res) => {
         const id = String(req.params.id);
         manager.abort(id);
+        (0, transient_children_1.killBackgroundProcessesForChat)(id);
         (0, agent_store_1.deleteAgentConversation)(desktopDb, id);
         // Cascade-remove the conversation's attachment directory (best-effort).
         void attachment_manager_1.attachmentManager.deleteAllAgent(id).catch((e) => console.error('[agent-chat] attachment cleanup failed:', e));

package/server/dist/agent-operator-prompt.js

@@ -161,6 +161,7 @@ never try to work around the refusal. When you are about to propose an action
 above the current level, say so up front.
 
 - NEVER call an ai-spawn action (rails launch, jobs spawn/interactive_turn,
+  jobs background_start,
   specs create/generate/ai_edit/contract_refine/smash, chat send, agents
   generate/test/refine, code regenerate_summary) without first proposing it in
   plain words — what runs, on which project, which engine/model, roughly how
@@ -401,6 +402,21 @@ summary later.
 - \`specrails_jobs(spawn, command)\` bypasses rails to enqueue an arbitrary
   slash-command job (e.g. \`/specrails:implement #5 --yes\`). Use rails for
   normal implement flows; spawn for advanced one-offs.
+- **Long-running shell commands get chips.** When the user asks you to run a
+  server/watch/tail command that should keep running (for example \`npm run dev\`,
+  \`vite --host\`, \`tail -f\`, or a local service), propose
+  \`specrails_jobs(background_start)\` with the command, project and cwd, wait for
+  explicit yes, then call that tool with \`confirmed:true\`. Do NOT use a raw shell/background-task
+  runner for these requests: only \`background_start\` emits the app events that
+  create the killable chip above this agent chat's composer. You normally do not
+  need to pass \`chatId\`; the in-app MCP origin conversation owns it. If a
+  job/loop is still running, do not pass \`allowWhileBusy:true\` unless the user
+  explicitly confirms running concurrently.
+- **Diagnose background chip failures from logs.** If user asks whether
+  background chip command failed or why it stopped, call
+  \`specrails_jobs(background_logs, pid)\` for that PID before asking
+  to relaunch. Explain from captured stdout/stderr tail; only say logs
+  unavailable if PID unknown/expired or captured output empty.
 - **Launch, then release the turn.** When a rail launch or job spawn is
   accepted (202), report the returned jobId(s)/ids VERBATIM and END YOUR REPLY
   immediately — do NOT sit on the turn watching the run. Progress streams live
@@ -471,4 +487,4 @@ When the user has no projects yet, or asks to add one:
 Setup is QUICK-only (fast, offline). Do NOT offer, mention, or attempt a "full"
 or "enrich" install — that flow is deprecated and not available through you.
 `;
-exports.OPERATOR_SYSTEM_PROMPT = `You are the Specrails operator agent, embedded inside the Specrails Desktop app; drive it on the user's behalf using the specrails_* MCP tools. Your full operator manual is the CLAUDE.md auto-loaded from your working directory — follow it. Non-negotiables: target a project with specrails_select_project or the projectId argument, and ask rather than guess when none is pinned; support/troubleshooting/install/usage/job-failure questions use specrails_support first and never become specs unless the user pivots to product work; missing agents/skills/slash commands concern the app-global specrails-core framework, never project-owned files — never say agents/skills/commands live inside the project; project setup checkpoints are not a core health signal, so pending/0 agents/0 commands must not trigger specrails_setup(install) or a project repair recommendation; offer core_update_check/core_update_apply only for global core updates, and if global core is current ask for the concrete job error/diagnostic; an on_review spec with an open PR, including a published pr_ready card, can be relaunched to continue that PR branch — do not require publish/discard/merge first; short async 202 ops (spec generation, ai-edit) may be awaited with specrails_watch (projectId required), but after a rail/job LAUNCH is accepted end your reply immediately — progress streams live in the conversation's run card and the app; watch a launched run only when the user explicitly asks you to wait, with a bounded untilMs; never claim success from a 202 acceptance alone — verify from a terminal event or a domain read (e.g. specrails_jobs get); call the free-form autonomous rail mode Freestyle in prose — freestyle/factory:freestyle/{{cmd:freestyle}} are canonical API/id/token values for that same capability; respect the cumulative permission ladder observe / edit / operate / autonomous — if a tool is refused, name the level the user must Shift+Tab to, never work around it; when refining a spec, ground it in the real codebase FIRST (specrails_code tree/read_file/summary + specrails_specs list) and show the evolving draft as one fenced spec-draft JSON block (title, description, labels, priority, acceptanceCriteria) at the end of each turn that changed it — the app renders it as a live card; persist the refined spec with specrails_specs commit_draft (no conversationId) — never route it through create/generate, which regenerate the content with AI; commit_draft appends a Contract Layer by default via one short background AI pass — pass contractRefine false when the user declines it; report tool outputs faithfully, including failures. Format replies for easy reading: short paragraphs separated by blank lines, bullet lists for enumerations. When asking the user to pick between concrete choices, end the reply with a fenced options code block containing a JSON array of the 2-6 choice labels (rendered as clickable chips); never use that block otherwise.`;
+exports.OPERATOR_SYSTEM_PROMPT = `You are the Specrails operator agent, embedded inside the Specrails Desktop app; drive it on the user's behalf using the specrails_* MCP tools. Your full operator manual is the CLAUDE.md auto-loaded from your working directory — follow it. Non-negotiables: target a project with specrails_select_project or the projectId argument, and ask rather than guess when none is pinned; support/troubleshooting/install/usage/job-failure questions use specrails_support first and never become specs unless the user pivots to product work; missing agents/skills/slash commands concern the app-global specrails-core framework, never project-owned files — never say agents/skills/commands live inside the project; project setup checkpoints are not a core health signal, so pending/0 agents/0 commands must not trigger specrails_setup(install) or a project repair recommendation; offer core_update_check/core_update_apply only for global core updates, and if global core is current ask for the concrete job error/diagnostic; an on_review spec with an open PR, including a published pr_ready card, can be relaunched to continue that PR branch — do not require publish/discard/merge first; run long-lived server/watch/tail shell commands with specrails_jobs background_start and confirmed:true after explicit user confirmation, not a raw shell runner, so the app can show the killable background chip in this chat; if a background chip exits/fails, use specrails_jobs background_logs for its pid before asking to relaunch; if a job/loop is still running, pass allowWhileBusy:true only after explicit concurrent confirmation; short async 202 ops (spec generation, ai-edit) may be awaited with specrails_watch (projectId required), but after a rail/job LAUNCH is accepted end your reply immediately — progress streams live in the conversation's run card and the app; watch a launched run only when the user explicitly asks you to wait, with a bounded untilMs; never claim success from a 202 acceptance alone — verify from a terminal event or a domain read (e.g. specrails_jobs get); call the free-form autonomous rail mode Freestyle in prose — freestyle/factory:freestyle/{{cmd:freestyle}} are canonical API/id/token values for that same capability; respect the cumulative permission ladder observe / edit / operate / autonomous — if a tool is refused, name the level the user must Shift+Tab to, never work around it; when refining a spec, ground it in the real codebase FIRST (specrails_code tree/read_file/summary + specrails_specs list) and show the evolving draft as one fenced spec-draft JSON block (title, description, labels, priority, acceptanceCriteria) at the end of each turn that changed it — the app renders it as a live card; persist the refined spec with specrails_specs commit_draft (no conversationId) — never route it through create/generate, which regenerate the content with AI; commit_draft appends a Contract Layer by default via one short background AI pass — pass contractRefine false when the user declines it; report tool outputs faithfully, including failures. Format replies for easy reading: short paragraphs separated by blank lines, bullet lists for enumerations. When asking the user to pick between concrete choices, end the reply with a fenced options code block containing a JSON array of the 2-6 choice labels (rendered as clickable chips); never use that block otherwise.`;

package/server/dist/db.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_FREESTYLE_PRE_PROMPT = void 0;
+exports.WORKTREE_ENV_NAME_RE = exports.DEFAULT_FREESTYLE_PRE_PROMPT = void 0;
 exports.initDb = initDb;
 exports.createJob = createJob;
 exports.markJobInteractive = markJobInteractive;
@@ -38,6 +38,7 @@ exports.deleteTemplate = deleteTemplate;
 exports.skipJob = skipJob;
 exports.getPipelineJobs = getPipelineJobs;
 exports.getStats = getStats;
+exports.normalizeWorktreeEnvPassthrough = normalizeWorktreeEnvPassthrough;
 exports.getProjectSettings = getProjectSettings;
 exports.getFreestylePrePrompt = getFreestylePrePrompt;
 exports.updateProjectSettings = updateProjectSettings;
@@ -722,7 +723,7 @@ const MIGRATIONS = [
     },
     // Migration 36: rail_pr_deliveries — one row per isolated rail LAUNCH tracking
     // the ask-first PR decision lifecycle (building → on_review → pr_draft →
-    // pr_ready → merged | discarded | pr_failed). The durable single source of
+    // pr_ready → merged | discarded | implementation_failed | pr_failed). The durable single source of
     // truth both decision surfaces (rail row + agent chat) read and write, so a
     // refresh/restart never loses a pending PR decision. `branches` captures the
     // per-unit DeliverBranch records at build-settle (deferred deliverRailAsPr
@@ -1238,18 +1239,57 @@ exports.DEFAULT_FREESTYLE_PRE_PROMPT = [
     'Do NOT follow any structured architect/developer/reviewer pipeline — use your own judgement and the repo conventions.',
     'Never ask for confirmation; there is no human to answer. Choose the recommended option and proceed.',
 ].join('\n');
+exports.WORKTREE_ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const WORKTREE_ENV_MAX_NAMES = 64;
+const WORKTREE_ENV_MAX_NAME_LENGTH = 128;
+function normalizeWorktreeEnvPassthrough(value) {
+    if (!Array.isArray(value))
+        throw new Error('worktreeEnvPassthrough must be an array of environment variable names');
+    const out = [];
+    const seen = new Set();
+    for (const raw of value) {
+        if (typeof raw !== 'string')
+            throw new Error('worktreeEnvPassthrough entries must be strings');
+        const name = raw.trim();
+        if (!name)
+            continue;
+        if (name.length > WORKTREE_ENV_MAX_NAME_LENGTH)
+            throw new Error(`environment variable name is too long: ${name.slice(0, 24)}...`);
+        if (!exports.WORKTREE_ENV_NAME_RE.test(name))
+            throw new Error(`invalid environment variable name: ${name}`);
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        out.push(name);
+        if (out.length > WORKTREE_ENV_MAX_NAMES)
+            throw new Error(`worktreeEnvPassthrough can contain at most ${WORKTREE_ENV_MAX_NAMES} names`);
+    }
+    return out;
+}
+function parseWorktreeEnvPassthrough(raw) {
+    if (!raw)
+        return [];
+    try {
+        return normalizeWorktreeEnvPassthrough(JSON.parse(raw));
+    }
+    catch {
+        return [];
+    }
+}
 function getProjectSettings(db) {
     const telemetryRow = db.prepare(`SELECT value FROM queue_state WHERE key = 'config.pipeline_telemetry_enabled'`).get();
     const modelRow = db.prepare(`SELECT value FROM queue_state WHERE key = 'config.orchestrator_model'`).get();
     const prePromptRow = db.prepare(`SELECT value FROM queue_state WHERE key = 'config.pre_prompt'`).get();
     const freestylePrePromptRow = db.prepare(`SELECT value FROM queue_state WHERE key = 'config.freestyle_pre_prompt'`).get();
     const integrationBranchRow = db.prepare(`SELECT value FROM queue_state WHERE key = 'config.integration_branch'`).get();
+    const worktreeEnvPassthroughRow = db.prepare(`SELECT value FROM queue_state WHERE key = 'config.worktree_env_passthrough'`).get();
     return {
         pipelineTelemetryEnabled: telemetryRow?.value === 'true',
         orchestratorModel: modelRow?.value ?? 'sonnet',
         prePrompt: prePromptRow?.value ?? '',
         freestylePrePrompt: freestylePrePromptRow?.value ?? '',
         integrationBranch: integrationBranchRow?.value ?? '',
+        worktreeEnvPassthrough: parseWorktreeEnvPassthrough(worktreeEnvPassthroughRow?.value),
     };
 }
 /** Resolve the effective Freestyle pre-prompt: the per-project override when
@@ -1289,6 +1329,15 @@ function updateProjectSettings(db, patch) {
             db.prepare(`INSERT OR REPLACE INTO queue_state (key, value) VALUES ('config.integration_branch', ?)`).run(patch.integrationBranch.trim());
         }
     }
+    if (patch.worktreeEnvPassthrough !== undefined) {
+        const names = normalizeWorktreeEnvPassthrough(patch.worktreeEnvPassthrough);
+        if (names.length === 0) {
+            db.prepare(`DELETE FROM queue_state WHERE key = 'config.worktree_env_passthrough'`).run();
+        }
+        else {
+            db.prepare(`INSERT OR REPLACE INTO queue_state (key, value) VALUES ('config.worktree_env_passthrough', ?)`).run(JSON.stringify(names));
+        }
+    }
 }
 // ─── Explore Spec acceleration ────────────────────────────────────────────────
 /**

package/server/dist/dev-ports.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_DEV_CLIENT_PORT = exports.DEFAULT_DEV_SERVER_PORT = void 0;
+exports.parseDevPort = parseDevPort;
+exports.resolveServerPort = resolveServerPort;
+exports.resolveWebDevPorts = resolveWebDevPorts;
+exports.DEFAULT_DEV_SERVER_PORT = 4200;
+exports.DEFAULT_DEV_CLIENT_PORT = 4201;
+function parseDevPort(value, fallback) {
+    if (value == null || value.trim() === '')
+        return fallback;
+    const port = Number(value);
+    if (!Number.isInteger(port) || port <= 0 || port > 65535)
+        return fallback;
+    return port;
+}
+function resolveServerPort(argv, env = process.env) {
+    let port = parseDevPort(env.SPECRAILS_DEV_SERVER_PORT ?? env.SPECRAILS_PORT, exports.DEFAULT_DEV_SERVER_PORT);
+    for (let i = 2; i < argv.length; i++) {
+        if (argv[i] === '--port' && argv[i + 1]) {
+            port = parseDevPort(argv[++i], port);
+        }
+    }
+    return port;
+}
+function resolveWebDevPorts(env = process.env) {
+    const serverPort = parseDevPort(env.SPECRAILS_DEV_SERVER_PORT, exports.DEFAULT_DEV_SERVER_PORT);
+    const clientPort = parseDevPort(env.SPECRAILS_DEV_CLIENT_PORT, exports.DEFAULT_DEV_CLIENT_PORT);
+    return {
+        serverPort,
+        clientPort,
+        serverOrigin: `http://localhost:${serverPort}`,
+        wsUrl: `ws://localhost:${serverPort}`,
+    };
+}

package/server/dist/global-plugins-router.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGlobalPluginsRouter = createGlobalPluginsRouter;
+const express_1 = require("express");
+function isProvider(value) {
+    return value === 'codex' || value === 'claude';
+}
+function createGlobalPluginsRouter(headroom) {
+    const router = (0, express_1.Router)();
+    router.get('/', async (_req, res) => {
+        res.json({
+            plugins: [
+                {
+                    id: 'headroom-ai',
+                    name: 'Headroom AI',
+                    scope: 'global',
+                    status: await headroom.getFreshState(),
+                },
+                { id: 'jira', name: 'Jira', scope: 'project' },
+                { id: 'serena', name: 'Serena', scope: 'project' },
+            ],
+        });
+    });
+    router.get('/headroom', async (_req, res) => {
+        res.json({ state: await headroom.getFreshState() });
+    });
+    router.get('/headroom/diagnostics', (_req, res) => {
+        res.json(headroom.diagnostics());
+    });
+    router.post('/headroom/install', async (_req, res) => {
+        const result = await headroom.install();
+        res.status(result.ok ? 200 : 409).json(result);
+    });
+    router.post('/headroom/activate', async (req, res) => {
+        const provider = req.body?.provider;
+        if (!isProvider(provider)) {
+            res.status(400).json({ error: 'provider must be codex or claude' });
+            return;
+        }
+        const result = await headroom.activate(provider);
+        res.status(result.ok ? 200 : 409).json(result);
+    });
+    router.post('/headroom/deactivate', async (req, res) => {
+        const provider = req.body?.provider;
+        if (!isProvider(provider)) {
+            res.status(400).json({ error: 'provider must be codex or claude' });
+            return;
+        }
+        const result = await headroom.deactivate(provider);
+        res.status(result.ok ? 200 : 409).json(result);
+    });
+    router.post('/headroom/uninstall', async (_req, res) => {
+        const result = await headroom.uninstall();
+        res.status(result.ok ? 200 : 409).json(result);
+    });
+    router.post('/headroom/port', async (req, res) => {
+        const port = Number(req.body?.port);
+        const result = await headroom.setPort(port);
+        res.status(result.ok ? 200 : 400).json(result);
+    });
+    return router;
+}