fraim-hub 2.0.238 → 2.0.239

package/bin/fraim-hub-2.js

@@ -1,12 +1,12 @@
-#!/usr/bin/env node
-try {
-  const { createFraimHub2Program } = require('../dist/src/cli/fraim-hub-2.js');
-  createFraimHub2Program().parseAsync(process.argv).catch((error) => {
-    console.error(error instanceof Error ? error.message : String(error));
-    process.exit(1);
-  });
-} catch (error) {
-  console.error('Unable to start FRAIM Hub 2. Run npm install -g fraim-hub again to refresh the package.');
-  console.error(error instanceof Error ? error.message : String(error));
-  process.exit(1);
-}
+#!/usr/bin/env node
+try {
+  const { createFraimHub2Program } = require('../dist/src/cli/fraim-hub-2.js');
+  createFraimHub2Program().parseAsync(process.argv).catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+} catch (error) {
+  console.error('Unable to start FRAIM Hub 2. Run npm install -g fraim-hub again to refresh the package.');
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+}

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

@@ -8,6 +8,12 @@ exports.parseSeekMentoringSignal = parseSeekMentoringSignal;
 exports.parseFraimJobLoadSignal = parseFraimJobLoadSignal;
 exports.parseUsageSignal = parseUsageSignal;
 exports.parseAgentIdentitySignal = parseAgentIdentitySignal;
+exports.__setAgentAvailabilityPathForTests = __setAgentAvailabilityPathForTests;
+exports.invalidateEmployeeDetectionCache = invalidateEmployeeDetectionCache;
+exports.__setEmployeeDetectionTtlForTests = __setEmployeeDetectionTtlForTests;
+exports.__getEmployeeProbeRoundsForTests = __getEmployeeProbeRoundsForTests;
+exports.__resetEmployeeProbeRoundsForTests = __resetEmployeeProbeRoundsForTests;
+exports.detectEmployeesAsync = detectEmployeesAsync;
 exports.detectEmployees = detectEmployees;
 exports.prepareCodexBrowserHome = prepareCodexBrowserHome;
 exports.sharedBrowserHostConfig = sharedBrowserHostConfig;
@@ -724,14 +730,246 @@ function resolveHostInvocation(plan) {
         args: ['/d', '/s', '/c', [command, ...args.map(escapeWindowsArg)].join(' ')],
     };
 }
+// Single source for the probe environment, shared by the sync and async probes so the two
+// cannot drift on how the managed-agent bin directories are put on PATH.
+const versionProbeEnv = () => ({
+    ...process.env,
+    PATH: (0, managed_agent_paths_1.buildPathWithManagedAgentBins)(process.env.PATH),
+});
 const availableByVersionProbe = (command) => {
     const invocation = resolveHostInvocation({ command, args: ['--version'] });
     const result = (0, child_process_1.spawnSync)(invocation.command, invocation.args, {
         encoding: 'utf8',
-        env: { ...process.env, PATH: (0, managed_agent_paths_1.buildPathWithManagedAgentBins)(process.env.PATH) },
+        env: versionProbeEnv(),
     });
     return result.status === 0;
 };
