fraim-framework 2.0.161 → 2.0.162

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

@@ -1,4 +1,37 @@
 "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 };
 };
@@ -15,6 +48,8 @@ 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 project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
 const PERSONA_AVATAR_SEEDS = {
     maestro: { seed: 'MAESTRO-founder-mode', bg: 'fde68a' },
     beza: { seed: 'BEZA-strategist', bg: 'c7d2fe' },
@@ -44,6 +79,8 @@ const agent_token_prices_1 = require("../local-mcp-server/agent-token-prices");
 const hosts_1 = require("./hosts");
 const manager_turns_1 = require("./manager-turns");
 const preferences_1 = require("./preferences");
+const conversation_store_1 = require("./conversation-store");
+const managed_browser_1 = require("./managed-browser");
 const managed_agent_paths_1 = require("../cli/utils/managed-agent-paths");
 function loadPersonaCapabilityModule() {
     try {
@@ -137,6 +174,151 @@ class AiHubRunRegistry {
     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;
+        }
+    }
+}
+function safeHttpUrl(value) {
+    if (typeof value !== 'string' || value.trim().length === 0)
+        return null;
+    try {
+        const parsed = new URL(value.trim());
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+            return null;
+        return parsed.href;
+    }
+    catch {
+        return null;
+    }
+}
+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 = 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 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 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() : '',
+        };
+    }
+    if (targetType === 'pull_request') {
+        const url = safeHttpUrl(rawTarget?.url);
+        if (!url)
+            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',
+        };
+    }
+    if (targetType === 'artifact_set' && artifacts.length > 0) {
+        return {
+            reviewRequired: true,
+            reviewTarget: { type: 'artifact_set', label: targetLabel || `${artifacts.length} artifact${artifacts.length === 1 ? '' : 's'}` },
+            artifacts,
+            summary: typeof value.summary === 'string' ? value.summary.trim() : '',
+            feedbackMode: typeof value.feedbackMode === 'string' ? value.feedbackMode.trim() : 'inline',
+        };
+    }
+    return null;
+}
+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;
+}
+const ARTIFACT_PATH_RE = /([A-Za-z0-9_\-.\\/]*?(?:docs|public|src|tests)[\\/][A-Za-z0-9_\-.\\/]+\.[A-Za-z0-9]+)/;
+const ARTIFACT_EXCLUDE_RE = /(^|[\\/])(retrospectives|evidence|learnings|mocks|raw|archive)[\\/]/i;
+function extractReviewArtifactFromText(text, projectPath) {
+    if (!text)
+        return null;
+    const match = text.match(ARTIFACT_PATH_RE);
+    if (!match)
+        return null;
+    const relativePath = match[1].replace(/\\/g, '/');
+    if (ARTIFACT_EXCLUDE_RE.test(relativePath))
+        return null;
+    const parts = relativePath.split('/').filter(Boolean);
+    const name = parts[parts.length - 1] || relativePath;
+    const artifactPath = path_1.default.isAbsolute(relativePath) ? relativePath : path_1.default.join(projectPath, relativePath);
+    return { type: path_1.default.extname(name).replace(/^\./, '') || 'file', label: name, path: artifactPath };
+}
+function applyReviewProjection(run, text) {
+    const handoff = extractReviewHandoffFromText(text);
+    if (handoff) {
+        run.reviewHandoff = handoff;
+        run.artifacts = handoff.artifacts;
+        return;
+    }
+    const artifact = extractReviewArtifactFromText(text, run.projectPath);
+    if (!artifact)
+        return;
+    run.artifacts = run.artifacts || [];
+    if (!run.artifacts.some((entry) => entry.path === artifact.path || entry.url === artifact.url)) {
+        run.artifacts.push(artifact);
+    }
 }
 function emptyTotals() {
     return {
@@ -202,6 +384,20 @@ function applyAgentIdentitySignal(run, identity) {
     run.agentName = identity.agentName;
     run.agentModel = identity.agentModel;
 }
+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();
+            return;
+        }
+    }
+    run.messages.push((0, hosts_1.createHubMessage)('employee', event.message));
+}
 // Apply a parsed seekMentoring tool-use signal from the host stream to
 // the run state. Returns the updated currentPhase.
 function applySeekMentoringSignal(run, signal) {
@@ -215,6 +411,8 @@ function applySeekMentoringSignal(run, signal) {
     const callJobId = signal.jobId || signal.jobName;
     if (callJobId && targetJobId && callJobId !== targetJobId)
         return;
+    if (signal.reviewHandoff)
+        run.reviewHandoff = signal.reviewHandoff;
     // 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.
@@ -286,7 +484,7 @@ function deriveStages(run, projectPath) {
         currentIndex < 0 &&
         historyMap.size === 0;
     if (completedWithoutPhaseTelemetry) {
-        return [];
+        return declaredPath.map((phase) => ({ phaseId: phase.id, label: phase.label, state: 'done' }));
     }
     return declaredPath.map((phase, index) => {
         let state;
@@ -386,6 +584,37 @@ function hubOpenTerminal(command) {
     }
     (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;
+}
+function hubOpenFile(filePath) {
+    if (process.platform === 'win32') {
+        (0, child_process_1.spawn)('powershell.exe', ['-NoProfile', '-Command', 'Start-Process -LiteralPath $args[0]', filePath], {
+            detached: true,
+            stdio: 'ignore',
+            windowsHide: true,
+        }).unref();
+        return;
+    }
+    if (process.platform === 'darwin') {
+        (0, child_process_1.spawn)('open', [filePath], { detached: true, stdio: 'ignore' }).unref();
+        return;
+    }
+    (0, child_process_1.spawn)('xdg-open', [filePath], { detached: true, stdio: 'ignore' }).unref();
+}
 function buildManagedLoginCommand(command) {
     const managedPath = (0, managed_agent_paths_1.buildPathWithManagedAgentBins)(process.env.PATH);
     if (process.platform === 'win32') {
@@ -408,16 +637,130 @@ function ensureDirectoryPath(projectPath) {
     }
     return resolved;
 }
+// ---------------------------------------------------------------------------
+// Issue #512 (S3) — Hub bootstrap projection helpers.
+// ---------------------------------------------------------------------------
+// Resolve the user email used to key personal (L1) learnings. Reads
+// ~/.fraim/preferences.json (the existing user-prefs file) when present so the
+// Brain counts match the auto-load context; falls back to a sensible default
+// that resolveLearningUserId can refine against on-disk files.
+function getHubUserEmail() {
+    try {
+        const prefsPath = path_1.default.join((0, project_fraim_paths_1.getUserFraimDirPath)(), 'preferences.json');
+        if (fs_1.default.existsSync(prefsPath)) {
+            const raw = JSON.parse(fs_1.default.readFileSync(prefsPath, 'utf8'));
+            if (typeof raw.userEmail === 'string' && raw.userEmail.length > 0)
+                return raw.userEmail;
+        }
+    }
+    catch {
+        // fall through to default
+    }
+    // #533: preferences.json may not carry the email yet — the proxy persists it on
+    // fraim_connect (see stdio-server). Until then, personal learnings are ALWAYS
+    // stamped `<email>-<type>.md`, so a single-user machine resolves deterministically
+    // from the on-disk files. This is what makes the avatar + personal learnings work.
+    const stamped = resolveSingleStampedUser();
+    if (stamped)
+        return stamped;
+    return 'fraim-user';
+}
+// Return the one user prefix stamped on the global learning files, or null if
+// there is not exactly one (so we never guess between multiple accounts).
+function resolveSingleStampedUser() {
+    try {
+        const dir = (0, project_fraim_paths_1.getUserFraimLearningsDir)();
+        if (!fs_1.default.existsSync(dir))
+            return null;
+        const prefixes = new Set();
+        for (const f of fs_1.default.readdirSync(dir)) {
+            if (f.startsWith('org-'))
+                continue;
+            const m = f.match(/^(.*)-(preferences|manager-coaching|mistake-patterns|validated-patterns)\.md$/);
+            if (m)
+                prefixes.add(m[1]);
+        }
+        if (prefixes.size === 1)
+            return Array.from(prefixes)[0];
+    }
+    catch {
+        // ignore unreadable dir
+    }
+    return null;
+}
+// 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 {
     constructor(options = {}) {
         this.app = (0, express_1.default)();
         this.runRegistry = new AiHubRunRegistry();
         this.projectPath = options.projectPath || process.cwd();
         this.preferencesStore = options.preferencesStore || new preferences_1.AiHubPreferencesStore();
+        this.conversationStore = options.conversationStore || new conversation_store_1.AiHubConversationStore();
         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());
         if (options.dbService !== undefined) {
             this.dbService = options.dbService;
@@ -428,11 +771,15 @@ class AiHubServer {
             this.ownsDbService = this.dbService !== undefined;
         }
         this.app.use(express_1.default.json());
+        if (this.dbService) {
+            const { registerPaymentRoutes } = require('../routes/payment-routes');
+            registerPaymentRoutes(this.app, () => this.paymentRepo ?? null, this.dbService);
+        }
         // 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, OPTIONS');
+            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') {
@@ -441,6 +788,37 @@ class AiHubServer {
             }
             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', async (req, res) => {
+            const sessionId = req.query['session_id'];
+            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);
+                }
+            }
+            if (sessionId && this.dbService) {
+                try {
+                    const { syncPersonaEntitlementFromCheckoutSession } = await Promise.resolve().then(() => __importStar(require('../services/persona-entitlement-service')));
+                    const { stripe } = await Promise.resolve().then(() => __importStar(require('../config/stripe')));
+                    const session = await stripe.checkout.sessions.retrieve(sessionId);
+                    await syncPersonaEntitlementFromCheckoutSession(this.dbService, session, 'dashboard-link');
+                }
+                catch (err) {
+                    console.warn('[ai-hub] payment-success entitlement sync failed:', err);
+                }
+            }
+            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
@@ -513,6 +891,11 @@ class AiHubServer {
         if (this.dbService) {
             try {
                 await this.dbService.connect();
+                const mongoClient = this.dbService.getClient();
+                if (mongoClient) {
+                    const PaymentRepositoryImpl = require('../db/payment-repository').PaymentRepository;
+                    this.paymentRepo = new PaymentRepositoryImpl(mongoClient);
+                }
             }
             catch (err) {
                 console.warn('[ai-hub] DB connect failed — personas will show as locked:', err);
@@ -524,6 +907,13 @@ class AiHubServer {
             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}`;
         // 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.
@@ -535,6 +925,18 @@ class AiHubServer {
                 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) => {
@@ -551,6 +953,9 @@ class AiHubServer {
             await closeServer(this.httpServer);
             this.httpServer = undefined;
         }
+        // #521: tear down the shared browser if WE launched it (stop() no-ops on a
+        // browser the manager owns).
+        this.managedBrowser.stop();
         if (this.ownsDbService && this.dbService) {
             await this.dbService.close();
             this.dbService = undefined;
@@ -578,7 +983,8 @@ class AiHubServer {
             requiredPersonaKey: getProtectedPersonaForHubJob(job.id),
         }));
         const managerTemplates = (0, catalog_1.discoverManagerTemplates)(normalizedProjectPath);
-        const { personas, subscriptionActive } = await this.computePersonas(apiKey || preferences.apiKey);
+        const { personas, subscriptionActive, workspaceId, userKey } = await this.computePersonas(apiKey || preferences.apiKey);
+        const managerTeam = await this.computeManagerTeam(workspaceId, userKey);
         // 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.
@@ -595,6 +1001,104 @@ class AiHubServer {
             personas,
             subscriptionActive,
             activeRun,
+            // 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),
+            // #533: the resolved account email, so the profile card shows the real
+            // identity (not a hardcoded placeholder) and the client can display it.
+            userEmail: getHubUserEmail(),
+            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: require('../config/ai-manager-hiring').buildManagerHiringCatalog(),
+            // Issue #540: server-authoritative manager team (personas assigned by this manager).
+            managerTeam,
+        };
+    }
+    conversationRecordFromRun(run) {
+        const lastUpdatedAt = run.updatedAt || new Date().toISOString();
+        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,
+            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,
+            compareMode: run.runRole === 'fraim' && run.compareRunId ? 'ab' : undefined,
+            compareRunId: run.compareRunId || null,
+        };
+    }
+    persistRunConversation(run, activeId) {
+        try {
+            this.conversationStore.upsertConversation(run.projectPath, this.conversationRecordFromRun(run), 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).
+    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.
+    computeBrain(projectPath, jobCount) {
+        const learnings = (0, learning_context_builder_1.countPreservedLearnings)(projectPath, getHubUserEmail());
+        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) {
@@ -606,16 +1110,61 @@ class AiHubServer {
             return { id: managerTemplate.id, stubPath: managerTemplate.stubPath };
         return null;
     }
+    // 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.
+    async markdownToDocxBuffer(md) {
+        const html = md
+            .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+            // headings
+            .replace(/^#### (.+)$/gm, '<h4>$1</h4>')
+            .replace(/^### (.+)$/gm, '<h3>$1</h3>')
+            .replace(/^## (.+)$/gm, '<h2>$1</h2>')
+            .replace(/^# (.+)$/gm, '<h1>$1</h1>')
+            // bold, italic, code
+            .replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>')
+            .replace(/\*(.+?)\*/g, '<em>$1</em>')
+            .replace(/`(.+?)`/g, '<code>$1</code>')
+            // unordered lists
+            .replace(/^[-*] (.+)$/gm, '<li>$1</li>')
+            // horizontal rules
+            .replace(/^---+$/gm, '<hr/>')
+            // paragraphs (double newlines)
+            .replace(/\n{2,}/g, '</p><p>')
+            .replace(/^/, '<p>')
+            .replace(/$/, '</p>')
+            // clean up list items into a ul
+            .replace(/(<li>.+<\/li>\n?)+/g, (m) => `<ul>${m}</ul>`);
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const htmlToDocx = require('html-to-docx');
+        return await htmlToDocx(`<html><body>${html}</body></html>`, null, {
+            table: { row: { cantSplit: true } },
+            footer: false,
+            pageNumber: false,
+        });
+    }
     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>.');
         }
+        // #521: `display` is what the manager's conversation bubble shows — only their own
+        // words. The FRAIM invocation (`$fraim <job>`), the stub path, and the shared-
+        // browser / communication-style notes are system context for the AGENT, kept out
+        // of the bubble so the thread isn't cluttered with machinery. `message` (with all
+        // of it) is what the agent actually receives.
+        const display = (explicit?.remainder || instructions || '').trim();
+        // #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__') {
             return {
                 jobId: resolvedJobId,
-                message: (0, manager_turns_1.buildManagerMessage)(hostId, resolvedJobId, 'start', instructions),
+                message: (0, manager_turns_1.buildManagerMessage)(hostId, resolvedJobId, 'start', instructions) + browserNote + styleNote,
+                display,
             };
         }
         const resolvedJob = this.resolveHubJob(projectPath, resolvedJobId);
@@ -624,7 +1173,8 @@ class AiHubServer {
             : undefined;
         return {
             jobId: resolvedJobId,
-            message: (0, manager_turns_1.buildManagerMessage)(hostId, resolvedJobId, 'start', instructions, absoluteStubPath),
+            message: (0, manager_turns_1.buildManagerMessage)(hostId, resolvedJobId, 'start', instructions, absoluteStubPath) + browserNote + styleNote,
+            display,
         };
     }
     prepareContinueMessage(run, instructions, coachingJobId) {
@@ -634,7 +1184,16 @@ class AiHubServer {
         // invocation prefix ($fraim / /fraim) based on run.hostId — the UI never
         // passes raw invocation syntax.
         const effectiveJobId = coachingJobId || run.jobId;
-        return (0, manager_turns_1.buildManagerMessage)(run.hostId, effectiveJobId, 'continue', instructions);
+        // #521: `display` = the manager's own words for the conversation bubble. When the
+        // manager typed nothing (a quick-coach button), fall back to the bare invocation
+        // so the bubble still shows what was triggered — but never the style note.
+        const explicit = (0, manager_turns_1.extractExplicitFraimInvocation)(instructions);
+        const userText = (explicit?.remainder || instructions || '').trim();
+        const display = userText || (0, manager_turns_1.buildManagerMessage)(run.hostId, effectiveJobId, 'continue', '');
+        return {
+            message: (0, manager_turns_1.buildManagerMessage)(run.hostId, effectiveJobId, 'continue', instructions) + (0, manager_turns_1.buildCommunicationStyleNote)(),
+            display,
+        };
     }
     async computePersonas(apiKey) {
         const allBundles = listHubPersonaBundles();
@@ -646,16 +1205,36 @@ class AiHubServer {
             pricingLabel: bundle.catalogMetadata.pricingLabel,
             status: 'locked',
             hireUrl: buildHubPersonaHireUrl(bundle.personaKey, bundle.defaultHireMode),
+            seatCount: 0,
+            seatsInUse: 0,
         }));
-        if (!apiKey || !this.dbService)
-            return { personas: fallbackPersonas, subscriptionActive: false };
+        if (!this.dbService) {
+            return { personas: fallbackPersonas, subscriptionActive: false, workspaceId: null, userKey: null };
+        }
         try {
-            const state = await getHubWorkspacePersonaState(this.dbService, 'anonymous', apiKey);
-            if (!state)
-                return { personas: fallbackPersonas, subscriptionActive: false };
+            const state = await getHubWorkspacePersonaState(this.dbService, getHubUserEmail(), apiKey ?? '');
+            if (!state) {
+                return { personas: fallbackPersonas, subscriptionActive: false, workspaceId: null, userKey: null };
+            }
             const hiredKeys = new Set(state.entitlements
                 .filter((e) => e.status === 'active')
                 .map((e) => e.personaKey));
+            // Build per-persona seat counts from entitlement records.
+            // jobCreditsRemaining represents the number of job-credits (seats) purchased.
+            const seatCountByKey = {};
+            for (const e of state.entitlements) {
+                if (e.status === 'active') {
+                    seatCountByKey[e.personaKey] = (seatCountByKey[e.personaKey] ?? 0) + (e.jobCreditsRemaining ?? 1);
+                }
+            }
+            // seatsInUse is the count of manager-assignment rows for this workspace/persona.
+            const workspaceId = state.workspaceId;
+            const seatsInUseByKey = {};
+            if (this.dbService) {
+                await Promise.all(Object.keys(seatCountByKey).map(async (pKey) => {
+                    seatsInUseByKey[pKey] = await this.dbService.countHubManagerAssignments(workspaceId, pKey);
+                }));
+            }
             const personas = allBundles.map((bundle) => ({
                 key: bundle.personaKey,
                 displayName: bundle.catalogMetadata.displayName,
@@ -664,15 +1243,51 @@ class AiHubServer {
                 pricingLabel: hiredKeys.has(bundle.personaKey) ? '' : bundle.catalogMetadata.pricingLabel,
                 status: (hiredKeys.has(bundle.personaKey) ? 'hired' : 'locked'),
                 hireUrl: buildHubPersonaHireUrl(bundle.personaKey, bundle.defaultHireMode),
+                seatCount: seatCountByKey[bundle.personaKey] ?? 0,
+                seatsInUse: seatsInUseByKey[bundle.personaKey] ?? 0,
             }));
-            return { personas, subscriptionActive: state.subscriptionActive };
+            return { personas, subscriptionActive: state.subscriptionActive, workspaceId, userKey: state.userId ?? null };
         }
         catch (err) {
             console.error('[ai-hub] persona entitlement lookup failed:', err);
-            return { personas: fallbackPersonas, subscriptionActive: false };
+            return { personas: fallbackPersonas, subscriptionActive: false, workspaceId: null, userKey: null };
+        }
+    }
+    async computeManagerTeam(workspaceId, userKey) {
+        if (!workspaceId || !userKey || !this.dbService)
+            return [];
+        try {
+            const rows = await this.dbService.getHubManagerAssignments(workspaceId, userKey);
+            return rows.map((r) => ({ personaKey: r.personaKey, assignedAt: r.assignedAt.toISOString() }));
+        }
+        catch {
+            return [];
         }
     }
     registerRoutes() {
+        // Issue #512: Serve the account and analytics pages from public/.
+        // These live outside of /ai-hub so they need explicit routes.
+        const publicDir = resolveAiHubPublicDir().replace(/[\\/]ai-hub$/, '');
+        this.app.get('/account', (_req, res) => {
+            const filePath = path_1.default.join(publicDir, 'account', 'index.html');
+            if (fs_1.default.existsSync(filePath)) {
+                res.sendFile(filePath);
+            }
+            else {
+                res.status(404).send('Account page not found.');
+            }
+        });
+        this.app.use('/account', express_1.default.static(path_1.default.join(publicDir, 'account')));
+        this.app.get('/analytics', (_req, res) => {
+            const filePath = path_1.default.join(publicDir, 'analytics', 'index.html');
+            if (fs_1.default.existsSync(filePath)) {
+                res.sendFile(filePath);
+            }
+            else {
+                res.status(404).send('Analytics page not found.');
+            }
+        });
+        this.app.use('/analytics', express_1.default.static(path_1.default.join(publicDir, '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
@@ -728,6 +1343,160 @@ class AiHubServer {
             const apiKey = typeof req.headers['x-fraim-api-key'] === 'string' ? req.headers['x-fraim-api-key'] : undefined;
             res.json(await this.bootstrapResponse(projectPath || this.projectPath, apiKey));
         });
+        // 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', (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;
+            return res.json(this.computeBrain(projectPath, jobCount));
+        });
+        // #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', (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 entries = (0, learning_context_builder_1.readPreservedLearnings)(resolveProjectPath(req), getHubUserEmail(), 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', (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 };
+            try {
+                const result = (0, learning_context_builder_1.applyLearningEntryChange)(resolveProjectPath(req), getHubUserEmail(), 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: POST /api/ai-hub/manager-team/assign
+        // Assigns a persona to the authenticated manager's team (uses X-Fraim-Api-Key header).
+        // Returns 404 {error:'no_company_seat'} when the workspace has purchased no seats for the persona.
+        // Returns 409 {error:'out_of_stock'} when all company seats are already assigned to other managers.
+        this.app.post('/api/ai-hub/manager-team/assign', async (req, res) => {
+            const apiKey = typeof req.headers['x-fraim-api-key'] === 'string' ? req.headers['x-fraim-api-key'] : undefined;
+            const { personaKey } = (req.body ?? {});
+            if (!personaKey)
+                return res.status(400).json({ error: 'personaKey required' });
+            if (!this.dbService) {
+                return res.status(404).json({ error: 'no_company_seat', personaKey });
+            }
+            try {
+                const { workspaceId, userKey, personas } = await this.computePersonas(apiKey);
+                if (!workspaceId || !userKey) {
+                    return res.status(404).json({ error: 'no_company_seat', personaKey });
+                }
+                const persona = personas.find((p) => p.key === personaKey);
+                if (!persona || persona.seatCount === 0) {
+                    return res.status(404).json({ error: 'no_company_seat', personaKey });
+                }
+                if (persona.seatsInUse >= persona.seatCount) {
+                    return res.status(409).json({ error: 'out_of_stock', personaKey, seatCount: persona.seatCount });
+                }
+                await this.dbService.addHubManagerAssignment(workspaceId, userKey, personaKey);
+                const team = await this.computeManagerTeam(workspaceId, userKey);
+                return res.json({ managerTeam: team });
+            }
+            catch (err) {
+                console.error('[ai-hub] assign manager seat failed:', err);
+                return res.status(500).json({ error: 'internal_error' });
+            }
+        });
+        // Issue #540: DELETE /api/ai-hub/manager-team/assign/:personaKey
+        // Removes a persona from the authenticated manager's team.
+        this.app.delete('/api/ai-hub/manager-team/assign/:personaKey', async (req, res) => {
+            const apiKey = typeof req.headers['x-fraim-api-key'] === 'string' ? req.headers['x-fraim-api-key'] : undefined;
+            const { personaKey } = req.params;
+            if (!this.dbService)
+                return res.status(204).end();
+            try {
+                const { workspaceId, userKey } = await this.computePersonas(apiKey);
+                if (workspaceId && userKey) {
+                    await this.dbService.removeHubManagerAssignment(workspaceId, userKey, personaKey);
+                }
+                return res.status(204).end();
+            }
+            catch (err) {
+                console.error('[ai-hub] remove manager seat failed:', err);
+                return res.status(500).json({ error: 'internal_error' });
+            }
+        });
+        this.app.get('/api/ai-hub/conversations', (req, res) => {
+            const projectPath = typeof req.query.projectPath === 'string' && req.query.projectPath.length > 0
+                ? path_1.default.resolve(req.query.projectPath)
+                : this.projectPath;
+            const loaded = this.conversationStore.loadProject(projectPath);
+            return res.json({ projectPath, ...loaded, source: 'disk' });
+        });
+        this.app.put('/api/ai-hub/conversations', (req, res) => {
+            try {
+                const body = (req.body ?? {});
+                const projectPath = ensureDirectoryPath(body.projectPath || this.projectPath);
+                if (!Array.isArray(body.conversations)) {
+                    return res.status(400).json({ error: 'conversations array required' });
+                }
+                const saved = this.conversationStore.replaceProject(projectPath, {
+                    activeId: body.activeId ?? null,
+                    conversations: body.conversations,
+                });
+                return res.json({ projectPath, ...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 projectPath = 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.post('/api/ai-hub/api-key', (req, res) => {
             const { apiKey } = req.body;
             if (!apiKey || typeof apiKey !== 'string')
@@ -746,6 +1515,8 @@ class AiHubServer {
             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 });
@@ -754,6 +1525,152 @@ class AiHubServer {
                 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);
+            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 #512 R7: Artifact export (md → docx) ──────────────────────────
+        // GET /api/ai-hub/artifact/export-docx?path=<abs-path-to-md>
+        // Converts a markdown file to .docx using html-to-docx and streams the result.
+        // The manager downloads it, annotates in Word, and saves it in place on disk
+        // (no upload). The agent then reads the comments + tracked changes via the
+        // `apply-docx-changes-to-md` skill (registry script extract-docx-edits.js)
+        // during the address-feedback phase.
+        this.app.get('/api/ai-hub/artifact/export-docx', async (req, res) => {
+            const rawPath = typeof req.query.path === 'string' ? req.query.path : '';
+            if (!rawPath)
+                return res.status(400).json({ error: 'path is required.' });
+            // Safety: path must be under the current workspace or a known safe root.
+            const resolved = resolveSafeArtifactPath(rawPath, this.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 {
+                const md = fs_1.default.readFileSync(resolved, 'utf8');
+                const docxBuf = await this.markdownToDocxBuffer(md);
+                const basename = path_1.default.basename(resolved, path_1.default.extname(resolved));
+                res.setHeader('Content-Type', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document');
+                res.setHeader('Content-Disposition', `attachment; filename="${basename}.docx"`);
+                res.send(docxBuf);
+            }
+            catch (err) {
+                res.status(500).json({ error: err instanceof Error ? err.message : 'Export failed.' });
+            }
+        });
+        // POST /api/ai-hub/artifact/export-docx  { content, filename? }
+        // Converts inline markdown (the employee's conversational deliverable) to .docx
+        // when the run produced no on-disk file — e.g. an onboarding answer to an empty
+        // repo. Keeps the "annotate in Word" review flow working instead of erroring
+        // with "no local artifact path available".
+        this.app.post('/api/ai-hub/artifact/export-docx', async (req, res) => {
+            const content = typeof req.body?.content === 'string' ? req.body.content : '';
+            if (!content.trim())
+                return res.status(400).json({ error: 'content is required.' });
+            const rawName = typeof req.body?.filename === 'string' && req.body.filename.trim()
+                ? req.body.filename.trim()
+                : 'deliverable';
+            const safeName = rawName.replace(/[^a-zA-Z0-9._ -]/g, '').replace(/\.docx?$/i, '').slice(0, 80) || 'deliverable';
+            try {
+                const docxBuf = await this.markdownToDocxBuffer(content);
+                res.setHeader('Content-Type', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document');
+                res.setHeader('Content-Disposition', `attachment; filename="${safeName}.docx"`);
+                res.send(docxBuf);
+            }
+            catch (err) {
+                res.status(500).json({ error: err instanceof Error ? err.message : 'Export failed.' });
+            }
+        });
+        this.app.post('/api/ai-hub/artifact/open', (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 {
+                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)
@@ -843,22 +1760,29 @@ class AiHubServer {
                     : {
                         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 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: typeof req.body.jobTitle === 'string' && req.body.jobTitle.trim() ? req.body.jobTitle.trim() : jobId,
                     jobId,
                     hostId,
                     projectPath,
                     status: 'running',
                     createdAt: startTimestamp,
                     updatedAt: startTimestamp,
-                    messages: [(0, hosts_1.createHubMessage)('manager', message)],
+                    messages: [(0, hosts_1.createHubMessage)('manager', managerDisplay)],
                     events: [(0, hosts_1.createHubEvent)('system', `Starting ${hostId} in ${projectPath}`)],
                     // Issue #347 — seed phase + totals state on creation.
                     currentPhase: null,
@@ -866,14 +1790,11 @@ class AiHubServer {
                     totals: emptyTotals(),
                     lastStatusChangeAt: startTimestamp,
                     personaKey: getProtectedPersonaForHubJob(jobId),
-                    // Gemini CLI does not emit a session ID in its output stream;
-                    // pre-seed one so the Send button is enabled and the continue
-                    // endpoint can proceed. continueRun for Gemini ignores it.
-                    ...(hostId === 'gemini' ? { sessionId: (0, crypto_1.randomUUID)() } : {}),
                     // Issue #442: mark this as the FRAIM side of an A/B pair when applicable.
                     ...(compareMode === 'ab' ? { runRole: 'fraim' } : {}),
                 };
                 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.
@@ -912,10 +1833,11 @@ class AiHubServer {
                         this.runRegistry.update(run.id, (current) => {
                             if (event.sessionId)
                                 current.sessionId = event.sessionId;
-                            if (event.message)
-                                current.messages.push((0, hosts_1.createHubMessage)('employee', event.message));
-                            if (event.raw)
+                            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.seekMentoring)
@@ -923,16 +1845,29 @@ class AiHubServer {
                             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'}.`));
+                            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.persistRunConversation(updated, updated.conversationId || updated.id);
                         this.runRegistry.dispose(run.id);
                     },
-                });
+                }, run.sessionId);
                 this.runRegistry.create(run, child);
                 // Issue #442: spawn the Direct run via startDirectRun so CliHostRuntime
                 // uses buildDirectStartPlan (--strict-mcp-config, raw stdin) rather than
