specrails-desktop 2.62.0 → 2.63.1

package/server/dist/modules/project-settings/adapters/http.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerProjectSettingsHttp = registerProjectSettingsHttp;
+exports.registerEnvPassthroughStatusHttp = registerEnvPassthroughStatusHttp;
 const __1 = require("..");
 /** Inbound adapter: translate HTTP into use cases and domain errors into HTTP. */
 function registerProjectSettingsHttp(router, serviceForRequest, 
@@ -34,3 +35,26 @@ onUpdated) {
         }
     });
 }
+/** Inbound adapter for `GET /:projectId/env-passthrough/status` and
+ * `POST /:projectId/env-passthrough/recheck`. Responses carry names and
+ * states only; values never reach this adapter. */
+function registerEnvPassthroughStatusHttp(router, port) {
+    router.get('/:projectId/env-passthrough/status', async (req, res) => {
+        try {
+            res.json(await port.read(req));
+        }
+        catch (error) {
+            console.error('[project-router] env status error:', error);
+            res.status(500).json({ error: 'Failed to read environment status' });
+        }
+    });
+    router.post('/:projectId/env-passthrough/recheck', async (req, res) => {
+        try {
+            res.json(await port.recheck(req));
+        }
+        catch (error) {
+            console.error('[project-router] env recheck error:', error);
+            res.status(500).json({ error: 'Failed to recheck environment' });
+        }
+    });
+}

package/server/dist/path-resolver.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.AUTH_ENV_VARS = void 0;
+exports.LOGIN_SHELL_PROBE_TIMEOUT_MS = exports.AUTH_ENV_VARS = void 0;
 exports.ensureWindowsBaseEnv = ensureWindowsBaseEnv;
 exports.resolveBundledRuntimePath = resolveBundledRuntimePath;
 exports.resolveBundledNodeExe = resolveBundledNodeExe;
@@ -12,6 +12,10 @@ exports.parseLoginShellOutput = parseLoginShellOutput;
 exports.augmentPathFromLoginShell = augmentPathFromLoginShell;
 exports.parseLoginShellEnv = parseLoginShellEnv;
 exports.augmentEnvFromLoginShell = augmentEnvFromLoginShell;
+exports.resolveLoginShellProbeTimeoutMs = resolveLoginShellProbeTimeoutMs;
+exports.hasCompleteLoginShellEnvBlock = hasCompleteLoginShellEnvBlock;
+exports.readEnvFromLoginShell = readEnvFromLoginShell;
+exports.readEnvFromLoginShellSyncDetailed = readEnvFromLoginShellSyncDetailed;
 exports.readEnvFromLoginShellSync = readEnvFromLoginShellSync;
 exports.augmentEnvFromLoginShellSync = augmentEnvFromLoginShellSync;
 exports.augmentAuthEnvFromLoginShell = augmentAuthEnvFromLoginShell;
@@ -580,17 +584,130 @@ async function augmentEnvFromLoginShell(names, opts = {}) {
         });
     });
 }
