fraim-hub 2.0.268 → 2.0.270

package/dist/src/ai-hub/catalog.js

@@ -7,6 +7,7 @@ exports.summarizeProject = summarizeProject;
 exports.discoverEmployeeJobs = discoverEmployeeJobs;
 exports.discoverManagerTemplates = discoverManagerTemplates;
 exports.loadJobPhases = loadJobPhases;
+exports.resolveJobPhaseTransition = resolveJobPhaseTransition;
 exports.loadAllJobPhaseIds = loadAllJobPhaseIds;
 exports.labelForPhaseId = labelForPhaseId;
 exports.getAiHubCategories = getAiHubCategories;
@@ -470,6 +471,19 @@ function loadJobPhases(jobId, projectPath, discriminant = 'feature') {
 // this job before appending it to the tracker, so cross-job pollution
 // (agent calling seekMentoring for a different job mid-run) cannot
 // surface stages from elsewhere.
+function resolveJobPhaseTransition(jobId, projectPath, phaseId, outcome, discriminant = 'feature') {
+    const stubPath = findJobStubPath(projectPath, jobId);
+    if (!stubPath)
+        return null;
+    const fm = readJobFrontmatter(stubPath);
+    if (!fm || !fm.phases)
+        return null;
+    const phaseDef = fm.phases[phaseId];
+    if (!phaseDef)
+        return null;
+    const edge = outcome === 'complete' ? phaseDef.onSuccess : phaseDef.onFailure;
+    return nextPhase(edge, discriminant);
+}
 function loadAllJobPhaseIds(jobId, projectPath) {
     const stubPath = findJobStubPath(projectPath, jobId);
     if (!stubPath)

package/dist/src/ai-hub/cli.js

@@ -36,6 +36,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DESKTOP_HUB_READY_TIMEOUT_ENV = void 0;
+exports.resolveDesktopReadyTimeoutMs = resolveDesktopReadyTimeoutMs;
 exports.waitForDesktopHubReady = waitForDesktopHubReady;
 exports.runHub = runHub;
 // Hub-owned launcher used by the fraim-hub package. Keep this outside
@@ -51,15 +53,8 @@ const hub_launch_decision_1 = require("./hub-launch-decision");
 const hub_runtime_file_1 = require("./hub-runtime-file");
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
 const version_utils_1 = require("../cli/utils/version-utils");
-function resolveElectronBinary() {
-    try {
-        // eslint-disable-next-line @typescript-eslint/no-var-requires
-        return require('electron');
-    }
-    catch {
-        return null;
-    }
-}
+const electron_dist_1 = require("./electron-dist");
+const process_liveness_1 = require("./process-liveness");
 function resolveDesktopEntry() {
     const candidates = [
         path_1.default.resolve(__dirname, 'desktop-main.js'),
@@ -76,10 +71,20 @@ function resolveDesktopEntry() {
     }
     return null;
 }
-function openDesktopWindow(projectPath, preferredPort, runtimeId) {
-    const electronBinary = resolveElectronBinary();
+// #1112: the Electron binary is resolved (and, on a first launch for a version, extracted) before
+// the spawn, not inside waitForDesktopHubReady. A one-time extraction is minutes of work on a slow
+// disk; charging it to the readiness budget is exactly the mistake #1110 fixed, so it happens here
+// with progress on stdout while nothing is being waited on.
+async function openDesktopWindow(projectPath, preferredPort, runtimeId) {
     const desktopEntry = resolveDesktopEntry();
-    if (!electronBinary || !desktopEntry) {
+    if (!desktopEntry) {
+        return null;
+    }
+    const electron = await (0, electron_dist_1.resolveHubElectronBinary)({
+        onProgress: (message) => console.log(message),
+        onError: (error) => console.log(`Could not prepare the shared Electron runtime (${error.message}). Opening the FRAIM Hub in your browser instead.`),
+    });
+    if (!electron) {
         return null;
     }
     const args = projectPath
@@ -88,7 +93,7 @@ function openDesktopWindow(projectPath, preferredPort, runtimeId) {
     if (runtimeId && runtimeId !== 'hub') {
         args.push('--hub-runtime-id', runtimeId);
     }
-    const child = (0, child_process_1.spawn)(electronBinary, args, {
+    const child = (0, child_process_1.spawn)(electron.binaryPath, args, {
         detached: true,
         stdio: 'ignore',
     });
@@ -108,15 +113,6 @@ function openBrowser(url) {
     const child = (0, child_process_1.spawn)('xdg-open', [url], { detached: true, stdio: 'ignore' });
     child.unref();
 }
-function isProcessAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (e) {
-        return !!(e && e.code === 'EPERM');
-    }
-}
 function killPid(pid) {
     try {
         if (process.platform === 'win32') {
@@ -207,9 +203,55 @@ function fetchRunningHubVersion(port) {
         req.on('timeout', () => { req.destroy(); resolve(null); });
     });
 }
+// #1110: the desktop shell's cold-start cost is work this launcher can neither see nor bound.
+// Before the Hub can answer /api/ai-hub/version it pays for Electron process boot, top-level
+// evaluation of the src/ai-hub/server.ts module graph, cert load plus a blocking certutil
+// trust call, and finally the listens. The same path measured 3.3s on an idle machine and
+// 20.5s on a real `npx fraim-hub@latest --restart` immediately after a release, when npm has
+// just written a fresh Electron dist. A fixed budget inside that spread turns a healthy launch
+// into a reported failure, which is what issue #1110 reports.
+//
+// The only positive evidence of a failed launch is the child dying, and that is handled
+// separately below. A live child that has not answered yet is still starting, so the wait is
+// long, says so out loud while it waits, and stays tunable for slower machines.
+exports.DESKTOP_HUB_READY_TIMEOUT_ENV = 'FRAIM_HUB_READY_TIMEOUT_MS';
+const DEFAULT_DESKTOP_HUB_READY_TIMEOUT_MS = 120000;
+const DEFAULT_DESKTOP_HUB_READY_PROGRESS_MS = 15000;
+function resolveDesktopReadyTimeoutMs() {
+    const configured = Number(process.env[exports.DESKTOP_HUB_READY_TIMEOUT_ENV]);
+    if (Number.isFinite(configured) && configured > 0)
+        return configured;
+    return DEFAULT_DESKTOP_HUB_READY_TIMEOUT_MS;
+}
+// Whole seconds read best at the real cadence (15s, 30s, 120s), but rounding a sub-second
+// duration to whole seconds prints "after 0s" or repeats "1s elapsed" on consecutive notices.
+// Keep one decimal below this threshold so the number is never wrong at any budget.
+const READY_SECONDS_DECIMAL_BELOW_MS = 10000;
+function formatReadySeconds(durationMs) {
+    return durationMs >= READY_SECONDS_DECIMAL_BELOW_MS
+        ? `${Math.round(durationMs / 1000)}s`
+        : `${Math.round(durationMs / 100) / 10}s`;
+}
+function reportDesktopReadyProgress(progress) {
+    console.log(`Still waiting for the FRAIM Hub desktop shell on port ${progress.port} `
+        + `(${formatReadySeconds(progress.elapsedMs)} elapsed, giving up at ${formatReadySeconds(progress.timeoutMs)}). `
+        + 'A first launch after an upgrade unpacks Electron, so this can take a while.');
+}
+// Where the Hub could be answering: the shell records its chosen port in the runtime file once
+// it is listening, which is the only way the launcher learns about a port other than the one it
+// asked for. Re-read every poll, because that file is written mid-wait.
+function readinessProbePorts(fraimDir, runtimeId, preferredPort) {
+    const runtime = (0, hub_runtime_file_1.readHubRuntimeFile)(fraimDir, runtimeId);
+    return runtime?.port && runtime.port !== preferredPort
+        ? [runtime.port, preferredPort]
+        : [preferredPort];
+}
 async function waitForDesktopHubReady(child, preferredPort, options = {}) {
-    const timeoutMs = options.timeoutMs ?? 15000;
+    const timeoutMs = options.timeoutMs ?? resolveDesktopReadyTimeoutMs();
     const pollMs = options.pollMs ?? 250;
+    const progressAfterMs = options.progressAfterMs ?? DEFAULT_DESKTOP_HUB_READY_PROGRESS_MS;
+    const progressIntervalMs = options.progressIntervalMs ?? progressAfterMs;
+    const onProgress = options.onProgress ?? reportDesktopReadyProgress;
     const runtimeId = options.runtimeId || 'hub';
     const fraimDir = options.fraimDir || (0, project_fraim_paths_1.getUserFraimDirPath)();
     const start = Date.now();
@@ -220,7 +262,10 @@ async function waitForDesktopHubReady(child, preferredPort, options = {}) {
     child.once('error', (error) => {
         childState.error = error;
     });
-    while (Date.now() - start < timeoutMs) {
+    // A dead child is the only positive evidence that the launch failed, so it always wins over
+    // the elapsed budget. Checked at the top of every poll and once more after the loop, so a
+    // child that dies during the final sleep is still reported as an exit and not as a timeout.
+    const failIfChildDied = () => {
         if (childState.error) {
             throw new Error(`FRAIM Hub desktop shell failed to launch: ${childState.error.message}`);
         }
@@ -228,24 +273,35 @@ async function waitForDesktopHubReady(child, preferredPort, options = {}) {
             const detail = childState.exit.signal ? `signal ${childState.exit.signal}` : `exit code ${childState.exit.code ?? 'unknown'}`;
             throw new Error(`FRAIM Hub desktop shell exited before the Hub became ready (${detail}).`);
         }
-        const runtime = (0, hub_runtime_file_1.readHubRuntimeFile)(fraimDir, runtimeId);
-        const ports = runtime?.port && runtime.port !== preferredPort
-            ? [runtime.port, preferredPort]
-            : [preferredPort];
-        for (const port of ports) {
+    };
+    let nextProgressAtMs = progressAfterMs;
+    while (Date.now() - start < timeoutMs) {
+        failIfChildDied();
+        for (const port of readinessProbePorts(fraimDir, runtimeId, preferredPort)) {
             const version = await fetchRunningHubVersion(port);
             if (version) {
                 return { port, version };
             }
         }
+        const elapsedMs = Date.now() - start;
+        if (elapsedMs >= nextProgressAtMs) {
+            onProgress({ elapsedMs, timeoutMs, port: preferredPort });
+            nextProgressAtMs = elapsedMs + progressIntervalMs;
+        }
         await new Promise((r) => setTimeout(r, pollMs));
     }
-    throw new Error(`Timed out waiting for FRAIM Hub desktop shell to become ready on port ${preferredPort}.`);
+    failIfChildDied();
+    const stillRunning = typeof child.pid === 'number'
+        ? ` The desktop shell (pid ${child.pid}) is still running and may finish starting on its own.`
+        : '';
+    throw new Error(`Timed out waiting for FRAIM Hub desktop shell to become ready on port ${preferredPort} after ${formatReadySeconds(timeoutMs)}.`
+        + `${stillRunning}`
+        + ` Set ${exports.DESKTOP_HUB_READY_TIMEOUT_ENV} to a larger value if this machine needs longer.`);
 }
 async function reconcileRunningHub(flags, runtimeId = 'hub') {
     const running = (0, hub_runtime_file_1.readHubRuntimeFile)((0, project_fraim_paths_1.getUserFraimDirPath)(), runtimeId);
     const confirmedVersion = running ? await fetchRunningHubVersion(running.port) : null;
-    const live = !!(running && confirmedVersion && isProcessAlive(running.pid));
+    const live = !!(running && confirmedVersion && (0, process_liveness_1.isPidAlive)(running.pid));
     const effective = live && running ? { ...running, version: confirmedVersion } : null;
     const decision = (0, hub_launch_decision_1.decideHubLaunch)({
         running: effective,
@@ -278,7 +334,7 @@ async function runHub(options) {
         if (wantDesktop) {
             await reconcileRunningHub({ restart: !!options.restart, keepRunning: !!options.keepRunning }, runtimeId);
         }
-        const desktopChild = wantDesktop ? openDesktopWindow(projectPath, preferredPort, runtimeId) : null;
+        const desktopChild = wantDesktop ? await openDesktopWindow(projectPath, preferredPort, runtimeId) : null;
         if (!desktopChild) {
             const port = await findAvailablePort(preferredPort);
             const server = new AiHubServer(projectPath ? { projectPath } : {});

package/dist/src/ai-hub/conversation-store-lock.js

@@ -7,22 +7,13 @@ exports.isLockStale = isLockStale;
 exports.withBucketLock = withBucketLock;
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
+const process_liveness_1 = require("./process-liveness");
 const DEFAULT_TIMEOUT_MS = 5000;
 const DEFAULT_STALE_MS = 10000;
 // Synchronous sleep without a busy spin (the store's write path is synchronous).
 function sleepMs(ms) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
-function pidAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (error) {
-        // ESRCH: no such process. EPERM: exists but not ours (still alive).
-        return error.code === 'EPERM';
-    }
-}
 // A lock is stale (safe to steal) if its file is unreadable/absent, its timestamp is older than
 // staleMs, or it names a dead pid on this same host.
 function isLockStale(lockPath, staleMs = DEFAULT_STALE_MS) {
@@ -35,7 +26,7 @@ function isLockStale(lockPath, staleMs = DEFAULT_STALE_MS) {
     }
     if (typeof info.ts === 'number' && Date.now() - info.ts > staleMs)
         return true;
-    if (typeof info.pid === 'number' && info.host === os_1.default.hostname() && !pidAlive(info.pid))
+    if (typeof info.pid === 'number' && info.host === os_1.default.hostname() && !(0, process_liveness_1.isPidAlive)(info.pid))
         return true;
     return false;
 }

package/dist/src/ai-hub/desktop-main.js

@@ -5,7 +5,6 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.launchDesktopShell = launchDesktopShell;
 const electron_1 = require("electron");
-const electron_updater_1 = require("electron-updater");
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
 const server_1 = require("./server");
@@ -91,8 +90,14 @@ function ensureLoginItem() {
 function configureAutoUpdater() {
     if (!electron_1.app.isPackaged)
         return;
-    electron_updater_1.autoUpdater.autoDownload = true;
-    electron_updater_1.autoUpdater.checkForUpdatesAndNotify().catch((err) => {
+    // #1110: electron-updater compiles ~114 files (js-yaml, builder-util-runtime, ...) that a
+    // non-packaged `npx fraim-hub` launch never uses, and this whole function returns early
+    // there. Requiring it lazily keeps those file reads off the cold-start path, which is what
+    // dominates time-to-ready on a freshly unpacked install.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { autoUpdater } = require('electron-updater');
+    autoUpdater.autoDownload = true;
+    autoUpdater.checkForUpdatesAndNotify().catch((err) => {
         console.warn('[fraim] auto-update check failed:', err);
     });
 }
@@ -329,13 +334,10 @@ async function launchDesktopShell(options) {
     const httpsPort = await (0, server_1.findAvailablePortExcluding)(43092, new Set([httpPort]));
     // Generate (or load cached) self-signed cert for HTTPS.
     // Fast on subsequent launches (file read); ~200ms on first launch (key gen).
+    // The cert bundle itself is needed here because server.start() binds the HTTPS listener with
+    // it. Trusting it in the OS store is a separate, Word-Online-only concern and happens after
+    // the Hub is serving (#1110) - see below.
     const certBundle = await (0, cert_store_1.loadOrCreateCert)();
-    try {
-        (0, cert_store_1.trustCert)((0, cert_store_1.certPaths)().certPath);
-    }
-    catch (err) {
-        console.warn('[fraim] could not trust localhost certificate:', err);
-    }
     server = new server_1.AiHubServer({
         ...(options.projectPath ? { projectPath: options.projectPath } : {}),
         // Issue #701: no local DB. Persona/manager-team state resolves through the hosted
@@ -366,6 +368,16 @@ async function launchDesktopShell(options) {
     catch (err) {
         console.warn('[fraim] could not write hub runtime file:', err);
     }
+    // #1110: trusting the loopback cert in the OS store is a blocking `certutil` subprocess and
+    // is only needed so Word *Online* will render the task pane over HTTPS. The Hub does not need
+    // it to serve, so it runs after the server is listening rather than in front of it. Grouped
+    // with the Office sideload because both are Word-only first-run housekeeping.
+    try {
+        (0, cert_store_1.trustCert)((0, cert_store_1.certPaths)().certPath);
+    }
+    catch (err) {
+        console.warn('[fraim] could not trust localhost certificate:', err);
+    }
     ensureWordSideload(resolvedProjectPath, httpsPort);
     const hubUrl = `http://127.0.0.1:${httpPort}/ai-hub/`;
     createTray(hubUrl, runtimeId);

package/dist/src/ai-hub/electron-dist.js

@@ -0,0 +1,265 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HUB_ELECTRON_VERSION = void 0;
+exports.electronExecutableRelativePath = electronExecutableRelativePath;
+exports.resolveSharedElectronDistDir = resolveSharedElectronDistDir;
+exports.resolveSharedElectronBinaryPath = resolveSharedElectronBinaryPath;
+exports.isElectronDistComplete = isElectronDistComplete;
+exports.ensureSharedElectronDist = ensureSharedElectronDist;
+exports.resolveHubElectronBinary = resolveHubElectronBinary;
+// #1112: one shared, versioned Electron dist instead of a private 345 MB copy per npx install.
+//
+// `electron` used to be a hard dependency of packages/fraim-hub. npm runs its postinstall in every
+// tree it installs into, and that postinstall extracts the ~345 MB platform zip. Because
+// `npx fraim-hub@latest` creates a fresh `_npx/<hash>/` tree for every published version, the same
+// dist was unpacked again on every upgrade: 27 copies and 9.1 GB on one developer machine, and a
+// first-execution cost on freshly written binaries that was the largest remaining term in the Hub
+// cold start measured in #1110.
+//
+// The extraction cannot be skipped at launch time. electron/install.js short-circuits only on
+// ELECTRON_SKIP_BINARY_DOWNLOAD, read from the environment of the npm process, and by the time
+// src/ai-hub/cli.ts runs npm has already unpacked. So `electron` is no longer declared at all, and
+// the Hub resolves the binary itself from ~/.fraim/bin/electron/<version>/ — extracted once per
+// Electron version per machine, shared by every installed and future fraim-hub version.
+//
+// The zip still comes from the same shared cache npm used (~/AppData/Local/electron/Cache on
+// Windows, ~/Library/Caches/electron on macOS, ~/.cache/electron on Linux), because this reuses
+// @electron/get and extract-zip — the two modules electron/install.js itself uses. That keeps
+// checksum validation, mirror and proxy environment variables, and symlink- and mode-preserving
+// extraction behaving exactly as they do today.
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
+const process_liveness_1 = require("./process-liveness");
+/**
+ * The exact Electron release the Hub runs on, and the runtime source of truth for it.
+ *
+ * @electron/get needs an exact version: a range cannot name a download. Two other declarations are
+ * pinned to this value and `scripts/validate-package-split.ts` fails the build if either drifts:
+ *   - `packages/fraim-hub` `build.electronVersion`, which is how electron-builder learns the
+ *     version now that `electron` is absent from that manifest.
+ *   - the repo root's `dependencies.electron` range, which still installs Electron for local dev,
+ *     `npm run hub:desktop`, and the Electron-launching test suites.
+ */
+exports.HUB_ELECTRON_VERSION = '41.2.2';
+/** Relative path of the Electron executable inside a dist, matching getPlatformPath() in electron/install.js. */
+function electronExecutableRelativePath(platform = process.platform) {
+    switch (platform) {
+        case 'darwin':
+            return path_1.default.join('Electron.app', 'Contents', 'MacOS', 'Electron');
+        case 'win32':
+            return 'electron.exe';
+        default:
+            return 'electron';
+    }
+}
+// An Electron release is `x.y.z` or `x.y.z-<prerelease>`, and nothing else. Anchoring on that shape
+// means a version string can never carry path syntax into the directory name below, which matters
+// because `ensureSharedElectronDist` calls a recursive `fs.rmSync` on the resulting path: a version
+// of `../../..` would delete an unrelated tree. Not reachable today - every caller resolves to the
+// compile-time `HUB_ELECTRON_VERSION` - so this is a guard at the write boundary, kept next to the
+// path construction it protects rather than left to every future caller to remember.
+const EXACT_ELECTRON_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+function assertPathSafeVersion(version) {
+    if (!EXACT_ELECTRON_VERSION.test(version)) {
+        throw new Error(`Refusing to use "${version}" as an Electron version: expected an exact release such as 41.2.2.`);
+    }
+    return version;
+}
+/**
+ * `~/.fraim/bin/electron/<version>/`.
+ *
+ * Deliberately a sibling of, not a child of, `resolveHubInstallDir()`
+ * (`~/.fraim/bin/fraim-hub-electron/`). That directory belongs to the installed Hub application:
+ * `runHubInstall` writes `fraim-hub.exe` and the downloaded release asset into it, and
+ * `installDownloadedAsset` does an `fs.rmSync` inside it on macOS. A shared runtime with a
+ * different lifecycle should not live inside a tree another code path deletes from.
+ */
+function resolveSharedElectronDistDir(version, fraimDir = (0, project_fraim_paths_1.getUserFraimDirPath)()) {
+    return path_1.default.join(fraimDir, 'bin', 'electron', assertPathSafeVersion(version));
+}
+/** Absolute path of the Electron executable inside the shared dist for a version. */
+function resolveSharedElectronBinaryPath(version, fraimDir = (0, project_fraim_paths_1.getUserFraimDirPath)(), platform = process.platform) {
+    return path_1.default.join(resolveSharedElectronDistDir(version, fraimDir), electronExecutableRelativePath(platform));
+}
+/**
+ * Whether a directory holds a complete dist for exactly this version.
+ *
+ * Same two conditions electron's own `isInstalled()` checks: the `version` file names this release,
+ * and the platform executable is present. A dist that fails either is stale or half-written, and
+ * spawning from it would fail at launch instead of here.
+ */
+function isElectronDistComplete(distDir, version, platform = process.platform) {
+    try {
+        const recorded = fs_1.default.readFileSync(path_1.default.join(distDir, 'version'), 'utf8').trim().replace(/^v/, '');
+        if (recorded !== version)
+            return false;
+        return fs_1.default.existsSync(path_1.default.join(distDir, electronExecutableRelativePath(platform)));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the platform zip through @electron/get, so a zip npm already cached for this version is a
+ * cache hit and no bytes cross the network. Checksums stay enabled: @electron/get validates the
+ * artifact against SHASUMS256.txt, fetching that 2 KB file when no local checksums.json is
+ * available. That is the only integrity check standing between a 345 MB download and executing it.
+ */
+const downloadElectronZip = async ({ version, platform, arch }) => {
+    // Required lazily: @electron/get pulls in got, fs-extra, and sumchecker, and none of that belongs
+    // in the module graph of a launch that resolves an already-extracted dist.
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { downloadArtifact } = require('@electron/get');
+    return downloadArtifact({ version, artifactName: 'electron', platform, arch });
+};
+const extractElectronZip = async (zipPath, destDir) => {
+    // extract-zip is what electron/install.js uses, and it preserves the mode bits and the symlinks
+    // inside Electron.app/Contents/Frameworks that a naive zip reader drops.
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const extract = require('extract-zip');
+    await extract(zipPath, { dir: destDir });
+};
+/**
+ * Remove staging trees whose owning process is gone.
+ *
+ * The `finally` that cleans up a staging tree does not run when the process is killed, and the
+ * window it covers is a visible "Preparing the shared Electron runtime" message that invites a
+ * Ctrl+C. Without this sweep, one impatient interrupt strands ~345 MB under `~/.fraim` forever,
+ * which is the same disk leak this change exists to stop. A staging tree whose pid is still alive
+ * belongs to a concurrent launch and is left alone.
+ */
+function sweepDeadStagingDirs(distDir) {
+    const parent = path_1.default.dirname(distDir);
+    const prefix = `${path_1.default.basename(distDir)}.staging-`;
+    let entries;
+    try {
+        entries = fs_1.default.readdirSync(parent, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !entry.name.startsWith(prefix))
+            continue;
+        const pid = Number(entry.name.slice(prefix.length));
+        if (Number.isInteger(pid) && pid > 0 && (0, process_liveness_1.isPidAlive)(pid))
+            continue;
+        try {
+            fs_1.default.rmSync(path_1.default.join(parent, entry.name), { recursive: true, force: true });
+        }
+        catch {
+            /* best effort: a tree we cannot delete is not a reason to fail a launch */
+        }
+    }
+}
+/**
+ * Return the Electron executable in the shared dist for this version, extracting it first if it is
+ * not already there. Returns immediately when a complete dist exists, which is the case on every
+ * launch after the first for a given Electron version.
+ *
+ * Extraction goes to a staging sibling and is promoted with a rename, matching the
+ * `${dir}.staging-${pid}` pattern in `org-pack-sync.ts` and `manager-pack-sync.ts`. A failure
+ * therefore leaves no partial tree at the versioned path, so the next launch cannot mistake one for
+ * a usable dist.
+ */
+async function ensureSharedElectronDist(options = {}) {
+    const version = options.version ?? exports.HUB_ELECTRON_VERSION;
+    const fraimDir = options.fraimDir ?? (0, project_fraim_paths_1.getUserFraimDirPath)();
+    const platform = options.platform ?? process.platform;
+    const arch = options.arch ?? process.arch;
+    const distDir = resolveSharedElectronDistDir(version, fraimDir);
+    const binaryPath = resolveSharedElectronBinaryPath(version, fraimDir, platform);
+    if (isElectronDistComplete(distDir, version, platform)) {
+        return binaryPath;
+    }
+    const downloadZip = options.downloadZip ?? downloadElectronZip;
+    const extractZip = options.extractZip ?? extractElectronZip;
+    const onProgress = options.onProgress;
+    onProgress?.(`Preparing the shared Electron ${version} runtime in ${distDir}. `
+        + 'This happens once per Electron version on this machine; later Hub launches reuse it.');
+    const zipPath = await downloadZip({ version, platform, arch });
+    await extractAndPromote({ zipPath, distDir, version, platform, extractZip });
+    onProgress?.(`Shared Electron ${version} runtime ready.`);
+    return binaryPath;
+}
+/**
+ * Unpack a zip into `distDir`, atomically.
+ *
+ * Extraction goes to a `${distDir}.staging-${pid}` sibling and is promoted with a rename, matching
+ * the pattern in `org-pack-sync.ts` and `manager-pack-sync.ts`. A failure therefore leaves no
+ * partial tree at the versioned path, so the next launch cannot mistake one for a usable dist.
+ */
+async function extractAndPromote(args) {
+    const { zipPath, distDir, version, platform, extractZip } = args;
+    const stagingDir = `${distDir}.staging-${process.pid}`;
+    fs_1.default.mkdirSync(path_1.default.dirname(distDir), { recursive: true });
+    sweepDeadStagingDirs(distDir);
+    fs_1.default.rmSync(stagingDir, { recursive: true, force: true });
+    try {
+        await extractZip(zipPath, stagingDir);
+        if (!isElectronDistComplete(stagingDir, version, platform)) {
+            throw new Error(`Extracted Electron ${version} is missing its version file or ${electronExecutableRelativePath(platform)}; `
+                + `refusing to install an incomplete dist from ${zipPath}.`);
+        }
+        // A concurrent launch may have finished extracting the same version while this one worked.
+        // Promoting over a complete dist would delete the tree that launch is spawning from, so the
+        // winner keeps it and this one discards its own copy.
+        if (!isElectronDistComplete(distDir, version, platform)) {
+            fs_1.default.rmSync(distDir, { recursive: true, force: true });
+            try {
+                fs_1.default.renameSync(stagingDir, distDir);
+            }
+            catch (error) {
+                // The same race, one step later: the target can appear between that check and this rename.
+                // A complete dist at the target is the outcome this call wanted, so it is success.
+                if (!isElectronDistComplete(distDir, version, platform))
+                    throw error;
+            }
+        }
+    }
+    finally {
+        fs_1.default.rmSync(stagingDir, { recursive: true, force: true });
+    }
+}
+/** Resolve the `electron` npm package's own binary, or null when it is absent or points nowhere. */
+function resolveInstalledElectronBinary(requireElectron) {
+    try {
+        const binaryPath = requireElectron();
+        return typeof binaryPath === 'string' && fs_1.default.existsSync(binaryPath) ? binaryPath : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The Electron binary this Hub should launch, or null when there is none.
+ *
+ * An installed `electron` package wins when one is present. That is this repo, and any consumer who
+ * depends on Electron themselves: its dist is already on disk, so preferring it avoids a needless
+ * download and keeps `npm run hub:desktop` and the Electron-launching suites on the exact path they
+ * use today. The published `fraim-hub` package declares no `electron`, so it takes the shared dist.
+ *
+ * Null is a supported outcome, not a failure: `openDesktopWindow()` returns null in that case and
+ * `runHub` starts the in-process server and opens a browser. An offline first launch must reach that
+ * fallback rather than throwing, so a download failure is reported through `onError` and swallowed.
+ */
+async function resolveHubElectronBinary(options = {}) {
+    const requireElectron = options.requireElectron
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        ?? (() => require('electron'));
+    const installed = resolveInstalledElectronBinary(requireElectron);
+    if (installed) {
+        return { binaryPath: installed, source: 'installed-package' };
+    }
+    try {
+        return { binaryPath: await ensureSharedElectronDist(options), source: 'shared-dist' };
+    }
+    catch (error) {
+        options.onError?.(error instanceof Error ? error : new Error(String(error)));
+        return null;
+    }
+}

package/dist/src/ai-hub/hosts.js

@@ -33,7 +33,6 @@ const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const manager_turns_1 = require("./manager-turns");
 const managed_agent_paths_1 = require("../cli/utils/managed-agent-paths");
-const mcp_config_generator_1 = require("../cli/setup/mcp-config-generator");
 const agent_token_prices_1 = require("../local-mcp-server/agent-token-prices");
 const configured_agents_1 = require("./configured-agents");
 const pack_home_1 = require("../cli/utils/pack-home");
@@ -1155,7 +1154,13 @@ function prepareCodexBrowserHome(cdp, env = process.env) {
         const realConfig = path_1.default.join(real, 'config.toml');
         const existing = fs_1.default.existsSync(realConfig) ? fs_1.default.readFileSync(realConfig, 'utf8') : '';
         const pwBlock = `[mcp_servers.playwright]\ncommand = "npx"\nargs = ["-y", "@playwright/mcp@latest", "--cdp-endpoint", "${cdp}"]\n`;
-        const merged = (0, mcp_config_generator_1.mergeTomlMCPServers)(existing, pwBlock, ['playwright']).content;
+        // #1110: this is the only use of mcp-config-generator here, and it runs when a run launches,
+        // never at Hub startup. Importing it at module scope pulled the whole
+        // mcp-server-builder -> mcp-server-registry -> provider-registry -> provider-client -> axios
+        // chain (~30 files) into the graph the Hub must compile before it can listen.
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { mergeTomlMCPServers } = require('../cli/setup/mcp-config-generator');
+        const merged = mergeTomlMCPServers(existing, pwBlock, ['playwright']).content;
         fs_1.default.writeFileSync(path_1.default.join(home, 'config.toml'), merged, 'utf8');
         // Auth + the session index (so resume can find existing rollouts by thread id).
         for (const f of ['auth.json', 'session_index.jsonl', 'history.jsonl']) {

package/dist/src/ai-hub/process-liveness.js

@@ -0,0 +1,25 @@
+"use strict";
+// Is a pid on this host still running? A leaf with no dependencies, so any Hub module can use it
+// without pulling in a graph or creating an import cycle.
+//
+// #1112 consolidated three byte-identical copies of this: `isProcessAlive` in `cli.ts` (which
+// decides whether a recorded Hub instance is live), `pidAlive` in `conversation-store-lock.ts`
+// (which decides whether a lock is stealable), and a third that the shared-Electron-dist sweep
+// would otherwise have added.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPidAlive = isPidAlive;
+/**
+ * `process.kill(pid, 0)` sends no signal; it only checks that the process exists and is signalable.
+ * `ESRCH` means no such process. `EPERM` means it exists but belongs to another user, which still
+ * counts as alive — treating it as dead is what would let a caller steal a live lock or delete a
+ * live process's working tree.
+ */
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}