specrails-desktop 2.26.2 → 2.28.0

package/server/dist/headroom-routing.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setHeadroomRoutingState = setHeadroomRoutingState;
+exports.getHeadroomRoutingState = getHeadroomRoutingState;
+exports.providerForBinary = providerForBinary;
+exports.applyHeadroomEnvForBinary = applyHeadroomEnvForBinary;
+exports.withHeadroomSpawnEnv = withHeadroomSpawnEnv;
+const DEFAULT_PORT = 8787;
+let routingState = {
+    port: DEFAULT_PORT,
+    activeProviders: {},
+};
+function setHeadroomRoutingState(next) {
+    routingState = {
+        port: Number.isInteger(next.port) ? next.port : DEFAULT_PORT,
+        activeProviders: { ...next.activeProviders },
+    };
+}
+function getHeadroomRoutingState() {
+    return {
+        port: routingState.port,
+        activeProviders: { ...routingState.activeProviders },
+    };
+}
+function providerForBinary(binary) {
+    const name = binary.toLowerCase().replace(/\.cmd$|\.exe$/, '');
+    if (name === 'codex')
+        return 'codex';
+    if (name === 'claude')
+        return 'claude';
+    return null;
+}
+function applyHeadroomEnvForBinary(binary, env) {
+    const provider = providerForBinary(binary);
+    if (!provider || !routingState.activeProviders[provider])
+        return env ?? process.env;
+    const base = `http://127.0.0.1:${routingState.port}`;
+    const merged = { ...(env ?? process.env) };
+    if (provider === 'codex') {
+        merged.OPENAI_BASE_URL = `${base}/v1`;
+    }
+    else if (provider === 'claude') {
+        merged.ANTHROPIC_BASE_URL = base;
+    }
+    merged.HEADROOM_PORT = String(routingState.port);
+    return merged;
+}
+function withHeadroomSpawnEnv(binary, options = {}) {
+    return {
+        ...options,
+        env: applyHeadroomEnvForBinary(binary, options.env),
+    };
+}

package/server/dist/index.js

@@ -29,10 +29,13 @@ const agent_chat_router_1 = require("./agent-chat-router");
 const agent_chat_registry_1 = require("./agent-chat-registry");
 const browser_playwright_1 = require("./browser-playwright");
 const telemetry_receiver_1 = require("./telemetry-receiver");
+const headroom_manager_1 = require("./headroom-manager");
+const global_plugins_router_1 = require("./global-plugins-router");
 const telemetry_compactor_1 = require("./telemetry-compactor");
 const framework_manager_1 = require("./framework-manager");
 const artifact_registry_1 = require("./artifact-registry");
 const path_resolver_1 = require("./path-resolver");
+const dev_ports_1 = require("./dev-ports");
 // Side-effect import: registers every bundled ProviderAdapter (claude, codex,
 // future providers) so `getAdapter`/`hasAdapter`/`listAdapters` are populated
 // before any manager constructs a project context. See
@@ -85,12 +88,7 @@ if (parentPidArg) {
     }
 }
 // ─── Parse CLI args ───────────────────────────────────────────────────────────
-let port = 4200;
-for (let i = 2; i < process.argv.length; i++) {
-    if (process.argv[i] === '--port' && process.argv[i + 1]) {
-        port = parseInt(process.argv[++i], 10);
-    }
-}
+const port = (0, dev_ports_1.resolveServerPort)(process.argv);
 // ─── PID file management ──────────────────────────────────────────────────────
 const PID_DIR = path_1.default.join(os_1.default.homedir(), '.specrails');
 const PID_FILE = path_1.default.join(PID_DIR, 'manager.pid');
@@ -541,6 +539,11 @@ function applyPtyWsRateLimiting(ws) {
         mcpManager.start().catch((err) => console.error('[mcp] boot start failed:', err));
     }
     // ─── App-global agent chat (drives the app via its own MCP) ────────────────
+    const headroomManager = new headroom_manager_1.HeadroomManager(registry.desktopDb, broadcast, () => registry.installedProvidersUnion().filter((provider) => provider === 'codex' || provider === 'claude'));
+    app.use('/api/global-plugins', (0, global_plugins_router_1.createGlobalPluginsRouter)(headroomManager));
+    headroomManager.startActiveProxyOnBoot().catch((err) => {
+        console.error('[headroom] boot start failed:', err);
+    });
     const agentChatManager = new agent_chat_manager_1.AgentChatManager(broadcast, registry.desktopDb, port, registry);
     _agentChatManager = agentChatManager;
     // Publish the instance to the process-wide registry so the rails layer can