-/** Read missing configured names without mutating the caller's or global env.
- * Callers own any cache so project credentials cannot leak across scopes. */
-function readEnvFromLoginShellSync(names, opts = {}) {
+/** Default budget for the asynchronous project-env probe. Real interactive
+ * profiles (oh-my-zsh, nvm, powerlevel10k, conda) routinely exceed 1.5 s. */
+exports.LOGIN_SHELL_PROBE_TIMEOUT_MS = 10_000;
+const LOGIN_SHELL_PROBE_MAX_TIMEOUT_MS = 120_000;
+const LOGIN_SHELL_OUTPUT_CAP = 1024 * 1024;
+/** `SPECRAILS_LOGIN_SHELL_TIMEOUT_MS` overrides the asynchronous probe budget.
+ * Invalid or non-positive values fall back to the 10 s default; values are
+ * capped at 2 minutes so a typo cannot park a probe forever. */
+function resolveLoginShellProbeTimeoutMs(env = process.env) {
+    const raw = env.SPECRAILS_LOGIN_SHELL_TIMEOUT_MS?.trim();
+    if (!raw || !/^\d+$/.test(raw))
+        return exports.LOGIN_SHELL_PROBE_TIMEOUT_MS;
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value <= 0)
+        return exports.LOGIN_SHELL_PROBE_TIMEOUT_MS;
+    return Math.min(value, LOGIN_SHELL_PROBE_MAX_TIMEOUT_MS);
+}
+/** True when the probe output contains the complete env sentinel block. The
+ * block is the proof that the printf ran, independent of the shell's status. */
+function hasCompleteLoginShellEnvBlock(stdout) {
+    const begin = stdout.indexOf(ENV_BEGIN);
+    return begin !== -1 && stdout.indexOf(ENV_END, begin + ENV_BEGIN.length) !== -1;
+}
+function loginShellProbeSkipped(names = []) {
+    return { values: {}, status: 'skipped', exitCode: null, shell: null, names };
+}
+function pickRecovered(stdout, wanted) {
+    const recovered = parseLoginShellEnv(stdout);
+    const out = {};
+    for (const key of wanted) {
+        const val = recovered[key];
+        if (val)
+            out[key] = val;
+    }
+    return out;
+}
+function settleLoginShellProbe(stdout, wanted, shell, exitCode, timedOut) {
+    if (hasCompleteLoginShellEnvBlock(stdout)) {
+        return { values: pickRecovered(stdout, wanted), status: 'ok', exitCode, shell, names: wanted };
+    }
+    return { values: {}, status: timedOut ? 'timeout' : 'failed', exitCode, shell, names: wanted };
+}
+function wantedLoginShellNames(names, env) {
     if (process.platform === 'win32')
-        return {};
+        return null;
     if (process.env.NODE_ENV === 'test' || process.env.VITEST === 'true')
-        return {};
+        return null;
+    return normalizeLoginShellEnvNames(names).filter((name) => !env[name]);
+}
+/** Asynchronously read missing configured names from the login shell without
+ * blocking the event loop or mutating any environment. Values from a complete
+ * sentinel block are accepted regardless of the shell's exit status. Output is
+ * capped at 1 MiB; the child is killed at the timeout. Callers own any cache. */
+function readEnvFromLoginShell(names, opts = {}) {
     const env = opts.env ?? process.env;
-    const wanted = normalizeLoginShellEnvNames(names).filter((name) => !env[name]);
+    const wanted = wantedLoginShellNames(names, env);
+    if (wanted === null)
+        return Promise.resolve(loginShellProbeSkipped());
     if (wanted.length === 0)
-        return {};
+        return Promise.resolve(loginShellProbeSkipped(wanted));
+    const spawnFn = opts.spawnFn ?? child_process_1.spawn;
+    const timeoutMs = opts.timeoutMs ?? resolveLoginShellProbeTimeoutMs(env);
+    const shell = resolveLoginShell(env);
+    const command = buildLoginShellEnvCommand(wanted);
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawnFn(shell, ['-l', '-i', '-c', command], { env, stdio: ['ignore', 'pipe', 'pipe'] });
+        }
+        catch {
+            resolve({ values: {}, status: 'failed', exitCode: null, shell, names: wanted });
+            return;
+        }
+        let stdout = '';
+        let timedOut = false;
+        let settled = false;
+        const kill = () => { try {
+            child.kill('SIGKILL');
+        }
+        catch { /* ignore */ } };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            kill();
+            // Settle now: a background job started by the profile can keep the pipes
+            // (and so 'close') open long after the shell itself was killed. A complete
+            // block printed before a hung exit hook is still a success.
+            finish(null);
+        }, timeoutMs);
+        const finish = (exitCode) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(settleLoginShellProbe(stdout, wanted, shell, exitCode, timedOut));
+        };
+        child.stdout?.on('data', (chunk) => {
+            if (stdout.length >= LOGIN_SHELL_OUTPUT_CAP)
+                return;
+            stdout += chunk.toString('utf-8');
+            if (stdout.length >= LOGIN_SHELL_OUTPUT_CAP) {
+                stdout = stdout.slice(0, LOGIN_SHELL_OUTPUT_CAP);
+                if (!hasCompleteLoginShellEnvBlock(stdout))
+                    kill();
+            }
+        });
+        child.stderr?.on('data', () => { });
+        child.on('error', () => finish(null));
+        child.on('close', (code) => finish(typeof code === 'number' ? code : null));
+    });
+}
+function isSpawnSyncTimeout(res) {
+    const error = res.error;
+    return Boolean(error && (error.code === 'ETIMEDOUT' || /ETIMEDOUT/.test(error.message)));
+}
+/** Synchronous, detailed variant used only as the cold fallback at spawn time.
+ * Keeps the short 1.5 s budget so a cold spawn never freezes the server for
+ * long, and accepts a complete sentinel block regardless of exit status. */
+function readEnvFromLoginShellSyncDetailed(names, opts = {}) {
+    const env = opts.env ?? process.env;
+    const wanted = wantedLoginShellNames(names, env);
+    if (wanted === null)
+        return loginShellProbeSkipped();
+    if (wanted.length === 0)
+        return loginShellProbeSkipped(wanted);
     const spawnSyncFn = opts.spawnSyncFn ?? child_process_1.spawnSync;
     const timeoutMs = opts.timeoutMs ?? LOGIN_SHELL_TIMEOUT_MS;
     const shell = resolveLoginShell(env);
@@ -602,23 +719,21 @@ function readEnvFromLoginShellSync(names, opts = {}) {
             encoding: 'utf8',
             stdio: ['ignore', 'pipe', 'pipe'],
             timeout: timeoutMs,
-            maxBuffer: 1024 * 1024,
+            // An interactive shell can ignore SIGTERM; the cold fallback must stay bounded.
+            killSignal: 'SIGKILL',
+            maxBuffer: LOGIN_SHELL_OUTPUT_CAP,
         });
     }
     catch {
-        return {};
+        return { values: {}, status: 'failed', exitCode: null, shell, names: wanted };
     }
