specrails-desktop 2.35.0 → 2.42.1

package/server/dist/framework-manager.js

@@ -3,13 +3,15 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.atomicWrite = exports.FrameworkManager = void 0;
-exports.frameworkRoot = frameworkRoot;
-exports.readCurrentFrameworkVersion = readCurrentFrameworkVersion;
+exports.atomicWrite = exports.FrameworkManager = exports.readCurrentFrameworkVersion = exports.frameworkRoot = void 0;
 const child_process_1 = require("child_process");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
-const bundled_core_1 = require("./bundled-core");
+const crypto_1 = require("crypto");
+const core_runtime_1 = require("./core-runtime");
+var core_runtime_2 = require("./core-runtime");
+Object.defineProperty(exports, "frameworkRoot", { enumerable: true, get: function () { return core_runtime_2.frameworkRoot; } });
+Object.defineProperty(exports, "readCurrentFrameworkVersion", { enumerable: true, get: function () { return core_runtime_2.readCurrentFrameworkVersion; } });
 const artifact_registry_1 = require("./artifact-registry");
 Object.defineProperty(exports, "atomicWrite", { enumerable: true, get: function () { return artifact_registry_1.atomicWrite; } });
 const semver_lite_1 = require("./semver-lite");
@@ -42,85 +44,6 @@ function realpathOrSelf(p) {
         return p;
     }
 }
