fraim-hub 2.0.337 → 2.0.339

package/dist/registry/scripts/learning/entry-format.js

@@ -0,0 +1,27 @@
+'use strict';
+
+// Read the shared author's current entry format for identity and update guards.
+function learningEntryBlocks(body) {
+    const headings = [...body.matchAll(/^#{2,6}\s+\[P-[A-Z]+\].*$/gm)];
+    return headings.map((heading, index) => {
+        const start = heading.index;
+        const next = headings[index + 1]?.index ?? body.length;
+        const ownDepth = heading[0].match(/^#+/)[0].length;
+        const afterHeading = start + heading[0].length;
+        const shallower = [...body.slice(afterHeading, next).matchAll(/^(#{1,6})\s+.*$/gm)].find(m => m[1].length <= ownDepth);
+        const limit = shallower ? afterHeading + shallower.index : next;
+        const text = body.slice(start, limit).trimEnd();
+        return { start, end: start + text.length, text, id: text.match(/^\*\*Id\*\*:\s*(L-[a-f0-9]{10})\s*$/m)?.[1] ?? null };
+    });
+}
+
+function learningEntryMetadata(content) {
+    const metadata = {};
+    for (const match of content.matchAll(/^\*\*(Recurrences|First recorded|First synthesized)\*\*:\s*([^\r\n]+)$/gm)) {
+        if (metadata[match[1]] !== undefined && metadata[match[1]] !== match[2]) throw new Error('entry-metadata-conflict');
+        metadata[match[1]] = match[2];
+    }
+    return metadata;
+}
+
+module.exports = { learningEntryMetadata, learningEntryBlocks };

package/dist/registry/scripts/learning/learning-domains.json

@@ -0,0 +1,78 @@
+{
+  "schemaVersion": 1,
+  "mapVersion": 1,
+  "domains": [
+    "engineering",
+    "product",
+    "go-to-market",
+    "people-ops",
+    "finance",
+    "legal",
+    "compliance",
+    "customer",
+    "company-building",
+    "operations"
+  ],
+  "jobDomainMap": {
+    "product-building": "engineering",
+    "dev-ops": "engineering",
+    "quality-assurance": "engineering",
+    "migration": "engineering",
+    "replicate": "engineering",
+    "reviewer": "engineering",
+    "security": "engineering",
+    "delivery-ops": "engineering",
+    "salesforce": "engineering",
+    "ai-engineering": "engineering",
+    "product-management": "product",
+    "customer-development": "product",
+    "brainstorming": "product",
+    "marketing": "go-to-market",
+    "branding": "go-to-market",
+    "sales": "go-to-market",
+    "go-to-market": "go-to-market",
+    "business-development": "go-to-market",
+    "commercial-ops": "go-to-market",
+    "people-ops": "people-ops",
+    "inclusion-ops": "people-ops",
+    "career": "people-ops",
+    "finance": "finance",
+    "invoicing": "finance",
+    "banking": "finance",
+    "legal": "legal",
+    "compliance": "compliance",
+    "customer-success": "customer",
+    "customer-communication": "customer",
+    "company-creation": "company-building",
+    "bootstrap": "company-building",
+    "fundraising": "company-building",
+    "business-ops": "operations",
+    "procurement": "operations",
+    "project-management": "operations"
+  },
+  "globalJobCategories": [
+    "manager",
+    "fraim",
+    "1-1",
+    "coaching",
+    "delegation",
+    "hiring",
+    "productivity",
+    "project-setup",
+    "setup-guardrails",
+    "team-learning",
+    "verification"
+  ],
+  "domainVoice": {
+    "engineering": "Precise and technical; file paths, commands, and test names are appropriate.",
+    "product": "Product and user-outcome language; behavior and flow, not code symbols.",
+    "go-to-market": "Marketing and sales language; campaigns, funnels, messaging, audience.",
+    "people-ops": "Plain HR and recruiting language; no engineering jargon.",
+    "finance": "Finance and accounting language; figures, close, forecasts.",
+    "legal": "Contract and IP language; obligations, clauses, risk.",
+    "compliance": "Controls, evidence, and regulation language.",
+    "customer": "Customer-relationship and support language.",
+    "company-building": "Founder and operations language; setup, entity, funding.",
+    "operations": "Business-operations language; process, vendors, planning, coordination."
+  }
+}

package/dist/src/ai-hub/managed-browser.js

@@ -110,15 +110,27 @@ function buildBrowserLaunchArgs(opts) {
  * baked into any registry job or skill. Returns '' when the shared browser is not
  * available (so the note only appears when there is something to connect to).
  */
-function buildBrowserContextNote(cdpEndpoint, hubBaseUrl) {
+function buildBrowserContextNote(cdpEndpoint, hubBaseUrl, conversationId, page) {
     if (!cdpEndpoint || !hubBaseUrl)
         return '';
+    const trimmedConversationId = typeof conversationId === 'string' ? conversationId.trim() : '';
+    const pageGuidance = trimmedConversationId
+        ? [
+            `Browser work for this Hub conversation must use the conversation page for \`${trimmedConversationId}\`, not the globally active tab.`,
+            `Before using a browser, ensure it is running and get this conversation's page: \`POST ${hubBaseUrl}/api/ai-hub/browser/start\` with JSON body \`{"conversationId":"${trimmedConversationId}"}\` (idempotent - it reuses the running browser and this conversation's page, or relaunches/recreates them if they were closed).`,
+            page?.targetId
+                ? `Current allocated page target: \`${page.targetId}\`${page.webSocketDebuggerUrl ? ` (${page.webSocketDebuggerUrl})` : ''}.`
+                : 'Use the returned `page.targetId` / `page.webSocketDebuggerUrl` from that endpoint when your browser tooling lets you choose a CDP target.',
+        ]
+        : [
+            `Before using a browser, ensure it is running: \`POST ${hubBaseUrl}/api/ai-hub/browser/start\` (idempotent - it reuses the running browser, or relaunches it if it was closed).`,
+        ];
     return [
         '',
-        '[FRAIM shared browser] A persistent shared browser is available — use it instead of launching your own.',
-        `Before using a browser, ensure it is running: \`POST ${hubBaseUrl}/api/ai-hub/browser/start\` (idempotent — it reuses the running browser, or relaunches it if it was closed).`,
-        `Then drive the shared browser at ${cdpEndpoint}: your Playwright/browser tools are pointed at it on supported agents; if your tools would otherwise open their own browser, connect to the shared one with \`connectOverCDP("${cdpEndpoint}")\` and reuse its existing context/tab.`,
-        'Never close the shared browser or sign me out. If a site needs login, open it there and ask me to log in — the session persists to your next turn.',
+        '[FRAIM shared browser] A persistent shared browser is available; use it instead of launching your own.',
+        ...pageGuidance,
+        `Then drive the shared browser at ${cdpEndpoint}: your Playwright/browser tools are pointed at it on supported agents; if your tools would otherwise open their own browser, connect to the shared one with \`connectOverCDP("${cdpEndpoint}")\` and use the conversation page target instead of an arbitrary existing tab.`,
+        'Never close the shared browser or sign me out. If a site needs login, open it there and ask me to log in; the session persists to your next turn.',
     ].join('\n');
 }
 /** Default persistent profile directory — sandboxed from the user's daily browser. */
@@ -168,6 +180,7 @@ class ManagedBrowser {
         this.child = null;
         this.ownsProcess = false;
         this.resolved = null;
+        this.conversationPages = new Map();
         this.opts = opts;
         this.channel = opts.channel || 'auto';
         this.port = opts.port || DEFAULT_PORT;
@@ -180,6 +193,11 @@ class ManagedBrowser {
     probe() {
         return this.opts.probeFn ? this.opts.probeFn(this.cdpEndpoint()) : probeCdpEndpoint(this.cdpEndpoint());
     }
+    async cdpRequest(requestPath, method = 'GET') {
+        if (this.opts.cdpRequestFn)
+            return this.opts.cdpRequestFn(requestPath, method);
+        return cdpJsonRequest(this.cdpEndpoint(), requestPath, method);
+    }
     /** Live check — does a Chromium CDP endpoint answer on the port right now. */
     isRunning() {
         return this.probe();
@@ -232,6 +250,71 @@ class ManagedBrowser {
         await this.waitForRunning();
         return { endpoint: this.cdpEndpoint(), reused: false, executable: exe.path, channel: exe.channel };
     }
+    async listPageTargets() {
+        const raw = await this.cdpRequest('/json/list');
+        if (!Array.isArray(raw))
+            return [];
+        return raw
+            .filter((target) => Boolean(target && typeof target === 'object' && typeof target.id === 'string'))
+            .filter((target) => !target.type || target.type === 'page');
+    }
+    pageFromTarget(conversationId, target) {
+        return {
+            conversationId,
+            targetId: target.id,
+            url: target.url || 'about:blank',
+            webSocketDebuggerUrl: target.webSocketDebuggerUrl || null,
+            endpoint: this.cdpEndpoint(),
+        };
+    }
+    async ensureConversationPage(conversationId, startUrl = 'about:blank') {
+        const id = conversationId.trim();
+        if (!id)
+            throw new Error('conversationId is required for browser page allocation.');
+        await this.start();
+        const existing = this.conversationPages.get(id);
+        const targets = await this.listPageTargets();
+        if (existing && targets.some((target) => target.id === existing.targetId)) {
+            try {
+                await this.cdpRequest(`/json/activate/${encodeURIComponent(existing.targetId)}`);
+            }
+            catch { /* best effort */ }
+            return existing;
+        }
+        const created = await this.cdpRequest(`/json/new?${encodeURIComponent(startUrl)}`, 'PUT');
+        if (!created || typeof created.id !== 'string') {
+            throw new Error('Browser did not return a page target for the conversation.');
+        }
+        const page = this.pageFromTarget(id, created);
+        this.conversationPages.set(id, page);
+        try {
+            await this.cdpRequest(`/json/activate/${encodeURIComponent(page.targetId)}`);
+        }
+        catch { /* best effort */ }
+        return page;
+    }
+    async releaseConversationPage(conversationId) {
+        const id = conversationId.trim();
+        if (!id)
+            return { released: false, conversationId: id, targetId: null };
+        const existing = this.conversationPages.get(id);
+        this.conversationPages.delete(id);
+        if (!existing)
+            return { released: false, conversationId: id, targetId: null };
+        if (await this.probe()) {
+            try {
+                await this.cdpRequest(`/json/close/${encodeURIComponent(existing.targetId)}`);
+            }
+            catch {
+                // The user may have closed the tab or browser manually. Dropping the
+                // mapping is the important cleanup invariant.
+            }
+        }
+        return { released: true, conversationId: id, targetId: existing.targetId };
+    }
+    conversationPage(conversationId) {
+        return this.conversationPages.get(conversationId.trim()) || null;
+    }
     async waitForRunning() {
         const timeoutMs = this.opts.waitTimeoutMs ?? 15000;
         const intervalMs = this.opts.waitIntervalMs ?? 250;
@@ -263,7 +346,49 @@ class ManagedBrowser {
             channel: this.resolved?.channel || this.channel,
             userDataDir: this.userDataDir,
             executable: this.resolved?.path || null,
+            conversationPages: Array.from(this.conversationPages.values()).map((page) => ({
+                conversationId: page.conversationId,
+                targetId: page.targetId,
+            })),
         };
     }
 }
 exports.ManagedBrowser = ManagedBrowser;
+function cdpJsonRequest(endpoint, requestPath, method) {
+    return new Promise((resolve, reject) => {
+        let url;
+        try {
+            url = new URL(requestPath, endpoint);
+        }
+        catch (error) {
+            reject(error);
+            return;
+        }
+        const req = http_1.default.request(url, { method, timeout: 3000 }, (res) => {
+            let body = '';
+            res.on('data', (chunk) => { body += chunk.toString(); });
+            res.on('end', () => {
+                if ((res.statusCode || 500) >= 400) {
+                    reject(new Error(`CDP ${method} ${requestPath} failed with HTTP ${res.statusCode}`));
+                    return;
+                }
+                if (!body.trim()) {
+                    resolve({});
+                    return;
+                }
+                try {
+                    resolve(JSON.parse(body));
+                }
+                catch {
+                    resolve(body);
+                }
+            });
+        });
+        req.on('error', reject);
+        req.on('timeout', () => {
+            req.destroy();
+            reject(new Error(`CDP ${method} ${requestPath} timed out.`));
+        });
+        req.end();
+    });
+}

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

@@ -3705,8 +3705,24 @@ class AiHubServer {
     // at spawn time instead, so it is available for the entire life of the
     // process. Call this at every startRun/continueRun call site (Direct-mode
     // spawns are exempt — they never load FRAIM, so there is nothing to report).
-    withHubRunIdEnv(launchContext, runId) {
-        return { ...launchContext, env: { ...(launchContext.env || {}), FRAIM_HUB_RUN_ID: runId } };
+    withBrowserConversationEnv(launchContext, runId, conversationId, page) {
+        return {
+            ...launchContext,
+            env: {
+                ...(launchContext.env || {}),
+                FRAIM_HUB_RUN_ID: runId,
+                FRAIM_BROWSER_CONVERSATION_ID: conversationId,
+                ...(page ? {
+                    FRAIM_BROWSER_PAGE_TARGET_ID: page.targetId,
+                    ...(page.webSocketDebuggerUrl ? { FRAIM_BROWSER_PAGE_WS_URL: page.webSocketDebuggerUrl } : {}),
+                } : {}),
+            },
+        };
+    }
+    async releaseBrowserConversationPage(conversationId) {
+        await this.managedBrowser.releaseConversationPage(conversationId).catch((error) => {
+            console.warn('[ai-hub] shared browser page release failed:', error instanceof Error ? error.message : error);
+        });
     }
     // Shared by both the runId-keyed and legacy by-session execution-mode routes.
     applyExecutionModeToRun(runId, body) {
@@ -4204,7 +4220,7 @@ class AiHubServer {
                     this.maybeStartDelegatedChildRuns(updated);
                 });
             },
-        }, startSessionSeedForHost(run.hostId, run.id), this.withHubRunIdEnv(freshLaunch.launchContext, run.id));
+        }, startSessionSeedForHost(run.hostId, run.id), this.withBrowserConversationEnv(freshLaunch.launchContext, run.id, run.conversationId || run.id));
         this.runRegistry.attachChildIfRunning(run.id, freshChild);
     }
     scheduleRunConversationPersistence(run, activeId) {
@@ -4507,7 +4523,7 @@ class AiHubServer {
             onExit: (exitCode) => {
                 this.handleRunExit(currentRun.id, exitCode, options.postPark);
             },
-        }, this.withHubRunIdEnv(launch.launchContext, currentRun.id));
+        }, this.withBrowserConversationEnv(launch.launchContext, currentRun.id, currentRun.conversationId || currentRun.id));
         this.runRegistry.attachChildIfRunning(currentRun.id, child);
         const updated = this.runRegistry.get(currentRun.id);
         if (updated)
@@ -4840,7 +4856,7 @@ class AiHubServer {
                 }
                 this.runRegistry.dispose(childRun.id);
             },
-        }, startSessionSeedForHost(managerRun.hostId, childRun.id), this.withHubRunIdEnv(childLaunch.launchContext, childRun.id));
+        }, startSessionSeedForHost(managerRun.hostId, childRun.id), this.withBrowserConversationEnv(childLaunch.launchContext, childRun.id, childRun.conversationId || childRun.id));
         this.runRegistry.attachChildIfRunning(childRun.id, child);
     }
     notifyManagerOfDelegatedChild(managerRunId, childRun) {
@@ -5004,7 +5020,7 @@ class AiHubServer {
                 if (latestManager)
                     this.drainPendingDelegatedReviews(latestManager);
             },
-        }, this.withHubRunIdEnv(managerLaunch.launchContext, managerRun.id));
+        }, this.withBrowserConversationEnv(managerLaunch.launchContext, managerRun.id, managerRun.conversationId || managerRun.id));
         this.runRegistry.attachChildIfRunning(managerRun.id, child);
     }
     computeFirstRun(projectPath, jobCount, personas) {
@@ -5113,6 +5129,9 @@ class AiHubServer {
         // unpromoted and then dropping its phase signals).
         this.maybePromoteFreeformRunToJob(run, signal.jobName || signal.jobId);
         applySeekMentoringSignal(run, signal);
+        if (signal.phaseId === 'retrospective' && signal.phaseStatus === 'complete') {
+            void this.releaseBrowserConversationPage(run.conversationId || run.id);
+        }
     }
     applyFraimJobSignalToRun(run, signal) {
         this.maybePromoteFreeformRunToJob(run, signal.jobId);
@@ -5153,7 +5172,7 @@ class AiHubServer {
         // #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 browserNote = (0, managed_browser_1.buildBrowserContextNote)(process.env.FRAIM_BROWSER_CDP_ENDPOINT, process.env.FRAIM_HUB_BASE_URL, options?.browserConversationId, options?.browserPage);
         const styleNote = (0, manager_turns_1.buildCommunicationStyleNote)();
         const backgroundTaskNote = (0, manager_turns_1.buildBackgroundTaskPolicyNote)();
         const ignoreEmbedded = options?.ignoreEmbeddedInvocation === true;
@@ -5873,7 +5892,7 @@ class AiHubServer {
         });
         // Issue #1740: interactive run deletion is a bounded one-record mutation. It requires an
         // explicit record-owned partition and never falls back to the currently selected project.
-        this.app.delete('/api/ai-hub/conversations/:conversationId', (req, res) => {
+        this.app.delete('/api/ai-hub/conversations/:conversationId', async (req, res) => {
             try {
                 const scope = scopeParam(req.query.scope);
                 if (!scope && (typeof req.query.projectPath !== 'string' || req.query.projectPath.trim().length === 0)) {
@@ -5885,6 +5904,7 @@ class AiHubServer {
                 const result = this.conversationStore.deleteConversation(key, req.params.conversationId);
                 if (!result.removed)
                     return res.status(404).json({ error: 'Conversation not found.' });
+                await this.releaseBrowserConversationPage(req.params.conversationId);
                 return res.json(result);
             }
             catch (error) {
@@ -6017,7 +6037,7 @@ class AiHubServer {
                     attemptedRunId = run.id;
                     const hostMessage = strategy === 'resume_same_host'
                         ? this.prepareContinueMessage(run, managerNote).message
-                        : this.prepareStartPayload(run.projectPath, run.hostId, run.jobId, renderAgentSwitchHandoffPrompt(handoffSummary, managerNote)).message;
+                        : this.prepareStartPayload(run.projectPath, run.hostId, run.jobId, renderAgentSwitchHandoffPrompt(handoffSummary, managerNote), { browserConversationId: run.conversationId || run.id }).message;
                     this.runRegistry.create(run, {});
                     this.persistRunConversation(run, run.conversationId || run.id);
                     const handlers = {
@@ -6063,8 +6083,8 @@ class AiHubServer {
                     };
                     this.recordHubGeneratedEvent(run, 'agent_input', hostMessage);
                     const child = strategy === 'resume_same_host'
-                        ? this.hostRuntime.continueRun(run.hostId, run.projectPath, priorSessionId, hostMessage, handlers, this.withHubRunIdEnv(resolved.launchContext, run.id))
-                        : this.hostRuntime.startRun(run.hostId, run.projectPath, hostMessage, handlers, startSessionSeedForHost(run.hostId, run.id), this.withHubRunIdEnv(resolved.launchContext, run.id));
+                        ? this.hostRuntime.continueRun(run.hostId, run.projectPath, priorSessionId, hostMessage, handlers, this.withBrowserConversationEnv(resolved.launchContext, run.id, run.conversationId || run.id))
+                        : this.hostRuntime.startRun(run.hostId, run.projectPath, hostMessage, handlers, startSessionSeedForHost(run.hostId, run.id), this.withBrowserConversationEnv(resolved.launchContext, run.id, run.conversationId || run.id));
                     this.runRegistry.attachChildIfRunning(run.id, child);
                     attemptedRunId = null;
                     console.info(`[ai-hub] hub.agent_switch.${strategy}`, {
@@ -6794,7 +6814,7 @@ class AiHubServer {
         // The proxy parses the Execution Mode Context block and POSTs here; Hub script reads from run poll.
         //
         // Issue #1443: the local proxy's only stable identity for "which run is this" is the
-        // Hub's own run id (see withHubRunIdEnv / FRAIM_HUB_RUN_ID) — the FRAIM/MCP session id it
+        // Hub's own run id (see FRAIM_HUB_RUN_ID) — the FRAIM/MCP session id it
         // carries is unrelated to any Hub run, and the host CLI's own session id (run.sessionId)
         // often isn't known yet when the first get_fraim_job call fires. Runs by id, not session.
         this.app.post('/api/ai-hub/runs/:runId/execution-mode', (req, res) => {
@@ -6849,8 +6869,13 @@ class AiHubServer {
                 }
                 const employees = this.hostRuntime.detectEmployees();
                 const { hostId, agent: configuredAgent, launchContext } = this.resolveLaunchAgent(req.body.configuredAgentId, requestedHostId, employees);
+                const runId = (0, crypto_1.randomUUID)();
+                const requestedConversationId = typeof req.body.conversationId === 'string' && req.body.conversationId.trim()
+                    ? req.body.conversationId.trim()
+                    : undefined;
+                const browserConversationId = requestedConversationId || runId;
                 const prepared = instructions
-                    ? this.prepareStartPayload(projectPath, hostId, req.body.jobId, instructions)
+                    ? this.prepareStartPayload(projectPath, hostId, req.body.jobId, instructions, { browserConversationId })
                     : {
                         jobId: req.body.jobId,
                         message: legacyMessage,
@@ -6890,9 +6915,6 @@ class AiHubServer {
                 const fallbackJobTitle = typeof req.body.jobTitle === 'string' && req.body.jobTitle.trim()
                     ? req.body.jobTitle.trim()
                     : jobId;
-                const requestedConversationId = typeof req.body.conversationId === 'string' && req.body.conversationId.trim()
-                    ? req.body.conversationId.trim()
-                    : undefined;
                 const continuity = this.validateRunConversationContinuity({
                     conversationId: requestedConversationId,
                     projectPath,
@@ -6912,7 +6934,7 @@ class AiHubServer {
                     ? this.resolveMessageAttachments((0, conversation_store_1.conversationScopeKey)(scope, projectPath), requestedConversationId, req.body.attachmentIds)
                     : { attachments: undefined, referenceSuffix: '' };
                 const run = {
-                    id: (0, crypto_1.randomUUID)(),
+                    id: runId,
                     conversationId: requestedConversationId,
                     conversationTitle: typeof req.body.conversationTitle === 'string' && req.body.conversationTitle.trim() ? req.body.conversationTitle.trim() : undefined,
                     jobTitle: jobMetadata?.title || fallbackJobTitle,
@@ -7025,7 +7047,7 @@ class AiHubServer {
                             this.maybeStartDelegatedChildRuns(updated);
                         });
                     },
-                }, startSessionSeedForHost(hostId, run.id), this.withHubRunIdEnv(launchContext, run.id));
+                }, startSessionSeedForHost(hostId, run.id), this.withBrowserConversationEnv(launchContext, run.id, run.conversationId || run.id));
                 pendingSpawnRuns.delete(run);
                 this.runRegistry.attachChildIfRunning(run.id, child);
                 // Issue #442: spawn the Direct run via startDirectRun so CliHostRuntime
@@ -7103,9 +7125,14 @@ class AiHubServer {
             const running = await this.managedBrowser.isRunning();
             res.json({ running, ...this.managedBrowser.status() });
         });
-        this.app.post('/api/ai-hub/browser/start', async (_req, res) => {
+        this.app.post('/api/ai-hub/browser/start', async (req, res) => {
             try {
-                const result = await this.ensureManagedBrowser();
+                const body = (req.body ?? {});
+                const conversationId = typeof body.conversationId === 'string' && body.conversationId.trim()
+                    ? body.conversationId.trim()
+                    : undefined;
+                const url = typeof body.url === 'string' && body.url.trim() ? body.url.trim() : undefined;
+                const result = await this.ensureManagedBrowser(conversationId, url);
                 res.json({
                     ok: true,
                     ...result,
@@ -7203,8 +7230,8 @@ class AiHubServer {
                         ? buildAgentSwitchHandoffSummary(conversation)
                         : null;
                     const freshPayload = handoffSummary
-                        ? this.prepareStartPayload(run.projectPath, run.hostId, run.jobId, renderAgentSwitchHandoffPrompt(handoffSummary, prepared.display || message))
-                        : this.prepareStartPayload(run.projectPath, run.hostId, run.jobId, prepared.display || message);
+                        ? this.prepareStartPayload(run.projectPath, run.hostId, run.jobId, renderAgentSwitchHandoffPrompt(handoffSummary, prepared.display || message), { browserConversationId: run.conversationId || run.id })
+                        : this.prepareStartPayload(run.projectPath, run.hostId, run.jobId, prepared.display || message, { browserConversationId: run.conversationId || run.id });
                     this.runRegistry.update(run.id, (current) => {
                         current.status = 'running';
                         current.pauseReason = 'working';
@@ -7269,7 +7296,7 @@ class AiHubServer {
                                 this.maybeStartDelegatedChildRuns(updated);
                             });
                         },
-                    }, startSessionSeedForHost(run.hostId, run.id), this.withHubRunIdEnv(freshLaunch.launchContext, run.id));
+                    }, startSessionSeedForHost(run.hostId, run.id), this.withBrowserConversationEnv(freshLaunch.launchContext, run.id, run.conversationId || run.id));
                     this.runRegistry.attachChildIfRunning(run.id, freshChild);
                     const refreshedFresh = this.runRegistry.get(run.id);
                     return res.json(refreshedFresh ? this.enrichRunForResponse(refreshedFresh) : refreshedFresh);
@@ -7392,7 +7419,7 @@ class AiHubServer {
                         if (failedInterrupt)
                             this.scheduleRunConversationPersistence(failedInterrupt, failedInterrupt.conversationId || failedInterrupt.id);
                     },
-                }, this.withHubRunIdEnv(continueLaunch.launchContext, run.id), deliveryIntent);
+                }, this.withBrowserConversationEnv(continueLaunch.launchContext, run.id, run.conversationId || run.id), deliveryIntent);
                 if (!startedCodexReviewApprovalFallback)
                     this.runRegistry.attachChildIfRunning(run.id, child);
                 const refreshed = this.runRegistry.get(run.id);
@@ -7504,7 +7531,7 @@ class AiHubServer {
                 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);
+                    : (0, managed_browser_1.buildBrowserContextNote)(process.env.FRAIM_BROWSER_CDP_ENDPOINT, process.env.FRAIM_HUB_BASE_URL, run.conversationId || run.id);
                 const message = preparedResume.message + browserContextNote;
                 // #521: bubble shows the manager's words; the agent gets the full message.
                 const managerMessage = (0, hosts_1.createHubMessage)('manager', preparedResume.display || message);
@@ -7559,7 +7586,7 @@ class AiHubServer {
                     onExit: (exitCode) => {
                         this.handleRunExit(run.id, exitCode);
                     },
-                }, this.withHubRunIdEnv(launchContext, run.id));
+                }, this.withBrowserConversationEnv(launchContext, run.id, run.conversationId || run.id));
                 this.runRegistry.attachChildIfRunning(run.id, child);
                 res.status(201).json(this.enrichRunForResponse(this.runRegistry.get(run.id) ?? run));
             }
@@ -8453,7 +8480,7 @@ class AiHubServer {
                             this.finalizeRunConversationProjection(run.id, updated.conversationId || updated.id);
                         this.runRegistry.dispose(run.id);
                     },
-                }, startSessionSeedForHost(hostId, run.id), this.withHubRunIdEnv(launchContext, run.id));
+                }, startSessionSeedForHost(hostId, run.id), this.withBrowserConversationEnv(launchContext, run.id, run.conversationId || run.id));
                 // Update the registry entry with the real child process handle.
                 this.runRegistry.attachChildIfRunning(run.id, child);
                 return res.json({
@@ -8473,10 +8500,13 @@ 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() {
+    async ensureManagedBrowser(conversationId, url) {
         const result = await this.managedBrowser.start();
         process.env.FRAIM_BROWSER_CDP_ENDPOINT = result.endpoint;
-        return { endpoint: result.endpoint, reused: result.reused, channel: result.channel };
+        const page = conversationId
+            ? await this.managedBrowser.ensureConversationPage(conversationId, url)
+            : undefined;
+        return { endpoint: result.endpoint, reused: result.reused, channel: result.channel, ...(page ? { page } : {}) };
     }
     // ─── Issue #578: Scheduled deployment helpers ─────────────────────────────
     rehydrateScheduledDeployments() {
@@ -8734,7 +8764,7 @@ class AiHubServer {
                 this.deploymentStore.update(deployment.id, (d) => { d.activeRunId = undefined; });
             }),
         };
-        const childLaunchContext = this.withHubRunIdEnv(launchContext, run.id);
+        const childLaunchContext = this.withBrowserConversationEnv(launchContext, run.id, run.conversationId || run.id);
         this.recordHubGeneratedEvent(run, 'agent_input', instructions);
         const child = existingHostSession
             ? this.hostRuntime.continueRun(hostId, effectiveDeployment.projectPath, existingHostSession.sessionId, instructions, handlers, childLaunchContext)
@@ -8917,7 +8947,7 @@ class AiHubServer {
                             this.scheduleRunConversationPersistence(updated, updated.conversationId || updated.id);
                     },
                     onExit: (code) => this.handleRunExit(runId, code, postPark),
-                }, this.withHubRunIdEnv(launchContext, runId));
+                }, this.withBrowserConversationEnv(launchContext, runId, current.conversationId || current.id));
                 this.runRegistry.attachChildIfRunning(runId, child);
             }, delay);
             if (tid.unref)

package/dist/src/cli/utils/pack-home.js

@@ -113,12 +113,14 @@ function defaultCloneDir(layer) {
  * Resolve where this layer's details live. Never throws and never touches the
  * network; call `ensurePackClone` separately when the git working copy has to
  * be present and current.
+ * Read-only inventory callers set `migrateLegacy: false` to suppress the
+ * otherwise backwards-compatible flat org layout migration.
  */
-function resolvePackHome(layer) {
+function resolvePackHome(layer, options = {}) {
     const config = (0, user_config_1.getLayerBackend)(layer);
     const standard = standardHome(layer);
     const make = (root, extra) => {
-        if (layer === 'org')
+        if (layer === 'org' && options.migrateLegacy !== false)
             migrateOrgFlatContent(root);
         return { layer, root, contentRoot: path_1.default.join(root, 'personalized-employee'), ...extra };
     };