@@ -944,8 +1879,7 @@ class AiHubServer {
                             this.runRegistry.update(directId, (current) => {
                                 if (event.sessionId)
                                     current.sessionId = event.sessionId;
-                                if (event.message)
-                                    current.messages.push((0, hosts_1.createHubMessage)('employee', event.message));
+                                appendHostMessage(current, hostId, event, channel);
                                 if (event.raw)
                                     current.events.push((0, hosts_1.createHubEvent)(channel, event.raw));
                                 if (event.agentIdentity)
@@ -962,7 +1896,7 @@ class AiHubServer {
                             });
                             this.runRegistry.dispose(directId);
                         },
-                    });
+                    }, directRun.sessionId);
                     this.runRegistry.create(directRun, directChild);
                 }
                 const existingPreferences = this.preferencesStore.load(projectPath);
@@ -971,7 +1905,7 @@ class AiHubServer {
                     projectPath,
                     employeeId: hostId,
                     recentJobIds: existingPreferences.recentJobIds,
-                }, jobId);
+                }, jobId, typeof instructions === 'string' ? instructions : undefined);
                 const fraimRunEnriched = this.enrichRunForResponse(this.runRegistry.get(run.id) ?? run);
                 const responsePayload = directRun
                     ? { ...fraimRunEnriched, compareRun: this.enrichRunForResponse(directRun) }
