@saptools/cf-inspector 0.7.1 → 0.8.0

package/README.md

@@ -37,6 +37,8 @@ Built so an AI agent (or a CI job) can drive a debugger from a single shell comm
 - 📡 **Non-pausing logpoints** — `cf-inspector log --at file:line --expr 'JSON.stringify({…})'` streams JSON Lines as the line executes without pausing the inspectee, with optional `--condition`, `--hit-count`, and `--max-events`
 - 🛡️ **Read-only capture guard** — snapshot, watch, and exception captures use V8's side-effect analysis by default; `--allow-mutation` is an explicit escape hatch
 - 🧵 **Automatic worker fan-out** — snapshot, watch, exception, and log attach to the main isolate plus every current or newly-spawned NodeWorker; explicit selectors remain available for pinning
+- 🚦 **Machine-readable readiness** — opt into a versioned `breakpoint-armed` stderr event before triggering external traffic; no prose matching or guessed delay required
+- 📜 **Isolate-aware script listing** — `list-scripts` aggregates the main isolate and every current worker, tagging every script with its isolate
 - 🧠 **Agent-friendly** — JSON-by-default I/O, deterministic shapes, and explicit `truncated`/`originalLength`/`omittedCount` metadata for bounded values
 - 🧭 **Path mapping** — local `src/handler.ts:42` is matched against the remote URL via a `urlRegex`, with optional `--remote-root` literal or regex (same DSL as `cds-debug`)
 - 🔁 **Composes with `cf-debugger`** — pass `--app/--region/--org/--space` and the tunnel is opened automatically; pass `--port` to attach to anything CDP-speaking
@@ -97,6 +99,42 @@ Use `--worker-id <id>` to pin a stable live worker ID from `list-targets`,
 pin a raw inspector target, or `--main-only` to deliberately ignore workers.
 Explicit selectors preserve single-isolate behavior.
 
+### Automation readiness contract
+
+Commands that arm debugger behavior before waiting (`snapshot`, `watch`,
+`exception`, and `log`) accept `--ready-event`. The flag writes exactly one
+compact JSON object to `stderr` after every session present during initial
+arming has completed its CDP setup and immediately before the command waits or
+streams:
+
+```json
+{"event":"breakpoint-armed","schemaVersion":1,"command":"snapshot","sessions":3,"resolvedLocations":2,"timeoutMs":30000}
+```
+
+This is the supported synchronization contract for callers that must start the
+CLI before firing an HTTP request, queue job, or other external trigger. Parse
+the JSON line and require `event === "breakpoint-armed"` plus
+`schemaVersion === 1`, then confirm `command` matches the invocation; do not
+poll prose such as `Waiting up to`.
+
+| Field | Contract |
+| --- | --- |
+| `event` | Always `"breakpoint-armed"` |
+| `schemaVersion` | Event schema version; currently `1` |
+| `command` | `snapshot`, `watch`, `exception`, or `log` |
+| `sessions` | Number of main/worker sessions whose initial arming completed before emission |
+| `resolvedLocations` | Total locations V8 had already resolved, or `null` for `exception`; `0` can still represent an accepted URL breakpoint that may resolve when a script loads |
+| `timeoutMs` | Snapshot/exception wait or watch per-hit timeout; `null` for log |
+
+Workers attaching after this one-time event are still armed dynamically, but
+are not included in its `sessions` or `resolvedLocations` totals. If initial
+arming fails or the command is cancelled first, no readiness event is emitted.
+With `log --ready-event`, matching events received while the remaining initial
+sessions are still arming are neither emitted nor counted, so the log stream
+cannot precede its readiness marker.
+Without `--ready-event`, stderr/stdout behavior is unchanged. An explicitly
+requested event is still emitted with `snapshot --quiet`.
+
 ---
 
 ## 🧰 CLI
@@ -143,6 +181,7 @@ cf-inspector snapshot --port 9229 \
 | `--include-scopes` | Include expanded paused-frame scopes under `topFrame.scopes`. Omitted by default to keep targeted captures concise |
 | `--no-json` | Print a human-readable summary instead of JSON |
 | `--quiet` | Suppress snapshot progress messages on stderr |
+| `--ready-event` | Emit the versioned `breakpoint-armed` JSON event on stderr after every current isolate is armed |
 | `--keep-paused` | Skip `Debugger.resume` after capture |
 | `--fail-on-unmatched-pause` | Fail immediately if the target pauses somewhere else instead of waiting cooperatively |
 