+// Issue #1010: the async counterpart of availableByVersionProbe. Same semantics (exit 0
+// from `<agent> --version` means the CLI is installed AND actually runs), but non-blocking
+// so N agents can be probed concurrently without freezing the event loop.
+// Upper bound on a single probe. Bug-bash finding: `spawn`/`spawnSync` here are otherwise
+// unbounded, so one wedged CLI would stall detection forever - and because the first-paint
+// path awaits detection, that would turn the slow first paint this issue is about into an
+// indefinite one. The worst probe observed on a healthy machine is 1419ms (gemini), so 10s
+// is far above any legitimate `--version`. The tradeoff is deliberate: a CLI that cannot
+// print its version within 10s is reported unavailable rather than allowed to hang the Hub.
+// It is recoverable from the UI via the existing per-agent "Check" action.
+const VERSION_PROBE_TIMEOUT_MS = 10_000;
+const availableByVersionProbeAsync = (command) => new Promise((resolve) => {
+    const invocation = resolveHostInvocation({ command, args: ['--version'] });
+    let settled = false;
+    let timer;
+    let child;
+    const finish = (value) => {
+        if (settled)
+            return;
+        settled = true;
+        if (timer)
+            clearTimeout(timer);
+        resolve(value);
+    };
+    try {
+        child = (0, child_process_1.spawn)(invocation.command, invocation.args, {
+            env: versionProbeEnv(),
+            stdio: 'ignore',
+        });
+        timer = setTimeout(() => {
+            console.warn(`[ai-hub] agent version probe timed out after ${VERSION_PROBE_TIMEOUT_MS}ms: ${command}`);
+            try {
+                child?.kill();
+            }
+            catch { /* already gone */ }
+            finish(false);
+        }, VERSION_PROBE_TIMEOUT_MS);
+        // Do not hold the process open just for a probe.
+        timer.unref?.();
+        child.on('error', () => finish(false));
+        child.on('close', (code) => finish(code === 0));
+    }
+    catch {
+        finish(false);
+    }
+});
+// ─── Issue #1010: employee-detection cache ───────────────────────────────────
+//
+// detectEmployees() used to run one blocking spawnSync per agent on EVERY call, and it is
+// called from bootstrapResponse and several routes. Measured 2715ms per call versus 53ms
+// for all of the Hub's own local discovery in the same handler (51x), with gemini (1419ms)
+// and copilot (939ms) dominating. Worse than the latency: spawnSync blocks Node's event
+// loop, so the Hub answered NOTHING while probing. A trivial 3ms endpoint measured 3043ms
+// when it happened to land during a bootstrap.
+//
+// "Which CLIs are installed on this machine" does not change between requests, so it is
+// cached. The TTL is a safety net for a CLI installed outside the Hub; installs performed
+// THROUGH the Hub invalidate explicitly (see the install-agent route) so they appear at once.
+const EMPLOYEE_DETECTION_TTL_MS = 5 * 60 * 1000;
+let employeeDetectionTtlMs = EMPLOYEE_DETECTION_TTL_MS;
+let cachedEmployees = null;
+let cachedEmployeesAtMs = 0;
+let inFlightDetection = null;
+function cachedEmployeesIfFresh() {
+    if (!cachedEmployees)
+        return null;
+    if (Date.now() - cachedEmployeesAtMs > employeeDetectionTtlMs)
+        return null;
+    return cachedEmployees;
+}
+// ─── Persisted last-known availability ───────────────────────────────────────
+//
+// An in-memory cache alone does not make the FIRST paint fast: after a Hub restart the
+// cache is empty, so the first bootstrap pays the full probe. Measured, the parallel probe
+// takes a consistent ~2.2s, and a headless browser hitting a freshly started server beat
+// startup priming and paid 2529ms - i.e. whether first paint is fast came down to a race
+// between Electron boot and priming. That is not a guarantee.
+//
+// Agent availability changes rarely (installing a CLI is a deliberate act), so the last
+// known answer is persisted and served immediately on the next start. Startup priming then
+// force-refreshes in the background.
+//
+// Tradeoff, deliberate: immediately after uninstalling a CLI outside the Hub, the first
+// paint can briefly show it as available until the background refresh lands (~2.2s) or the
+// TTL lapses. That is recoverable and self-correcting, and is preferable to freezing every
+// cold start for 2.2s. Installs performed THROUGH the Hub invalidate explicitly.
+const AGENT_AVAILABILITY_FILE = 'hub-agent-availability.json';
+// Overridable so tests do not mutate the developer's real ~/.fraim state. These guards run
+// in the smoke suite now, and invalidation DELETES this file, so pointing them at a temp
+// path keeps a frequent test run from repeatedly clearing real agent-availability data.
+let agentAvailabilityPathOverride = null;
+/** Test seam only. Pass null to restore the real user-level path. */
+function __setAgentAvailabilityPathForTests(filePath) {
+    agentAvailabilityPathOverride = filePath;
+}
+function agentAvailabilityFilePath() {
+    if (agentAvailabilityPathOverride)
+        return agentAvailabilityPathOverride;
+    // Resolved lazily and defensively: this module is imported by CLI paths that must not
+    // fail to load just because a home directory is unusual.
+    return path_1.default.join(os_1.default.homedir(), '.fraim', AGENT_AVAILABILITY_FILE);
+}
+function loadPersistedEmployees() {
+    try {
+        const raw = fs_1.default.readFileSync(agentAvailabilityFilePath(), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed.employees) || parsed.employees.length === 0)
+            return null;
+        // Only accept entries that still match the current known agent ids, so a stale file
+        // from an older build cannot introduce unknown ids into the roster.
+        const knownIds = new Set(Object.keys(EMPLOYEE_LABELS));
+        const employees = parsed.employees.filter((e) => e && typeof e.id === 'string' && knownIds.has(e.id));
+        if (employees.length === 0)
+            return null;
+        const detectedAtMs = parsed.detectedAt ? Date.parse(parsed.detectedAt) : NaN;
+        return { employees, detectedAtMs: Number.isFinite(detectedAtMs) ? detectedAtMs : 0 };
+    }
+    catch {
+        return null; // absent or malformed is fine; we simply probe instead
+    }
+}
+/**
+ * Adopt a persisted entry into the in-memory cache, preserving its ORIGINAL age.
+ *
+ * Critically this does NOT stamp `Date.now()`. Doing so made a stale file look permanently
+ * fresh, which silently killed the TTL: `detectEmployees()` expired the in-memory entry,
+ * immediately re-read the same stale file, and never re-probed - so a CLI installed outside
+ * the Hub was never picked up. Caught by asserting on the persisted `detectedAt` stamp; a
+ * timing-based assertion had masked it.
+ *
+ * When the adopted entry is already past the TTL it is still returned (first paint stays
+ * fast) but a background refresh is kicked off so the next read is correct.
+ */
+function adoptPersistedEmployees(persisted) {
+    cachedEmployees = persisted.employees;
+    cachedEmployeesAtMs = persisted.detectedAtMs;
+    if (Date.now() - persisted.detectedAtMs > employeeDetectionTtlMs) {
+        void detectEmployeesAsync({ force: true }).catch(() => undefined);
+    }
+    return persisted.employees;
+}
+function persistEmployees(employees) {
+    try {
+        const file = agentAvailabilityFilePath();
+        fs_1.default.mkdirSync(path_1.default.dirname(file), { recursive: true });
+        fs_1.default.writeFileSync(file, JSON.stringify({ employees, detectedAt: new Date().toISOString() }, null, 2), 'utf8');
+    }
+    catch {
+        // Best effort only: failing to persist must never break detection.
+    }
+}
+function storeDetectedEmployees(employees) {
+    cachedEmployees = employees;
+    cachedEmployeesAtMs = Date.now();
+    persistEmployees(employees);
+    return employees;
+}
+/**
+ * Drop the cached agent-availability result so the next detection re-probes.
+ * Call after anything that changes what is installed (for example the Hub's own
+ * install-agent flow) so a newly installed CLI shows up without waiting for the TTL.
+ */
+function invalidateEmployeeDetectionCache() {
+    cachedEmployees = null;
+    cachedEmployeesAtMs = 0;
+    inFlightDetection = null;
+    try {
+        fs_1.default.rmSync(agentAvailabilityFilePath(), { force: true });
+    }
+    catch { /* best effort */ }
+}
+/** Test seam only. Mirrors __resetLatestVersionCache in hub-latest-version.ts. */
+function __setEmployeeDetectionTtlForTests(ttlMs) {
+    employeeDetectionTtlMs = ttlMs ?? EMPLOYEE_DETECTION_TTL_MS;
+}
+// Counts detection rounds that actually executed CLI probes, as opposed to being served
+// from the in-memory cache or the persisted file. This is the perf signal worth asserting
+// on, because it is ENVIRONMENT-INDEPENDENT: how expensive a probe happens to be varies
+// wildly (2715ms on a machine with the CLIs installed, ~44ms on CI where none are), but
+// "how many times did we pay for it" does not. Absolute millisecond thresholds silently
+// pass on unfixed code wherever probes are cheap; this counter cannot.
+let employeeProbeRounds = 0;
+/** Test seam only: number of detection rounds that really probed. */
+function __getEmployeeProbeRoundsForTests() {
+    return employeeProbeRounds;
+}
+/** Test seam only. */
+function __resetEmployeeProbeRoundsForTests() {
+    employeeProbeRounds = 0;
+}
+function buildEmployeeStatus(id, available) {
+    return {
+        id,
+        label: EMPLOYEE_LABELS[id],
+        available,
+        detail: available ? 'Installed and ready on this machine.' : 'CLI not detected on this machine.',
+        supportsRaw: supportsDirectPath(id),
+    };
+}
+/**
+ * Non-blocking employee detection. Probes every agent CONCURRENTLY, so the cost is the
+ * slowest single probe rather than the sum of all of them, and the event loop stays free
+ * for other requests. Result populates the same cache detectEmployees() reads.
+ *
+ * Concurrent callers share one in-flight probe rather than each starting their own.
+ */
+async function detectEmployeesAsync(options = {}) {
+    const fresh = cachedEmployeesIfFresh();
+    if (fresh)
+        return fresh;
+    if (!options.force) {
+        // Fast path for the first request after a restart: serve last-known immediately rather
+        // than making first paint wait ~2.2s. Startup priming passes force:true to refresh.
+        const persisted = loadPersistedEmployees();
+        if (persisted)
+            return adoptPersistedEmployees(persisted);
+    }
+    if (inFlightDetection)
+        return inFlightDetection;
+    const ids = Object.keys(EMPLOYEE_LABELS);
+    employeeProbeRounds += 1;
+    inFlightDetection = Promise.all(ids.map(async (id) => buildEmployeeStatus(id, await availableByVersionProbeAsync(agentBinaryName(id)))))
+        .then((employees) => storeDetectedEmployees(employees))
+        .finally(() => { inFlightDetection = null; });
+    return inFlightDetection;
+}
 // Resolve the binary name for each agent tool.
 function agentBinaryName(id) {
     if (id === 'copilot')
@@ -740,17 +978,26 @@ function agentBinaryName(id) {
         return AGY_BINARY;
     return executableName(id);
 }
+/**
+ * Synchronous employee detection, served from the Issue #1010 cache when it is fresh.
+ *
+ * The blocking probe is retained as the cache-miss fallback rather than removed, so this
+ * function's contract is unchanged for every existing caller: it still returns a resolved
+ * answer, never a placeholder, and needs no "availability unknown" state in the UI. In
+ * practice the miss is rare because the server primes the cache asynchronously at startup
+ * (see AiHubServer.start), so requests read a warm cache instead of paying ~2.7s.
+ */
 function detectEmployees() {
-    return Object.keys(EMPLOYEE_LABELS).map((id) => {
-        const available = availableByVersionProbe(agentBinaryName(id));
-        return {
-            id,
-            label: EMPLOYEE_LABELS[id],
-            available,
-            detail: available ? 'Installed and ready on this machine.' : 'CLI not detected on this machine.',
-            supportsRaw: supportsDirectPath(id),
-        };
-    });
+    const fresh = cachedEmployeesIfFresh();
+    if (fresh)
+        return fresh;
+    // Prefer last-known over a blocking probe: ~0ms instead of ~2.7s of frozen event loop.
+    const persisted = loadPersistedEmployees();
+    if (persisted)
+        return adoptPersistedEmployees(persisted);
+    employeeProbeRounds += 1;
+    const employees = Object.keys(EMPLOYEE_LABELS).map((id) => buildEmployeeStatus(id, availableByVersionProbe(agentBinaryName(id))));
+    return storeDetectedEmployees(employees);
 }
 function parseFraimInvocation(message) {
     const trimmed = message.trim();
@@ -1476,6 +1723,10 @@ class CliHostRuntime {
     detectEmployees() {
         return detectEmployees();
     }
+    // Issue #1010: probes all agents concurrently without blocking the event loop.
+    detectEmployeesAsync() {
+        return detectEmployeesAsync();
+    }
     startRun(hostId, projectPath, message, handlers, sessionId, launchContext) {
         return spawnHostProcess(hostId, (0, configured_agents_1.decorateHostPlanWithConfiguredAgent)(buildStartPlan(hostId, message, sessionId), launchContext?.agent, launchContext?.env), projectPath, handlers);
     }

package/dist/src/ai-hub/hub2-remote-config.js

@@ -7,9 +7,9 @@ const remote_hub_gateway_1 = require("./remote-hub-gateway");
 exports.HUB2_REMOTE_UI_CHANNEL = 'hub2';
 exports.HUB2_REMOTE_UI_RELEASE_ID = '2026.07.25.1';
 exports.HUB2_REMOTE_UI_ASSET_ORIGIN = 'https://fraim.wellnessatwork.me';
-exports.HUB2_REMOTE_UI_PUBLIC_KEY_PEM = `-----BEGIN PUBLIC KEY-----
-MCowBQYDK2VwAyEAn53Ks3CQSqzflw4/6KIJbKmZeWy94V5H7LYlWhMOePo=
------END PUBLIC KEY-----
+exports.HUB2_REMOTE_UI_PUBLIC_KEY_PEM = `-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAn53Ks3CQSqzflw4/6KIJbKmZeWy94V5H7LYlWhMOePo=
+-----END PUBLIC KEY-----
 `;
 function hub2RemoteManifestUrl(remoteBaseUrl = (0, remote_hub_gateway_1.resolveFraimRemoteUrl)()) {
     const target = new URL('/api/ai-hub/ui/releases/latest', remoteBaseUrl);

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

@@ -134,6 +134,27 @@ function normalizeAiHubProjectList(projects, currentProjectPath, options = {}) {
         add(normalizeProjectEntry(project));
     return withUniqueProjectIds(Array.from(byPath.values()));
 }
+// Issue #1024: tombstones live in a separate file so a wholesale replacement of
+// ai-hub-state.json (backup restore, cross-machine sync) can never drop project
+// deletions that happened after the snapshot was taken.
+function tombstoneFilePath(stateFilePath) {
+    return stateFilePath.replace(/\.json$/i, '-tombstones.json');
+}
+function readTombstoneFile(stateFilePath) {
+    const tombFile = tombstoneFilePath(stateFilePath);
+    try {
+        const raw = JSON.parse(fs_1.default.readFileSync(tombFile, 'utf8'));
+        return normalizeRemovedProjectPaths(raw);
+    }
+    catch {
+        return [];
+    }
+}
+function writeTombstoneFile(stateFilePath, paths) {
+    const tombFile = tombstoneFilePath(stateFilePath);
+    fs_1.default.mkdirSync(path_1.default.dirname(tombFile), { recursive: true });
+    fs_1.default.writeFileSync(tombFile, JSON.stringify(normalizeRemovedProjectPaths(paths), null, 2));
+}
 class AiHubPreferencesStore {
     constructor(stateFilePath = path_1.default.join((0, project_fraim_paths_1.getUserFraimDirPath)(), 'ai-hub-state.json')) {
         this.stateFilePath = stateFilePath;
@@ -144,7 +165,13 @@ class AiHubPreferencesStore {
         }
         try {
             const raw = JSON.parse(fs_1.default.readFileSync(this.stateFilePath, 'utf8'));
-            const removedProjectPaths = normalizeRemovedProjectPaths(raw.removedProjectPaths);
+            // Issue #1024: merge tombstones from ai-hub-state.json with those in the
+            // separate tombstone file so a wholesale restore of the state file can never
+            // drop project deletions that happened after the snapshot was taken.
+            const removedProjectPaths = normalizeRemovedProjectPaths([
+                ...(Array.isArray(raw.removedProjectPaths) ? raw.removedProjectPaths : []),
+                ...readTombstoneFile(this.stateFilePath),
+            ]);
             return {
                 projectPath: raw.projectPath || projectPath,
                 employeeId: (raw.employeeId === 'claude' || raw.employeeId === 'codex' || raw.employeeId === 'gemini' || raw.employeeId === 'copilot' || raw.employeeId === 'antigravity') ? raw.employeeId : DEFAULT_EMPLOYEE,
@@ -168,6 +195,8 @@ class AiHubPreferencesStore {
     save(preferences) {
         fs_1.default.mkdirSync(path_1.default.dirname(this.stateFilePath), { recursive: true });
         fs_1.default.writeFileSync(this.stateFilePath, JSON.stringify(preferences, null, 2));
+        // Issue #1024: keep the tombstone file in sync so load() always sees the union.
+        writeTombstoneFile(this.stateFilePath, preferences.removedProjectPaths || []);
     }
     saveProjects(projectPath, projects, options = {}) {
         const normalizedProjectPath = normalizeProjectPath(projectPath);