-/** `~/.specrails/framework` — same home as the registry. */
-function frameworkRoot(home) {
-    return path_1.default.join((0, artifact_registry_1.resolveHome)(home), '.specrails', 'framework');
-}
-/** Path to the `current` symlink under the framework root. */
-function currentLink(home) {
-    return path_1.default.join(frameworkRoot(home), 'current');
-}
-/**
- * Read the framework version from the documented per-version stamp marker that
- * core's `install-framework` writes at `<versionDir>/.framework-stamp<providerDir>.json`
- * (`{ version, provider, at }`). When `current` is a real dir (Windows copy
- * fallback) or a junction, the version is NOT recoverable from the path basename
- * (`current`), so the marker inside the dir is the source of truth.
- *
- * Returns the first non-empty `version` field found among any stamp markers
- * directly under `dir`, or null when none is present/readable.
- */
-function readFrameworkVersionMarker(dir) {
-    let entries;
-    try {
-        entries = fs_1.default.readdirSync(dir);
-    }
-    catch {
-        return null;
-    }
-    for (const name of entries) {
-        // `.framework-stamp.claude.json` / `.framework-stamp.codex.json` / `.gemini`.
-        if (!name.startsWith('.framework-stamp') || !name.endsWith('.json'))
-            continue;
-        try {
-            const parsed = JSON.parse(fs_1.default.readFileSync(path_1.default.join(dir, name), 'utf8'));
-            if (typeof parsed.version === 'string') {
-                const v = parsed.version.trim();
-                if (v.length > 0)
-                    return v;
-            }
-        }
-        catch {
-            /* unreadable / malformed marker — try the next one */
-        }
-    }
-    return null;
-}
-/**
- * The version `framework/current` resolves to, or null when `current` is absent
- * / unresolvable. POSIX: reads the basename of the symlink target (the `<version>`
- * dir name). Windows junction/copy fallback: `current` is a real dir (or a
- * junction whose `lstat` is not a POSIX symlink), so the basename is `current`
- * and the version is read from the documented `.framework-stamp*.json` marker
- * inside it instead.
- */
-function readCurrentFrameworkVersion(home) {
-    const link = currentLink(home);
-    try {
-        const st = fs_1.default.lstatSync(link);
-        if (st.isSymbolicLink()) {
-            const target = fs_1.default.readlinkSync(link);
-            const resolved = path_1.default.isAbsolute(target) ? target : path_1.default.resolve(frameworkRoot(home), target);
-            const base = path_1.default.basename(resolved);
-            // A POSIX symlink targets the `<version>` dir by name. A Windows junction
-            // read as a symlink also yields the absolute `<version>` target, so the
-            // basename is the version. Only when the basename is still `current`
-            // (unresolvable) do we fall back to the stamp marker inside the dir.
-            if (base !== 'current')
-                return base;
-            return readFrameworkVersionMarker(resolved);
-        }
-        if (st.isDirectory()) {
-            // Windows copy fallback / non-symlink junction: `current` is a real dir
-            // holding the materialized framework. Read the version from its marker.
-            return readFrameworkVersionMarker(link);
-        }
-        return null;
-    }
-    catch {
-        return null;
-    }
-}
 class FrameworkManager {
     home;
     broadcast;
@@ -139,30 +62,21 @@ class FrameworkManager {
             const cli = path_1.default.join(this.coreRoot, 'dist', 'installer', 'cli.js');
             return fs_1.default.existsSync(cli) ? realpathOrSelf(cli) : null;
         }
-        const bundled = (0, bundled_core_1.getBundledCoreCli)();
-        return bundled ? realpathOrSelf(bundled) : null;
+        return (0, core_runtime_1.resolveCoreRuntime)(this.home)?.cli ?? null;
     }
     /** True when a usable core (override or bundled) is present (else methods no-op). */
     isAvailable() {
         return this.resolveCli() !== null;
     }
     /**
-     * The version the app should materialize: the override core's version (update
-     * channel) when a `coreRoot` is set, else the bundled core version. Null when
+     * Historical API name: this is the SELECTED runtime's version (including a
+     * managed update or newer external CLI), not necessarily the shipped bundle. Null when
      * neither is present / unreadable.
      */
     bundledVersion() {
-        if (this.coreRoot) {
-            try {
-                const pkg = JSON.parse(fs_1.default.readFileSync(path_1.default.join(this.coreRoot, 'package.json'), 'utf8'));
-                const v = pkg.version?.trim();
-                return v && v.length > 0 ? v : null;
-            }
-            catch {
-                return null;
-            }
-        }
-        return (0, bundled_core_1.getBundledCoreVersion)();
+        return this.coreRoot
+            ? (0, core_runtime_1.readCoreRuntime)(this.coreRoot, 'managed')?.version ?? null
+            : (0, core_runtime_1.resolveCoreRuntime)(this.home)?.version ?? null;
     }
     /**
      * Materialize the framework for `version` (default: the bundled core version)
@@ -183,7 +97,7 @@ class FrameworkManager {
         if (!ver) {
             return { ran: false, version: null, providers: [], errors: [] };
         }
-        const fwDir = frameworkRoot(this.home);
+        const fwDir = (0, core_runtime_1.frameworkRoot)(this.home);
         fs_1.default.mkdirSync(fwDir, { recursive: true });
         const errors = [];
         const done = [];
@@ -233,16 +147,79 @@ class FrameworkManager {
         const cli = this.resolveCli();
         if (!cli)
             return { ok: false, detail: 'no usable core CLI to run swap-current with' };
-        if (readCurrentFrameworkVersion(this.home) === version)
+        if ((0, core_runtime_1.readCurrentFrameworkVersion)(this.home) === version)
             return { ok: true, detail: null };
-        const fwDir = frameworkRoot(this.home);
+        const fwDir = (0, core_runtime_1.frameworkRoot)(this.home);
+        const current = path_1.default.join(fwDir, 'current');
+        const previousVersion = (0, core_runtime_1.readCurrentFrameworkVersion)(this.home);
+        let backup = null;
+        if (previousVersion) {
+            backup = path_1.default.join(fwDir, `.current-recovery-${(0, crypto_1.randomUUID)()}`);
+            try {
+                if (fs_1.default.lstatSync(current).isSymbolicLink()) {
+                    fs_1.default.symlinkSync(fs_1.default.realpathSync(current), backup, process.platform === 'win32' ? 'junction' : 'dir');
+                }
+                else {
+                    fs_1.default.cpSync(current, backup, {
+                        recursive: true, dereference: false, verbatimSymlinks: true,
+                        // Node 22's native recursive-copy fast path mishandles Unicode on
+                        // Windows (nodejs/node#61878). Use JS traversal into the fresh backup
+                        // so neither native directory copy nor file replacement is used.
+                        filter: () => true, mode: fs_1.default.constants.COPYFILE_FICLONE,
+                    });
+                }
+            }
+            catch (error) {
+                return { ok: false, detail: `Could not preserve the active framework before updating: ${error instanceof Error ? error.message : String(error)}` };
+            }
+        }
+        const failed = (detail) => {
+            if (!backup)
+                return { ok: false, detail };
+            const actualVersion = (0, core_runtime_1.readCurrentFrameworkVersion)(this.home);
+            if (actualVersion === previousVersion) {
+                try {
+                    fs_1.default.rmSync(backup, { recursive: true, force: true });
+                }
+                catch { /* safe recovery copy */ }
+                return { ok: false, detail };
+            }
+            // Never overwrite another operation's published version. Preserve the
+            // recovery copy for diagnosis instead of guessing which install owns it.
+            if (actualVersion !== null && actualVersion !== version)
+                return { ok: false, detail: `${detail}; recovery retained at ${backup} (current changed concurrently)` };
+            const failedCurrent = path_1.default.join(fwDir, `.failed-current-${(0, crypto_1.randomUUID)()}`);
+            try {
+                try {
+                    fs_1.default.lstatSync(current);
+                    fs_1.default.renameSync(current, failedCurrent);
+                }
+                catch (error) {
+                    if (error.code !== 'ENOENT')
+                        throw error;
+                }
+                fs_1.default.renameSync(backup, current);
+                if ((0, core_runtime_1.readCurrentFrameworkVersion)(this.home) !== previousVersion)
+                    throw new Error('restored framework identity did not match');
+                return { ok: false, detail: `${detail}; previous framework ${previousVersion} restored` };
+            }
+            catch (error) {
+                return { ok: false, detail: `${detail}; recovery retained at ${backup}: ${error instanceof Error ? error.message : String(error)}` };
+            }
+        };
         const res = (0, child_process_1.spawnSync)(nodeInterpreter(), [cli, 'swap-current', '--framework-dir', fwDir, '--version', version], { env: this.childEnv(), encoding: 'utf-8', timeout: 120_000 });
         if (res.error || (res.status ?? 1) !== 0) {
             const detail = (res.error?.message ?? `${res.stderr || res.stdout || ''}`.trim()) || `exit ${res.status ?? 'unknown'}`;
-            return { ok: false, detail };
+            return failed(detail);
         }
