browser-commander 0.30.0 → 0.31.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.31.0
+
+### Minor Changes
+
+- 2f5b1d4: Leave JavaScript launch and commander recording off by default for read-only-safe navigation. Opt in with debug:true, a debug object or BROWSER_COMMANDER_DEBUG=1. Add bounded managed recording directories, retention controls and stopDebug(), with cleanup limited to the session's owned child directory. Document migration from 0.30.x and application-owned signal teardown.
+
+## 0.30.1
+
+### Patch Changes
+
+- aee418c: Upgrade Command Stream to ^2.0.2 to remove the vulnerable ShellJS/braces dependency chain from fresh consumer installations while preserving subprocess and detached browser launch behavior.
+
 ## 0.30.0
 
 ### Minor Changes

package/README.md

@@ -816,12 +816,19 @@ See [capture, debugging and reusable sessions](https://github.com/link-foundatio
 for screenshots, recordings, full/text DOM links, network/HAR, rotation,
 persistent browsers, early trigger readiness and engine capability limits.
 
-JavaScript commanders and browser launches record complete sessions by default
-under `./browser-commander-traces/`, including trusted user actions, DOM changes,
-network metadata and `trace.lino`. Await `commander.ready` before using its raw
-page, and call `commander.destroy()` or the launch's `close()` to finish the files.
-Use `debug: false` or `BROWSER_COMMANDER_DEBUG=0` to opt out; `debug: { output }`
-chooses the directory. `commander.tracePath` exposes its path.
+JavaScript commanders and browser launches leave recording off by default and
+support navigation in a read-only cwd. Request `debug: true`, `debug: { output }`
+or `BROWSER_COMMANDER_DEBUG=1` for complete capture; an output hint alone does not
+enable recording. `debug: false` or `BROWSER_COMMANDER_DEBUG=0` overrides automatic
+capture. Explicit trace APIs remain available.
+
+Use `debug: { directory: '/owned/evidence', retain: false }` for a private unique
+session child with finite data/duration limits and cleanup on teardown. Await
+`commander.ready` before using its raw page; `commander.tracePath` exposes the
+recording path. Await `commander.destroy()` or launch `close()` in `finally`.
+`stopDebug({ discard: true })` removes only a managed child; recordings are
+retained by default. See the guide above for migration from 0.30.x, limits and
+application-owned signal handling.
 
 `startTrace()` records a session into a schema-versioned bundle any of the three
 languages can read - the manifest, an ordered NDJSON timeline, per-checkpoint

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-commander",
-  "version": "0.30.0",
+  "version": "0.31.0",
   "description": "Universal browser automation library that supports Playwright, Puppeteer, and Selenium with a unified API",
   "main": "src/index.js",
   "bin": {
@@ -81,7 +81,7 @@
   },
   "dependencies": {
     "bplist-parser": "^0.5.0",
-    "command-stream": "^1.4.0",
+    "command-stream": "^2.0.2",
     "csv-parse": "^7.0.3",
     "gifenc": "^1.0.3",
     "links-notation": "^0.23.0",

package/scripts/run-tests.mjs

@@ -177,8 +177,8 @@ function runNodeTests(options, testFiles) {
     process.execPath,
     buildNodeTestArgs(options, testFiles),
     {
-      // Most fixtures exercise unrelated APIs with incomplete fake pages. The
-      // default-recording regressions explicitly unset this harness opt-out.
+      // Isolate unrelated fixtures from ambient debug opt-ins. Recording policy
+      // regressions explicitly clear this harness opt-out.
       env: { BROWSER_COMMANDER_DEBUG: '0', ...process.env, ...options.env },
       stdio: 'inherit',
     }

package/src/browser/launcher.js

@@ -8,7 +8,8 @@ import {
 import { assertSupportedEngine } from './connector.js';
 import { emulateMedia } from './media.js';
 import { reserveLoopbackPort } from './debugging-port.js';
-import { attachLaunchDebug } from '../traces/debug-session.js';
+import { attachLaunchDebug, debugEnabled } from '../traces/debug-session.js';
+import { validateDebugConfig } from '../traces/debug-output.js';
 import {
   buildPlaywrightLaunchOptions,
   buildPuppeteerLaunchOptions,
@@ -307,6 +308,7 @@ async function unfocusAddressBar(page, verbose, settleMs = 500) {
  * @param {Object} [options.fingerprint] - Environment fields to present to pages, such as userAgent, timezone, locale, hardwareConcurrency or screen. Applied over CDP after launch; see src/fingerprint/profile.js for the full field list and presets.js for ready-made profiles.
  * @param {boolean} [options.automationParity=true] - Keep navigator.webdriver false where a launch switch would turn it on (headless or engine launches)
  * @param {boolean|Object} [options.downloads] - Manage downloads: true for defaults, or {directory, persist, conflict}. The directory may be an absolute path, 'user-downloads' or 'temporary'.
+ * @param {boolean|Object} [options.debug=false] - Opt-in recording: true, {output}, or {directory, retain, maxDurationMs, limits} for managed storage
  * @returns {Promise<{browser: Object, page: Object, downloads: (Object|null), close: function(): Promise<void>, launch: string, userDataDir: string, temporaryProfile: boolean, args: Array<string>}>} Browser (a BrowserContext for Playwright), page, download manager and launch metadata
  */
 export async function launchBrowser(options = {}) {
@@ -318,6 +320,9 @@ export async function launchBrowserWithDependencies(
   options = {},
   dependencies = {}
 ) {
+  if (debugEnabled(options) && typeof options.debug === 'object') {
+    validateDebugConfig(options.debug);
+  }
   if (options.keepOpen) {
     const { connectOrLaunch } = await import('./persistent-session.js');
     return attachLaunchDebug(

package/src/browser/real-browser.js

@@ -10,6 +10,7 @@ import { launchSafari } from './safari-launch.js';
 import { isSafariChannel } from './safari-support.js';
 
 import { startProcess } from '../utilities/subprocess.js';
+import { withDeadline } from '../traces/deadline.js';
 import {
   applyAutomationParityArgs,
   detectAutomationControlledTriggers,
@@ -308,15 +309,26 @@ function createCloser({
   temporaryProfile,
   closeTimeout,
   closeConnection,
+  verbose,
 }) {
   const originalClose = closeConnection ?? browser?.close;
   let closing;
   const close = () => {
     closing ??= (async () => {
       if (browserProcess.exitCode === null && originalClose) {
-        await requestBrowserClose({ engine, browser, originalClose }).catch(
-          () => {}
-        );
+        // A signal can sever the engine transport while its close RPC is pending.
+        // Keep the existing close budget active until owned-process cleanup runs.
+        await withDeadline(
+          requestBrowserClose({ engine, browser, originalClose }),
+          closeTimeout,
+          'browser close'
+        ).catch((error) => {
+          if (verbose) {
+            console.debug(
+              `[browser-commander] Engine close failed: ${error.message}; finishing owned process cleanup`
+            );
+          }
+        });
       }
       if (!(await waitForExit(browserProcess, closeTimeout))) {
         browserProcess.kill();
@@ -755,6 +767,7 @@ export async function launchAndConnectRealBrowserWithDependencies(
       temporaryProfile,
       closeTimeout,
       closeConnection: engine === 'selenium' ? connection.close : undefined,
+      verbose,
     });
     return await installSessionPersistence(
       {

package/src/core/commander-features.js

@@ -52,6 +52,14 @@ export function attachCommanderFeatures(commander, options, recreate) {
   let debugSession;
   let detachActions;
   commander.tracePath = null;
+  commander.stopDebug = async (stopOptions) => {
+    await commander.ready;
+    try {
+      return (await debugSession?.stop(stopOptions)) ?? null;
+    } finally {
+      detachActions?.();
+    }
+  };
   const ensureDebug = () => commander.ready;
   for (const name of [...INTERACTIONS, 'goto', 'evaluate', 'count']) {
     const method = commander[name];
@@ -71,10 +79,14 @@ export function attachCommanderFeatures(commander, options, recreate) {
   commander.destroy = async () => {
     try {
       await commander.ready;
-      await debugSession?.stop();
-      await Promise.all([...managed].map((item) => item.stop()));
-      detachActions?.();
+      try {
+        await commander.stopDebug();
+      } finally {
+        await Promise.all([...managed].map((item) => item.stop()));
+        detachActions?.();
+      }
     } finally {
+      detachActions?.();
       await destroy();
     }
   };

package/src/factory.js

@@ -33,6 +33,7 @@ import { createCdpSession } from './browser/cdp-session.js';
  * @param {boolean} options.enableNetworkTracking - Enable network request tracking (default: true)
  * @param {boolean} options.enableNavigationManager - Enable navigation manager (default: true)
  * @param {Object} [options.downloads] - A download manager to expose as commander.downloads, such as the one launchBrowser() returned
+ * @param {boolean|Object} [options.debug=false] - Opt-in recording: true, {output}, or {directory, retain, maxDurationMs, limits} for managed storage
  * @returns {Object} - Browser commander API
  */
 export function makeBrowserCommander(options = {}) {

package/src/traces/commander-actions.js

@@ -141,6 +141,10 @@ export function observeCommanderActions({
         commander[name] = original;
       }
     }
-    commanders.delete(commander);
+    // A repeated teardown may belong to an older, already stopped recording.
+    // Preserve observers installed by a newer explicit trace on this commander.
+    if (commanders.get(commander) === state) {
+      commanders.delete(commander);
+    }
   };
 }

package/src/traces/debug-output.js

@@ -0,0 +1,81 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { openTraceBundle } from './bundle.js';
+
+/** Managed debug sessions own only a fresh child of the caller's storage root. */
+export function validateDebugConfig(config = {}) {
+  if (config.retain !== undefined && typeof config.retain !== 'boolean') {
+    throw new TypeError('debug retain must be a boolean');
+  }
+  if (config.retain === false && config.directory === undefined) {
+    throw new TypeError('debug retain:false requires a managed directory');
+  }
+  if (config.directory === undefined) {
+    return;
+  }
+  if (typeof config.directory !== 'string' || config.directory === '') {
+    throw new TypeError('debug managed directory must be a path');
+  }
+  if (config.output !== undefined || config.limits?.rotate) {
+    throw new TypeError(
+      'debug managed directory cannot use output or rotation'
+    );
+  }
+  if (config.links && config.links !== false) {
+    throw new TypeError('debug managed directory uses links:false');
+  }
+  if (typeof config.network?.har === 'string') {
+    throw new TypeError('debug managed HAR must stay inside its directory');
+  }
+  for (const [name, value] of Object.entries({
+    maxBundleBytes: config.limits?.maxBundleBytes ?? 8 * 1024 * 1024,
+    maxResourceBytes: config.limits?.maxResourceBytes ?? 1024 * 1024,
+    maxDurationMs: config.maxDurationMs ?? 60000,
+  })) {
+    if (!Number.isSafeInteger(value) || value <= 0 || value > 2147483647) {
+      throw new RangeError(
+        `debug managed ${name} must be a finite positive integer`
+      );
+    }
+  }
+}
+
+export async function prepareDebugOutput(options, config) {
+  if (config.directory !== undefined) {
+    const directory = path.resolve(config.directory);
+    await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+    const output = await fs.mkdtemp(path.join(directory, 'session-'));
+    // No unbounded side export or rotation bypasses the managed bundle budget.
+    return {
+      output,
+      owned: true,
+      maxDurationMs: config.maxDurationMs ?? 60000,
+      traceOptions: {
+        ...config,
+        // Continuous traces otherwise rotate automatically when the budget fills.
+        openBundle: openTraceBundle,
+        links: false,
+        network: config.network ?? { har: false },
+        limits: {
+          ...config.limits,
+          maxBundleBytes: config.limits?.maxBundleBytes ?? 8 * 1024 * 1024,
+          maxResourceBytes: config.limits?.maxResourceBytes ?? 1024 * 1024,
+        },
+      },
+    };
+  }
+  return {
+    output: path.resolve(
+      config.output ??
+        options.output ??
+        process.env.BROWSER_COMMANDER_TRACE ??
+        path.join(
+          'browser-commander-traces',
+          `${new Date().toISOString().replaceAll(':', '-')}-${process.pid}-${randomUUID().slice(0, 8)}`
+        )
+    ),
+    owned: false,
+    traceOptions: config,
+  };
+}

package/src/traces/debug-session.js

@@ -1,15 +1,23 @@
-import path from 'node:path';
-import { randomUUID } from 'node:crypto';
+import fs from 'node:fs/promises';
 import { startTrace } from './recorder.js';
+import { prepareDebugOutput, validateDebugConfig } from './debug-output.js';
 
 const sessions = new WeakMap();
 const disabledPages = new WeakSet();
 
 export function debugEnabled(options = {}) {
+  if (options.debug === false || process.env.BROWSER_COMMANDER_DEBUG === '0') {
+    return false;
+  }
+  if (options.debug === undefined && disabledPages.has(options.page)) {
+    return false;
+  }
   return (
-    options.debug !== false &&
-    process.env.BROWSER_COMMANDER_DEBUG !== '0' &&
-    !(options.debug === undefined && disabledPages.has(options.page))
+    options.debug === true ||
+    (options.debug !== null && typeof options.debug === 'object') ||
+    (options.debug === undefined &&
+      (sessions.has(options.page) ||
+        process.env.BROWSER_COMMANDER_DEBUG === '1'))
   );
 }
 
@@ -18,7 +26,9 @@ export async function ensureDebugSession(options) {
   const { page, commander } = options;
   const existing = sessions.get(page);
   if (!debugEnabled(options)) {
-    disabledPages.add(page);
+    if (options.debug === false) {
+      disabledPages.add(page);
+    }
     await existing?.stop();
     return null;
   }
@@ -27,50 +37,78 @@ export async function ensureDebugSession(options) {
   if (!session) {
     const config =
       options.debug && typeof options.debug === 'object' ? options.debug : {};
-    const output = path.resolve(
-      config.output ??
-        options.output ??
-        process.env.BROWSER_COMMANDER_TRACE ??
-        path.join(
-          'browser-commander-traces',
-          `${new Date().toISOString().replaceAll(':', '-')}-${process.pid}-${randomUUID().slice(0, 8)}`
-        )
-    );
-    session = { path: output };
+    validateDebugConfig(config);
+    session = { path: null, owned: false };
     sessions.set(page, session);
-    session.ready = startTrace({
-      ...config,
-      output,
-      page,
-      commander: commander ?? {
-        page,
-        engine: options.engine,
-        downloads: options.downloads,
-      },
-      checkpointOnNavigation: config.checkpointOnNavigation ?? true,
-    })
-      .then((trace) => {
-        console.error(`[browser-commander] Recording session to ${output}`);
+    let timer;
+    session.ready = prepareDebugOutput(options, config)
+      .then(async (prepared) => {
+        session.path = prepared.output;
+        session.owned = prepared.owned;
+        const trace = await startTrace({
+          ...prepared.traceOptions,
+          output: prepared.output,
+          page,
+          commander: commander ?? {
+            page,
+            engine: options.engine,
+            downloads: options.downloads,
+          },
+          checkpointOnNavigation: config.checkpointOnNavigation ?? true,
+        });
+        console.error(
+          `[browser-commander] Recording session to ${session.path}`
+        );
+        if (prepared.maxDurationMs) {
+          timer = setTimeout(() => {
+            session
+              .stop()
+              .catch((error) =>
+                console.warn(
+                  `[browser-commander] Could not finish recording: ${error.message}`
+                )
+              );
+          }, prepared.maxDurationMs);
+          timer.unref?.();
+        }
         return trace;
       })
-      .catch((error) => {
+      .catch(async (error) => {
         sessions.delete(page);
+        if (session.owned) {
+          await fs.rm(session.path, { recursive: true, force: true });
+        }
         console.warn(
           `[browser-commander] Could not start recording: ${error.message}`
         );
         return null;
       });
     let stopping;
-    session.stop = () =>
-      (stopping ??= session.ready.then(async (trace) => {
+    session.stop = (stopOptions = {}) => {
+      const discard = stopOptions.discard ?? config.retain === false;
+      if (discard && !session.owned && session.path) {
+        return Promise.reject(
+          new Error('Only a managed debug directory can be discarded')
+        );
+      }
+      return (stopping ??= session.ready.then(async (trace) => {
+        if (discard && trace && !session.owned) {
+          throw new Error('Only a managed debug directory can be discarded');
+        }
+        clearTimeout(timer);
+        disabledPages.add(page);
         try {
-          return await trace?.stop();
+          return await trace?.stop({ ...stopOptions, discard });
         } finally {
           if (sessions.get(page) === session) {
             sessions.delete(page);
           }
+          if (discard && session.owned) {
+            await fs.rm(session.path, { recursive: true, force: true });
+          }
         }
       }));
+    };
   }
   const trace = await session.ready;
   if (!trace) {
@@ -93,6 +131,8 @@ export async function attachLaunchDebug(result, options) {
     downloads: result.downloads,
   });
   result.tracePath = session?.path ?? null;
+  result.stopDebug = (options) =>
+    session?.stop(options) ?? Promise.resolve(null);
   if (!session) {
     return result;
   }

package/src/utilities/subprocess.js

@@ -9,7 +9,7 @@ export async function startDetachedProcess(file, args = [], options = {}) {
     runner.child.once('error', reject);
   });
   const child = runner.child;
-  // command-stream 1.x starts noninteractive children in their own process
+  // command-stream starts noninteractive children in their own process
   // group. Release its controller-owned cancellation registry while retaining
   // the child's exit listeners. Keep this adapter isolated until it exposes a
   // public detach operation; normal subprocesses retain managed cancellation.

package/tests/e2e/capture.e2e.test.js

@@ -0,0 +1,96 @@
+/** Real launch and capture contracts for the Command Stream upgrade (#164). */
+import { it } from 'node:test';
+import assert from 'node:assert/strict';
+import UPNG from 'upng-js';
+import {
+  screenshot,
+  startRecording,
+  encodeAnimation,
+  encodeVideo,
+  launchBrowser,
+} from '../../src/index.js';
+import { CHROME_LAUNCH_OPTIONS } from '../helpers/e2e-browser.js';
+
+for (const engine of ['playwright', 'puppeteer', 'selenium']) {
+  it(
+    `${engine}: screenshots and bounded animation/video capture after a real launch`,
+    { skip: !process.env.RUN_E2E, timeout: 60000 },
+    async () => {
+      const session = await launchBrowser({
+        engine,
+        headless: process.env.HEADLESS !== 'false',
+        ...CHROME_LAUNCH_OPTIONS,
+        ...(engine === 'selenium' ? { bidi: true } : {}),
+      });
+      let recording;
+      try {
+        const { page } = session;
+        await page.goto(
+          'data:text/html,<input id="focus"><div style="height:2000px;background:teal">Capture fixture</div>'
+        );
+        const state = () =>
+          page.evaluate(() => ({
+            scroll: window.scrollY,
+            active: document.activeElement.id,
+          }));
+        await page.evaluate(() => {
+          document.querySelector('input').focus();
+          window.scrollTo(0, 200);
+        });
+        const before = await state();
+        const png = await screenshot({ page, engine, stableViewport: true });
+        assert.equal(png.subarray(1, 4).toString(), 'PNG');
+        assert.deepEqual(await state(), before);
+        const jpeg = await screenshot({ page, engine, format: 'jpeg' });
+        assert.equal(jpeg.readUInt16BE(0), 0xffd8);
+        const webp = await screenshot({ page, engine, format: 'webp' });
+        assert.equal(webp.subarray(8, 12).toString(), 'WEBP');
+
+        recording = await startRecording({
+          page,
+          engine,
+          format: 'frames',
+          fps: 2,
+          maxFrames: 2,
+          maxBytes: 1024 * 1024,
+          maxDurationMs: 3000,
+          size: { width: 120, height: 100 },
+        });
+        await page.evaluate(() => {
+          document.querySelector('div').style.background = 'red';
+        });
+        const deadline = Date.now() + 3000;
+        while (recording.frames.length < 2 && Date.now() < deadline) {
+          await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+        const { frames } = await recording.stop();
+        assert.equal(frames.length, 2);
+        const gif = await encodeAnimation(frames, { format: 'gif', fps: 2 });
+        assert.equal(gif.subarray(0, 6).toString(), 'GIF89a');
+        const apng = await encodeAnimation(frames, { format: 'apng', fps: 2 });
+        assert.equal(UPNG.decode(apng).frames.length, 2);
+        const animatedWebp = await encodeAnimation(frames, {
+          format: 'webp',
+          fps: 2,
+        });
+        assert.equal(
+          animatedWebp.toString('latin1').split('ANMF').length - 1,
+          2
+        );
+        const video = await encodeVideo(frames, {
+          page,
+          engine,
+          format: 'webm',
+          fps: 2,
+        });
+        assert.equal(video.readUInt32BE(0), 0x1a45dfa3);
+      } finally {
+        try {
+          await recording?.stop();
+        } finally {
+          await session.close();
+        }
+      }
+    }
+  );
+}

package/tests/e2e/issue-166-policy.e2e.test.js

@@ -0,0 +1,169 @@
+import { clearDebugEnvironment } from '../helpers/debug-environment.js';
+import { it } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+import { fileURLToPath } from 'node:url';
+import { launchBrowser } from '../../src/browser/launcher.js';
+import { makeBrowserCommander } from '../../src/factory.js';
+import { readTrace } from '../../src/traces/reader.js';
+import { CHROME_LAUNCH_OPTIONS } from '../helpers/e2e-browser.js';
+
+function navigate(commander, url, timeout = 5000) {
+  return commander.goto({
+    url,
+    timeout,
+    waitForStableUrlBefore: false,
+    waitForStableUrlAfter: false,
+    waitForNetworkIdle: false,
+  });
+}
+
+async function fixture(run) {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bc-readonly-'));
+  const cwd = process.cwd();
+  const restoreEnvironment = clearDebugEnvironment();
+  const readonly = path.join(root, 'checkout');
+  const evidence = path.join(root, 'evidence');
+  await fs.mkdir(readonly);
+  await fs.mkdir(evidence);
+  await fs.writeFile(path.join(evidence, 'keep.txt'), 'caller evidence');
+  await fs.chmod(readonly, 0o555);
+  process.chdir(readonly);
+  try {
+    if (process.platform !== 'win32') {
+      await assert.rejects(fs.access(readonly, fs.constants.W_OK));
+    }
+    await run({ readonly, evidence });
+    assert.deepEqual(await fs.readdir(readonly), []);
+  } finally {
+    process.chdir(cwd);
+    restoreEnvironment();
+    await fs.chmod(readonly, 0o700);
+    await fs.rm(root, { recursive: true, force: true });
+  }
+}
+
+for (const engine of ['playwright', 'puppeteer']) {
+  it(
+    `navigates in read-only cwd and cleans managed recording with ${engine}`,
+    {
+      skip: process.env.RUN_E2E !== 'true',
+      timeout: 90000,
+    },
+    async () => {
+      await fixture(async ({ evidence }) => {
+        let launched, commander;
+        const managedCommander = () =>
+          makeBrowserCommander({
+            page: launched.page,
+            debug: { directory: evidence, retain: false },
+          });
+        try {
+          launched = await launchBrowser({
+            engine,
+            headless: true,
+            ...CHROME_LAUNCH_OPTIONS,
+          });
+          commander = makeBrowserCommander({ page: launched.page });
+          await navigate(
+            commander,
+            'data:text/html,<h1>No recording requested</h1>'
+          );
+          assert.equal(launched.tracePath, null);
+          assert.equal(commander.tracePath, null);
+          await commander.destroy();
+          commander = managedCommander();
+          await navigate(commander, 'data:text/html,<h1>Owned recording</h1>');
+          assert.equal(path.dirname(commander.tracePath), evidence);
+          await commander.stopDebug({ discard: false });
+          const trace = await readTrace(commander.tracePath);
+          assert.equal(trace.manifest.outcome, 'complete');
+          assert.ok(trace.events.some((event) => event.source === 'commander'));
+          // First stop determines retention; retained output is now caller-owned.
+          await fs.rm(commander.tracePath, { recursive: true });
+          await commander.destroy();
+          commander = managedCommander();
+          await commander.ready;
+          await assert.rejects(
+            navigate(commander, 'http://127.0.0.1:1/'),
+            /ERR_UNSAFE_PORT/
+          );
+        } finally {
+          try {
+            await commander?.destroy();
+          } finally {
+            await launched?.close();
+          }
+        }
+        assert.deepEqual(await fs.readdir(evidence), ['keep.txt']);
+      });
+    }
+  );
+}
+
+for (const signal of ['SIGINT', 'SIGTERM']) {
+  it(
+    `application signal handler cleans managed recording on ${signal}`,
+    {
+      skip: process.env.RUN_E2E !== 'true' || process.platform === 'win32',
+      timeout: 90000,
+    },
+    async () => {
+      await fixture(async ({ readonly, evidence }) => {
+        const script = fileURLToPath(
+          new URL(
+            '../../../examples/managed-debug-session.mjs',
+            import.meta.url
+          )
+        );
+        const child = spawn(
+          process.execPath,
+          [script, evidence, '--wait-for-signal'],
+          {
+            cwd: readonly,
+            env: process.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+          }
+        );
+        const exited = once(child, 'exit');
+        let output = '',
+          errors = '';
+        child.stderr.on('data', (data) => {
+          errors += data;
+        });
+        try {
+          await new Promise((resolve, reject) => {
+            child.stdout.on('data', (data) => {
+              output += data;
+              if (output.includes('"ready":true')) {
+                resolve();
+              }
+            });
+            child.once('error', reject);
+            child.once('exit', (code) =>
+              reject(new Error(`Child exited ${code}: ${errors}`))
+            );
+          });
+          const { tracePath } = JSON.parse(
+            output.split('\n').find((line) => line.includes('"ready":true'))
+          );
+          assert.equal(path.dirname(tracePath), evidence);
+          child.kill(signal);
+          const [code, killed] = await exited;
+          assert.equal(code, 0, errors);
+          assert.equal(killed, null);
+          assert.deepEqual(await fs.readdir(evidence), ['keep.txt']);
+        } finally {
+          if (child.exitCode === null && child.signalCode === null) {
+            child.kill('SIGTERM');
+            await exited;
+          }
+        }
+      });
+    }
+  );
+}

package/tests/helpers/debug-environment.js

@@ -0,0 +1,17 @@
+/** Isolate explicit debug policy tests from the runner's environment opt-out. */
+export function clearDebugEnvironment() {
+  const names = ['BROWSER_COMMANDER_DEBUG', 'BROWSER_COMMANDER_TRACE'];
+  const previous = names.map((name) => process.env[name]);
+  names.forEach((name) => {
+    delete process.env[name];
+  });
+  return () => {
+    names.forEach((name, index) => {
+      if (previous[index] === undefined) {
+        delete process.env[name];
+      } else {
+        process.env[name] = previous[index];
+      }
+    });
+  };
+}

package/tests/unit/browser/real-browser.test.js

@@ -460,6 +460,35 @@ describe('launchAndConnectRealBrowser', () => {
     await assert.rejects(() => access(result.userDataDir), /ENOENT/);
   });
 
+  it(
+    'finishes owned cleanup when the engine close stalls after interruption',
+    { timeout: 1000 },
+    async () => {
+      const calls = [];
+      const browserProcess = fakeProcess(calls);
+      const result = await launchAndConnectRealBrowserWithDependencies(
+        { engine: 'puppeteer', closeTimeout: 20 },
+        {
+          resolveExecutable: async () => '/opt/google/chrome',
+          reservePort: async () => 40005,
+          spawnBrowser: () => browserProcess,
+          waitForEndpoint: async () => 'http://127.0.0.1:40005',
+          connect: async () => ({
+            browser: { close: () => new Promise(() => {}) },
+            page: null,
+          }),
+        }
+      );
+      temporaryDirectory = result.userDataDir;
+      await result.close();
+      assert.deepEqual(
+        { calls, exitCode: browserProcess.exitCode },
+        { calls: [['kill']], exitCode: 143 }
+      );
+      await assert.rejects(() => access(result.userDataDir), /ENOENT/);
+    }
+  );
+
   it('passes restriction environment to the browser only', async () => {
     const before = process.env.GOOGLE_API_KEY;
     let spawnOptions;

package/tests/unit/traces/issue-162-defaults.test.js

@@ -1,3 +1,4 @@
+import { clearDebugEnvironment } from '../../helpers/debug-environment.js';
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
 import fs from 'node:fs/promises';
@@ -19,23 +20,12 @@ describe('complete recording defaults (issue #162)', { timeout: 15000 }, () => {
     const output = await fs.mkdtemp(path.join(os.tmpdir(), 'bc-defaults-'));
     const page = createFakePage();
     const commander = createFakeCommander(page, { destroy: async () => {} });
-    const previous = { ...process.env };
-    delete process.env.BROWSER_COMMANDER_DEBUG;
-    delete process.env.BROWSER_COMMANDER_TRACE;
+    const restoreEnvironment = clearDebugEnvironment();
     try {
       await run({ output, page, commander });
     } finally {
       await commander.destroy();
-      for (const key of [
-        'BROWSER_COMMANDER_DEBUG',
-        'BROWSER_COMMANDER_TRACE',
-      ]) {
-        if (previous[key] === undefined) {
-          delete process.env[key];
-        } else {
-          process.env[key] = previous[key];
-        }
-      }
+      restoreEnvironment();
       await fs.rm(output, { recursive: true, force: true });
     }
   }
@@ -112,7 +102,7 @@ describe('complete recording defaults (issue #162)', { timeout: 15000 }, () => {
     });
   });
 
-  it('records the very first call with no options and chooses a unique session directory', async () => {
+  it('records the very first call with debug:true and chooses a unique session directory', async () => {
     await fixture(async ({ output, page }) => {
       const cwd = process.cwd();
       process.chdir(output);
@@ -123,6 +113,7 @@ describe('complete recording defaults (issue #162)', { timeout: 15000 }, () => {
       try {
         commander = makeBrowserCommander({
           page,
+          debug: true,
           enableNetworkTracking: false,
           enableNavigationManager: false,
           enableDialogManager: false,

package/tests/unit/traces/issue-166-policy.test.js

@@ -0,0 +1,333 @@
+import { clearDebugEnvironment } from '../../helpers/debug-environment.js';
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { attachCommanderFeatures } from '../../../src/core/commander-features.js';
+import { attachLaunchDebug } from '../../../src/traces/debug-session.js';
+import { readTrace } from '../../../src/traces/reader.js';
+import { launchBrowserWithDependencies } from '../../../src/browser/launcher.js';
+import {
+  createFakePage,
+  createFakeCommander,
+} from '../../helpers/trace-fixtures.js';
+
+describe('opt-in recording policy (issue #166)', { timeout: 15000 }, () => {
+  async function fixture(run) {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'bc-policy-'));
+    const page = createFakePage();
+    const commander = createFakeCommander(page, { destroy: async () => {} });
+    const restoreEnvironment = clearDebugEnvironment();
+    const cwd = process.cwd();
+    process.chdir(root);
+    try {
+      const configureDebug = async (debug) => {
+        attachCommanderFeatures(commander, { debug }, () => {});
+        await commander.ready;
+      };
+      await run({ root, page, commander, configureDebug });
+    } finally {
+      await commander.destroy();
+      process.chdir(cwd);
+      restoreEnvironment();
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  }
+
+  for (const outputHint of ['none', 'option', 'environment']) {
+    it(`navigates without recording or writes with ${outputHint} output hints`, async () => {
+      await fixture(async ({ root, page, commander }) => {
+        const output = path.join(root, 'unrequested');
+        if (outputHint === 'environment') {
+          process.env.BROWSER_COMMANDER_TRACE = output;
+        }
+        attachCommanderFeatures(
+          commander,
+          outputHint === 'option' ? { output } : {},
+          () => {}
+        );
+        await commander.goto('https://example.com');
+        assert.equal(commander.tracePath, null);
+        assert.equal(page.listenerCount('request'), 0);
+        assert.deepEqual(page.state.initScripts, []);
+        assert.deepEqual(await fs.readdir(root), []);
+      });
+    });
+  }
+
+  it('enables recording through BROWSER_COMMANDER_DEBUG=1', async () => {
+    await fixture(async ({ root, commander }) => {
+      process.env.BROWSER_COMMANDER_DEBUG = '1';
+      process.env.BROWSER_COMMANDER_TRACE = path.join(root, 'requested');
+      attachCommanderFeatures(commander, {}, () => {});
+      await commander.ready;
+      assert.equal(commander.tracePath, process.env.BROWSER_COMMANDER_TRACE);
+    });
+  });
+
+  it('leaves default launches unrecorded', async () => {
+    await fixture(async ({ root, page }) => {
+      const launched = await attachLaunchDebug({ page }, {});
+      assert.equal(launched.tracePath, null);
+      assert.deepEqual(await fs.readdir(root), []);
+    });
+  });
+
+  it('owns a unique managed child, shares it with launch, and discards only that child', async () => {
+    await fixture(async ({ root, page, commander }) => {
+      const directory = path.join(root, 'evidence');
+      await fs.mkdir(directory);
+      await fs.writeFile(path.join(directory, 'keep.txt'), 'caller owned');
+      let closed = 0;
+      const launched = await attachLaunchDebug(
+        {
+          page,
+          close: async () => {
+            closed += 1;
+          },
+        },
+        { debug: { directory, retain: false } }
+      );
+      attachCommanderFeatures(commander, {}, () => {});
+      await commander.ready;
+      assert.equal(commander.tracePath, launched.tracePath);
+      assert.equal(path.dirname(commander.tracePath), directory);
+      await commander.goto('https://example.com');
+      await commander.destroy();
+      await launched.close();
+      assert.equal(closed, 1);
+      assert.deepEqual(await fs.readdir(directory), ['keep.txt']);
+      assert.deepEqual(await fs.readdir(root), ['evidence']);
+    });
+  });
+
+  it('retains managed recordings unless discarded, with idempotent explicit stop', async () => {
+    await fixture(async ({ root, commander, configureDebug }) => {
+      await configureDebug({ directory: root });
+      const stopped = await commander.stopDebug();
+      assert.equal(stopped, await commander.stopDebug());
+      assert.equal(
+        (await readTrace(commander.tracePath)).manifest.outcome,
+        'complete'
+      );
+    });
+  });
+
+  it('allows explicit discard of a managed child', async () => {
+    await fixture(async ({ root, commander, configureDebug }) => {
+      await configureDebug({ directory: root });
+      const stopped = await commander.stopDebug({ discard: true });
+      assert.equal(stopped.discarded, true);
+      assert.deepEqual(await fs.readdir(root), []);
+    });
+  });
+
+  it('leaves later explicit traces intact when debug teardown repeats', async () => {
+    await fixture(async ({ root, page, commander, configureDebug }) => {
+      await configureDebug({ directory: root, retain: false });
+      await commander.stopDebug();
+      const first = await commander.startTrace({
+        output: path.join(root, 'first-explicit'),
+      });
+      await commander.stopDebug();
+      const second = await commander.startTrace({
+        output: path.join(root, 'second-explicit'),
+      });
+      await first.stop();
+      await second.stop();
+      let captures = 0;
+      page.evaluate = async () => {
+        captures += 1;
+      };
+      await commander.click('#after-teardown');
+      assert.equal(captures, 0, 'stopped traces must leave no input labels');
+    });
+  });
+
+  it('refuses to discard a caller-supplied output directory', async () => {
+    await fixture(async ({ root, commander }) => {
+      attachCommanderFeatures(commander, { debug: { output: root } }, () => {});
+      await commander.ready;
+      await assert.rejects(commander.stopDebug({ discard: true }), /managed/);
+      await commander.stopDebug();
+      assert.equal((await readTrace(root)).manifest.outcome, 'complete');
+    });
+  });
+
+  it('removes its managed child when recorder startup fails', async () => {
+    await fixture(async ({ root, page, commander }) => {
+      page.failEvaluate('captureSnapshotInPage', new Error('capture failed'));
+      attachCommanderFeatures(
+        commander,
+        { debug: { directory: root, strict: true } },
+        () => {}
+      );
+      await commander.ready;
+      assert.equal(commander.tracePath, null);
+      assert.equal(page.listenerCount('request'), 0);
+      assert.deepEqual(await fs.readdir(root), []);
+    });
+  });
+
+  it('cleans managed recording in finally after failed navigation', async () => {
+    await fixture(async ({ root, commander }) => {
+      commander.goto = async () => {
+        throw new Error('navigation failed');
+      };
+      attachCommanderFeatures(
+        commander,
+        { debug: { directory: root, retain: false } },
+        () => {}
+      );
+      try {
+        await assert.rejects(
+          commander.goto('https://example.com'),
+          /navigation failed/
+        );
+      } finally {
+        await commander.destroy();
+      }
+      assert.deepEqual(await fs.readdir(root), []);
+    });
+  });
+
+  it('stops managed recording automatically at its duration limit', async () => {
+    await fixture(async ({ root, commander }) => {
+      attachCommanderFeatures(
+        commander,
+        {
+          debug: {
+            directory: root,
+            retain: false,
+            maxDurationMs: 20,
+          },
+        },
+        () => {}
+      );
+      await commander.ready;
+      // Poll actual teardown, bounded by the suite timeout, rather than a fixed sleep.
+      while ((await fs.readdir(root)).length) {
+        await new Promise((resolve) => setTimeout(resolve, 10));
+      }
+      assert.equal((await commander.stopDebug()).discarded, true);
+    });
+  });
+
+  it('enforces the managed data budget and preserves partial outcome', async () => {
+    await fixture(async ({ root, page, commander }) => {
+      attachCommanderFeatures(
+        commander,
+        {
+          debug: {
+            directory: root,
+            limits: { maxBundleBytes: 1024, maxResourceBytes: 512 },
+          },
+        },
+        () => {}
+      );
+      await commander.ready;
+      for (let index = 0; index < 20; index += 1) {
+        page.emit('pageerror', new Error('bounded error '.repeat(20)));
+      }
+      const result = await commander.stopDebug();
+      const trace = await readTrace(result.path);
+      assert.equal(trace.manifest.outcome, 'partial');
+      const events = await fs.stat(path.join(result.path, 'events.ndjson'));
+      assert.ok(events.size <= 1024);
+      assert.equal(trace.manifest.limits.maxBundleBytes, 1024);
+      await assert.rejects(fs.access(path.join(result.path, 'trace.lino')));
+    });
+  });
+
+  it('does not create recording storage when browser launch fails', async () => {
+    await fixture(async ({ root }) => {
+      await assert.rejects(
+        launchBrowserWithDependencies(
+          { debug: { directory: root } },
+          {
+            resolveSystem: async () => '/usr/bin/google-chrome',
+            launchRealBrowser: async () => {
+              throw new Error('launch failed');
+            },
+          }
+        ),
+        /launch failed/
+      );
+      assert.deepEqual(await fs.readdir(root), []);
+    });
+  });
+
+  it('discards its child and closes the browser even when finalization fails', async () => {
+    await fixture(async ({ root, page }) => {
+      let closed = false;
+      const launched = await attachLaunchDebug(
+        {
+          page,
+          close: async () => {
+            closed = true;
+          },
+        },
+        {
+          debug: { directory: root, retain: false },
+        }
+      );
+      await fs.mkdir(path.join(launched.tracePath, 'manifest.json'));
+      await assert.rejects(launched.close(), /EISDIR|EPERM|EACCES/);
+      assert.equal(closed, true);
+      assert.deepEqual(await fs.readdir(root), []);
+    });
+  });
+
+  it('validates managed launch configuration before starting the browser', async () => {
+    await fixture(async ({ root }) => {
+      let started = false;
+      await assert.rejects(
+        launchBrowserWithDependencies(
+          {
+            debug: { directory: root, retain: false, maxDurationMs: Infinity },
+          },
+          {
+            launchRealBrowser: async () => {
+              started = true;
+            },
+          }
+        ),
+        /debug managed/
+      );
+      assert.equal(started, false);
+      assert.deepEqual(await fs.readdir(root), []);
+    });
+  });
+
+  for (const debug of [false, true, { directory: '.' }]) {
+    it(`environment opt-out prevents recording with debug=${JSON.stringify(debug)}`, async () => {
+      await fixture(async ({ root, commander }) => {
+        process.env.BROWSER_COMMANDER_DEBUG = '0';
+        attachCommanderFeatures(commander, { debug }, () => {});
+        await commander.ready;
+        assert.equal(commander.tracePath, null);
+        assert.deepEqual(await fs.readdir(root), []);
+      });
+    });
+  }
+
+  for (const debug of [
+    { retain: false },
+    { directory: '.', output: 'other' },
+    { directory: '.', limits: { maxBundleBytes: Infinity } },
+    { directory: '.', limits: { rotate: { maxBytes: 1024 } } },
+    { directory: '.', links: { output: '../outside.lino' } },
+    { directory: '.', network: { har: '../outside.har' } },
+    { directory: '.', maxDurationMs: Infinity },
+  ]) {
+    it(`rejects unsafe managed settings before writing: ${JSON.stringify(debug)}`, async () => {
+      await fixture(async ({ root, commander }) => {
+        attachCommanderFeatures(commander, { debug }, () => {});
+        await assert.rejects(commander.ready, /debug|managed/);
+        commander.ready = Promise.resolve();
+        assert.deepEqual(await fs.readdir(root), []);
+      });
+    });
+  }
+});

package/tests/unit/utilities/subprocess.test.js

@@ -1,14 +1,18 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert';
+import * as fs from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
 import {
   CommandError,
   runCommand,
   startProcess,
 } from '../../../src/utilities/subprocess.js';
+import { repoPath } from '../../helpers/repo.js';
 
 const node = process.execPath;
 
-describe('runCommand', () => {
+describe('runCommand', { timeout: 10000 }, () => {
   it('passes arguments without a shell and captures output', async () => {
     const result = await runCommand(node, [
       '-e',
@@ -46,9 +50,25 @@ describe('runCommand', () => {
     const result = await runCommand(node, args, { check: false });
     assert.equal(result.code, 3);
   });
+
+  it('reports a missing executable as exit 127 with ENOENT diagnostics', async () => {
+    const file = path.join(tmpdir(), 'bc-missing-executable-164', 'missing');
+    await assert.rejects(
+      () => runCommand(file),
+      (error) => {
+        assert.ok(error instanceof CommandError);
+        assert.equal(error.code, 127);
+        assert.match(error.stderr, /ENOENT/);
+        return true;
+      }
+    );
+    const result = await runCommand(file, [], { check: false });
+    assert.equal(result.code, 127);
+    assert.match(result.stderr, /ENOENT/);
+  });
 });
 
-describe('startProcess', () => {
+describe('startProcess', { timeout: 10000 }, () => {
   it('streams output and reports the exit code', async () => {
     const child = startProcess(node, [
       '-e',
@@ -78,3 +98,61 @@ describe('startProcess', () => {
     assert.notEqual(exitCode, 0);
   });
 });
+
+describe(
+  'startDetachedProcess',
+  {
+    timeout: 10000,
+    // Both the original 1.4.0 and 2.0.2 runner disable Windows detachment.
+    skip:
+      process.platform === 'win32' &&
+      'Command Stream only creates detached process groups on Unix',
+  },
+  () => {
+    it('lets the launcher exit while the detached child survives', async (t) => {
+      const directory = await fs.mkdtemp(
+        path.join(tmpdir(), 'bc-detached-164-')
+      );
+      const marker = path.join(directory, 'survived');
+      let pid;
+      const launcher = startProcess(node, [
+        repoPath('experiments', 'issue-164', 'detached-launcher.mjs'),
+        marker,
+      ]);
+      t.after(async () => {
+        launcher.kill();
+        if (pid) {
+          try {
+            process.kill(pid, 'SIGKILL');
+          } catch (error) {
+            if (error.code !== 'ESRCH') {
+              throw error;
+            }
+          }
+        }
+        await fs.rm(directory, { recursive: true, force: true });
+      });
+      let output = '';
+      launcher.stdout.on('data', (chunk) => {
+        output += chunk;
+        pid = Number(output.trim());
+      });
+      assert.equal(await launcher.exited, 0, launcher.stderrTail);
+      assert.ok(pid > 0);
+      await assert.rejects(fs.readFile(marker), { code: 'ENOENT' });
+      const deadline = Date.now() + 5000;
+      while (Date.now() < deadline) {
+        try {
+          assert.equal(await fs.readFile(marker, 'utf8'), 'survived');
+          return;
+        } catch (error) {
+          if (error.code !== 'ENOENT') {
+            throw error;
+          }
+          await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+      }
+      assert.fail('detached child did not survive the launcher exit');
+    });
+  }
+);