browser-commander 0.30.1 → 0.31.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.31.1
+
+### Patch Changes
+
+- c8f52e3: Upgrade Links Notation to ^0.25.2 so consumers using 0.25.2 can share one copy without an override. Preserve trace text containing lone UTF-16 surrogates, verify export/import and streaming compatibility, and document the new empty/control-value literals for consumers upgrading older parsers.
+
+## 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

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.1",
+  "version": "0.31.1",
   "description": "Universal browser automation library that supports Playwright, Puppeteer, and Selenium with a unified API",
   "main": "src/index.js",
   "bin": {
@@ -84,7 +84,7 @@
     "command-stream": "^2.0.2",
     "csv-parse": "^7.0.3",
     "gifenc": "^1.0.3",
-    "links-notation": "^0.23.0",
+    "links-notation": "^0.25.2",
     "log-lazy": "^1.0.4",
     "plist": "^5.0.0",
     "test-anywhere": "^0.9.1",

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/traces/links.js

@@ -107,11 +107,11 @@ const HEAD_FIELDS = new Set([
 /**
  * Make one value safe to write as a link.
  *
- * Links Notation 0.20 quotes a value with whichever quote character the value
- * does not contain, and its parser does not read escapes, so a value holding
- * both quote characters cannot be read back. Newlines are worse: they would
- * split one record across lines. Both are encoded here, reversibly, rather
- * than dropped, so the export loses nothing the bundle holds.
+ * Keep the representation's legacy escapes even though current Links Notation
+ * can quote both quote characters. Newlines must not split a record across
+ * lines. Lone UTF-16 surrogates are escaped too: the notation requires valid
+ * Unicode, but JavaScript trace strings can hold individual surrogate units.
+ * All these encodings are reversible, so the export loses no scalar text.
  *
  * @param {*} value - Any scalar from a trace record
  * @returns {string} Text that survives a format and parse round trip
@@ -122,9 +122,13 @@ export function encodeLinkText(value) {
     .replaceAll('\\', '\\\\')
     .replaceAll('\n', '\\n')
     .replaceAll('\r', '\\r')
-    .replaceAll('\t', '\\t');
-  // Only a value that holds both quote characters is unquotable, so only that
-  // value pays for the ugliness of an escaped quote.
+    .replaceAll('\t', '\\t')
+    // Unicode mode matches lone surrogates without splitting valid pairs.
+    .replace(
+      /[\ud800-\udfff]/gu,
+      (unit) => `\\u${unit.charCodeAt(0).toString(16)}`
+    );
+  // Preserve the existing encoding for values holding both quote characters.
   return escaped.includes("'") && escaped.includes('"')
     ? escaped.replaceAll('"', '\\u0022')
     : escaped;
@@ -139,8 +143,9 @@ export function encodeLinkText(value) {
 export function decodeLinkText(text) {
   const decoded = { '\\': '\\', n: '\n', r: '\r', t: '\t', u0022: '"' };
   return String(text).replace(
-    /\\(\\|n|r|t|u0022)/g,
-    (match, code) => decoded[code]
+    /\\(\\|n|r|t|u0022|ud[89a-f][0-9a-f]{2})/g,
+    (match, code) =>
+      decoded[code] ?? String.fromCharCode(Number.parseInt(code.slice(1), 16))
   );
 }
 

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/traces/links-compatibility.test.js

@@ -0,0 +1,56 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { Parser, StreamParser } from 'links-notation';
+import {
+  decodeLinkText,
+  formatTraceLinks,
+  timelineLink,
+} from '../../../src/traces/links.js';
+import { readRepoText } from '../../helpers/repo.js';
+
+describe(
+  'trace compatibility with Links Notation (issue #168)',
+  { timeout: 10000 },
+  () => {
+    it('preserves scalar text through the formatter, parser and trace decoder', () => {
+      for (const text of [
+        '',
+        '#comment',
+        'issue#168',
+        '~1{61}',
+        'both\'and" with `backticks`',
+        'line\r\nbreak\ttab\\literal\\u0022\\ud800\\udfff',
+        '\u0000\u0001\u007f',
+        'a\u00a0b\u2028c\u2029d\ufeff',
+        'Tiếng Việt 日本語 🧭 e\u0301',
+        '\ud800',
+        '\udfff',
+        '🧭\ud800🧭\udfff',
+      ]) {
+        const line = formatTraceLinks([
+          timelineLink({ kind: 'console', text }),
+        ]);
+        assert.equal(line.split('\n').length, 2, 'one record per line');
+        const [parsed] = new Parser().parse(line);
+        const field = parsed.values.find((value) => value.id === 'text');
+        assert.equal(decodeLinkText(field.values[0].id), text);
+      }
+    });
+
+    it('imports the existing cross-language golden export in arbitrary chunks', () => {
+      const text = readRepoText(
+        'js/tests/fixtures/traces/conformance/expected/trace.lino'
+      );
+      const expected = new Parser().parse(text);
+      assert.equal(expected.length, 27);
+      for (const chunkSize of [1, 17, text.length]) {
+        const stream = new StreamParser();
+        for (let offset = 0; offset < text.length; offset += chunkSize) {
+          stream.write(text.slice(offset, offset + chunkSize));
+        }
+        stream.end();
+        assert.deepEqual(stream.drain(), expected);
+      }
+    });
+  }
+);

package/tests/unit/traces/links.test.js

@@ -544,8 +544,8 @@ describe('trace links export (issue #94)', () => {
     // The notation's formatter and parser decide whether an export can be read
     // back, so the range this package depends on and the version the tests
     // proved are the same range.
-    assert.strictEqual(manifest.dependencies['links-notation'], '^0.23.0');
-    assert.match(installed.version, /^0\.23\./);
+    assert.strictEqual(manifest.dependencies['links-notation'], '^0.25.2');
+    assert.match(installed.version, /^0\.25\./);
   });
 
   it('should export a bundle named by path as readily as an open one', async () => {