@monoes/monobrowse 1.0.16 → 1.0.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monoes/monobrowse",
-  "version": "1.0.16",
+  "version": "1.0.17",
   "description": "Native browser automation via Chrome DevTools Protocol — the engine powering monomind browse",
   "type": "module",
   "bin": {

package/src/__tests__/report-exit-code.test.ts

@@ -0,0 +1,207 @@
+/**
+ * `monobrowse report` exited 0, and printed nothing at all, on a page that
+ * FAILED its budgets — while the report JSON it had already written on disk
+ * said `"verdict": "fail"`. Anything gating on exit status (CI, an agent, a
+ * shell `&&` chain) saw green on a broken page, which defeats the entire
+ * point of the budgets feature.
+ *
+ * Two things combined to cause it:
+ *
+ *   1. closeBrowser() could hang. Its timers were unref'd, so once Chrome's
+ *      CDP socket went away nothing was left holding the event loop open and
+ *      Node exited before those timers ever fired. (browser.ts; the poll-loop
+ *      half of this is #314's launch-close-settle.test.ts.)
+ *
+ *   2. commands-report.ts awaited that teardown in a `finally` positioned
+ *      BETWEEN producing the result and printing it. So a hung teardown took
+ *      the verdict down with it: the print never ran, `exitCode: 1` was never
+ *      returned, and Node drained the loop and exited 0.
+ *
+ * (1) alone is not enough to make this safe — any future teardown hang would
+ * silently reintroduce it. (2) is the ordering fix: print the verdict and fix
+ * process.exitCode BEFORE teardown, so a teardown that never settles can no
+ * longer turn a failing page green.
+ *
+ * WHY THIS IS A SUBPROCESS TEST. The bug only exists in the semantics of a
+ * real process exit — "the event loop drained while a promise was still
+ * pending, so Node exited with the code it had". An in-process test cannot
+ * observe that: vitest's own runner pins the event loop, so the hang simply
+ * becomes a pending promise and the exit code is never consulted. (#314's
+ * test says the same thing about fake timers.) So this spawns a real `node`
+ * and asserts the code the OS sees.
+ *
+ * WHY IT NEEDS NO CHROME. The suite is deliberately browser-free (see the
+ * monobrowse note in .github/workflows/tests.yml) and this keeps it that way.
+ * The child imports the REAL built commands-report.js, but next to stub
+ * `session.js` / `report/index.js` modules in a temp sandbox — commands-report
+ * has only those two static imports, and output.js has none, so copying three
+ * files reproduces its module graph exactly with no loader hooks and no
+ * Node-version-specific API. The stub's closeBrowser() is the hang, modelled
+ * as a promise that never settles — which is precisely what an unref'd timer
+ * on a dead socket degrades into.
+ *
+ * Requires `npm run build` (CI's monobrowse job builds before `npm test`).
+ */
+
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { cp, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const distCli = join(here, '..', '..', 'dist', 'src', 'cli');
+const hasBuild = existsSync(join(distCli, 'commands-report.js'));
+
+let sandbox: string;
+
+beforeEach(async () => {
+  sandbox = await mkdtemp(join(tmpdir(), 'monobrowse-report-exit-'));
+});
+
+afterEach(async () => {
+  await rm(sandbox, { recursive: true, force: true });
+});
+
+/** Stub `cli/session.js`. `closeBrowser` is the failure under test. */
+function sessionStub(mode: 'hang' | 'clean'): string {
+  const close =
+    mode === 'hang'
+      ? // Never settles — a teardown that is wedged forever. An unref'd timer
+        // racing a dead socket degrades into exactly this.
+        'closeBrowser: () => new Promise(() => {}),'
+      : 'closeBrowser: async () => {},';
+  return `
+export const session = {
+  client: null, sessionId: '', targetId: '', port: 9222,
+  refs: new Map(), parentSessionId: '',
+};
+export async function ensureConnected(port) {
+  session.client = {}; session.sessionId = 'stub-session';
+  return { client: session.client, sessionId: session.sessionId };
+}
+export function print(line) { console.log(line); }
+export async function getBrowser() {
+  return {
+    // Non-undefined so the teardown branch actually runs (it is skipped for
+    // a browser this process did not launch).
+    getLaunchedPid: () => 4242,
+    stopRequestCapture: () => {},
+    teardownConsoleCapture: () => {},
+    ${close}
+    clearActivePort: async () => {},
+    clearRefCache: async () => {},
+  };
+}
+export function ensureSignalCleanupHandlers() {}
+`;
+}
+
+/** Stub `report/index.js` — a run that FAILED its budgets. */
+const reportStub = `
+const report = {
+  verdict: 'fail',
+  failures: [{ budget: 'maxConsoleErrors', expected: '<= 0', actual: 3, detail: 'boom' }],
+  notes: [],
+  trend: undefined,
+  diff: undefined,
+};
+export async function runReport() {
+  return {
+    report,
+    htmlPath: '/stub/r.html',
+    jsonPath: '/stub/r.json',
+    summary: '✗ FAIL — 1 budget failure(s)',
+    historyDir: undefined,
+    flake: undefined,
+  };
+}
+export const runReportRepeated = runReport;
+export async function readHistory() { return { dir: '/stub', runs: [] }; }
+export function toJsonReport(r) { return r; }
+`;
+
+/** Harness: mirrors cli.ts's real shape — `main().then(() => process.exit(...))`,
+ *  NOT a top-level await. That distinction is the whole bug: with a top-level
+ *  await Node notices the unsettled promise and exits 13, but cli.ts's promise
+ *  chain simply never runs its `.then`, so the loop drains and the process
+ *  exits with whatever process.exitCode holds — 0, unless someone set it. */
+const harness = `
+import { reportCommand } from './cli/commands-report.js';
+
+async function main() {
+  const result = await reportCommand.action({
+    args: ['http://127.0.0.1:1/broken.html'],
+    flags: { out: '/stub/r.html' },
+    cwd: process.cwd(),
+    interactive: false,
+  });
+  // Only reached when teardown settles. cli.ts does exactly this.
+  if (result && !result.success) process.exitCode = result.exitCode ?? 1;
+}
+
+main()
+  .then(() => { process.exit(process.exitCode ?? 0); })
+  .catch((err) => { console.error(err?.message ?? String(err)); process.exit(1); });
+`;
+
+async function runChild(mode: 'hang' | 'clean'): Promise<{
+  code: number | null;
+  stdout: string;
+  stderr: string;
+}> {
+  await mkdir(join(sandbox, 'cli'), { recursive: true });
+  await mkdir(join(sandbox, 'report'), { recursive: true });
+  await cp(join(distCli, 'commands-report.js'), join(sandbox, 'cli', 'commands-report.js'));
+  await cp(join(distCli, 'output.js'), join(sandbox, 'cli', 'output.js'));
+  await writeFile(join(sandbox, 'cli', 'session.js'), sessionStub(mode), 'utf-8');
+  await writeFile(join(sandbox, 'report', 'index.js'), reportStub, 'utf-8');
+  await writeFile(join(sandbox, 'run.mjs'), harness, 'utf-8');
+
+  return await new Promise((resolve) => {
+    const child = spawn(process.execPath, [join(sandbox, 'run.mjs')], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      cwd: sandbox,
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d) => (stdout += String(d)));
+    child.stderr.on('data', (d) => (stderr += String(d)));
+    // A hung teardown must still let the process EXIT (by draining), so if
+    // the child is genuinely still alive here the test should fail loudly
+    // rather than hang the suite.
+    const kill = setTimeout(() => child.kill('SIGKILL'), 15_000);
+    child.on('close', (code) => {
+      clearTimeout(kill);
+      resolve({ code, stdout, stderr });
+    });
+  });
+}
+
+describe.skipIf(!hasBuild)('report exit code survives a hung browser teardown', () => {
+  it('exits non-zero and prints the verdict even when closeBrowser never settles', async () => {
+    const { code, stdout, stderr } = await runChild('hang');
+
+    // THE BUG: this was 0 — a failing page reported as success, with the
+    // process exiting cleanly because the loop drained mid-teardown.
+    expect(code).toBe(1);
+    // ...and the verdict was never printed at all.
+    expect(stderr + stdout).toContain('FAIL');
+    expect(stdout).toContain('maxConsoleErrors');
+  }, 30_000);
+
+  it('still exits non-zero on the normal path where teardown completes', async () => {
+    const { code, stdout, stderr } = await runChild('clean');
+
+    expect(code).toBe(1);
+    expect(stderr + stdout).toContain('FAIL');
+  }, 30_000);
+});
+
+describe.skipIf(hasBuild)('report exit code subprocess test', () => {
+  it('is skipped because dist/ is not built (run `npm run build`)', () => {
+    expect(hasBuild).toBe(false);
+  });
+});

package/src/browser/actions.ts

@@ -680,18 +680,27 @@ export async function evaluateJs(
     sessionId,
   );
 
-  const result = await (timeoutMs > 0
-    ? Promise.race([
-        evalPromise,
-        new Promise<never>((_, reject) => {
-          const t = setTimeout(
-            () => reject(new Error(`JS evaluation timed out after ${timeoutMs}ms`)),
-            timeoutMs,
-          );
-          t.unref?.();
-        }),
-      ])
-    : evalPromise);
+  // Not unref'd (same rule as CdpClient.send): this timer settles the awaited
+  // race, so it has to hold the event loop open while the evaluation is in
+  // flight. Cleared in the finally so a fast evaluation does not keep the
+  // process alive for the rest of timeoutMs.
+  let evalTimer: ReturnType<typeof setTimeout> | undefined;
+  let result: Awaited<typeof evalPromise>;
+  try {
+    result = await (timeoutMs > 0
+      ? Promise.race([
+          evalPromise,
+          new Promise<never>((_, reject) => {
+            evalTimer = setTimeout(
+              () => reject(new Error(`JS evaluation timed out after ${timeoutMs}ms`)),
+              timeoutMs,
+            );
+          }),
+        ])
+      : evalPromise);
+  } finally {
+    clearTimeout(evalTimer);
+  }
 
   if (result.exceptionDetails) {
     throw new Error(

package/src/browser/bridge.ts

@@ -237,13 +237,16 @@ export class BridgeTransport implements CdpTransport {
     const envelope: BridgeEnvelope = { id, type, params };
     if (this.tabId) envelope.tabId = this.tabId;
     return new Promise<BridgeReply>((resolve, reject) => {
+      // Not unref'd (same rule as CdpClient.send): this timer settles a
+      // promise the caller awaits, so it must count toward keeping the event
+      // loop alive — otherwise a dead bridge socket lets Node exit 0 rather
+      // than surfacing the timeout. Cleared on every settle path below.
       let timer: ReturnType<typeof setTimeout> | undefined;
       if (timeoutMs > 0) {
         timer = setTimeout(() => {
           this.pending.delete(id);
           reject(new Error(`bridge ${type} timed out after ${timeoutMs}ms`));
         }, timeoutMs);
-        timer.unref?.();
       }
       this.pending.set(id, (reply) => {
         if (timer) clearTimeout(timer);

package/src/browser/browser.ts

@@ -363,20 +363,30 @@ export async function connectToTarget(
  */
 export async function closeBrowser(client: CdpClient, port: number): Promise<void> {
   let gracefullyClosed = false;
+  let closeTimer: ReturnType<typeof setTimeout> | undefined;
   try {
     await Promise.race([
       client.send('Browser.close', {}),
+      // Deliberately NOT unref'd, for the same reason waitForProcessExit()'s
+      // poll below is not. This timer is the only thing that settles the race
+      // when Chrome's socket dies without ever acknowledging the close, and
+      // closeBrowser() is actively awaited by callers. An unref'd timer does
+      // not hold the event loop open, so Node would consider the loop drained
+      // and exit — status 0, before the caller's verdict was ever printed.
+      // Cleared in the finally so a close that IS acknowledged does not pin
+      // the loop for the rest of BROWSER_CLOSE_TIMEOUT_MS.
       new Promise<never>((_, reject) => {
-        const t = setTimeout(
+        closeTimer = setTimeout(
           () => reject(new Error('Browser.close timed out')),
           BROWSER_CLOSE_TIMEOUT_MS,
         );
-        t.unref?.();
       }),
     ]);
     gracefullyClosed = true;
   } catch {
     // fall through to PID-kill fallback below
+  } finally {
+    clearTimeout(closeTimer);
   }
 
   let pid = launchedPids.get(port);
@@ -501,22 +511,27 @@ export async function reapIdleLaunchedBrowser(): Promise<number | null> {
     if ((await fetchTargets(session.port)).length > 0) return null;
 
     const client = new CdpClient();
+    let reapTimer: ReturnType<typeof setTimeout> | undefined;
     try {
       // CdpClient.connect() has no timeout of its own — a socket that never
       // opens (and never errors) would hang the launch this reap is running
       // inside of, which is strictly worse than leaving the port squatted.
+      // Not unref'd (see closeBrowser): a socket that never opens and never
+      // errors leaves this timer as the only thing that can settle the race,
+      // and the reap is awaited inside launch/attach. Cleared in the finally
+      // below so a connect that succeeds does not pin the event loop.
       await Promise.race([
         client.connect(wsUrl),
         new Promise<never>((_, reject) => {
-          const t = setTimeout(
+          reapTimer = setTimeout(
             () => reject(new Error('Reap: CDP connect timed out')),
             REAP_CONNECT_TIMEOUT_MS,
           );
-          t.unref?.();
         }),
       ]);
       await closeBrowser(client, session.port);
     } finally {
+      clearTimeout(reapTimer);
       try {
         client.close();
       } catch {

package/src/browser/cdp.ts

@@ -125,13 +125,20 @@ export class CdpClient {
       const cmd: CdpCommand = { id, method, params };
       if (sessionId) cmd.sessionId = sessionId;
 
+      // This timer is deliberately NOT unref'd. It is the backstop for the
+      // exact case described at the top of this file — a socket that dies
+      // without ever firing 'close'/'error', so flushPending() never runs.
+      // send()'s promise is awaited by essentially every caller; an unref'd
+      // timer cannot hold the event loop open, so Node would drain and exit
+      // (status 0, no output) instead of rejecting with a timeout the caller
+      // can report. Every settle path below clears it, so a command that gets
+      // its response never keeps the loop alive.
       let timer: ReturnType<typeof setTimeout> | undefined;
       if (timeoutMs > 0) {
         timer = setTimeout(() => {
           this.pendingCommands.delete(id);
           reject(new Error(`CDP command "${method}" timed out after ${timeoutMs}ms`));
         }, timeoutMs);
-        timer.unref?.();
       }
 
       this.pendingCommands.set(id, {

package/src/cli/commands-report.ts

@@ -186,6 +186,34 @@ export const reportCommand: Command = {
       trendWindow: ctx.flags['trend-window'] as number | undefined,
     };
 
+    // Closing the browser is cleanup, not part of the verdict. It used to run
+    // in a `finally` sitting between "we have the result" and "we print it",
+    // which meant anything that wedged the teardown — a Chrome that never
+    // acknowledged `Browser.close`, a CDP socket that died silently — took the
+    // verdict down with it: no output at all, and exit 0 on a page that FAILED
+    // its budgets. That is exactly the signal CI, agents and `&&` chains gate
+    // on, so a hung teardown reported success on a broken page. The verdict is
+    // now printed and the exit code fixed BEFORE any of this runs.
+    const teardown = async (): Promise<void> => {
+      // A report is a one-shot command — CI should not be left with an
+      // orphan Chrome. Only close a browser THIS process launched: an
+      // attached one belongs to the user's own `open`/`connect` session.
+      if (ctx.flags['keep-open'] || browser.getLaunchedPid(session.port) === undefined) return;
+      browser.stopRequestCapture(sessionId);
+      browser.teardownConsoleCapture(sessionId);
+      try {
+        await browser.closeBrowser(client, session.port);
+      } catch {
+        /* best-effort */
+      }
+      session.client = null;
+      session.sessionId = '';
+      session.targetId = '';
+      session.refs = new Map();
+      await browser.clearActivePort();
+      await browser.clearRefCache();
+    };
+
     let result:
       | Awaited<ReturnType<typeof runReport>>
       | Awaited<ReturnType<typeof runReportRepeated>>;
@@ -193,25 +221,11 @@ export const reportCommand: Command = {
       result = repeat
         ? await runReportRepeated(client, sessionId, { ...runOptions, repeat })
         : await runReport(client, sessionId, runOptions);
-    } finally {
-      // A report is a one-shot command — CI should not be left with an
-      // orphan Chrome. Only close a browser THIS process launched: an
-      // attached one belongs to the user's own `open`/`connect` session.
-      if (!ctx.flags['keep-open'] && browser.getLaunchedPid(session.port) !== undefined) {
-        browser.stopRequestCapture(sessionId);
-        browser.teardownConsoleCapture(sessionId);
-        try {
-          await browser.closeBrowser(client, session.port);
-        } catch {
-          /* best-effort */
-        }
-        session.client = null;
-        session.sessionId = '';
-        session.targetId = '';
-        session.refs = new Map();
-        await browser.clearActivePort();
-        await browser.clearRefCache();
-      }
+    } catch (err) {
+      // No verdict to print on this path, so the old ordering still applies:
+      // clean up, then let the error propagate to the CLI's error handler.
+      await teardown();
+      throw err;
     }
 
     const { report, htmlPath, jsonPath, summary, historyDir } = result;
@@ -220,6 +234,15 @@ export const reportCommand: Command = {
     // runs must not exit 0 just because the last run happened to be green.
     const passed = flake ? flake.verdict === 'pass' : report.verdict === 'pass';
 
+    // Set the process-wide failure code up front, before printing and before
+    // teardown. Returning `exitCode` below is the normal channel, but it only
+    // reaches the CLI if this function returns; if teardown never settles,
+    // Node drains the event loop and exits on its own — and a natural exit
+    // uses process.exitCode. Setting it here means a failing page cannot exit
+    // 0 no matter what happens after this line. Only ever set on failure, so
+    // this never clears a non-zero code set elsewhere.
+    if (!passed) process.exitCode = 1;
+
     if (ctx.flags.json) {
       const { toJsonReport } = await import('../report/index.js');
       print(
@@ -265,6 +288,10 @@ export const reportCommand: Command = {
       if (historyDir) print(`History: ${historyDir}`);
     }
 
+    // Verdict is printed and the exit code is fixed — only now is it safe to
+    // close the browser.
+    await teardown();
+
     // Non-zero exit is the point of RIG-06 — CI and agents gate on it.
     return {
       success: passed,

package/src/report/util.ts

@@ -3,10 +3,13 @@
 /** Budget for one non-navigation collector (AX tree, screenshot, eval). */
 export const STEP_TIMEOUT_MS = 15_000;
 
+/** Not unref'd: callers `await sleep(...)` (e.g. the web-vitals settle
+ *  window), so this timer is on an actively-awaited path. An unref'd timer
+ *  does not keep the event loop alive, so once the CDP socket closes Node
+ *  would drain and exit mid-report instead of resuming after the sleep. */
 export function sleep(ms: number): Promise<void> {
   return new Promise((r) => {
-    const t = setTimeout(r, ms);
-    t.unref?.();
+    setTimeout(r, ms);
   });
 }
 
@@ -23,9 +26,12 @@ export async function withTimeout<T>(promise: Promise<T>, ms: number, label: str
   try {
     return await Promise.race([
       promise,
+      // Not unref'd: this timer is the only thing that settles the race when
+      // `promise` is waiting on a socket that quietly went away, and every
+      // caller awaits the result. The finally below clears it, so work that
+      // finishes in time never holds the event loop open.
       new Promise<never>((_, reject) => {
         timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
-        timer.unref?.();
       }),
     ]);
   } finally {