specrails-desktop 2.26.1 → 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/mcp/tools/rails.js

@@ -20,6 +20,8 @@ function prDeliveryContinuesTickets(raw, ticketIds) {
         return false;
     if (typeof raw.branch !== 'string' || !raw.branch)
         return false;
+    if (raw.prState !== 'pr-created')
+        return false;
     if (!Array.isArray(raw.ticketIds))
         return false;
     const covered = new Set(raw.ticketIds.filter((id) => typeof id === 'number'));

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/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-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-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/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),
             };
         }