@saptools/cf-inspector 0.3.2 → 0.3.3

package/README.md

@@ -22,7 +22,7 @@ Built so an AI agent (or a CI job) can drive a debugger from a single shell comm
 - ✅ **Conditional breakpoints** — `--condition 'req.userId === "abc"'` only pauses when the predicate is truthy
 - 🎭 **Multi-breakpoint** — repeat `--bp` to race several locations; first hit wins
 - 📡 **Non-pausing logpoints** — `cf-inspector log --at file:line --expr 'JSON.stringify({…})'` streams JSON Lines as the line executes, **without ever pausing the inspectee** (safe for production traffic)
-- 🧠 **Agent-friendly** — JSON-by-default I/O, deterministic shape, sensitive-name redaction (`password`, `token`, `secret`, `cookie`, …) baked in
+- 🧠 **Agent-friendly** — JSON-by-default I/O, deterministic shape, sensitive-name redaction (`password`, `credentials`, `token`, `secret`, `cookie`, …) baked in
 - 🧭 **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
 - 🪶 **Tiny dependency footprint** — `commander` + `ws` only, no heavy CDP framework
@@ -109,16 +109,26 @@ cf-inspector snapshot --port 9229 \
 | `--port <number>` | Local port the inspector or tunnel listens on. **Required** unless `--app/--region/--org/--space` are all set |
 | `--bp <file:line>` | **Required.** Source location to break at. Pass multiple times to race several locations — the first one to hit wins |
 | `--condition <expr>` | Only pause when this JS expression evaluates truthy in the paused frame. Errors in the condition are silently treated as `false` by V8 |
-| `--capture <expr,…>` | Comma-separated expressions to evaluate in the paused frame; results merged into the snapshot |
+| `--capture <expr,…>` | Top-level comma-separated expressions to evaluate in the paused frame; nested commas inside objects, arrays, calls, or strings are preserved |
 | `--timeout <seconds>` | How long to wait for the breakpoint to hit (default: `30`) |
 | `--remote-root <value>` | Optional path-mapping anchor: literal path or `regex:<pattern>` / `/pattern/flags` |
 | `--no-json` | Print a human-readable summary instead of JSON |
-| `--keep-paused` | Skip the auto-resume after capture (useful for diagnostics) |
+| `--keep-paused` | Skip `Debugger.resume` after capture; Node may resume when the CLI disconnects |
+| `--fail-on-unmatched-pause` | Fail immediately if the target pauses somewhere else instead of waiting cooperatively |
 
 JSON output includes `pausedDurationMs`, the client-observed time from receiving
 the matching pause event until `Debugger.resume` completes. It does not include
 the time spent waiting for the breakpoint to hit. When `--keep-paused` is used,
-`pausedDurationMs` is `null` because the process intentionally remains paused.
+`pausedDurationMs` is `null` because `cf-inspector` intentionally skips
+`Debugger.resume`. Node may resume execution when this one-shot CLI disconnects,
+so treat `--keep-paused` as a low-level diagnostic escape hatch, not a durable
+paused-session mode.
+
+If the target pauses somewhere else first, for example another debugger's
+breakpoint or a `debugger;` statement, `snapshot` does not resume it by default.
+It warns once, waits for `Debugger.resumed`, then continues waiting for its own
+breakpoint within the remaining timeout. Use `--fail-on-unmatched-pause` when a
+strict immediate error is preferred.
 
 For Cloud Foundry targets, replace `--port` with `--region/--org/--space/--app` (and optionally `--cf-timeout <seconds>` for the tunnel).
 
@@ -161,7 +171,7 @@ When the user expression throws, the event is emitted with `error` instead of `v
 
 ### 🧮 `cf-inspector eval`
 
-Evaluate one expression and print the result. If a breakpoint is currently paused, it runs in the top frame; otherwise it runs against `Runtime.evaluate` in the global scope.
+Evaluate one expression with `Runtime.evaluate` in the global scope and print the result. For paused-frame values, use `snapshot --capture` or the programmatic `evaluateOnFrame(...)` API.
 
 ```bash
 cf-inspector eval --port 9229 --expr 'process.uptime()'
@@ -204,7 +214,11 @@ const bp = await setBreakpoint(session, {
 });
 const pause = await waitForPause(session, { timeoutMs: 30_000 });
 const snapshot = await captureSnapshot(session, pause);