-        if (readCurrentFrameworkVersion(this.home) !== version) {
-            return { ok: false, detail: `swap-current exited 0 but current still resolves to ${readCurrentFrameworkVersion(this.home) ?? 'nothing'}` };
+        if ((0, core_runtime_1.readCurrentFrameworkVersion)(this.home) !== version) {
+            return failed(`swap-current exited 0 but current still resolves to ${(0, core_runtime_1.readCurrentFrameworkVersion)(this.home) ?? 'nothing'}`);
+        }
+        if (backup) {
+            try {
+                fs_1.default.rmSync(backup, { recursive: true, force: true });
+            }
+            catch { /* recovery copy is safe to retain */ }
         }
         return { ok: true, detail: null };
     }
@@ -253,12 +230,23 @@ class FrameworkManager {
      * no bundled core is present. Returns the resulting current version (or null).
      */
     versionCheck(providers = ['claude']) {
-        const bundled = this.bundledVersion();
+        // Keep an already activated framework even if its old updater discarded the
+        // corresponding package. Runtime consumers report the repair requirement.
+        let bundled;
+        try {
+            bundled = this.bundledVersion();
+        }
+        catch {
+            return { swapped: false, version: (0, core_runtime_1.readCurrentFrameworkVersion)(this.home) };
+        }
         if (!this.resolveCli() || !bundled) {
-            return { swapped: false, version: readCurrentFrameworkVersion(this.home) };
+            return { swapped: false, version: (0, core_runtime_1.readCurrentFrameworkVersion)(this.home) };
         }
-        const current = readCurrentFrameworkVersion(this.home);
+        const current = (0, core_runtime_1.readCurrentFrameworkVersion)(this.home);
         if (current === bundled) {
+            const mat = this.materialize(bundled, providers);
+            if (mat.errors.length)
+                this.broadcast?.({ type: 'framework.update_failed', version: bundled, errors: mat.errors });
             return { swapped: false, version: current };
         }
         // Anti-downgrade guard: NEVER swap `current` down to the bundled version when
@@ -318,7 +306,7 @@ class FrameworkManager {
         catch {
             /* broadcast is best-effort */
         }
-        return { swapped: false, version: readCurrentFrameworkVersion(this.home) };
+        return { swapped: false, version: (0, core_runtime_1.readCurrentFrameworkVersion)(this.home) };
     }
     /**
      * Assemble a project workspace by SYMLINKING the materialized framework into
@@ -332,7 +320,7 @@ class FrameworkManager {
         const ver = input.version ?? this.bundledVersion();
         if (!ver)
             return { ran: false };
-        const fwDir = frameworkRoot(this.home);
+        const fwDir = (0, core_runtime_1.frameworkRoot)(this.home);
         const res = (0, child_process_1.spawnSync)(nodeInterpreter(), [
             cli,
             'assemble',
@@ -362,7 +350,7 @@ class FrameworkManager {
         // Point the core CLI's scriptDir at the package whose framework we are
         // materializing so its template/command sources resolve from there: the
         // OVERRIDE core (update channel) when set, else the bundled package.
-        const coreRoot = this.coreRoot ?? process.env.SPECRAILS_BUNDLED_CORE_PATH;
+        const coreRoot = this.coreRoot ?? (0, core_runtime_1.resolveCoreRuntime)(this.home)?.root;
         if (coreRoot)
             env.SPECRAILS_CORE_SCRIPT_DIR = coreRoot;
         return env;

package/server/dist/framework-reseed.js

@@ -46,6 +46,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertWorkspaceCoreReady = void 0;
 exports.isFrameworkAutoswapEnabled = isFrameworkAutoswapEnabled;
 exports.readWorkspaceFrameworkVersion = readWorkspaceFrameworkVersion;
 exports.reseedStaleWorkspaces = reseedStaleWorkspaces;
@@ -55,6 +56,10 @@ const providers_1 = require("./providers");
 const workspace_manager_1 = require("./workspace-manager");
 const workspace_resolution_1 = require("./workspace-resolution");
 const offline_assemble_1 = require("./offline-assemble");
+const core_runtime_1 = require("./core-runtime");
+const core_update_state_1 = require("./core-update-state");
+var core_update_state_2 = require("./core-update-state");
+Object.defineProperty(exports, "assertWorkspaceCoreReady", { enumerable: true, get: function () { return core_update_state_2.assertWorkspaceCoreReady; } });
 function isFrameworkAutoswapEnabled() {
     const v = (process.env.SPECRAILS_FRAMEWORK_AUTOSWAP ?? '').toLowerCase();
     return v !== 'false' && v !== '0' && v !== 'off';
@@ -84,15 +89,37 @@ async function reseedStaleWorkspaces(projects, currentVersion, io) {
     const results = [];
     if (!currentVersion)
         return results;
+    // Mark every affected workspace before yielding for the first install. A
+    // later project must not launch against mixed templates while earlier ones
+    // are still being refreshed.
+    const pendingErrors = new Map();
+    for (const project of projects) {
+        const workspace = (0, workspace_manager_1.workspacePathFor)(project.slug);
+        if (!(0, workspace_resolution_1.isWorkspacePopulated)(workspace))
+            continue;
+        if (readWorkspaceFrameworkVersion(project.slug) === currentVersion && !fs.existsSync((0, core_update_state_1.coreUpdatePendingPath)(workspace)))
+            continue;
+        try {
+            fs.mkdirSync(path.dirname((0, core_update_state_1.coreUpdatePendingPath)(workspace)), { recursive: true });
+            fs.writeFileSync((0, core_update_state_1.coreUpdatePendingPath)(workspace), JSON.stringify({ version: currentVersion, projectId: project.id }), { mode: 0o600 });
+        }
+        catch (error) {
+            pendingErrors.set(project.id, `Could not mark the workspace for Core refresh: ${String(error)}`);
+        }
+    }
     const assemble = io?.assemble
         ?? (async (p, providers) => {
-            await (0, offline_assemble_1.assembleProjectOffline)({
+            const results = await (0, offline_assemble_1.assembleProjectOffline)({
                 projectPath: p.path,
                 slug: p.slug,
                 desktopProjectId: p.id,
                 providers,
                 continueOnError: true,
+                preserveExistingConfig: true,
             });
+            const failed = results.filter(result => !result.ok);
+            if (failed.length)
+                throw new Error(failed.map(result => `${result.provider}: ${result.error}`).join('; '));
         });
     for (const project of projects) {
         const workspace = (0, workspace_manager_1.workspacePathFor)(project.slug);
@@ -101,7 +128,7 @@ async function reseedStaleWorkspaces(projects, currentVersion, io) {
             continue;
         }
         const recorded = readWorkspaceFrameworkVersion(project.slug);
-        if (recorded === currentVersion) {
+        if (recorded === currentVersion && !fs.existsSync((0, core_update_state_1.coreUpdatePendingPath)(workspace))) {
             results.push({ projectId: project.id, reseeded: false, skippedReason: 'up-to-date' });
             continue;
         }
@@ -118,18 +145,27 @@ async function reseedStaleWorkspaces(projects, currentVersion, io) {
         }
         catch { /* absent */ }
         try {
+            if (pendingErrors.has(project.id))
+                throw new Error(pendingErrors.get(project.id));
             await assemble(project, providers);
-            if (mcpBefore !== null) {
-                let mcpAfter = null;
-                try {
-                    mcpAfter = fs.readFileSync(mcpPath, 'utf-8');
+            if (readWorkspaceFrameworkVersion(project.slug) !== currentVersion)
+                throw new Error('Core assembly did not publish the expected workspace version.');
+            // Published Core 5 installations before the execution contract remain
+            // valid. Require the helper only when the selected package declares it.
+            if (!io?.assemble) {
+                const runtime = (0, core_runtime_1.resolveCoreRuntime)();
+                if (runtime) {
+                    const contractPath = path.join(runtime.root, 'integration-contract.json');
+                    let required;
+                    try {
+                        required = JSON.parse(fs.readFileSync(contractPath, 'utf8')).execution?.runtime;
+                    }
+                    catch { /* legacy contract */ }
+                    if (typeof required === 'string' && required && !fs.existsSync(path.join(workspace, required)))
+                        throw new Error('Core assembly did not install its declared execution runtime.');
                 }
-                catch { /* deleted by assemble */ }
-                if (mcpAfter !== mcpBefore)
-                    fs.writeFileSync(mcpPath, mcpBefore, 'utf-8');
             }
             results.push({ projectId: project.id, reseeded: true });
-            console.log(`[framework-reseed] ${project.slug}: ${recorded ?? '(none)'} → ${currentVersion}`);
         }
         catch (err) {
             results.push({
@@ -139,6 +175,36 @@ async function reseedStaleWorkspaces(projects, currentVersion, io) {
             });
             console.warn(`[framework-reseed] ${project.slug} failed (non-fatal):`, err);
         }
+        finally {
+            if (mcpBefore !== null) {
+                let mcpAfter = null;
+                try {
+                    mcpAfter = fs.readFileSync(mcpPath, 'utf-8');
+                }
+                catch { /* deleted by assemble */ }
+                if (mcpAfter !== mcpBefore) {
+                    try {
+                        fs.writeFileSync(mcpPath, mcpBefore, 'utf-8');
+                    }
+                    catch (error) {
+                        const result = results[results.length - 1];
+                        result.reseeded = false;
+                        result.error = `Could not restore the project's MCP configuration: ${String(error)}`;
+                    }
+                }
+            }
+            const result = results[results.length - 1];
+            if (result.reseeded) {
+                try {
+                    fs.rmSync((0, core_update_state_1.coreUpdatePendingPath)(workspace), { force: true });
+                    console.log(`[framework-reseed] ${project.slug}: ${recorded ?? '(none)'} → ${currentVersion}`);
+                }
+                catch (error) {
+                    result.reseeded = false;
+                    result.error = `Could not finalize the Core refresh: ${String(error)}`;
+                }
+            }
+        }
     }
     return results;
 }

package/server/dist/headroom-manager.js

@@ -3,7 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HeadroomManager = exports.HEADROOM_ACTIVATION_SOURCE = exports.HEADROOM_ACTIVATION_SCHEMA_VERSION = exports.HEADROOM_MANAGED_PYTHON_VERSION = exports.HEADROOM_RELAY_PATH = void 0;
+exports.HeadroomManager = exports.HEADROOM_ACTIVATION_SOURCE = exports.HEADROOM_ACTIVATION_SCHEMA_VERSION = exports.HEADROOM_MANAGED_PYTHON_VERSION = exports.HEADROOM_RELAY_PATH = exports.PROXY_START_TIMEOUT_MS = void 0;
+exports.getProxyStartTimeoutMs = getProxyStartTimeoutMs;
 exports.getHeadroomManagedInstallPlan = getHeadroomManagedInstallPlan;
 exports.parseWindowsOwnershipSnapshot = parseWindowsOwnershipSnapshot;
 exports.windowsSnapshotHasOwnedListener = windowsSnapshotHasOwnedListener;
@@ -22,7 +23,27 @@ const win_spawn_1 = require("./util/win-spawn");
 const STATE_KEY = 'plugins.headroom.state';
 const DEFAULT_PORT = 8787;
 const PROXY_HEALTH_REQUEST_TIMEOUT_MS = 750;
+/**
+ * How long a freshly spawned proxy gets to answer `/livez` before activation
+ * is declared failed. The proxy is a Python tool run through uv: a COLD start
+ * (first run after install, or a wiped bytecode cache) compiles ~3 000
+ * modules and only prints its banner ~4 s in, answering `/livez` after ~7.5 s
+ * on an M-series Mac — the previous 6 s budget killed it every time and left
+ * `proxyTail` empty, so the diagnostics said nothing. Warm starts take ~3.7 s.
+ * A child that EXITS is failed immediately regardless of this budget.
+ */
+exports.PROXY_START_TIMEOUT_MS = 30_000;
+const PROXY_START_TIMEOUT_ENV = 'SPECRAILS_HEADROOM_START_TIMEOUT_MS';
 const RELAY_CONNECT_TIMEOUT_MS = 3_000;
+/** Effective proxy startup budget: the env override when it is a positive
+ *  integer number of milliseconds, else the default. */
+function getProxyStartTimeoutMs(env = process.env) {
+    const raw = env[PROXY_START_TIMEOUT_ENV];
+    if (raw === undefined || raw.trim() === '')
+        return exports.PROXY_START_TIMEOUT_MS;
+    const parsed = Number(raw);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : exports.PROXY_START_TIMEOUT_MS;
+}
 exports.HEADROOM_RELAY_PATH = '/_specrails/headroom';
 exports.HEADROOM_MANAGED_PYTHON_VERSION = '3.12';
 exports.HEADROOM_ACTIVATION_SCHEMA_VERSION = 1;
@@ -1437,6 +1458,9 @@ class HeadroomManager {
                     HEADROOM_LEARN: state.learning.enabled ? '1' : '0',
                     HEADROOM_SAVINGS_PROFILE: process.env.HEADROOM_SAVINGS_PROFILE ?? 'agent-90',
                     HEADROOM_MODE: process.env.HEADROOM_MODE ?? 'token',
+                    // stdout is a pipe here, so Python block-buffers it: without this the
+                    // banner (and any traceback) never reaches `proxyTail` before a kill.
+                    PYTHONUNBUFFERED: '1',
                 },
                 stdio: ['ignore', 'pipe', 'pipe'],
             });
