fraim-hub 2.0.288 → 2.0.290

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

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const electron_1 = require("electron");
+const path_1 = __importDefault(require("path"));
+const hub_app_materializer_1 = require("./hub-app-materializer");
+// Issue #1415: this is the packaged Electron `main` entry (see packages/fraim-hub/package.json
+// `"main"`). It is deliberately thin and changes rarely: its only job is to resolve which version
+// of the actual Hub application (the code in desktop-main.ts) to run — the latest published to
+// npm, materializing it once per machine if not already cached — and hand off to it. The native
+// installer only ever needs to ship a new build of this file and the Electron shell itself;
+// every ordinary `fraim-hub` release reaches an already-installed user the moment this
+// resolution runs on their next launch, with no new installer download.
+const BUNDLED_ENTRY_PATH = path_1.default.join(__dirname, 'desktop-main.js');
+async function bootstrapFrom(entryPath) {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const entry = require(entryPath);
+    await entry.bootstrap();
+}
+async function launch() {
+    // Issue #1415: deterministic escape hatch for integration testing — skips the real npm
+    // resolution (and its dependence on whatever happens to be published at test time) so a test can
+    // prove the Electron main-process boot chain itself (resolveHubAppEntry -> require -> bootstrap
+    // -> healthy server) without a network round-trip. Not used in any real launch path; mirrors the
+    // existing `FRAIM_INSTALLER_LIFECYCLE_TEST` kill-switch pattern already used for testability.
+    const resolved = process.env.FRAIM_HUB_SKIP_MATERIALIZE === '1'
+        ? { entryPath: BUNDLED_ENTRY_PATH, source: 'bundled', version: electron_1.app.getVersion() }
+        : await (0, hub_app_materializer_1.resolveHubAppEntry)({
+            bundledVersion: electron_1.app.getVersion(),
+            bundledEntryPath: BUNDLED_ENTRY_PATH,
+            onProgress: (message) => console.log(`[fraim-hub-launcher] ${message}`),
+        }).catch((error) => {
+            // resolveHubAppEntry is designed to never throw (every failure mode falls back internally),
+            // but a launch must survive even a bug in that resolution rather than fail here.
+            console.error('[fraim-hub-launcher] resolution failed unexpectedly; using the bundled build:', error);
+            return { entryPath: BUNDLED_ENTRY_PATH, source: 'bundled', version: electron_1.app.getVersion() };
+        });
+    console.log(`[fraim-hub-launcher] running FRAIM Hub ${resolved.version} (${resolved.source})`);
+    try {
+        await bootstrapFrom(resolved.entryPath);
+    }
+    catch (error) {
+        if (resolved.entryPath === BUNDLED_ENTRY_PATH)
+            throw error;
+        // A materialized copy that fails to load (corrupt cache, an ABI mismatch some future
+        // dependency introduces) must not strand the user on a broken launch — fall back to the
+        // build that shipped with this installer, which is always known-good for this Electron binary.
+        console.error(`[fraim-hub-launcher] materialized FRAIM Hub ${resolved.version} failed to load; falling back to the bundled build:`, error);
+        await bootstrapFrom(BUNDLED_ENTRY_PATH);
+    }
+}
+if (process.versions.electron && process.type !== 'renderer') {
+    launch().catch((error) => {
+        console.error(error instanceof Error ? error.message : error);
+        try {
+            electron_1.dialog.showErrorBox('FRAIM Hub failed to start', error instanceof Error ? error.message : String(error));
+        }
+        catch {
+            // dialog can be unavailable this early in rare startup failures; the console error above
+            // is the fallback record.
+        }
+        electron_1.app.exit(1);
+    });
+}

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

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.launchDesktopShell = launchDesktopShell;
+exports.bootstrap = bootstrap;
 const electron_1 = require("electron");
 const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
@@ -20,6 +21,7 @@ const server_2 = require("../first-run/server");
 const session_service_1 = require("../first-run/session-service");
 const fraim_mcp_latest_launcher_1 = require("../cli/mcp/fraim-mcp-latest-launcher");
 const desktop_auto_updater_1 = require("./desktop-auto-updater");
+const hub_app_materializer_1 = require("./hub-app-materializer");
 // Keep installed, running, and user-pinned Windows shortcuts grouped under the
 // stable identity declared in packages/fraim-hub/package.json.
 electron_1.app.setAppUserModelId('ai.fraim.hub');