-const customValue = await evaluateOnFrame(session, pause.callFrames[0]!.callFrameId, "this.user");
+const topFrame = pause.callFrames[0];
+if (topFrame === undefined) {
+  throw new Error("Breakpoint paused without a call frame");
+}
+const customValue = await evaluateOnFrame(session, topFrame.callFrameId, "this.user");
 await resume(session);
 await session.dispose();
 
@@ -247,6 +261,8 @@ console.log({ bp, snapshot, customValue });
 | `INSPECTOR_CONNECTION_FAILED` | WebSocket handshake failed, or the connection closed mid-request |
 | `CDP_REQUEST_FAILED` | A CDP method returned an error result, timed out, or failed to send |
 | `BREAKPOINT_NOT_HIT` | The breakpoint did not hit before the timeout elapsed |
+| `UNRELATED_PAUSE` | The target paused somewhere else and `--fail-on-unmatched-pause` was enabled |
+| `UNRELATED_PAUSE_TIMEOUT` | The target stayed paused somewhere else until the snapshot timeout elapsed |
 | `EVALUATION_FAILED` | Reserved for future use — current evaluation paths surface remote exceptions inline via `CapturedExpression.error` instead of throwing |
 | `MISSING_TARGET` | Neither `--port` nor a complete CF target (`--region/--org/--space/--app`) was provided |
 | `ABORTED` | Reserved for future use by long-running streams when an `AbortSignal` fires |
@@ -272,10 +288,10 @@ Path mapping uses CDP's first-class `urlRegex`:
 
 | `--remote-root` | Resulting urlRegex (line `42` of `src/handler.ts`) |
 | --- | --- |
-| _omitted_ | `(?:^|/)src/handler\.(?:ts\|js)$` |
-| `/home/vcap/app` (literal) | `^file:///home/vcap/app/src/handler\.(?:ts\|js)$` |
-| `regex:^/example-root-.*$` | `^file:///example-root-[^/]+/src/handler\.(?:ts\|js)$` |
-| `/^/example-root-.*$/` | same as above |
+| _omitted_ | `(?:^|/)src/handler\.(?:ts\|js\|mts\|mjs\|cts\|cjs)$` |
+| `/home/vcap/app` (literal) | `^file:///home/vcap/app/src/handler\.(?:ts\|js\|mts\|mjs\|cts\|cjs)$` |
+| `regex:^/example-root-.*$` | `^file:///example-root-.*/src/handler\.(?:ts\|js\|mts\|mjs\|cts\|cjs)$` |
+| `regex:^/(home/vcap/app\|example-root-.*)$` | `^file:///(home/vcap/app\|example-root-.*)/src/handler\.(?:ts\|js\|mts\|mjs\|cts\|cjs)$` |
 
 `.ts ↔ .js` is folded into the regex automatically because Node's V8 inspector normally serves both the source-mapped TypeScript URL and the runtime JavaScript URL — matching either is correct.
 

package/dist/cli.js

@@ -118,12 +118,13 @@ var init_wsTransport = __esm({
 });
 
 // src/cli.ts
-import { performance } from "perf_hooks";
+import { performance as performance2 } from "perf_hooks";
 import process from "process";
 import { Command } from "commander";
 
 // src/inspector.ts
 import { request } from "http";
+import { performance } from "perf_hooks";
 
 // src/cdp.ts
 init_types();
@@ -430,6 +431,15 @@ function stripTrailingSlash(value) {
   }
   return value;
 }
+function normalizeRegexRootPattern(pattern) {
+  const withoutStartAnchor = pattern.startsWith("^") ? pattern.slice(1) : pattern;
+  const withoutEndAnchor = withoutStartAnchor.endsWith("$") && !isEscaped(withoutStartAnchor, withoutStartAnchor.length - 1) ? withoutStartAnchor.slice(0, -1) : withoutStartAnchor;
+  return stripTrailingSlash(withoutEndAnchor);
+}
+function buildFileUrlRegex(rootPattern, tail) {
+  const separator = rootPattern.endsWith("/") ? "" : "/";
+  return `^file://${rootPattern}${separator}${tail}$`;
+}
 function escapeRegExp(value) {
   return value.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
 }