@@ -1472,13 +1496,24 @@ class HeadroomManager {
         // fallback for unusual ChildProcess implementations and stdio teardown.
         child.on('exit', invalidateOwnedProxy);
         child.on('close', invalidateOwnedProxy);
-        const healthy = await this.waitForProxyHealthy(state.port, 6000, () => this.isProxyGenerationCurrent(generation));
+        const startTimeoutMs = getProxyStartTimeoutMs();
+        const childAlive = () => child.exitCode == null && child.signalCode == null;
+        const healthy = await this.waitForProxyHealthy(state.port, startTimeoutMs, 
+        // A dead child can never become healthy — stop waiting the moment it
+        // exits so a crash surfaces at once instead of after the whole budget.
+        () => this.isProxyGenerationCurrent(generation) && childAlive());
         if (!this.isProxyGenerationCurrent(generation)) {
             await this.discardProxyChild(child);
             return this.cancelledProxyStart();
         }
         if (!healthy) {
-            const failure = classifyProxyFailure(this.proxyTail, command);
+            // Prefer the process's own words; otherwise say precisely which of the two
+            // things happened so "did not become healthy" is never an empty box.
+            const tail = this.proxyTail.trim();
+            const detail = tail || (childAlive()
+                ? `The Headroom proxy did not answer /livez within ${Math.round(startTimeoutMs / 1000)} s.`
+                : `The Headroom proxy exited during startup (${child.signalCode ?? `exit code ${child.exitCode}`}).`);
+            const failure = classifyProxyFailure(detail, command);
             await this.discardProxyChild(child);
             this.updatePersisted({ lastIssue: failure });
             this.emit('failed', failure.title);

package/server/dist/host-control.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.consumeHostControlToken = consumeHostControlToken;
+exports.createHostControlRouter = createHostControlRouter;
+const express_1 = require("express");
+const auth_1 = require("./auth");
+const TOKEN_ENV = 'SPECRAILS_HOST_CONTROL_TOKEN';
+/** Consume the host-only capability before provider/terminal environments are copied. */
+function consumeHostControlToken(env = process.env) {
+    let token;
+    for (const key of Object.keys(env)) {
+        if (key.toUpperCase() !== TOKEN_ENV)
+            continue;
+        token ??= env[key];
+        delete env[key];
+    }
+    return token && /^[a-zA-Z0-9_-]{32,256}$/.test(token) ? token : undefined;
+}
+/** Private host control; deliberately independent of the renderer's desktop token. */
+function createHostControlRouter(options) {
+    const router = (0, express_1.Router)();
+    let requested = false;
+    router.post('/shutdown', (req, res) => {
+        if (!options.token) {
+            res.status(404).json({ error: 'Not found' });
+            return;
+        }
+        const supplied = req.headers['x-specrails-host-token'];
+        if (!(0, auth_1.isLoopbackAddress)(req.socket.remoteAddress) || req.headers.origin !== undefined
+            || typeof supplied !== 'string' || !(0, auth_1.safeEqual)(supplied, options.token)) {
+            res.status(403).json({ error: 'Forbidden' });
+            return;
+        }
+        if (!requested) {
+            // The host must receive the owned PID before shutdown closes all sockets.
+            res.once('finish', () => {
+                if (requested)
+                    return;
+                requested = true;
+                setImmediate(() => {
+                    void Promise.resolve().then(options.onShutdown).catch(() => {
+                        // No credentials or environment values in this diagnostic. The host
+                        // retains its bounded, identity-checked force-stop fallback.
+                        console.error('[host-control] graceful shutdown failed');
+                    });
+                });
+            });
+        }
+        res.status(202).json({ ok: true, pid: options.pid ?? process.pid });
+    });
+    return router;
+}

package/server/dist/index.js

@@ -44,12 +44,16 @@ 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");
+const api_not_found_1 = require("./api-not-found");
 const process_admission_1 = require("./process-admission");
+const host_control_1 = require("./host-control");
+const transient_children_1 = require("./transient-children");
 // 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
 // openspec/changes/add-multi-provider-support/specs/multi-provider-architecture/spec.md.
 require("./providers");
+const hostControlToken = (0, host_control_1.consumeHostControlToken)();
 const inheritedPathBeforeResolve = (process.env.PATH ?? '').split(process.platform === 'win32' ? ';' : ':').filter(Boolean).length;
 // Backfill SystemRoot/ComSpec/etc into process.env BEFORE anything spawns, so a
 // stripped GUI-launch sidecar env never breaks cmd.exe-mediated spawns (PTY,
@@ -155,6 +159,7 @@ function corsMiddleware(req, res, next) {
     next();
 }
 app.use(corsMiddleware);
+app.use('/api/host', (0, host_control_1.createHostControlRouter)({ token: hostControlToken, onShutdown: shutdown }));
 // Provider traffic uses the desktop listener as a stable relay. Mount before
 // every body parser so large/streaming request bodies and Codex event streams
 // pass through byte-for-byte; the relay verifies the connected Headroom backend
@@ -504,9 +509,17 @@ function applyPtyWsRateLimiting(ws) {
 // ─── Super-mode bootstrap ─────────────────────────────────────────────────────
 {
     const registry = new project_registry_1.ProjectRegistry(broadcast, undefined, port);
+    try {
+        (0, transient_children_1.initializeBackgroundProcessPersistence)(path_1.default.join(path_1.default.dirname(registry.desktopDb.name), 'background-processes.sqlite'));
+    }
+    catch (error) {
+        // A log-store failure must not take mission chat or the project catalog
+        // offline. New background launches report the persistence error directly.
+        console.error('[background-process] persistent history unavailable:', error);
+    }
     registry.loadAll();
     _registry = registry;
-    _getProjectCount = () => registry.listContexts().length;
+    _getProjectCount = () => registry.listProjects().length;
     // ─── Bundled framework update channel (Phase 6) ─────────────────────────────
     // After the registry + projects have loaded, run a single framework
     // version-check. On FIRST run it materializes the bundled framework to
@@ -606,6 +619,15 @@ function applyPtyWsRateLimiting(ws) {
         broadcast,
     }));
     if (mcpManager.isEnabledSetting()) {
+        // MCP is on by default, so mint + persist the scoped token at boot: the
+        // stdio bridge reads ~/.specrails/mcp.token locally, and on a fresh install
+        // nothing else would have written it until Settings ▸ MCP was opened.
+        try {
+            (0, mcp_1.getMcpToken)();
+        }
+        catch (err) {
+            console.warn('[mcp] could not prepare the scoped token at boot:', err);
+        }
         mcpManager.start().catch((err) => console.error('[mcp] boot start failed:', err));
     }
     // ─── App-global agent chat (drives the app via its own MCP) ────────────────
@@ -660,7 +682,7 @@ function applyPtyWsRateLimiting(ws) {
                 state.subscribedProjectId = frame.projectId;
         });
         // Send app state init
-        const projects = registry.listContexts().map((ctx) => ctx.project);
+        const projects = registry.listProjects();
         ws.send(JSON.stringify({
             type: 'desktop.projects',
             projects,
@@ -680,6 +702,7 @@ app.use((err, _req, res, _next) => {
     }
 });
 // ─── Serve built React client (production) ────────────────────────────────────
+app.use(['/api', '/hooks'], api_not_found_1.apiNotFound);
 const clientDist = path_1.default.resolve(__dirname, '../../client/dist');
 if (fs_1.default.existsSync(clientDist)) {
     app.use(express_1.default.static(clientDist));
@@ -699,6 +722,13 @@ server.on('error', (err) => {
 server.listen(port, '127.0.0.1', () => {
     console.log(`specrails web manager running on http://127.0.0.1:${port}`);
     writePidFile();
+    // Milestone launch chains launch chunks over loopback REST, so a chain whose
+    // chunk settled while the server was down can only replay once we listen.
+    for (const ctx of _registry?.listContexts() ?? []) {
+        void ctx.milestoneChains?.recoverOnStartup().catch((err) => {
+            console.error(`[milestone-chain] startup recovery failed for ${ctx.project.id}:`, err);
+        });
+    }
     // Sweep stale shell-integration shim directories left behind by previous runs.
     try {
         const removed = (0, terminal_shell_integration_1.cleanupStaleShimDirs)();
@@ -744,6 +774,17 @@ async function shutdown() {
         Promise.resolve().then(() => _agentChatManager?.shutdown()),
         Promise.resolve().then(() => _blueprintChatManager?.shutdown()),
     ]);
+    // The shell can exit before its application descendants. Keep the event
+    // loop alive for the owned-group escalation before server.close exits us.
+    const remainingBackground = await (0, transient_children_1.awaitBackgroundProcessesStopped)(6000);
+    if (remainingBackground.length)
+        console.error('[shutdown] background applications still alive after stop deadline:', remainingBackground.map(({ pid, processId, error }) => ({ pid, processId, error })));
+    try {
+        (0, transient_children_1.closeBackgroundProcessPersistence)();
+    }
+    catch (error) {
+        console.error('[shutdown] background process history could not be flushed:', error);
+    }
     try {
         await _headroomManager?.shutdown();
     }