@@ -990,6 +1924,60 @@ class AiHubServer {
                 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);
@@ -1004,28 +1992,34 @@ class AiHubServer {
                 // 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 message = instructions
+                const prepared = instructions
                     ? this.prepareContinueMessage(run, instructions, coachingJobId)
                     : coachingJobId
                         ? this.prepareContinueMessage(run, '', coachingJobId)
-                        : (req.body.message || '').trim();
+                        : { 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.' });
                 }
                 this.runRegistry.update(run.id, (current) => {
                     current.status = 'running';
-                    current.messages.push((0, hosts_1.createHubMessage)('manager', message));
+                    // #521: bubble shows the manager's words; the agent gets the full message.
+                    current.messages.push((0, hosts_1.createHubMessage)('manager', prepared.display || message));
                 });
+                const started = this.runRegistry.get(run.id);
+                if (started)
+                    this.persistRunConversation(started, started.conversationId || started.id);
                 this.runRegistry.create(run, {});
                 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;
-                            if (event.message)
-                                current.messages.push((0, hosts_1.createHubMessage)('employee', event.message));
-                            if (event.raw)
+                            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.seekMentoring)
@@ -1033,6 +2027,9 @@ class AiHubServer {
                             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) => {
@@ -1040,6 +2037,9 @@ class AiHubServer {
                             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);
                     },
                 });