@@ -456,10 +466,11 @@ function buildBreakpointUrlRegex(input) {
     }
     case "literal": {
       const escapedRoot = escapeRegExp(input.remoteRoot.value);
-      return `^file://${escapedRoot}/${tail}$`;
+      return buildFileUrlRegex(escapedRoot, tail);
     }
     case "regex": {
-      return `^file://${input.remoteRoot.pattern}/${tail}$`;
+      const rootPattern = normalizeRegexRootPattern(input.remoteRoot.pattern);
+      return buildFileUrlRegex(rootPattern, tail);
     }
   }
 }
@@ -608,21 +619,21 @@ async function connectInspector(options) {
   const PAUSE_BUFFER_LIMIT = 32;
   const pauseBuffer = [];
   const pauseWaitGate = { active: false };
+  const debuggerState = {};
   client.on("Debugger.paused", (raw) => {
     if (pauseWaitGate.active) {
       return;
     }
     const params = raw;
-    const event = {
-      reason: asString(params.reason),
-      hitBreakpoints: Array.isArray(params.hitBreakpoints) ? params.hitBreakpoints.filter((id) => typeof id === "string") : [],
-      callFrames: toCallFrames(params.callFrames)
-    };
+    const event = toPauseEvent(params, performance.now());
     if (pauseBuffer.length >= PAUSE_BUFFER_LIMIT) {
       pauseBuffer.shift();
     }
     pauseBuffer.push(event);
   });
+  client.on("Debugger.resumed", () => {
+    debuggerState.lastResumedAtMs = performance.now();
+  });
   await client.send("Runtime.enable");
   await client.send("Debugger.enable");
   return {
@@ -631,6 +642,7 @@ async function connectInspector(options) {
     scripts,
     pauseBuffer,
     pauseWaitGate,
+    debuggerState,
     dispose: async () => {
       try {
         await client.send("Debugger.disable");
@@ -748,36 +760,121 @@ function pauseMatches(pause, breakpointIds) {
   }
   return pause.hitBreakpoints.some((id) => breakpointIds.includes(id));
 }
+function toPauseEvent(params, receivedAtMs) {
+  return {
+    reason: asString(params.reason),
+    hitBreakpoints: Array.isArray(params.hitBreakpoints) ? params.hitBreakpoints.filter((id) => typeof id === "string") : [],
+    callFrames: toCallFrames(params.callFrames),
+    receivedAtMs
+  };
+}
+function remainingUntil(deadlineMs) {
+  return Math.max(0, deadlineMs - performance.now());
+}
+function topFrameLocation(pause) {
+  const top = pause.callFrames[0];
+  if (top === void 0) {
+    return "(no call frame)";
+  }
+  const url = top.url !== void 0 && top.url.length > 0 ? top.url : "(unknown)";
+  return `${url}:${(top.lineNumber + 1).toString()}:${(top.columnNumber + 1).toString()}`;
+}
+function pauseDetail(pause) {
+  return JSON.stringify({
+    reason: pause.reason,
+    hitBreakpoints: pause.hitBreakpoints,
+    topFrame: topFrameLocation(pause)
+  });
+}
+function hasResumedSincePause(session, pause) {
+  const pauseAt = pause.receivedAtMs;
+  const resumedAt = session.debuggerState.lastResumedAtMs;
+  return pauseAt !== void 0 && resumedAt !== void 0 && resumedAt >= pauseAt;
+}
+function throwBreakpointTimeout(timeoutMs) {
+  throw new CfInspectorError(
+    "BREAKPOINT_NOT_HIT",
+    `Timed out waiting for matching Debugger.paused after ${timeoutMs.toString()}ms`
+  );
+}
+function throwUnrelatedPauseTimeout(pause, timeoutMs) {
+  throw new CfInspectorError(
+    "UNRELATED_PAUSE_TIMEOUT",
+    `Target stayed paused by another debugger event before this command's breakpoint could hit within ${timeoutMs.toString()}ms`,
+    pauseDetail(pause)
+  );
+}
+async function waitForUnmatchedPauseToResume(session, pause, deadlineMs, timeoutMs) {
+  if (hasResumedSincePause(session, pause)) {
+    return;
+  }
+  const remainingMs = remainingUntil(deadlineMs);
+  if (remainingMs <= 0) {
+    throwUnrelatedPauseTimeout(pause, timeoutMs);
+  }
+  try {
+    await session.client.waitFor("Debugger.resumed", { timeoutMs: remainingMs });
+    session.debuggerState.lastResumedAtMs = performance.now();
+  } catch (err) {
+    if (err instanceof CfInspectorError && err.code === "BREAKPOINT_NOT_HIT") {
+      throwUnrelatedPauseTimeout(pause, timeoutMs);
+    }
+    throw err;
+  }
+}
+async function handleUnmatchedPause(session, pause, options, deadlineMs) {
+  if (options.unmatchedPausePolicy === "fail") {
+    throw new CfInspectorError(
+      "UNRELATED_PAUSE",
+      "Target paused before this command's breakpoint was reached",
+      pauseDetail(pause)
+    );
+  }
+  if (hasResumedSincePause(session, pause)) {
+    return;
+  }
+  options.onUnmatchedPause?.(pause);
+  await waitForUnmatchedPauseToResume(session, pause, deadlineMs, options.timeoutMs);
+}
 async function waitForPause(session, options) {
+  const deadlineMs = performance.now() + options.timeoutMs;
   const buffer = session.pauseBuffer;
-  while (buffer.length > 0) {
-    const head = buffer.shift();
-    if (head !== void 0 && pauseMatches(head, options.breakpointIds)) {
-      return head;
+  while (buffer.length > 0 || remainingUntil(deadlineMs) > 0) {
+    while (buffer.length > 0) {
+      const buffered = buffer.shift();
+      if (buffered === void 0) {
+        continue;
+      }
+      if (pauseMatches(buffered, options.breakpointIds)) {
+        return buffered;
+      }
+      await handleUnmatchedPause(session, buffered, options, deadlineMs);
     }
-  }
-  session.pauseWaitGate.active = true;
-  let params;
-  try {
-    const expected = options.breakpointIds;
-    params = await session.client.waitFor("Debugger.paused", {
-      timeoutMs: options.timeoutMs,
-      predicate: (raw) => {
-        if (expected === void 0 || expected.length === 0) {
+    const remainingMs = remainingUntil(deadlineMs);
+    if (remainingMs <= 0) {
+      throwBreakpointTimeout(options.timeoutMs);
+    }
+    session.pauseWaitGate.active = true;
+    let receivedAtMs;
+    let params;
+    try {
+      params = await session.client.waitFor("Debugger.paused", {
+        timeoutMs: remainingMs,
+        predicate: () => {
+          receivedAtMs = performance.now();
           return true;
         }
-        const ids = Array.isArray(raw.hitBreakpoints) ? raw.hitBreakpoints.filter((id) => typeof id === "string") : [];
-        return ids.some((id) => expected.includes(id));
-      }
-    });
-  } finally {
-    session.pauseWaitGate.active = false;
+      });
+    } finally {
+      session.pauseWaitGate.active = false;
+    }
+    const pause = toPauseEvent(params, receivedAtMs ?? performance.now());
+    if (pauseMatches(pause, options.breakpointIds)) {
+      return pause;
+    }
+    await handleUnmatchedPause(session, pause, options, deadlineMs);
   }
-  return {
-    reason: asString(params.reason),
-    hitBreakpoints: Array.isArray(params.hitBreakpoints) ? params.hitBreakpoints.filter((id) => typeof id === "string") : [],
-    callFrames: toCallFrames(params.callFrames)
-  };
+  throwBreakpointTimeout(options.timeoutMs);
 }
 async function resume(session) {
   await session.client.send("Debugger.resume");
@@ -975,7 +1072,7 @@ var MAX_SCOPE_VARIABLES = 20;
 var MAX_CHILD_VARIABLES = 8;
 var MAX_VARIABLE_DEPTH = 2;
 var MAX_VALUE_LENGTH = 240;
-var SENSITIVE_NAME_REGEX = /(pass(?:word)?|token|secret|api[_-]?key|authorization|cookie|session|private[_-]?key)/i;
+var SENSITIVE_NAME_REGEX = /(pass(?:word)?|credentials?|creds?|token|secret|api[_-]?key|authorization|cookie|session|private[_-]?key)/i;
 var PRIORITY_BY_TYPE = {
   local: 0,
   arguments: 1,
@@ -1036,8 +1133,11 @@ function formatPrimitive(value) {
   }
   return String(value);
 }
+function isSensitiveName(name) {
+  return SENSITIVE_NAME_REGEX.test(name);
+}
 function sanitizeValue(name, raw) {
-  if (SENSITIVE_NAME_REGEX.test(name)) {
+  if (isSensitiveName(name)) {
     return "[REDACTED]";
   }
   if (raw.length <= MAX_VALUE_LENGTH) {
@@ -1055,8 +1155,9 @@ async function captureProperties(session, objectId, limit, depth) {
     limited.map(async (prop) => {
       const name = typeof prop.name === "string" ? prop.name : "?";
       const described = describeProperty(prop);
+      const sensitive = isSensitiveName(name);
       let children;
-      if (depth > 0 && described.objectId !== void 0 && isExpandable(described.type)) {
+      if (!sensitive && depth > 0 && described.objectId !== void 0 && isExpandable(described.type)) {
         try {
           const nested = await captureProperties(
             session,
@@ -1070,7 +1171,7 @@ async function captureProperties(session, objectId, limit, depth) {
         } catch {
         }
       }
-      const sanitizedValue = sanitizeValue(name, described.value);
+      const sanitizedValue = sensitive ? "[REDACTED]" : sanitizeValue(name, described.value);
       const base = { name, value: sanitizedValue };
       const withType = described.type === void 0 ? base : { ...base, type: described.type };
       return children === void 0 ? withType : { ...withType, children };
@@ -1248,7 +1349,82 @@ function parseCaptureList(raw) {
   if (raw === void 0 || raw.trim().length === 0) {
     return [];
   }
-  return raw.split(",").map((piece) => piece.trim()).filter((piece) => piece.length > 0);
+  return splitCaptureExpressions(raw);
+}
+function isQuoteChar(value) {
+  return value === "'" || value === '"' || value === "`";
+}
+function consumeQuotedChar(state, char) {
+  if (state.quote === void 0) {
+    return false;
+  }
+  if (state.escaped) {
+    state.escaped = false;
+    return true;
+  }
+  if (char === "\\") {
+    state.escaped = true;
+    return true;
+  }
+  if (char === state.quote) {
+    state.quote = void 0;
+  }
+  return true;
+}
+function updateCaptureDepth(state, char) {
+  if (char === "(") {
+    state.parenDepth += 1;
+  } else if (char === ")") {
+    state.parenDepth = Math.max(0, state.parenDepth - 1);
+  } else if (char === "[") {
+    state.bracketDepth += 1;
+  } else if (char === "]") {
+    state.bracketDepth = Math.max(0, state.bracketDepth - 1);
+  } else if (char === "{") {
+    state.braceDepth += 1;
+  } else if (char === "}") {
+    state.braceDepth = Math.max(0, state.braceDepth - 1);
+  }
+}
+function isTopLevel(state) {
+  return state.parenDepth === 0 && state.bracketDepth === 0 && state.braceDepth === 0;
+}
+function appendCapturePiece(raw, state, end) {
+  const piece = raw.slice(state.start, end).trim();
+  if (piece.length > 0) {
+    state.pieces.push(piece);
+  }
+}
+function splitCaptureExpressions(raw) {
+  const state = {
+    escaped: false,
+    parenDepth: 0,
+    bracketDepth: 0,
+    braceDepth: 0,
+    quote: void 0,
+    start: 0,
+    pieces: []
+  };
+  for (let idx = 0; idx < raw.length; idx += 1) {
+    const char = raw[idx];
+    if (char === void 0) {
+      continue;
+    }
+    if (consumeQuotedChar(state, char)) {
+      continue;
+    }
+    if (isQuoteChar(char)) {
+      state.quote = char;
+      continue;
+    }
+    updateCaptureDepth(state, char);
+    if (char === "," && isTopLevel(state)) {
+      appendCapturePiece(raw, state, idx);
+      state.start = idx + 1;
+    }
+  }
+  appendCapturePiece(raw, state, raw.length);
+  return state.pieces;
 }
 async function withSession(target, fn) {
   const tunnel = await openTarget(target);
@@ -1280,6 +1456,21 @@ function warnOnUnboundBreakpoints(handles) {
 function roundDurationMs(durationMs) {
   return Math.round(durationMs * 1e3) / 1e3;
 }
+function formatPauseLocation(pause) {
+  const top = pause.callFrames[0];
+  if (top === void 0) {
+    return "(no call frame)";
+  }
+  const url = top.url !== void 0 && top.url.length > 0 ? top.url : "(unknown)";
+  return `${url}:${(top.lineNumber + 1).toString()}:${(top.columnNumber + 1).toString()}`;
+}
+function warnOnUnmatchedPause(pause) {
+  const reason = pause.reason.length > 0 ? pause.reason : "unknown";
+  process.stderr.write(
+    `[cf-inspector] warning: target is paused by another debugger event (${reason} at ${formatPauseLocation(pause)}); waiting for it to resume...
+`
+  );
+}
 function withPausedDuration(snapshot, pausedDurationMs) {
   return {
     reason: snapshot.reason,
@@ -1291,7 +1482,7 @@ function withPausedDuration(snapshot, pausedDurationMs) {
   };
 }
 function writeHumanSnapshot(snapshot) {
-  const pausedDuration = snapshot.pausedDurationMs === null ? "still paused" : `${snapshot.pausedDurationMs.toFixed(1)}ms`;
+  const pausedDuration = snapshot.pausedDurationMs === null ? "unknown" : `${snapshot.pausedDurationMs.toFixed(1)}ms`;
   const lines = [];
   lines.push(
     `Snapshot @ ${snapshot.capturedAt}`,
@@ -1352,8 +1543,20 @@ async function handleSnapshot(opts) {
     );
     warnOnUnboundBreakpoints(handles);
     const breakpointIds = handles.map((h) => h.breakpointId);
-    const pause = await waitForPause(session, { timeoutMs, breakpointIds });
-    const pausedStartedAt = performance.now();
+    let warnedUnmatchedPause = false;
+    const pause = await waitForPause(session, {
+      timeoutMs,
+      breakpointIds,
+      unmatchedPausePolicy: opts.failOnUnmatchedPause === true ? "fail" : "wait-for-resume",
+      onUnmatchedPause: (unmatchedPause) => {
+        if (warnedUnmatchedPause || opts.failOnUnmatchedPause === true) {
+          return;
+        }
+        warnedUnmatchedPause = true;
+        warnOnUnmatchedPause(unmatchedPause);
+      }
+    });
+    const pausedStartedAt = pause.receivedAtMs ?? performance2.now();
     const snapshot = await captureSnapshot(session, pause, { captures });
     if (opts.keepPaused === true) {
       return withPausedDuration(snapshot, null);
@@ -1362,9 +1565,12 @@ async function handleSnapshot(opts) {
       await resume(session);
       return withPausedDuration(
         snapshot,
-        roundDurationMs(performance.now() - pausedStartedAt)
+        roundDurationMs(performance2.now() - pausedStartedAt)
       );
     } catch {
+      process.stderr.write(
+        "[cf-inspector] warning: Debugger.resume failed after snapshot; pausedDurationMs is unknown.\n"
+      );
       return withPausedDuration(snapshot, null);
     }
   });
@@ -1381,6 +1587,9 @@ async function handleEval(opts) {
   });
   if (opts.json) {
     writeJson(result);
+    if (result.exceptionDetails !== void 0) {
+      process.exitCode = 1;
+    }
     return;
   }
   if (result.exceptionDetails !== void 0) {
@@ -1518,10 +1727,10 @@ async function main(argv) {
     "Breakpoint location (repeatable; first hit wins), e.g. src/handler.ts:42",
     collectStrings,
     []
-  ).option("--capture <expr,\u2026>", "Comma-separated expressions to evaluate in the paused frame").option("--timeout <seconds>", "How long to wait for the breakpoint to hit (default: 30)").option("--remote-root <value>", "Path-mapping anchor: literal path or regex:<pattern> / /pattern/flags").option(
+  ).option("--capture <expr,\u2026>", "Top-level comma-separated expressions to evaluate in the paused frame").option("--timeout <seconds>", "How long to wait for the breakpoint to hit (default: 30)").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("--no-json", "Print a human-readable summary instead of JSON").option("--keep-paused", "Skip the auto-resume after capture").action(async (opts) => {
+  ).option("--no-json", "Print a human-readable summary instead of JSON").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);
   });
   applyTargetOptions(