-    if (res.error || res.status !== 0)
-        return {};
     const stdout = typeof res.stdout === 'string' ? res.stdout : res.stdout?.toString('utf8') ?? '';
-    const recovered = parseLoginShellEnv(stdout);
-    const out = {};
-    for (const key of wanted) {
-        const val = recovered[key];
-        if (val)
-            out[key] = val;
-    }
-    return out;
+    return settleLoginShellProbe(stdout, wanted, shell, typeof res.status === 'number' ? res.status : null, isSpawnSyncTimeout(res));
+}
+/** Read missing configured names without mutating the caller's or global env.
+ * Callers own any cache so project credentials cannot leak across scopes. */
+function readEnvFromLoginShellSync(names, opts = {}) {
+    return readEnvFromLoginShellSyncDetailed(names, opts).values;
 }
 /** Compatibility backfill for callers that intentionally augment process.env.
  * Failed probes remain retryable; successful names are already present. */

package/server/dist/project-env.js

@@ -1,37 +1,237 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROJECT_ENV_FAILURE_TTL_MS = exports.PROJECT_ENV_SUCCESS_TTL_MS = void 0;
+exports.refreshProjectEnv = refreshProjectEnv;
+exports.ensureProjectEnvFresh = ensureProjectEnvFresh;
+exports.startProjectEnvWarmup = startProjectEnvWarmup;
+exports.stopProjectEnvWarmup = stopProjectEnvWarmup;
 exports.resolveWorktreeEnvPassthrough = resolveWorktreeEnvPassthrough;
 exports.applyWorktreeEnvPassthrough = applyWorktreeEnvPassthrough;
