fraim-hub 2.0.204

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

@@ -0,0 +1,4013 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findAvailablePortExcluding = exports.findAvailablePort = exports.AiHubServer = exports.HostConfigStore = exports.DeploymentStore = void 0;
+exports.configureFraimForHubAgent = configureFraimForHubAgent;
+exports.buildOpenFileInvocation = buildOpenFileInvocation;
+const express_1 = __importDefault(require("express"));
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const crypto_1 = require("crypto");
+const child_process_1 = require("child_process");
+const https_1 = __importDefault(require("https"));
+const types_1 = require("../first-run/types");
+const learning_context_builder_1 = require("../local-mcp-server/learning-context-builder");
+const brand_store_1 = require("../core/brand-store");
+const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
+const catalog_1 = require("./catalog");
+const agent_token_prices_1 = require("../local-mcp-server/agent-token-prices");
+const hosts_1 = require("./hosts");
+const configured_agents_1 = require("./configured-agents");
+const url_safety_1 = require("./url-safety");
+const manager_turns_1 = require("./manager-turns");
+const preferences_1 = require("./preferences");
+const conversation_store_1 = require("./conversation-store");
+const remote_hub_gateway_1 = require("./remote-hub-gateway");
+const managed_browser_1 = require("./managed-browser");
+const managed_agent_paths_1 = require("../cli/utils/managed-agent-paths");
+const user_config_1 = require("../cli/utils/user-config");
+const version_utils_1 = require("../cli/utils/version-utils");
+const hub_latest_version_1 = require("./hub-latest-version");
+const semver = __importStar(require("semver"));
+let personaHiringModule;
+let managerHiringModule;
+function loadPersonaHiringModule() {
+    const cached = personaHiringModule;
+    if (cached !== undefined) {
+        return cached;
+    }
+    try {
+        // Server deployments include the persona catalog. The npm client package
+        // intentionally does not, so importing ai-hub/server must not require it.
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const loaded = require('../config/persona-hiring');
+        personaHiringModule = loaded;
+        return loaded;
+    }
+    catch {
+        personaHiringModule = null;
+        return null;
+    }
+}
+function buildReviewApprovalSystemEventText(instructions) {
+    const text = (instructions || '').trim();
+    if (text === 'Approved.') {
+        return 'review_approved';
+    }
+    if (/^Approved and push to\b/i.test(text))
+        return 'review_approved push_default_branch';
+    if (/^Approved, merge PR, and complete the issue\.$/i.test(text))
+        return 'review_approved merge_pr_work_completion';
+    if (/^Approved and clean up branch\.$/i.test(text))
+        return 'review_approved cleanup_branch';
+    return null;
+}
+function loadManagerHiringModule() {
+    const cached = managerHiringModule;
+    if (cached !== undefined) {
+        return cached;
+    }
+    try {
+        // Server deployments include the manager-hiring catalog. The npm client
+        // package intentionally does not, so Hub bootstrap must not require it.
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const loaded = require('../config/ai-manager-hiring');
+        managerHiringModule = loaded;
+        return loaded;
+    }
+    catch {
+        managerHiringModule = null;
+        return null;
+    }
+}
+function loadPersonaCapabilityModule() {
+    try {
+        // Server deployments include the persona catalog. The npm client package
+        // intentionally does not, so Hub setup must degrade without loading it.
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        return require('../config/persona-capability-bundles');
+    }
+    catch {
+        return null;
+    }
+}
+function getProtectedPersonaForHubJob(jobName) {
+    return loadPersonaCapabilityModule()?.getProtectedPersonaForJob(jobName) ?? null;
+}
+const FRAIM_INTERNAL_JOB_IDS = new Set([
+    'contribute-to-fraim',
+    'create-registry-asset',
+    'extract-ashley-learnings',
+    'file-fraim-issue',
+    'praise-fraim',
+    'run-on-remote-hub',
+    'setup-remote-hub',
+    'update-registry-override',
+]);
+function listHubPersonaBundles() {
+    return loadPersonaCapabilityModule()?.listPersonaCapabilityBundles() ?? [];
+}
+function buildHubPersonaHireUrl(personaKey, hireMode = 'job') {
+    const params = new URLSearchParams({ persona: personaKey, mode: hireMode });
+    return `/pricing?${params.toString()}`;
+}
+function buildLocalHubReturnUrl(req, surface) {
+    const proto = req.protocol || 'http';
+    const host = req.get('host') || '127.0.0.1';
+    const target = new URL('/ai-hub/', `${proto}://${host}`);
+    target.searchParams.set('connected', surface);
+    return target.toString();
+}
+function buildHostedAuthUrl(surface, redirectTo, hubReturn) {
+    const target = new URL('/auth/sign-in.html', (0, remote_hub_gateway_1.resolveFraimRemoteUrl)());
+    target.searchParams.set('surface', surface);
+    target.searchParams.set('redirect_to', redirectTo);
+    if (hubReturn)
+        target.searchParams.set('hub_return', hubReturn);
+    return target.toString();
+}
+function buildHostedPathUrl(pathname, queryString) {
+    const target = new URL(pathname, (0, remote_hub_gateway_1.resolveFraimRemoteUrl)());
+    target.search = queryString;
+    return target.toString();
+}
+function buildHubPersonaAvatarUrl(personaKey) {
+    return loadPersonaHiringModule()?.buildPersonaAvatarUrl(personaKey) ?? '';
+}
+function buildHubManagerHiringCatalog() {
+    return loadManagerHiringModule()?.buildManagerHiringCatalog() ?? {
+        qualities: [],
+        services: [],
+        roles: {},
+    };
+}
+class AiHubRunRegistry {
+    constructor() {
+        this.runs = new Map();
+        this.children = new Map();
+    }
+    listLatest() {
+        return [...this.runs.values()].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))[0];
+    }
+    get(runId) {
+        return this.runs.get(runId);
+    }
+    all() {
+        return [...this.runs.values()];
+    }
+    create(run, child) {
+        this.runs.set(run.id, run);
+        this.children.set(run.id, child);
+        return run;
+    }
+    attachChildIfRunning(runId, child) {
+        const run = this.runs.get(runId);
+        if (!run || run.status !== 'running')
+            return false;
+        this.children.set(runId, child);
+        return true;
+    }
+    update(runId, updater) {
+        const run = this.runs.get(runId);
+        if (!run) {
+            throw new Error(`Run ${runId} not found`);
+        }
+        const priorStatus = run.status;
+        updater(run);
+        const now = new Date().toISOString();
+        // Issue #347: when status flipped, accumulate the previous status's
+        // duration into the appropriate working/waiting bucket. lastStatusChangeAt
+        // is the wall-clock timestamp of the most recent flip; on the first
+        // call it falls back to createdAt.
+        if (run.status !== priorStatus) {
+            const lastAt = run.lastStatusChangeAt || run.createdAt;
+            const elapsedMs = Date.parse(now) - Date.parse(lastAt);
+            if (Number.isFinite(elapsedMs) && elapsedMs > 0) {
+                run.totals = run.totals || emptyTotals();
+                if (priorStatus === 'running') {
+                    run.totals.workingDurationMs += elapsedMs;
+                }
+                else {
+                    run.totals.waitingDurationMs += elapsedMs;
+                }
+            }
+            run.lastStatusChangeAt = now;
+        }
+        run.updatedAt = now;
+        return run;
+    }
+    dispose(runId) {
+        this.children.delete(runId);
+    }
+    // #521: terminate the agent process for a run (manager clicked Stop). Returns
+    // true if a live child was signalled. The child's onExit handler then fires and
+    // parks the run in its waiting state.
+    stop(runId) {
+        const child = this.children.get(runId);
+        if (!child || typeof child.kill !== 'function')
+            return false;
+        try {
+            child.kill();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+// ─── Issue #578: Deployment + Host stores ─────────────────────────────────────
+const VALID_EMPLOYEE_IDS = ['codex', 'claude', 'gemini', 'copilot'];
+function startSessionSeedForHost(hostId, runId) {
+    return hostId === 'gemini' ? undefined : runId;
+}
+class DeploymentStore {
+    constructor(filePath) {
+        this.filePath = filePath ?? path_1.default.join(getUserHubDir(), 'hub-deployments.json');
+    }
+    load() {
+        try {
+            if (!fs_1.default.existsSync(this.filePath))
+                return [];
+            return JSON.parse(fs_1.default.readFileSync(this.filePath, 'utf8'));
+        }
+        catch {
+            return [];
+        }
+    }
+    save(deployments) {
+        fs_1.default.mkdirSync(path_1.default.dirname(this.filePath), { recursive: true });
+        fs_1.default.writeFileSync(this.filePath, JSON.stringify(deployments, null, 2));
+    }
+    create(deployment) {
+        const list = this.load();
+        list.push(deployment);
+        this.save(list);
+        return deployment;
+    }
+    update(id, updater) {
+        const list = this.load();
+        const dep = list.find((d) => d.id === id);
+        if (!dep)
+            return false;
+        updater(dep);
+        dep.updatedAt = new Date().toISOString();
+        this.save(list);
+        return true;
+    }
+    delete(id) {
+        const list = this.load();
+        const next = list.filter((d) => d.id !== id);
+        if (next.length === list.length)
+            return false;
+        this.save(next);
+        return true;
+    }
+}
+exports.DeploymentStore = DeploymentStore;
+class HostConfigStore {
+    constructor(filePath) {
+        this.filePath = filePath ?? path_1.default.join(getUserHubDir(), 'hub-hosts.json');
+    }
+    load() {
+        try {
+            if (!fs_1.default.existsSync(this.filePath))
+                return [];
+            return JSON.parse(fs_1.default.readFileSync(this.filePath, 'utf8'));
+        }
+        catch {
+            return [];
+        }
+    }
+    save(hosts) {
+        fs_1.default.mkdirSync(path_1.default.dirname(this.filePath), { recursive: true });
+        fs_1.default.writeFileSync(this.filePath, JSON.stringify(hosts, null, 2));
+    }
+    add(host) {
+        const list = this.load();
+        list.push(host);
+        this.save(list);
+        return host;
+    }
+    delete(id) {
+        const list = this.load();
+        const next = list.filter((h) => h.id !== id);
+        if (next.length === list.length)
+            return false;
+        this.save(next);
+        return true;
+    }
+}
+exports.HostConfigStore = HostConfigStore;
+async function pingHost(host) {
+    const start = Date.now();
+    try {
+        const resp = await fetch(`${host.url.replace(/\/$/, '')}/health`, {
+            signal: AbortSignal.timeout(5000),
+            headers: host.authToken ? { 'X-Hub-Auth': host.authToken } : {},
+        });
+        const latencyMs = Date.now() - start;
+        return {
+            id: host.id,
+            label: host.label,
+            url: host.url,
+            status: resp.ok ? 'online' : 'degraded',
+            latencyMs,
+            lastPingAt: new Date().toISOString(),
+        };
+    }
+    catch {
+        return {
+            id: host.id,
+            label: host.label,
+            url: host.url,
+            status: 'offline',
+            latencyMs: null,
+            lastPingAt: new Date().toISOString(),
+        };
+    }
+}
+function normalizeReviewArtifact(raw, index = 0) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const value = raw;
+    const artifactPath = typeof value.path === 'string' && value.path.trim().length > 0 ? value.path.trim() : null;
+    const url = (0, url_safety_1.safeHttpUrl)(value.url);
+    const type = typeof value.type === 'string' && value.type.trim().length > 0 ? value.type.trim() : 'file';
+    const label = typeof value.label === 'string' && value.label.trim().length > 0
+        ? value.label.trim()
+        : artifactPath
+            ? artifactPath.split(/[\\/]/).filter(Boolean).pop() || `Artifact ${index + 1}`
+            : url || `Artifact ${index + 1}`;
+    if (!artifactPath && !url)
+        return null;
+    return { type, label, path: artifactPath, url };
+}
+function normalizeReviewAction(raw, index = 0) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const value = raw;
+    const id = typeof value.id === 'string' && value.id.trim().length > 0
+        ? value.id.trim()
+        : `review-action-${index + 1}`;
+    const label = typeof value.label === 'string' && value.label.trim().length > 0 ? value.label.trim() : '';
+    const kind = typeof value.kind === 'string' && value.kind.trim().length > 0 ? value.kind.trim() : '';
+    if (!label || !kind)
+        return null;
+    const rawTarget = value.target && typeof value.target === 'object' && !Array.isArray(value.target)
+        ? value.target
+        : null;
+    const target = rawTarget ? {
+        ...(typeof rawTarget.branch === 'string' && rawTarget.branch.trim().length > 0 ? { branch: rawTarget.branch.trim() } : {}),
+        ...((0, url_safety_1.safeHttpUrl)(rawTarget.prUrl) ? { prUrl: (0, url_safety_1.safeHttpUrl)(rawTarget.prUrl) } : {}),
+        ...(typeof rawTarget.prNumber === 'number' && Number.isFinite(rawTarget.prNumber) ? { prNumber: rawTarget.prNumber } : {}),
+        ...(typeof rawTarget.label === 'string' && rawTarget.label.trim().length > 0 ? { label: rawTarget.label.trim() } : {}),
+    } : null;
+    return {
+        id,
+        label,
+        kind,
+        ...(typeof value.style === 'string' && value.style.trim().length > 0 ? { style: value.style.trim() } : {}),
+        ...(typeof value.deliveryActionId === 'string' && value.deliveryActionId.trim().length > 0 ? { deliveryActionId: value.deliveryActionId.trim() } : {}),
+        ...(typeof value.description === 'string' && value.description.trim().length > 0 ? { description: value.description.trim() } : {}),
+        ...(target && Object.keys(target).length > 0 ? { target } : {}),
+    };
+}
+function normalizeReviewHandoff(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const value = raw;
+    if (typeof value.reviewRequired !== 'boolean')
+        return null;
+    const artifacts = Array.isArray(value.artifacts)
+        ? value.artifacts.map((artifact, index) => normalizeReviewArtifact(artifact, index)).filter((artifact) => Boolean(artifact))
+        : [];
+    const reviewActions = Array.isArray(value.reviewActions)
+        ? value.reviewActions.map((action, index) => normalizeReviewAction(action, index)).filter((action) => Boolean(action))
+        : [];
+    const rawTarget = value.reviewTarget && typeof value.reviewTarget === 'object' ? value.reviewTarget : null;
+    const targetType = rawTarget && typeof rawTarget.type === 'string' ? rawTarget.type.trim() : '';
+    const targetLabel = rawTarget && typeof rawTarget.label === 'string' && rawTarget.label.trim().length > 0
+        ? rawTarget.label.trim()
+        : '';
+    if (!value.reviewRequired) {
+        return {
+            reviewRequired: false,
+            reviewTarget: rawTarget ? { type: targetType || 'none', label: targetLabel || 'Completed work' } : null,
+            artifacts,
+            summary: typeof value.summary === 'string' ? value.summary.trim() : '',
+            feedbackMode: typeof value.feedbackMode === 'string' ? value.feedbackMode.trim() : '',
+            ...(reviewActions.length > 0 ? { reviewActions } : {}),
+        };
+    }
+    if (targetType === 'pull_request') {
+        const url = (0, url_safety_1.safeHttpUrl)(rawTarget?.url);
+        if (!url)
+            return null;
+        if (artifacts.length > 0)
+            return null;
+        return {
+            reviewRequired: true,
+            reviewTarget: { type: 'pull_request', label: targetLabel || 'Pull request', url },
+            artifacts: [],
+            summary: typeof value.summary === 'string' ? value.summary.trim() : '',
+            feedbackMode: typeof value.feedbackMode === 'string' ? value.feedbackMode.trim() : 'pull_request_comments',
+            ...(reviewActions.length > 0 ? { reviewActions } : {}),
+        };
+    }
+    const fileArtifacts = artifacts.filter((artifact) => artifact.path && !artifact.url);
+    if (targetType === 'artifact_set' && fileArtifacts.length > 0 && fileArtifacts.length === artifacts.length) {
+        return {
+            reviewRequired: true,
+            reviewTarget: { type: 'artifact_set', label: targetLabel || `${artifacts.length} artifact${artifacts.length === 1 ? '' : 's'}` },
+            artifacts: fileArtifacts,
+            summary: typeof value.summary === 'string' ? value.summary.trim() : '',
+            feedbackMode: typeof value.feedbackMode === 'string' ? value.feedbackMode.trim() : 'inline',
+            ...(reviewActions.length > 0 ? { reviewActions } : {}),
+        };
+    }
+    return null;
+}
+const DELEGATION_TASK_STATUSES = new Set([
+    'planned',
+    'running',
+    'submitted',
+    'reviewed',
+    'blocked',
+    'completed',
+    'failed',
+]);
+function cleanString(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+function cleanNullableString(value) {
+    const cleaned = cleanString(value);
+    return cleaned.length > 0 ? cleaned : null;
+}
+function normalizeDelegationLedger(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const value = raw;
+    // Accept delegationRequired:true OR presence of goal/objective + tasks/jobs/groups (AI may omit the flag).
+    const hasFlag = value.delegationRequired === true;
+    const objective = cleanString((value.objective || value.goal));
+    if (!hasFlag && !objective)
+        return null;
+    if (!objective)
+        return null;
+    // Flatten tasks from multiple schemas:
+    //   canonical: tasks/jobs: [{title, taskId, personaKey, jobId, instructions, dependsOn}]
+    //   group-based: groups: [{runs: [{run_id, job, persona, briefing, expected_artifact}]}]
+    //   with optional depends_on referencing other run_id values
+    let rawTasks = [];
+    const rawJobs = (value.jobs || value.tasks);
+    if (Array.isArray(rawJobs)) {
+        rawTasks = rawJobs;
+    }
+    else if (Array.isArray(value.groups)) {
+        // Flatten groups[].runs into a linear task list, resolving depends_on from group membership.
+        let groupDepIds = [];
+        for (const group of value.groups) {
+            const runs = Array.isArray(group.runs) ? group.runs : [];
+            const currentIds = runs.map((r) => cleanString(r.run_id) || '').filter(Boolean);
+            for (const run of runs) {
+                // Synthesise a canonical task from the run schema.
+                const dependsOnRaw = Array.isArray(group.depends_on) ? group.depends_on.map(String) : groupDepIds.length ? groupDepIds : [];
+                rawTasks.push({
+                    taskId: run.run_id,
+                    title: cleanString(run.briefing)?.slice(0, 80) || cleanString(run.job) || 'Task',
+                    personaKey: run.persona,
+                    jobId: run.job,
+                    instructions: run.briefing,
+                    dependsOn: dependsOnRaw,
+                    status: 'planned',
+                });
+            }
+            groupDepIds = currentIds;
+        }
+    }
+    const tasks = rawTasks.map((task, index) => {
+        if (!task || typeof task !== 'object')
+            return null;
+        const rawTask = task;
+        // Accept title or first 80 chars of briefing/instructions
+        const title = cleanString((rawTask.title || rawTask.briefing || rawTask.instructions))?.slice(0, 80);
+        if (!title)
+            return null;
+        const taskId = cleanString((rawTask.taskId || rawTask.run_id || rawTask.id))
+            || title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')
+            || `task-${index + 1}`;
+        const rawStatus = cleanString(rawTask.status);
+        const status = DELEGATION_TASK_STATUSES.has(rawStatus) ? rawStatus : 'planned';
+        const artifacts = Array.isArray(rawTask.artifacts)
+            ? rawTask.artifacts.map((a, ai) => normalizeReviewArtifact(a, ai)).filter((a) => Boolean(a))
+            : [];
+        const reviewHandoff = normalizeReviewHandoff(rawTask.reviewHandoff);
+        // Accept dependsOn or depends_on as string array
+        const rawDeps = rawTask.dependsOn || rawTask.depends_on;
+        return {
+            taskId,
+            title,
+            status,
+            personaKey: cleanNullableString((rawTask.personaKey || rawTask.persona)),
+            jobId: cleanNullableString((rawTask.jobId || rawTask.job || rawTask.job_id)),
+            reviewJobId: cleanNullableString(rawTask.reviewJobId),
+            reviewType: cleanNullableString(rawTask.reviewType),
+            instructions: cleanString((rawTask.instructions || rawTask.briefing)) || undefined,
+            latestSummary: cleanString(rawTask.latestSummary) || undefined,
+            hostThreadId: cleanNullableString(rawTask.hostThreadId),
+            hostSessionId: cleanNullableString(rawTask.hostSessionId),
+            runId: cleanNullableString(rawTask.runId),
+            conversationId: cleanNullableString(rawTask.conversationId),
+            dependsOn: Array.isArray(rawDeps) ? rawDeps.map(String).filter(Boolean) : [],
+            artifacts,
+            reviewHandoff,
+        };
+    }).filter((task) => Boolean(task));
+    if (tasks.length === 0)
+        return null;
+    return {
+        delegationRequired: true,
+        objective,
+        orchestratorPersonaKey: cleanNullableString((value.orchestratorPersonaKey || value.manager_persona)),
+        rootRunId: cleanNullableString(value.rootRunId),
+        managerRunId: cleanNullableString((value.managerRunId || value.manager_session)),
+        latestSummary: cleanString(value.latestSummary) || undefined,
+        tasks,
+    };
+}
+function extractReviewHandoffFromText(text) {
+    if (!text || !/reviewRequired|reviewTarget|review_handoff/i.test(text))
+        return null;
+    const candidates = [];
+    for (const match of String(text).matchAll(/```(?:json)?\s*([\s\S]*?)```/gi))
+        candidates.push(match[1]);
+    const tagged = String(text).match(/<review_handoff>\s*([\s\S]*?)\s*<\/review_handoff>/i);
+    if (tagged)
+        candidates.push(tagged[1]);
+    const inline = String(text).match(/(\{\s*"reviewRequired"[\s\S]*\})/i);
+    if (inline)
+        candidates.push(inline[1]);
+    for (const candidate of candidates) {
+        try {
+            const handoff = normalizeReviewHandoff(JSON.parse(candidate.trim()));
+            if (handoff)
+                return handoff;
+        }
+        catch {
+            // Malformed snippets are ignored; the UI can still surface legacy fallback state.
+        }
+    }
+    return null;
+}
+function extractDelegationLedgerFromText(text) {
+    if (!text || !/delegationRequired|delegation_ledger|delegationLedger|"goal"\s*:.*"groups"\s*:/is.test(text))
+        return null;
+    const candidates = [];
+    for (const match of String(text).matchAll(/```(?:json)?\s*([\s\S]*?)```/gi))
+        candidates.push(match[1]);
+    const tagged = String(text).match(/<delegation_ledger>\s*([\s\S]*?)\s*<\/delegation_ledger>/i);
+    if (tagged)
+        candidates.push(tagged[1]);
+    const inline = String(text).match(/(\{\s*"delegationRequired"[\s\S]*\})/i);
+    if (inline)
+        candidates.push(inline[1]);
+    for (const candidate of candidates) {
+        try {
+            const ledger = normalizeDelegationLedger(JSON.parse(candidate.trim()));
+            if (ledger)
+                return ledger;
+        }
+        catch {
+            // Malformed delegation snippets are ignored; the host transcript remains available in Micro-manage.
+        }
+    }
+    return null;
+}
+function applyReviewProjection(run, text) {
+    const delegation = extractDelegationLedgerFromText(text);
+    if (delegation) {
+        run.delegation = {
+            ...delegation,
+            rootRunId: delegation.rootRunId || run.id,
+            managerRunId: delegation.managerRunId || run.id,
+        };
+    }
+    const handoff = extractReviewHandoffFromText(text);
+    if (handoff) {
+        run.reviewHandoff = handoff;
+        run.artifacts = handoff.reviewTarget?.type === 'artifact_set' ? handoff.artifacts : [];
+        return;
+    }
+}
+function emptyTotals() {
+    return {
+        totalDurationMs: 0,
+        workingDurationMs: 0,
+        waitingDurationMs: 0,
+        tokenTotals: {
+            inputTokens: null,
+            outputTokens: null,
+            costUsd: null,
+            // Issue #347: Hub server cannot read tokenSnapshot from the local
+            // proxy in-process. Cross-process attribution is a follow-up;
+            // until then, every Hub-driven run reports unavailable. The Hub UI
+            // renders "—" per spec R4.6.
+            coverage: 'unavailable',
+        },
+    };
+}
+const PHASE_STATUSES = new Set(['starting', 'complete', 'incomplete', 'failure']);
+function normalizePersistedPhaseHistory(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value
+        .map((entry) => {
+        if (!entry || typeof entry !== 'object')
+            return null;
+        const raw = entry;
+        if (typeof raw.phaseId !== 'string' || !raw.phaseId)
+            return null;
+        const latestStatus = typeof raw.latestStatus === 'string' && PHASE_STATUSES.has(raw.latestStatus)
+            ? raw.latestStatus
+            : null;
+        return {
+            phaseId: raw.phaseId,
+            enteredAt: typeof raw.enteredAt === 'string' ? raw.enteredAt : new Date().toISOString(),
+            latestStatus,
+            latestText: typeof raw.latestText === 'string' ? raw.latestText : null,
+        };
+    })
+        .filter((entry) => Boolean(entry));
+}
+function readPersistedRunProjection(conversation) {
+    const rawRun = conversation?.run;
+    if (!rawRun || typeof rawRun !== 'object')
+        return null;
+    const value = rawRun;
+    return {
+        currentPhase: typeof value.currentPhase === 'string' ? value.currentPhase : null,
+        phaseHistory: normalizePersistedPhaseHistory(value.phaseHistory),
+        stages: Array.isArray(value.stages) ? value.stages : [],
+        totals: value.totals && typeof value.totals === 'object' ? value.totals : null,
+        runDiscriminant: typeof value.runDiscriminant === 'string' ? value.runDiscriminant : null,
+    };
+}
+// Issue #347 — apply per-turn usage from the host stream into the
+// run's tokenTotals. Idempotent on the same turn (we replace, not add)
+// because Codex's `turn.completed.usage` is cumulative, not delta.
+// When the host doesn't emit costUsd directly (Codex), we compute it
+// from the captured agent identity via the price table.
+function applyUsageSignal(run, usage) {
+    run.totals = run.totals || emptyTotals();
+    const tt = run.totals.tokenTotals;
+    // Total input tokens (for the user-facing display) = non-cached + cached.
+    // Cumulative across the whole run on both hosts; take max to guard
+    // against any out-of-order delivery.
+    const totalInput = usage.nonCachedInputTokens + usage.cachedInputTokens;
+    tt.inputTokens = Math.max(tt.inputTokens || 0, totalInput);
+    tt.outputTokens = Math.max(tt.outputTokens || 0, usage.outputTokens);
+    // Cost: prefer the host's own number (Claude). For hosts that don't
+    // emit it (Codex), compute from the captured agent identity + price
+    // table. If neither source applies, leave costUsd null and coverage
+    // stays 'partial'.
+    let computedCost = null;
+    if (typeof usage.costUsd === 'number') {
+        computedCost = usage.costUsd;
+    }
+    else if (run.agentName && run.agentModel) {
+        const price = (0, agent_token_prices_1.lookupPrice)(run.agentName.toLowerCase(), run.agentModel.toLowerCase());
+        if (price) {
+            computedCost =
+                (usage.nonCachedInputTokens / 1_000_000) * price.inputPerMTok +
+                    (usage.cachedInputTokens / 1_000_000) * price.cacheReadPerMTok +
+                    (usage.cacheCreationTokens / 1_000_000) * price.cacheCreationPerMTok +
+                    (usage.outputTokens / 1_000_000) * price.outputPerMTok;
+        }
+    }
+    if (computedCost !== null) {
+        tt.costUsd = Math.max(tt.costUsd || 0, computedCost);
+        tt.coverage = 'complete';
+    }
+    else if (tt.coverage !== 'complete') {
+        tt.coverage = 'partial';
+    }
+}
+// Issue #347 — capture agent identity from the host stream's fraim_connect
+// call. Used downstream by applyUsageSignal to compute cost via the price
+// table when the host does not emit costUsd directly.
+function applyAgentIdentitySignal(run, identity) {
+    run.agentName = identity.agentName;
+    run.agentModel = identity.agentModel;
+}
+function stripStructuredHostPayloads(text) {
+    return text
+        .replace(/<delegation_ledger>\s*[\s\S]*?\s*<\/delegation_ledger>/gi, '')
+        .replace(/<review_handoff>\s*[\s\S]*?\s*<\/review_handoff>/gi, '')
+        .trim();
+}
+function appendHostMessage(run, hostId, event, channel) {
+    if (!event.message || channel !== 'stdout')
+        return;
+    applyReviewProjection(run, event.message);
+    if (hostId === 'gemini') {
+        const last = run.messages[run.messages.length - 1];
+        if (last?.role === 'employee') {
+            last.text = `${last.text}\n${event.message}`;
+            last.createdAt = new Date().toISOString();
+            applyReviewProjection(run, last.text);
+            last.text = stripStructuredHostPayloads(last.text);
+            if (!last.text)
+                run.messages.pop();
+            return;
+        }
+    }
+    const displayMessage = stripStructuredHostPayloads(event.message);
+    if (!displayMessage)
+        return;
+    run.messages.push((0, hosts_1.createHubMessage)('employee', displayMessage));
+}
+// Apply a parsed seekMentoring tool-use signal from the host stream to
+// the run state. Returns the updated currentPhase.
+function applySeekMentoringSignal(run, signal) {
+    // Issue #347: filter cross-job pollution. The agent may call
+    // seekMentoring for jobs OTHER than the one this run is tracking
+    // (e.g., consulting `organizational-learning-synthesis` mid-run).
+    // Only apply signals whose job identity matches this run's.
+    // Issue #732: match on `jobName` — the stable job-name slug that equals
+    // run.jobId — NOT `jobId`. get_fraim_job mints a fresh randomUUID as the
+    // job id on every call and the agent echoes that UUID into
+    // seekMentoring.jobId, so a UUID never equals run.jobId. Comparing the UUID
+    // discarded every real phase signal as if it were foreign-job pollution and
+    // froze the tracker at "no phases done". The UUID cannot positively identify
+    // this run's job, so it must not participate in the match.
+    const targetJobId = run.jobId;
+    const callJobName = signal.jobName;
+    if (callJobName && targetJobId && callJobName !== targetJobId)
+        return;
+    if (signal.reviewHandoff) {
+        const normalizedReviewHandoff = normalizeReviewHandoff(signal.reviewHandoff);
+        run.reviewHandoff = normalizedReviewHandoff || signal.reviewHandoff;
+        run.artifacts = normalizedReviewHandoff?.reviewTarget?.type === 'artifact_set'
+            ? normalizedReviewHandoff.artifacts
+            : [];
+    }
+    if (signal.delegationLedger &&
+        run.jobId === 'fully-delegate' &&
+        signal.phaseStatus === 'complete' &&
+        (signal.phaseId === 'confirm-or-fallback' || signal.phaseId === 'create-delegation-graph')) {
+        run.delegation = {
+            ...signal.delegationLedger,
+            rootRunId: signal.delegationLedger.rootRunId || run.id,
+            managerRunId: signal.delegationLedger.managerRunId || run.id,
+        };
+    }
+    // Discriminant signals are routing hints only — they don't move the
+    // tracker, but they do change which phase id will be considered
+    // reachable next time stages are derived. Persist on the run.
+    if (signal.phaseId === '__discriminant__') {
+        if (signal.discriminant)
+            run.runDiscriminant = signal.discriminant;
+        return;
+    }
+    if (signal.discriminant)
+        run.runDiscriminant = signal.discriminant;
+    // The seekMentoring workflow uses `currentPhase: "starting"` as a
+    // sentinel for the very first call ("give me phase 1 instructions").
+    // It is not an actual phase id — skip it so the tracker doesn't
+    // render an extra "starting" stage at the end of the path.
+    if (signal.phaseId === 'starting')
+        return;
+    run.phaseHistory = run.phaseHistory || [];
+    const existing = run.phaseHistory.find((entry) => entry.phaseId === signal.phaseId);
+    if (existing) {
+        existing.latestStatus = signal.phaseStatus;
+        if (signal.findingsText)
+            existing.latestText = signal.findingsText;
+    }
+    else {
+        const entry = {
+            phaseId: signal.phaseId,
+            enteredAt: new Date().toISOString(),
+            latestStatus: signal.phaseStatus,
+            latestText: signal.findingsText || null,
+        };
+        run.phaseHistory.push(entry);
+    }
+    run.currentPhase = signal.phaseId;
+}
+// Build the stage list for a run. Combines the FSM's reachable path with
+// any phases the run has actually visited (in case the run took an
+// onFailure back-edge into a phase the simple onSuccess walk wouldn't
+// surface). Each stage is marked done / current / upcoming based on
+// whether it precedes / matches / follows the current phase along the
+// rendered order.
+function deriveStages(run, projectPath) {
+    const declaredPath = (0, catalog_1.loadJobPhases)(run.jobId, projectPath, run.runDiscriminant || 'feature');
+    if (declaredPath.length === 0)
+        return [];
+    // Merge in any visited phase that's not on the declared path BUT is
+    // declared in the job's frontmatter (e.g., a phase reached via an
+    // onFailure back-edge that the simple onSuccess walk didn't surface).
+    // Skip the 'starting' sentinel, the __discriminant__ marker, and any
+    // phase id NOT in the frontmatter — that last filter prevents
+    // cross-job pollution from showing up on the tracker.
+    const allDeclared = (0, catalog_1.loadAllJobPhaseIds)(run.jobId, projectPath);
+    const visited = (run.phaseHistory || []).map((entry) => entry.phaseId);
+    const known = new Set(declaredPath.map((p) => p.id));
+    for (const visitedId of visited) {
+        if (visitedId === 'starting' || visitedId === '__discriminant__')
+            continue;
+        if (!allDeclared.has(visitedId))
+            continue;
+        if (!known.has(visitedId)) {
+            declaredPath.push({ id: visitedId, label: (0, catalog_1.labelForPhaseId)(visitedId, run.jobId, projectPath) });
+            known.add(visitedId);
+        }
+    }
+    const currentIndex = run.currentPhase
+        ? declaredPath.findIndex((p) => p.id === run.currentPhase)
+        : -1;
+    const historyMap = new Map((run.phaseHistory || []).map((e) => [e.phaseId, e]));
+    const completedWithoutPhaseTelemetry = run.status === 'completed' &&
+        currentIndex < 0 &&
+        historyMap.size === 0;
+    if (completedWithoutPhaseTelemetry) {
+        return declaredPath.map((phase) => ({ phaseId: phase.id, label: phase.label, state: 'done' }));
+    }
+    return declaredPath.map((phase, index) => {
+        let state;
+        const entry = historyMap.get(phase.id);
+        if (index === currentIndex) {
+            // If the agent has already reported this phase as 'complete', advance
+            // its visual state to 'done' so the tracker doesn't look frozen while
+            // waiting for the agent to start the next phase (e.g. after
+            // implement-submission completes but before address-feedback starts).
+            state = entry?.latestStatus === 'complete' ? 'done' : 'current';
+        }
+        else if (entry?.latestStatus === 'complete' || (currentIndex >= 0 && index < currentIndex && entry)) {
+            state = 'done';
+        }
+        else {
+            state = 'upcoming';
+        }
+        return { phaseId: phase.id, label: phase.label, state };
+    });
+}
+// ---------------------------------------------------------------------------
+// Agent install helpers (shared with first-run; duplicated here to avoid
+// the session-key dependency in that module's public API).
+// ---------------------------------------------------------------------------
+const HUB_TO_FIRST_RUN_ID = {
+    claude: 'claude-code',
+    codex: 'codex',
+    gemini: 'gemini-cli',
+    copilot: 'copilot-cli',
+};
+function hubAgentOption(hubId) {
+    const frId = HUB_TO_FIRST_RUN_ID[hubId];
+    return frId ? types_1.FIRST_RUN_AGENT_OPTIONS.find((o) => o.id === frId) : undefined;
+}
+/**
+ * Issue #747: after the Hub installs an agent CLI, run the `add-ide` command for that agent so the
+ * FRAIM MCP (plus slash commands / rules) is wired into its config and its first run works.
+ * Previously the install only ran `npm install -g` + a version probe, so the agent launched with
+ * no `fraim` MCP server. This invokes the same `runAddIDE` the `fraim add-ide` CLI runs — scoped to
+ * the just-installed agent — rather than re-implementing the MCP-config write.
+ *
+ * `runAddIDE` reads the FRAIM key from ~/.fraim/config.json (written by setup/first-run) and
+ * `process.exit(1)`s when it is missing. We guard on that here via the exported `loadGlobalConfig`
+ * so a missing key degrades to a logged no-op instead of terminating the long-running Hub server.
+ * `skipTokenPrompts` keeps the run fully non-interactive.
+ */
+async function configureFraimForHubAgent(hubId) {
+    const frId = HUB_TO_FIRST_RUN_ID[hubId];
+    if (!frId)
+        return { configured: false, error: `Unknown hub agent: ${hubId}` };
+    try {
+        const { runAddIDE, loadGlobalConfig } = await Promise.resolve().then(() => __importStar(require('../cli/commands/add-ide')));
+        const config = await loadGlobalConfig();
+        if (!config?.fraimKey) {
+            return { configured: false, error: 'No FRAIM key in ~/.fraim/config.json; run `fraim setup` first.' };
+        }
+        // `frId` (e.g. 'claude-code', 'codex', 'gemini-cli', 'copilot-cli') is a valid add-ide
+        // `--ide` name/alias; runAddIDE resolves and configures it even when not yet detected.
+        await runAddIDE({ ide: frId, skipTokenPrompts: true });
+        return { configured: true, ideName: frId };
+    }
+    catch (e) {
+        return { configured: false, error: e instanceof Error ? e.message : String(e) };
+    }
+}
+function hubCommandVersion(command, extraBinDirs, basePath) {
+    const executable = process.platform === 'win32' ? 'cmd.exe' : command;
+    const args = process.platform === 'win32'
+        ? ['/d', '/s', '/c', `${command} --version`]
+        : ['--version'];
+    const pathValue = extraBinDirs && extraBinDirs.length > 0
+        ? (0, managed_agent_paths_1.appendBinDirsToPath)(basePath ?? process.env.PATH, extraBinDirs)
+        : basePath;
+    const env = pathValue === undefined ? undefined : { ...process.env, PATH: pathValue };
+    const result = (0, child_process_1.spawnSync)(executable, args, { encoding: 'utf8', timeout: 5000, ...(env ? { env } : {}) });
+    if (result.status !== 0 || result.error)
+        return null;
+    const raw = (result.stdout || result.stderr || '').trim();
+    return raw || null;
+}
+function hubRunProcess(command, args, env) {
+    return new Promise((resolve, reject) => {
+        const [realCmd, realArgs] = process.platform === 'win32'
+            ? ['cmd.exe', ['/d', '/s', '/c', command, ...args]]
+            : [command, args];
+        const childEnv = { ...process.env };
+        for (const [key, value] of Object.entries(env || {})) {
+            if (value === undefined)
+                delete childEnv[key];
+            else
+                childEnv[key] = value;
+        }
+        const child = (0, child_process_1.spawn)(realCmd, realArgs, {
+            env: childEnv,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (d) => { stdout += d.toString(); });
+        child.stderr.on('data', (d) => { stderr += d.toString(); });
+        child.on('close', (code) => {
+            if (code === 0)
+                resolve({ stdout, stderr });
+            else
+                reject(new Error(stderr || `Process exited with code ${code}`));
+        });
+        child.on('error', reject);
+    });
+}
+function hubOpenTerminal(command) {
+    if (process.platform === 'win32') {
+        (0, child_process_1.spawn)('cmd.exe', ['/c', 'start', 'cmd.exe', '/k', command], { detached: true, stdio: 'ignore' }).unref();
+        return;
+    }
+    if (process.platform === 'darwin') {
+        const script = `tell application "Terminal" to do script "${command.replace(/"/g, '\\"')}"`;
+        (0, child_process_1.spawn)('osascript', ['-e', script], { detached: true, stdio: 'ignore' }).unref();
+        return;
+    }
+    const linux = [
+        ['gnome-terminal', ['--', 'bash', '-c', `${command}; exec bash`]],
+        ['xterm', ['-e', `bash -c '${command}; exec bash'`]],
+        ['konsole', ['--noclose', '-e', 'bash', '-c', command]],
+        ['x-terminal-emulator', ['-e', `bash -c '${command}; exec bash'`]],
+    ];
+    for (const [term, args] of linux) {
+        if ((0, child_process_1.spawnSync)('which', [term], { encoding: 'utf8' }).status === 0) {
+            (0, child_process_1.spawn)(term, args, { detached: true, stdio: 'ignore' }).unref();
+            return;
+        }
+    }
+    (0, child_process_1.spawn)('bash', ['-c', command], { detached: true, stdio: 'ignore' }).unref();
+}
+function pathWithin(root, candidate) {
+    const resolvedRoot = path_1.default.resolve(root);
+    const resolvedCandidate = path_1.default.resolve(candidate);
+    return resolvedCandidate === resolvedRoot || resolvedCandidate.startsWith(resolvedRoot + path_1.default.sep);
+}
+function resolveSafeArtifactPath(rawPath, projectPath) {
+    const trimmed = rawPath.trim();
+    if (!trimmed || /^https?:\/\//i.test(trimmed))
+        return null;
+    const resolved = path_1.default.resolve(path_1.default.isAbsolute(trimmed) ? trimmed : path_1.default.join(projectPath, trimmed));
+    const safeRoots = [
+        path_1.default.resolve(projectPath),
+        path_1.default.resolve(os_1.default.homedir()),
+    ];
+    return safeRoots.some((root) => pathWithin(root, resolved)) ? resolved : null;
+}
+// Builds the OS "open this file with its default app" invocation. Exported for regression
+// testing (see tests/isolated/test-ai-hub-open-file.ts).
+//
+// Windows contract: the path travels via an ENVIRONMENT VARIABLE, never as a trailing `-Command`
+// argument. PowerShell re-parses trailing args on its own command line and mangles Windows paths —
+// it strips backslashes and truncates at the first space — so `Invoke-Item -LiteralPath $p`
+// received a broken path (e.g. `C:UserssidmaOneDriveCodeDrug`) and failed for every real artifact
+// path, which is why the Hub's "open file" button did nothing. `$env:FRAIM_OPEN_PATH` is read
+// directly from the environment and is not re-parsed, so the path arrives intact (verified against
+// paths containing spaces and backslashes).
+function buildOpenFileInvocation(filePath, platform = process.platform) {
+    if (platform === 'win32') {
+        return {
+            command: 'powershell.exe',
+            args: [
+                '-NoProfile',
+                '-ExecutionPolicy',
+                'Bypass',
+                '-Command',
+                'try { Invoke-Item -LiteralPath $env:FRAIM_OPEN_PATH; exit 0 } catch { Write-Error $_; exit 1 }',
+            ],
+            envPatch: { FRAIM_OPEN_PATH: filePath },
+        };
+    }
+    return {
+        command: platform === 'darwin' ? 'open' : 'xdg-open',
+        args: [filePath],
+        envPatch: {},
+    };
+}
+function hubOpenFile(filePath) {
+    return new Promise((resolve, reject) => {
+        const { command, args, envPatch } = buildOpenFileInvocation(filePath);
+        const child = (0, child_process_1.spawn)(command, args, {
+            stdio: ['ignore', 'ignore', 'pipe'],
+            windowsHide: process.platform === 'win32',
+            env: { ...process.env, ...envPatch },
+        });
+        let stderr = '';
+        child.stderr?.on('data', (chunk) => {
+            stderr += String(chunk);
+        });
+        child.on('error', reject);
+        child.on('close', (code) => {
+            if (code === 0) {
+                resolve();
+                return;
+            }
+            reject(new Error(stderr.trim() || `Open command failed with exit code ${code ?? 'unknown'}.`));
+        });
+    });
+}
+function buildManagedLoginCommand(command) {
+    const managedPath = (0, managed_agent_paths_1.buildPathWithManagedAgentBins)(process.env.PATH);
+    if (process.platform === 'win32') {
+        return `set "PATH=${managedPath}" && ${command}`;
+    }
+    return `export PATH="${managedPath}"; ${command}`;
+}
+function getUserHubDir() {
+    return path_1.default.join(os_1.default.homedir(), '.fraim');
+}
+function ensureDirectoryPath(projectPath) {
+    const trimmed = (projectPath || '').trim();
+    if (!trimmed) {
+        throw new Error('Project path is required.');
+    }
+    const resolved = path_1.default.resolve(trimmed);
+    const stat = fs_1.default.existsSync(resolved) ? fs_1.default.statSync(resolved) : null;
+    if (!stat || !stat.isDirectory()) {
+        throw new Error('Project path must point to an existing directory.');
+    }
+    return resolved;
+}
+function normalizedDirectoryPath(projectPath) {
+    const resolved = path_1.default.resolve(projectPath);
+    return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+function sameDirectoryPath(left, right) {
+    return normalizedDirectoryPath(left) === normalizedDirectoryPath(right);
+}
+function deploymentProjectFilter(rawProjectPath, fallbackProjectPath) {
+    return ensureDirectoryPath(typeof rawProjectPath === 'string' && rawProjectPath.trim() ? rawProjectPath : fallbackProjectPath);
+}
+function deploymentBelongsToProject(deployment, projectPath, fallbackProjectPath) {
+    const deploymentProjectPath = typeof deployment.projectPath === 'string' && deployment.projectPath.trim()
+        ? deployment.projectPath
+        : fallbackProjectPath;
+    return sameDirectoryPath(deploymentProjectPath, projectPath);
+}
+// ---------------------------------------------------------------------------
+// Issue #512 (S3) — Hub bootstrap projection helpers.
+// ---------------------------------------------------------------------------
+// Issue #750: the Hub's identity — for persona/entitlement resolution, the
+// displayed "signed in as" email, and personal (L1) learnings keying — comes
+// from ~/.fraim/config.json's apiKey (architecture.md §4.3.4's "Global config
+// stores only identity"), the same credential every other FRAIM CLI/MCP
+// surface already reads via readUserFraimConfig(). There is no fallback: a
+// missing or invalid apiKey resolves to null (rendered as a "not connected"
+// state), never a guess from another local file.
+function resolveApiKey() {
+    return (0, user_config_1.readUserFraimConfig)().apiKey;
+}
+// Read persisted Get-started step states from ~/.fraim/install-state.json
+// (architecture §3.5) and ~/.fraim/preferences.json. Returns a partial — any
+// missing key falls back to derivation. Persisted `true` is sticky so the rail
+// never re-shows once a step is completed (R13.4).
+function readPersistedFirstRun() {
+    const out = {};
+    const apply = (source) => {
+        if (!source || typeof source !== 'object')
+            return;
+        // Support both a flat shape ({ company: true }) and a nested
+        // ({ firstRun: { company: true } }) one — the rail mirrors to whichever.
+        const nested = source.firstRun;
+        const candidates = [source, nested].filter((c) => !!c && typeof c === 'object');
+        for (const c of candidates) {
+            for (const key of ['install', 'company', 'hire', 'project']) {
+                if (c[key] === true)
+                    out[key] = true;
+            }
+        }
+    };
+    const readJson = (fileName) => {
+        try {
+            const p = path_1.default.join((0, project_fraim_paths_1.getUserFraimDirPath)(), fileName);
+            if (!fs_1.default.existsSync(p))
+                return null;
+            return JSON.parse(fs_1.default.readFileSync(p, 'utf8'));
+        }
+        catch {
+            return null;
+        }
+    };
+    apply(readJson('install-state.json'));
+    apply(readJson('preferences.json'));
+    return out;
+}
+// Count .md files recursively under a directory (skills/rules catalog counts).
+function countMarkdownFilesRecursive(dirPath) {
+    if (!fs_1.default.existsSync(dirPath))
+        return 0;
+    let total = 0;
+    try {
+        for (const entry of fs_1.default.readdirSync(dirPath, { withFileTypes: true })) {
+            const child = path_1.default.join(dirPath, entry.name);
+            if (entry.isDirectory()) {
+                total += countMarkdownFilesRecursive(child);
+            }
+            else if (entry.isFile() && entry.name.endsWith('.md')) {
+                total += 1;
+            }
+        }
+    }
+    catch {
+        // ignore unreadable dirs
+    }
+    return total;
+}
+class AiHubServer {
+    get hubBase() {
+        return process.env.FRAIM_HUB_BASE_URL || `http://127.0.0.1:${this.httpPort}`;
+    }
+    constructor(options = {}) {
+        this.app = (0, express_1.default)();
+        this.runRegistry = new AiHubRunRegistry();
+        this.cronHandles = new Map();
+        this.projectPath = options.projectPath || process.cwd();
+        this.preferencesStore = options.preferencesStore || new preferences_1.AiHubPreferencesStore();
+        this.conversationStore = options.conversationStore || new conversation_store_1.AiHubConversationStore();
+        this.configuredAgentStore = options.configuredAgentStore || new configured_agents_1.AiHubConfiguredAgentStore();
+        this.wordTaskpaneDir = options.wordTaskpaneDir ?? resolveWordTaskpaneDir(this.projectPath);
+        this.folderPicker = options.folderPicker ?? pickProjectPath;
+        this.httpsPort = options.httpsPort;
+        this.certBundle = options.certBundle;
+        this.managedBrowser = options.managedBrowser || new managed_browser_1.ManagedBrowser({
+            channel: process.env.FRAIM_BROWSER_CHANNEL || 'auto',
+            port: process.env.FRAIM_BROWSER_PORT ? Number(process.env.FRAIM_BROWSER_PORT) : undefined,
+            userDataDir: process.env.FRAIM_BROWSER_USER_DATA_DIR || undefined,
+            explicitPath: process.env.FRAIM_BROWSER_PATH || undefined,
+        });
+        this.hostRuntime = options.hostRuntime || (process.env.FRAIM_AI_HUB_FAKE_HOST === '1' ? new hosts_1.FakeHostRuntime() : new hosts_1.CliHostRuntime());
+        // Issue #701 / #749: the AI Hub is a loopback companion that runs on user machines and
+        // never touches a database. Persona and manager-team state resolve from the hosted server
+        // through the remote gateway; the hosted server is the sole owner of DB access.
+        this.remoteGateway = options.remoteGateway ?? new remote_hub_gateway_1.HttpHubRemoteGateway();
+        this.deploymentStore = options.deploymentStore ?? new DeploymentStore();
+        this.hostConfigStore = options.hostConfigStore ?? new HostConfigStore();
+        this.app.use(express_1.default.json({ limit: '10mb' }));
+        // CORS + Chrome Private Network Access for browser extensions and Office add-in task panes
+        // calling the Hub from a public origin (word-edit.officeapps.live.com, etc.).
+        this.app.use((_req, res, next) => {
+            res.setHeader('Access-Control-Allow-Origin', '*');
+            res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, PATCH, DELETE, OPTIONS');
+            res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+            res.setHeader('Access-Control-Allow-Private-Network', 'true');
+            if (_req.method === 'OPTIONS') {
+                res.sendStatus(204);
+                return;
+            }
+            next();
+        });
+        // Payment success redirect: sync entitlement then bounce to the hub.
+        // Stripe redirects here after a completed persona-hire checkout.
+        this.app.get('/ai-hub/payment-success', (req, res) => {
+            const email = req.query['email'];
+            // Persist the buyer's email so bootstrap can look up entitlements by userId.
+            if (email) {
+                try {
+                    const prefsPath = path_1.default.join((0, project_fraim_paths_1.getUserFraimDirPath)(), 'preferences.json');
+                    const existing = fs_1.default.existsSync(prefsPath)
+                        ? JSON.parse(fs_1.default.readFileSync(prefsPath, 'utf8'))
+                        : {};
+                    fs_1.default.writeFileSync(prefsPath, JSON.stringify({ ...existing, userEmail: email }, null, 2));
+                }
+                catch (err) {
+                    console.warn('[ai-hub] could not persist userEmail:', err);
+                }
+            }
+            // Issue #749: the Hub holds no DB. Entitlement is synced authoritatively by the backend
+            // Stripe webhook; the Hub re-reads status via the remote gateway on the next bootstrap.
+            res.redirect('/ai-hub/?hired=1');
+        });
+        this.app.use('/ai-hub', express_1.default.static(resolveAiHubPublicDir()));
+        // Issue #489: Serve the Word task pane assets at /word-taskpane/*.
+        // Office JS appends ?_host_Info=Word$Win32$... to every request — we must
+        // strip the query string before resolving the file path, otherwise every
+        // request returns 404.  express.static does NOT strip query strings, so we
+        // use a custom middleware that resolves the pathname manually.
+        if (this.wordTaskpaneDir) {
+            const wordDir = this.wordTaskpaneDir; // capture for closure
+            this.app.use('/word-taskpane', (req, res, next) => {
+                // Chrome Private Network Access: public origin (word-edit.officeapps.live.com)
+                // loading a private-network resource (localhost) requires this header on both the
+                // preflight OPTIONS response and the final GET response.
+                res.setHeader('Access-Control-Allow-Private-Network', 'true');
+                res.setHeader('Access-Control-Allow-Origin', '*');
+                res.setHeader('Access-Control-Allow-Methods', 'GET, OPTIONS');
+                res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+                if (req.method === 'OPTIONS') {
+                    res.sendStatus(204);
+                    return;
+                }
+                // Strip query string — Office appends ?_host_Info=Word$Win32$... to every request
+                const { pathname } = new URL(req.url, 'http://localhost');
+                const target = pathname === '/' || pathname === '' ? '/taskpane.html' : pathname;
+                // Prevent path traversal
+                const safeTarget = path_1.default.normalize(target).replace(/^(\.\.(\/|\\|$))+/, '');
+                const filePath = path_1.default.join(wordDir, safeTarget);
+                if (!filePath.startsWith(wordDir + path_1.default.sep) && filePath !== wordDir) {
+                    res.status(403).end();
+                    return;
+                }
+                const ext = path_1.default.extname(filePath);
+                const contentTypes = {
+                    '.html': 'text/html; charset=utf-8',
+                    '.css': 'text/css; charset=utf-8',
+                    '.js': 'application/javascript; charset=utf-8',
+                    '.xml': 'application/xml; charset=utf-8',
+                };
+                const contentType = contentTypes[ext] || 'text/plain; charset=utf-8';
+                fs_1.default.readFile(filePath, (err, data) => {
+                    if (err) {
+                        next(); // fall through to 404
+                        return;
+                    }
+                    res.setHeader('Content-Type', contentType);
+                    res.end(data);
+                });
+            });
+        }
+        this.app.get(['/word-taskpane/config.js', '/powerpoint-taskpane/config.js'], (_req, res) => {
+            const port = this.httpPort || 43091;
+            const origin = `http://127.0.0.1:${port}`;
+            res.setHeader('Content-Type', 'application/javascript; charset=utf-8');
+            res.setHeader('Access-Control-Allow-Origin', '*');
+            res.end(`window.FRAIM_HUB_ORIGIN=${JSON.stringify(origin)};\n`);
+        });
+        this.app.get('/health', (_req, res) => {
+            res.json({ status: 'ok', service: 'fraim-ai-hub' });
+        });
+        // Extended health endpoint for trigger surfaces (browser extension, Office add-ins, tray)
+        this.app.get('/api/health', (_req, res) => {
+            res.json({ status: 'ok', service: 'fraim-ai-hub' });
+        });
+        // Issue #659: Inbound auth middleware for remote-exposed hubs.
+        // Activated only when FRAIM_HUB_AUTH_TOKEN env var is set. Gates all
+        // /api/ai-hub/* routes. /health and /api/health are registered above
+        // this block and are never gated.
+        if (process.env.FRAIM_HUB_AUTH_TOKEN) {
+            const expectedToken = process.env.FRAIM_HUB_AUTH_TOKEN;
+            this.app.use('/api/ai-hub', (req, res, next) => {
+                const token = req.headers['x-hub-auth'];
+                if (typeof token !== 'string' ||
+                    token.length !== expectedToken.length ||
+                    !(0, crypto_1.timingSafeEqual)(Buffer.from(token), Buffer.from(expectedToken))) {
+                    res.status(401).json({ error: 'Unauthorized' });
+                    return;
+                }
+                next();
+            });
+        }
+        this.registerRoutes();
+    }
+    getApp() {
+        return this.app;
+    }
+    async start(port) {
+        this.httpPort = port;
+        await new Promise((resolve, reject) => {
+            this.httpServer = this.app.listen(port, '127.0.0.1');
+            this.httpServer.once('listening', () => resolve());
+            this.httpServer.once('error', (error) => reject(error));
+        });
+        // #521: publish where the shared browser lives + how to bring it up, so every
+        // agent inherits them. The browser is NOT launched here — it's started lazily
+        // (the browser-use skill POSTs /browser/start when it actually needs one, which
+        // also relaunches it if the manager closed the window). Deterministic endpoint,
+        // so it's known even before the browser is running.
+        process.env.FRAIM_BROWSER_CDP_ENDPOINT = this.managedBrowser.cdpEndpoint();
+        process.env.FRAIM_HUB_BASE_URL = `http://127.0.0.1:${port}`;
+        // Issue #578: rehydrate active scheduled deployments from disk.
+        this.rehydrateScheduledDeployments();
+        // Start HTTPS server when a cert bundle and port are provided.
+        // Word Online requires HTTPS; the HTTPS server shares the same Express app
+        // so all routes (including /word-taskpane/*) are available over both protocols.
+        if (this.httpsPort && this.certBundle) {
+            await new Promise((resolve, reject) => {
+                this.httpsServer = https_1.default.createServer({ key: this.certBundle.key, cert: this.certBundle.cert }, this.app);
+                this.httpsServer.listen(this.httpsPort, '127.0.0.1');
+                this.httpsServer.once('listening', () => resolve());
+                this.httpsServer.once('error', (error) => reject(error));
+            });
+        }
+        // #521: when the shared browser is enabled, bring it up at boot so the CDP
+        // endpoint is already published when the first run spawns. Best-effort — a
+        // missing browser must not stop the Hub from serving.
+        if (process.env.FRAIM_BROWSER_ENABLED === '1') {
+            try {
+                const r = await this.ensureManagedBrowser();
+                console.log(`[ai-hub] shared browser ready at ${r.endpoint}${r.reused ? ' (reused)' : ''}`);
+            }
+            catch (err) {
+                console.warn('[ai-hub] shared browser not started:', err instanceof Error ? err.message : err);
+            }
+        }
+    }
+    async stop() {
+        const closeServer = (srv) => new Promise((resolve, reject) => {
+            const closable = srv;
+            closable.closeIdleConnections?.();
+            const forceCloseTimer = setTimeout(() => {
+                closable.closeIdleConnections?.();
+                closable.closeAllConnections?.();
+            }, 250);
+            srv.close((error) => {
+                clearTimeout(forceCloseTimer);
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            });
+        });
+        if (this.httpsServer) {
+            await closeServer(this.httpsServer);
+            this.httpsServer = undefined;
+        }
+        if (this.httpServer) {
+            await closeServer(this.httpServer);
+            this.httpServer = undefined;
+        }
+        // Issue #578: stop all active scheduled deployments.
+        for (const [, task] of this.cronHandles) {
+            task.stop();
+        }
+        this.cronHandles.clear();
+        // #521: tear down the shared browser if WE launched it (stop() no-ops on a
+        // browser the manager owns).
+        this.managedBrowser.stop();
+    }
+    getHttpsPort() { return this.httpsPort; }
+    knownProjects(projectPath, extras = []) {
+        const normalizedProjectPath = path_1.default.resolve(projectPath || this.projectPath);
+        const preferences = this.preferencesStore.load(normalizedProjectPath);
+        const conversationProjects = this.conversationStore.listProjectPaths().map((folderPath) => ({ folderPath }));
+        return (0, preferences_1.normalizeAiHubProjectList)([
+            ...(preferences.projects || []),
+            ...conversationProjects,
+            ...extras,
+        ], normalizedProjectPath, { removedProjectPaths: preferences.removedProjectPaths || [] });
+    }
+    async bootstrapResponse(projectPath) {
+        const normalizedProjectPath = path_1.default.resolve(projectPath || this.projectPath);
+        const employees = this.hostRuntime.detectEmployees();
+        const configuredAgents = this.configuredAgentStore
+            .listWithDefaults(employees)
+            .map((agent) => (0, configured_agents_1.projectConfiguredAgent)(agent, employees));
+        let preferences = this.preferencesStore.load(normalizedProjectPath);
+        // If the stored employee isn't available on this machine, auto-select the
+        // first available one so the Hub never opens showing "(unavailable)".
+        const storedAvailable = employees.find((e) => e.id === preferences.employeeId)?.available ?? false;
+        if (!storedAvailable) {
+            const firstAvailable = employees.find((e) => e.available);
+            if (firstAvailable) {
+                preferences = { ...preferences, employeeId: firstAvailable.id };
+                this.preferencesStore.save(preferences);
+            }
+        }
+        const project = (0, catalog_1.summarizeProject)(normalizedProjectPath);
+        const catalogOptions = { includeRegistry: true };
+        const rawJobs = (0, catalog_1.discoverEmployeeJobs)(normalizedProjectPath, catalogOptions);
+        // Issue #566 (R7): jobs already carry `personalized` from catalog discovery
+        // (true for the fraim/personalized-employee layer). The Hub renders a plain
+        // "Personalized" marking from that flag — no author/attribution is tracked.
+        const jobs = rawJobs
+            .filter((job) => !FRAIM_INTERNAL_JOB_IDS.has(job.id))
+            .map((job) => ({
+            ...job,
+            requiredPersonaKey: getProtectedPersonaForHubJob(job.id),
+        }));
+        const managerTemplates = (0, catalog_1.discoverManagerTemplates)(normalizedProjectPath, catalogOptions);
+        // Issue #750: the apiKey always comes from ~/.fraim/config.json — no header
+        // override, no ai-hub-state.json copy, no fallback chain.
+        const resolvedApiKey = resolveApiKey();
+        const { personas, subscriptionActive, workspaceId, userKey } = await this.computePersonas(resolvedApiKey);
+        const managerTeam = await this.computeManagerTeam(resolvedApiKey);
+        const resolvedUserEmail = userKey ?? null;
+        const projects = this.knownProjects(normalizedProjectPath);
+        preferences = { ...preferences, projectPath: normalizedProjectPath, projects };
+        this.preferencesStore.save(preferences);
+        // Issue #347: enrich the activeRun the same way GET /runs/:id does
+        // so the bootstrap surface (used on first paint) carries stages and
+        // live totals — not just the raw run state.
+        const latest = this.runRegistry.listLatest();
+        const activeRun = latest ? this.enrichRunForResponse(latest) : undefined;
+        return {
+            title: 'AI Hub',
+            remoteBaseUrl: (0, remote_hub_gateway_1.resolveFraimRemoteUrl)(),
+            // #755: the running build version, so the account menu can show it and flag
+            // when a newer version is available (see GET /api/ai-hub/version for `latest`).
+            version: (0, version_utils_1.getFraimVersion)(),
+            project,
+            // Issue #750: `apiKey` is no longer a persisted AiHubPreferences field —
+            // it is overlaid on the wire response only, freshly resolved from
+            // ~/.fraim/config.json, so public/ai-hub/script.js's existing
+            // tfConnectedApiKey()/tfConnectedSurfaceUrl read path needs no changes.
+            preferences: { ...preferences, apiKey: resolvedApiKey },
+            categories: (0, catalog_1.getAiHubCategories)(normalizedProjectPath, catalogOptions),
+            jobs,
+            managerTemplates,
+            employees,
+            configuredAgents,
+            personas,
+            subscriptionActive,
+            activeRun,
+            projects,
+            // Issue #512 (S3) — additive manager-flow projections.
+            firstRun: this.computeFirstRun(normalizedProjectPath, jobs.length, personas),
+            teamContext: this.computeTeamContext(normalizedProjectPath),
+            brain: this.computeBrain(normalizedProjectPath, jobs.length + managerTemplates.length, resolvedUserEmail),
+            // #533/#750: the resolved account email (from the same ~/.fraim/config.json
+            // apiKey used for personas above), or null when not connected — so the
+            // profile card and personas can never disagree about who's signed in.
+            userEmail: resolvedUserEmail,
+            // #744: the org cobrand identity (name/color/logo) from the org context
+            // storage, or null when unset so the Hub falls back to FRAIM identity.
+            orgBrand: (0, learning_context_builder_1.readOrgBrand)(normalizedProjectPath),
+            assignments: { byProject: {}, source: 'client-localStorage' },
+            // Issue #538 — source of truth for the "Hire a human manager" UI. Lazy-required
+            // (not a top-level import) so the lightweight client CLI paths that import this
+            // module for findAvailablePort do not eagerly load server-only config (repro #422).
+            managerHiring: buildHubManagerHiringCatalog(),
+            // Issue #540: server-authoritative manager team (personas assigned by this manager).
+            managerTeam,
+        };
+    }
+    configuredAgentsForCurrentMachine(employees = this.hostRuntime.detectEmployees()) {
+        return this.configuredAgentStore.listWithDefaults(employees);
+    }
+    resolveLaunchAgent(configuredAgentId, hostId, employees = this.hostRuntime.detectEmployees()) {
+        const resolved = (0, configured_agents_1.resolveConfiguredAgentForHost)(configuredAgentId, hostId, this.configuredAgentsForCurrentMachine(employees));
+        const check = (0, configured_agents_1.checkConfiguredAgentAvailability)(resolved.agent, employees);
+        if (check.reasons.length) {
+            throw new Error(`${resolved.agent.label} is not ready: ${check.reasons.join(' ')}`);
+        }
+        const env = (0, configured_agents_1.resolveConfiguredAgentEnv)(resolved.agent);
+        return {
+            hostId: resolved.baseHostId,
+            agent: resolved.agent,
+            launchContext: { agent: resolved.agent, env },
+        };
+    }
+    isTrustedHubOrigin(req) {
+        const origin = req.get('origin');
+        if (!origin)
+            return true;
+        try {
+            const parsed = new URL(origin);
+            const hostname = parsed.hostname.toLowerCase();
+            const port = parsed.port ? Number(parsed.port) : (parsed.protocol === 'https:' ? 443 : 80);
+            const trustedHost = hostname === '127.0.0.1' || hostname === 'localhost' || hostname === '::1';
+            return trustedHost && (port === this.httpPort || port === this.httpsPort);
+        }
+        catch {
+            return false;
+        }
+    }
+    requireTrustedHubOrigin(req, res) {
+        if (this.isTrustedHubOrigin(req))
+            return true;
+        res.status(403).json({ error: 'Configured agent management is only allowed from the local Hub origin.' });
+        return false;
+    }
+    conversationRecordFromRun(run) {
+        const lastUpdatedAt = run.updatedAt || new Date().toISOString();
+        const stages = deriveStages(run, run.projectPath);
+        return {
+            id: run.conversationId || run.id,
+            projectPath: path_1.default.resolve(run.projectPath),
+            title: run.conversationTitle || run.jobTitle || run.jobId,
+            jobId: run.jobId,
+            jobTitle: run.jobTitle || run.jobId,
+            agentName: run.hostId,
+            configuredAgentId: run.configuredAgentId,
+            configuredAgentLabel: run.configuredAgentLabel,
+            baseHostId: run.baseHostId,
+            personaKey: run.personaKey ?? null,
+            runId: run.id,
+            sessionId: run.sessionId || null,
+            status: run.status,
+            createdAt: run.createdAt,
+            lastUpdatedAt,
+            messages: run.messages.map((message) => ({
+                role: message.role,
+                text: message.text,
+                at: Date.parse(message.createdAt) || Date.now(),
+            })),
+            events: run.events.map((event) => ({
+                channel: event.channel,
+                text: event.text,
+            })),
+            artifacts: run.artifacts || [],
+            reviewHandoff: run.reviewHandoff || null,
+            delegation: run.delegation || null,
+            delegationTaskId: run.delegationTaskId || null,
+            managedByRunId: run.managedByRunId || null,
+            managedByPersonaKey: run.managedByPersonaKey || null,
+            humanCoachingDisabled: run.humanCoachingDisabled || false,
+            managedReviewStatus: run.managedReviewStatus || null,
+            compareMode: run.runRole === 'fraim' && run.compareRunId ? 'ab' : undefined,
+            compareRunId: run.compareRunId || null,
+            // Issue #578: preserve trigger source so the UI can render the chip.
+            sourceTrigger: run.sourceTrigger,
+            // Issue #708: carry the invocation scope so the record lands in (and is keyed to)
+            // the right bucket. Falls back to the legacy client `invokedArea` when present.
+            scope: run.scope
+                ?? run.invokedArea
+                ?? 'project',
+            run: {
+                stages,
+                currentPhase: run.currentPhase || null,
+                phaseHistory: run.phaseHistory || [],
+                totals: run.totals || null,
+                runDiscriminant: run.runDiscriminant || null,
+            },
+        };
+    }
+    persistRunConversation(run, activeId) {
+        try {
+            // Issue #708: route the record to its scope bucket (manager/company runs get a
+            // project-independent home); project runs continue to key by project path.
+            const record = this.conversationRecordFromRun(run);
+            const key = (0, conversation_store_1.conversationScopeKey)(record.scope, run.projectPath);
+            this.conversationStore.upsertConversation(key, record, activeId);
+        }
+        catch (error) {
+            console.warn('[ai-hub] conversation store write failed:', error instanceof Error ? error.message : error);
+        }
+    }
+    // Issue #512 (S3, R13) — derive the four Get-started step states, then let any
+    // persisted `true` in ~/.fraim/{install-state,preferences}.json override the
+    // derivation (so a completed step stays completed even if its signal vanishes).
+    maybeStartDelegatedChildRuns(managerRun) {
+        const ledger = managerRun.delegation;
+        if (!ledger || managerRun.managedByRunId)
+            return;
+        managerRun.orchestratedDelegationTaskIds = managerRun.orchestratedDelegationTaskIds || [];
+        const started = new Set(managerRun.orchestratedDelegationTaskIds);
+        for (const task of ledger.tasks || []) {
+            if (!task.taskId || started.has(task.taskId))
+                continue;
+            if (!task.jobId || !this.delegationDependenciesSatisfied(ledger, task.dependsOn || []))
+                continue;
+            if (!task.personaKey)
+                task.personaKey = getProtectedPersonaForHubJob(task.jobId);
+            this.startDelegatedChildRun(managerRun, task.taskId);
+            started.add(task.taskId);
+            managerRun.orchestratedDelegationTaskIds.push(task.taskId);
+        }
+    }
+    delegationDependenciesSatisfied(ledger, dependsOn) {
+        if (!dependsOn.length)
+            return true;
+        const terminal = new Set(['reviewed', 'completed']);
+        return dependsOn.every((dependency) => {
+            const matched = ledger.tasks.find((task) => task.taskId === dependency || task.jobId === dependency);
+            return !!matched && terminal.has(matched.status);
+        });
+    }
+    startDelegatedChildRun(managerRun, taskId) {
+        const ledger = managerRun.delegation;
+        const task = ledger?.tasks.find((entry) => entry.taskId === taskId);
+        if (!ledger || !task || !task.jobId)
+            return;
+        if (!task.personaKey)
+            task.personaKey = getProtectedPersonaForHubJob(task.jobId);
+        const resolvedJob = this.resolveHubJob(managerRun.projectPath, task.jobId);
+        if (!resolvedJob) {
+            task.status = 'blocked';
+            task.latestSummary = `Delegation blocked: job "${task.jobId}" is not available in this project.`;
+            managerRun.events.push((0, hosts_1.createHubEvent)('system', task.latestSummary));
+            this.persistRunConversation(managerRun, managerRun.conversationId || managerRun.id);
+            return;
+        }
+        const childConversationId = task.conversationId || `${managerRun.id}-${task.taskId}`;
+        const now = new Date().toISOString();
+        const childInstructions = [
+            task.instructions || task.latestSummary || `Complete the delegated workstream: ${task.title}.`,
+            '',
+            task.personaKey
+                ? `You are working as ${task.personaKey} for the manager job.`
+                : 'You are working as the specialist assigned by this delegated job.',
+            `Parent objective: ${ledger.objective}.`,
+            task.reviewJobId ? `Manager review route: this output should be reviewed using ${task.reviewJobId}.` : '',
+            'Submit a concise deliverable summary and any artifact references back to Mandy.',
+            'This is a delegated subtask, not an end-to-end FRAIM submission workflow. After you provide the deliverable for Mandy, stop. Do not create evidence docs, open or update PRs, update GitHub issues, or ask the human for review.',
+            'Do not ask the human for coaching; Mandy is your manager for this workstream.',
+        ].join('\n');
+        const prepared = this.prepareStartPayload(managerRun.projectPath, managerRun.hostId, task.jobId, childInstructions);
+        const childRun = {
+            id: (0, crypto_1.randomUUID)(),
+            conversationId: childConversationId,
+            conversationTitle: task.title,
+            jobTitle: task.title,
+            jobId: prepared.jobId || task.jobId,
+            hostId: managerRun.hostId,
+            configuredAgentId: managerRun.configuredAgentId,
+            configuredAgentLabel: managerRun.configuredAgentLabel,
+            baseHostId: managerRun.baseHostId,
+            projectPath: managerRun.projectPath,
+            status: 'running',
+            createdAt: now,
+            updatedAt: now,
+            messages: [(0, hosts_1.createHubMessage)('manager', `Mandy delegated: ${task.title}\n\n${childInstructions}`)],
+            events: [(0, hosts_1.createHubEvent)('system', `Mandy started delegated workstream ${task.taskId} for ${task.personaKey || task.jobId}.`)],
+            currentPhase: null,
+            phaseHistory: [],
+            totals: emptyTotals(),
+            lastStatusChangeAt: now,
+            personaKey: task.personaKey,
+            delegationTaskId: task.taskId,
+            managedByRunId: managerRun.id,
+            managedByPersonaKey: managerRun.personaKey || ledger.orchestratorPersonaKey || 'mandy',
+            humanCoachingDisabled: true,
+        };
+        task.runId = childRun.id;
+        task.conversationId = childConversationId;
+        task.status = 'running';
+        this.runRegistry.create(childRun, {});
+        this.persistRunConversation(childRun);
+        this.persistRunConversation(managerRun, managerRun.conversationId || managerRun.id);
+        const childLaunch = this.resolveLaunchAgent(managerRun.configuredAgentId, managerRun.hostId);
+        const child = this.hostRuntime.startRun(managerRun.hostId, managerRun.projectPath, prepared.message, {
+            onEvent: (event, channel) => {
+                this.runRegistry.update(childRun.id, (current) => {
+                    if (event.sessionId)
+                        current.sessionId = event.sessionId;
+                    appendHostMessage(current, managerRun.hostId, event, channel);
+                    if (event.raw) {
+                        current.events.push((0, hosts_1.createHubEvent)(channel, event.raw));
+                        applyReviewProjection(current, event.raw);
+                    }
+                    if (event.agentIdentity)
+                        applyAgentIdentitySignal(current, event.agentIdentity);
+                    if (event.fraimJob)
+                        this.applyFraimJobSignalToRun(current, event.fraimJob);
+                    if (event.seekMentoring)
+                        this.applySeekMentoringSignalToRun(current, event.seekMentoring);
+                    if (event.usage)
+                        applyUsageSignal(current, event.usage);
+                });
+                const updatedChild = this.runRegistry.get(childRun.id);
+                if (updatedChild)
+                    this.persistRunConversation(updatedChild);
+            },
+            onExit: (exitCode) => {
+                this.runRegistry.update(childRun.id, (current) => {
+                    current.exitCode = exitCode;
+                    current.status = exitCode === 0 ? 'completed' : 'failed';
+                    current.events.push((0, hosts_1.createHubEvent)('system', `Delegated workstream exited with code ${exitCode ?? 'unknown'}.`));
+                });
+                const updatedChild = this.runRegistry.get(childRun.id);
+                if (updatedChild) {
+                    this.persistRunConversation(updatedChild);
+                    this.markDelegatedChildSubmitted(managerRun.id, updatedChild);
+                    this.notifyManagerOfDelegatedChild(managerRun.id, updatedChild);
+                }
+                this.runRegistry.dispose(childRun.id);
+            },
+        }, startSessionSeedForHost(managerRun.hostId, childRun.id), childLaunch.launchContext);
+        this.runRegistry.attachChildIfRunning(childRun.id, child);
+    }
+    notifyManagerOfDelegatedChild(managerRunId, childRun) {
+        const managerRun = this.runRegistry.get(managerRunId);
+        if (!managerRun) {
+            childRun.events.push((0, hosts_1.createHubEvent)('system', 'Delegated deliverable could not be routed because the manager run is unavailable.'));
+            this.persistRunConversation(childRun);
+            return;
+        }
+        if (!managerRun.sessionId || managerRun.status === 'running') {
+            this.enqueueDelegatedReview(managerRun, childRun, !managerRun.sessionId ? 'manager session is unavailable' : 'manager is still running');
+            return;
+        }
+        const latest = [...(childRun.messages || [])].reverse().find((message) => message.role === 'employee')?.text || '';
+        const artifacts = childRun.reviewHandoff?.artifacts?.map((artifact) => artifact.label || artifact.path || artifact.url).filter(Boolean).join(', ') || 'none reported';
+        const reviewPrompt = [
+            `Delegated workstream submitted by ${childRun.personaKey || 'a peer agent'}: ${childRun.conversationTitle || childRun.jobTitle || childRun.jobId}.`,
+            `Status: ${childRun.status}.`,
+            `Latest deliverable summary: ${latest || 'No employee summary captured.'}`,
+            `Artifacts: ${artifacts}.`,
+            childRun.delegationTaskId ? this.delegatedReviewRouteLine(managerRun, childRun.delegationTaskId) : '',
+            '',
+            'As Mandy, review this child deliverable. If it is acceptable, say it is reviewed for synthesis. If it needs correction, write specific coaching feedback for that child workstream.',
+        ].join('\n');
+        this.continueManagerRunForDelegation(managerRun, reviewPrompt, `Mandy reviews ${childRun.conversationTitle || childRun.jobTitle || childRun.jobId}`, childRun);
+    }
+    delegatedReviewRouteLine(managerRun, taskId) {
+        const task = managerRun.delegation?.tasks.find((entry) => entry.taskId === taskId);
+        if (!task?.reviewJobId)
+            return '';
+        return `Declared manager review job: ${task.reviewJobId}${task.reviewType ? ` (${task.reviewType})` : ''}. Use that review standard when judging the deliverable.`;
+    }
+    enqueueDelegatedReview(managerRun, childRun, reason) {
+        managerRun.pendingDelegatedReviewChildRunIds = managerRun.pendingDelegatedReviewChildRunIds || [];
+        if (!managerRun.pendingDelegatedReviewChildRunIds.includes(childRun.id)) {
+            managerRun.pendingDelegatedReviewChildRunIds.push(childRun.id);
+            managerRun.events.push((0, hosts_1.createHubEvent)('system', `Delegated deliverable queued for Mandy review because ${reason}.`));
+        }
+        childRun.events.push((0, hosts_1.createHubEvent)('system', `Deliverable submitted to Mandy; review is queued because ${reason}.`));
+        this.persistRunConversation(managerRun, managerRun.conversationId || managerRun.id);
+        this.persistRunConversation(childRun);
+    }
+    drainPendingDelegatedReviews(managerRun) {
+        if (managerRun.status === 'running' || !managerRun.sessionId)
+            return;
+        const queue = managerRun.pendingDelegatedReviewChildRunIds || [];
+        while (queue.length > 0) {
+            const childRunId = queue.shift();
+            const childRun = this.runRegistry.get(childRunId);
+            if (!childRun || childRun.managedReviewStatus === 'reviewed')
+                continue;
+            managerRun.pendingDelegatedReviewChildRunIds = queue;
+            this.persistRunConversation(managerRun, managerRun.conversationId || managerRun.id);
+            this.notifyManagerOfDelegatedChild(managerRun.id, childRun);
+            return;
+        }
+        managerRun.pendingDelegatedReviewChildRunIds = queue;
+        this.persistRunConversation(managerRun, managerRun.conversationId || managerRun.id);
+    }
+    markDelegatedChildSubmitted(managerRunId, childRun) {
+        const managerRun = this.runRegistry.get(managerRunId);
+        if (!managerRun?.delegation)
+            return;
+        const task = managerRun.delegation.tasks.find((entry) => entry.taskId === childRun.delegationTaskId || entry.runId === childRun.id);
+        if (!task)
+            return;
+        task.status = childRun.status === 'completed' ? 'submitted' : 'failed';
+        const latest = [...(childRun.messages || [])].reverse().find((message) => message.role === 'employee')?.text || '';
+        if (latest)
+            task.latestSummary = latest;
+        if (childRun.reviewHandoff)
+            task.reviewHandoff = childRun.reviewHandoff;
+        const artifacts = childRun.reviewHandoff?.artifacts?.length ? childRun.reviewHandoff.artifacts : childRun.artifacts || [];
+        if (artifacts.length)
+            task.artifacts = artifacts;
+        this.persistRunConversation(managerRun, managerRun.conversationId || managerRun.id);
+    }
+    markDelegatedChildReviewed(childRun, managerRun) {
+        const reviewText = [...(managerRun.messages || [])].reverse().find((message) => message.role === 'employee')?.text || '';
+        childRun.managedReviewStatus = 'reviewed';
+        childRun.updatedAt = new Date().toISOString();
+        if (reviewText) {
+            childRun.messages.push((0, hosts_1.createHubMessage)('manager', `Mandy reviewed this workstream:\n\n${reviewText}`));
+        }
+        childRun.events.push((0, hosts_1.createHubEvent)('system', 'Mandy reviewed the delegated deliverable.'));
+        this.persistRunConversation(childRun);
+        const task = managerRun.delegation?.tasks.find((entry) => entry.taskId === childRun.delegationTaskId || entry.runId === childRun.id);
+        if (task) {
+            task.status = 'reviewed';
+            task.latestSummary = reviewText || task.latestSummary;
+            if (childRun.reviewHandoff)
+                task.reviewHandoff = childRun.reviewHandoff;
+            const artifacts = childRun.reviewHandoff?.artifacts?.length ? childRun.reviewHandoff.artifacts : childRun.artifacts || [];
+            if (artifacts.length)
+                task.artifacts = artifacts;
+        }
+        this.maybeStartDelegatedChildRuns(managerRun);
+    }
+    continueManagerRunForDelegation(managerRun, instructions, display, reviewedChildRun) {
+        if (!managerRun.sessionId || managerRun.status === 'running')
+            return;
+        const prepared = this.prepareContinueMessage(managerRun, instructions);
+        this.runRegistry.update(managerRun.id, (current) => {
+            current.status = 'running';
+            current.messages.push((0, hosts_1.createHubMessage)('manager', display));
+            current.events.push((0, hosts_1.createHubEvent)('system', 'Delegated child output routed back to Mandy for review.'));
+        });
+        const started = this.runRegistry.get(managerRun.id);
+        if (started)
+            this.persistRunConversation(started, started.conversationId || started.id);
+        this.runRegistry.create(managerRun, {});
+        const managerLaunch = this.resolveLaunchAgent(managerRun.configuredAgentId, managerRun.hostId);
+        const child = this.hostRuntime.continueRun(managerRun.hostId, managerRun.projectPath, managerRun.sessionId, prepared.message, {
+            onEvent: (event, channel) => {
+                this.runRegistry.update(managerRun.id, (current) => {
+                    if (event.sessionId)
+                        current.sessionId = event.sessionId;
+                    appendHostMessage(current, managerRun.hostId, event, channel);
+                    if (event.raw) {
+                        current.events.push((0, hosts_1.createHubEvent)(channel, event.raw));
+                        applyReviewProjection(current, event.raw);
+                    }
+                    if (event.agentIdentity)
+                        applyAgentIdentitySignal(current, event.agentIdentity);
+                    if (event.fraimJob)
+                        this.applyFraimJobSignalToRun(current, event.fraimJob);
+                    if (event.seekMentoring)
+                        this.applySeekMentoringSignalToRun(current, event.seekMentoring);
+                    if (event.usage)
+                        applyUsageSignal(current, event.usage);
+                });
+                const updated = this.runRegistry.get(managerRun.id);
+                if (updated)
+                    this.persistRunConversation(updated, updated.conversationId || updated.id);
+            },
+            onExit: (exitCode) => {
+                this.runRegistry.update(managerRun.id, (current) => {
+                    current.exitCode = exitCode;
+                    current.status = exitCode === 0 ? 'completed' : 'failed';
+                    current.events.push((0, hosts_1.createHubEvent)('system', `Mandy review turn exited with code ${exitCode ?? 'unknown'}.`));
+                });
+                const updated = this.runRegistry.get(managerRun.id);
+                if (updated) {
+                    if (exitCode === 0 && reviewedChildRun)
+                        this.markDelegatedChildReviewed(reviewedChildRun, updated);
+                    this.persistRunConversation(updated, updated.conversationId || updated.id);
+                }
+                this.runRegistry.dispose(managerRun.id);
+                const latestManager = this.runRegistry.get(managerRun.id);
+                if (latestManager)
+                    this.drainPendingDelegatedReviews(latestManager);
+            },
+        });
+        this.runRegistry.attachChildIfRunning(managerRun.id, child);
+    }
+    computeFirstRun(projectPath, jobCount, personas) {
+        const tc = (0, learning_context_builder_1.resolveTeamContextFiles)(projectPath);
+        // company = any organization-layer context written by org onboarding.
+        const companyDone = tc.orgContext.present || tc.managerContext.present || tc.orgRules.present || tc.managerRules.present;
+        // hire = any persona hired (entitlement active).
+        const hireDone = personas.some((p) => p.status === 'hired');
+        // project = a project brief exists OR the workspace has FRAIM jobs set up.
+        const projectDone = tc.projectContext.present || tc.projectBrief.present || tc.projectRules.present || tc.projectQa.present || jobCount > 0;
+        const derived = {
+            install: true, // the Hub is running, so the toolchain install step is satisfied.
+            company: companyDone,
+            hire: hireDone,
+            project: projectDone,
+        };
+        const persisted = readPersistedFirstRun();
+        return {
+            install: persisted.install ?? derived.install,
+            company: persisted.company || derived.company,
+            hire: persisted.hire || derived.hire,
+            project: persisted.project || derived.project,
+        };
+    }
+    // Issue #512 (S3, R3) — presence + display paths of the three-layer context
+    // files. Reuses the learning-context-builder resolvers (same layering as the
+    // auto-load Team Context block).
+    computeTeamContext(projectPath) {
+        return (0, learning_context_builder_1.resolveTeamContextFiles)(projectPath);
+    }
+    // Issue #512 (S3, R14) — Brain summary: preserved-learning counts by scope +
+    // registry catalog counts. A read projection; no new storage.
+    // Issue #750: `userEmail` is the config.json-resolved identity, or `null` when
+    // not connected. `organization`/`rawSignals` are identity-independent (org-*
+    // files and repo-level raw signals) and must always be counted regardless of
+    // connection state — only `manager`/`project` (L1, individual-keyed) are
+    // zeroed when not connected, rather than guessing an identity via
+    // resolveLearningUserId's single-stamped-user fallback (a legitimate
+    // convenience for MCP auto-load context, but not appropriate here).
+    computeBrain(projectPath, jobCount, userEmail) {
+        const learnings = (0, learning_context_builder_1.countPreservedLearnings)(projectPath, userEmail || '');
+        if (!userEmail) {
+            learnings.manager = 0;
+            learnings.project = 0;
+        }
+        return {
+            learnings,
+            catalog: {
+                jobs: jobCount,
+                skills: countMarkdownFilesRecursive(path_1.default.join(projectPath, 'registry', 'skills')) +
+                    countMarkdownFilesRecursive(path_1.default.join((0, project_fraim_paths_1.getWorkspaceFraimDir)(projectPath), 'ai-employee', 'skills')),
+                rules: countMarkdownFilesRecursive(path_1.default.join(projectPath, 'registry', 'rules')) +
+                    countMarkdownFilesRecursive(path_1.default.join((0, project_fraim_paths_1.getWorkspaceFraimDir)(projectPath), 'ai-employee', 'rules')),
+            },
+        };
+    }
+    resolveHubJob(projectPath, jobId) {
+        if (!jobId || jobId === '__freeform__')
+            return null;
+        const employeeJob = (0, catalog_1.discoverEmployeeJobs)(projectPath).find((job) => job.id === jobId);
+        if (employeeJob) {
+            return {
+                id: employeeJob.id,
+                title: employeeJob.title,
+                stubPath: employeeJob.stubPath,
+                personaKey: employeeJob.requiredPersonaKey ?? getProtectedPersonaForHubJob(employeeJob.id),
+            };
+        }
+        const managerTemplate = (0, catalog_1.discoverManagerTemplates)(projectPath).find((job) => job.id === jobId);
+        if (managerTemplate) {
+            return {
+                id: managerTemplate.id,
+                title: managerTemplate.title,
+                stubPath: managerTemplate.stubPath,
+                personaKey: getProtectedPersonaForHubJob(managerTemplate.id),
+            };
+        }
+        return null;
+    }
+    applySeekMentoringSignalToRun(run, signal) {
+        // Issue #732: promote using the stable jobName slug, not the per-call UUID
+        // jobId (resolveHubJob would never match a UUID, leaving a freeform run
+        // unpromoted and then dropping its phase signals).
+        this.maybePromoteFreeformRunToJob(run, signal.jobName || signal.jobId);
+        applySeekMentoringSignal(run, signal);
+    }
+    applyFraimJobSignalToRun(run, signal) {
+        this.maybePromoteFreeformRunToJob(run, signal.jobId);
+    }
+    maybePromoteFreeformRunToJob(run, signalJobId) {
+        const normalizedJobId = (signalJobId || '').trim().toLowerCase();
+        if (run.jobId !== '__freeform__' || !normalizedJobId)
+            return;
+        const metadata = this.resolveHubJob(run.projectPath, normalizedJobId);
+        if (!metadata)
+            return;
+        run.jobId = metadata.id;
+        run.jobTitle = metadata.title;
+        run.personaKey = metadata.personaKey;
+        run.updatedAt = new Date().toISOString();
+        run.events.push((0, hosts_1.createHubEvent)('system', `Recognized FRAIM job ${metadata.id} from structured telemetry.`));
+    }
+    // Lightweight markdown → .docx. Shared by the GET (file path) and POST (inline
+    // content) export routes so a conversational deliverable with no on-disk file
+    // can still be downloaded for Word annotation.
+    prepareStartPayload(projectPath, hostId, selectedJobId, instructions) {
+        const explicit = (0, manager_turns_1.extractExplicitFraimInvocation)(instructions);
+        const resolvedJobId = explicit?.jobId || selectedJobId;
+        if (!resolvedJobId) {
+            throw new Error('Choose a FRAIM job before starting a run, or start with /fraim <job-id>.');
+        }
+        // `display` is the manager conversation bubble. It keeps the user's full
+        // coaching text with the host-specific FRAIM invocation. The agent payload
+        // still receives Hub-only helper blocks such as `[FRAIM shared browser]`
+        // and `[How to talk to me]`; those are omitted from the visible bubble.
+        // #521: the shared-browser guidance is injected HERE, at the Hub layer — never
+        // baked into the registry job/skill. It only appears when a shared browser is
+        // available (env published at boot).
+        const browserNote = (0, managed_browser_1.buildBrowserContextNote)(process.env.FRAIM_BROWSER_CDP_ENDPOINT, process.env.FRAIM_HUB_BASE_URL);
+        const styleNote = (0, manager_turns_1.buildCommunicationStyleNote)();
+        if (resolvedJobId === '__freeform__') {
+            const display = (0, manager_turns_1.buildManagerMessage)(hostId, resolvedJobId, 'start', instructions);
+            return {
+                jobId: resolvedJobId,
+                message: (0, manager_turns_1.buildManagerMessage)(hostId, resolvedJobId, 'start', instructions) + browserNote + styleNote,
+                display,
+            };
+        }
+        const resolvedJob = this.resolveHubJob(projectPath, resolvedJobId);
+        const absoluteStubPath = resolvedJob?.stubPath
+            ? [projectPath, resolvedJob.stubPath].join('/').replace(/\\/g, '/').replace(/\/+/g, '/')
+            : undefined;
+        const display = (0, manager_turns_1.buildManagerMessage)(hostId, resolvedJobId, 'start', instructions);
+        return {
+            jobId: resolvedJobId,
+            message: (0, manager_turns_1.buildManagerMessage)(hostId, resolvedJobId, 'start', instructions, absoluteStubPath) + browserNote + styleNote,
+            display,
+        };
+    }
+    prepareDeploymentStartPayload(deployment, webhookBody) {
+        const context = [
+            (deployment.instructions || '').trim(),
+            webhookBody !== undefined
+                ? `Inbound payload:\n${JSON.stringify(webhookBody, null, 2)}`
+                : '',
+        ].filter(Boolean).join('\n\n');
+        return this.prepareStartPayload(deployment.projectPath, deployment.hostId, deployment.jobId, context);
+    }
+    prepareContinueMessage(run, instructions, coachingJobId) {
+        // coachingJobId is set when the user selected a manager coaching template
+        // (e.g. follow-your-mentor). When present, it overrides the run's own jobId
+        // as the target of the FRAIM invocation. The server picks the correct
+        // invocation prefix ($fraim / /fraim) based on run.hostId — the UI never
+        // passes raw invocation syntax.
+        const explicit = (0, manager_turns_1.extractExplicitFraimInvocation)(instructions);
+        const effectiveJobId = explicit?.jobId || coachingJobId || run.jobId;
+        const userText = (explicit?.remainder || instructions || '').trim();
+        // Issue #761: approval variants are manager commands, not coaching turns.
+        // Send them to the resumed agent exactly as selected; do not wrap them in
+        // generic same-job continue prose or phase-routing instructions.
+        if (!explicit && !coachingJobId && buildReviewApprovalSystemEventText(userText)) {
+            return { message: userText, display: userText };
+        }
+        // Issue #732: a plain continue of the SAME active real job must not re-load
+        // the job via get_fraim_job on every coaching turn — the host session is
+        // resumed with the job already in context, so re-fetching is wasted latency
+        // and tokens (the reported hub slowness) and mints a fresh UUID job id each
+        // time. Only load the job when the continue SWITCHES jobs (a coaching
+        // template or an explicit /fraim <other>). Freeform/adhoc runs keep the
+        // existing buildManagerMessage path (which already emits no invocation).
+        const switchesJob = effectiveJobId !== run.jobId;
+        const showsInvocation = switchesJob || run.jobId === '__freeform__';
+        // Issue #756: the manager bubble must MIRROR what actually happens. A
+        // same-job coaching continue resumes the active job WITHOUT re-invoking it
+        // (the `message` below carries no `/fraim`), so the bubble shows only what
+        // the manager SAID — never a `/fraim <same-job>` line, which reads as a full
+        // re-run of the active job Y and misled managers into thinking coaching
+        // restarts the workflow. Only a real job SWITCH actually issues an
+        // invocation, so only then does the bubble lead with the command. This still
+        // upholds the #730 guarantee: the manager's coaching text is never dropped,
+        // and when a command IS issued it appears in front of that text.
+        // The invocation form (`/fraim <job>` + words) is built once and reused for
+        // both the bubble and the agent payload when a command is actually issued.
+        const invocationForm = showsInvocation
+            ? (0, manager_turns_1.buildManagerMessage)(run.hostId, effectiveJobId, 'continue', instructions)
+            : null;
+        // Bubble: the command form for a real switch, else the manager's own words.
+        const display = invocationForm ?? userText;
+        // Agent payload: the same command form for a switch, else a lightweight
+        // same-job continue; the communication-style note is agent-only.
+        const message = (invocationForm ?? (0, manager_turns_1.buildSameJobContinueMessage)(userText)) + (0, manager_turns_1.buildCommunicationStyleNote)();
+        return { message, display };
+    }
+    async computePersonas(apiKey) {
+        const allBundles = listHubPersonaBundles();
+        const fallbackPersonas = allBundles.map((bundle) => ({
+            key: bundle.personaKey,
+            displayName: bundle.catalogMetadata.displayName,
+            role: bundle.catalogMetadata.role,
+            avatarUrl: buildHubPersonaAvatarUrl(bundle.personaKey),
+            pricingLabel: bundle.catalogMetadata.pricingLabel,
+            status: 'locked',
+            hireUrl: buildHubPersonaHireUrl(bundle.personaKey, bundle.defaultHireMode),
+            seatCount: 0,
+            seatsInUse: 0,
+        }));
+        try {
+            // Issue #701: persona state comes from the hosted server (GET /api/personas/me)
+            // via the user's API key — never a local MongoDB connection.
+            const state = await this.remoteGateway.getPersonaState(apiKey);
+            // A null result means we could not reach the authority (no/expired key or a
+            // transport error). That is the ONLY access decision the Hub makes on its own —
+            // render the locked "not-signed-in" fallback. When a state IS returned, its
+            // per-persona `status` is authoritative and rendered verbatim: the hired/locked
+            // decision (feature-off, legacy bypass, per-entitlement gating) lives solely in
+            // persona-entitlement-service.resolvePersonaAccessStatuses — the Hub does not
+            // re-derive it.
+            if (!state) {
+                return { personas: fallbackPersonas, subscriptionActive: false, workspaceId: null, userKey: null };
+            }
+            const verdictByKey = new Map((state.personas || []).map((p) => [p.personaKey, p]));
+            // seatsInUse (manager-team assignments) is display-only accounting fetched
+            // separately; it is not part of the access verdict.
+            const seatsInUseByKey = {};
+            const team = await this.remoteGateway.listManagerTeam(apiKey);
+            for (const entry of team) {
+                seatsInUseByKey[entry.personaKey] = (seatsInUseByKey[entry.personaKey] ?? 0) + 1;
+            }
+            const personas = allBundles.map((bundle) => {
+                const verdict = verdictByKey.get(bundle.personaKey);
+                const status = (verdict?.status ?? 'locked');
+                return {
+                    key: bundle.personaKey,
+                    displayName: bundle.catalogMetadata.displayName,
+                    role: bundle.catalogMetadata.role,
+                    avatarUrl: buildHubPersonaAvatarUrl(bundle.personaKey),
+                    pricingLabel: status === 'hired' ? '' : bundle.catalogMetadata.pricingLabel,
+                    status,
+                    hireUrl: buildHubPersonaHireUrl(bundle.personaKey, bundle.defaultHireMode),
+                    seatCount: verdict?.seatCount ?? 0,
+                    seatsInUse: seatsInUseByKey[bundle.personaKey] ?? 0,
+                };
+            });
+            return { personas, subscriptionActive: state.subscriptionActive, workspaceId: state.workspaceId, userKey: state.userId ?? null };
+        }
+        catch (err) {
+            console.error('[ai-hub] persona lookup failed:', err);
+            return { personas: fallbackPersonas, subscriptionActive: false, workspaceId: null, userKey: null };
+        }
+    }
+    async computeManagerTeam(apiKey) {
+        // Issue #701: manager team comes from the hosted server, not local Mongo.
+        return this.remoteGateway.listManagerTeam(apiKey);
+    }
+    // Issue #750: identity for routes that don't already call computePersonas()
+    // (which fetches this same hosted state for personas/manager-team). Always
+    // sources the apiKey from ~/.fraim/config.json; null means "not connected" —
+    // no local-guess fallback.
+    async resolveHubIdentity() {
+        const apiKey = resolveApiKey();
+        if (!apiKey)
+            return null;
+        const state = await this.remoteGateway.getPersonaState(apiKey);
+        return state?.userId ?? null;
+    }
+    // Issue #750: shared by the two learnings routes below. 'org' scope never
+    // needs identity (readPreservedLearnings/applyLearningEntryChange ignore the
+    // userId param for it); every other scope resolves through resolveHubIdentity,
+    // returning '' (not a guess) when not connected — callers distinguish
+    // "org" from "not connected" via the scope check they already have to make.
+    async resolveLearningIdentity(scope) {
+        if (scope === 'org')
+            return '';
+        return (await this.resolveHubIdentity()) || '';
+    }
+    registerRoutes() {
+        // Issue #512 / #749: the account and analytics surfaces live outside /ai-hub. The
+        // on-machine Hub holds no DB, so it always redirects these (and /auth) to the hosted
+        // server, which owns the authenticated, DB-backed pages.
+        this.app.get(/^\/auth(\/.*)?$/, (req, res) => {
+            const parsed = new URL(req.originalUrl, 'http://127.0.0.1');
+            if (parsed.pathname === '/auth/sign-in.html' && !parsed.searchParams.has('hub_return')) {
+                const rawSurface = parsed.searchParams.get('surface');
+                const surface = rawSurface === 'account' || rawSurface === 'brain' || rawSurface === 'analytics'
+                    ? rawSurface
+                    : 'analytics';
+                parsed.searchParams.set('hub_return', buildLocalHubReturnUrl(req, surface));
+            }
+            res.redirect(buildHostedPathUrl(parsed.pathname, parsed.search));
+        });
+        this.app.get(['/account', '/account/'], (req, res) => {
+            res.redirect(buildHostedAuthUrl('account', '/account/', buildLocalHubReturnUrl(req, 'account')));
+        });
+        this.app.get(['/analytics', '/analytics/'], (req, res) => {
+            res.redirect(buildHostedAuthUrl('analytics', '/analytics/', buildLocalHubReturnUrl(req, 'analytics')));
+        });
+        // Issue #478: Serve the PowerPoint task pane HTML and manifest.
+        // Office JS appends query strings (?_host_Info=PowerPoint$Win32$...) to every
+        // request, so we must strip them before resolving the file path. Use a custom
+        // route rather than express.static so we can apply the new URL().pathname fix.
+        this.app.get(/^\/powerpoint-taskpane(\/.*)?$/, (req, res) => {
+            const taskpaneDir = resolveTaskpaneDir('powerpoint-taskpane');
+            // Strip query string — Office appends ?_host_Info=PowerPoint$... to every fetch.
+            const { pathname } = new URL(req.url, 'http://localhost');
+            // Map root /powerpoint-taskpane/ to index.html
+            const relativePath = pathname.replace(/^\/powerpoint-taskpane\/?/, '') || 'index.html';
+            const filePath = path_1.default.join(taskpaneDir, relativePath);
+            if (!filePath.startsWith(taskpaneDir)) {
+                // Path traversal guard
+                res.status(403).end();
+                return;
+            }
+            const ext = path_1.default.extname(filePath).toLowerCase();
+            const contentTypeMap = {
+                '.html': 'text/html; charset=utf-8',
+                '.xml': 'application/xml',
+                '.js': 'application/javascript',
+                '.css': 'text/css',
+                '.png': 'image/png',
+            };
+            const contentType = contentTypeMap[ext] || 'text/plain';
+            fs_1.default.readFile(filePath, (err, data) => {
+                if (err) {
+                    res.status(404).end('Not found');
+                    return;
+                }
+                res.setHeader('Content-Type', contentType);
+                res.setHeader('Access-Control-Allow-Origin', '*');
+                res.end(data);
+            });
+        });
+        this.app.get('/api/ai-hub/bootstrap', async (req, res) => {
+            let projectPath = typeof req.query.projectPath === 'string' && req.query.projectPath.length > 0
+                ? req.query.projectPath
+                : null;
+            // If no explicit projectPath but a file:// docUrl was passed (Word Desktop),
+            // derive the project directory from the document's local path.
+            if (!projectPath && typeof req.query.docUrl === 'string' && req.query.docUrl.startsWith('file://')) {
+                try {
+                    const fileUrl = new URL(req.query.docUrl);
+                    const rawPath = process.platform === 'win32'
+                        ? fileUrl.pathname.replace(/^\/([A-Za-z]:)/, '$1')
+                        : fileUrl.pathname;
+                    projectPath = path_1.default.dirname(decodeURIComponent(rawPath));
+                }
+                catch { }
+            }
+            // #719: a bare reload (no projectPath query) must land on the last-recorded
+            // workspace project, not the launch folder. The bootstrap saves its resolved
+            // current path back into the projects list, so defaulting to the launch
+            // folder would resurrect a removed launch-folder project on every reload
+            // (tfSwitchProjectFolder already documents the recorded folder as "the
+            // default on next load"). The launch folder stays the fallback when nothing
+            // is recorded or the recorded folder no longer exists.
+            if (!projectPath) {
+                const recorded = this.preferencesStore.load(this.projectPath).projectPath;
+                if (recorded && path_1.default.resolve(recorded) !== path_1.default.resolve(this.projectPath) && fs_1.default.existsSync(recorded)) {
+                    projectPath = recorded;
+                }
+            }
+            res.json(await this.bootstrapResponse(projectPath || this.projectPath));
+        });
+        // Issue #512 (S3, R14) — Brain summary as a standalone route, returning the
+        // same projection folded into bootstrap. Useful for the avatar→Brain view
+        // without re-fetching the whole bootstrap payload.
+        this.app.get('/api/ai-hub/brain', async (req, res) => {
+            const projectPath = typeof req.query.projectPath === 'string' && req.query.projectPath.length > 0
+                ? path_1.default.resolve(req.query.projectPath)
+                : this.projectPath;
+            const jobCount = (0, catalog_1.discoverEmployeeJobs)(projectPath).length + (0, catalog_1.discoverManagerTemplates)(projectPath).length;
+            const userEmail = await this.resolveHubIdentity();
+            return res.json(this.computeBrain(projectPath, jobCount, userEmail));
+        });
+        // #533: read the PRESERVED learnings for a section + storage level so the
+        // Company/Manager sections (machine level) and the project workspace (project
+        // level) can DISPLAY and edit them.
+        const VALID_SCOPES = ['org', 'manager', 'reverse'];
+        const VALID_LEVELS = ['machine', 'project'];
+        const VALID_CATEGORIES = ['avoid', 'preference', 'repeat', 'coaching'];
+        const resolveProjectPath = (req) => typeof req.query.projectPath === 'string' && req.query.projectPath.length > 0
+            ? path_1.default.resolve(req.query.projectPath)
+            : (typeof (req.body && req.body.projectPath) === 'string' && req.body.projectPath.length > 0
+                ? path_1.default.resolve(req.body.projectPath)
+                : this.projectPath);
+        this.app.get('/api/ai-hub/learnings', async (req, res) => {
+            const scope = req.query.scope;
+            if (typeof scope !== 'string' || !VALID_SCOPES.includes(scope)) {
+                return res.status(400).json({ error: `scope must be one of: ${VALID_SCOPES.join(', ')}` });
+            }
+            const level = (typeof req.query.level === 'string' && VALID_LEVELS.includes(req.query.level))
+                ? req.query.level : 'machine';
+            try {
+                const userEmail = await this.resolveLearningIdentity(scope);
+                if (scope !== 'org' && !userEmail) {
+                    return res.json({ scope, level, entries: [] });
+                }
+                const entries = (0, learning_context_builder_1.readPreservedLearnings)(resolveProjectPath(req), userEmail, scope, level);
+                return res.json({ scope, level, entries });
+            }
+            catch (error) {
+                return res.status(500).json({ error: error instanceof Error ? error.message : 'Could not read learnings.' });
+            }
+        });
+        // #533 §3: add / edit / delete a single learning entry — writes the real file
+        // at the section's level (machine for the Manager/Company tabs, project for the
+        // project workspace). The action targets exactly the card's file.
+        this.app.post('/api/ai-hub/learnings/entry', async (req, res) => {
+            const b = (req.body || {});
+            if (!['add', 'edit', 'delete'].includes(b.action || '')) {
+                return res.status(400).json({ error: 'action must be one of: add, edit, delete' });
+            }
+            if (!b.scope || !VALID_SCOPES.includes(b.scope))
+                return res.status(400).json({ error: `scope must be one of: ${VALID_SCOPES.join(', ')}` });
+            if (!b.category || !VALID_CATEGORIES.includes(b.category))
+                return res.status(400).json({ error: `category must be one of: ${VALID_CATEGORIES.join(', ')}` });
+            const level = (b.level && VALID_LEVELS.includes(b.level)) ? b.level : 'machine';
+            const ref = { scope: b.scope, level, category: b.category };
+            // Issue #750: writes to a personal-scope file need a resolved identity —
+            // fail explicitly rather than writing to a guessed or empty-string file.
+            const userEmail = await this.resolveLearningIdentity(b.scope);
+            if (b.scope !== 'org' && !userEmail) {
+                return res.status(400).json({ error: 'not_connected', message: 'No FRAIM identity resolved. Run `fraim setup` first.' });
+            }
+            try {
+                const result = (0, learning_context_builder_1.applyLearningEntryChange)(resolveProjectPath(req), userEmail, ref, b.action, {
+                    originalTitle: b.originalTitle,
+                    severity: b.severity,
+                    title: b.title,
+                    body: b.body,
+                });
+                return res.json({ ok: true, path: result.path });
+            }
+            catch (error) {
+                return res.status(400).json({ error: error instanceof Error ? error.message : 'Could not write learning.' });
+            }
+        });
+        // Issue #540/#701/#750: POST /api/ai-hub/manager-team/assign
+        // Proxies to the hosted server (which owns the DB + seat enforcement), using
+        // the Hub's own ~/.fraim/config.json apiKey — not a caller-supplied header.
+        // Hosted returns 404 no_company_seat / 409 out_of_stock; those are passed through.
+        this.app.post('/api/ai-hub/manager-team/assign', async (req, res) => {
+            const { personaKey } = (req.body ?? {});
+            if (!personaKey)
+                return res.status(400).json({ error: 'personaKey required' });
+            const result = await this.remoteGateway.assignManagerTeam(resolveApiKey(), personaKey);
+            return res.status(result.status).json(result.body);
+        });
+        // Issue #540/#701/#750: DELETE /api/ai-hub/manager-team/assign/:personaKey
+        // Proxies the seat release to the hosted server.
+        this.app.delete('/api/ai-hub/manager-team/assign/:personaKey', async (req, res) => {
+            const { personaKey } = req.params;
+            await this.remoteGateway.removeManagerTeam(resolveApiKey(), personaKey);
+            return res.status(204).end();
+        });
+        // Issue #708: manager/company scopes resolve to a project-independent sentinel bucket
+        // key (which must bypass path/dir resolution); everything else keys by project path.
+        const scopeParam = (raw) => (raw === 'manager' || raw === 'company') ? raw : undefined;
+        this.app.get('/api/ai-hub/conversations', (req, res) => {
+            const scope = scopeParam(req.query.scope);
+            const key = scope
+                ? (0, conversation_store_1.conversationScopeKey)(scope, '')
+                : (typeof req.query.projectPath === 'string' && req.query.projectPath.length > 0
+                    ? path_1.default.resolve(req.query.projectPath)
+                    : this.projectPath);
+            const loaded = this.conversationStore.loadProject(key);
+            return res.json({ projectPath: key, scope: scope ?? 'project', ...loaded, source: 'disk' });
+        });
+        this.app.put('/api/ai-hub/conversations', (req, res) => {
+            try {
+                const body = (req.body ?? {});
+                const scope = scopeParam(body.scope);
+                const key = scope ? (0, conversation_store_1.conversationScopeKey)(scope, '') : ensureDirectoryPath(body.projectPath || this.projectPath);
+                if (!Array.isArray(body.conversations)) {
+                    return res.status(400).json({ error: 'conversations array required' });
+                }
+                // The client strips server-owned heavy fields (messages/events/artifacts/run/
+                // delegation) from its PUT payload to stay under the body-size limit. Merge them
+                // back from the stored record so a client-owned change (e.g. reviewApproved) never
+                // erases run history. List membership still comes from the incoming array, so
+                // deletes are honored (a conversation absent here is dropped).
+                const prior = this.conversationStore.loadProject(key);
+                const priorById = new Map(prior.conversations.map((entry) => [entry.id, entry]));
+                // Write-boundary guard for the cross-project leak (docs/rca/hub-conversation-cross-project-leak.md):
+                // a project PUT persists the client's current-project list, but that list can transiently
+                // include a conversation belonging to ANOTHER project (e.g. the just-finished run of the
+                // project the user switched away from). Never file such a record into this project bucket —
+                // its authoritative home is its own project bucket. Scope (manager/company) PUTs are exempt:
+                // their sentinel buckets legitimately hold records whose projectPath points at a project.
+                const belongsInBucket = (incoming) => {
+                    if (scope)
+                        return true;
+                    const incomingScope = incoming.scope
+                        ?? incoming.invokedArea;
+                    if (incomingScope === 'manager' || incomingScope === 'company')
+                        return false;
+                    const own = incoming && typeof incoming.projectPath === 'string' ? incoming.projectPath : '';
+                    if (!own)
+                        return true;
+                    return normalizedDirectoryPath(own) === normalizedDirectoryPath(key);
+                };
+                const conversations = body.conversations
+                    .filter((incoming) => belongsInBucket(incoming))
+                    .map((incoming) => {
+                    const existing = incoming && incoming.id ? priorById.get(incoming.id) : undefined;
+                    return existing ? { ...existing, ...incoming } : incoming;
+                });
+                const saved = this.conversationStore.replaceProject(key, {
+                    activeId: body.activeId ?? null,
+                    conversations,
+                });
+                return res.json({ projectPath: key, scope: scope ?? 'project', ...saved, source: 'disk' });
+            }
+            catch (error) {
+                return res.status(400).json({ error: error instanceof Error ? error.message : 'Could not persist conversations.' });
+            }
+        });
+        this.app.patch('/api/ai-hub/conversations/:conversationId', (req, res) => {
+            try {
+                const body = (req.body ?? {});
+                const scope = scopeParam(body.scope);
+                const projectPath = scope ? (0, conversation_store_1.conversationScopeKey)(scope, '') : ensureDirectoryPath(body.projectPath || this.projectPath);
+                const saved = this.conversationStore.patchConversation(projectPath, req.params.conversationId, body);
+                if (body.activeId !== undefined) {
+                    const withActive = this.conversationStore.replaceProject(projectPath, { ...saved, activeId: body.activeId });
+                    return res.json({ projectPath, ...withActive, source: 'disk' });
+                }
+                return res.json({ projectPath, ...saved, source: 'disk' });
+            }
+            catch (error) {
+                return res.status(400).json({ error: error instanceof Error ? error.message : 'Could not persist conversation.' });
+            }
+        });
+        this.app.get('/api/ai-hub/projects', (req, res) => {
+            const projectPath = typeof req.query.projectPath === 'string' && req.query.projectPath.length > 0
+                ? path_1.default.resolve(req.query.projectPath)
+                : this.projectPath;
+            return res.json({ projectPath, projects: this.knownProjects(projectPath), source: 'disk' });
+        });
+        this.app.put('/api/ai-hub/projects', (req, res) => {
+            try {
+                const body = (req.body ?? {});
+                const projectPath = ensureDirectoryPath(body.projectPath || this.projectPath);
+                if (!Array.isArray(body.projects)) {
+                    return res.status(400).json({ error: 'projects array required' });
+                }
+                const projects = this.preferencesStore.saveProjects(projectPath, [...this.knownProjects(projectPath), ...body.projects], { reviveRemovedPaths: Array.isArray(body.reviveRemovedPaths) ? body.reviveRemovedPaths : [] });
+                return res.json({ projectPath, projects, source: 'disk' });
+            }
+            catch (error) {
+                return res.status(400).json({ error: error instanceof Error ? error.message : 'Could not persist projects.' });
+            }
+        });
+        // Issue #719: DELETE /api/ai-hub/projects/:id — remove a project from the Hub.
+        // PUT is a merge by design and cannot express removal, so removal gets its own
+        // route (same convention as /schedules/:id, /webhooks/:id, /hosts/:id). Deletes
+        // every server-side derivation layer — preferences entry, conversation-store
+        // KEY, project-scoped deployments — so the project cannot resurrect (R3/R6/R9).
+        // Never touches anything under the project's folderPath (R8).
+        this.app.delete('/api/ai-hub/projects/:id', (req, res) => {
+            const projectPath = typeof req.query.projectPath === 'string' && req.query.projectPath.length > 0
+                ? path_1.default.resolve(req.query.projectPath)
+                : this.projectPath;
+            const known = this.knownProjects(projectPath);
+            // Match by id, falling back to the canonical folderPath. The client and server
+            // hash a path to an id with different algorithms, and the client mints its own id
+            // for the CURRENT project (tfEnsureCurrentProject), so a delete-by-id can carry an
+            // id the server never assigned — the folderPath is the true project identity (#726).
+            const requestedFolderPath = typeof req.query.folderPath === 'string' && req.query.folderPath.length > 0
+                ? req.query.folderPath
+                : null;
+            const entry = known.find((project) => project.id === req.params.id)
+                || (requestedFolderPath ? known.find((project) => sameDirectoryPath(project.folderPath, requestedFolderPath)) : undefined);
+            if (!entry)
+                return res.status(404).json({ error: 'Project not found.' });
+            // The current projectPath is unconditionally re-injected on every load, so
+            // deleting it would resurrect on the next request — reject as a sequencing
+            // error; the client switches workspaces before deleting (R5/D4).
+            if (sameDirectoryPath(entry.folderPath, projectPath)) {
+                return res.status(409).json({ error: 'Cannot remove the current project. Switch to another project first.' });
+            }
+            // A live schedule/webhook would fire later, write a conversation under the
+            // removed folderPath, and resurrect the project in the background (R6).
+            for (const deployment of this.deploymentStore.load()) {
+                if (!deploymentBelongsToProject(deployment, entry.folderPath, this.projectPath))
+                    continue;
+                const task = this.cronHandles.get(deployment.id);
+                if (task) {
+                    task.stop();
+                    this.cronHandles.delete(deployment.id);
+                }
+                this.deploymentStore.delete(deployment.id);
+            }
+            // Delete the conversation-store KEY — an empty list would still re-derive
+            // the project via listProjectPaths (R9).
+            this.conversationStore.removeProject(entry.folderPath);
+            // Persist the filtered list with a tombstone: a normal project save
+            // still merges derived projects and cannot express removal.
+            const projects = this.preferencesStore.removeProject(projectPath, known.filter((project) => project.id !== entry.id), entry.folderPath);
+            return res.json({ ok: true, projects });
+        });
+        // Issue #750: POST /api/ai-hub/api-key is removed — there is no Hub-local
+        // apiKey to persist. Identity always comes from ~/.fraim/config.json
+        // (set by `fraim setup`), read fresh via resolveApiKey() on every request.
+        this.app.post('/api/ai-hub/preferences', (req, res) => {
+            const { personaKey } = req.body;
+            const prefs = this.preferencesStore.load(this.projectPath);
+            this.preferencesStore.save({ ...prefs, personaKey: personaKey ?? null });
+            return res.json({ ok: true });
+        });
+        // #755: running build version + best-effort latest published version, so the
+        // account menu can show the version and flag when an update is available. The
+        // `fraim hub` CLI also queries this to confirm a running instance's version.
+        this.app.get('/api/ai-hub/version', async (_req, res) => {
+            const version = (0, version_utils_1.getFraimVersion)();
+            const latest = await (0, hub_latest_version_1.getLatestPublishedVersion)();
+            const updateAvailable = !!(latest && semver.valid(version) && semver.valid(latest) && semver.gt(latest, version));
+            return res.json({ version, latest, updateAvailable });
+        });
+        this.app.post('/api/ai-hub/project-path/pick', async (_req, res) => {
+            try {
+                const projectPath = await this.folderPicker();
+                if (!projectPath) {
+                    // User cancelled the native dialog, or no interactive dialog was
+                    // available (e.g. CI/headless). Front-end treats 204 as "no change".
+                    return res.status(204).end();
+                }
+                return res.json({ path: projectPath });
+            }
+            catch (error) {
+                return res.status(500).json({ error: error instanceof Error ? error.message : 'Could not open the folder picker.' });
+            }
+        });
+        // ── Issue #512 R3/R8: Team Context inline read/write ────────────────────
+        // GET  /api/ai-hub/context[?key=<key>]  → file content for the editor.
+        //   With ?key=<one of eight>: { key, present, displayPath, scope, content }.
+        //   Without key: { files: { <key>: {present, displayPath, scope, content} } }.
+        // POST /api/ai-hub/context  { key, content }  → persists to the correct
+        //   destination (user-level for org/manager/orgRules/managerRules unless a repo-local
+        //   override exists; repo-local for project*), creating parent dirs.
+        // Loopback-only (the Hub binds 127.0.0.1); writes are constrained to live
+        // under a personalized-employee/ directory (path-traversal guard).
+        const readContextFile = (projectPath, key) => {
+            const loc = (0, learning_context_builder_1.resolveTeamContextFile)(projectPath, key);
+            let content = '';
+            if (loc.present && loc.readPath) {
+                try {
+                    content = fs_1.default.readFileSync(loc.readPath, 'utf8');
+                }
+                catch {
+                    content = '';
+                }
+            }
+            return {
+                key,
+                present: loc.present,
+                displayPath: loc.displayPath,
+                scope: loc.scope,
+                content,
+            };
+        };
+        this.app.get('/api/ai-hub/context', (req, res) => {
+            const projectPath = typeof req.query.projectPath === 'string' && req.query.projectPath.length > 0
+                ? path_1.default.resolve(req.query.projectPath)
+                : this.projectPath;
+            const rawKey = typeof req.query.key === 'string' ? req.query.key : undefined;
+            if (rawKey !== undefined) {
+                if (!(0, learning_context_builder_1.isTeamContextKey)(rawKey)) {
+                    return res.status(400).json({ error: `Unknown context key: ${rawKey}` });
+                }
+                return res.json(readContextFile(projectPath, rawKey));
+            }
+            const keys = ['org', 'manager', 'orgRules', 'managerRules', 'projectContext', 'projectBrief', 'projectRules', 'projectQa'];
+            const files = {};
+            for (const key of keys)
+                files[key] = readContextFile(projectPath, key);
+            return res.json({ files });
+        });
+        this.app.post('/api/ai-hub/context', (req, res) => {
+            const body = (req.body ?? {});
+            if (!(0, learning_context_builder_1.isTeamContextKey)(body.key)) {
+                return res.status(400).json({ error: 'key must be one of org|manager|orgRules|managerRules|projectContext|projectBrief|projectRules|projectQa.' });
+            }
+            if (typeof body.content !== 'string') {
+                return res.status(400).json({ error: 'content (string) is required.' });
+            }
+            const projectPath = typeof body.projectPath === 'string' && body.projectPath.length > 0
+                ? path_1.default.resolve(body.projectPath)
+                : this.projectPath;
+            const loc = (0, learning_context_builder_1.resolveTeamContextFile)(projectPath, body.key);
+            if (loc.managedByOrgSync || loc.managedByManagerSync || !loc.writePath) {
+                // Enforcement only: block editing a synced org file (it would be
+                // overwritten on next sync). The how-to-change procedure lives in the
+                // organization-onboarding job, not in this error body (issue #563 review).
+                return res.status(409).json({
+                    error: loc.managedByManagerSync
+                        ? 'This manager file is managed by manager sync and is read-only here.'
+                        : 'This organization file is managed by org sync and is read-only here.'
+                });
+            }
+            const dest = path_1.default.resolve(loc.writePath);
+            // Path-traversal guard: the resolved destination must live under a
+            // personalized-employee directory (covers both ~/.fraim/... and repo-local).
+            const segments = dest.split(path_1.default.sep);
+            if (!segments.includes('personalized-employee')) {
+                return res.status(403).json({ error: 'Write destination outside personalized-employee.' });
+            }
+            try {
+                fs_1.default.mkdirSync(path_1.default.dirname(dest), { recursive: true });
+                fs_1.default.writeFileSync(dest, body.content, 'utf8');
+            }
+            catch (err) {
+                return res.status(500).json({ error: err instanceof Error ? err.message : 'Write failed.' });
+            }
+            // Re-read so the client gets the canonical post-write state (present flips).
+            return res.json(readContextFile(projectPath, body.key));
+        });
+        // Issue #744 — Hub cobranding.
+        // GET  /api/ai-hub/brand  → { brand: OrgBrand | null } resolved from the org
+        //   context storage (same layering as org_context.md).
+        // POST /api/ai-hub/brand  { name?, color?, logo?, projectPath? }  → sanitizes
+        //   + normalizes (SVG allowlist, hex normalize) and persists org_brand.json to
+        //   the org context write location. Loopback-only; write is constrained under
+        //   a personalized-employee/ directory (same path-traversal guard as context).
+        this.app.get('/api/ai-hub/brand', (req, res) => {
+            const projectPath = typeof req.query.projectPath === 'string' && req.query.projectPath.length > 0
+                ? path_1.default.resolve(req.query.projectPath)
+                : this.projectPath;
+            return res.json({ brand: (0, learning_context_builder_1.readOrgBrand)(projectPath) });
+        });
+        this.app.post('/api/ai-hub/brand', (req, res) => {
+            const body = (req.body ?? {});
+            const projectPath = typeof body.projectPath === 'string' && body.projectPath.length > 0
+                ? path_1.default.resolve(body.projectPath)
+                : this.projectPath;
+            const input = {
+                name: typeof body.name === 'string' ? body.name : undefined,
+                color: typeof body.color === 'string' ? body.color : undefined,
+                logo: typeof body.logo === 'string' ? body.logo : undefined,
+            };
+            const dest = path_1.default.resolve((0, learning_context_builder_1.resolveOrgBrandWriteDir)(projectPath));
+            // Path-traversal guard: the write dir must live under a personalized-employee
+            // directory (matches the context write guard; never the managed org cache).
+            if (!dest.split(path_1.default.sep).includes('personalized-employee')) {
+                return res.status(403).json({ error: 'Brand write destination outside personalized-employee.' });
+            }
+            try {
+                // writeBrandToDir sanitizes the logo (SVG allowlist) and normalizes the
+                // color before persisting, so unsafe input never reaches disk.
+                const stored = (0, brand_store_1.writeBrandToDir)(dest, input);
+                return res.json({ brand: stored });
+            }
+            catch (err) {
+                return res.status(500).json({ error: err instanceof Error ? err.message : 'Brand write failed.' });
+            }
+        });
+        this.app.post('/api/ai-hub/artifact/open', async (req, res) => {
+            const rawPath = typeof req.body?.path === 'string' ? req.body.path : '';
+            const projectPath = typeof req.body?.projectPath === 'string' && req.body.projectPath.length > 0
+                ? path_1.default.resolve(req.body.projectPath)
+                : this.projectPath;
+            if (!rawPath)
+                return res.status(400).json({ error: 'path is required.' });
+            const resolved = resolveSafeArtifactPath(rawPath, projectPath);
+            if (!resolved)
+                return res.status(403).json({ error: 'Path outside allowed roots.' });
+            if (!fs_1.default.existsSync(resolved))
+                return res.status(404).json({ error: 'File not found.' });
+            try {
+                await hubOpenFile(resolved);
+                return res.json({ ok: true, path: resolved });
+            }
+            catch (err) {
+                return res.status(500).json({ error: err instanceof Error ? err.message : 'Failed to open artifact.' });
+            }
+        });
+        this.app.post('/api/ai-hub/install-agent', async (req, res) => {
+            const { hubId } = req.body;
+            if (!hubId)
+                return res.status(400).json({ error: 'hubId is required.' });
+            const option = hubAgentOption(hubId);
+            if (!option)
+                return res.status(400).json({ error: `Unknown agent: ${hubId}` });
+            try {
+                const systemPath = (0, managed_agent_paths_1.stripManagedAgentBinDirsFromPath)(process.env.PATH);
+                const existingVersion = hubCommandVersion(option.launchCommand, undefined, systemPath);
+                if (existingVersion) {
+                    const mcp = await configureFraimForHubAgent(hubId);
+                    if (!mcp.configured) {
+                        console.warn(`[ai-hub] install-agent: FRAIM add-ide did not run for existing ${option.label}: ${mcp.error || 'unknown reason'}`);
+                    }
+                    return res.json({
+                        ok: true,
+                        message: `${option.label} is already installed.`,
+                        needsLogin: true,
+                        loginCommand: option.loginCommand,
+                        loginHint: `Sign in to ${option.label} to activate it. A terminal window will open — complete sign-in there, then click "Check if Ready".`,
+                        fraimConfigured: mcp.configured,
+                    });
+                }
+                let standardInstallError = null;
+                try {
+                    await hubRunProcess('npm', ['install', '-g', option.installPackage], {
+                        PATH: systemPath,
+                        npm_config_prefix: undefined,
+                        NPM_CONFIG_PREFIX: undefined,
+                    });
+                    const standardVersion = hubCommandVersion(option.launchCommand, undefined, systemPath);
+                    const npmGlobalBinDirs = standardVersion
+                        ? []
+                        : (0, managed_agent_paths_1.resolveNpmGlobalBinDirs)(systemPath, {
+                            npm_config_prefix: undefined,
+                            NPM_CONFIG_PREFIX: undefined,
+                        });
+                    const standardVersionWithNpmBin = standardVersion
+                        || (npmGlobalBinDirs.length > 0
+                            ? hubCommandVersion(option.launchCommand, npmGlobalBinDirs, systemPath)
+                            : null);
+                    if (standardVersionWithNpmBin) {
+                        if (npmGlobalBinDirs.length > 0) {
+                            process.env.PATH = (0, managed_agent_paths_1.appendBinDirsToPath)(systemPath, npmGlobalBinDirs);
+                        }
+                        const mcp = await configureFraimForHubAgent(hubId);
+                        if (!mcp.configured) {
+                            console.warn(`[ai-hub] install-agent: FRAIM add-ide did not run for standard ${option.label}: ${mcp.error || 'unknown reason'}`);
+                        }
+                        return res.json({
+                            ok: true,
+                            message: `${option.label} installed successfully.`,
+                            needsLogin: true,
+                            loginCommand: option.loginCommand,
+                            loginHint: `Sign in to ${option.label} to activate it. A terminal window will open — complete sign-in there, then click "Check if Ready".`,
+                            fraimConfigured: mcp.configured,
+                        });
+                    }
+                    standardInstallError = `${option.label} standard install completed, but the CLI is not runnable from the user PATH.`;
+                }
+                catch (error) {
+                    standardInstallError = error instanceof Error ? error.message : 'Unknown error';
+                }
+                const prefix = (0, managed_agent_paths_1.getManagedNodeRoot)();
+                fs_1.default.mkdirSync(prefix, { recursive: true });
+                await hubRunProcess('npm', ['install', '-g', option.installPackage], { npm_config_prefix: prefix });
+                const ver = hubCommandVersion(option.launchCommand, (0, managed_agent_paths_1.getManagedAgentBinDirs)());
+                if (!ver) {
+                    throw new Error(`${option.label} install completed, but the CLI is not runnable from FRAIM's managed PATH. Standard install failure: ${standardInstallError}`);
+                }
+                // Issue #747: run `add-ide` for the newly installed agent so the FRAIM MCP is wired in
+                // and its first run works (previously the agent launched with no `fraim` MCP server).
+                const mcp = await configureFraimForHubAgent(hubId);
+                if (!mcp.configured) {
+                    console.warn(`[ai-hub] install-agent: FRAIM add-ide did not run for ${option.label}: ${mcp.error || 'unknown reason'}`);
+                }
+                return res.json({
+                    ok: true,
+                    message: `${option.label} installed successfully.`,
+                    needsLogin: true,
+                    loginCommand: option.loginCommand,
+                    loginHint: `Sign in to ${option.label} to activate it. A terminal window will open — complete sign-in there, then click "Check if Ready".`,
+                    fraimConfigured: mcp.configured,
+                });
+            }
+            catch (error) {
+                const detail = error instanceof Error ? error.message : 'Unknown error';
+                return res.status(500).json({ ok: false, error: `Failed to install ${option.label}: ${detail}` });
+            }
+        });
+        this.app.post('/api/ai-hub/trigger-agent-login', (req, res) => {
+            const { hubId } = req.body;
+            if (!hubId)
+                return res.status(400).json({ error: 'hubId is required.' });
+            const option = hubAgentOption(hubId);
+            if (!option)
+                return res.status(400).json({ error: `Unknown agent: ${hubId}` });
+            try {
+                hubOpenTerminal(buildManagedLoginCommand(option.loginCommand));
+                return res.json({
+                    ok: true,
+                    message: `A terminal window opened with the ${option.label} sign-in command. Complete sign-in there, then return here.`,
+                });
+            }
+            catch (error) {
+                const detail = error instanceof Error ? error.message : 'Unknown error';
+                return res.json({
+                    ok: false,
+                    message: `Could not open a terminal automatically: ${detail}. Run \`${option.loginCommand}\` in a terminal to sign in.`,
+                });
+            }
+        });
+        this.app.post('/api/ai-hub/check-agent', (req, res) => {
+            const { hubId } = req.body;
+            if (!hubId)
+                return res.status(400).json({ error: 'hubId is required.' });
+            const option = hubAgentOption(hubId);
+            if (!option)
+                return res.status(400).json({ error: `Unknown agent: ${hubId}` });
+            const ver = hubCommandVersion(option.launchCommand, (0, managed_agent_paths_1.getManagedAgentBinDirs)());
+            if (ver) {
+                return res.json({ ok: true, ready: true, message: `${option.label} is ready.` });
+            }
+            return res.json({
+                ok: true,
+                ready: false,
+                message: `${option.label} is not detected yet. Make sure sign-in is complete and try again.`,
+            });
+        });
+        this.app.get('/api/ai-hub/configured-agents', (_req, res) => {
+            const employees = this.hostRuntime.detectEmployees();
+            res.json(this.configuredAgentsForCurrentMachine(employees).map((agent) => (0, configured_agents_1.projectConfiguredAgent)(agent, employees)));
+        });
+        this.app.post('/api/ai-hub/configured-agents', (req, res) => {
+            if (!this.requireTrustedHubOrigin(req, res))
+                return;
+            const result = this.configuredAgentStore.upsert(req.body);
+            if (!result.ok || !result.agent)
+                return res.status(400).json({ error: result.error || 'Invalid configured agent.' });
+            return res.status(201).json((0, configured_agents_1.projectConfiguredAgent)(result.agent, this.hostRuntime.detectEmployees()));
+        });
+        this.app.put('/api/ai-hub/configured-agents/:id', (req, res) => {
+            if (!this.requireTrustedHubOrigin(req, res))
+                return;
+            const result = this.configuredAgentStore.upsert({ ...req.body, id: req.params.id });
+            if (!result.ok || !result.agent)
+                return res.status(400).json({ error: result.error || 'Invalid configured agent.' });
+            return res.json((0, configured_agents_1.projectConfiguredAgent)(result.agent, this.hostRuntime.detectEmployees()));
+        });
+        this.app.delete('/api/ai-hub/configured-agents/:id', (req, res) => {
+            if (!this.requireTrustedHubOrigin(req, res))
+                return;
+            const ok = this.configuredAgentStore.delete(req.params.id);
+            if (!ok)
+                return res.status(404).json({ error: 'Configured agent not found or cannot be deleted.' });
+            return res.json({ ok: true });
+        });
+        this.app.post('/api/ai-hub/configured-agents/:id/check', (req, res) => {
+            if (!this.requireTrustedHubOrigin(req, res))
+                return;
+            const employees = this.hostRuntime.detectEmployees();
+            const agent = this.configuredAgentsForCurrentMachine(employees).find((entry) => entry.id === req.params.id);
+            if (!agent)
+                return res.status(404).json({ error: 'Configured agent not found.' });
+            return res.json((0, configured_agents_1.checkConfiguredAgentAvailability)(agent, employees));
+        });
+        this.app.post('/api/ai-hub/runs', (req, res) => {
+            try {
+                const projectPath = ensureDirectoryPath(req.body.projectPath || this.projectPath);
+                const requestedHostId = req.body.hostId;
+                const instructions = (req.body.instructions || '').trim();
+                const legacyMessage = (req.body.message || '').trim();
+                const compareMode = req.body.compareMode;
+                if (!instructions && !legacyMessage) {
+                    throw new Error('Coach your employee before starting the run.');
+                }
+                const employees = this.hostRuntime.detectEmployees();
+                const { hostId, agent: configuredAgent, launchContext } = this.resolveLaunchAgent(req.body.configuredAgentId, requestedHostId, employees);
+                const prepared = instructions
+                    ? this.prepareStartPayload(projectPath, hostId, req.body.jobId, instructions)
+                    : {
+                        jobId: req.body.jobId,
+                        message: legacyMessage,
+                        display: legacyMessage,
+                    };
+                const jobId = prepared.jobId;
+                const message = prepared.message;
+                // #521: store only the manager's own words in the conversation; the agent
+                // still receives `message` (with the Hub-injected invocation + notes).
+                const managerDisplay = prepared.display || message;
+                if (!jobId) {
+                    throw new Error('Choose a FRAIM job before starting a run.');
+                }
+                const startTimestamp = new Date().toISOString();
+                const jobMetadata = this.resolveHubJob(projectPath, jobId);
+                const fallbackJobTitle = typeof req.body.jobTitle === 'string' && req.body.jobTitle.trim()
+                    ? req.body.jobTitle.trim()
+                    : jobId;
+                const run = {
+                    id: (0, crypto_1.randomUUID)(),
+                    conversationId: typeof req.body.conversationId === 'string' && req.body.conversationId.trim() ? req.body.conversationId.trim() : undefined,
+                    conversationTitle: typeof req.body.conversationTitle === 'string' && req.body.conversationTitle.trim() ? req.body.conversationTitle.trim() : undefined,
+                    jobTitle: jobMetadata?.title || fallbackJobTitle,
+                    jobId,
+                    hostId,
+                    configuredAgentId: configuredAgent.id,
+                    configuredAgentLabel: configuredAgent.label,
+                    baseHostId: configuredAgent.baseHostId,
+                    projectPath,
+                    status: 'running',
+                    createdAt: startTimestamp,
+                    updatedAt: startTimestamp,
+                    messages: [(0, hosts_1.createHubMessage)('manager', managerDisplay)],
+                    events: [(0, hosts_1.createHubEvent)('system', `Starting ${configuredAgent.label} (${hostId}) in ${projectPath}`)],
+                    // Issue #347 — seed phase + totals state on creation.
+                    currentPhase: null,
+                    phaseHistory: [],
+                    totals: emptyTotals(),
+                    lastStatusChangeAt: startTimestamp,
+                    personaKey: jobMetadata?.personaKey ?? getProtectedPersonaForHubJob(jobId),
+                    // Issue #442: mark this as the FRAIM side of an A/B pair when applicable.
+                    ...(compareMode === 'ab' ? { runRole: 'fraim' } : {}),
+                    // #0: trigger source — defaults to 'manager' when not provided by the caller.
+                    sourceTrigger: req.body.sourceTrigger ?? 'manager',
+                };
+                this.runRegistry.create(run, {});
+                this.persistRunConversation(run, run.conversationId || run.id);
+                // Issue #442: create the Direct (B) run before spawning either process
+                // so we can cross-link both runs via compareRunId before any events arrive.
+                // directMsg is the plain user instructions — no FRAIM invocation prefix.
+                const directMsg = compareMode === 'ab'
+                    ? ((req.body.directInstructions || '').trim() || instructions || message)
+                    : message;
+                let directRun;
+                if (compareMode === 'ab') {
+                    const directTimestamp = new Date().toISOString();
+                    directRun = {
+                        id: (0, crypto_1.randomUUID)(),
+                        jobId: 'direct',
+                        hostId,
+                        configuredAgentId: configuredAgent.id,
+                        configuredAgentLabel: configuredAgent.label,
+                        baseHostId: configuredAgent.baseHostId,
+                        projectPath,
+                        status: 'running',
+                        createdAt: directTimestamp,
+                        updatedAt: directTimestamp,
+                        messages: [(0, hosts_1.createHubMessage)('manager', directMsg)],
+                        events: [(0, hosts_1.createHubEvent)('system', `Starting direct (no FRAIM) ${configuredAgent.label} (${hostId}) in ${projectPath}`)],
+                        currentPhase: null,
+                        phaseHistory: [],
+                        totals: emptyTotals(),
+                        lastStatusChangeAt: directTimestamp,
+                        personaKey: null,
+                        runRole: 'direct',
+                        compareRunId: run.id,
+                    };
+                    // Back-link the FRAIM run to the Direct run.
+                    this.runRegistry.update(run.id, (current) => {
+                        current.compareRunId = directRun.id;
+                    });
+                    this.runRegistry.create(directRun, {});
+                }
+                const child = this.hostRuntime.startRun(hostId, projectPath, message, {
+                    onEvent: (event, channel) => {
+                        this.runRegistry.update(run.id, (current) => {
+                            if (event.sessionId)
+                                current.sessionId = event.sessionId;
+                            appendHostMessage(current, hostId, event, channel);
+                            if (event.raw) {
+                                current.events.push((0, hosts_1.createHubEvent)(channel, event.raw));
+                                applyReviewProjection(current, event.raw);
+                            }
+                            if (event.agentIdentity)
+                                applyAgentIdentitySignal(current, event.agentIdentity);
+                            if (event.fraimJob)
+                                this.applyFraimJobSignalToRun(current, event.fraimJob);
+                            if (event.seekMentoring)
+                                this.applySeekMentoringSignalToRun(current, event.seekMentoring);
+                            if (event.usage)
+                                applyUsageSignal(current, event.usage);
+                        });
+                        const updated = this.runRegistry.get(run.id);
+                        if (updated) {
+                            this.maybeStartDelegatedChildRuns(updated);
+                            this.persistRunConversation(updated, updated.conversationId || updated.id);
+                        }
+                    },
+                    onExit: (exitCode) => {
+                        this.runRegistry.update(run.id, (current) => {
+                            current.exitCode = exitCode;
+                            if (current.stoppedByUser) {
+                                // Manager stopped it — park in "waiting on you", don't call it a failure.
+                                current.status = 'failed';
+                                current.events.push((0, hosts_1.createHubEvent)('system', '⏹ Run stopped by you. The employee is paused — send the next instruction to continue.'));
+                            }
+                            else {
+                                current.status = exitCode === 0 ? 'completed' : 'failed';
+                                current.events.push((0, hosts_1.createHubEvent)('system', `Run exited with code ${exitCode ?? 'unknown'}.`));
+                            }
+                        });
+                        const updated = this.runRegistry.get(run.id);
+                        if (updated) {
+                            this.maybeStartDelegatedChildRuns(updated);
+                            this.persistRunConversation(updated, updated.conversationId || updated.id);
+                        }
+                        this.runRegistry.dispose(run.id);
+                        const latest = this.runRegistry.get(run.id);
+                        if (latest)
+                            this.drainPendingDelegatedReviews(latest);
+                    },
+                }, startSessionSeedForHost(hostId, run.id), launchContext);
+                this.runRegistry.attachChildIfRunning(run.id, child);
+                // Issue #442: spawn the Direct run via startDirectRun so CliHostRuntime
+                // uses buildDirectStartPlan (--strict-mcp-config, raw stdin) rather than
+                // the FRAIM-wrapping buildStartPlan path.
+                if (directRun) {
+                    const directId = directRun.id;
+                    const directChild = this.hostRuntime.startDirectRun(hostId, directMsg, projectPath, {
+                        onEvent: (event, channel) => {
+                            this.runRegistry.update(directId, (current) => {
+                                if (event.sessionId)
+                                    current.sessionId = event.sessionId;
+                                appendHostMessage(current, hostId, event, channel);
+                                if (event.raw)
+                                    current.events.push((0, hosts_1.createHubEvent)(channel, event.raw));
+                                if (event.agentIdentity)
+                                    applyAgentIdentitySignal(current, event.agentIdentity);
+                                if (event.usage)
+                                    applyUsageSignal(current, event.usage);
+                            });
+                        },
+                        onExit: (exitCode) => {
+                            this.runRegistry.update(directId, (current) => {
+                                current.exitCode = exitCode;
+                                current.status = exitCode === 0 ? 'completed' : 'failed';
+                                current.events.push((0, hosts_1.createHubEvent)('system', `Direct run exited with code ${exitCode ?? 'unknown'}.`));
+                            });
+                            this.runRegistry.dispose(directId);
+                        },
+                    }, startSessionSeedForHost(hostId, directRun.id), launchContext);
+                    this.runRegistry.attachChildIfRunning(directRun.id, directChild);
+                }
+                const existingPreferences = this.preferencesStore.load(projectPath);
+                this.preferencesStore.remember({
+                    ...existingPreferences,
+                    projectPath,
+                    employeeId: hostId,
+                    recentJobIds: existingPreferences.recentJobIds,
+                }, jobId, typeof instructions === 'string' ? instructions : undefined);
+                const fraimRunEnriched = this.enrichRunForResponse(this.runRegistry.get(run.id) ?? run);
+                const responsePayload = directRun
+                    ? { ...fraimRunEnriched, compareRun: this.enrichRunForResponse(directRun) }
+                    : fraimRunEnriched;
+                res.status(201).json(responsePayload);
+                // Background sync: refresh the local FRAIM catalog so the next job
+                // picker load sees any jobs that were added or updated since last run.
+                try {
+                    const syncChild = (0, child_process_1.spawn)('npx', ['fraim', 'sync'], { cwd: projectPath, detached: true, stdio: 'ignore' });
+                    syncChild.on('error', () => { });
+                    syncChild.unref();
+                }
+                catch { /* ignore if spawn itself throws synchronously */ }
+            }
+            catch (error) {
+                res.status(400).json({ error: error instanceof Error ? error.message : 'Could not start run.' });
+            }
+        });
+        // #521: Shared persistent browser. start() launches (or reuses) the one
+        // FRAIM-owned Chrome/Edge and publishes its CDP endpoint to agents via env so
+        // the browser-use skill connects to it instead of launching a throwaway one.
+        this.app.get('/api/ai-hub/browser/status', async (_req, res) => {
+            const running = await this.managedBrowser.isRunning();
+            res.json({ running, ...this.managedBrowser.status() });
+        });
+        this.app.post('/api/ai-hub/browser/start', async (_req, res) => {
+            try {
+                const result = await this.ensureManagedBrowser();
+                res.json({
+                    ok: true,
+                    ...result,
+                    loginHint: 'Log into your sites in the FRAIM browser window — the session persists across agent turns.',
+                });
+            }
+            catch (err) {
+                res.status(500).json({ error: err instanceof Error ? err.message : 'Could not start the browser.' });
+            }
+        });
+        this.app.post('/api/ai-hub/browser/stop', (_req, res) => {
+            // Kill the process; keep FRAIM_BROWSER_CDP_ENDPOINT published — it's the
+            // deterministic location, so the agent can re-ensure and reconnect later.
+            this.managedBrowser.stop();
+            res.json({ ok: true });
+        });
+        // #521: Stop — the manager interrupts a running agent. Kills the process and
+        // parks the run in a "waiting on you" state so they can give the next
+        // instruction (continue) or leave it. Idempotent for already-finished runs.
+        this.app.post('/api/ai-hub/runs/:runId/stop', (req, res) => {
+            const run = this.runRegistry.get(req.params.runId);
+            if (!run) {
+                return res.status(404).json({ error: 'Run not found.' });
+            }
+            if (run.status !== 'running') {
+                // Nothing to stop — return the current state unchanged.
+                return res.json(this.enrichRunForResponse(run));
+            }
+            this.runRegistry.update(run.id, (current) => { current.stoppedByUser = true; });
+            const killed = this.runRegistry.stop(run.id);
+            // Park it immediately (don't wait for onExit, which may lag or not fire on a
+            // host that already detached). onExit, if it fires, keeps this same state.
+            this.runRegistry.update(run.id, (current) => {
+                current.status = 'failed';
+                current.events.push((0, hosts_1.createHubEvent)('system', killed
+                    ? '⏹ Run stopped by you. The employee is paused — send the next instruction to continue.'
+                    : '⏹ Stop requested. The employee was already wrapping up — send the next instruction to continue.'));
+            });
+            const stopped = this.runRegistry.get(run.id);
+            if (stopped)
+                this.persistRunConversation(stopped, stopped.conversationId || stopped.id);
+            this.runRegistry.dispose(run.id);
+            return res.json(this.enrichRunForResponse(this.runRegistry.get(run.id) ?? run));
+        });
+        this.app.post('/api/ai-hub/runs/:runId/messages', (req, res) => {
+            try {
+                const run = this.runRegistry.get(req.params.runId);
+                if (!run) {
+                    return res.status(404).json({ error: 'Run not found.' });
+                }
+                if (!run.sessionId) {
+                    return res.status(409).json({ error: 'This run does not have a resumable host session yet.' });
+                }
+                const instructions = (req.body.instructions || '').trim();
+                const coachingJobId = req.body.coachingJobId?.trim() || undefined;
+                // When coachingJobId is present (user picked a manager template via the UI),
+                // it overrides the run's own jobId in the invocation. The server always adds
+                // the correct $fraim / /fraim prefix — the UI never passes raw invocation syntax.
+                const prepared = instructions
+                    ? this.prepareContinueMessage(run, instructions, coachingJobId)
+                    : coachingJobId
+                        ? this.prepareContinueMessage(run, '', coachingJobId)
+                        : { message: (req.body.message || '').trim(), display: (req.body.message || '').trim() };
+                const message = prepared.message;
+                if (!message) {
+                    return res.status(400).json({ error: 'Coach your employee before sending the next turn.' });
+                }
+                const reviewApprovalSystemEventText = buildReviewApprovalSystemEventText(prepared.display || message);
+                this.runRegistry.update(run.id, (current) => {
+                    current.status = 'running';
+                    // #521: bubble shows the manager's words; the agent gets the full message.
+                    current.messages.push((0, hosts_1.createHubMessage)('manager', prepared.display || message));
+                    if (reviewApprovalSystemEventText)
+                        current.events.push((0, hosts_1.createHubEvent)('system', reviewApprovalSystemEventText));
+                });
+                const started = this.runRegistry.get(run.id);
+                if (started)
+                    this.persistRunConversation(started, started.conversationId || started.id);
+                this.runRegistry.create(run, {});
+                const continueLaunch = this.resolveLaunchAgent(run.configuredAgentId, run.hostId);
+                const child = this.hostRuntime.continueRun(run.hostId, run.projectPath, run.sessionId, message, {
+                    onEvent: (event, channel) => {
+                        this.runRegistry.update(run.id, (current) => {
+                            if (event.sessionId)
+                                current.sessionId = event.sessionId;
+                            appendHostMessage(current, run.hostId, event, channel);
+                            if (event.raw) {
+                                current.events.push((0, hosts_1.createHubEvent)(channel, event.raw));
+                                applyReviewProjection(current, event.raw);
+                            }
+                            if (event.agentIdentity)
+                                applyAgentIdentitySignal(current, event.agentIdentity);
+                            if (event.fraimJob)
+                                this.applyFraimJobSignalToRun(current, event.fraimJob);
+                            if (event.seekMentoring)
+                                this.applySeekMentoringSignalToRun(current, event.seekMentoring);
+                            if (event.usage)
+                                applyUsageSignal(current, event.usage);
+                        });
+                        const updated = this.runRegistry.get(run.id);
+                        if (updated) {
+                            this.maybeStartDelegatedChildRuns(updated);
+                            this.persistRunConversation(updated, updated.conversationId || updated.id);
+                        }
+                    },
+                    onExit: (exitCode) => {
+                        this.runRegistry.update(run.id, (current) => {
+                            current.exitCode = exitCode;
+                            current.status = exitCode === 0 ? 'completed' : 'failed';
+                            current.events.push((0, hosts_1.createHubEvent)('system', `Run exited with code ${exitCode ?? 'unknown'}.`));
+                        });
+                        const updated = this.runRegistry.get(run.id);
+                        if (updated) {
+                            this.maybeStartDelegatedChildRuns(updated);
+                            this.persistRunConversation(updated, updated.conversationId || updated.id);
+                        }
+                        this.runRegistry.dispose(run.id);
+                        const latest = this.runRegistry.get(run.id);
+                        if (latest)
+                            this.drainPendingDelegatedReviews(latest);
+                    },
+                }, continueLaunch.launchContext);
+                this.runRegistry.attachChildIfRunning(run.id, child);
+                const refreshed = this.runRegistry.get(run.id);
+                res.json(refreshed ? this.enrichRunForResponse(refreshed) : refreshed);
+            }
+            catch (error) {
+                res.status(400).json({ error: error instanceof Error ? error.message : 'Could not continue run.' });
+            }
+        });
+        // #521: resume a conversation whose Hub run was lost (e.g. a server restart)
+        // but whose agent session still exists on disk. Recreates a run bound to the
+        // existing sessionId and continues it via the host's resume path — so a
+        // conversation can be carried forward without losing its context.
+        this.app.post('/api/ai-hub/runs/resume', (req, res) => {
+            try {
+                const body = (req.body ?? {});
+                const projectPath = ensureDirectoryPath(body.projectPath || this.projectPath);
+                const requestedHostId = body.hostId;
+                const sessionId = (body.sessionId || '').trim();
+                const jobId = (body.jobId || '').trim();
+                const instructions = (body.instructions || '').trim();
+                const coachingJobId = body.coachingJobId?.trim() || undefined;
+                if (!sessionId)
+                    throw new Error('A host sessionId is required to resume.');
+                if (!jobId)
+                    throw new Error('A jobId is required to resume.');
+                if (!instructions)
+                    throw new Error('Provide an instruction to continue.');
+                const { hostId, agent: configuredAgent, launchContext } = this.resolveLaunchAgent(body.configuredAgentId, requestedHostId);
+                const conversationId = typeof body.conversationId === 'string' && body.conversationId.trim()
+                    ? body.conversationId.trim()
+                    : undefined;
+                const persistedConversation = conversationId
+                    ? this.conversationStore.loadProject(projectPath).conversations.find((entry) => entry.id === conversationId)
+                    : undefined;
+                const persistedRun = readPersistedRunProjection(persistedConversation);
+                const now = new Date().toISOString();
+                const run = {
+                    id: (0, crypto_1.randomUUID)(),
+                    conversationId,
+                    conversationTitle: typeof body.conversationTitle === 'string' && body.conversationTitle.trim() ? body.conversationTitle.trim() : undefined,
+                    jobTitle: typeof body.jobTitle === 'string' && body.jobTitle.trim() ? body.jobTitle.trim() : jobId,
+                    jobId, hostId, configuredAgentId: configuredAgent.id, configuredAgentLabel: configuredAgent.label, baseHostId: configuredAgent.baseHostId, projectPath, status: 'running', sessionId,
+                    createdAt: now, updatedAt: now, messages: [],
+                    events: [(0, hosts_1.createHubEvent)('system', `Resuming ${configuredAgent.label} (${hostId}) session ${sessionId} in ${projectPath}`)],
+                    currentPhase: persistedRun?.currentPhase || null,
+                    phaseHistory: persistedRun?.phaseHistory || [],
+                    totals: persistedRun?.totals || emptyTotals(),
+                    lastStatusChangeAt: now,
+                    runDiscriminant: persistedRun?.runDiscriminant || undefined,
+                    personaKey: getProtectedPersonaForHubJob(jobId),
+                };
+                // Continue-turn message (FRAIM invocation for the job + instructions) plus
+                // the shared-browser note so the resumed agent knows about it.
+                const preparedResume = this.prepareContinueMessage(run, instructions, coachingJobId);
+                const reviewApprovalSystemEventText = buildReviewApprovalSystemEventText(preparedResume.display || preparedResume.message);
+                const browserContextNote = reviewApprovalSystemEventText
+                    ? ''
+                    : (0, managed_browser_1.buildBrowserContextNote)(process.env.FRAIM_BROWSER_CDP_ENDPOINT, process.env.FRAIM_HUB_BASE_URL);
+                const message = preparedResume.message + browserContextNote;
+                // #521: bubble shows the manager's words; the agent gets the full message.
+                run.messages.push((0, hosts_1.createHubMessage)('manager', preparedResume.display || message));
+                if (reviewApprovalSystemEventText)
+                    run.events.push((0, hosts_1.createHubEvent)('system', reviewApprovalSystemEventText));
+                this.runRegistry.create(run, {});
+                this.persistRunConversation(run, run.conversationId || run.id);
+                const child = this.hostRuntime.continueRun(hostId, projectPath, sessionId, message, {
+                    onEvent: (event, channel) => {
+                        this.runRegistry.update(run.id, (current) => {
+                            if (event.sessionId)
+                                current.sessionId = event.sessionId;
+                            appendHostMessage(current, hostId, event, channel);
+                            if (event.raw) {
+                                current.events.push((0, hosts_1.createHubEvent)(channel, event.raw));
+                                applyReviewProjection(current, event.raw);
+                            }
+                            if (event.agentIdentity)
+                                applyAgentIdentitySignal(current, event.agentIdentity);
+                            if (event.fraimJob)
+                                this.applyFraimJobSignalToRun(current, event.fraimJob);
+                            if (event.seekMentoring)
+                                this.applySeekMentoringSignalToRun(current, event.seekMentoring);
+                            if (event.usage)
+                                applyUsageSignal(current, event.usage);
+                        });
+                        const updated = this.runRegistry.get(run.id);
+                        if (updated)
+                            this.persistRunConversation(updated, updated.conversationId || updated.id);
+                    },
+                    onExit: (exitCode) => {
+                        this.runRegistry.update(run.id, (current) => {
+                            current.exitCode = exitCode;
+                            current.status = exitCode === 0 ? 'completed' : 'failed';
+                            current.events.push((0, hosts_1.createHubEvent)('system', `Run exited with code ${exitCode ?? 'unknown'}.`));
+                        });
+                        const updated = this.runRegistry.get(run.id);
+                        if (updated)
+                            this.persistRunConversation(updated, updated.conversationId || updated.id);
+                        this.runRegistry.dispose(run.id);
+                        const latest = this.runRegistry.get(run.id);
+                        if (latest)
+                            this.drainPendingDelegatedReviews(latest);
+                    },
+                }, launchContext);
+                this.runRegistry.attachChildIfRunning(run.id, child);
+                res.status(201).json(this.enrichRunForResponse(this.runRegistry.get(run.id) ?? run));
+            }
+            catch (error) {
+                res.status(400).json({ error: error instanceof Error ? error.message : 'Could not resume the conversation.' });
+            }
+        });
+        // Issue #442: continue the Direct (B) run without FRAIM MCP servers.
+        this.app.post('/api/ai-hub/runs/:runId/direct-messages', (req, res) => {
+            try {
+                const run = this.runRegistry.get(req.params.runId);
+                if (!run)
+                    return res.status(404).json({ error: 'Run not found.' });
+                if (run.runRole !== 'direct')
+                    return res.status(400).json({ error: 'Run is not a Direct run.' });
+                if (!run.sessionId)
+                    return res.status(409).json({ error: 'Direct run does not have a resumable session yet.' });
+                const message = (req.body.message || '').trim();
+                if (!message)
+                    return res.status(400).json({ error: 'Message is required.' });
+                this.runRegistry.update(run.id, (current) => {
+                    current.status = 'running';
+                    current.messages.push((0, hosts_1.createHubMessage)('manager', message));
+                });
+                this.runRegistry.create(run, {});
+                const directLaunch = this.resolveLaunchAgent(run.configuredAgentId, run.hostId);
+                const child = this.hostRuntime.continueDirectRun(run.hostId, run.sessionId, message, run.projectPath, {
+                    onEvent: (event, channel) => {
+                        this.runRegistry.update(run.id, (current) => {
+                            if (event.sessionId)
+                                current.sessionId = event.sessionId;
+                            appendHostMessage(current, run.hostId, event, channel);
+                            if (event.raw)
+                                current.events.push((0, hosts_1.createHubEvent)(channel, event.raw));
+                            if (event.usage)
+                                applyUsageSignal(current, event.usage);
+                        });
+                    },
+                    onExit: (exitCode) => {
+                        this.runRegistry.update(run.id, (current) => {
+                            current.exitCode = exitCode;
+                            current.status = exitCode === 0 ? 'completed' : 'failed';
+                            current.events.push((0, hosts_1.createHubEvent)('system', `Direct run exited with code ${exitCode ?? 'unknown'}.`));
+                        });
+                        this.runRegistry.dispose(run.id);
+                    },
+                }, directLaunch.launchContext);
+                this.runRegistry.attachChildIfRunning(run.id, child);
+                const refreshed = this.runRegistry.get(run.id);
+                res.json(refreshed ? this.enrichRunForResponse(refreshed) : refreshed);
+            }
+            catch (error) {
+                res.status(400).json({ error: error instanceof Error ? error.message : 'Could not continue Direct run.' });
+            }
+        });
+        // GET /api/ai-hub/runs — list runs for cross-host polling and the UI ledger.
+        // Query params: status (filter), sourceTrigger (filter), limit (default 100, max 200).
+        // Must be registered BEFORE the :runId route to avoid 'runs' being matched as a runId.
+        this.app.get('/api/ai-hub/runs', (req, res) => {
+            const statusFilter = typeof req.query.status === 'string' ? req.query.status : null;
+            const triggerFilter = typeof req.query.sourceTrigger === 'string' ? req.query.sourceTrigger : null;
+            const limit = Math.min(200, parseInt(String(req.query.limit || '100'), 10) || 100);
+            let runs = this.runRegistry.all();
+            if (statusFilter)
+                runs = runs.filter((r) => r.status === statusFilter);
+            if (triggerFilter)
+                runs = runs.filter((r) => (r.sourceTrigger ?? 'manager') === triggerFilter);
+            runs = runs.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt)).slice(0, limit);
+            return res.json(runs.map((r) => this.enrichRunForResponse(r)));
+        });
+        // ─── Issue #578: /api/ai-hub/runs/merged must be registered BEFORE :runId ──
+        this.app.get('/api/ai-hub/runs/merged', async (req, res) => {
+            const local = this.runRegistry.all().map((r) => this.enrichRunForResponse(r));
+            const hosts = this.hostConfigStore.load();
+            const remoteResults = await Promise.allSettled(hosts.map(async (host) => {
+                const url = `${host.url.replace(/\/$/, '')}/api/ai-hub/runs`;
+                const resp = await fetch(url, {
+                    signal: AbortSignal.timeout(8000),
+                    headers: host.authToken ? { 'X-Hub-Auth': host.authToken } : {},
+                });
+                if (!resp.ok)
+                    return [];
+                return resp.json();
+            }));
+            const remote = remoteResults
+                .filter((r) => r.status === 'fulfilled')
+                .flatMap((r) => r.value);
+            const merged = [...local, ...remote].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+            return res.json(merged);
+        });
+        // GET /api/ai-hub/runs/:runId — registered AFTER /merged to avoid shadowing.
+        this.app.get('/api/ai-hub/runs/:runId', (req, res) => {
+            const run = this.runRegistry.get(req.params.runId);
+            if (!run) {
+                return res.status(404).json({ error: 'Run not found.' });
+            }
+            return res.json(this.enrichRunForResponse(run));
+        });
+        // ─── Issue #578: Scheduled + Reactive Employees ───────────────────────────
+        // POST /api/ai-hub/schedules — create a recurring scheduled deployment.
+        this.app.post('/api/ai-hub/schedules', (req, res) => {
+            const { label, jobId, projectPath, hostId, configuredAgentId, cronExpr, instructions, outputChannel, allowConcurrent } = req.body ?? {};
+            if (!label || !jobId || !cronExpr) {
+                return res.status(400).json({ error: 'label, jobId, and cronExpr are required.' });
+            }
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const cronLib = require('node-cron');
+            if (!cronLib.validate(cronExpr)) {
+                return res.status(400).json({ error: 'Invalid cron expression.' });
+            }
+            const validEmployees = VALID_EMPLOYEE_IDS;
+            const resolvedHostId = validEmployees.includes(hostId) ? hostId : 'claude';
+            const now = new Date().toISOString();
+            const deployment = {
+                id: (0, crypto_1.randomUUID)(),
+                type: 'scheduled',
+                label,
+                jobId,
+                projectPath: ensureDirectoryPath(projectPath || this.projectPath),
+                hostId: resolvedHostId,
+                ...(typeof configuredAgentId === 'string' && configuredAgentId.trim() ? { configuredAgentId: configuredAgentId.trim() } : {}),
+                cronExpr,
+                instructions: typeof instructions === 'string' ? instructions : undefined,
+                outputChannel: typeof outputChannel === 'string' ? outputChannel : undefined,
+                allowConcurrent: allowConcurrent === true,
+                active: true,
+                createdAt: now,
+                updatedAt: now,
+            };
+            this.deploymentStore.create(deployment);
+            this.scheduleDeployment(deployment);
+            return res.status(201).json(deployment);
+        });
+        // GET /api/ai-hub/schedules — list scheduled deployments for one project.
+        this.app.get('/api/ai-hub/schedules', (req, res) => {
+            try {
+                const projectPath = deploymentProjectFilter(req.query.projectPath, this.projectPath);
+                return res.json(this.deploymentStore.load().filter((d) => d.type === 'scheduled' && deploymentBelongsToProject(d, projectPath, this.projectPath)));
+            }
+            catch (err) {
+                return res.status(400).json({ error: err instanceof Error ? err.message : 'Invalid project path.' });
+            }
+        });
+        // DELETE /api/ai-hub/schedules/:id — remove a scheduled deployment.
+        this.app.delete('/api/ai-hub/schedules/:id', (req, res) => {
+            const { id } = req.params;
+            const task = this.cronHandles.get(id);
+            if (task) {
+                task.stop();
+                this.cronHandles.delete(id);
+            }
+            const deleted = this.deploymentStore.delete(id);
+            if (!deleted)
+                return res.status(404).json({ error: 'Deployment not found.' });
+            return res.json({ ok: true });
+        });
+        // PUT /api/ai-hub/schedules/:id — update an existing scheduled deployment.
+        this.app.put('/api/ai-hub/schedules/:id', (req, res) => {
+            const { id } = req.params;
+            const { label, jobId, projectPath, cronExpr, hostId, configuredAgentId, instructions, allowConcurrent } = req.body ?? {};
+            if (cronExpr !== undefined) {
+                // eslint-disable-next-line @typescript-eslint/no-var-requires
+                const cronLib = require('node-cron');
+                if (!cronLib.validate(cronExpr)) {
+                    return res.status(400).json({ error: 'Invalid cron expression.' });
+                }
+            }
+            let resolvedProjectPath;
+            try {
+                if (projectPath !== undefined)
+                    resolvedProjectPath = ensureDirectoryPath(projectPath || this.projectPath);
+            }
+            catch (err) {
+                return res.status(400).json({ error: err instanceof Error ? err.message : 'Invalid project path.' });
+            }
+            const validEmployees = VALID_EMPLOYEE_IDS;
+            let updated = null;
+            const ok = this.deploymentStore.update(id, (dep) => {
+                if (label !== undefined)
+                    dep.label = label;
+                if (jobId !== undefined)
+                    dep.jobId = jobId;
+                if (resolvedProjectPath !== undefined)
+                    dep.projectPath = resolvedProjectPath;
+                if (cronExpr !== undefined)
+                    dep.cronExpr = cronExpr;
+                if (hostId !== undefined && validEmployees.includes(hostId))
+                    dep.hostId = hostId;
+                if (configuredAgentId !== undefined)
+                    dep.configuredAgentId = typeof configuredAgentId === 'string' && configuredAgentId.trim() ? configuredAgentId.trim() : undefined;
+                if (instructions !== undefined)
+                    dep.instructions = typeof instructions === 'string' ? instructions : undefined;
+                if (allowConcurrent !== undefined)
+                    dep.allowConcurrent = allowConcurrent === true;
+                updated = dep;
+            });
+            if (!ok || !updated)
+                return res.status(404).json({ error: 'Deployment not found.' });
+            const oldTask = this.cronHandles.get(id);
+            if (oldTask) {
+                oldTask.stop();
+                this.cronHandles.delete(id);
+            }
+            this.scheduleDeployment(updated);
+            return res.json(updated);
+        });
+        // POST /api/ai-hub/webhooks — register an inbound webhook deployment.
+        this.app.post('/api/ai-hub/webhooks', (req, res) => {
+            const { label, jobId, projectPath, hostId, configuredAgentId, instructions, outputChannel, allowConcurrent } = req.body ?? {};
+            if (!label || !jobId) {
+                return res.status(400).json({ error: 'label and jobId are required.' });
+            }
+            const validEmployees = VALID_EMPLOYEE_IDS;
+            const resolvedHostId = validEmployees.includes(hostId) ? hostId : 'claude';
+            const now = new Date().toISOString();
+            const deployment = {
+                id: (0, crypto_1.randomUUID)(),
+                type: 'webhook',
+                label,
+                jobId,
+                projectPath: ensureDirectoryPath(projectPath || this.projectPath),
+                hostId: resolvedHostId,
+                ...(typeof configuredAgentId === 'string' && configuredAgentId.trim() ? { configuredAgentId: configuredAgentId.trim() } : {}),
+                instructions: typeof instructions === 'string' ? instructions : undefined,
+                outputChannel: typeof outputChannel === 'string' ? outputChannel : undefined,
+                allowConcurrent: allowConcurrent === true,
+                active: true,
+                createdAt: now,
+                updatedAt: now,
+            };
+            this.deploymentStore.create(deployment);
+            return res.status(201).json({ ...deployment, inboundUrl: `${this.hubBase}/api/ai-hub/webhooks/${deployment.id}/inbound` });
+        });
+        // GET /api/ai-hub/webhooks — list webhook deployments for one project.
+        this.app.get('/api/ai-hub/webhooks', (req, res) => {
+            const hubBase = this.hubBase;
+            try {
+                const projectPath = deploymentProjectFilter(req.query.projectPath, this.projectPath);
+                return res.json(this.deploymentStore.load()
+                    .filter((d) => d.type === 'webhook' && deploymentBelongsToProject(d, projectPath, this.projectPath))
+                    .map((d) => ({ ...d, inboundUrl: `${hubBase}/api/ai-hub/webhooks/${d.id}/inbound` })));
+            }
+            catch (err) {
+                return res.status(400).json({ error: err instanceof Error ? err.message : 'Invalid project path.' });
+            }
+        });
+        // DELETE /api/ai-hub/webhooks/:id — remove a webhook deployment.
+        this.app.delete('/api/ai-hub/webhooks/:id', (req, res) => {
+            const deleted = this.deploymentStore.delete(req.params.id);
+            if (!deleted)
+                return res.status(404).json({ error: 'Deployment not found.' });
+            return res.json({ ok: true });
+        });
+        // PUT /api/ai-hub/webhooks/:id — update an existing webhook deployment.
+        this.app.put('/api/ai-hub/webhooks/:id', (req, res) => {
+            const { id } = req.params;
+            const { label, jobId, projectPath, hostId, configuredAgentId, instructions, allowConcurrent } = req.body ?? {};
+            let resolvedProjectPath;
+            try {
+                if (projectPath !== undefined)
+                    resolvedProjectPath = ensureDirectoryPath(projectPath || this.projectPath);
+            }
+            catch (err) {
+                return res.status(400).json({ error: err instanceof Error ? err.message : 'Invalid project path.' });
+            }
+            const validEmployees = VALID_EMPLOYEE_IDS;
+            let updated = null;
+            const ok = this.deploymentStore.update(id, (dep) => {
+                if (label !== undefined)
+                    dep.label = label;
+                if (jobId !== undefined)
+                    dep.jobId = jobId;
+                if (resolvedProjectPath !== undefined)
+                    dep.projectPath = resolvedProjectPath;
+                if (hostId !== undefined && validEmployees.includes(hostId))
+                    dep.hostId = hostId;
+                if (configuredAgentId !== undefined)
+                    dep.configuredAgentId = typeof configuredAgentId === 'string' && configuredAgentId.trim() ? configuredAgentId.trim() : undefined;
+                if (instructions !== undefined)
+                    dep.instructions = typeof instructions === 'string' ? instructions : undefined;
+                if (allowConcurrent !== undefined)
+                    dep.allowConcurrent = allowConcurrent === true;
+                updated = dep;
+            });
+            if (!ok || !updated)
+                return res.status(404).json({ error: 'Deployment not found.' });
+            return res.json({ ...updated, inboundUrl: `${this.hubBase}/api/ai-hub/webhooks/${id}/inbound` });
+        });
+        // POST /api/ai-hub/webhooks/:id/inbound — webhook inbound trigger from external systems.
+        this.app.post('/api/ai-hub/webhooks/:id/inbound', async (req, res) => {
+            const deployments = this.deploymentStore.load();
+            const deployment = deployments.find((d) => d.id === req.params.id && d.type === 'webhook' && d.active);
+            if (!deployment) {
+                return res.status(404).json({ error: 'Webhook not found or inactive.' });
+            }
+            try {
+                const run = await this.fireDeploymentRun(deployment, req.body);
+                return res.status(202).json({ runId: run.id, status: run.status });
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : 'Failed to start run.';
+                return res.status(500).json({ error: msg });
+            }
+        });
+        // GET /api/ai-hub/hosts — list registered remote hosts with health status.
+        this.app.get('/api/ai-hub/hosts', async (_req, res) => {
+            const hosts = this.hostConfigStore.load();
+            const healthResults = await Promise.allSettled(hosts.map((h) => pingHost(h)));
+            const health = healthResults.map((r, i) => r.status === 'fulfilled'
+                ? r.value
+                : { id: hosts[i].id, label: hosts[i].label, url: hosts[i].url, status: 'offline', latencyMs: null, lastPingAt: new Date().toISOString() });
+            return res.json(health);
+        });
+        // POST /api/ai-hub/hosts — register a named remote hub host.
+        this.app.post('/api/ai-hub/hosts', (req, res) => {
+            const { label, url, authToken } = req.body ?? {};
+            const validUrl = (0, url_safety_1.safeHttpUrl)(url);
+            if (!label || !validUrl) {
+                return res.status(400).json({ error: 'label and a valid http(s) url are required.' });
+            }
+            const host = {
+                id: (0, crypto_1.randomUUID)(),
+                label,
+                url: validUrl,
+                authToken: typeof authToken === 'string' && authToken ? authToken : undefined,
+                createdAt: new Date().toISOString(),
+            };
+            this.hostConfigStore.add(host);
+            return res.status(201).json({ id: host.id, label: host.label, url: host.url, createdAt: host.createdAt });
+        });
+        // DELETE /api/ai-hub/hosts/:id — remove a named remote host.
+        this.app.delete('/api/ai-hub/hosts/:id', (req, res) => {
+            const deleted = this.hostConfigStore.delete(req.params.id);
+            if (!deleted)
+                return res.status(404).json({ error: 'Host not found.' });
+            return res.json({ ok: true });
+        });
+        // GET /api/ai-hub/hosts/:id/health — ping a single host.
+        this.app.get('/api/ai-hub/hosts/:id/health', async (req, res) => {
+            const host = this.hostConfigStore.load().find((h) => h.id === req.params.id);
+            if (!host)
+                return res.status(404).json({ error: 'Host not found.' });
+            const health = await pingHost(host);
+            return res.json(health);
+        });
+        // ─── End Issue #578 ───────────────────────────────────────────────────────
+        // -------------------------------------------------------------------------
+        // Issue #489: POST /api/trigger
+        // Stable API endpoint for extension surfaces (Office add-ins, browser
+        // extensions, VS Code extensions, Electron tray) to start FRAIM jobs.
+        //
+        // Body: { employeeId, jobName, context?: { text, sourceApp, fileName, ... }, projectPath? }
+        // Response: { runId, status: "started", employee, job }
+        // -------------------------------------------------------------------------
+        this.app.post('/api/trigger', (req, res) => {
+            try {
+                const { employeeId, jobName, context, projectPath: reqProjectPath } = req.body;
+                if (!employeeId) {
+                    return res.status(400).json({ error: 'employeeId is required.' });
+                }
+                if (!jobName) {
+                    return res.status(400).json({ error: 'jobName is required.' });
+                }
+                const projectPath = ensureDirectoryPath(reqProjectPath || this.projectPath);
+                // Use the requested agent directly — caller specifies which agent to run (claude, codex, gemini).
+                const requestedAgentId = req.body.configuredAgentId || employeeId;
+                const requestedHostId = VALID_EMPLOYEE_IDS.includes(employeeId) ? employeeId : undefined;
+                const { hostId, agent: configuredAgent, launchContext } = this.resolveLaunchAgent(requestedAgentId, requestedHostId);
+                const contextText = context?.text?.trim() || '';
+                const sourceInfo = [
+                    context?.sourceApp ? `sourceApp: ${context.sourceApp}` : '',
+                    context?.fileName ? `file: ${context.fileName}` : '',
+                ].filter(Boolean).join(', ');
+                const message = [
+                    `/fraim ${jobName}`,
+                    '',
+                    sourceInfo ? `Context (${sourceInfo}):` : 'Context:',
+                    contextText || '(no context provided)',
+                ].join('\n');
+                const startTimestamp = new Date().toISOString();
+                const run = {
+                    id: (0, crypto_1.randomUUID)(),
+                    jobId: jobName,
+                    hostId,
+                    configuredAgentId: configuredAgent.id,
+                    configuredAgentLabel: configuredAgent.label,
+                    baseHostId: configuredAgent.baseHostId,
+                    projectPath,
+                    status: 'running',
+                    createdAt: startTimestamp,
+                    updatedAt: startTimestamp,
+                    messages: [(0, hosts_1.createHubMessage)('manager', message)],
+                    events: [(0, hosts_1.createHubEvent)('system', `Trigger: ${configuredAgent.label} / ${jobName} from ${context?.sourceApp || 'unknown'} in ${projectPath}`)],
+                    currentPhase: null,
+                    phaseHistory: [],
+                    totals: emptyTotals(),
+                    lastStatusChangeAt: startTimestamp,
+                    personaKey: getProtectedPersonaForHubJob(jobName),
+                };
+                // Register the run before spawning so onEvent/onExit callbacks can
+                // safely call update() even if they fire synchronously (FakeHostRuntime).
+                this.runRegistry.create(run, {});
+                const child = this.hostRuntime.startRun(hostId, projectPath, message, {
+                    onEvent: (event, channel) => {
+                        this.runRegistry.update(run.id, (current) => {
+                            if (event.sessionId)
+                                current.sessionId = event.sessionId;
+                            appendHostMessage(current, hostId, event, channel);
+                            if (event.raw)
+                                current.events.push((0, hosts_1.createHubEvent)(channel, event.raw));
+                            if (event.agentIdentity)
+                                applyAgentIdentitySignal(current, event.agentIdentity);
+                            if (event.fraimJob)
+                                this.applyFraimJobSignalToRun(current, event.fraimJob);
+                            if (event.seekMentoring)
+                                this.applySeekMentoringSignalToRun(current, event.seekMentoring);
+                            if (event.usage)
+                                applyUsageSignal(current, event.usage);
+                        });
+                    },
+                    onExit: (exitCode) => {
+                        this.runRegistry.update(run.id, (current) => {
+                            current.exitCode = exitCode;
+                            current.status = exitCode === 0 ? 'completed' : 'failed';
+                            current.events.push((0, hosts_1.createHubEvent)('system', `Trigger run exited with code ${exitCode ?? 'unknown'}.`));
+                        });
+                        this.runRegistry.dispose(run.id);
+                    },
+                }, startSessionSeedForHost(hostId, run.id), launchContext);
+                // Update the registry entry with the real child process handle.
+                this.runRegistry.attachChildIfRunning(run.id, child);
+                return res.json({ runId: run.id, status: 'started', employee: employeeId, job: jobName });
+            }
+            catch (error) {
+                return res.status(400).json({ error: error instanceof Error ? error.message : 'Could not start run.' });
+            }
+        });
+    }
+    // #521: start (or reuse) the shared browser and publish its CDP endpoint so
+    // every agent spawned afterward inherits FRAIM_BROWSER_CDP_ENDPOINT and its
+    // browser-use skill connects to the long-lived window instead of a throwaway.
+    async ensureManagedBrowser() {
+        const result = await this.managedBrowser.start();
+        process.env.FRAIM_BROWSER_CDP_ENDPOINT = result.endpoint;
+        return { endpoint: result.endpoint, reused: result.reused, channel: result.channel };
+    }
+    // ─── Issue #578: Scheduled deployment helpers ─────────────────────────────
+    rehydrateScheduledDeployments() {
+        const active = this.deploymentStore.load().filter((d) => d.type === 'scheduled' && d.active);
+        for (const dep of active) {
+            this.scheduleDeployment(dep);
+        }
+        if (active.length > 0) {
+            console.log(`[ai-hub] rehydrated ${active.length} scheduled deployment(s)`);
+        }
+    }
+    scheduleDeployment(deployment) {
+        if (!deployment.cronExpr)
+            return;
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const cron = require('node-cron');
+            if (!cron.validate(deployment.cronExpr)) {
+                console.warn(`[ai-hub] invalid cronExpr for deployment ${deployment.id}: ${deployment.cronExpr}`);
+                return;
+            }
+            const task = cron.schedule(deployment.cronExpr, async () => {
+                try {
+                    await this.fireDeploymentRun(deployment);
+                }
+                catch (err) {
+                    console.warn(`[ai-hub] scheduled deployment ${deployment.id} fire failed:`, err);
+                }
+            });
+            this.cronHandles.set(deployment.id, task);
+        }
+        catch (err) {
+            console.warn('[ai-hub] node-cron not available — scheduled deployments require node-cron:', err);
+        }
+    }
+    async fireDeploymentRun(deployment, webhookBody) {
+        // Overlapping run guard: if the prior run is still active and allowConcurrent is false, skip.
+        if (!deployment.allowConcurrent && deployment.activeRunId) {
+            const active = this.runRegistry.get(deployment.activeRunId);
+            if (active && active.status === 'running') {
+                console.log(`[ai-hub] deployment ${deployment.id} skipped — prior run ${deployment.activeRunId} still running`);
+                return active;
+            }
+        }
+        const { hostId, agent: configuredAgent, launchContext } = this.resolveLaunchAgent(deployment.configuredAgentId, deployment.hostId);
+        const prepared = this.prepareDeploymentStartPayload(deployment, webhookBody);
+        const jobId = prepared.jobId;
+        const instructions = prepared.message;
+        const managerDisplay = prepared.display || instructions;
+        const jobMetadata = this.resolveHubJob(deployment.projectPath, jobId);
+        const startTimestamp = new Date().toISOString();
+        const run = {
+            id: (0, crypto_1.randomUUID)(),
+            jobId,
+            jobTitle: jobMetadata?.title || jobId,
+            hostId,
+            configuredAgentId: configuredAgent.id,
+            configuredAgentLabel: configuredAgent.label,
+            baseHostId: configuredAgent.baseHostId,
+            projectPath: deployment.projectPath,
+            status: 'running',
+            sourceTrigger: deployment.type === 'scheduled' ? 'scheduled' : 'webhook',
+            createdAt: startTimestamp,
+            updatedAt: startTimestamp,
+            messages: [(0, hosts_1.createHubMessage)('manager', managerDisplay)],
+            events: [(0, hosts_1.createHubEvent)('system', `Triggered by deployment: ${deployment.label} (${deployment.type}) using ${configuredAgent.label}`)],
+            currentPhase: null,
+            phaseHistory: [],
+            totals: emptyTotals(),
+            lastStatusChangeAt: startTimestamp,
+            personaKey: jobMetadata?.personaKey ?? getProtectedPersonaForHubJob(jobId),
+        };
+        // Pre-register before startRun so synchronous onEvent calls (e.g. FakeHostRuntime)
+        // can call runRegistry.update without "Run not found" throws.
+        this.runRegistry.create(run, {});
+        const child = this.hostRuntime.startRun(hostId, deployment.projectPath, instructions, {
+            onEvent: (event, channel) => {
+                this.runRegistry.update(run.id, (current) => {
+                    if (event.sessionId)
+                        current.sessionId = event.sessionId;
+                    appendHostMessage(current, hostId, event, channel);
+                    if (event.raw) {
+                        current.events.push((0, hosts_1.createHubEvent)(channel, event.raw));
+                        applyReviewProjection(current, event.raw);
+                    }
+                    if (event.agentIdentity)
+                        applyAgentIdentitySignal(current, event.agentIdentity);
+                    if (event.fraimJob)
+                        this.applyFraimJobSignalToRun(current, event.fraimJob);
+                    if (event.seekMentoring)
+                        this.applySeekMentoringSignalToRun(current, event.seekMentoring);
+                    if (event.usage)
+                        applyUsageSignal(current, event.usage);
+                });
+                const updated = this.runRegistry.get(run.id);
+                if (updated)
+                    this.persistRunConversation(updated, updated.conversationId || updated.id);
+            },
+            onExit: (exitCode) => {
+                this.runRegistry.update(run.id, (r) => {
+                    r.exitCode = exitCode;
+                    r.status = exitCode === 0 ? 'completed' : 'failed';
+                    r.events.push((0, hosts_1.createHubEvent)('system', `Run exited with code ${exitCode ?? 'unknown'}.`));
+                });
+                const updated = this.runRegistry.get(run.id);
+                if (updated)
+                    this.persistRunConversation(updated, updated.conversationId || updated.id);
+                this.deploymentStore.update(deployment.id, (d) => { d.activeRunId = undefined; });
+                this.runRegistry.dispose(run.id);
+            },
+        }, startSessionSeedForHost(hostId, run.id), launchContext);
+        this.runRegistry.create(run, child);
+        this.deploymentStore.update(deployment.id, (d) => { d.activeRunId = run.id; });
+        return run;
+    }
+    // ─── End Issue #578 helpers ───────────────────────────────────────────────
+    // Issue #347 — assemble the read-side projection of a run. Stages are
+    // derived from job frontmatter + visited phases; totalDurationMs ticks
+    // forward while the run is still running so the UI's totals line
+    // updates each poll without the server having to rewrite the run on
+    // every tick.
+    enrichRunForResponse(run) {
+        const stages = deriveStages(run, run.projectPath);
+        const now = Date.now();
+        const created = Date.parse(run.createdAt);
+        const updated = Date.parse(run.updatedAt);
+        const liveTotalMs = run.status === 'running'
+            ? Math.max(0, now - created)
+            : Math.max(0, updated - created);
+        const baseTotals = run.totals || emptyTotals();
+        // While the run is still in its current status (not yet flipped), the
+        // current bucket needs to include the in-flight delta since the last
+        // flip. Compute it here so the client sees a smoothly increasing
+        // working/waiting figure instead of frozen counters between flips.
+        const lastFlipMs = run.lastStatusChangeAt
+            ? Date.parse(run.lastStatusChangeAt)
+            : created;
+        const inflightMs = Math.max(0, now - lastFlipMs);
+        const liveTotals = {
+            totalDurationMs: liveTotalMs,
+            workingDurationMs: baseTotals.workingDurationMs + (run.status === 'running' ? inflightMs : 0),
+            waitingDurationMs: baseTotals.waitingDurationMs + (run.status !== 'running' ? inflightMs : 0),
+            tokenTotals: baseTotals.tokenTotals,
+        };
+        // Defensive cap: working + waiting should never exceed total. Trim
+        // the trailing bucket if rounding pushes us past.
+        const sum = liveTotals.workingDurationMs + liveTotals.waitingDurationMs;
+        if (sum > liveTotalMs) {
+            const overflow = sum - liveTotalMs;
+            if (run.status === 'running') {
+                liveTotals.workingDurationMs = Math.max(0, liveTotals.workingDurationMs - overflow);
+            }
+            else {
+                liveTotals.waitingDurationMs = Math.max(0, liveTotals.waitingDurationMs - overflow);
+            }
+        }
+        return { ...run, stages, totals: liveTotals, artifacts: run.artifacts || [] };
+    }
+}
+exports.AiHubServer = AiHubServer;
+var ports_1 = require("../core/utils/ports");
+Object.defineProperty(exports, "findAvailablePort", { enumerable: true, get: function () { return ports_1.findAvailablePort; } });
+Object.defineProperty(exports, "findAvailablePortExcluding", { enumerable: true, get: function () { return ports_1.findAvailablePortExcluding; } });
+function resolveAiHubPublicDir() {
+    const candidates = [
+        path_1.default.resolve(process.cwd(), 'public/ai-hub'),
+        path_1.default.resolve(__dirname, '..', '..', 'public/ai-hub'),
+        path_1.default.resolve(__dirname, '..', '..', '..', 'public/ai-hub'),
+    ];
+    for (const candidate of candidates) {
+        if (fs_1.default.existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    throw new Error('Could not locate public/ai-hub assets.');
+}
+// Issue #489: Resolve the word taskpane static assets directory.
+// Returns null (not throws) when the directory does not exist so the Hub
+// can start without the Word add-in assets present (e.g., older installs).
+function resolveWordTaskpaneDir(projectPath) {
+    const base = projectPath || process.cwd();
+    const candidates = [
+        path_1.default.resolve(base, 'extensions/office-word'),
+        path_1.default.resolve(__dirname, '..', '..', 'extensions/office-word'),
+        path_1.default.resolve(__dirname, '..', '..', '..', 'extensions/office-word'),
+    ];
+    for (const candidate of candidates) {
+        if (fs_1.default.existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    // Word add-in assets not found — /word-taskpane/* routes will not be registered.
+    return null;
+}
+// Issue #478: resolve the directory that contains a named Office task pane.
+// Example: resolveTaskpaneDir('powerpoint-taskpane') → <repo>/public/ai-hub/powerpoint-taskpane
+function resolveTaskpaneDir(pane) {
+    const aiHubDir = resolveAiHubPublicDir();
+    const taskpaneDir = path_1.default.join(aiHubDir, pane);
+    if (!fs_1.default.existsSync(taskpaneDir)) {
+        throw new Error(`Task pane directory not found: ${taskpaneDir}`);
+    }
+    return taskpaneDir;
+}
+/**
+ * Open the OS-native "choose a folder" dialog and resolve to the selected
+ * absolute path, or null if the user cancelled / no dialog was available.
+ *
+ * This is the genuinely native picker: it spawns the platform's own folder
+ * chooser (WinForms FolderBrowserDialog on Windows, `choose folder` on macOS,
+ * zenity/kdialog on Linux). The Hub runs on loopback on the user's machine, so
+ * it can launch the real dialog itself.
+ *
+ * Implementation notes (kept in lockstep with src/first-run/server.ts, which
+ * proved this out — see the long-form comment there):
+ *  - ASYNC (`spawn`, not `spawnSync`). The dialog blocks until the user
+ *    dismisses it, which can be many seconds. With `spawnSync` the entire Node
+ *    event loop freezes for that whole time — every other Hub HTTP request
+ *    (bootstrap, run polling) stalls and the Hub looks dead. `spawn` keeps the
+ *    server responsive while the dialog is up.
+ *  - Windows needs `-STA` (Single-Threaded Apartment) for FolderBrowserDialog
+ *    to work reliably, plus a hidden TopMost `$owner` form so the picker comes
+ *    to the foreground instead of opening behind the browser window.
+ *  - A hard timeout guarantees the endpoint can never hang forever: if nothing
+ *    is selected within the window (or the spawn wedges) we resolve null and
+ *    the caller degrades to "no change".
+ *  - NON-INTERACTIVE GUARD: a real OS folder dialog blocks waiting for a human.
+ *    In CI / automated UI tests (which DO reach this live endpoint) that would
+ *    hang. When AI_HUB_DISABLE_NATIVE_PICKER is set (or NODE_ENV=test) we skip
+ *    the dialog entirely and resolve null, so the endpoint returns 204 without
+ *    ever popping a window. Real desktop/loopback usage leaves it unset and
+ *    gets the genuine native dialog.
+ */
+function pickProjectPath() {
+    if (process.env.AI_HUB_DISABLE_NATIVE_PICKER === '1' ||
+        process.env.NODE_ENV === 'test') {
+        return Promise.resolve(null);
+    }
+    if (process.platform === 'win32') {
+        const script = [
+            'Add-Type -AssemblyName System.Windows.Forms',
+            '$dialog = New-Object System.Windows.Forms.FolderBrowserDialog',
+            '$dialog.Description = "Select a FRAIM project folder"',
+            '$dialog.ShowNewFolderButton = $true',
+            // Hidden owner form forces the dialog above the user's browser. Without
+            // this the dialog often appears behind the browser tab and the user sees
+            // nothing happen when they click the folder button.
+            '$owner = New-Object System.Windows.Forms.Form',
+            '$owner.TopMost = $true',
+            '$owner.ShowInTaskbar = $false',
+            'if ($dialog.ShowDialog($owner) -eq [System.Windows.Forms.DialogResult]::OK) {',
+            '  Write-Output $dialog.SelectedPath',
+            '}',
+            '$owner.Dispose()',
+        ].join('; ');
+        return runPickerProcess('powershell', ['-NoProfile', '-STA', '-Command', script]);
+    }
+    if (process.platform === 'darwin') {
+        return runPickerProcess('osascript', ['-e', 'POSIX path of (choose folder with prompt "Select a FRAIM project folder")']);
+    }
+    return runPickerProcess('bash', ['-lc', 'zenity --file-selection --directory 2>/dev/null || kdialog --getexistingdirectory 2>/dev/null']);
+}
+/**
+ * Spawn a native folder-dialog process and resolve to its trimmed stdout (the
+ * chosen path) or null. Hardened so it can never hang the server: any spawn
+ * error resolves null, and a hard timeout kills a wedged child and resolves
+ * null. The timeout is generous (the user may take a while to browse) but
+ * finite.
+ */
+function runPickerProcess(command, args, timeoutMs = 5 * 60_000) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(value);
+        };
+        let proc;
+        try {
+            proc = (0, child_process_1.spawn)(command, args, {
+                stdio: ['ignore', 'pipe', 'pipe'],
+                windowsHide: true,
+            });
+        }
+        catch {
+            finish(null);
+            return;
+        }
+        const timer = setTimeout(() => {
+            try {
+                proc.kill();
+            }
+            catch {
+                /* ignore */
+            }
+            finish(null);
+        }, timeoutMs);
+        let stdout = '';
+        proc.stdout?.on('data', (chunk) => { stdout += chunk.toString('utf8'); });
+        proc.stderr?.on('data', () => { });
+        proc.on('close', () => finish(stdout.trim() || null));
+        proc.on('error', () => finish(null));
+    });
+}