@@ -73,7 +75,7 @@ function configurePackagedFraimRuntime() {
     if (!electron_1.app.isPackaged && process.env.FRAIM_DESKTOP_FIRST_RUN !== '1')
         return;
     process.env.FRAIM_PACKAGED_CLI_EXECUTABLE = process.execPath;
-    process.env.FRAIM_PACKAGED_CLI_SCRIPT = path_1.default.join(electron_1.app.getAppPath(), 'node_modules', 'fraim', 'bin', 'fraim.js');
+    process.env.FRAIM_PACKAGED_CLI_SCRIPT = (0, hub_app_materializer_1.resolvePackagedCliScriptPath)(__dirname);
     (0, fraim_mcp_latest_launcher_1.ensureFraimMcpLatestLauncher)();
 }
 function shouldShowEmbeddedFirstRun() {
@@ -133,11 +135,39 @@ async function configureAutoUpdater() {
     });
     return result.action === 'installing';
 }
-function checkForUpdateAfterSecondInstance() {
+// Issue #1415: a second-instance activation (the user re-clicking the icon while the Hub is
+// already running) is the common case once login-item autostart + hide-to-tray keep the Hub
+// resident for days, and it is the one launch-shaped event where the desktop-launcher.ts
+// materializer never gets a chance to run — bootstrap() has already won the single-instance lock
+// by the time it fires. Without this check, an already-running Hub could only ever pick up a new
+// `fraim-hub` release through the slower electron-updater feed below, which is the exact lagging
+// signal #1415 was filed about. `getFraimVersion()` (not `app.getVersion()`) is compared, because
+// it resolves from wherever the currently-running code actually lives — the bundled app.asar or a
+// previously materialized copy — while `app.getVersion()` always names the former.
+async function checkForHubAppUpdateOnSecondInstance() {
+    const runningVersion = (0, version_utils_1.getFraimVersion)();
+    const resolved = await (0, hub_app_materializer_1.resolveHubAppEntry)({
+        bundledVersion: runningVersion,
+        bundledEntryPath: __filename,
+    });
+    if (resolved.version === runningVersion)
+        return false;
+    console.log(`[fraim] newer FRAIM Hub ${resolved.version} available (was running ${runningVersion}); restarting to apply it`);
+    electron_1.app.relaunch();
+    electron_1.app.quit();
+    return true;
+}
+// Issue #1415: shared by both re-launch-shaped events on an already-running Hub — Windows/Linux's
+// `second-instance` (a new process lost the single-instance lock) and macOS's `activate` (the
+// Dock icon click that never spawns a new process at all, so `second-instance` never fires there).
+// Before this, neither path re-checked npm-latest, only the older, slower electron-updater feed.
+function checkForRelaunchAttemptUpdate() {
     if (!electron_1.app.isPackaged || process.env.FRAIM_INSTALLER_LIFECYCLE_TEST === '1')
         return;
-    void configureAutoUpdater().catch((err) => {
-        console.warn('[fraim] second-instance update check failed:', err);
+    void checkForHubAppUpdateOnSecondInstance()
+        .then((restarting) => (restarting ? undefined : configureAutoUpdater().then(() => undefined)))
+        .catch((err) => {
+        console.warn('[fraim] relaunch-attempt update check failed:', err);
     });
 }
 // ---------------------------------------------------------------------------
@@ -469,6 +499,9 @@ async function launchDesktopShell(options) {
 // ---------------------------------------------------------------------------
 // Bootstrap
 // ---------------------------------------------------------------------------
+// Issue #1415: exported so `desktop-launcher.ts` can `require()` this module (whether the copy
+// bundled in this installer or a materialized npm-latest copy) and invoke bootstrap explicitly,
+// instead of relying on the module's own top-level self-execution below.
 async function bootstrap() {
     const options = parseArgs(process.argv.slice(2));
     applyUserDataOverride();
@@ -483,7 +516,7 @@ async function bootstrap() {
         return;
     }
     electron_1.app.on('second-instance', () => {
-        void electron_1.app.whenReady().then(checkForUpdateAfterSecondInstance);
+        void electron_1.app.whenReady().then(checkForRelaunchAttemptUpdate);
         if (mainWindow) {
             mainWindow.show();
             mainWindow.focus();
@@ -508,7 +541,10 @@ async function bootstrap() {
             return;
     }
     electron_1.app.on('activate', () => {
-        // macOS: clicking dock icon re-shows the window
+        // macOS: clicking dock icon re-shows the window. Unlike Windows/Linux, this never spawns a
+        // second process (so 'second-instance' never fires here) — it is macOS's equivalent
+        // relaunch-attempt event, so it gets the same npm-latest re-check (#1415).
+        checkForRelaunchAttemptUpdate();
         if (mainWindow) {
             mainWindow.show();
             mainWindow.focus();
@@ -533,7 +569,12 @@ async function bootstrap() {
     });
     await launchDesktopShell(options);
 }
-if (process.versions.electron && process.type !== 'renderer') {
+// Issue #1415: self-execution is now gated on `require.main === module` in addition to the
+// existing Electron-main-process check, so `desktop-launcher.ts` requiring this file (bundled or
+// materialized) does not double-run bootstrap — the launcher calls the exported `bootstrap`
+// explicitly instead. Direct invocation (`npm run hub:desktop`, Electron-launching test suites)
+// is unaffected: this file is still `require.main` in that case.
+if (require.main === module && process.versions.electron && process.type !== 'renderer') {
     bootstrap().catch(async (error) => {
         console.error(error instanceof Error ? error.message : error);
         await stopServerOnce();

package/dist/src/ai-hub/hub-app-materializer.js

@@ -0,0 +1,285 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HUB_APP_ENTRY_RELATIVE = exports.HUB_APP_PACKAGE_NAME = void 0;
+exports.resolvePackagedCliScriptPath = resolvePackagedCliScriptPath;
+exports.planHubAppMaterialization = planHubAppMaterialization;
+exports.resolveHubAppCacheDir = resolveHubAppCacheDir;
+exports.isHubAppCacheComplete = isHubAppCacheComplete;
+exports.listCachedHubAppVersions = listCachedHubAppVersions;
+exports.ensureMaterializedHubApp = ensureMaterializedHubApp;
+exports.resolveHubAppEntry = resolveHubAppEntry;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const semver_1 = __importDefault(require("semver"));
+const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
+const hub_latest_version_1 = require("./hub-latest-version");
+const managed_node_runtime_1 = require("../cli/utils/managed-node-runtime");
+// Issue #1415: a packaged FRAIM Hub install can already be behind npm's published "latest" the
+// moment it is downloaded, and its own electron-updater feed (#1387) only advances once a full
+// signed desktop build has finished — which happens on a much slower cadence than npm publishes.
+// This module reconciles the two: on every launch, resolve the version actually published to npm
+// (`fraim-hub` and `fraim` are lockstep-versioned, so `hub-latest-version.ts`'s existing 5-minute-
+// cached npm lookup is reused rather than duplicated), materialize that version's application code
+// once per machine (mirroring `electron-dist.ts`'s "extract once, reuse forever" shared-dist
+// pattern), and hand back the entry point to run. The Electron shell itself — installed once via
+// the native installer — never needs a new install for an ordinary `fraim-hub` point release; only
+// the application payload this module resolves does.
+//
+// The decision (`planHubAppMaterialization`) is a pure function so the whole staleness/cache/
+// offline matrix is unit-testable without touching npm, disk, or Electron — the same separation
+// `hub-launch-decision.ts` (#755) and `desktop-auto-updater.ts` (#1387) already established for
+// this exact class of problem.
+exports.HUB_APP_PACKAGE_NAME = 'fraim-hub';
+/** Relative path, from a materialized (or bundled) package root, to the Electron main entry. */
+exports.HUB_APP_ENTRY_RELATIVE = path_1.default.join('dist', 'src', 'ai-hub', 'desktop-main.js');
+/**
+ * Where the packaged CLI/MCP shim (`ensureFraimMcpLatestLauncher()`) should find `fraim`'s CLI
+ * script, derived from `desktop-main.ts`'s own directory (`<packageRoot>/dist/src/ai-hub/`) rather
+ * than Electron's `app.getAppPath()`. `desktop-launcher.ts` may have loaded `desktop-main.js` from a
+ * materialized `fraim-hub@<latest>` copy under `~/.fraim/bin/hub-app/<version>/` rather than from
+ * the original app.asar, and `app.getAppPath()` always names the latter regardless of which copy is
+ * actually running. `moduleDir` tracks whichever copy is really executing. Kept in this
+ * Electron-free module (rather than inlined in `desktop-main.ts`) so it is unit-testable without an
+ * Electron `app` object.
+ */
+function resolvePackagedCliScriptPath(moduleDir) {
+    return path_1.default.join(moduleDir, '..', '..', '..', 'node_modules', 'fraim', 'bin', 'fraim.js');
+}
+function pickNewestComplete(cachedVersions) {
+    const versions = cachedVersions.filter((entry) => entry.complete).map((entry) => entry.version);
+    if (versions.length === 0)
+        return null;
+    return versions.reduce((newest, candidate) => (semver_1.default.gt(candidate, newest) ? candidate : newest));
+}
+/**
+ * Decide whether to run a cached materialized version, materialize a new one, or fall back to the
+ * version bundled with this installer. Pure: no fs, no network, no Electron.
+ */
+function planHubAppMaterialization(input) {
+    const { bundledVersion, latestPublishedVersion, cachedVersions } = input;
+    if (latestPublishedVersion === null) {
+        const newestCached = pickNewestComplete(cachedVersions);
+        if (newestCached) {
+            return {
+                action: 'use-cached',
+                version: newestCached,
+                reason: 'npm registry unreachable; reusing the newest complete cached version',
+            };
+        }
+        return {
+            action: 'use-bundled',
+            version: bundledVersion,
+            reason: 'npm registry unreachable and no cached version available; falling back to the version bundled with this installer',
+        };
+    }
+    if (latestPublishedVersion === bundledVersion) {
+        return {
+            action: 'use-bundled',
+            version: bundledVersion,
+            reason: 'the installed shell already matches the latest published version',
+        };
+    }
+    const alreadyMaterialized = cachedVersions.some((entry) => entry.complete && entry.version === latestPublishedVersion);
+    if (alreadyMaterialized) {
+        return {
+            action: 'use-cached',
+            version: latestPublishedVersion,
+            reason: 'latest published version is already materialized on disk',
+        };
+    }
+    return {
+        action: 'materialize',
+        version: latestPublishedVersion,
+        reason: `latest published version ${latestPublishedVersion} is not yet materialized`,
+    };
+}
+// ---------------------------------------------------------------------------
+// Cache directory layout: ~/.fraim/bin/hub-app/<version>/
+// ---------------------------------------------------------------------------
+// Same shape as an npm version, optionally with a prerelease/build suffix. Anchoring on this
+// before ever joining a version into a path means a hostile string (`../../..`, an absolute path)
+// can never escape the versioned cache directory.
+const SAFE_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+function assertPathSafeVersion(version) {
+    if (!SAFE_VERSION.test(version)) {
+        throw new Error(`Refusing to use "${version}" as a fraim-hub version: expected an exact release such as 2.0.290.`);
+    }
+    return version;
+}
+function resolveHubAppCacheDir(version, fraimDir = (0, project_fraim_paths_1.getUserFraimDirPath)()) {
+    return path_1.default.join(fraimDir, 'bin', 'hub-app', assertPathSafeVersion(version));
+}
+/** Whether `dir` holds a complete materialized install for exactly `version`. */
+function isHubAppCacheComplete(dir, version) {
+    try {
+        const recorded = fs_1.default.readFileSync(path_1.default.join(dir, 'version'), 'utf8').trim();
+        if (recorded !== version)
+            return false;
+        return fs_1.default.existsSync(path_1.default.join(dir, exports.HUB_APP_ENTRY_RELATIVE));
+    }
+    catch {
+        return false;
+    }
+}
+/** Every version directory under the cache root that is a complete, trustworthy install. */
+function listCachedHubAppVersions(fraimDir = (0, project_fraim_paths_1.getUserFraimDirPath)()) {
+    const root = path_1.default.join(fraimDir, 'bin', 'hub-app');
+    let entries;
+    try {
+        entries = fs_1.default.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const versions = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !semver_1.default.valid(entry.name))
+            continue;
+        if (isHubAppCacheComplete(path_1.default.join(root, entry.name), entry.name)) {
+            versions.push({ version: entry.name, complete: true });
+        }
+    }
+    return versions;
+}
+/**
+ * Default installer: `npm install fraim-hub@<version>` into a scratch prefix, then flatten the
+ * installed package up to `destDir` so callers can treat `destDir` itself as the package root
+ * (`destDir/dist/...`), with the package's own dependencies left as siblings under
+ * `destDir/node_modules/` where Node's module resolution finds them from any depth under `destDir`.
+ * A fresh, empty `--prefix` install of a single package has nothing to conflict with, so npm hoists
+ * every dependency to that top level; nothing here relies on nested-dependency resolution.
+ *
+ * The `npm` executable itself is resolved via `ensureManagedNpm()` (system PATH, an already-managed
+ * runtime, or a freshly downloaded one) rather than assumed present on PATH — a genuinely GUI-only
+ * install (native installer only, no CLI ever run) has neither system npm nor FRAIM's own managed
+ * one, since first-run's embedded-desktop path only needs Electron's own bundled Node for its own
+ * purposes and never downloads a standalone npm (see managed-node-runtime.ts's own header comment).
+ */
+// Node's spawnSync fails with EINVAL when a `.cmd` shim (npm's own launcher on Windows) is
+// invoked directly without a shell — the same issue `fraim-mcp-latest-launcher.ts` already works
+// around for `npm`/`npx`. Mirrors that exact fix: run through cmd.exe with args quoted, rather
+// than inventing a different approach for this second call site.
+function quoteCmdArg(arg) {
+    return /[\s"&|<>^]/.test(arg) ? `"${arg.replace(/"/g, '""')}"` : arg;
+}
+function runNpmInstall(npmPath, args) {
+    if (process.platform !== 'win32') {
+        return (0, child_process_1.spawnSync)(npmPath, args, { encoding: 'utf8' });
+    }
+    return (0, child_process_1.spawnSync)(process.env.ComSpec || 'cmd.exe', ['/d', '/s', '/c', [quoteCmdArg(npmPath), ...args.map(quoteCmdArg)].join(' ')], { encoding: 'utf8' });
+}
+const defaultInstallPackage = async (version, destDir) => {
+    fs_1.default.mkdirSync(destDir, { recursive: true });
+    const npm = await (0, managed_node_runtime_1.ensureManagedNpm)();
+    const result = runNpmInstall(npm.npmPath, ['install', `${exports.HUB_APP_PACKAGE_NAME}@${version}`, '--no-save', '--omit=dev', '--prefix', destDir]);
+    if (result.status !== 0) {
+        const detail = result.stderr || result.stdout || result.error?.message || 'unknown error';
+        throw new Error(`npm install ${exports.HUB_APP_PACKAGE_NAME}@${version} failed via ${npm.source} npm (exit ${result.status}): ${detail}`);
+    }
+    const installedRoot = path_1.default.join(destDir, 'node_modules', exports.HUB_APP_PACKAGE_NAME);
+    if (!fs_1.default.existsSync(installedRoot)) {
+        throw new Error(`npm install ${exports.HUB_APP_PACKAGE_NAME}@${version} did not produce ${installedRoot}`);
+    }
+    for (const entry of fs_1.default.readdirSync(installedRoot)) {
+        const from = path_1.default.join(installedRoot, entry);
+        const to = path_1.default.join(destDir, entry);
+        if (entry === 'node_modules' && fs_1.default.existsSync(to)) {
+            // Only reachable if npm nested a dependency inside fraim-hub's own node_modules despite the
+            // empty prefix (a version conflict with itself is not possible, but defend anyway): merge
+            // child-by-child rather than clobbering the siblings already hoisted to destDir/node_modules.
+            for (const nested of fs_1.default.readdirSync(from)) {
+                fs_1.default.renameSync(path_1.default.join(from, nested), path_1.default.join(to, nested));
+            }
+        }
+        else {
+            fs_1.default.renameSync(from, to);
+        }
+    }
+    fs_1.default.rmSync(installedRoot, { recursive: true, force: true });
+};
+/**
+ * Return the entry path for `version`, materializing it first if it is not already a complete
+ * cache entry. Returns immediately (no npm invocation) when a complete entry already exists.
+ */
+async function ensureMaterializedHubApp(version, options = {}) {
+    const fraimDir = options.fraimDir ?? (0, project_fraim_paths_1.getUserFraimDirPath)();
+    const installPackage = options.installPackage ?? defaultInstallPackage;
+    const destDir = resolveHubAppCacheDir(version, fraimDir);
+    const entryPath = path_1.default.join(destDir, exports.HUB_APP_ENTRY_RELATIVE);
+    if (isHubAppCacheComplete(destDir, version)) {
+        return entryPath;
+    }
+    const stagingDir = `${destDir}.staging-${process.pid}`;
+    fs_1.default.mkdirSync(path_1.default.dirname(destDir), { recursive: true });
+    fs_1.default.rmSync(stagingDir, { recursive: true, force: true });
+    try {
+        await installPackage(version, stagingDir);
+        // Written only on success, after the installer's own work, so a throw never leaves a staging
+        // tree that could be mistaken for complete.
+        fs_1.default.writeFileSync(path_1.default.join(stagingDir, 'version'), version, 'utf8');
+        if (!isHubAppCacheComplete(stagingDir, version)) {
+            throw new Error(`materialized ${exports.HUB_APP_PACKAGE_NAME}@${version} is missing ${exports.HUB_APP_ENTRY_RELATIVE}; refusing to promote an incomplete install`);
+        }
+        // A concurrent launch may have finished materializing the same version already; the winner
+        // keeps its copy rather than being clobbered by this one (mirrors electron-dist.ts).
+        if (!isHubAppCacheComplete(destDir, version)) {
+            fs_1.default.rmSync(destDir, { recursive: true, force: true });
+            try {
+                fs_1.default.renameSync(stagingDir, destDir);
+            }
+            catch (error) {
+                if (!isHubAppCacheComplete(destDir, version))
+                    throw error;
+            }
+        }
+    }
+    finally {
+        fs_1.default.rmSync(stagingDir, { recursive: true, force: true });
+    }
+    return entryPath;
+}
+/**
+ * Resolve which `desktop-main.js` to run: the latest published version, materializing it first if
+ * needed, or the bundled build when npm is unreachable, already current, or materialization fails
+ * for any reason. A materialization failure must never block a launch — it always falls back to
+ * the bundled copy rather than propagating.
+ */
+async function resolveHubAppEntry(options) {
+    const fraimDir = options.fraimDir ?? (0, project_fraim_paths_1.getUserFraimDirPath)();
+    const getLatest = options.getLatestPublishedVersion ?? hub_latest_version_1.getLatestPublishedVersion;
+    const cachedVersions = listCachedHubAppVersions(fraimDir);
+    let latestPublishedVersion;
+    try {
+        latestPublishedVersion = await getLatest();
+    }
+    catch {
+        latestPublishedVersion = null;
+    }
+    const plan = planHubAppMaterialization({
+        bundledVersion: options.bundledVersion,
+        latestPublishedVersion,
+        cachedVersions,
+    });
+    if (plan.action === 'use-bundled') {
+        return { entryPath: options.bundledEntryPath, source: 'bundled', version: plan.version };
+    }
+    if (plan.action === 'use-cached') {
+        return {
+            entryPath: path_1.default.join(resolveHubAppCacheDir(plan.version, fraimDir), exports.HUB_APP_ENTRY_RELATIVE),
+            source: 'cached',
+            version: plan.version,
+        };
+    }
+    try {
+        options.onProgress?.(`Fetching FRAIM Hub ${plan.version}...`);
+        const entryPath = await ensureMaterializedHubApp(plan.version, { fraimDir, installPackage: options.installPackage });
+        return { entryPath, source: 'cached', version: plan.version };
+    }
+    catch {
+        return { entryPath: options.bundledEntryPath, source: 'bundled', version: options.bundledVersion };
+    }
+}

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

@@ -6332,14 +6332,10 @@ class AiHubServer {
                     messages: persistedConversation ? persistedMessagesForRun(persistedConversation) : [],
                     events: resumeEvents,
                     eventLogRefs: persistedConversation?.eventLogRefs || [],
-                    // Issue #1373: a conversation is permanently scoped to one job for its
-                    // lifetime, including after that job's conversation is marked
-                    // 'completed' — a coaching turn sent to a Done job resumes the SAME
-                    // job's phase history, it does not start unrelated new work. Always
-                    // carry the persisted run projection forward regardless of the
-                    // conversation's prior status. If the resumed session genuinely has
-                    // nothing left to do, it simply reaches the same completed state
-                    // again on its own the next time seekMentoring reports its phase.
+                    // A manager can issue new instructions after a job was marked done.
+                    // That correction stays in the same conversation/job identity and keeps
+                    // its phase history so the tracker can show the job moving back to an
+                    // earlier phase instead of pretending this is unrelated fresh work.
                     currentPhase: persistedRun?.currentPhase || null,
                     phaseHistory: persistedRun?.phaseHistory || [],
                     phaseVisits: persistedRun?.phaseVisits || [],