@@ -1051,6 +2051,93 @@ class AiHubServer {
                 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 hostId = body.hostId;
+                const sessionId = (body.sessionId || '').trim();
+                const jobId = (body.jobId || '').trim();
+                const instructions = (body.instructions || '').trim();
+                const coachingJobId = body.coachingJobId?.trim() || undefined;
+                if (hostId !== 'codex' && hostId !== 'claude' && hostId !== 'gemini') {
+                    throw new Error('Choose an available employee to resume.');
+                }
+                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 employee = this.hostRuntime.detectEmployees().find((entry) => entry.id === hostId);
+                if (!employee?.available) {
+                    throw new Error(`${employee?.label || 'Selected employee'} is not available on this machine.`);
+                }
+                const now = new Date().toISOString();
+                const run = {
+                    id: (0, crypto_1.randomUUID)(),
+                    conversationId: typeof body.conversationId === 'string' && body.conversationId.trim() ? body.conversationId.trim() : undefined,
+                    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, projectPath, status: 'running', sessionId,
+                    createdAt: now, updatedAt: now, messages: [],
+                    events: [(0, hosts_1.createHubEvent)('system', `Resuming ${hostId} session ${sessionId} in ${projectPath}`)],
+                    currentPhase: null, phaseHistory: [], totals: emptyTotals(), lastStatusChangeAt: now,
+                    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 message = preparedResume.message
+                    + (0, managed_browser_1.buildBrowserContextNote)(process.env.FRAIM_BROWSER_CDP_ENDPOINT, process.env.FRAIM_HUB_BASE_URL);
+                // #521: bubble shows the manager's words; the agent gets the full message.
+                run.messages.push((0, hosts_1.createHubMessage)('manager', preparedResume.display || message));
+                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.seekMentoring)
+                                applySeekMentoringSignal(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);
+                    },
+                });
+                this.runRegistry.create(run, 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 {
@@ -1074,8 +2161,7 @@ class AiHubServer {
                         this.runRegistry.update(run.id, (current) => {
                             if (event.sessionId)
                                 current.sessionId = event.sessionId;
-                            if (event.message)
-                                current.messages.push((0, hosts_1.createHubMessage)('employee', event.message));
+                            appendHostMessage(current, run.hostId, event, channel);
                             if (event.raw)
                                 current.events.push((0, hosts_1.createHubEvent)(channel, event.raw));
                             if (event.usage)
@@ -1167,8 +2253,7 @@ class AiHubServer {
                         this.runRegistry.update(run.id, (current) => {
                             if (event.sessionId)
                                 current.sessionId = event.sessionId;
-                            if (event.message)
-                                current.messages.push((0, hosts_1.createHubMessage)('employee', event.message));
+                            appendHostMessage(current, hostId, event, channel);
                             if (event.raw)
                                 current.events.push((0, hosts_1.createHubEvent)(channel, event.raw));
                             if (event.agentIdentity)
@@ -1187,7 +2272,7 @@ class AiHubServer {
                         });
                         this.runRegistry.dispose(run.id);
                     },
-                });
+                }, run.sessionId);
                 // Update the registry entry with the real child process handle.
                 this.runRegistry.create(run, child);
                 return res.json({ runId: run.id, status: 'started', employee: employeeId, job: jobName });
@@ -1197,6 +2282,14 @@ class AiHubServer {
             }
         });
     }
