Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

fix: name the stalled phase and owned-browser state in composition CDP timeouts (#12294)

[._.]/ Adam Eivyab068c03ce5c
diff --git a/server/services/htmlComposition/browser.js b/server/services/htmlComposition/browser.js
index d8e53ca4db..25717d1a86 100644
--- a/server/services/htmlComposition/browser.js
+++ b/server/services/htmlComposition/browser.js
@@ -61,6 +61,12 @@ export async function snapshotAssets(directory, { streamMedia = false } = {}) {
return assets;
}
+// Events whose arrival distinguishes a closed, crashed or detached target from
+// a live session that simply never answered. Only the method name is retained.
+const LIFECYCLE_EVENTS = new Set([
+ 'Target.detachedFromTarget', 'Target.targetCrashed', 'Target.targetDestroyed', 'Inspector.detached', 'Inspector.targetCrashed',
+]);
+
// One browser-level socket owns a disposable context and its hidden target.
// Disconnect/abort rejects pending commands; disposeOnDetach covers crashes.
// `bytes=a-b` / `bytes=a-` / `bytes=-n` against `size`; null when absent or unsatisfiable.
@@ -137,6 +143,7 @@ export async function openComposition(directory, {
const page = await connectComposition(assets, {
...connectOptions,
transport: owner.transport,
+ lifecycleFacts: owner.lifecycleFacts,
version: owner.transport
? { 'User-Agent': 'HeadlessChrome/' }
: { webSocketDebuggerUrl: owner.webSocketDebuggerUrl, 'User-Agent': 'HeadlessChrome/' },
@@ -157,7 +164,7 @@ export async function openComposition(directory, {
async function connectComposition(assets, {
signal, mediaMode, version, initScripts = [], transport, contentSecurityPolicy, freezeNetworkConstructors = true,
- onEvent, previewBridge = false, refuseUnknown = 'fail', lockLoopback = false,
+ onEvent, previewBridge = false, refuseUnknown = 'fail', lockLoopback = false, lifecycleFacts,
}) {
const { webSocketDebuggerUrl } = version || {};
if (!transport && !webSocketDebuggerUrl) throw new Error('Managed browser has no CDP endpoint');
@@ -168,6 +175,28 @@ async function connectComposition(assets, {
let contextId;
let sessionId;
let closing = false;
+ // Failure-only evidence for a command that never answers (#12294): which
+ // setup step was reached, whether the connection and session were still
+ // talking, which allowlisted lifecycle events arrived and what the owned
+ // child had done. Names and counters only; never params, payloads or paths.
+ const startedAt = performance.now();
+ const sinceStart = () => Math.round(performance.now() - startedAt);
+ let phase = 'connect';
+ let lastInboundMs = null;
+ let lastSessionInboundMs = null;
+ let transportState = 'open';
+ const lifecycleEvents = new Set();
+ const commandFacts = (sentMs) => {
+ const owned = (() => { try { return lifecycleFacts?.() ?? {}; } catch { return { owner: 'unreadable' }; } })();
+ const facts = {
+ phase, sentMs, timeoutMs: sinceStart(),
+ context: contextId ? 'created' : 'none', session: sessionId ? 'attached' : 'none',
+ transport: transportState, lastInboundMs, lastSessionInboundMs,
+ events: lifecycleEvents.size ? [...lifecycleEvents].join('|') : 'none', pending: pending.size,
+ ...owned,
+ };
+ return Object.entries(facts).map(([key, value]) => `${key}=${value ?? 'unobserved'}`).join(', ');
+ };
const fail = (error) => {
failure ??= error;
for (const command of pending.values()) command.reject(failure);
@@ -179,7 +208,9 @@ async function connectComposition(assets, {
if (failure) return Promise.reject(failure);
return new Promise((resolveCommand, rejectCommand) => {
const id = ++nextId;
- const timer = setTimeout(() => fail(new Error(`Browser command timed out: ${method}`)), 30000);
+ const sentMs = sinceStart();
+ // The prefix is matched by encode.js page recovery; facts follow it.
+ const timer = setTimeout(() => fail(new Error(`Browser command timed out: ${method} (${commandFacts(sentMs)})`)), 30000);
const finish = (fn) => (value) => { clearTimeout(timer); pending.delete(id); fn(value); };
pending.set(id, { resolve: finish(resolveCommand), reject: finish(rejectCommand) });
ws.send(JSON.stringify({ id, method, params, ...(session ? { sessionId: session } : {}) }), error => {
@@ -246,6 +277,9 @@ async function connectComposition(assets, {
ws.on('message', bytes => {
try {
const message = JSON.parse(bytes.toString());
+ lastInboundMs = sinceStart();
+ if (sessionId && message.sessionId === sessionId) lastSessionInboundMs = lastInboundMs;
+ if (LIFECYCLE_EVENTS.has(message.method)) lifecycleEvents.add(message.method);
if (message.id) {
const command = pending.get(message.id);
if (message.error) command?.reject(new Error(message.error.message));
@@ -275,8 +309,11 @@ async function connectComposition(assets, {
}
} catch (error) { fail(error); }
});
- ws.on('error', fail);
- ws.on('close', () => { if (!closing) fail(new Error('Managed browser disconnected')); });
+ ws.on('error', error => { transportState = 'error'; fail(error); });
+ ws.on('close', () => {
+ if (transportState === 'open') transportState = 'closed';
+ if (!closing) fail(new Error('Managed browser disconnected'));
+ });
async function close({ verify = false } = {}) {
closing = true;
signal?.removeEventListener('abort', abort);
@@ -306,6 +343,7 @@ async function connectComposition(assets, {
ws.once('close', () => rejectOpen(failure ?? new Error('Managed browser disconnected')));
});
signal?.throwIfAborted();
+ phase = 'create-context';
({ browserContextId: contextId } = await send('Target.createBrowserContext', {
disposeOnDetach: true,
// Defense in depth for browser-originated HTTP requests outside Fetch.
@@ -315,9 +353,12 @@ async function connectComposition(assets, {
// Headless Chrome has no tab UI to hide. Give its compositor a foreground
// target: hidden targets can stall surface screenshots on Linux. Headed
// managed browsers retain the hidden, background rendering posture.
+ phase = 'create-target';
const headless = /HeadlessChrome\//.test(version['User-Agent'] || '');
const { targetId } = await send('Target.createTarget', { url: 'about:blank', browserContextId: contextId, hidden: !headless, background: !headless }, null);
+ phase = 'attach';
({ sessionId } = await send('Target.attachToTarget', { targetId, flatten: true }, null));
+ phase = 'session-setup';
await send('Page.enable');
await send('Runtime.enable');
await send('Runtime.addBinding', { name: '__portosRefused' });
@@ -391,10 +432,12 @@ async function connectComposition(assets, {
if (previewBridge) await send('Page.addScriptToEvaluateOnNewDocument', { source: PREVIEW_BRIDGE_SCRIPT });
for (const source of initScripts) await send('Page.addScriptToEvaluateOnNewDocument', { source });
await send('Fetch.enable', { patterns: [{ urlPattern: '*', requestStage: 'Request' }] });
+ phase = 'navigate';
const navigation = await send('Page.navigate', { url: `${ORIGIN}/index.html` });
if (navigation.errorText) throw new Error(`Composition navigation failed: ${navigation.errorText}`);
await evaluate(`new Promise(resolve => document.readyState === 'complete' ? resolve() : addEventListener('load', resolve, { once: true }))`, 'document load');
await evaluate('document.fonts.ready.then(() => true)', 'font readiness');
+ phase = 'ready';
return { evaluate, send, close, check: () => { signal?.throwIfAborted(); if (failure) throw failure; } };
} catch (error) {
await close();
diff --git a/server/services/htmlComposition/browser.setupDiagnostics.test.js b/server/services/htmlComposition/browser.setupDiagnostics.test.js
new file mode 100644
index 0000000000..303faedd8c
--- /dev/null
+++ b/server/services/htmlComposition/browser.setupDiagnostics.test.js
@@ -0,0 +1,81 @@
+// A CDP setup command that never answers must leave evidence of which step,
+// connection and owned-child state it stalled in, read before cleanup and
+// without page content or paths (#12294). Real Chrome cannot hang on demand,
+// so a scripted pipe transport stands in for the owned browser.
+import { afterAll, afterEach, describe, expect, it, vi } from 'vitest';
+import { EventEmitter } from 'node:events';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { cleanupTempDataRoots, lazyTempDataRoot, makePathsProxy } from '../../lib/mockPathsDataRoot.js';
+
+vi.mock('../../lib/fileUtils.js', async importOriginal => makePathsProxy(await importOriginal(), {
+ dataRoot: () => lazyTempDataRoot('portos-composition-setup-diagnostics-'),
+}));
+
+const owner = vi.hoisted(() => ({ order: [], transport: null, sent: null }));
+vi.mock('./ownedBrowser.js', () => ({
+ launchCompositionBrowser: async () => ({
+ transport: owner.transport,
+ lifecycleFacts: () => {
+ owner.order.push('facts');
+ return { childSpawned: true, childExited: false, childClosed: false, exitCode: 'none', signalCode: 'none' };
+ },
+ close: async () => { owner.order.push('close'); },
+ }),
+}));
+
+const REPLIES = {
+ 'Target.createBrowserContext': { browserContextId: 'context-example' },
+ 'Target.createTarget': { targetId: 'target-example' },
+ 'Target.attachToTarget': { sessionId: 'session-example' },
+};
+
+// Answers browser-level setup, then leaves `stallOn` pending forever.
+function scriptedTransport(stallOn) {
+ const emitter = new EventEmitter();
+ let stalled;
+ owner.sent = new Promise(resolve => { stalled = resolve; });
+ return {
+ readyState: 1,
+ send(text, callback) {
+ callback?.();
+ const { id, method } = JSON.parse(text);
+ if (method === stallOn) return stalled();
+ setImmediate(() => emitter.emit('message', Buffer.from(JSON.stringify({ id, result: REPLIES[method] ?? {} }))));
+ },
+ terminate() { this.readyState = 3; },
+ on: emitter.on.bind(emitter),
+ once: emitter.once.bind(emitter),
+ };
+}
+
+const { PATHS } = await import('../../lib/fileUtils.js');
+const { openComposition } = await import('./browser.js');
+
+afterEach(() => { vi.useRealTimers(); owner.order = []; });
+afterAll(() => cleanupTempDataRoots());
+
+describe('composition CDP setup timeout evidence', () => {
+ it('names the stalled phase, session and owned-child state before cleanup, without content or paths', async () => {
+ const directory = 'compositions/setup-diagnostics';
+ await mkdir(join(PATHS.data, directory), { recursive: true });
+ await writeFile(join(PATHS.data, directory, 'index.html'), '<html><body>private-marker</body></html>');
+ owner.transport = scriptedTransport('Page.enable');
+ vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] });
+
+ const opened = openComposition(directory, { ownedBrowser: true }).catch(error => error);
+ await owner.sent;
+ await vi.advanceTimersByTimeAsync(30000);
+ const error = await opened;
+
+ expect(error.message).toMatch(/^Browser command timed out: Page\.enable \(/);
+ expect(error.message).toContain('phase=session-setup');
+ expect(error.message).toContain('context=created, session=attached, transport=open');
+ expect(error.message).toContain('events=none');
+ expect(error.message).toContain('childSpawned=true, childExited=false, childClosed=false, exitCode=none, signalCode=none');
+ expect(error.message).not.toContain('private-marker');
+ expect(error.message).not.toContain(PATHS.data);
+ expect(error.message).not.toContain('session-example');
+ expect(owner.order).toEqual(['facts', 'close']);
+ });
+});
diff --git a/server/services/htmlComposition/ownedBrowser.js b/server/services/htmlComposition/ownedBrowser.js
index e7e1d2f3a9..6821af2ffc 100644
--- a/server/services/htmlComposition/ownedBrowser.js
+++ b/server/services/htmlComposition/ownedBrowser.js
@@ -114,6 +114,14 @@ export async function launchCompositionBrowser({
const observedMs = () => Math.round(performance.now() - observedSince);
const groupTermination = { term: 'not-attempted', kill: 'not-attempted', error: 'none', failedSignal: 'none', failedPhase: 'none' };
const termination = { term: 'not-attempted', kill: 'not-attempted', error: 'none' };
+ // Never interpolate arbitrary child properties: only allowlisted status values.
+ const childStatus = () => ({
+ exitCode: proc?.exitCode == null ? 'none' : Number.isSafeInteger(proc.exitCode) ? proc.exitCode : 'other',
+ signalCode: proc?.signalCode == null ? 'none'
+ : typeof proc.signalCode === 'string' && Object.hasOwn(osConstants.signals, proc.signalCode) ? proc.signalCode : 'other',
+ });
+ // Read by the CDP client when a command fails, before close() changes them.
+ const lifecycleFacts = () => ({ childSpawned: spawned, childExited: exited, childClosed: closed, ...childStatus() });
const safeSignalError = error => ['EPERM', 'ESRCH', 'EINVAL', 'ENOSYS'].includes(error?.code) ? error.code : 'other';
const cleanupProfile = () => {
if (!profileCleanup) {
@@ -207,9 +215,7 @@ export async function launchCompositionBrowser({
// Never interpolate arbitrary child properties, errors or output.
// Public status and observed events are separate evidence: accepted
// signals alone do not establish that the child has exited.
- const exitCode = proc.exitCode == null ? 'none' : Number.isSafeInteger(proc.exitCode) ? proc.exitCode : 'other';
- const signalCode = proc.signalCode == null ? 'none'
- : typeof proc.signalCode === 'string' && Object.hasOwn(osConstants.signals, proc.signalCode) ? proc.signalCode : 'other';
+ const { exitCode, signalCode } = childStatus();
const facts = {
exit: exited, stdioClosed: Boolean(proc.stderr?.destroyed),
term: termination.term, kill: termination.kill, signalError: termination.error,
@@ -322,8 +328,8 @@ export async function launchCompositionBrowser({
signal?.addEventListener('abort', abort, { once: true });
signal?.throwIfAborted();
if (startupPipeError) throw new Error('Composition browser failed to start (pipe)');
- if (piped) return { transport, close, mechanism: plan.mechanism };
- return { webSocketDebuggerUrl: ready, close };
+ if (piped) return { transport, close, lifecycleFacts, mechanism: plan.mechanism };
+ return { webSocketDebuggerUrl: ready, close, lifecycleFacts };
} catch (error) {
await close();
throw error;