@@ -269,6 +308,7 @@ When the user expression throws, the event is emitted with `error` instead of `v
 | `--max-value-length <chars>` | Maximum characters per log value (streaming default: `4096`). Truncated events include `truncated` and `originalLength` |
 | `--remote-root <value>` | Optional path-mapping anchor (same DSL as `snapshot`) |
 | `--no-json` | Print human-readable lines instead of JSON Lines |
+| `--ready-event` | Emit the versioned `breakpoint-armed` JSON event on stderr after every current isolate is armed |
 
 Native logpoint expressions and conditions have no V8 side-effect gate. The
 CLI warns when its best-effort syntax scan recognizes assignments or common
@@ -319,6 +359,7 @@ Each event is a `WatchEvent`:
 | `--allow-mutation` | Disable the capture side-effect guard and explicitly allow mutation-shaped native conditions |
 | `--include-scopes` | Include expanded paused-frame scopes per hit |
 | `--no-json` | Print human-readable lines instead of JSON Lines |
+| `--ready-event` | Emit the versioned `breakpoint-armed` JSON event on stderr after every current isolate is armed |
 
 ### 💥 `cf-inspector exception`
 
@@ -365,6 +406,7 @@ Result is a `SnapshotResult` with an extra `exception` field:
 | `--max-value-length <chars>` | Maximum characters per captured value (one-shot default: `131072`) |
 | `--keep-paused` | Skip `Debugger.resume` after capture |
 | `--no-json` | Print a human-readable summary instead of JSON |
+| `--ready-event` | Emit the versioned `breakpoint-armed` JSON event on stderr after pause-on-exception is active in every current isolate |
 
 ### 🧮 `cf-inspector eval`
 
@@ -382,12 +424,23 @@ cf-inspector eval --port 9229 --expr 'process.uptime()'
 
 ### 📜 `cf-inspector list-scripts`
 
-Print every script the V8 instance knows about (useful for debugging path-mapping issues). Add `--filter <pattern>` to narrow noisy script lists with a literal/wildcard pattern; `|` separates alternatives and `.*` / `.+` match variable text.
+Print every script known by the main isolate and each currently attached
+NodeWorker (useful for debugging path-mapping issues). Each JSON entry carries
+`isolate: {"kind":"main"}` or
+`isolate: {"kind":"worker","workerId":"…"}`, so duplicate per-isolate
+`scriptId` values remain unambiguous. Add `--filter <pattern>` to narrow noisy
+script lists with a literal/wildcard pattern; `|` separates alternatives and
+`.*` / `.+` match variable text.
 
 ```bash
 cf-inspector list-scripts --port 9229 --filter 'dist/.+\.js'
 ```
 
+With `--no-json`, rows are
+`scriptId<TAB>url<TAB>isolate`, where isolate is `main` or
+`worker:<workerId>`. `--main-only`, `--worker-id`, `--worker`, and `--target`
+retain their normal narrowing behavior.
+
 ### 🎯 `cf-inspector list-targets`
 
 Print raw `/json/list` inspector targets with stable `index` values, likely

package/dist/cli.js

@@ -391,6 +391,15 @@ function writeProgress(message) {
   process2.stderr.write(`[cf-inspector] ${message}
 `);
 }
+function writeArmedEvent(event) {
+  const payload = {
+    event: "breakpoint-armed",
+    schemaVersion: 1,
+    ...event
+  };
+  process2.stderr.write(`${JSON.stringify(payload)}
+`);
+}
 function writeJson(value) {
   process2.stdout.write(`${JSON.stringify(value, null, 2)}
 `);
@@ -3103,6 +3112,8 @@ var BreakpointFanout = class {
   detachError;
   activeRace;
   pauseReasons = [];
+  pendingSetupError;
+  preserveReadinessErrors = false;
   constructor(group, setupSession, pauseReasons = []) {
     this.pauseReasons = pauseReasons;
     this.detach = group.onSession((session) => {
@@ -3128,13 +3139,51 @@ var BreakpointFanout = class {
       this.activeRace?.remove(session);
     });
     this.detachError = group.onError((error) => {
+      if (this.setupErrors.length === 0 && this.pendingSetupError === void 0) {
+        this.pendingSetupError = error;
+      }
       for (const reject of this.setupErrors) {
         reject(error);
       }
     });
   }
-  async ready() {
-    await Promise.all([...this.records.values()].map((record) => record.setup));
+  async ready(options = {}) {
+    if (options.includeNewSessions !== true) {
+      const records = [...this.records.values()];
+      await Promise.all(records.map((record) => record.setup));
+      options.onReady?.(this.outcomesFor(records));
+      return;
+    }
+    this.preserveReadinessErrors = true;
+    const pendingError = this.takePendingSetupError();
+    if (pendingError !== void 0) {
+      throw pendingError;
+    }
+    let rejectGroupError = () => void 0;
+    const groupError = new Promise((_resolve, reject) => {
+      rejectGroupError = reject;
+    });
+    this.setupErrors.push(rejectGroupError);
+    try {
+      let stableRecords;
+      while (stableRecords === void 0) {
+        const records = [...this.records.values()];
+        await Promise.race([
+          Promise.all(records.map((record) => record.setup)),
+          groupError
+        ]);
+        const stable = records.length === this.records.size && records.every((record) => this.records.get(record.session) === record);
+        if (stable) {
+          stableRecords = records;
+        }
+      }
+      options.onReady?.(this.outcomesFor(stableRecords));
+    } finally {
+      const index = this.setupErrors.indexOf(rejectGroupError);
+      if (index >= 0) {
+        this.setupErrors.splice(index, 1);
+      }
+    }
   }
   trackHandle(session, handle) {
     const record = this.records.get(session);
@@ -3143,11 +3192,19 @@ var BreakpointFanout = class {
     }
   }
   availableOutcomes() {
-    return [...this.records.values()].map((record) => ({
+    return this.outcomesFor([...this.records.values()]);
+  }
+  outcomesFor(records) {
+    return records.map((record) => ({
       session: record.session,
       setup: { handles: record.handles }
     }));
   }
+  takePendingSetupError() {
+    const error = this.pendingSetupError;
+    this.pendingSetupError = void 0;
+    return error;
+  }
   async waitForFirst(timeoutMs, options = {}, signal) {
     if (this.activeRace !== void 0) {
       throw new CfInspectorError("INVALID_ARGUMENT", "A fan-out pause race is already active");
@@ -3156,6 +3213,12 @@ var BreakpointFanout = class {
     this.pauseReasons = options.pauseReasons ?? [];
     this.activeRace = race;
     this.setupErrors.push(race.reject);
+    if (this.preserveReadinessErrors) {
+      const pendingError = this.takePendingSetupError();
+      if (pendingError !== void 0) {
+        race.reject(pendingError);
+      }
+    }
     for (const record of this.records.values()) {
       race.add(record);
     }
@@ -4126,7 +4189,20 @@ async function runExceptionCommand(command, opts, signal) {
     let winner;
     let preserveWinner = false;
     try {
-      await fanout.ready();
+      await fanout.ready(opts.readyEvent === true ? {
+        includeNewSessions: true,
+        onReady: (outcomes) => {
+          if (signal?.aborted === true) {
+            return;
+          }
+          writeArmedEvent({
+            command: "exception",
+            sessions: outcomes.length,
+            resolvedLocations: null,
+            timeoutMs: command.timeoutMs
+          });
+        }
+      } : {});
       const hit = await fanout.waitForFirst(command.timeoutMs, {
         pauseReasons: ["exception", "promiseRejection"],
         unmatchedPausePolicy: "wait-for-resume"
@@ -4179,16 +4255,44 @@ import process9 from "process";
 async function handleListScripts(opts) {
   const target = await resolveTargetWithCurrentCfTarget(opts);
   const filter = compileScriptUrlFilter(opts.filter);
-  const scripts = (await withSession(target, (session) => Promise.resolve(listScripts(session)))).filter((script) => filter === void 0 || filter(script.url));
+  const scripts = (await withSessions(target, (group) => {
+    const sessions = group.list();
+    warnOnListScriptsSelection(target, {
+      targetCount: group.targetCount,
+      targetIndex: group.targetIndex,
+      ...sessions[0]?.workerTargets === void 0 ? {} : { workerTargets: sessions[0].workerTargets }
+    });
+    return Promise.resolve(collectListedScripts(sessions));
+  })).filter((script) => filter === void 0 || filter(script.url));
   if (opts.json) {
     writeJson(scripts);
     return;
   }
   for (const script of scripts) {
-    process9.stdout.write(`${script.scriptId}	${script.url}
-`);
+    process9.stdout.write(
+      `${script.scriptId}	${script.url}	${formatIsolate2(script.isolate)}
+`
+    );
   }
 }
+function warnOnListScriptsSelection(target, selection) {
+  const autoAttach = target.targetIndex === void 0 && target.workerIndex === void 0 && target.workerId === void 0 && target.mainOnly !== true;
+  const isolateWasExplicit = autoAttach || target.workerIndex !== void 0 || target.workerId !== void 0 || target.mainOnly === true;
+  warnOnImplicitInspectorSelection(
+    selection,
+    target.targetIndex !== void 0,
+    isolateWasExplicit
+  );
+}
+function collectListedScripts(sessions) {
+  return sessions.flatMap((session) => listScripts(session).map((script) => ({
+    ...script,
+    isolate: session.isolate ?? { kind: "main" }
+  })));
+}
+function formatIsolate2(isolate) {
+  return isolate.kind === "worker" ? `worker:${isolate.workerId}` : "main";
+}
 async function handleListTargets(opts) {
   const target = await resolveTargetWithCurrentCfTarget(opts);
   const tunnel = await openTarget(target);
@@ -4521,6 +4625,9 @@ async function streamLogpoint(session, options) {
     if (event === void 0) {
       return;
     }
+    if (options.eventGate?.() === false) {
+      return;
+    }
     emitted += 1;
     try {
       options.onEvent(event);
@@ -4639,6 +4746,7 @@ async function handleLog(opts) {
         ...condition === void 0 ? {} : { condition },
         maxValueLength,
         json: opts.json,
+        emitReadyEvent: opts.readyEvent === true,
         signal
       });
       writeLogSummary(result.stoppedReason, result.emitted, opts.json);
@@ -4650,9 +4758,13 @@ async function runLogGroup(group, options) {
   const tasks = /* @__PURE__ */ new Set();
   const removedSessions = /* @__PURE__ */ new Set();
   const results = [];
+  const pendingArming = /* @__PURE__ */ new Set();
+  const resolvedLocations = /* @__PURE__ */ new Map();
   let fatalError;
   let emitted = 0;
   let reason = "signal";
+  let sessionRegistrationComplete = false;
+  let readyEventEmitted = !options.emitReadyEvent;
   let resolveStop;
   const stopped = new Promise((resolve) => {
     resolveStop = resolve;
@@ -4675,10 +4787,35 @@ async function runLogGroup(group, options) {
   const timer = options.durationMs === void 0 ? void 0 : setTimeout(() => {
     finish("duration");
   }, options.durationMs);
+  const detachError = options.emitReadyEvent ? group.onError((error) => {
+    if (controller.signal.aborted) {
+      return;
+    }
+    fatalError = error;
+    finish("transport-closed");
+  }) : () => void 0;
+  const emitReadyEventIfArmed = () => {
+    if (readyEventEmitted || !sessionRegistrationComplete || pendingArming.size > 0 || resolvedLocations.size === 0 || controller.signal.aborted) {
+      return;
+    }
+    writeArmedEvent({
+      command: "log",
+      sessions: resolvedLocations.size,
+      resolvedLocations: [...resolvedLocations.values()].reduce(
+        (total, count) => total + count,
+        0
+      ),
+      timeoutMs: null
+    });
+    readyEventEmitted = true;
+  };
   const startSession = (session) => {
     if (controller.signal.aborted) {
       return;
     }
+    if (!readyEventEmitted) {
+      pendingArming.add(session);
+    }
     const task = (async () => {
       await validateExpression(session, options.expression);
       if (options.condition !== void 0) {
@@ -4692,6 +4829,7 @@ async function runLogGroup(group, options) {
         ...options.condition === void 0 ? {} : { condition: options.condition },
         maxValueLength: options.maxValueLength,
         signal: controller.signal,
+        ...options.emitReadyEvent ? { eventGate: () => readyEventEmitted } : {},
         onEvent: (event) => {
           if (controller.signal.aborted) {
             return;
@@ -4704,6 +4842,11 @@ async function runLogGroup(group, options) {
         },
         onBreakpointSet: (handle) => {
           warnOnUnboundBreakpoints([handle]);
+          if (!readyEventEmitted) {
+            resolvedLocations.set(session, handle.resolvedLocations.length);
+            pendingArming.delete(session);
+            emitReadyEventIfArmed();
+          }
         }
       });
     })();
@@ -4716,6 +4859,9 @@ async function runLogGroup(group, options) {
         }
       },
       (error) => {
+        if (options.emitReadyEvent && (removedSessions.has(session) || fatalError !== void 0)) {
+          return;
+        }
         fatalError = error;
         finish("transport-closed");
       }
@@ -4724,8 +4870,27 @@ async function runLogGroup(group, options) {
     });
   };
   const detach = group.onSession(startSession);
+  sessionRegistrationComplete = true;
+  emitReadyEventIfArmed();
   const detachRemoved = group.onSessionRemoved((session) => {
     removedSessions.add(session);
+    if (!readyEventEmitted) {
+      if (controller.signal.aborted) {
+        pendingArming.delete(session);
+        resolvedLocations.delete(session);
+        return;
+      }
+      if (pendingArming.has(session)) {
+        fatalError = new CfInspectorError(
+          "INSPECTOR_CONNECTION_FAILED",
+          "A worker detached before logpoint arming completed; no readiness event was emitted."
+        );
+        finish("transport-closed");
+        return;
+      }
+      resolvedLocations.delete(session);
+      emitReadyEventIfArmed();
+    }
   });
   try {
     await stopped;
@@ -4733,6 +4898,7 @@ async function runLogGroup(group, options) {
   } finally {
     detach();
     detachRemoved();
+    detachError();
     if (timer !== void 0) {
       clearTimeout(timer);
     }
@@ -4839,18 +5005,38 @@ async function runSnapshotCommand(command, opts, reportProgress, signal) {
     let winner;
     let preserveWinner = false;
     try {
-      await fanout.ready();
-      if (command.setupEvals.length > 0) {
-        reportProgress?.("Setup evaluation complete.");
-      }
-      if (command.condition !== void 0) {
-        reportProgress?.("Breakpoint condition is valid.");
+      const reportArmedSetup = (outcomes) => {
+        if (opts.readyEvent === true && signal?.aborted === true) {
+          return;
+        }
+        if (command.setupEvals.length > 0) {
+          reportProgress?.("Setup evaluation complete.");
+        }
+        if (command.condition !== void 0) {
+          reportProgress?.("Breakpoint condition is valid.");
+        }
+        const setup = reportBreakpointOutcomes(outcomes, reportProgress);
+        reportProgress?.(
+          `Waiting up to ${(command.timeoutMs / 1e3).toString()}s for a breakpoint hit...`
+        );
+        if (opts.readyEvent === true && signal?.aborted !== true) {
+          writeArmedEvent({
+            command: "snapshot",
+            sessions: setup.sessions,
+            resolvedLocations: setup.resolvedLocations,
+            timeoutMs: command.timeoutMs
+          });
+        }
+      };
+      if (opts.readyEvent === true) {
+        await fanout.ready({
+          includeNewSessions: true,
+          onReady: reportArmedSetup
+        });
+      } else {
+        await fanout.ready();
+        reportArmedSetup(fanout.availableOutcomes());
       }
-      const outcomes = fanout.availableOutcomes();
-      reportBreakpointOutcomes(outcomes, reportProgress);
-      reportProgress?.(
-        `Waiting up to ${(command.timeoutMs / 1e3).toString()}s for a breakpoint hit...`
-      );
       const hit = await fanout.waitForFirst(command.timeoutMs, {
         unmatchedPausePolicy: opts.failOnUnmatchedPause === true ? "fail" : "wait-for-resume",
         ...opts.failOnUnmatchedPause === true ? {} : { onUnmatchedPause: warnOnUnmatchedPause }
@@ -4898,11 +5084,12 @@ function reportBreakpointOutcomes(outcomes, reportProgress) {
     reportProgress?.(
       `Breakpoint setup complete: ${locations.toString()} resolved ${locations === 1 ? "location" : "locations"}.`
     );
-    return;
+    return { sessions: outcomes.length, resolvedLocations: locations };
   }
   reportProgress?.(
     `Breakpoint setup complete: sessions=${outcomes.length.toString()} boundSessions=${boundSessions.toString()} resolvedLocations=${locations.toString()}.`
   );
+  return { sessions: outcomes.length, resolvedLocations: locations };
 }
 async function captureSnapshotResult(session, pause, command, opts, reportProgress) {
   const pausedStartedAt = pause.receivedAtMs ?? performance6.now();
@@ -5023,7 +5210,26 @@ async function runWatchGroup(group, command, opts, signal) {
   let stoppedReason = "signal";
   const deadline = computeDeadline(command.durationMs);
   try {
-    await fanout.ready();
+    await fanout.ready(opts.readyEvent === true ? {
+      includeNewSessions: true,
+      onReady: (outcomes) => {
+        if (signal.aborted || remainingForLoop(deadline, command.perHitTimeoutMs) <= 0) {
+          return;
+        }
+        writeArmedEvent({
+          command: "watch",
+          sessions: outcomes.length,
+          resolvedLocations: outcomes.reduce(
+            (total, outcome) => total + outcome.setup.handles.reduce(
+              (sessionTotal, handle) => sessionTotal + handle.resolvedLocations.length,
+              0
+            ),
+            0
+          ),
+          timeoutMs: command.perHitTimeoutMs
+        });
+      }
+    } : {});
     while (!signal.aborted) {
       const remainingMs = remainingForLoop(deadline, command.perHitTimeoutMs);
       if (remainingMs <= 0) {
@@ -5197,6 +5403,7 @@ var collectStrings = (value, prev = []) => [
   ...prev,
   value
 ];
+var READY_EVENT_DESCRIPTION = "Emit a versioned breakpoint-armed JSON event on stderr after every current isolate is armed";
 function readPackageVersion() {
   let current = dirname(fileURLToPath(import.meta.url));
   for (let depth = 0; depth < 4; depth += 1) {
@@ -5242,14 +5449,14 @@ function registerSnapshot(program) {
   applyTargetOptions(
     program.command("snapshot").description("Set a breakpoint, wait for it to hit, capture expressions, and resume"),
     { includeTimeout: false }
-  ).option("--bp <file:line>", "Breakpoint location (repeatable; first hit wins), e.g. src/handler.ts:42", collectStrings, []).option("--capture <expr,\u2026>", "Top-level comma-separated expressions to evaluate in the paused frame").option("--setup-eval <expr>", "Evaluate a global setup expression before breakpoint setup (repeatable)", collectStrings, []).option("--timeout <seconds>", "How long to wait for the breakpoint to hit (default: 30)").option("--max-value-length <chars>", "Maximum characters per captured value before truncation (default: 131072)").option("--remote-root <value>", "Path-mapping anchor: literal path or regex:<pattern> / /pattern/flags").option("--condition <expr>", "Only pause when this JS expression evaluates truthy in the paused frame").option("--hit-count <n>", "Only pause after the breakpoint has been hit N or more times").option("--stack-depth <n>", "Walk this many call frames when capturing (default: 1, only top frame)").option("--stack-captures <expr,\u2026>", "Expressions to evaluate on each call frame in the stack").option("--allow-mutation", "Allow mutation-capable captures and native breakpoint conditions to run").option("--include-scopes", "Include expanded paused-frame scopes in the snapshot").option("--no-json", "Print a human-readable summary instead of JSON").option("--quiet", "Suppress progress messages on stderr").option("--keep-paused", "Skip Debugger.resume after capture; Node may resume when this CLI disconnects").option("--fail-on-unmatched-pause", "Fail immediately if the target pauses somewhere else").action(async (opts) => {
+  ).option("--bp <file:line>", "Breakpoint location (repeatable; first hit wins), e.g. src/handler.ts:42", collectStrings, []).option("--capture <expr,\u2026>", "Top-level comma-separated expressions to evaluate in the paused frame").option("--setup-eval <expr>", "Evaluate a global setup expression before breakpoint setup (repeatable)", collectStrings, []).option("--timeout <seconds>", "How long to wait for the breakpoint to hit (default: 30)").option("--max-value-length <chars>", "Maximum characters per captured value before truncation (default: 131072)").option("--remote-root <value>", "Path-mapping anchor: literal path or regex:<pattern> / /pattern/flags").option("--condition <expr>", "Only pause when this JS expression evaluates truthy in the paused frame").option("--hit-count <n>", "Only pause after the breakpoint has been hit N or more times").option("--stack-depth <n>", "Walk this many call frames when capturing (default: 1, only top frame)").option("--stack-captures <expr,\u2026>", "Expressions to evaluate on each call frame in the stack").option("--allow-mutation", "Allow mutation-capable captures and native breakpoint conditions to run").option("--include-scopes", "Include expanded paused-frame scopes in the snapshot").option("--no-json", "Print a human-readable summary instead of JSON").option("--quiet", "Suppress progress messages on stderr").option("--ready-event", READY_EVENT_DESCRIPTION).option("--keep-paused", "Skip Debugger.resume after capture; Node may resume when this CLI disconnects").option("--fail-on-unmatched-pause", "Fail immediately if the target pauses somewhere else").action(async (opts) => {
     await handleSnapshot(opts);
   });
 }
 function registerLog(program) {
   applyTargetOptions(
     program.command("log").description("Stream a non-pausing logpoint: log an expression each time a line executes")
-  ).requiredOption("--at <file:line>", "Logpoint location, e.g. src/handler.ts:42").requiredOption("--expr <expression>", "JavaScript expression to log on each hit").option("--remote-root <value>", "Path-mapping anchor: literal path or regex:<pattern> / /pattern/flags").option("--duration <seconds>", "Stop streaming after N seconds (default: run until SIGINT)").option("--max-events <n>", "Stop streaming after emitting N log events").option("--hit-count <n>", "Start logging once the line has been hit N or more times").option("--condition <expr>", "Only log when this JS expression evaluates truthy on the inspectee").option("--max-value-length <chars>", "Maximum characters per log value before truncation (default: 4096)").option("--no-json", "Print human-readable lines instead of JSON Lines").action(async (opts) => {
+  ).requiredOption("--at <file:line>", "Logpoint location, e.g. src/handler.ts:42").requiredOption("--expr <expression>", "JavaScript expression to log on each hit").option("--remote-root <value>", "Path-mapping anchor: literal path or regex:<pattern> / /pattern/flags").option("--duration <seconds>", "Stop streaming after N seconds (default: run until SIGINT)").option("--max-events <n>", "Stop streaming after emitting N log events").option("--hit-count <n>", "Start logging once the line has been hit N or more times").option("--condition <expr>", "Only log when this JS expression evaluates truthy on the inspectee").option("--max-value-length <chars>", "Maximum characters per log value before truncation (default: 4096)").option("--no-json", "Print human-readable lines instead of JSON Lines").option("--ready-event", READY_EVENT_DESCRIPTION).action(async (opts) => {
     await handleLog(opts);
   });
 }
@@ -5257,7 +5464,7 @@ function registerWatch(program) {
   applyTargetOptions(
     program.command("watch").description("Stream a snapshot per breakpoint hit (multi-shot watch); resume between hits"),
     { includeTimeout: false }
-  ).option("--bp <file:line>", "Breakpoint location (repeatable), e.g. src/handler.ts:42", collectStrings, []).option("--capture <expr,\u2026>", "Top-level comma-separated expressions to evaluate per hit").option("--setup-eval <expr>", "Evaluate a global setup expression before breakpoint setup (repeatable)", collectStrings, []).option("--condition <expr>", "Only emit hits where this JS expression evaluates truthy").option("--hit-count <n>", "Start emitting after the line has been hit N or more times").option("--remote-root <value>", "Path-mapping anchor: literal path or regex:<pattern> / /pattern/flags").option("--duration <seconds>", "Stop streaming after N seconds (default: run until SIGINT)").option("--max-events <n>", "Stop streaming after emitting N watch events").option("--timeout <seconds>", "How long to wait for the next hit before giving up (default: 30)").option("--max-value-length <chars>", "Maximum characters per captured value before truncation (default: 4096)").option("--stack-depth <n>", "Walk this many call frames per hit (default: 1)").option("--stack-captures <expr,\u2026>", "Expressions to evaluate on each call frame").option("--allow-mutation", "Allow mutation-capable captures and native breakpoint conditions to run").option("--include-scopes", "Include expanded paused-frame scopes per hit").option("--no-json", "Print human-readable lines instead of JSON Lines").action(async (opts) => {
+  ).option("--bp <file:line>", "Breakpoint location (repeatable), e.g. src/handler.ts:42", collectStrings, []).option("--capture <expr,\u2026>", "Top-level comma-separated expressions to evaluate per hit").option("--setup-eval <expr>", "Evaluate a global setup expression before breakpoint setup (repeatable)", collectStrings, []).option("--condition <expr>", "Only emit hits where this JS expression evaluates truthy").option("--hit-count <n>", "Start emitting after the line has been hit N or more times").option("--remote-root <value>", "Path-mapping anchor: literal path or regex:<pattern> / /pattern/flags").option("--duration <seconds>", "Stop streaming after N seconds (default: run until SIGINT)").option("--max-events <n>", "Stop streaming after emitting N watch events").option("--timeout <seconds>", "How long to wait for the next hit before giving up (default: 30)").option("--max-value-length <chars>", "Maximum characters per captured value before truncation (default: 4096)").option("--stack-depth <n>", "Walk this many call frames per hit (default: 1)").option("--stack-captures <expr,\u2026>", "Expressions to evaluate on each call frame").option("--allow-mutation", "Allow mutation-capable captures and native breakpoint conditions to run").option("--include-scopes", "Include expanded paused-frame scopes per hit").option("--no-json", "Print human-readable lines instead of JSON Lines").option("--ready-event", READY_EVENT_DESCRIPTION).action(async (opts) => {
     await handleWatch(opts);
   });
 }
@@ -5265,7 +5472,7 @@ function registerException(program) {
   applyTargetOptions(
     program.command("exception").description("Pause on a thrown exception, capture the value and frame, then resume"),
     { includeTimeout: false }
-  ).option("--type <state>", "Pause type: uncaught (default), caught, or all").option("--capture <expr,\u2026>", "Top-level comma-separated expressions to evaluate in the paused frame").option("--remote-root <value>", "Path-mapping anchor: literal path or regex:<pattern> / /pattern/flags").option("--timeout <seconds>", "How long to wait for an exception (default: 30)").option("--max-value-length <chars>", "Maximum characters per captured value before truncation (default: 131072)").option("--stack-depth <n>", "Walk this many call frames when capturing (default: 1)").option("--stack-captures <expr,\u2026>", "Expressions to evaluate on each call frame in the stack").option("--allow-mutation", "Allow mutation-capable capture expressions to run").option("--include-scopes", "Include expanded paused-frame scopes in the snapshot").option("--keep-paused", "Skip Debugger.resume after capture; Node may resume when this CLI disconnects").option("--no-json", "Print a human-readable summary instead of JSON").action(async (opts) => {
+  ).option("--type <state>", "Pause type: uncaught (default), caught, or all").option("--capture <expr,\u2026>", "Top-level comma-separated expressions to evaluate in the paused frame").option("--remote-root <value>", "Path-mapping anchor: literal path or regex:<pattern> / /pattern/flags").option("--timeout <seconds>", "How long to wait for an exception (default: 30)").option("--max-value-length <chars>", "Maximum characters per captured value before truncation (default: 131072)").option("--stack-depth <n>", "Walk this many call frames when capturing (default: 1)").option("--stack-captures <expr,\u2026>", "Expressions to evaluate on each call frame in the stack").option("--allow-mutation", "Allow mutation-capable capture expressions to run").option("--include-scopes", "Include expanded paused-frame scopes in the snapshot").option("--keep-paused", "Skip Debugger.resume after capture; Node may resume when this CLI disconnects").option("--no-json", "Print a human-readable summary instead of JSON").option("--ready-event", READY_EVENT_DESCRIPTION).action(async (opts) => {
     await handleException(opts);
   });
 }
@@ -5278,8 +5485,10 @@ function registerEval(program) {
 }
 function registerListScripts(program) {
   applyTargetOptions(
-    program.command("list-scripts").description("Print the scripts the V8 instance currently knows about")
-  ).option("--filter <pattern>", "Only include script URLs matching this pattern").option("--no-json", "Print scriptId<TAB>url instead of JSON").action(async (opts) => {
+    program.command("list-scripts").description(
+      "Print scripts from the main isolate and every worker, tagged by isolate"
+    )
+  ).option("--filter <pattern>", "Only include script URLs matching this pattern").option("--no-json", "Print scriptId<TAB>url<TAB>isolate instead of JSON").action(async (opts) => {
     await handleListScripts(opts);
   });
 }