+    // #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 #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
@@ -1306,36 +2399,105 @@ function resolveTaskpaneDir(pane) {
     }
     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 cmd;
-        let args;
-        if (process.platform === 'win32') {
-            const script = [
-                'Add-Type -AssemblyName System.Windows.Forms',
-                '$dialog = New-Object System.Windows.Forms.FolderBrowserDialog',
-                '$dialog.ShowNewFolderButton = $false',
-                'if ($dialog.ShowDialog() -eq [System.Windows.Forms.DialogResult]::OK) {',
-                '  Write-Output $dialog.SelectedPath',
-                '}',
-            ].join('; ');
-            cmd = 'powershell';
-            args = ['-NoProfile', '-Command', script];
-        }
-        else if (process.platform === 'darwin') {
-            cmd = 'osascript';
-            args = ['-e', 'POSIX path of (choose folder with prompt "Select a FRAIM project folder")'];
+        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,
+            });
         }
-        else {
-            cmd = 'bash';
-            args = ['-lc', 'zenity --file-selection --directory 2>/dev/null || kdialog --getexistingdirectory 2>/dev/null'];
+        catch {
+            finish(null);
+            return;
         }
+        const timer = setTimeout(() => {
+            try {
+                proc.kill();
+            }
+            catch {
+                /* ignore */
+            }
+            finish(null);
+        }, timeoutMs);
         let stdout = '';
-        const child = (0, child_process_1.spawn)(cmd, args, { stdio: ['ignore', 'pipe', 'ignore'] });
-        child.stdout.on('data', (chunk) => { stdout += chunk; });
-        child.on('close', (code) => {
-            resolve(code === 0 ? stdout.trim() || null : null);
-        });
-        child.on('error', () => resolve(null));
+        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));
     });
 }