fraim-hub 2.0.270 → 2.0.272

package/bin/fraim-hub-2.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 try {
   const { createFraimHub2Program } = require('../dist/src/cli/fraim-hub-2.js');
   createFraimHub2Program().parseAsync(process.argv).catch((error) => {

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

@@ -14,6 +14,7 @@ exports.getAiHubCategories = getAiHubCategories;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
+const resolve_phase_edge_1 = require("../core/resolve-phase-edge");
 // Directories scanned for employee jobs at runtime, in lowest-to-highest
 // precedence order. Later entries win on {categoryId, jobId} collision.
 //
@@ -411,21 +412,6 @@ function findJobStubPath(projectPath, jobId) {
     }
     return null;
 }
-// Resolve a phase's `onSuccess` edge to the next phase id given the run's
-// discriminant. Returns null when the edge is absent or terminal.
-function nextPhase(edge, discriminant) {
-    if (edge == null)
-        return null;
-    if (typeof edge === 'string')
-        return edge;
-    if (typeof edge === 'object') {
-        if (typeof edge[discriminant] === 'string')
-            return edge[discriminant];
-        if (typeof edge.default === 'string')
-            return edge.default;
-    }
-    return null;
-}
 // Parse the ordered phase list from a job stub's ## Steps section.
 // Real FRAIM job stubs use Markdown steps rather than JSON frontmatter;
 // this is the fallback parser that makes the pizza tracker work for them.
@@ -460,7 +446,7 @@ function loadJobPhases(jobId, projectPath, discriminant = 'feature') {
         const phaseDef = fm.phases[cursor];
         if (!phaseDef)
             break;
-        cursor = nextPhase(phaseDef.onSuccess, discriminant);
+        cursor = (0, resolve_phase_edge_1.resolvePhaseEdge)(fm.phases[cursor]?.onSuccess, discriminant);
     }
     const labels = fm.phaseLabels || {};
     return ordered.map((id) => ({ id, label: friendlyPhaseLabel(id, labels[id]) }));
@@ -482,7 +468,7 @@ function resolveJobPhaseTransition(jobId, projectPath, phaseId, outcome, discrim
     if (!phaseDef)
         return null;
     const edge = outcome === 'complete' ? phaseDef.onSuccess : phaseDef.onFailure;
-    return nextPhase(edge, discriminant);
+    return (0, resolve_phase_edge_1.resolvePhaseEdge)(edge, discriminant);
 }
 function loadAllJobPhaseIds(jobId, projectPath) {
     const stubPath = findJobStubPath(projectPath, jobId);

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

@@ -26,7 +26,6 @@ const HEADER_OMITTED_FIELDS = [
     'events',
     'artifacts',
     'run',
-    'delegation',
     'handoffSummary',
     '_bodyLoaded',
     '_stopping',
@@ -44,6 +43,9 @@ function conversationScopeKey(scope, projectPath) {
         return exports.MANAGER_SCOPE_KEY;
     if (scope === 'company')
         return exports.COMPANY_SCOPE_KEY;
+    if (typeof projectPath !== 'string' || projectPath.trim().length === 0) {
+        throw new Error('conversationScopeKey: empty project path');
+    }
     return normalizeConversationKey(projectPath);
 }
 const emptyProjectState = () => ({
@@ -68,7 +70,10 @@ function normalizeConversationKey(key) {
     if (typeof key === 'string' && (key === exports.MANAGER_SCOPE_KEY || key === exports.COMPANY_SCOPE_KEY)) {
         return key;
     }
-    return path_1.default.resolve(key || process.cwd());
+    if (typeof key !== 'string' || key.trim().length === 0) {
+        throw new Error('normalizeConversationKey: empty project path');
+    }
+    return path_1.default.resolve(key);
 }
 function normalizeProjectPath(projectPath) {
     return normalizeConversationKey(projectPath);
@@ -181,13 +186,34 @@ function placeConversationInBucket(bucket, conv) {
     const existingScore = conversationRichness(existing);
     const incomingScore = conversationRichness(conv);
     if (incomingScore > existingScore) {
-        bucket.conversations[idx] = conv;
+        bucket.conversations[idx] = withStableConversationCreatedAt(existing, conv);
     }
     else if (incomingScore === existingScore
         && timestampValue(value?.lastUpdatedAt) > timestampValue(existing.lastUpdatedAt)) {
-        bucket.conversations[idx] = conv;
+        bucket.conversations[idx] = withStableConversationCreatedAt(existing, conv);
     }
 }
+function stableConversationCreatedAt(existing, incoming) {
+    const existingValue = existing?.createdAt;
+    const incomingValue = incoming?.createdAt;
+    const existingTs = timestampValue(existingValue);
+    const incomingTs = timestampValue(incomingValue);
+    if (existingTs > 0 && incomingTs > 0)
+        return existingTs <= incomingTs ? existingValue : incomingValue;
+    if (existingTs > 0)
+        return existingValue;
+    if (incomingTs > 0)
+        return incomingValue;
+    return existingValue ?? incomingValue;
+}
+function withStableConversationCreatedAt(existing, incoming) {
+    if (!incoming || typeof incoming !== 'object')
+        return incoming;
+    const createdAt = stableConversationCreatedAt(existing, incoming);
+    if (createdAt === undefined)
+        return incoming;
+    return { ...incoming, createdAt };
+}
 // Relocate any project-scoped record mis-filed under the wrong project bucket back to its own
 // project (see docs/rca/hub-conversation-cross-project-leak.md). Sentinel buckets are left as-is.
 function migrateProjectBuckets(store) {
@@ -303,14 +329,45 @@ function newestFirst(a, b) {
 }
 function toHeader(conv) {
     const header = { ...conv };
+    const delegation = compactDelegationForHeader(header.delegation);
     for (const field of HEADER_OMITTED_FIELDS)
         delete header[field];
+    if (delegation)
+        header.delegation = delegation;
     for (const field of Object.keys(header)) {
         if (field.startsWith('_'))
             delete header[field];
     }
     return header;
 }
+function compactDelegationForHeader(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const delegation = raw;
+    const tasks = Array.isArray(delegation.tasks) ? delegation.tasks : [];
+    if (!tasks.length)
+        return undefined;
+    return {
+        delegationRequired: delegation.delegationRequired === true,
+        objective: delegation.objective,
+        orchestratorPersonaKey: delegation.orchestratorPersonaKey,
+        rootRunId: delegation.rootRunId,
+        managerRunId: delegation.managerRunId,
+        tasks: tasks.map((task) => {
+            const value = task && typeof task === 'object' ? task : {};
+            return {
+                taskId: value.taskId,
+                title: value.title,
+                status: value.status,
+                personaKey: value.personaKey,
+                jobId: value.jobId,
+                runId: value.runId,
+                conversationId: value.conversationId,
+                dependsOn: Array.isArray(value.dependsOn) ? value.dependsOn : [],
+            };
+        }),
+    };
+}
 function headerNeedsSanitization(header) {
     const value = header;
     return Object.keys(value).some((field) => HEADER_OMITTED_FIELD_SET.has(field) || field.startsWith('_'));
@@ -345,6 +402,17 @@ class AiHubConversationStore {
         // Sibling directory of the legacy file, e.g. ~/.fraim/ai-hub-conversations/
         this.shardRoot = path_1.default.join(dir, base);
     }
+    /**
+     * Root directory holding the per-bucket shards.
+     *
+     * Issue #1164: exposed read-only so callers that walk the shard layout, such as
+     * the stale-bucket sweep, ask the store where its data lives instead of
+     * re-deriving the path. Two independent derivations of the same layout drift the
+     * moment one changes, and a sweep pointed at the wrong directory fails silently.
+     */
+    get shardRootPath() {
+        return this.shardRoot;
+    }
     // ---- path helpers ----
     bucketDir(bucketKey) {
         const canonical = bucketKey === exports.MANAGER_SCOPE_KEY || bucketKey === exports.COMPANY_SCOPE_KEY
@@ -732,6 +800,7 @@ class AiHubConversationStore {
                 id: existing.id,
                 projectPath: key,
                 agentName: patch.agentName || existing.agentName,
+                createdAt: stableConversationCreatedAt(existing, patch) ?? existing.createdAt,
                 lastUpdatedAt: patch.lastUpdatedAt ?? new Date().toISOString(),
             }) ?? existing;
             this.writeConvFile(bucketDir, key, merged);

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

@@ -381,7 +381,19 @@ function extractSignalFromArgs(args) {
         : 'starting';
     const findings = args.findings;
     const findingsText = findings && typeof findings.summary === 'string' ? findings.summary : undefined;
-    const discriminant = typeof args.runDiscriminant === 'string' ? args.runDiscriminant : undefined;
+    // Issue #1135: `runDiscriminant` is not a field of the seekMentoring tool schema
+    // and no agent sends it, so before issue #1123 this was populated only by the
+    // scripted test double and production always resolved with the literal default
+    // 'feature'. The real discriminant is the one the mentor routes on
+    // (`findings.phaseOutcome`), so read that first and keep the legacy field as a
+    // fallback for the test double.
+    const evidenceArgs = args.evidence;
+    const discriminantFromFindings = findings && typeof findings.phaseOutcome === 'string' ? findings.phaseOutcome
+        : findings && typeof findings.issueType === 'string' ? findings.issueType
+            : evidenceArgs && typeof evidenceArgs.issueType === 'string' ? evidenceArgs.issueType
+                : undefined;
+    const discriminant = discriminantFromFindings
+        ?? (typeof args.runDiscriminant === 'string' ? args.runDiscriminant : undefined);
     const jobName = typeof args.jobName === 'string' ? args.jobName : undefined;
     const jobId = typeof args.jobId === 'string' ? args.jobId : undefined;
     const issueNumber = typeof args.issueNumber === 'string' ? args.issueNumber
@@ -1787,6 +1799,7 @@ class CliHostRuntime {
 exports.CliHostRuntime = CliHostRuntime;
 class FakeHostRuntime {
     constructor() {
+        this.isTestDouble = true;
         this.employees = [
             { id: 'codex', label: 'Codex', available: true, detail: 'Test double employee.', supportsRaw: true },
             { id: 'claude', label: 'Claude Code', available: true, detail: 'Test double employee.', supportsRaw: true },
@@ -1878,6 +1891,7 @@ exports.FakeHostRuntime = FakeHostRuntime;
 // FakeHostRuntime (smaller surface, no seekMentoring).
 class ScriptedHostRuntime {
     constructor() {
+        this.isTestDouble = true;
         this.employees = [
             { id: 'codex', label: 'Codex', available: true, detail: 'Scripted test double.', supportsRaw: true },
             { id: 'claude', label: 'Claude Code', available: true, detail: 'Scripted test double.', supportsRaw: true },

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

@@ -10,33 +10,34 @@ exports.getOsShortcutPaths = getOsShortcutPaths;
 exports.writeMacosLaunchAgent = writeMacosLaunchAgent;
 exports.writeLinuxDesktopEntry = writeLinuxDesktopEntry;
 exports.runHubInstall = runHubInstall;
-// #921: `fraim hub install` — register the FRAIM Hub as an OS application so users
+// #921/#1179: `fraim-hub install` — register the FRAIM Hub as an OS application so users
 // can launch it without a terminal or npx command.
 //
-// This is an interim mitigation. Full packaged installers (electron-builder, code
-// signing, .msi/.dmg) are a separate effort requiring signing infrastructure.
+// #921 shipped this as a downloader: it fetched a packaged Electron app from the repository's
+// latest GitHub Release and pointed the shortcut at it. That never worked. The lookup is
+// unauthenticated and `mathursrus/FRAIM` is private (GitHub answers 404, not 403), and no release
+// has ever been published, so every run ended in `GitHub release lookup failed with HTTP 404`.
+//
+// #1179 replaces the download with a generated launcher that runs the Hub through
+// `npx fraim-hub@latest` (see `./hub-launcher`). That needs no release feed and no signing
+// infrastructure, and it matches the shape of the macOS installer that already ships:
+// `scripts/build-macos-installer.sh` builds a `pkgbuild --nopayload` package whose entire payload
+// is a script that runs `npx -y fraim@latest first-run`.
 const commander_1 = require("commander");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
 const child_process_1 = require("child_process");
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
-const hub_release_download_1 = require("./hub-release-download");
+const hub_launcher_1 = require("./hub-launcher");
 // Stable install directory under ~/.fraim/bin/fraim-hub-electron/
 function resolveHubInstallDir() {
     return path_1.default.join((0, project_fraim_paths_1.getUserFraimDirPath)(), 'bin', 'fraim-hub-electron');
 }
-// The binary that OS shortcuts should point at. On Windows this is the Electron .exe;
-// on POSIX systems it is the unpacked Electron binary or a shell wrapper.
+// The file OS shortcuts point at: the generated launcher, `fraim-hub.cmd` on Windows and
+// `fraim-hub` elsewhere. Before #1179 this named a downloaded Electron binary that never arrived.
 function resolveShortcutTarget() {
-    const installDir = resolveHubInstallDir();
-    if (process.platform === 'win32') {
-        return path_1.default.join(installDir, 'fraim-hub.exe');
-    }
-    if (process.platform === 'darwin') {
-        return path_1.default.join(installDir, 'FRAIM Hub.app', 'Contents', 'MacOS', 'FRAIM Hub');
-    }
-    return path_1.default.join(installDir, 'fraim-hub');
+    return (0, hub_launcher_1.resolveLauncherPath)(resolveHubInstallDir());
 }
 // Platform-correct locations for OS launcher entries.
 function getOsShortcutPaths(home) {
@@ -48,7 +49,10 @@ function getOsShortcutPaths(home) {
     }
     if (process.platform === 'darwin') {
         return {
+            // The LaunchAgent starts the Hub headless at login; the .app is what Launchpad and Finder
+            // show. Neither substitutes for the other, so both are installed.
             launchAgent: path_1.default.join(home, 'Library', 'LaunchAgents', 'ai.fraim.hub.plist'),
+            appBundle: path_1.default.join(home, 'Applications', 'FRAIM Hub.app'),
         };
     }
     return {
@@ -81,11 +85,21 @@ function writeMacosLaunchAgent(plistPath, target) {
     fs_1.default.mkdirSync(path_1.default.dirname(plistPath), { recursive: true });
     fs_1.default.writeFileSync(plistPath, content, 'utf8');
 }
-function writeLinuxDesktopEntry(desktopPath, target) {
+function writeLinuxDesktopEntry(desktopPath, target, workingDir = os_1.default.homedir()) {
+    // No `--no-open` here. A .desktop entry is something the user clicks, and `--no-open` would start
+    // the server without ever showing the Hub. Only the macOS LaunchAgent, which runs at login with
+    // no click behind it, wants the headless form.
+    //
+    // `Path=` is not decoration. #646 lost a whole release to the same class of bug on macOS: the
+    // installer ran its bootstrap from a temp directory that no longer existed, so `npx`'s
+    // `process.cwd()` threw `ENOENT: uv_cwd` and first-run never launched (fixed in d680d2a6 by
+    // cd-ing to the user's home). A launcher started by a desktop environment inherits whatever
+    // working directory that environment had, so name one that is guaranteed to exist.
     const content = `[Desktop Entry]
 Name=FRAIM Hub
 Comment=FRAIM AI Workforce Hub
-Exec=${target} --no-open
+Exec=${target}
+Path=${workingDir}
 Icon=fraim-hub
 Terminal=false
 Type=Application
@@ -99,13 +113,26 @@ StartupNotify=true
     }
     catch { /* non-fatal */ }
 }
-function writeWindowsShortcutScript(lnkPath, target) {
+function writeWindowsShortcutScript(lnkPath, target, workingDir = os_1.default.homedir()) {
     // PowerShell WScript.Shell creates a real .lnk shortcut.
+    //
+    // WindowStyle 7 (minimized), not 1 (normal): the target is a .cmd, so Windows creates a console
+    // host for the length of the launch. `src/ai-hub/cli.ts` detaches and unrefs the Electron child,
+    // so npx returns once the Hub is ready and that console closes on its own; minimized keeps it
+    // from taking focus in front of the Hub window while it is up. Hiding it outright would need a
+    // wscript/VBS shim, which this repo has no precedent for.
+    //
+    // WorkingDirectory is set rather than left empty. #646 lost a release to the same class of bug:
+    // the macOS installer ran its bootstrap from a temp directory that no longer existed, `npx`'s
+    // `process.cwd()` threw `ENOENT: uv_cwd`, and first-run never launched (fixed in d680d2a6 by
+    // cd-ing to the user's home). A shortcut with no WorkingDirectory hands npx whatever directory
+    // the shell that launched it happened to be in.
     const ps = [
         '$ws = New-Object -ComObject WScript.Shell',
         `$sc = $ws.CreateShortcut('${lnkPath.replace(/'/g, "''")}')`,
         `$sc.TargetPath = '${target.replace(/'/g, "''")}'`,
-        "$sc.WindowStyle = 1",
+        `$sc.WorkingDirectory = '${workingDir.replace(/'/g, "''")}'`,
+        "$sc.WindowStyle = 7",
         '$sc.Save()',
     ].join('; ');
     try {
@@ -113,8 +140,10 @@ function writeWindowsShortcutScript(lnkPath, target) {
     }
     catch {
         // PowerShell unavailable (e.g. minimal CI image) — write a plain .cmd launcher as fallback.
+        // Same working-directory guarantee the .lnk gets above, for the same #646 reason.
         const safeTarget = target.replace(/"/g, '""');
-        const cmd = `@echo off\r\nstart "" "${safeTarget}"\r\n`;
+        const safeWorkingDir = workingDir.replace(/"/g, '""');
+        const cmd = `@echo off\r\ncd /d "${safeWorkingDir}"\r\nstart "" "${safeTarget}"\r\n`;
         const cmdPath = lnkPath.replace(/\.lnk$/i, '.cmd');
         fs_1.default.mkdirSync(path_1.default.dirname(cmdPath), { recursive: true });
         fs_1.default.writeFileSync(cmdPath, cmd, 'utf8');
@@ -127,14 +156,18 @@ async function runHubInstall() {
     const home = os_1.default.homedir();
     const shortcuts = getOsShortcutPaths(home);
     fs_1.default.mkdirSync(installDir, { recursive: true });
-    const downloaded = await (0, hub_release_download_1.downloadLatestHubBinary)(installDir, target);
-    console.log(`  Downloaded release asset: ${downloaded.assetName}`);
+    (0, hub_launcher_1.writeHubLauncher)({ installDir });
+    console.log(`  Launcher: ${target}`);
     if (process.platform === 'win32' && shortcuts.startMenu) {
         fs_1.default.mkdirSync(path_1.default.dirname(shortcuts.startMenu), { recursive: true });
-        writeWindowsShortcutScript(shortcuts.startMenu, target);
+        writeWindowsShortcutScript(shortcuts.startMenu, target, home);
         console.log(`  Start Menu shortcut: ${shortcuts.startMenu}`);
     }
     else if (process.platform === 'darwin' && shortcuts.launchAgent) {
+        if (shortcuts.appBundle) {
+            (0, hub_launcher_1.writeMacosAppBundle)(shortcuts.appBundle, target);
+            console.log(`  Application: ${shortcuts.appBundle}`);
+        }
         writeMacosLaunchAgent(shortcuts.launchAgent, target);
         // Load the agent so it is active immediately without a logout/login.
         try {
@@ -144,7 +177,7 @@ async function runHubInstall() {
         console.log(`  LaunchAgent: ${shortcuts.launchAgent}`);
     }
     else if (shortcuts.desktopEntry) {
-        writeLinuxDesktopEntry(shortcuts.desktopEntry, target);
+        writeLinuxDesktopEntry(shortcuts.desktopEntry, target, home);
         // Notify the desktop environment to refresh its app database.
         try {
             (0, child_process_1.execFileSync)('update-desktop-database', [path_1.default.dirname(shortcuts.desktopEntry)], { stdio: 'ignore' });
@@ -155,6 +188,7 @@ async function runHubInstall() {
     console.log('');
     console.log('FRAIM Hub is registered as an OS application.');
     console.log('Launch it from your Start Menu / Launchpad / application launcher.');
+    console.log('Each launch resolves the latest published fraim-hub, so there is nothing to reinstall.');
 }
 exports.hubInstallCommand = new commander_1.Command('install')
     .description('Register FRAIM Hub as an OS application (Start Menu / Launchpad entry)')

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

@@ -0,0 +1,184 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveLauncherPath = resolveLauncherPath;
+exports.writeHubLauncher = writeHubLauncher;
+exports.writeMacosAppBundle = writeMacosAppBundle;
+// #1179: the launcher an OS shortcut points at.
+//
+// `fraim-hub install` used to download a packaged Electron app from
+// `https://api.github.com/repos/mathursrus/FRAIM/releases/latest`. That call is unauthenticated and
+// `mathursrus/FRAIM` is private, so GitHub answered 404 rather than 403; and no release has ever
+// been published, because `.github/workflows/fraim-hub-release.yml` fires only on `release:
+// published`. The command therefore failed for every user and never produced anything launchable.
+//
+// The Hub does not need a packaged binary to be double-clickable. `npx fraim-hub@latest` already
+// resolves a shared Electron dist from `~/.fraim/bin/electron/<version>/` (#1112) and detaches the
+// desktop child (`src/ai-hub/cli.ts`), and the shipped macOS installer is the same shape: a
+// `pkgbuild --nopayload` package whose whole job is to run `npx -y fraim@latest first-run`. So the
+// shortcut target is a small generated script that runs the Hub through npx.
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/**
+ * What the launcher runs.
+ *
+ * `@latest` and not a pinned version, because an npx-launched Hub has no self-update path:
+ * `configureAutoUpdater()` in `desktop-main.ts` returns immediately unless `app.isPackaged` (never
+ * true under npx), it reads from the same absent release feed, and `/api/ai-hub/version` only
+ * reports `updateAvailable` without acting on it. Resolving `@latest` at launch is the update
+ * mechanism; pinning here would strand users on the version they installed.
+ */
+const HUB_LAUNCH_SPEC = 'fraim-hub@latest';
+/**
+ * No `--restart`: it replaces a running Hub unconditionally, so double-clicking the icon while the
+ * Hub is up would kill it and pay a cold relaunch (~20s in #1110). The default already replaces
+ * only an older or stale instance and re-focuses a current one (`src/cli/fraim-hub.ts`).
+ *
+ * No `--no-open` either: that belongs to the background LaunchAgent, not to a clicked app entry.
+ */
+const NPX_ARGS = `-y ${HUB_LAUNCH_SPEC}`;
+/**
+ * Shown when no `npx` can be resolved. Worth a real sentence because the failure surface is a
+ * double-clicked icon with no terminal behind it, where the alternative is cmd's
+ * `'npx' is not recognized` flashing past.
+ *
+ * Emitted by a batch `echo`, so this string must stay free of `& | < > ^`, which cmd interprets
+ * rather than prints.
+ */
+const MISSING_NODE_MESSAGE = 'FRAIM Hub needs Node.js. Install it from https://nodejs.org/ and open FRAIM Hub again.';
+/**
+ * Quote a value for a POSIX shell script.
+ *
+ * The launcher interpolates filesystem paths into a script it then executes. Inside double quotes a
+ * shell still expands `$(...)`, backticks, and `$VAR`, so a path carrying any of those would be
+ * evaluated rather than used. Single quotes suppress all of it, and `'\''` is the standard way to
+ * carry a literal single quote through.
+ *
+ * These paths derive from `process.execPath` and `getUserFraimDirPath()` (which honours
+ * `FRAIM_USER_DIR`), so an attacker who controls them can already run code as this user. This is
+ * not a privilege boundary; it is a write-boundary guard kept next to the construction it protects,
+ * so a future caller passing a less trustworthy path does not turn this into one.
+ */
+function posixSingleQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * Escape a value for literal use inside a batch file.
+ *
+ * `%` is the variable sigil, and a Windows path may legally contain it, so `C:\%TEMP%\node` would
+ * expand at parse time instead of naming the directory. In a batch file `%%` yields a literal `%`.
+ * `"` needs no handling: it is not a legal character in a Windows path.
+ */
+function batchEscape(value) {
+    return value.replace(/%/g, '%%');
+}
+/** `fraim-hub.cmd` on Windows, `fraim-hub` elsewhere. */
+function launcherFileName(platform = process.platform) {
+    return platform === 'win32' ? 'fraim-hub.cmd' : 'fraim-hub';
+}
+function resolveLauncherPath(installDir, platform = process.platform) {
+    return path_1.default.join(installDir, launcherFileName(platform));
+}
+/**
+ * The Node directory recorded into the launcher is *appended* to PATH, never prepended.
+ *
+ * Appended, because prepending would pin every future launch to whichever Node ran the install and
+ * shadow a later system upgrade indefinitely. A system `npx` should keep winning; this directory is
+ * the fallback for the case that made recording it necessary at all: a GUI shortcut inherits no
+ * shell PATH, and the portable-Node bootstrap in `scripts/installer/fraim-install-win.template.cmd`
+ * puts Node under `~/.fraim/node/...` where the system PATH never points.
+ */
+function renderWindowsLauncher(nodeDir) {
+    return [
+        '@echo off',
+        'rem FRAIM Hub launcher - generated by `fraim-hub install` (issue #1179). Safe to delete;',
+        'rem re-running `npx fraim-hub@latest install` recreates it.',
+        'setlocal',
+        `set "PATH=%PATH%;${batchEscape(nodeDir)}"`,
+        'where npx >nul 2>nul',
+        'if errorlevel 1 (',
+        `  echo ${MISSING_NODE_MESSAGE}`,
+        '  pause',
+        '  exit /b 1',
+        ')',
+        `call npx ${NPX_ARGS} %*`,
+        '',
+    ].join('\r\n');
+}
+function renderPosixLauncher(nodeDir) {
+    return [
+        '#!/bin/sh',
+        '# FRAIM Hub launcher - generated by `fraim-hub install` (issue #1179). Safe to delete;',
+        '# re-running `npx fraim-hub@latest install` recreates it.',
+        `FRAIM_NODE_DIR=${posixSingleQuote(nodeDir)}`,
+        'PATH="$PATH:$FRAIM_NODE_DIR"',
+        'export PATH',
+        'if ! command -v npx >/dev/null 2>&1; then',
+        `  echo "${MISSING_NODE_MESSAGE}" >&2`,
+        '  exit 1',
+        'fi',
+        `exec npx ${NPX_ARGS} "$@"`,
+        '',
+    ].join('\n');
+}
+/**
+ * Write the launcher and return its path. Idempotent: the contents depend only on the platform and
+ * the Node directory, so a repeat install rewrites the same bytes.
+ */
+function writeHubLauncher(options) {
+    const platform = options.platform ?? process.platform;
+    const nodeDir = options.nodeDir ?? path_1.default.dirname(process.execPath);
+    const launcherPath = resolveLauncherPath(options.installDir, platform);
+    fs_1.default.mkdirSync(options.installDir, { recursive: true });
+    fs_1.default.writeFileSync(launcherPath, platform === 'win32' ? renderWindowsLauncher(nodeDir) : renderPosixLauncher(nodeDir), 'utf8');
+    if (platform !== 'win32') {
+        fs_1.default.chmodSync(launcherPath, 0o755);
+    }
+    return launcherPath;
+}
+/**
+ * A minimal `.app` around the launcher, so macOS has something to show in Launchpad and Finder.
+ *
+ * The LaunchAgent `runHubInstall` already writes is a login item, not an application: it starts the
+ * Hub headless at login and produces no clickable entry. The two are complementary and both are
+ * installed.
+ *
+ * `CFBundleIdentifier` is deliberately `ai.fraim.hub.launcher`, not the `ai.fraim.hub` that
+ * `packages/fraim-hub/package.json` declares as electron-builder's `appId`. If a packaged Hub is
+ * ever installed alongside this one, two bundles sharing an identifier would leave LaunchServices
+ * to guess which is which.
+ */
+function writeMacosAppBundle(appDir, launcherPath) {
+    const executableName = 'FRAIM Hub';
+    const macosDir = path_1.default.join(appDir, 'Contents', 'MacOS');
+    fs_1.default.mkdirSync(macosDir, { recursive: true });
+    const infoPlist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleName</key>
+  <string>FRAIM Hub</string>
+  <key>CFBundleDisplayName</key>
+  <string>FRAIM Hub</string>
+  <key>CFBundleIdentifier</key>
+  <string>ai.fraim.hub.launcher</string>
+  <key>CFBundleExecutable</key>
+  <string>${executableName}</string>
+  <key>CFBundlePackageType</key>
+  <string>APPL</string>
+  <key>CFBundleInfoDictionaryVersion</key>
+  <string>6.0</string>
+  <key>CFBundleVersion</key>
+  <string>1</string>
+  <key>CFBundleShortVersionString</key>
+  <string>1.0</string>
+</dict>
+</plist>
+`;
+    fs_1.default.writeFileSync(path_1.default.join(appDir, 'Contents', 'Info.plist'), infoPlist, 'utf8');
+    const executablePath = path_1.default.join(macosDir, executableName);
+    fs_1.default.writeFileSync(executablePath, `#!/bin/sh\nexec ${posixSingleQuote(launcherPath)} "$@"\n`, 'utf8');
+    fs_1.default.chmodSync(executablePath, 0o755);
+}

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

@@ -22,7 +22,10 @@ const defaultPreferences = (projectPath) => ({
     removedProjectPaths: [],
 });
 function normalizeProjectPath(projectPath) {
-    return path_1.default.resolve(projectPath || process.cwd());
+    if (typeof projectPath !== 'string' || projectPath.trim().length === 0) {
+        throw new Error('normalizeProjectPath: empty project path');
+    }
+    return path_1.default.resolve(projectPath);
 }
 function canonicalProjectPath(projectPath) {
     const normalized = normalizeProjectPath(projectPath);

package/dist/src/ai-hub/restart-recovery-policy.js

@@ -8,6 +8,7 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const crypto_1 = require("crypto");
 const conversation_store_1 = require("./conversation-store");
+const process_liveness_1 = require("./process-liveness");
 exports.DEFAULT_RESTART_RECOVERY_LEASE_MS = 60_000;
 function normalizedDirectoryPath(projectPath) {
     const resolved = path_1.default.resolve(projectPath);
@@ -49,6 +50,8 @@ class RestartRecoveryPolicy {
         this.recoveryLeaseMs = options.recoveryLeaseMs ?? exports.DEFAULT_RESTART_RECOVERY_LEASE_MS;
         this.projectExists = options.projectExists || ((projectPath) => fs_1.default.existsSync(projectPath));
         this.machineLevelJobIds = options.machineLevelJobIds || new Set();
+        this.currentPid = options.currentPid ?? process.pid;
+        this.pidAlive = options.pidAlive || process_liveness_1.isPidAlive;
     }
     classify(conversation, bucketKey, options = {}) {
         const bucketReason = restartRecoveryBucketOwnershipReason(conversation, bucketKey);
@@ -81,6 +84,17 @@ class RestartRecoveryPolicy {
         if (options.activeRunExists) {
             return { action: 'defer', reason: 'active_run_exists' };
         }
+        // Issue #1159: `activeRunExists` only sees this process's run registry, so it
+        // cannot tell that a *different* live Hub owns this run. Two Hubs on one
+        // machine is the normal case here: the desktop Hub plus any Hub a job starts
+        // for validation. Without this check the second one adopts the first one's
+        // in-flight work, replaces its run id, and parks it as "Waiting on you".
+        // A dead owner pid is exactly the restart case recovery exists for, so only
+        // a live foreign owner defers.
+        const ownerPid = typeof conversation.ownerPid === 'number' ? conversation.ownerPid : 0;
+        if (ownerPid > 0 && ownerPid !== this.currentPid && this.pidAlive(ownerPid)) {
+            return { action: 'defer', reason: 'owner_process_alive' };
+        }
         const recoveredAt = timestampMs(conversation.restartRecovery?.recoveredAt);
         if (recoveredAt > 0 && this.nowMs() - recoveredAt < this.recoveryLeaseMs) {
             return { action: 'defer', reason: 'recent_recovery' };