+exports.getProjectEnvStatus = getProjectEnvStatus;
+exports.worktreeEnvPassthroughWarning = worktreeEnvPassthroughWarning;
 const db_1 = require("./db");
 const path_resolver_1 = require("./path-resolver");
-// Values stay in the owning project's memory, never process.env or SQLite.
-// Both successful and missing lookups expire so profiles can recover/rotate.
-const LOGIN_SHELL_CACHE_MS = 30_000;
-const shellValues = new WeakMap();
+/** Successful recoveries stay valid for 10 minutes; the background refresh
+ *  rotates them well inside that window. */
+exports.PROJECT_ENV_SUCCESS_TTL_MS = 10 * 60_000;
+/** Failed or empty lookups are retried after 30 seconds. */
+exports.PROJECT_ENV_FAILURE_TTL_MS = 30_000;
+/** The background refresh runs this long before a success expires. */
+const PROJECT_ENV_REFRESH_LEAD_MS = 60_000;
+const states = new WeakMap();
+function shellIdentity() {
+    return JSON.stringify([process.env.SHELL, process.env.HOME, process.env.ZDOTDIR]);
+}
+function stateFor(db) {
+    const identity = shellIdentity();
+    let state = states.get(db);
+    if (!state) {
+        state = { identity, records: new Map(), values: new Map(), inflight: null, queued: null, timer: null, active: false };
+        states.set(db, state);
+    }
+    else if (state.identity !== identity) {
+        state.identity = identity;
+        state.records.clear();
+        state.values.clear();
+    }
+    return state;
+}
+function configuredNames(db) {
+    try {
+        return (0, db_1.getProjectSettings)(db).worktreeEnvPassthrough;
+    }
+    catch {
+        // A closed/unloaded project connection has no configured names.
+        return [];
+    }
+}
+function missingNames(names) {
+    return names.filter(name => !process.env[name]);
+}
+/** Drop records for names no longer configured or now inherited. */
+function prune(state, names) {
+    for (const name of [...state.records.keys()]) {
+        if (!names.includes(name) || process.env[name]) {
+            state.records.delete(name);
+            state.values.delete(name);
+        }
+    }
+}
+function isValid(record, now) {
+    return Boolean(record && now < record.expiresAt);
+}
+function statusFromProbe(probe, value) {
+    if (value)
+        return 'recovered';
+    if (probe.status === 'timeout')
+        return 'probe-timeout';
+    if (probe.status === 'failed')
+        return 'probe-failed';
+    // `ok` without a value, or `skipped` (Windows / no login-shell recovery).
+    return 'not-defined';
+}
+function recordProbe(state, probe, names, now) {
+    for (const name of names) {
+        const value = probe.values[name];
+        const status = statusFromProbe(probe, value);
+        const previous = state.records.get(name);
+        // A transient probe failure never discards a still-valid recovered value.
+        if (status !== 'recovered' && previous?.status === 'recovered' && isValid(previous, now) && probe.status !== 'ok')
+            continue;
+        state.records.set(name, {
+            status,
+            shell: probe.shell,
+            checkedAt: now,
+            expiresAt: now + (status === 'recovered' ? exports.PROJECT_ENV_SUCCESS_TTL_MS : exports.PROJECT_ENV_FAILURE_TTL_MS),
+            exitCode: probe.exitCode,
+        });
+        if (value)
+            state.values.set(name, value);
+        else
+            state.values.delete(name);
+    }
+}
+function scheduleRefresh(db, state) {
+    if (state.timer) {
+        clearTimeout(state.timer);
+        state.timer = null;
+    }
+    if (!state.active || states.get(db) !== state)
+        return;
+    let earliest = Infinity;
+    for (const record of state.records.values()) {
+        if (record.status === 'recovered')
+            earliest = Math.min(earliest, record.expiresAt);
+    }
+    if (earliest === Infinity)
+        return;
+    const now = Date.now();
+    const at = Math.max(now + exports.PROJECT_ENV_FAILURE_TTL_MS, earliest - PROJECT_ENV_REFRESH_LEAD_MS);
+    state.timer = setTimeout(() => {
+        state.timer = null;
+        if (state.active && states.get(db) === state)
+            void refreshProjectEnv(db);
+    }, at - now);
+    state.timer.unref?.();
+}
+/** Probe the login shell asynchronously for every configured name missing from
+ *  the process environment and update this project's records. De-duplicated
+ *  while a probe is in flight: a call during a probe resolves after one more
+ *  probe that starts when the current one ends, so a settings change or an
+ *  explicit recheck is never answered with stale results. Never rejects. */
+function refreshProjectEnv(db) {
+    const state = stateFor(db);
+    if (state.inflight) {
+        // A request during a probe (settings change, recheck) gets a fresh probe
+        // after the current one; concurrent requests share that single follow-up.
+        if (!state.queued) {
+            state.queued = state.inflight.then(() => {
+                state.queued = null;
+                return refreshProjectEnv(db);
+            });
+        }
+        return state.queued;
+    }
+    const names = configuredNames(db);
+    prune(state, names);
+    const missing = missingNames(names);
+    if (missing.length === 0) {
+        scheduleRefresh(db, state);
+        return Promise.resolve();
+    }
+    const run = (0, path_resolver_1.readEnvFromLoginShell)(missing, { timeoutMs: (0, path_resolver_1.resolveLoginShellProbeTimeoutMs)() })
+        .then(probe => {
+        if (states.get(db) !== state)
+            return;
+        const current = configuredNames(db);
+        prune(state, current);
+        // Only names still configured and still missing are recorded.
+        const stillMissing = missingNames(current);
+        recordProbe(state, probe, missing.filter(name => stillMissing.includes(name)), Date.now());
+    })
+        .catch(() => { })
+        .finally(() => {
+        state.inflight = null;
+        scheduleRefresh(db, state);
+    });
+    state.inflight = run;
+    return run;
+}
+/** Probe only when a configured missing name has no valid record yet. */
+function ensureProjectEnvFresh(db) {
+    const state = stateFor(db);
+    if (state.inflight)
+        return state.inflight;
+    const names = configuredNames(db);
+    prune(state, names);
+    const now = Date.now();
+    const stale = missingNames(names).some(name => !isValid(state.records.get(name), now));
+    return stale ? refreshProjectEnv(db) : Promise.resolve();
+}
+/** Start background warm-up for a loaded project: probe now, then refresh
+ *  before successful results expire, until `stopProjectEnvWarmup`. */
+function startProjectEnvWarmup(db) {
+    const state = stateFor(db);
+    state.active = true;
+    void refreshProjectEnv(db);
+}
+/** Stop the background refresh and forget this project's recovered values. */
+function stopProjectEnvWarmup(db) {
+    const state = states.get(db);
+    if (!state)
+        return;
+    state.active = false;
+    if (state.timer) {
+        clearTimeout(state.timer);
+        state.timer = null;
+    }
+    states.delete(db);
+}
 function recoverProjectEnv(db, names) {
-    const missing = names.filter(name => !process.env[name]);
-    if (!missing.length) {
-        shellValues.delete(db);
+    const state = stateFor(db);
+    prune(state, names);
+    const missing = missingNames(names);
+    if (!missing.length)
         return {};
+    const now = Date.now();
+    // Cold fallback: a name with no record (or an expired success) gets the
+    // short synchronous probe. Expired failures are retried asynchronously.
+    const cold = missing.filter(name => {
+        const record = state.records.get(name);
+        return !record || (record.status === 'recovered' && !isValid(record, now));
+    });
+    let retry = missing.some(name => {
+        const record = state.records.get(name);
+        return record !== undefined && record.status !== 'recovered' && !isValid(record, now);
+    });
+    if (cold.length) {
+        const probe = (0, path_resolver_1.readEnvFromLoginShellSyncDetailed)(cold);
+        recordProbe(state, probe, cold, now);
+        // The async probe has a larger budget than the cold sync one.
+        if (probe.status === 'timeout' || probe.status === 'failed')
+            retry = true;
+    }
+    if (retry)
+        void refreshProjectEnv(db);
+    const out = {};
+    for (const name of missing) {
+        const value = state.values.get(name);
+        if (value && isValid(state.records.get(name), now))
+            out[name] = value;
     }
-    const identity = JSON.stringify([names, missing, process.env.SHELL, process.env.HOME, process.env.ZDOTDIR]);
-    const cached = shellValues.get(db);
-    if (cached?.identity === identity && Date.now() < cached.expiresAt)
-        return cached.env;
-    const env = (0, path_resolver_1.readEnvFromLoginShellSync)(missing);
-    shellValues.set(db, { identity, expiresAt: Date.now() + LOGIN_SHELL_CACHE_MS, env });
-    return env;
+    return out;
 }
 /** 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 bounded login-shell
- * recovery with a short, project-owned cache. Unresolved names remain absent.
+ * source is `process.env`, missing configured names come from the project's
+ * warm login-shell cache; the short synchronous probe runs only when cold.
+ * Unresolved names remain absent.
  */
 function resolveWorktreeEnvPassthrough(db, sourceEnv = process.env) {
     const out = {};
-    const names = (0, db_1.getProjectSettings)(db).worktreeEnvPassthrough;
+    const names = configuredNames(db);
     const recovered = sourceEnv === process.env ? recoverProjectEnv(db, names) : {};
     for (const name of names) {
         const value = sourceEnv[name] || recovered[name] || sourceEnv[name];
@@ -44,3 +244,51 @@ function applyWorktreeEnvPassthrough(db, env, sourceEnv = process.env) {
     const passthrough = resolveWorktreeEnvPassthrough(db, sourceEnv);
     return Object.keys(passthrough).length === 0 ? env : { ...env, ...passthrough };
 }
+/** Value-free status of every configured name for this project. */
+function getProjectEnvStatus(db) {
+    const state = stateFor(db);
+    const names = configuredNames(db);
+    prune(state, names);
+    const nowIso = new Date(Date.now()).toISOString();
+    return {
+        loginShellRecovery: process.platform !== 'win32',
+        timeoutMs: (0, path_resolver_1.resolveLoginShellProbeTimeoutMs)(),
+        checking: state.inflight !== null,
+        names: names.map((name) => {
+            if (process.env[name])
+                return { name, status: 'inherited', shell: null, checkedAt: nowIso, exitCode: null };
+            const record = state.records.get(name);
+            if (!record)
+                return { name, status: 'pending', shell: null, checkedAt: null, exitCode: null };
+            return {
+                name,
+                status: record.status,
+                shell: record.shell,
+                checkedAt: new Date(record.checkedAt).toISOString(),
+                exitCode: record.exitCode,
+            };
+        }),
+    };
+}
+/** One aggregated, value-free run-log line naming every configured name that
+ *  is absent from `env`, or null when all configured names resolved. */
+function worktreeEnvPassthroughWarning(db, env) {
+    const names = configuredNames(db);
+    const unresolved = names.filter(name => !env[name]);
+    if (!unresolved.length)
+        return null;
+    const state = states.get(db);
+    const now = Date.now();
+    const parts = unresolved.map(name => {
+        const record = state?.records.get(name);
+        // An expired success no longer counts as recovered; failures keep their cause.
+        const status = !record ? 'not-defined' : record.status === 'recovered' && now >= record.expiresAt ? 'not-defined' : record.status;
+        return { name, status };
+    });
+    const hint = process.platform === 'win32'
+        ? 'set it in the environment Specrails starts with'
+        : 'configure it in the login shell or launch from a terminal';
+    if (parts.length === 1)
+        return `[environment] ${parts[0].name} not available (${parts[0].status}); ${hint}`;
+    return `[environment] ${parts.map(p => `${p.name} (${p.status})`).join(', ')} not available; ${hint.replace(' it ', ' them ')}`;
+}

package/server/dist/project-registry.js

@@ -390,6 +390,11 @@ class ProjectRegistry {
                 (0, telemetry_receiver_1.dropBlobStatesForProject)(id);
             }
             catch { /* ignore */ }
+            // Stop the login-shell env refresh and forget recovered values.
+            try {
+                (0, project_env_1.stopProjectEnvWarmup)(ctx.db);
+            }
+            catch { /* ignore */ }
             // Close the DB connection BEFORE removing the project's data dir below.
             try {
                 ctx.db.close();
@@ -639,6 +644,10 @@ class ProjectRegistry {
                 ctx.fileSummaryManager.dispose();
             }
             catch { /* ignore */ }
+            try {
+                (0, project_env_1.stopProjectEnvWarmup)(ctx.db);
+            }
+            catch { /* ignore */ }
             ctx.ticketWatcher.close().catch(() => { });
         }
         // Close the shared browser context once, after every per-project manager has
@@ -1152,6 +1161,8 @@ class ProjectRegistry {
             sourcePath: () => (0, project_repositories_1.resolveProjectRepository)(project).path,
             workspacePaths: () => { const primary = (0, project_repositories_1.resolveProjectRepository)(project); return primary.workspacePaths ?? (primary.workspacePath ? [primary.workspacePath] : undefined); },
             env: () => (0, workspace_resolution_1.resolveLoopBaseEnv)({ slug: project.slug, path: project.path }, undefined, (0, project_env_1.applyWorktreeEnvPassthrough)(db, process.env)),
+            // One value-free run-log line when configured names are unresolved.
+            environmentNotice: () => (0, project_env_1.worktreeEnvPassthroughWarning)(db, (0, project_env_1.applyWorktreeEnvPassthrough)(db, process.env)),
             // Named rail profiles and global per-agent defaults ride the same
             // SPECRAILS_PROFILE_PATH snapshot in both AI transports. An explicit null
             // rail selection opts out; omitted selections keep Core's default rules.
@@ -1486,6 +1497,9 @@ class ProjectRegistry {
         const ctx = { project, db, queueManager, chatManager, setupManager, proposalManager, agentRefineManager, fileSummaryManager, specLauncherManager, ticketWatcher, browserCaptureManager, jiraSyncManager, stuckRunDetector, broadcast: boundBroadcast, railJobs, loopRunManager, railLoopRuns, onLoopRunFinished, getTicketSpec, desktopDb: this._desktopDb, milestoneProgress };
         ctx.milestoneChains = milestoneChains;
         this._contexts.set(project.id, ctx);
+        // Warm the project's login-shell env cache off the event loop so the first
+        // rail/loop spawn reads recovered credentials instead of a cold 1.5 s probe.
+        (0, project_env_1.startProjectEnvWarmup)(db);
         const recoverAfterProbe = (definitionStates) => {
             if (this._contexts.get(project.id) !== ctx)
                 return;

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

@@ -9,6 +9,7 @@ exports.registerSettingsRoutes = registerSettingsRoutes;
 const project_settings_1 = require("./modules/project-settings");
 const sqlite_1 = require("./modules/project-settings/adapters/sqlite");
 const http_1 = require("./modules/project-settings/adapters/http");
+const project_env_1 = require("./project-env");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const db_1 = require("./db");
@@ -35,6 +36,22 @@ function registerSettingsRoutes(deps) {
         const runtimeChanged = JSON.stringify(settings.subagentRuntime) !== JSON.stringify(previous.subagentRuntime);
         if (settings.allowSubagents !== previous.allowSubagents || runtimeChanged)
             registry.notifySettingsChanged({ projectId: String(req.params.projectId) });
+        // Configured env names changed: re-warm this project's login-shell cache.
+        if (JSON.stringify(settings.worktreeEnvPassthrough) !== JSON.stringify(previous.worktreeEnvPassthrough))
+            void (0, project_env_1.refreshProjectEnv)(ctx(req).db);
+    });
+    // Value-free resolution status of the configured env names (+ recheck).
+    (0, http_1.registerEnvPassthroughStatusHttp)(router, {
+        read: async (req) => {
+            const { db } = ctx(req);
+            await (0, project_env_1.ensureProjectEnvFresh)(db);
+            return (0, project_env_1.getProjectEnvStatus)(db);
+        },
+        recheck: async (req) => {
+            const { db } = ctx(req);
+            await (0, project_env_1.refreshProjectEnv)(db);
+            return (0, project_env_1.getProjectEnvStatus)(db);
+        },
     });
     // ─── Per-project Quick mode Contract Refine last-used value ─────────────────
     router.get('/:projectId/add-spec-quick-contract-refine-last', (req, res) => {

package/server/dist/schemas/agent-runtime.schema.json

@@ -12,7 +12,7 @@
       "planning": { "enum": ["full", "proportional"] }, "acceptDeveloperChecks": { "type": "boolean" },
       "verification": { "type": "object", "additionalProperties": false, "properties": { "maxConcurrency": { "type": "integer", "minimum": 1, "maximum": 4 } } }
     } },
-    "guardrails": { "type": "object", "additionalProperties": false, "properties": { "plan-validation": { "type": "boolean" }, "genuine-blocking-question": { "type": "boolean" }, "plan-language-hint": { "type": "boolean" }, "frozen-plan-writes": { "type": "boolean" }, "primary-language": { "type": "boolean" }, "duplicate-sibling": { "type": "boolean" }, "one-test-per-module": { "type": "boolean" }, "empty-write": { "type": "boolean" }, "evidence-gated-ticking": { "type": "boolean" }, "inventory-retry": { "type": "boolean" }, "synthetic-corrections": { "type": "boolean" }, "silent-group-closure": { "type": "boolean" }, "verify-per-group": { "type": "boolean" }, "test-reachability": { "type": "boolean" }, "exit-code-honesty": { "type": "boolean" }, "environment-repair": { "type": "boolean" }, "lockfile-repair": { "type": "boolean" }, "verify-idle-timeout": { "type": "boolean" } } },
+    "guardrails": { "type": "object", "additionalProperties": false, "properties": { "plan-validation": { "type": "boolean" }, "genuine-blocking-question": { "type": "boolean" }, "plan-language-hint": { "type": "boolean" }, "frozen-plan-writes": { "type": "boolean" }, "primary-language": { "type": "boolean" }, "duplicate-sibling": { "type": "boolean" }, "one-test-per-module": { "type": "boolean" }, "empty-write": { "type": "boolean" }, "evidence-gated-ticking": { "type": "boolean" }, "inventory-retry": { "type": "boolean" }, "synthetic-corrections": { "type": "boolean" }, "silent-group-closure": { "type": "boolean" }, "verify-per-group": { "type": "boolean" }, "test-reachability": { "type": "boolean" }, "exit-code-honesty": { "type": "boolean" }, "environment-repair": { "type": "boolean" }, "lockfile-repair": { "type": "boolean" }, "verify-idle-timeout": { "type": "boolean" }, "verification-output-adoption": { "type": "boolean" } } },
     "rolePrompts": { "type": "object", "propertyNames": { "pattern": "^[a-z][a-z0-9-]{0,63}$" }, "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 20000, "pattern": "\\S" }, "properties": {
       "architect": { "type": "string", "minLength": 1, "maxLength": 20000, "pattern": "\\S" },
       "developer": { "type": "string", "minLength": 1, "maxLength": 20000, "pattern": "\\S" },