package/server/dist/mcp/guide.js

@@ -149,6 +149,9 @@ heading inside the description); \`labels\`; \`priority\`. Spec content is Engli
 - \`specrails_jobs(spawn, command)\` bypasses rails and enqueues an arbitrary
   slash-command job (e.g. \`/specrails:implement #5 --yes\`); \`queue\`, \`pause\`,
   \`resume\`, \`reorder\`, \`priority\` manage the queue.
+- Long-running shell commands launched with \`specrails_jobs(background_start)\`
+  create chat chips; use \`specrails_jobs(background_logs, pid)\` to read bounded
+  stdout/stderr tail when a chip exits or fails.
 
 ## Async results (IMPORTANT)
 

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

@@ -18,6 +18,7 @@ const setup_1 = require("./setup");
 const analytics_1 = require("./analytics");
 const git_1 = require("./git");
 const support_1 = require("./support");
+const env_1 = require("./env");
 /**
  * The full MCP tool catalog. Domain-facade tools each expose an `action` enum
  * and call the app's REST API over loopback (see apiCall). Meta tools receive a
@@ -42,6 +43,7 @@ function buildToolSpecs() {
     specs.push(...(0, setup_1.setupTools)());
     specs.push(...(0, analytics_1.analyticsTools)());
     specs.push(...(0, git_1.gitTools)());
+    specs.push(...(0, env_1.envTools)());
     specs.push(...(0, support_1.supportTools)());
     // Meta last (needs the full list for search/describe)
     specs.push(...(0, meta_1.metaTools)(() => specs));

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

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.envTools = envTools;
+const zod_1 = require("zod");
+const types_1 = require("./types");
+const worktree_env_discovery_1 = require("../../worktree-env-discovery");
+function uniq(names) {
+    const out = [];
+    for (const v of names) {
+        if (typeof v !== 'string')
+            continue;
+        const name = v.trim();
+        if (name && !out.includes(name))
+            out.push(name);
+    }
+    return out;
+}
+function envTools() {
+    return [
+        {
+            name: 'specrails_env',
+            title: 'Project worktree environment',
+            description: 'Read, scan, and configure the per-project environment variable NAME allowlist used for rail jobs and isolated loop worktrees. ' +
+                'Values are never read or stored by this tool; runs read them from the server environment and can recover configured names from the login shell when the desktop process is missing them. scan inspects safe repo config files such as package.json, .npmrc, .yarnrc.yml and pnpm-workspace.yaml for ${VAR} / process.env.VAR references and private scoped package auth hints. ' +
+                'Actions: get (read current names), scan (discover candidates), set (write names), auto_configure (scan then merge discovered names into settings).',
+            hintTier: 'read',
+            tier: (args) => (args.action === 'set' || args.action === 'auto_configure' ? 'write' : 'read'),
+            inputSchema: {
+                action: zod_1.z.enum(['get', 'scan', 'set', 'auto_configure']).describe('Operation'),
+                projectId: zod_1.z.string().optional().describe('Project id (defaults to the active project)'),
+                names: zod_1.z.array(zod_1.z.string()).optional().describe('set: env var names to configure'),
+                merge: zod_1.z.boolean().optional().describe('set: merge with existing names instead of replacing them (default true)'),
+            },
+            async handler(ctx, args) {
+                const action = args.action;
+                const base = (0, types_1.projectPath)(ctx, args.projectId);
+                if (action === 'get') {
+                    const settings = await (0, types_1.apiCall)(ctx, 'GET', `${base}/settings`);
+                    return { names: Array.isArray(settings.worktreeEnvPassthrough) ? settings.worktreeEnvPassthrough : [] };
+                }
+                if (action === 'scan') {
+                    const project = (0, types_1.requireProject)(ctx, args.projectId).project;
+                    return (0, worktree_env_discovery_1.scanWorktreeEnvRequirements)(project.path);
+                }
+                if (action === 'set') {
+                    const incoming = uniq(Array.isArray(args.names) ? args.names : []);
+                    if (incoming.length === 0)
+                        throw new Error('set requires at least one env var name in "names".');
+                    const merge = args.merge !== false;
+                    const current = await (0, types_1.apiCall)(ctx, 'GET', `${base}/settings`);
+                    const existing = Array.isArray(current.worktreeEnvPassthrough) ? uniq(current.worktreeEnvPassthrough) : [];
+                    const next = merge ? uniq([...existing, ...incoming]) : incoming;
+                    const res = await (0, types_1.apiCall)(ctx, 'PATCH', `${base}/settings`, { worktreeEnvPassthrough: next });
+                    return { ok: true, names: res.settings?.worktreeEnvPassthrough ?? next, changed: next.filter((n) => !existing.includes(n)) };
+                }
+                if (action === 'auto_configure') {
+                    const project = (0, types_1.requireProject)(ctx, args.projectId).project;
+                    const scan = (0, worktree_env_discovery_1.scanWorktreeEnvRequirements)(project.path);
+                    const discovered = scan.candidates.map((c) => c.name);
+                    const current = await (0, types_1.apiCall)(ctx, 'GET', `${base}/settings`);
+                    const existing = Array.isArray(current.worktreeEnvPassthrough) ? uniq(current.worktreeEnvPassthrough) : [];
+                    if (discovered.length === 0)
+                        return { ok: true, names: existing, changed: [], scan };
+                    const next = uniq([...existing, ...discovered]);
+                    const res = await (0, types_1.apiCall)(ctx, 'PATCH', `${base}/settings`, { worktreeEnvPassthrough: next });
+                    return { ok: true, names: res.settings?.worktreeEnvPassthrough ?? next, changed: next.filter((n) => !existing.includes(n)), scan };
+                }
+                throw new Error(`Unknown action "${action}".`);
+            },
+        },
+    ];
+}

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

@@ -1,8 +1,52 @@
 "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");
+const loop_runs_store_1 = require("../../loop-runs-store");
+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(),
+        }),
+        onExited: (process) => broadcast({
+            type: 'background_process.exited',
+            process,
+            projectId: process.projectId,
+            timestamp: new Date().toISOString(),
+        }),
+    };
+}
+function backgroundStartBusyReason(projectCtx) {
+    const activeJobId = typeof projectCtx.queueManager?.getActiveJobId === 'function' ? projectCtx.queueManager.getActiveJobId() : null;
+    if (activeJobId)
+        return `job ${activeJobId} is still running`;
+    try {
+        const runningLoops = (0, loop_runs_store_1.listRunningLoopRuns)(projectCtx.db, projectCtx.project.id);
+        if (runningLoops.length > 0)
+            return `loop run ${runningLoops[0].id} is still running`;
+    }
+    catch {
+        // Some unit harnesses stub the DB narrowly; absence of loop metadata is not a blocker.
+    }
+    return null;
+}
 /**
  * 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 +64,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 confirmed:true after explicit user confirmation before use), background_logs, 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 +79,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 +109,9 @@ function jobsTools() {
                     'default_spec_model',
                     'interactive_turn',
                     'finalize',
+                    'background_start',
+                    'background_logs',
+                    'background_kill',
                 ])
                     .describe('Operation to perform'),
                 projectId: zod_1.z.string().optional().describe('Project id (defaults to the active project)'),
@@ -73,7 +121,7 @@ function jobsTools() {
                     .optional()
                     .describe('Job id (for get / cancel / priority / diagnostic / interactive_turn / finalize)'),
                 // ── list / export pagination + filters ──
-                limit: zod_1.z.number().optional().describe('Page size for list (1-200, default 50) / activity (1-100, default 50)'),
+                limit: zod_1.z.number().optional().describe('Page size for list (1-200, default 50) / activity (1-100, default 50); background_logs returns the last N buffered log lines'),
                 offset: zod_1.z.number().optional().describe('Page offset for list'),
                 status: zod_1.z.string().optional().describe('Filter by job status (list)'),
                 from: zod_1.z.string().optional().describe('ISO date lower bound (list / export / purge)'),
@@ -99,6 +147,11 @@ 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_logs/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_logs/background_kill'),
+                confirmed: zod_1.z.boolean().optional().describe('background_start only: must be true after explicit user confirmation for this exact command'),
+                allowWhileBusy: zod_1.z.boolean().optional().describe('background_start only: override active job/loop guard after explicit user confirmation'),
                 // ── export ──
                 format: zod_1.z.enum(['json', 'csv']).optional().describe('Export format (default json)'),
                 // ── default_spec_model ──
@@ -270,6 +323,61 @@ 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".');
+                        if (args.confirmed !== true)
+                            throw new Error('background_start requires confirmed:true after explicit user confirmation for this exact 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 busyReason = backgroundStartBusyReason(projectCtx);
+                        if (busyReason && args.allowWhileBusy !== true) {
+                            throw new Error(`background_start refused because ${busyReason}. Wait for it to finish, or pass allowWhileBusy:true only after explicit user confirmation.`);
+                        }
+                        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' };
+                    }
+                    case 'background_logs': {
+                        const pid = args.pid;
+                        if (typeof pid !== 'number' || !Number.isFinite(pid))
+                            throw new Error('background_logs requires a numeric "pid".');
+                        const chatId = args.chatId ?? ctx.originConversationId ?? undefined;
+                        if (!chatId || !chatId.trim())
+                            throw new Error('background_logs requires a "chatId".');
+                        const projectCtx = (0, types_1.requireProject)(ctx, args.projectId);
+                        const limit = typeof args.limit === 'number' && Number.isFinite(args.limit) ? args.limit : undefined;
+                        const logs = (0, transient_children_1.getBackgroundProcessLogs)(pid, {
+                            projectId: projectCtx.project.id,
+                            chatId: chatId.trim(),
+                            ...(limit !== undefined ? { limit } : {}),
+                        });
+                        if (!logs)
+                            throw new Error('background_logs requires a registered pid in the same project/chat; logs may have expired.');
+                        return {
+                            ok: true,
+                            ...logs,
+                            hint: logs.lines.length > 0
+                                ? 'Inspect stdout/stderr to explain why the background process exited or failed.'
+                                : 'No stdout/stderr lines have been captured yet; the process may not have emitted newline-terminated output.',
+                        };
+                    }
                     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;
@@ -103,7 +105,14 @@ function resolveBundledBinDirs(runtimesPath) {
     else if (fileExists(path_1.default.join(runtimesPath, 'git', 'bin', 'git'))) {
         gitBinDir = path_1.default.join(runtimesPath, 'git', 'bin');
     }
-    return { nodeBinDir, gitBinDir };
+    const uvBinDir = isWin
+        ? (fileExists(path_1.default.join(runtimesPath, 'uv', 'uv.exe')) ? path_1.default.join(runtimesPath, 'uv')
+            : fileExists(path_1.default.join(runtimesPath, 'uv', 'bin', 'uv.exe')) ? path_1.default.join(runtimesPath, 'uv', 'bin')
+                : null)
+        : (fileExists(path_1.default.join(runtimesPath, 'uv', 'bin', 'uv')) ? path_1.default.join(runtimesPath, 'uv', 'bin')
+            : fileExists(path_1.default.join(runtimesPath, 'uv', 'uv')) ? path_1.default.join(runtimesPath, 'uv')
+                : null);
+    return { nodeBinDir, gitBinDir, uvBinDir };
 }
 /**
  * Bin dir of the bundled GitHub CLI (`runtimes/gh/bin/gh[.exe]`), or null.
@@ -264,7 +273,7 @@ function resolveStartupPathBase() {
     if (process.env.SPECRAILS_IS_DESKTOP === '1') {
         const runtimesPath = process.env.SPECRAILS_BUNDLED_RUNTIMES_PATH;
         if (runtimesPath) {
-            const { nodeBinDir, gitBinDir } = resolveBundledBinDirs(runtimesPath);
+            const { nodeBinDir, gitBinDir, uvBinDir } = resolveBundledBinDirs(runtimesPath);
             // Activate the bundle only when BOTH node and git are present. A partial
             // bundle (one tool present, the other missing — a botched extraction) is
             // treated as NOT active so the full system fallback (fast-path + login-shell)
@@ -273,7 +282,7 @@ function resolveStartupPathBase() {
             if (nodeBinDir && gitBinDir) {
                 const inherited = splitPath(process.env.PATH);
                 const inheritedSet = new Set(inherited);
-                const bundledDirs = [nodeBinDir, gitBinDir].filter((d) => !inheritedSet.has(d));
+                const bundledDirs = [nodeBinDir, gitBinDir, uvBinDir].filter((d) => !!d && !inheritedSet.has(d));
                 bundledDirs.forEach((d) => inheritedSet.add(d));
                 // Provider CLIs (claude/codex/gemini) are NEVER bundled — they always
                 // come from the system. On Windows their `.cmd` shims live in
@@ -464,6 +473,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 +513,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 +559,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 +569,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 +647,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 {