fraim-hub 2.0.290 → 2.0.291

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

@@ -46,15 +46,10 @@ const git_utils_1 = require("../core/utils/git-utils");
 const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
 const fs_1 = __importDefault(require("fs"));
-const net_1 = __importDefault(require("net"));
-const http_1 = __importDefault(require("http"));
-const tree_kill_1 = __importDefault(require("tree-kill"));
-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");
 const electron_dist_1 = require("./electron-dist");
-const process_liveness_1 = require("./process-liveness");
+const hub_instance_reconciliation_1 = require("./hub-instance-reconciliation");
 function resolveDesktopEntry() {
     const candidates = [
         path_1.default.resolve(__dirname, 'desktop-main.js'),
@@ -113,96 +108,6 @@ function openBrowser(url) {
     const child = (0, child_process_1.spawn)('xdg-open', [url], { detached: true, stdio: 'ignore' });
     child.unref();
 }
-function killPid(pid) {
-    try {
-        if (process.platform === 'win32') {
-            // /T kills the entire process tree; /F forces termination without prompting.
-            (0, child_process_1.execFileSync)('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore' });
-        }
-        else {
-            // tree-kill sends SIGTERM to the process group so child Electron helper processes
-            // are also terminated, not just the root node process (#921).
-            (0, tree_kill_1.default)(pid, 'SIGTERM');
-        }
-    }
-    catch {
-        /* already gone */
-    }
-}
-// #921: after killing the registered pid, probe ports 43091-43200 for any Hub HTTP
-// response. Any Hub found on those ports that is NOT the already-killed pid is an
-// orphan (e.g. an older version started via bare `npx` that never wrote hub-runtime.json).
-// GET /api/ai-hub/pid identifies the pid; we then kill it and wait for its port to free.
-async function fetchHubPid(port) {
-    return new Promise((resolve) => {
-        const req = http_1.default.get({ host: '127.0.0.1', port, path: '/api/ai-hub/pid', timeout: 1000 }, (res) => {
-            if (res.statusCode !== 200) {
-                res.resume();
-                return resolve(null);
-            }
-            let body = '';
-            res.on('data', (c) => { body += c; });
-            res.on('end', () => { try {
-                resolve(JSON.parse(body).pid ?? null);
-            }
-            catch {
-                resolve(null);
-            } });
-        });
-        req.on('error', () => resolve(null));
-        req.on('timeout', () => { req.destroy(); resolve(null); });
-    });
-}
-async function scanAndKillOrphanHubs(excludePid) {
-    const HUB_PORT_SCAN_START = 43091;
-    const HUB_PORT_SCAN_END = 43200;
-    for (let port = HUB_PORT_SCAN_START; port <= HUB_PORT_SCAN_END; port++) {
-        const version = await fetchRunningHubVersion(port);
-        if (!version)
-            continue; // port not a Hub
-        const pid = await fetchHubPid(port);
-        if (pid === null || pid === excludePid)
-            continue; // same process we already killed
-        console.log(`Killing orphan Hub (pid ${pid}) on port ${port}`);
-        killPid(pid);
-        await waitForPortFree(port);
-    }
-}
-function isPortFree(port, timeoutMs = 500) {
-    return new Promise((resolve) => {
-        const sock = net_1.default.connect({ host: '127.0.0.1', port }, () => { sock.destroy(); resolve(false); });
-        sock.on('error', () => resolve(true));
-        sock.setTimeout(timeoutMs, () => { sock.destroy(); resolve(true); });
-    });
-}
-async function waitForPortFree(port, totalMs = 5000) {
-    const start = Date.now();
-    while (Date.now() - start < totalMs) {
-        if (await isPortFree(port))
-            return;
-        await new Promise((r) => setTimeout(r, 200));
-    }
-}
-function fetchRunningHubVersion(port) {
-    return new Promise((resolve) => {
-        const req = http_1.default.get({ host: '127.0.0.1', port, path: '/api/ai-hub/version', timeout: 1000 }, (res) => {
-            if (res.statusCode !== 200) {
-                res.resume();
-                return resolve(null);
-            }
-            let body = '';
-            res.on('data', (c) => { body += c; });
-            res.on('end', () => { try {
-                resolve(JSON.parse(body).version ?? null);
-            }
-            catch {
-                resolve(null);
-            } });
-        });
-        req.on('error', () => resolve(null));
-        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
@@ -278,7 +183,7 @@ async function waitForDesktopHubReady(child, preferredPort, options = {}) {
     while (Date.now() - start < timeoutMs) {
         failIfChildDied();
         for (const port of readinessProbePorts(fraimDir, runtimeId, preferredPort)) {
-            const version = await fetchRunningHubVersion(port);
+            const version = await (0, hub_instance_reconciliation_1.fetchRunningHubVersion)(port);
             if (version) {
                 return { port, version };
             }
@@ -298,32 +203,6 @@ async function waitForDesktopHubReady(child, preferredPort, options = {}) {
         + `${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 && (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,
-        pidAlive: live,
-        cliVersion: (0, version_utils_1.getFraimVersion)(),
-        restart: flags.restart,
-        noRestart: flags.keepRunning,
-    });
-    if (decision.action === 'replace' && effective) {
-        console.log(`Replacing running Hub (v${effective.version}, pid ${effective.pid}) - ${decision.reason}`);
-        killPid(effective.pid);
-        await waitForPortFree(effective.port);
-        // #921: after killing the registered pid, scan for orphan Hub processes that were
-        // never registered in hub-runtime.json (e.g. older versions started via bare npx).
-        if (runtimeId === 'hub') {
-            await scanAndKillOrphanHubs(effective.pid);
-        }
-    }
-    else if (decision.action === 'focus-existing' && effective) {
-        console.log(`A Hub (v${effective.version}) is already running - focusing it. Use --restart to replace it.`);
-    }
-}
 async function runHub(options) {
     const { AiHubServer, findAvailablePort } = await Promise.resolve().then(() => __importStar(require('./server')));
     const preferredPort = options.port || (0, git_utils_1.getPort)() + 100;
@@ -332,7 +211,7 @@ async function runHub(options) {
     if (options.open) {
         const wantDesktop = !options.browser;
         if (wantDesktop) {
-            await reconcileRunningHub({ restart: !!options.restart, keepRunning: !!options.keepRunning }, runtimeId);
+            await (0, hub_instance_reconciliation_1.reconcileRunningHub)({ restart: !!options.restart, keepRunning: !!options.keepRunning }, runtimeId);
         }
         const desktopChild = wantDesktop ? await openDesktopWindow(projectPath, preferredPort, runtimeId) : null;
         if (!desktopChild) {

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

@@ -22,6 +22,7 @@ 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");
+const hub_instance_reconciliation_1 = require("./hub-instance-reconciliation");
 // 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');
@@ -135,28 +136,54 @@ async function configureAutoUpdater() {
     });
     return result.action === 'installing';
 }
+// Issue #1415: shared by every path that needs to know "is a newer FRAIM Hub published than the
+// one currently running" — the automatic second-instance/activate recheck below, and the
+// manually-triggered restart from the web UI's update badge (see restartToLatestNow). Compares
+// `getFraimVersion()` (not `app.getVersion()`), 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 resolveLatestHubAppVersion() {
+    const runningVersion = (0, version_utils_1.getFraimVersion)();
+    const resolved = await (0, hub_app_materializer_1.resolveHubAppEntry)({
+        bundledVersion: runningVersion,
+        bundledEntryPath: __filename,
+    });
+    return { upgradable: resolved.version !== runningVersion, latest: resolved.version };
+}
 // 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.
+// signal #1415 was filed about.
 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)
+    const { upgradable, latest } = await resolveLatestHubAppVersion();
+    if (!upgradable)
         return false;
-    console.log(`[fraim] newer FRAIM Hub ${resolved.version} available (was running ${runningVersion}); restarting to apply it`);
+    console.log(`[fraim] newer FRAIM Hub ${latest} available (was running ${(0, version_utils_1.getFraimVersion)()}); restarting to apply it`);
     electron_1.app.relaunch();
     electron_1.app.quit();
     return true;
 }
+// Issue #1415: the web UI's persistent update badge (#1379) used to just tell the user to quit
+// and relaunch by hand. This is the same "resolve latest, relaunch" as the automatic checks above,
+// just triggered by an explicit click instead of a relaunch-shaped Electron event — wired into
+// AiHubServer as the `restartToLatest` option (see launchDesktopShell) so POST
+// /api/ai-hub/restart-to-latest can call it. The relaunch/quit is deferred a beat so the HTTP
+// response reaches the browser (which uses it to start polling for the new instance) before this
+// process starts tearing down.
+async function restartToLatestNow() {
+    const { upgradable, latest } = await resolveLatestHubAppVersion();
+    if (!upgradable)
+        return { restarting: false, latest };
+    console.log(`[fraim] manual restart requested; relaunching to FRAIM Hub ${latest}`);
+    setTimeout(() => {
+        electron_1.app.relaunch();
+        electron_1.app.quit();
+    }, 300);
+    return { restarting: true, latest };
+}
 // 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).
@@ -434,6 +461,7 @@ async function launchDesktopShell(options) {
             });
             return result.canceled || result.filePaths.length === 0 ? null : result.filePaths[0];
         },
+        restartToLatest: restartToLatestNow,
     });
     await server.start(httpPort);
     const resolvedProjectPath = server.getProjectPath();
@@ -525,6 +553,25 @@ async function bootstrap() {
     await electron_1.app.whenReady();
     electron_1.app.setName(displayName(options.runtimeId));
     configurePackagedFraimRuntime();
+    // Issue #1415 (follow-up): app.requestSingleInstanceLock() above only sees another instance of
+    // *this same identity* — it cannot see a Hub already running via a different launch path (e.g.
+    // `npx fraim-hub`'s raw electron.exe, confirmed live to end up under a different userData scope
+    // than this packaged app). hub-runtime.json is the identity-agnostic record both launch paths
+    // already write (#755); reconcile against it — and sweep for unregistered orphans (#921) —
+    // before binding our own port, so a direct double-click launch takes over whatever Hub is
+    // already running instead of silently opening a second, independent one on a fallback port.
+    // `restart: true` because a materialized/bundled launch is by construction already resolved to
+    // the current latest — there is nothing to compare, only to replace. Runs after whenReady, like
+    // every other network-touching step in this function (checkForRelaunchAttemptUpdate,
+    // configureAutoUpdater) — reconcileRunningHub makes real HTTP probes and process kills, and this
+    // keeps it on the same footing as those instead of racing Electron's own startup.
+    // Gated on the same FRAIM_AI_HUB_FAKE_HOST flag as the single-instance lock above, not on
+    // FRAIM_INSTALLER_LIFECYCLE_TEST: the orphan sweep probes real system ports 43091-43200
+    // regardless of FRAIM_USER_DIR isolation, so a test double (FAKE_HOST=1) skips it for the same
+    // reason it skips the lock — it must never disturb a real Hub already running on this machine.
+    if (!skipSingleInstance) {
+        await (0, hub_instance_reconciliation_1.reconcileRunningHub)({ restart: true, keepRunning: false }, options.runtimeId);
+    }
     // macOS reads the dock icon from the app bundle once packaged, but an
     // unpackaged `npm run hub:desktop` / `npx fraim-hub` run shows Electron's
     // own icon there unless we set it explicitly (#1329).

package/dist/src/ai-hub/hub-instance-reconciliation.js

@@ -0,0 +1,156 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.killPid = killPid;
+exports.isPortFree = isPortFree;
+exports.waitForPortFree = waitForPortFree;
+exports.fetchRunningHubVersion = fetchRunningHubVersion;
+exports.fetchHubPid = fetchHubPid;
+exports.scanAndKillOrphanHubs = scanAndKillOrphanHubs;
+exports.reconcileRunningHub = reconcileRunningHub;
+// Issue #755/#921: kill-and-take-over an already-running Hub, identified through the shared,
+// identity-agnostic ~/.fraim/hub-runtime.json + a port scan - never through OS-level process
+// identity (Electron's app.requestSingleInstanceLock() included). That distinction matters: a
+// Hub can be running via `npx fraim-hub`'s raw electron.exe (a different userData scope than the
+// packaged, branded app) or a bare-npx build that never wrote hub-runtime.json at all, and this
+// module is what makes "only one Hub, and it's the one that just launched" true regardless of
+// which of those started the one already running.
+//
+// Originally only exercised by the CLI (`fraim hub`, see cli.ts) before it spawns its own desktop
+// shell. Issue #1415 follow-up: the packaged desktop app's own bootstrap (desktop-main.ts) never
+// called any of this when launched directly (double-click / Windows shortcut, no CLI in front of
+// it) - confirmed live: a Hub already running via `npx fraim-hub` kept its default ports while a
+// freshly installed packaged build silently fell back to the next free ports and came up as an
+// independent second Hub instead of replacing it. Both launch paths now share this module so
+// there is exactly one implementation of "is a Hub already running, and if so, replace it."
+const child_process_1 = require("child_process");
+const net_1 = __importDefault(require("net"));
+const http_1 = __importDefault(require("http"));
+const tree_kill_1 = __importDefault(require("tree-kill"));
+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");
+const process_liveness_1 = require("./process-liveness");
+function killPid(pid) {
+    try {
+        if (process.platform === 'win32') {
+            // /T kills the entire process tree; /F forces termination without prompting.
+            (0, child_process_1.execFileSync)('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore' });
+        }
+        else {
+            // tree-kill sends SIGTERM to the process group so child Electron helper processes
+            // are also terminated, not just the root node process (#921).
+            (0, tree_kill_1.default)(pid, 'SIGTERM');
+        }
+    }
+    catch {
+        /* already gone */
+    }
+}
+function isPortFree(port, timeoutMs = 500) {
+    return new Promise((resolve) => {
+        const sock = net_1.default.connect({ host: '127.0.0.1', port }, () => { sock.destroy(); resolve(false); });
+        sock.on('error', () => resolve(true));
+        sock.setTimeout(timeoutMs, () => { sock.destroy(); resolve(true); });
+    });
+}
+async function waitForPortFree(port, totalMs = 5000) {
+    const start = Date.now();
+    while (Date.now() - start < totalMs) {
+        if (await isPortFree(port))
+            return;
+        await new Promise((r) => setTimeout(r, 200));
+    }
+}
+function fetchRunningHubVersion(port) {
+    return new Promise((resolve) => {
+        const req = http_1.default.get({ host: '127.0.0.1', port, path: '/api/ai-hub/version', timeout: 1000 }, (res) => {
+            if (res.statusCode !== 200) {
+                res.resume();
+                return resolve(null);
+            }
+            let body = '';
+            res.on('data', (c) => { body += c; });
+            res.on('end', () => { try {
+                resolve(JSON.parse(body).version ?? null);
+            }
+            catch {
+                resolve(null);
+            } });
+        });
+        req.on('error', () => resolve(null));
+        req.on('timeout', () => { req.destroy(); resolve(null); });
+    });
+}
+// #921: after killing the registered pid, probe ports 43091-43200 for any Hub HTTP
+// response. Any Hub found on those ports that is NOT the already-killed pid is an
+// orphan (e.g. an older version started via bare `npx` that never wrote hub-runtime.json).
+// GET /api/ai-hub/pid identifies the pid; we then kill it and wait for its port to free.
+function fetchHubPid(port) {
+    return new Promise((resolve) => {
+        const req = http_1.default.get({ host: '127.0.0.1', port, path: '/api/ai-hub/pid', timeout: 1000 }, (res) => {
+            if (res.statusCode !== 200) {
+                res.resume();
+                return resolve(null);
+            }
+            let body = '';
+            res.on('data', (c) => { body += c; });
+            res.on('end', () => { try {
+                resolve(JSON.parse(body).pid ?? null);
+            }
+            catch {
+                resolve(null);
+            } });
+        });
+        req.on('error', () => resolve(null));
+        req.on('timeout', () => { req.destroy(); resolve(null); });
+    });
+}
+async function scanAndKillOrphanHubs(excludePid) {
+    const HUB_PORT_SCAN_START = 43091;
+    const HUB_PORT_SCAN_END = 43200;
+    for (let port = HUB_PORT_SCAN_START; port <= HUB_PORT_SCAN_END; port++) {
+        const version = await fetchRunningHubVersion(port);
+        if (!version)
+            continue; // port not a Hub
+        const pid = await fetchHubPid(port);
+        if (pid === null || pid === excludePid)
+            continue; // same process we already killed
+        console.log(`Killing orphan Hub (pid ${pid}) on port ${port}`);
+        killPid(pid);
+        await waitForPortFree(port);
+    }
+}
+// The one entry point both launch paths call before starting their own server: reads
+// hub-runtime.json for `runtimeId`, confirms the recorded pid is actually alive and answering
+// (not just present in a stale file), and - when the decision is `replace` - kills it, waits for
+// its port to free, then sweeps for any unregistered orphan on the standard Hub port range.
+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 && (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,
+        pidAlive: live,
+        cliVersion: (0, version_utils_1.getFraimVersion)(),
+        restart: flags.restart,
+        noRestart: flags.keepRunning,
+    });
+    if (decision.action === 'replace' && effective) {
+        console.log(`Replacing running Hub (v${effective.version}, pid ${effective.pid}) - ${decision.reason}`);
+        killPid(effective.pid);
+        await waitForPortFree(effective.port);
+        // #921: after killing the registered pid, scan for orphan Hub processes that were
+        // never registered in hub-runtime.json (e.g. older versions started via bare npx).
+        if (runtimeId === 'hub') {
+            await scanAndKillOrphanHubs(effective.pid);
+        }
+    }
+    else if (decision.action === 'focus-existing' && effective) {
+        console.log(`A Hub (v${effective.version}) is already running - focusing it. Use --restart to replace it.`);
+    }
+}

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

@@ -2201,6 +2201,31 @@ function buildHubBackgroundTaskContinueMessage(run) {
         'If results are not yet available, wait briefly or check again. Once you have the results, continue with your original plan.',
     ].join('\n');
 }
+// #1419 (Change 3): auto-resume when the only unresolved condition is a
+// KILLED background task (see hasKilledBackgroundTask) — distinct from
+// buildHubBackgroundTaskContinueMessage above, which resumes a still-ACTIVE
+// resumable task. recoveryAttempts is NOT incremented — same budget-preserving
+// semantics as #1275's background_task resume.
+function createHubBackgroundTaskLostContinueEvent(run) {
+    return (0, hosts_1.createHubEvent)('system', `Hub background-task-lost continuation for run ${run.id} session ${run.sessionId || 'unknown'} — a background task was killed before its work finished.${hostErrorSuffix(run)}`);
+}
+// `killedDescription` must be captured at classification time (classifyExit's
+// systemNote) rather than recomputed here: handleRunExit's resume path calls
+// clearBackgroundTaskLifecycle before this message is built (the setTimeout'd
+// continue), which wipes run.hostLifecycle.backgroundTasks. Recomputing from
+// the live run at that point would always fall back to the generic
+// 'a background task' description.
+function buildHubBackgroundTaskLostContinueMessage(run, killedDescription) {
+    return [
+        '[FRAIM Hub system recovery]',
+        'This is not a manager-authored instruction. Do not say the manager asked you to continue.',
+        `Run id: ${run.id}`,
+        `Session id: ${run.sessionId || 'unknown'}`,
+        `A background task was killed when a turn ended before it reached a terminal state: ${killedDescription || describeKilledBackgroundTasks(run)}.`,
+        'Its result is unknown, not passing or failing.',
+        'Check for partial output first; if none exists, re-run the work and say plainly that this is a re-run because the prior attempt\'s result was never observed.',
+    ].join('\n');
+}
 function isHumanActionGate(run) {
     if (run.stoppedByUser)
         return true;
@@ -2248,19 +2273,31 @@ function hasActiveResumableBackgroundTask(run) {
     return Object.values(tasks).some((task) => task.status === 'active' && isResumableBackgroundTaskType(task.taskType));
 }
 // Issue #1234: true when the host reported a background task as active
-// (`background_tasks_changed`) and it either never resolved before the host's
-// child process exited, or resolved as `killed` rather than `completed`. Both
-// are evidence the agent's promised follow-up did not happen.
+// (`background_tasks_changed`) and it never resolved before the host's child
+// process exited — a still-running, non-resumable task is a worse signal
+// than a cleanly killed one (it is "unexpectedly still running", not
+// "definitely gone") and must keep hard-erroring rather than auto-resuming.
 // #1275: tightened — local_bash active tasks are handled by hasActiveResumableBackgroundTask above.
-// #1355: the same predicate decides both sides, so an untyped active task cannot be
-// simultaneously non-resumable here and non-local_bash there. A killed task is
-// unresolved regardless of its type — that clause is independent of taskType.
-function hasUnresolvedBackgroundTask(run) {
+// #1419: split out of the old hasUnresolvedBackgroundTask so a killed task can be
+// classified separately (see hasKilledBackgroundTask) — Change 3's fix is to the
+// classification's *action* for the killed case, not to detection, which already
+// fired correctly for both cases.
+function hasActiveNonResumableBackgroundTask(run) {
     const tasks = run.hostLifecycle?.backgroundTasks;
     if (!tasks)
         return false;
-    return Object.values(tasks).some((task) => (task.status === 'active' && !isResumableBackgroundTaskType(task.taskType)) ||
-        task.status === 'killed');
+    return Object.values(tasks).some((task) => task.status === 'active' && !isResumableBackgroundTaskType(task.taskType));
+}
+// #1419: true when the host reported a background task that resolved as
+// `killed` rather than `completed` — evidence the agent's (or its subagent's)
+// promised follow-up did not happen, but the work is definitively gone rather
+// than still running. Independent of taskType: a killed task is killed
+// regardless of what type the host labelled it.
+function hasKilledBackgroundTask(run) {
+    const tasks = run.hostLifecycle?.backgroundTasks;
+    if (!tasks)
+        return false;
+    return Object.values(tasks).some((task) => task.status === 'killed');
 }
 function describeUnresolvedBackgroundTasks(run) {
     const descriptions = Object.values(run.hostLifecycle?.backgroundTasks || {})
@@ -2270,6 +2307,15 @@ function describeUnresolvedBackgroundTasks(run) {
     return `The host ended this turn while ${list} was still active, and it was killed or never confirmed complete. `
         + `The agent's promised follow-up did not happen; review the conversation before continuing.`;
 }
+// #1419: names the specific killed task(s) so the auto-resume continuation
+// message (buildHubBackgroundTaskLostContinueMessage) can be concrete about
+// what was lost, same spirit as describeUnresolvedBackgroundTasks above.
+function describeKilledBackgroundTasks(run) {
+    const descriptions = Object.values(run.hostLifecycle?.backgroundTasks || {})
+        .filter((task) => task.status === 'killed')
+        .map((task) => task.description || 'a background task');
+    return descriptions.length > 0 ? descriptions.join('; ') : 'a background task';
+}
 function classifyExit(run, exitCode) {
     if (run.stoppedByUser) {
         return { action: 'park', pauseReason: 'stopped' };
@@ -2321,26 +2367,50 @@ function classifyExit(run, exitCode) {
             if (hasActiveResumableBackgroundTask(run)) {
                 return { action: 'resume', pauseReason: 'working', recoveryKind: 'background_task' };
             }
-            if (hasUnresolvedBackgroundTask(run)) {
+            // #1419 (Change 3): an unexpectedly-still-running non-resumable task is a
+            // worse signal than a cleanly killed one — keep hard-erroring for it.
+            if (hasActiveNonResumableBackgroundTask(run)) {
                 return { action: 'error', pauseReason: 'error', systemNote: describeUnresolvedBackgroundTasks(run) };
             }
+            // When the ONLY unresolved condition is a killed task, the work is
+            // definitely gone rather than still running: auto-resume once with an
+            // evidence-honest continuation instead of forcing the manager to say
+            // "continue" with no evidence of what was lost.
+            if (hasKilledBackgroundTask(run)) {
+                // systemNote computed now, before clearBackgroundTaskLifecycle wipes
+                // the task map in handleRunExit — the continuation message needs the
+                // real description, not the post-clear fallback.
+                return { action: 'resume', pauseReason: 'working', recoveryKind: 'background_task_lost', systemNote: describeKilledBackgroundTasks(run) };
+            }
             return { action: 'park', pauseReason: 'awaiting_user' };
         }
         if (compactingActive) {
             return { action: 'resume', pauseReason: 'working', recoveryKind: 'compaction' };
         }
-        if (hasUnresolvedBackgroundTask(run)) {
+        if (hasActiveNonResumableBackgroundTask(run)) {
             return { action: 'error', pauseReason: 'error', systemNote: describeUnresolvedBackgroundTasks(run) };
         }
+        if (hasKilledBackgroundTask(run)) {
+            // systemNote computed now, before clearBackgroundTaskLifecycle wipes
+            // the task map in handleRunExit — the continuation message needs the
+            // real description, not the post-clear fallback.
+            return { action: 'resume', pauseReason: 'working', recoveryKind: 'background_task_lost', systemNote: describeKilledBackgroundTasks(run) };
+        }
         // Phase mid-flight (started but not completed/incomplete): conservative park.
         return { action: 'park', pauseReason: 'awaiting_user' };
     }
     if (compactingActive) {
         return { action: 'resume', pauseReason: 'working', recoveryKind: 'compaction' };
     }
-    if (hasUnresolvedBackgroundTask(run)) {
+    if (hasActiveNonResumableBackgroundTask(run)) {
         return { action: 'error', pauseReason: 'error', systemNote: describeUnresolvedBackgroundTasks(run) };
     }
+    if (hasKilledBackgroundTask(run)) {
+        // systemNote computed now, before clearBackgroundTaskLifecycle wipes the
+        // task map in handleRunExit — the continuation message needs the real
+        // description, not the post-clear fallback.
+        return { action: 'resume', pauseReason: 'working', recoveryKind: 'background_task_lost', systemNote: describeKilledBackgroundTasks(run) };
+    }
     // Signal-less non-FRAIM run: conservative park.
     return { action: 'park', pauseReason: 'awaiting_user' };
 }
@@ -2478,6 +2548,7 @@ class AiHubServer {
         this.configuredAgentStore = options.configuredAgentStore || new configured_agents_1.AiHubConfiguredAgentStore();
         this.wordTaskpaneDir = options.wordTaskpaneDir ?? resolveWordTaskpaneDir(this.projectPath);
         this.folderPicker = options.folderPicker ?? pickProjectPath;
+        this.restartToLatest = options.restartToLatest ?? (async () => ({ restarting: false }));
         this.httpsPort = options.httpsPort;
         this.certBundle = options.certBundle;
         this.hubUiCacheDir = options.hubUiCacheDir || process.env.FRAIM_HUB_UI_CACHE_DIR || (0, ui_cache_1.defaultHubUiCacheDir)();
@@ -5381,6 +5452,19 @@ class AiHubServer {
         this.app.get('/api/ai-hub/pid', (_req, res) => {
             return res.json({ pid: process.pid });
         });
+        // Issue #1415/#1379: the update badge's click handler POSTs here instead of just telling the
+        // user to quit and relaunch by hand. `restartToLatest` (the Electron shell's
+        // restartToLatestNow) responds before it actually tears the process down, so the client can
+        // rely on this response arriving and then poll /api/ai-hub/version for the new instance.
+        this.app.post('/api/ai-hub/restart-to-latest', async (_req, res) => {
+            try {
+                const result = await this.restartToLatest();
+                return res.json(result);
+            }
+            catch (error) {
+                return res.status(500).json({ error: error instanceof Error ? error.message : 'Could not restart to the latest version.' });
+            }
+        });
         this.app.post('/api/ai-hub/project-path/pick', async (_req, res) => {
             try {
                 const projectPath = await this.folderPicker();
@@ -7407,9 +7491,11 @@ class AiHubServer {
             // entries from the dead Claude Code process don't re-trigger hasActiveResumableBackgroundTask
             // on the next exit, causing an infinite loop.
             this.runRegistry.update(runId, (current) => {
-                if (classification.recoveryKind === 'background_task') {
+                if (classification.recoveryKind === 'background_task' || classification.recoveryKind === 'background_task_lost') {
                     clearBackgroundTaskLifecycle(current);
-                    current.events.push(createHubBackgroundTaskContinueEvent(current));
+                    current.events.push(classification.recoveryKind === 'background_task'
+                        ? createHubBackgroundTaskContinueEvent(current)
+                        : createHubBackgroundTaskLostContinueEvent(current));
                 }
                 else {
                     current.recoveryAttempts = (current.recoveryAttempts ?? 0) + 1;
@@ -7444,7 +7530,9 @@ class AiHubServer {
                     ? buildHubCompactionRecoveryContinueMessage(current, exitCode, attempt)
                     : classification.recoveryKind === 'background_task'
                         ? buildHubBackgroundTaskContinueMessage(current)
-                        : buildHubRecoveryContinueMessage(current, exitCode, attempt);
+                        : classification.recoveryKind === 'background_task_lost'
+                            ? buildHubBackgroundTaskLostContinueMessage(current, classification.systemNote)
+                            : buildHubRecoveryContinueMessage(current, exitCode, attempt);
                 // Issue #1150: recovery must relaunch as the SAME configured agent. Its setup
                 // script supplies the env that selects the profile the host session lives in
                 // (CODEX_HOME for Codex), and resuming without it sends `codex exec resume`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-hub",
-  "version": "2.0.290",
+  "version": "2.0.291",
   "description": "FRAIM Hub local companion package.",
   "author": "Sid Mathur <sid.mathur@gmail.com>",
   "homepage": "https://github.com/mathursrus/FRAIM#readme",
@@ -211,7 +211,7 @@
     "electron-updater": "^6.8.9",
     "express": "^5.2.1",
     "extract-zip": "^2.0.1",
-    "fraim": "2.0.290",
+    "fraim": "2.0.291",
     "mongodb": "^7.0.0",
     "node-cron": "4.2.1",
     "node-edge-tts": "^1.2.10",

package/public/ai-hub/script.js

@@ -16078,11 +16078,12 @@ function tfWireShell() {
   }
   const avatar = document.getElementById('avatar-btn');
   if (avatar) avatar.addEventListener('click', tfToggleAccountMenu);
-  // #1379: clicking the top-bar badge opens the same account menu that already carries
-  // the full update-available detail, rather than duplicating that content into a
-  // second popover.
+  // Issue #1415: clicking the top-bar badge now restarts the Hub straight into the latest
+  // published version (the same "resolve latest, relaunch" the desktop shell already does on
+  // every second-instance/activate attempt) instead of opening the account menu to read
+  // instructions for quitting and relaunching by hand.
   const updateBadge = document.getElementById('hub-update-badge');
-  if (updateBadge) updateBadge.addEventListener('click', tfToggleAccountMenu);
+  if (updateBadge) updateBadge.addEventListener('click', tfRestartHubToLatest);
   tfWireThemeToggle();
   const accountItem = document.getElementById('am-account');
   if (accountItem) accountItem.addEventListener('click', (e) => {
@@ -16334,6 +16335,60 @@ function tfPopulateVersionInfo() {
     .catch(() => { /* offline / best-effort: leave both surfaces hidden */ });
 }
 
+// Issue #1415: the update badge used to only tell the user to quit and relaunch by hand
+// (#1379). This resolves latest npm-published FRAIM Hub and relaunches into it directly - the
+// desktop shell responds to the POST before it actually tears itself down (see
+// restartToLatestNow in desktop-main.ts), so the ack below is reliable; the reload then waits
+// for the *new* instance specifically (matching `latest`), not just any response, so it never
+// reloads against the old process mid-shutdown.
+function tfRestartHubToLatest(event) {
+  if (event) event.preventDefault();
+  const badgeEl = document.getElementById('hub-update-badge');
+  if (badgeEl) {
+    badgeEl.disabled = true;
+    badgeEl.textContent = '⬆️ Restarting…';
+  }
+  fetch('/api/ai-hub/restart-to-latest', { method: 'POST' })
+    .then((r) => (r.ok ? r.json() : Promise.reject(new Error(`status ${r.status}`))))
+    .then((info) => {
+      if (info && info.restarting) {
+        tfPollForHubRestart(info.latest || null, 0);
+      } else if (badgeEl) {
+        badgeEl.disabled = false;
+        badgeEl.textContent = '⬆️ Updates available';
+      }
+    })
+    .catch(() => {
+      if (badgeEl) {
+        badgeEl.disabled = false;
+        badgeEl.textContent = '⬆️ Updates available';
+      }
+    });
+}
+
+const HUB_RESTART_POLL_MS = 1000;
+const HUB_RESTART_POLL_MAX_ATTEMPTS = 45; // ~45s: generous for a fresh materialize-from-npm relaunch
+
+function tfPollForHubRestart(targetVersion, attempt) {
+  if (attempt >= HUB_RESTART_POLL_MAX_ATTEMPTS) {
+    window.location.reload();
+    return;
+  }
+  setTimeout(() => {
+    fetch('/api/ai-hub/version')
+      .then((r) => (r.ok ? r.json() : Promise.reject(new Error(`status ${r.status}`))))
+      .then((info) => {
+        // No target to match (best-effort) or the new instance is the one now answering.
+        if (!targetVersion || (info && info.version === targetVersion)) {
+          window.location.reload();
+        } else {
+          tfPollForHubRestart(targetVersion, attempt + 1);
+        }
+      })
+      .catch(() => tfPollForHubRestart(targetVersion, attempt + 1));
+  }, HUB_RESTART_POLL_MS);
+}
+
 function tfRequestedConnectedSurface() {
   try {
     const params = new URLSearchParams(window.location.search);

package/public/ai-hub/styles.css

@@ -4494,6 +4494,10 @@ body.hub-shell { display: flex; flex-direction: column; height: 100vh; overflow:
 .hub-update-badge:hover { opacity: .85; box-shadow: 0 2px 8px rgba(0,0,0,.22); }
 .hub-update-badge:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
 .hub-update-badge[hidden] { display: none; }
+/* Issue #1415: while the restart-to-latest request is in flight / the new instance is coming up,
+   the badge shows a live "Restarting…" state rather than the static hover affordance. */
+.hub-update-badge:disabled { cursor: default; opacity: .7; }
+.hub-update-badge:disabled:hover { box-shadow: 0 1px 4px rgba(0,0,0,.18); }
 
 /* Suppress the old Hub's header and rail when inside the workspace-conv */
 .workspace-conv .header { display: none !important; }