@saptools/cf-inspector 0.3.18 → 0.4.0

package/dist/cli.js

@@ -110,7 +110,7 @@ var init_wsTransport = __esm({
 });
 
 // src/cli.ts
-import process8 from "process";
+import process10 from "process";
 
 // src/cli/program.ts
 import { Command } from "commander";
@@ -250,8 +250,11 @@ function writeHumanSnapshot(snapshot) {
     `  reason:  ${snapshot.reason}`,
     `  paused:  ${pausedDuration}`
   );
+  if (snapshot.exception !== void 0) {
+    appendExceptionLines(lines, snapshot.exception);
+  }
   if (snapshot.topFrame) {
-    appendFrameLines(lines, snapshot);
+    appendFrameLines(lines, snapshot.topFrame);
   }
   if (snapshot.captures.length > 0) {
     lines.push("  captures:");
@@ -260,14 +263,16 @@ function writeHumanSnapshot(snapshot) {
       lines.push(`    ${capture.expression} = ${detail}`);
     }
   }
+  if (snapshot.stack !== void 0 && snapshot.stack.length > 0) {
+    lines.push("  stack:");
+    for (const frame of snapshot.stack) {
+      appendStackFrameLine(lines, frame);
+    }
+  }
   process.stdout.write(`${lines.join("\n")}
 `);
 }
-function appendFrameLines(lines, snapshot) {
-  const frame = snapshot.topFrame;
-  if (frame === void 0) {
-    return;
-  }
+function appendFrameLines(lines, frame) {
   const fnName = frame.functionName.length === 0 ? "(anonymous)" : frame.functionName;
   const sourceUrl = frame.url !== void 0 && frame.url.length > 0 ? frame.url : "(unknown)";
   lines.push(
@@ -283,6 +288,25 @@ function appendFrameLines(lines, snapshot) {
     }
   }
 }
+function appendStackFrameLine(lines, frame) {
+  const fnName = frame.functionName.length === 0 ? "(anonymous)" : frame.functionName;
+  const sourceUrl = frame.url !== void 0 && frame.url.length > 0 ? frame.url : "(unknown)";
+  lines.push(`    ${fnName} ${sourceUrl}:${frame.line.toString()}:${frame.column.toString()}`);
+  if (frame.captures !== void 0) {
+    for (const capture of frame.captures) {
+      const detail = capture.error ?? capture.value ?? "undefined";
+      lines.push(`      ${capture.expression} = ${detail}`);
+    }
+  }
+}
+function appendExceptionLines(lines, exception) {
+  if (exception.error !== void 0) {
+    lines.push(`  exception: !err ${exception.error}`);
+    return;
+  }
+  const detail = exception.description ?? exception.value ?? "(unknown)";
+  lines.push(`  exception: ${detail}`);
+}
 function writeLogEvent(event, json) {
   if (json) {
     process.stdout.write(`${JSON.stringify(event)}
@@ -297,6 +321,25 @@ function writeLogEvent(event, json) {
   process.stdout.write(`[${event.ts}] ${event.at} ${event.value ?? ""}
 `);
 }
+function writeWatchEvent(event, json) {
+  if (json) {
+    process.stdout.write(`${JSON.stringify(event)}
+`);
+    return;
+  }
+  process.stdout.write(`[${event.ts}] hit#${event.hit.toString()} ${event.at}
+`);
+  if (event.exception !== void 0) {
+    const detail = event.exception.description ?? event.exception.value ?? event.exception.error ?? "(unknown)";
+    process.stdout.write(`  exception: ${detail}
+`);
+  }
+  for (const capture of event.captures) {
+    const detail = capture.error ?? capture.value ?? "undefined";
+    process.stdout.write(`  ${capture.expression} = ${detail}
+`);
+  }
+}
 
 // src/cf/tunnel.ts
 import { startDebugger } from "@saptools/cf-debugger";
@@ -557,6 +600,9 @@ function asString(value, fallback = "") {
 function asNumber(value, fallback = 0) {
   return typeof value === "number" && Number.isFinite(value) ? value : fallback;
 }
+function nonEmptyString(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
 function toResolvedLocations(value) {
   if (!Array.isArray(value)) {
     return [];
@@ -595,7 +641,18 @@ function toScopeChain(value) {
     return [objectId === void 0 ? base : { ...base, objectId }];
   });
 }
-function toCallFrames(value) {
+function resolveCallFrameUrl(frame, scripts) {
+  const direct = nonEmptyString(frame.url);
+  if (direct !== void 0) {
+    return direct;
+  }
+  const scriptId = nonEmptyString(frame.location?.scriptId);
+  if (scriptId === void 0) {
+    return void 0;
+  }
+  return nonEmptyString(scripts?.get(scriptId)?.url);
+}
+function toCallFrames(value, scripts) {
   if (!Array.isArray(value)) {
     return [];
   }
@@ -608,7 +665,7 @@ function toCallFrames(value) {
     if (callFrameId.length === 0) {
       return [];
     }
-    const url = typeof candidate.url === "string" ? candidate.url : void 0;
+    const url = resolveCallFrameUrl(candidate, scripts);
     const base = {
       callFrameId,
       functionName: asString(candidate.functionName),
@@ -619,13 +676,14 @@ function toCallFrames(value) {
     return [url === void 0 ? base : { ...base, url }];
   });
 }
-function toPauseEvent(params, receivedAtMs) {
-  return {
+function toPauseEvent(params, receivedAtMs, scripts) {
+  const base = {
     reason: asString(params.reason),
     hitBreakpoints: Array.isArray(params.hitBreakpoints) ? params.hitBreakpoints.filter((id) => typeof id === "string") : [],
-    callFrames: toCallFrames(params.callFrames),
+    callFrames: toCallFrames(params.callFrames, scripts),
     receivedAtMs
   };
+  return params.data === void 0 ? base : { ...base, data: params.data };
 }
 function topFrameLocation(pause) {
   const top = pause.callFrames[0];
@@ -677,7 +735,7 @@ async function connectInspector(options) {
       return;
     }
     const params = raw;
-    const event = toPauseEvent(params, performance.now());
+    const event = toPauseEvent(params, performance.now(), scripts);
     if (pauseBuffer.length >= PAUSE_BUFFER_LIMIT) {
       pauseBuffer.shift();
     }
@@ -711,6 +769,7 @@ init_types();
 // src/cli/commandTypes.ts
 var DEFAULT_BREAKPOINT_TIMEOUT_SEC = 30;
 var DEFAULT_CF_TIMEOUT_SEC = 60;
+var DEFAULT_EXCEPTION_TIMEOUT_SEC = 30;
 
 // src/cli/target.ts
 function parsePositiveInt(raw, label) {
@@ -813,6 +872,9 @@ init_types();
 async function resume(session) {
   await session.client.send("Debugger.resume");
 }
+async function setPauseOnExceptions(session, state) {
+  await session.client.send("Debugger.setPauseOnExceptions", { state });
+}
 async function evaluateOnFrame(session, callFrameId, expression) {
   return await session.client.send("Debugger.evaluateOnCallFrame", {
     callFrameId,
@@ -900,23 +962,9 @@ function writeHumanEvalResult(result) {
 `);
 }
 
-// src/cli/commands/listScripts.ts
-import process4 from "process";
-async function handleListScripts(opts) {
-  const target = resolveTarget(opts);
-  const scripts = await withSession(target, (session) => Promise.resolve(listScripts(session)));
-  if (opts.json) {
-    writeJson(scripts);
-    return;
-  }
-  for (const script of scripts) {
-    process4.stdout.write(`${script.scriptId}	${script.url}
-`);
-  }
-}
-
-// src/cli/commands/log.ts
-import process6 from "process";
+// src/cli/commands/exception.ts
+import { performance as performance3 } from "perf_hooks";
+import process5 from "process";
 
 // src/pathMapper.ts
 init_types();
@@ -1059,6 +1107,46 @@ function buildBreakpointUrlRegex(input) {
 
 // src/inspector/breakpoints.ts
 init_types();
+var HITS_GLOBAL = "globalThis.__CFI_HITS";
+var counterKeyCounter = 0;
+function nextCounterKey(file, line) {
+  counterKeyCounter += 1;
+  return `${file}:${line.toString()}:${counterKeyCounter.toString()}`;
+}
+function validateHitCount(hitCount) {
+  if (hitCount === void 0) {
+    return void 0;
+  }
+  if (!Number.isInteger(hitCount) || hitCount <= 0) {
+    throw new CfInspectorError(
+      "INVALID_HIT_COUNT",
+      `hitCount must be a positive integer, received: ${hitCount.toString()}`
+    );
+  }
+  return hitCount;
+}
+function buildHitCountedCondition(hitCount, counterKey, userCondition) {
+  const keyLiteral = JSON.stringify(counterKey);
+  const baseCondition = userCondition !== void 0 && userCondition.trim().length > 0 ? `(${userCondition})` : "true";
+  return [
+    "(function(){",
+    `var m=(${HITS_GLOBAL}=${HITS_GLOBAL}||{});`,
+    `var k=${keyLiteral};`,
+    "m[k]=(m[k]||0)+1;",
+    `if(m[k]<${hitCount.toString()})return false;`,
+    `return ${baseCondition};`,
+    "})()"
+  ].join("");
+}
+function resolveCondition(input) {
+  const condition = input.condition;
+  const hitCount = validateHitCount(input.hitCount);
+  if (hitCount === void 0) {
+    return condition !== void 0 && condition.length > 0 ? condition : void 0;
+  }
+  const counterKey = nextCounterKey(input.file, input.line);
+  return buildHitCountedCondition(hitCount, counterKey, condition);
+}
 async function setBreakpoint(session, input) {
   const remoteRoot = input.remoteRoot ?? { kind: "none" };
   const urlRegex = buildBreakpointUrlRegex({ file: input.file, remoteRoot });
@@ -1066,8 +1154,9 @@ async function setBreakpoint(session, input) {
     lineNumber: input.line - 1,
     urlRegex
   };
-  if (input.condition !== void 0 && input.condition.length > 0) {
-    params["condition"] = input.condition;
+  const condition = resolveCondition(input);
+  if (condition !== void 0) {
+    params["condition"] = condition;
   }
   const result = await session.client.send(
     "Debugger.setBreakpointByUrl",
@@ -1092,378 +1181,130 @@ async function removeBreakpoint(session, breakpointId) {
   await session.client.send("Debugger.removeBreakpoint", { breakpointId });
 }
 
-// src/logpoint/condition.ts
-import { randomBytes } from "crypto";
-var SENTINEL_PREFIX = "__CFI_LOG_";
-var SENTINEL_SUFFIX = "__";
-function buildLogpointCondition(sentinel, expression) {
-  return [
-    "(function(){",
-    `var s=${JSON.stringify(sentinel)};`,
-    "try{",
-    `var v=(${expression});`,
-    "var r=typeof v==='string'?v:JSON.stringify(v);",
-    "console.log(s, r);",
-    "}catch(e){",
-    "console.log(s, '!err:'+(e&&e.message?e.message:String(e)));",
-    "}",
-    "return false;",
-    "})()"
-  ].join("");
+// src/inspector/pause.ts
+init_types();
+import { performance as performance2 } from "perf_hooks";
+function pauseMatches(pause, breakpointIds, pauseReasons) {
+  if (pauseReasons !== void 0 && pauseReasons.length > 0) {
+    return pauseReasons.includes(pause.reason);
+  }
+  if (breakpointIds === void 0 || breakpointIds.length === 0) {
+    return true;
+  }
+  return pause.hitBreakpoints.some((id) => breakpointIds.includes(id));
 }
-function generateSentinel() {
-  return `${SENTINEL_PREFIX}${randomBytes(8).toString("hex")}${SENTINEL_SUFFIX}`;
+function remainingUntil(deadlineMs) {
+  return Math.max(0, deadlineMs - performance2.now());
 }
-
-// src/logpoint/events.ts
-function asString2(value) {
-  return typeof value === "string" ? value : void 0;
+function hasResumedSincePause(session, pause) {
+  const pauseAt = pause.receivedAtMs;
+  const resumedAt = session.debuggerState.lastResumedAtMs;
+  return pauseAt !== void 0 && resumedAt !== void 0 && resumedAt >= pauseAt;
 }
-function readArg(arg, index) {
-  if (typeof arg !== "object" || arg === null) {
-    return void 0;
+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 candidate = arg;
-  if (candidate.type === "string" && typeof candidate.value === "string") {
-    return candidate.value;
+  const remainingMs = remainingUntil(deadlineMs);
+  if (remainingMs <= 0) {
+    throwUnrelatedPauseTimeout(pause, timeoutMs);
   }
-  const isPrimitiveType = candidate.type === "number" || candidate.type === "boolean" || candidate.type === "bigint";
-  const isPrimitiveValue = typeof candidate.value === "number" || typeof candidate.value === "boolean" || typeof candidate.value === "bigint";
-  if (isPrimitiveType && isPrimitiveValue) {
-    return String(candidate.value);
+  try {
+    await session.client.waitFor("Debugger.resumed", { timeoutMs: remainingMs });
+    session.debuggerState.lastResumedAtMs = performance2.now();
+  } catch (err) {
+    if (err instanceof CfInspectorError && err.code === "BREAKPOINT_NOT_HIT") {
+      throwUnrelatedPauseTimeout(pause, timeoutMs);
+    }
+    throw err;
   }
-  return index === 0 ? void 0 : "";
 }
-function parseLogEvent(rawArgs, sentinel, location, timestamp) {
-  if (!Array.isArray(rawArgs) || rawArgs.length < 2) {
-    return void 0;
-  }
-  const tag = readArg(rawArgs[0], 0);
-  if (tag !== sentinel) {
-    return void 0;
+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)
+    );
   }
-  const payload = readArg(rawArgs[1], 1) ?? "";
-  const ts = new Date(typeof timestamp === "number" ? timestamp : Date.now()).toISOString();
-  const at = `${location.file}:${location.line.toString()}`;
-  if (payload.startsWith("!err:")) {
-    return { ts, at, error: payload.slice("!err:".length) };
+  if (hasResumedSincePause(session, pause)) {
+    return;
   }
-  return parsePayload(ts, at, payload);
+  options.onUnmatchedPause?.(pause);
+  await waitForUnmatchedPauseToResume(session, pause, deadlineMs, options.timeoutMs);
 }
-function parsePayload(ts, at, payload) {
-  try {
-    const parsed = JSON.parse(payload);
-    if (typeof parsed === "string") {
-      return { ts, at, value: parsed };
+async function waitForPause(session, options) {
+  const deadlineMs = performance2.now() + options.timeoutMs;
+  const buffer = session.pauseBuffer;
+  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, options.pauseReasons)) {
+        return buffered;
+      }
+      await handleUnmatchedPause(session, buffered, options, deadlineMs);
     }
-    return { ts, at, value: JSON.stringify(parsed) };
-  } catch {
-    return { ts, at, value: payload, raw: payload };
+    const pause = await waitForLivePause(session, options, deadlineMs);
+    if (pauseMatches(pause, options.breakpointIds, options.pauseReasons)) {
+      return pause;
+    }
+    await handleUnmatchedPause(session, pause, options, deadlineMs);
   }
+  throwBreakpointTimeout(options.timeoutMs);
 }
-
-// src/logpoint/stream.ts
-async function streamLogpoint(session, options) {
-  const sentinel = generateSentinel();
-  const condition = buildLogpointCondition(sentinel, options.expression);
-  let emitted = 0;
-  const offEvent = session.client.on("Runtime.consoleAPICalled", (raw) => {
-    const event = toLogpointEvent(raw, sentinel, options.location);
-    if (event === void 0) {
-      return;
-    }
-    emitted += 1;
-    options.onEvent(event);
-  });
-  let handle;
-  try {
-    handle = await setBreakpoint(session, {
-      file: options.location.file,
-      line: options.location.line,
-      ...options.remoteRoot === void 0 ? {} : { remoteRoot: options.remoteRoot },
-      condition
-    });
-  } catch (err) {
-    offEvent();
-    throw err;
+async function waitForLivePause(session, options, deadlineMs) {
+  const remainingMs = remainingUntil(deadlineMs);
+  if (remainingMs <= 0) {
+    throwBreakpointTimeout(options.timeoutMs);
   }
-  options.onBreakpointSet?.(handle);
+  session.pauseWaitGate.active = true;
+  let receivedAtMs;
+  let params;
   try {
-    const reason = await waitForStop(session, options);
-    return { handle, sentinel, emitted, stoppedReason: reason };
+    params = await session.client.waitFor("Debugger.paused", {
+      timeoutMs: remainingMs,
+      predicate: () => {
+        receivedAtMs = performance2.now();
+        return true;
+      }
+    });
   } finally {
-    offEvent();
-    await removeBreakpointBestEffort(session, handle.breakpointId);
+    session.pauseWaitGate.active = false;
   }
+  return toPauseEvent(params, receivedAtMs ?? performance2.now(), session.scripts);
 }
-function toLogpointEvent(raw, sentinel, location) {
-  const params = raw;
-  if (asString2(params.type) !== "log") {
-    return void 0;
-  }
-  const ts = typeof params.timestamp === "number" ? params.timestamp : void 0;
-  return parseLogEvent(params.args, sentinel, location, ts);
+
+// src/snapshot/values.ts
+init_types();
+var DEFAULT_MAX_VALUE_LENGTH = 4096;
+function isPrimitive(value) {
+  const t = typeof value;
+  return t === "string" || t === "number" || t === "boolean" || t === "bigint" || t === "symbol";
 }
-async function removeBreakpointBestEffort(session, breakpointId) {
-  try {
-    await removeBreakpoint(session, breakpointId);
-  } catch {
+function formatPrimitive(value) {
+  if (typeof value === "symbol") {
+    return value.toString();
   }
-}
-async function waitForStop(session, options) {
-  return await new Promise((resolve) => {
-    let settled = false;
-    const finish = (reason) => {
-      if (settled) {
-        return;
-      }
-      settled = true;
-      cleanup();
-      resolve(reason);
-    };
-    const timer = options.durationMs === void 0 ? void 0 : setTimeout(() => {
-      finish("duration");
-    }, options.durationMs);
-    const offClose = session.client.onClose(() => {
-      finish("transport-closed");
-    });
-    const onAbort = () => {
-      finish("signal");
-    };
-    options.signal?.addEventListener("abort", onAbort, { once: true });
-    if (options.signal?.aborted === true) {
-      finish("signal");
-    }
-    function cleanup() {
-      if (timer !== void 0) {
-        clearTimeout(timer);
-      }
-      offClose();
-      options.signal?.removeEventListener("abort", onAbort);
-    }
-  });
-}
-
-// src/cli/commands/log.ts
-init_types();
-
-// src/cli/warnings.ts
-import process5 from "process";
-function warnOnUnboundBreakpoints(handles) {
-  for (const handle of handles) {
-    if (handle.resolvedLocations.length === 0) {
-      process5.stderr.write(
-        `[cf-inspector] warning: breakpoint ${handle.file}:${handle.line.toString()} did not bind to any loaded script. Check the path or pass --remote-root. Use 'list-scripts' to inspect what V8 currently has loaded.
-`
-      );
-    }
-  }
-}
-function roundDurationMs(durationMs) {
-  return Math.round(durationMs * 1e3) / 1e3;
-}
-function warnOnUnmatchedPause(pause) {
-  const reason = pause.reason.length > 0 ? pause.reason : "unknown";
-  process5.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,
-    hitBreakpoints: snapshot.hitBreakpoints,
-    capturedAt: snapshot.capturedAt,
-    pausedDurationMs,
-    ...snapshot.topFrame === void 0 ? {} : { topFrame: snapshot.topFrame },
-    captures: snapshot.captures
-  };
-}
-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()}`;
-}
-
-// src/cli/commands/log.ts
-async function handleLog(opts) {
-  const target = resolveTarget(opts);
-  const location = parseBreakpointSpec(opts.at);
-  const remoteRoot = parseRemoteRoot(opts.remoteRoot);
-  const durationSec = parsePositiveInt(opts.duration, "--duration");
-  const expression = opts.expr.trim();
-  if (expression.length === 0) {
-    throw new CfInspectorError("INVALID_BREAKPOINT", "--expr must not be empty");
-  }
-  const abort = new AbortController();
-  const onSig = () => {
-    abort.abort();
-  };
-  process6.once("SIGINT", onSig);
-  process6.once("SIGTERM", onSig);
-  try {
-    await withSession(target, async (session) => {
-      await validateExpression(session, expression);
-      const result = await streamLogpoint(session, {
-        location,
-        expression,
-        remoteRoot,
-        ...durationSec === void 0 ? {} : { durationMs: durationSec * 1e3 },
-        signal: abort.signal,
-        onEvent: (event) => {
-          writeLogEvent(event, opts.json);
-        },
-        onBreakpointSet: (handle) => {
-          warnOnUnboundBreakpoints([handle]);
-        }
-      });
-      writeLogSummary(result.stoppedReason, result.emitted, opts.json);
-    });
-  } finally {
-    process6.off("SIGINT", onSig);
-    process6.off("SIGTERM", onSig);
-  }
-}
-function writeLogSummary(stoppedReason, emitted, json) {
-  if (json) {
-    process6.stderr.write(`${JSON.stringify({ stopped: stoppedReason, emitted })}
-`);
-    return;
-  }
-  process6.stderr.write(
-    `Stopped (${stoppedReason}); emitted ${emitted.toString()} log ${emitted === 1 ? "entry" : "entries"}.
-`
-  );
-}
-
-// src/cli/commands/snapshot.ts
-import { performance as performance3 } from "perf_hooks";
-import process7 from "process";
-
-// src/inspector/pause.ts
-init_types();
-import { performance as performance2 } from "perf_hooks";
-function pauseMatches(pause, breakpointIds) {
-  if (breakpointIds === void 0 || breakpointIds.length === 0) {
-    return true;
-  }
-  return pause.hitBreakpoints.some((id) => breakpointIds.includes(id));
-}
-function remainingUntil(deadlineMs) {
-  return Math.max(0, deadlineMs - performance2.now());
-}
-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 = performance2.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 = performance2.now() + options.timeoutMs;
-  const buffer = session.pauseBuffer;
-  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);
-    }
-    const pause = await waitForLivePause(session, options, deadlineMs);
-    if (pauseMatches(pause, options.breakpointIds)) {
-      return pause;
-    }
-    await handleUnmatchedPause(session, pause, options, deadlineMs);
-  }
-  throwBreakpointTimeout(options.timeoutMs);
-}
-async function waitForLivePause(session, options, deadlineMs) {
-  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 = performance2.now();
-        return true;
-      }
-    });
-  } finally {
-    session.pauseWaitGate.active = false;
-  }
-  return toPauseEvent(params, receivedAtMs ?? performance2.now());
-}
-
-// src/snapshot/values.ts
-init_types();
-var DEFAULT_MAX_VALUE_LENGTH = 4096;
-function isPrimitive(value) {
-  const t = typeof value;
-  return t === "string" || t === "number" || t === "boolean" || t === "bigint" || t === "symbol";
-}
-function formatPrimitive(value) {
-  if (typeof value === "symbol") {
-    return value.toString();
-  }
-  if (typeof value === "bigint") {
-    return `${value.toString()}n`;
-  }
-  return String(value);
+  if (typeof value === "bigint") {
+    return `${value.toString()}n`;
+  }
+  return String(value);
 }
 function resolveMaxValueLength(value) {
   if (value === void 0) {
@@ -1665,19 +1506,11 @@ async function capturePropertyChildren(session, described, depth, maxValueLength
   }
 }
 
-// src/snapshot/objects.ts
-function objectIdFromEvalResult(result) {
-  const inner = result.result;
-  if (inner?.type !== "object") {
-    return void 0;
-  }
-  const objectId = inner.objectId;
-  if (typeof objectId !== "string" || objectId.length === 0) {
-    return void 0;
-  }
-  return objectId;
+// src/snapshot/exception.ts
+function asString2(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
 }
-async function renderObjectCapture(session, objectId, maxValueLength) {
+async function materializeObject(session, objectId, maxValueLength) {
   try {
     const properties = await captureProperties(
       session,
@@ -1686,6 +1519,9 @@ async function renderObjectCapture(session, objectId, maxValueLength) {
       MAX_VARIABLE_DEPTH,
       maxValueLength
     );
+    if (properties.length === 0) {
+      return void 0;
+    }
     const structured = {};
     for (const variable of properties) {
       structured[variable.name] = toStructuredValue(variable);
@@ -1695,7 +1531,99 @@ async function renderObjectCapture(session, objectId, maxValueLength) {
     return void 0;
   }
 }
-function normalizeRenderedObjectCapture(rendered, original) {
+async function readPropertyDescription(session, objectId, name) {
+  try {
+    const properties = await getProperties(session, objectId);
+    for (const prop of properties) {
+      if (prop.name !== name) {
+        continue;
+      }
+      const value = prop.value;
+      if (value === void 0) {
+        continue;
+      }
+      if (typeof value.value === "string") {
+        return value.value;
+      }
+      if (typeof value.description === "string") {
+        return value.description;
+      }
+    }
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
+async function captureException(session, pause, maxValueLength) {
+  if (pause.reason !== "exception" && pause.reason !== "promiseRejection") {
+    return void 0;
+  }
+  const data = pause.data;
+  if (typeof data !== "object" || data === null) {
+    return { error: "no exception data attached" };
+  }
+  const candidate = data;
+  const type = asString2(candidate.type);
+  const description = asString2(candidate.description);
+  if (typeof candidate.value === "string") {
+    return buildResult(type, description, JSON.stringify(candidate.value), maxValueLength);
+  }
+  if (typeof candidate.value === "number" || typeof candidate.value === "boolean") {
+    return buildResult(type, description, String(candidate.value), maxValueLength);
+  }
+  const objectId = asString2(candidate.objectId);
+  if (objectId === void 0) {
+    if (description !== void 0) {
+      return buildResult(type, description, description, maxValueLength);
+    }
+    return { error: "exception data has no objectId or value" };
+  }
+  const message = await readPropertyDescription(session, objectId, "message");
+  const rendered = await materializeObject(session, objectId, maxValueLength);
+  if (rendered !== void 0) {
+    const result = buildResult(type, description, rendered, maxValueLength);
+    return message === void 0 ? result : { ...result, description: limitValueLength(message, maxValueLength) };
+  }
+  return buildResult(type, description, description ?? "[exception]", maxValueLength);
+}
+function buildResult(type, description, value, maxValueLength) {
+  const safeValue = limitValueLength(value, maxValueLength);
+  const base = { value: safeValue };
+  const withType = type === void 0 ? base : { ...base, type };
+  return description === void 0 ? withType : { ...withType, description: limitValueLength(description, maxValueLength) };
+}
+
+// src/snapshot/objects.ts
+function objectIdFromEvalResult(result) {
+  const inner = result.result;
+  if (inner?.type !== "object") {
+    return void 0;
+  }
+  const objectId = inner.objectId;
+  if (typeof objectId !== "string" || objectId.length === 0) {
+    return void 0;
+  }
+  return objectId;
+}
+async function renderObjectCapture(session, objectId, maxValueLength) {
+  try {
+    const properties = await captureProperties(
+      session,
+      objectId,
+      MAX_SCOPE_VARIABLES,
+      MAX_VARIABLE_DEPTH,
+      maxValueLength
+    );
+    const structured = {};
+    for (const variable of properties) {
+      structured[variable.name] = toStructuredValue(variable);
+    }
+    return JSON.stringify(structured);
+  } catch {
+    return void 0;
+  }
+}
+function normalizeRenderedObjectCapture(rendered, original) {
   if (rendered === "{}" && original !== "Object") {
     return void 0;
   }
@@ -1767,12 +1695,73 @@ async function captureScopes(session, frame, maxValueLength) {
   );
 }
 
+// src/snapshot/stack.ts
+var DEFAULT_STACK_DEPTH = 1;
+var MAX_STACK_DEPTH = 64;
+function clampDepth(depth, frameCount) {
+  if (depth <= 0) {
+    return 0;
+  }
+  return Math.min(depth, frameCount, MAX_STACK_DEPTH);
+}
+function buildBaseFrame(frame) {
+  const base = {
+    functionName: frame.functionName,
+    line: frame.lineNumber + 1,
+    column: frame.columnNumber + 1
+  };
+  return frame.url === void 0 ? base : { ...base, url: frame.url };
+}
+async function captureFrameExpression(session, callFrameId, expression, maxValueLength) {
+  try {
+    const result = await evaluateOnFrame(session, callFrameId, expression);
+    const captured = evalResultToCaptured(expression, result, maxValueLength);
+    return await withSerializedObjectCapture(session, expression, result, captured, maxValueLength);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { expression, error: limitValueLength(message, maxValueLength) };
+  }
+}
+async function captureFrameExpressions(session, frame, expressions, maxValueLength) {
+  if (expressions.length === 0) {
+    return [];
+  }
+  return await Promise.all(
+    expressions.map(
+      (expression) => captureFrameExpression(session, frame.callFrameId, expression, maxValueLength)
+    )
+  );
+}
+async function walkStack(session, callFrames, options) {
+  const depth = clampDepth(options.stackDepth, callFrames.length);
+  if (depth <= 1) {
+    return [];
+  }
+  const slice = callFrames.slice(0, depth);
+  return await Promise.all(
+    slice.map(async (frame) => {
+      const base = buildBaseFrame(frame);
+      if (options.stackCaptures.length === 0) {
+        return base;
+      }
+      const captures = await captureFrameExpressions(
+        session,
+        frame,
+        options.stackCaptures,
+        options.maxValueLength
+      );
+      return { ...base, captures };
+    })
+  );
+}
+
 // src/snapshot/capture.ts
 async function captureSnapshot(session, pause, options = {}) {
   const maxValueLength = resolveMaxValueLength(options.maxValueLength);
   const top = pause.callFrames[0];
   let topFrame;
   let captures = [];
+  let stack = [];
   if (top) {
     topFrame = {
       functionName: top.functionName,
@@ -1785,14 +1774,31 @@ async function captureSnapshot(session, pause, options = {}) {
       topFrame = { ...topFrame, scopes };
     }
     captures = await captureExpressions(session, top.callFrameId, options.captures, maxValueLength);
+    stack = await walkStack(session, pause.callFrames, {
+      stackDepth: options.stackDepth ?? DEFAULT_STACK_DEPTH,
+      stackCaptures: options.stackCaptures ?? [],
+      maxValueLength
+    });
   }
-  return {
-    reason: pause.reason,
-    hitBreakpoints: pause.hitBreakpoints,
+  const exception = await captureException(session, pause, maxValueLength);
+  return buildResult2({
+    pause,
+    topFrame,
+    captures,
+    stack,
+    exception
+  });
+}
+function buildResult2(input) {
+  const base = {
+    reason: input.pause.reason,
+    hitBreakpoints: input.pause.hitBreakpoints,
     capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    ...topFrame === void 0 ? {} : { topFrame },
-    captures
+    captures: input.captures
   };
+  const withFrame = input.topFrame === void 0 ? base : { ...base, topFrame: input.topFrame };
+  const withStack = input.stack.length > 0 ? { ...withFrame, stack: input.stack } : withFrame;
+  return input.exception === void 0 ? withStack : { ...withStack, exception: input.exception };
 }
 async function captureExpressions(session, callFrameId, captures, maxValueLength) {
   if (captures === void 0 || captures.length === 0) {
@@ -1815,7 +1821,7 @@ async function captureExpression(session, callFrameId, expression, maxValueLengt
   }
 }
 
-// src/cli/commands/snapshot.ts
+// src/cli/commands/exception.ts
 init_types();
 
 // src/cli/captureParser.ts
@@ -1898,7 +1904,450 @@ function splitCaptureExpressions(raw) {
   return state.pieces;
 }
 
+// src/cli/warnings.ts
+import process4 from "process";
+function warnOnUnboundBreakpoints(handles) {
+  for (const handle of handles) {
+    if (handle.resolvedLocations.length === 0) {
+      process4.stderr.write(
+        `[cf-inspector] warning: breakpoint ${handle.file}:${handle.line.toString()} did not bind to any loaded script. Check the path or pass --remote-root. Use 'list-scripts' to inspect what V8 currently has loaded.
+`
+      );
+    }
+  }
+}
+function roundDurationMs(durationMs) {
+  return Math.round(durationMs * 1e3) / 1e3;
+}
+function warnOnUnmatchedPause(pause) {
+  const reason = pause.reason.length > 0 ? pause.reason : "unknown";
+  process4.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) {
+  const base = {
+    reason: snapshot.reason,
+    hitBreakpoints: snapshot.hitBreakpoints,
+    capturedAt: snapshot.capturedAt,
+    pausedDurationMs,
+    captures: snapshot.captures
+  };
+  const withFrame = snapshot.topFrame === void 0 ? base : { ...base, topFrame: snapshot.topFrame };
+  const withStack = snapshot.stack === void 0 ? withFrame : { ...withFrame, stack: snapshot.stack };
+  return snapshot.exception === void 0 ? withStack : { ...withStack, exception: snapshot.exception };
+}
+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()}`;
+}
+
+// src/cli/commands/exception.ts
+var VALID_PAUSE_TYPES = ["uncaught", "caught", "all"];
+async function handleException(opts) {
+  const prepared = prepareExceptionCommand(opts);
+  const result = await runExceptionCommand(prepared, opts);
+  if (opts.json) {
+    writeJson(result);
+  } else {
+    writeHumanSnapshot(result);
+  }
+}
+function prepareExceptionCommand(opts) {
+  const target = resolveTarget(opts);
+  const stateRaw = (opts.type ?? "uncaught").trim().toLowerCase();
+  if (!VALID_PAUSE_TYPES.includes(stateRaw)) {
+    throw new CfInspectorError(
+      "INVALID_PAUSE_TYPE",
+      `--type must be one of ${VALID_PAUSE_TYPES.join(", ")} (received "${stateRaw}")`
+    );
+  }
+  const timeoutSec = parsePositiveInt(opts.timeout, "--timeout") ?? DEFAULT_EXCEPTION_TIMEOUT_SEC;
+  const maxValueLength = parsePositiveInt(opts.maxValueLength, "--max-value-length");
+  const stackDepth = parsePositiveInt(opts.stackDepth, "--stack-depth");
+  return {
+    target,
+    state: stateRaw,
+    captures: parseCaptureList(opts.capture),
+    remoteRoot: parseRemoteRoot(opts.remoteRoot),
+    timeoutMs: timeoutSec * 1e3,
+    ...maxValueLength === void 0 ? {} : { maxValueLength },
+    ...stackDepth === void 0 ? {} : { stackDepth },
+    stackCaptures: parseCaptureList(opts.stackCaptures)
+  };
+}
+async function runExceptionCommand(command, opts) {
+  return await withSession(command.target, async (session) => {
+    await setPauseOnExceptions(session, command.state);
+    try {
+      const pause = await waitForPause(session, {
+        timeoutMs: command.timeoutMs,
+        pauseReasons: ["exception", "promiseRejection"],
+        unmatchedPausePolicy: "wait-for-resume"
+      });
+      const pausedStartedAt = pause.receivedAtMs ?? performance3.now();
+      const snapshot = await captureSnapshot(session, pause, {
+        captures: command.captures,
+        includeScopes: opts.includeScopes === true,
+        ...command.maxValueLength === void 0 ? {} : { maxValueLength: command.maxValueLength },
+        ...command.stackDepth === void 0 ? {} : { stackDepth: command.stackDepth },
+        stackCaptures: command.stackCaptures
+      });
+      if (opts.keepPaused === true) {
+        return withPausedDuration(snapshot, null);
+      }
+      return await resumeAfterException(session, snapshot, pausedStartedAt);
+    } finally {
+      await disablePauseOnExceptionsBestEffort(session);
+    }
+  });
+}
+async function resumeAfterException(session, snapshot, pausedStartedAt) {
+  try {
+    await resume(session);
+    return withPausedDuration(snapshot, roundDurationMs(performance3.now() - pausedStartedAt));
+  } catch {
+    process5.stderr.write(
+      "[cf-inspector] warning: Debugger.resume failed after exception capture; pausedDurationMs is unknown.\n"
+    );
+    return withPausedDuration(snapshot, null);
+  }
+}
+async function disablePauseOnExceptionsBestEffort(session) {
+  try {
+    await setPauseOnExceptions(session, "none");
+  } catch {
+  }
+}
+
+// src/cli/commands/listScripts.ts
+import process6 from "process";
+async function handleListScripts(opts) {
+  const target = resolveTarget(opts);
+  const scripts = await withSession(target, (session) => Promise.resolve(listScripts(session)));
+  if (opts.json) {
+    writeJson(scripts);
+    return;
+  }
+  for (const script of scripts) {
+    process6.stdout.write(`${script.scriptId}	${script.url}
+`);
+  }
+}
+
+// src/cli/commands/log.ts
+import process7 from "process";
+
+// src/logpoint/stream.ts
+init_types();
+
+// src/logpoint/condition.ts
+import { randomBytes } from "crypto";
+var SENTINEL_PREFIX = "__CFI_LOG_";
+var SENTINEL_SUFFIX = "__";
+var HITS_GLOBAL2 = "globalThis.__CFI_LOG_HITS";
+function buildLoggingIife(sentinel, expression) {
+  return [
+    "(function(){",
+    `var s=${JSON.stringify(sentinel)};`,
+    "try{",
+    `var v=(${expression});`,
+    "var r=typeof v==='string'?v:JSON.stringify(v);",
+    "console.log(s, r);",
+    "}catch(e){",
+    "console.log(s, '!err:'+(e&&e.message?e.message:String(e)));",
+    "}",
+    "return false;",
+    "})()"
+  ].join("");
+}
+function buildHitGate(hitCount, counterKey) {
+  const keyLiteral = JSON.stringify(counterKey);
+  return [
+    "(function(){",
+    `var m=(${HITS_GLOBAL2}=${HITS_GLOBAL2}||{});`,
+    `var k=${keyLiteral};`,
+    "m[k]=(m[k]||0)+1;",
+    `return m[k]>=${hitCount.toString()};`,
+    "})()"
+  ].join("");
+}
+function combineGuards(guards) {
+  const filtered = guards.filter((guard) => guard.length > 0);
+  if (filtered.length === 0) {
+    return void 0;
+  }
+  if (filtered.length === 1) {
+    return filtered[0];
+  }
+  return filtered.map((guard) => `(${guard})`).join("&&");
+}
+function buildLogpointCondition(sentinel, expression, options = {}) {
+  const guards = [];
+  if (options.hitCount !== void 0) {
+    const counterKey = options.counterKey ?? sentinel;
+    guards.push(buildHitGate(options.hitCount, counterKey));
+  }
+  const userPredicate = options.predicate?.trim();
+  if (userPredicate !== void 0 && userPredicate.length > 0) {
+    guards.push(`(${userPredicate})`);
+  }
+  const iife = buildLoggingIife(sentinel, expression);
+  const guard = combineGuards(guards);
+  if (guard === void 0) {
+    return iife;
+  }
+  return `(${guard})?${iife}:false`;
+}
+function generateSentinel() {
+  return `${SENTINEL_PREFIX}${randomBytes(8).toString("hex")}${SENTINEL_SUFFIX}`;
+}
+
+// src/logpoint/events.ts
+function asString3(value) {
+  return typeof value === "string" ? value : void 0;
+}
+function readArg(arg, index) {
+  if (typeof arg !== "object" || arg === null) {
+    return void 0;
+  }
+  const candidate = arg;
+  if (candidate.type === "string" && typeof candidate.value === "string") {
+    return candidate.value;
+  }
+  const isPrimitiveType = candidate.type === "number" || candidate.type === "boolean" || candidate.type === "bigint";
+  const isPrimitiveValue = typeof candidate.value === "number" || typeof candidate.value === "boolean" || typeof candidate.value === "bigint";
+  if (isPrimitiveType && isPrimitiveValue) {
+    return String(candidate.value);
+  }
+  return index === 0 ? void 0 : "";
+}
+function parseLogEvent(rawArgs, sentinel, location, timestamp) {
+  if (!Array.isArray(rawArgs) || rawArgs.length < 2) {
+    return void 0;
+  }
+  const tag = readArg(rawArgs[0], 0);
+  if (tag !== sentinel) {
+    return void 0;
+  }
+  const payload = readArg(rawArgs[1], 1) ?? "";
+  const ts = new Date(typeof timestamp === "number" ? timestamp : Date.now()).toISOString();
+  const at = `${location.file}:${location.line.toString()}`;
+  if (payload.startsWith("!err:")) {
+    return { ts, at, error: payload.slice("!err:".length) };
+  }
+  return parsePayload(ts, at, payload);
+}
+function parsePayload(ts, at, payload) {
+  try {
+    const parsed = JSON.parse(payload);
+    if (typeof parsed === "string") {
+      return { ts, at, value: parsed };
+    }
+    return { ts, at, value: JSON.stringify(parsed) };
+  } catch {
+    return { ts, at, value: payload, raw: payload };
+  }
+}
+
+// src/logpoint/stream.ts
+function validateMaxEvents(maxEvents) {
+  if (maxEvents === void 0) {
+    return void 0;
+  }
+  if (!Number.isInteger(maxEvents) || maxEvents <= 0) {
+    throw new CfInspectorError(
+      "INVALID_ARGUMENT",
+      `maxEvents must be a positive integer, received: ${maxEvents.toString()}`
+    );
+  }
+  return maxEvents;
+}
+function validateHitCount2(hitCount) {
+  if (hitCount === void 0) {
+    return void 0;
+  }
+  if (!Number.isInteger(hitCount) || hitCount <= 0) {
+    throw new CfInspectorError(
+      "INVALID_HIT_COUNT",
+      `hitCount must be a positive integer, received: ${hitCount.toString()}`
+    );
+  }
+  return hitCount;
+}
+async function streamLogpoint(session, options) {
+  const maxEvents = validateMaxEvents(options.maxEvents);
+  const hitCount = validateHitCount2(options.hitCount);
+  const sentinel = generateSentinel();
+  const condition = buildLogpointCondition(sentinel, options.expression, {
+    ...options.condition === void 0 ? {} : { predicate: options.condition },
+    ...hitCount === void 0 ? {} : { hitCount }
+  });
+  let emitted = 0;
+  let maxEventsReached = false;
+  let stopMaxEvents;
+  const offEvent = session.client.on("Runtime.consoleAPICalled", (raw) => {
+    if (maxEventsReached) {
+      return;
+    }
+    const event = toLogpointEvent(raw, sentinel, options.location);
+    if (event === void 0) {
+      return;
+    }
+    emitted += 1;
+    options.onEvent(event);
+    if (maxEvents !== void 0 && emitted >= maxEvents) {
+      maxEventsReached = true;
+      stopMaxEvents?.();
+    }
+  });
+  let handle;
+  try {
+    handle = await setBreakpoint(session, {
+      file: options.location.file,
+      line: options.location.line,
+      ...options.remoteRoot === void 0 ? {} : { remoteRoot: options.remoteRoot },
+      condition
+    });
+  } catch (err) {
+    offEvent();
+    throw err;
+  }
+  options.onBreakpointSet?.(handle);
+  try {
+    const reason = await waitForStop(session, options, (signal) => {
+      stopMaxEvents = signal;
+      if (maxEventsReached) {
+        signal();
+      }
+    });
+    return { handle, sentinel, emitted, stoppedReason: reason };
+  } finally {
+    offEvent();
+    await removeBreakpointBestEffort(session, handle.breakpointId);
+  }
+}
+function toLogpointEvent(raw, sentinel, location) {
+  const params = raw;
+  if (asString3(params.type) !== "log") {
+    return void 0;
+  }
+  const ts = typeof params.timestamp === "number" ? params.timestamp : void 0;
+  return parseLogEvent(params.args, sentinel, location, ts);
+}
+async function removeBreakpointBestEffort(session, breakpointId) {
+  try {
+    await removeBreakpoint(session, breakpointId);
+  } catch {
+  }
+}
+async function waitForStop(session, options, registerMaxEventsSignal) {
+  return await new Promise((resolve) => {
+    let settled = false;
+    const finish = (reason) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      cleanup();
+      resolve(reason);
+    };
+    const timer = options.durationMs === void 0 ? void 0 : setTimeout(() => {
+      finish("duration");
+    }, options.durationMs);
+    const offClose = session.client.onClose(() => {
+      finish("transport-closed");
+    });
+    const onAbort = () => {
+      finish("signal");
+    };
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+    if (options.signal?.aborted === true) {
+      finish("signal");
+    }
+    registerMaxEventsSignal(() => {
+      finish("max-events");
+    });
+    function cleanup() {
+      if (timer !== void 0) {
+        clearTimeout(timer);
+      }
+      offClose();
+      options.signal?.removeEventListener("abort", onAbort);
+    }
+  });
+}
+
+// src/cli/commands/log.ts
+init_types();
+async function handleLog(opts) {
+  const target = resolveTarget(opts);
+  const location = parseBreakpointSpec(opts.at);
+  const remoteRoot = parseRemoteRoot(opts.remoteRoot);
+  const durationSec = parsePositiveInt(opts.duration, "--duration");
+  const maxEvents = parsePositiveInt(opts.maxEvents, "--max-events");
+  const hitCount = parsePositiveInt(opts.hitCount, "--hit-count");
+  const expression = opts.expr.trim();
+  if (expression.length === 0) {
+    throw new CfInspectorError("INVALID_EXPRESSION", "--expr must not be empty");
+  }
+  const condition = opts.condition !== void 0 && opts.condition.trim().length > 0 ? opts.condition.trim() : void 0;
+  const abort = new AbortController();
+  const onSig = () => {
+    abort.abort();
+  };
+  process7.once("SIGINT", onSig);
+  process7.once("SIGTERM", onSig);
+  try {
+    await withSession(target, async (session) => {
+      await validateExpression(session, expression);
+      if (condition !== void 0) {
+        await validateExpression(session, condition);
+      }
+      const result = await streamLogpoint(session, {
+        location,
+        expression,
+        remoteRoot,
+        ...durationSec === void 0 ? {} : { durationMs: durationSec * 1e3 },
+        ...maxEvents === void 0 ? {} : { maxEvents },
+        ...hitCount === void 0 ? {} : { hitCount },
+        ...condition === void 0 ? {} : { condition },
+        signal: abort.signal,
+        onEvent: (event) => {
+          writeLogEvent(event, opts.json);
+        },
+        onBreakpointSet: (handle) => {
+          warnOnUnboundBreakpoints([handle]);
+        }
+      });
+      writeLogSummary(result.stoppedReason, result.emitted, opts.json);
+    });
+  } finally {
+    process7.off("SIGINT", onSig);
+    process7.off("SIGTERM", onSig);
+  }
+}
+function writeLogSummary(stoppedReason, emitted, json) {
+  if (json) {
+    process7.stderr.write(`${JSON.stringify({ stopped: stoppedReason, emitted })}
+`);
+    return;
+  }
+  process7.stderr.write(
+    `Stopped (${stoppedReason}); emitted ${emitted.toString()} log ${emitted === 1 ? "entry" : "entries"}.
+`
+  );
+}
+
 // src/cli/commands/snapshot.ts
+import { performance as performance4 } from "perf_hooks";
+import process8 from "process";
+init_types();
 async function handleSnapshot(opts) {
   const prepared = prepareSnapshotCommand(opts);
   const result = await runSnapshotCommand(prepared, opts);
@@ -1919,6 +2368,8 @@ function prepareSnapshotCommand(opts) {
   const timeoutSec = parsePositiveInt(opts.timeout, "--timeout") ?? DEFAULT_BREAKPOINT_TIMEOUT_SEC;
   const maxValueLength = parsePositiveInt(opts.maxValueLength, "--max-value-length");
   const condition = opts.condition !== void 0 && opts.condition.trim().length > 0 ? opts.condition.trim() : void 0;
+  const hitCount = parsePositiveInt(opts.hitCount, "--hit-count");
+  const stackDepth = parsePositiveInt(opts.stackDepth, "--stack-depth");
   return {
     target,
     breakpoints: opts.bp.map((spec) => parseBreakpointSpec(spec)),
@@ -1926,7 +2377,10 @@ function prepareSnapshotCommand(opts) {
     remoteRoot: parseRemoteRoot(opts.remoteRoot),
     timeoutMs: timeoutSec * 1e3,
     ...condition === void 0 ? {} : { condition },
-    ...maxValueLength === void 0 ? {} : { maxValueLength }
+    ...maxValueLength === void 0 ? {} : { maxValueLength },
+    ...hitCount === void 0 ? {} : { hitCount },
+    ...stackDepth === void 0 ? {} : { stackDepth },
+    stackCaptures: parseCaptureList(opts.stackCaptures)
   };
 }
 async function runSnapshotCommand(command, opts) {
@@ -1940,17 +2394,20 @@ async function runSnapshotCommand(command, opts) {
           file: bp.file,
           line: bp.line,
           remoteRoot: command.remoteRoot,
-          ...command.condition === void 0 ? {} : { condition: command.condition }
+          ...command.condition === void 0 ? {} : { condition: command.condition },
+          ...command.hitCount === void 0 ? {} : { hitCount: command.hitCount }
         })
       )
     );
     warnOnUnboundBreakpoints(handles);
     const pause = await waitForCommandPause(session, opts, handles, command.timeoutMs);
-    const pausedStartedAt = pause.receivedAtMs ?? performance3.now();
+    const pausedStartedAt = pause.receivedAtMs ?? performance4.now();
     const snapshot = await captureSnapshot(session, pause, {
       captures: command.captures,
       includeScopes: opts.includeScopes === true,
-      ...command.maxValueLength === void 0 ? {} : { maxValueLength: command.maxValueLength }
+      ...command.maxValueLength === void 0 ? {} : { maxValueLength: command.maxValueLength },
+      ...command.stackDepth === void 0 ? {} : { stackDepth: command.stackDepth },
+      stackCaptures: command.stackCaptures
     });
     if (opts.keepPaused === true) {
       return withPausedDuration(snapshot, null);
@@ -1976,47 +2433,293 @@ async function waitForCommandPause(session, opts, handles, timeoutMs) {
 async function resumeAfterSnapshot(session, snapshot, pausedStartedAt) {
   try {
     await resume(session);
-    return withPausedDuration(snapshot, roundDurationMs(performance3.now() - pausedStartedAt));
+    return withPausedDuration(snapshot, roundDurationMs(performance4.now() - pausedStartedAt));
   } catch {
-    process7.stderr.write(
+    process8.stderr.write(
       "[cf-inspector] warning: Debugger.resume failed after snapshot; pausedDurationMs is unknown.\n"
     );
     return withPausedDuration(snapshot, null);
   }
 }
 
+// src/cli/commands/watch.ts
+import process9 from "process";
+init_types();
+async function handleWatch(opts) {
+  const prepared = prepareWatchCommand(opts);
+  const abort = new AbortController();
+  const onSig = () => {
+    abort.abort();
+  };
+  process9.once("SIGINT", onSig);
+  process9.once("SIGTERM", onSig);
+  let stoppedReason = "signal";
+  let emitted = 0;
+  try {
+    await withSession(prepared.target, async (session) => {
+      const result = await runWatchLoop(session, prepared, opts, abort.signal);
+      stoppedReason = result.stoppedReason;
+      emitted = result.emitted;
+    });
+  } finally {
+    process9.off("SIGINT", onSig);
+    process9.off("SIGTERM", onSig);
+  }
+  writeWatchSummary(stoppedReason, emitted, opts.json);
+}
+function prepareWatchCommand(opts) {
+  const target = resolveTarget(opts);
+  if (opts.bp.length === 0) {
+    throw new CfInspectorError(
+      "INVALID_BREAKPOINT",
+      "At least one --bp <file:line> is required."
+    );
+  }
+  const perHitTimeoutSec = parsePositiveInt(opts.timeout, "--timeout") ?? DEFAULT_BREAKPOINT_TIMEOUT_SEC;
+  const durationSec = parsePositiveInt(opts.duration, "--duration");
+  const maxEvents = parsePositiveInt(opts.maxEvents, "--max-events");
+  const maxValueLength = parsePositiveInt(opts.maxValueLength, "--max-value-length");
+  const hitCount = parsePositiveInt(opts.hitCount, "--hit-count");
+  const stackDepth = parsePositiveInt(opts.stackDepth, "--stack-depth");
+  const condition = opts.condition !== void 0 && opts.condition.trim().length > 0 ? opts.condition.trim() : void 0;
+  return {
+    target,
+    breakpoints: opts.bp.map((spec) => parseBreakpointSpec(spec)),
+    captures: parseCaptureList(opts.capture),
+    remoteRoot: parseRemoteRoot(opts.remoteRoot),
+    perHitTimeoutMs: perHitTimeoutSec * 1e3,
+    ...durationSec === void 0 ? {} : { durationMs: durationSec * 1e3 },
+    ...maxEvents === void 0 ? {} : { maxEvents },
+    ...maxValueLength === void 0 ? {} : { maxValueLength },
+    ...condition === void 0 ? {} : { condition },
+    ...hitCount === void 0 ? {} : { hitCount },
+    ...stackDepth === void 0 ? {} : { stackDepth },
+    stackCaptures: parseCaptureList(opts.stackCaptures)
+  };
+}
+async function runWatchLoop(session, command, opts, signal) {
+  if (command.condition !== void 0) {
+    await validateExpression(session, command.condition);
+  }
+  const handles = await Promise.all(
+    command.breakpoints.map(
+      (bp) => setBreakpoint(session, {
+        file: bp.file,
+        line: bp.line,
+        remoteRoot: command.remoteRoot,
+        ...command.condition === void 0 ? {} : { condition: command.condition },
+        ...command.hitCount === void 0 ? {} : { hitCount: command.hitCount }
+      })
+    )
+  );
+  warnOnUnboundBreakpoints(handles);
+  const deadline = computeDeadline(command.durationMs);
+  let emitted = 0;
+  const state = { stopped: false, reason: "signal" };
+  const setStop = (reason) => {
+    if (state.stopped) {
+      return;
+    }
+    state.reason = reason;
+    state.stopped = true;
+  };
+  const transportClosed = waitForTransportClose(session);
+  transportClosed.promise.then(() => {
+    setStop("transport-closed");
+  }).catch(() => {
+  });
+  try {
+    while (!state.stopped) {
+      if (signal.aborted) {
+        setStop("signal");
+        break;
+      }
+      const remainingMs = remainingForLoop(deadline, command.perHitTimeoutMs);
+      if (remainingMs <= 0) {
+        setStop("duration");
+        break;
+      }
+      const pause = await waitForNextWatchPause(session, handles, remainingMs, signal);
+      if (pause === "signal") {
+        setStop("signal");
+        break;
+      }
+      if (pause === "timeout") {
+        if (deadline !== void 0 && Date.now() >= deadline) {
+          setStop("duration");
+          break;
+        }
+        continue;
+      }
+      const event = await captureWatchEvent(session, command, pause, emitted + 1, opts);
+      emitted += 1;
+      writeWatchEvent(event, opts.json);
+      try {
+        await resume(session);
+      } catch {
+        process9.stderr.write("[cf-inspector] warning: Debugger.resume failed during watch.\n");
+        setStop("transport-closed");
+        break;
+      }
+      if (command.maxEvents !== void 0 && emitted >= command.maxEvents) {
+        setStop("max-events");
+        break;
+      }
+    }
+  } finally {
+    transportClosed.cancel();
+  }
+  return { emitted, stoppedReason: state.reason };
+}
+function computeDeadline(durationMs) {
+  if (durationMs === void 0) {
+    return void 0;
+  }
+  return Date.now() + durationMs;
+}
+function remainingForLoop(deadline, perHitTimeoutMs) {
+  if (deadline === void 0) {
+    return perHitTimeoutMs;
+  }
+  const remaining = deadline - Date.now();
+  if (remaining <= 0) {
+    return 0;
+  }
+  return Math.min(remaining, perHitTimeoutMs);
+}
+function waitForTransportClose(session) {
+  let cancelled = false;
+  let resolve;
+  const promise = new Promise((res) => {
+    resolve = res;
+  });
+  const off = session.client.onClose(() => {
+    if (!cancelled) {
+      resolve?.();
+    }
+  });
+  return {
+    promise,
+    cancel: () => {
+      cancelled = true;
+      off();
+      resolve?.();
+    }
+  };
+}
+async function waitForNextWatchPause(session, handles, timeoutMs, signal) {
+  if (signal.aborted) {
+    return "signal";
+  }
+  try {
+    return await waitForPause(session, {
+      timeoutMs,
+      breakpointIds: handles.map((h) => h.breakpointId),
+      unmatchedPausePolicy: "wait-for-resume"
+    });
+  } catch (err) {
+    if (err instanceof CfInspectorError) {
+      if (err.code === "BREAKPOINT_NOT_HIT") {
+        return "timeout";
+      }
+      if (err.code === "UNRELATED_PAUSE_TIMEOUT") {
+        return "timeout";
+      }
+    }
+    throw err;
+  }
+}
+async function captureWatchEvent(session, command, pause, hit, opts) {
+  const snapshot = await captureSnapshot(session, pause, {
+    captures: command.captures,
+    includeScopes: opts.includeScopes === true,
+    ...command.maxValueLength === void 0 ? {} : { maxValueLength: command.maxValueLength },
+    ...command.stackDepth === void 0 ? {} : { stackDepth: command.stackDepth },
+    stackCaptures: command.stackCaptures
+  });
+  const at = formatLocation(command, snapshot.topFrame);
+  const base = {
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    at,
+    hit,
+    reason: snapshot.reason,
+    hitBreakpoints: snapshot.hitBreakpoints,
+    captures: snapshot.captures
+  };
+  const withFrame = snapshot.topFrame === void 0 ? base : { ...base, topFrame: snapshot.topFrame };
+  const withStack = snapshot.stack === void 0 ? withFrame : { ...withFrame, stack: snapshot.stack };
+  return snapshot.exception === void 0 ? withStack : { ...withStack, exception: snapshot.exception };
+}
+function formatLocation(command, topFrame) {
+  if (topFrame?.url !== void 0) {
+    return `${topFrame.url}:${topFrame.line.toString()}`;
+  }
+  const first = command.breakpoints[0];
+  if (first === void 0) {
+    return "(unknown)";
+  }
+  return `${first.file}:${first.line.toString()}`;
+}
+function writeWatchSummary(reason, emitted, json) {
+  if (json) {
+    process9.stderr.write(`${JSON.stringify({ stopped: reason, emitted })}
+`);
+    return;
+  }
+  process9.stderr.write(
+    `Stopped (${reason}); emitted ${emitted.toString()} watch ${emitted === 1 ? "event" : "events"}.
+`
+  );
+}
+
 // src/cli/program.ts
 function applyTargetOptions(cmd) {
   return cmd.option("--port <number>", "Local port the inspector or tunnel listens on").option("--host <host>", "Hostname (default: 127.0.0.1)", "127.0.0.1").option("--region <key>", "CF region key (e.g. eu10)").option("--org <name>", "CF org name").option("--space <name>", "CF space name").option("--app <name>", "CF app name").option("--cf-timeout <seconds>", "Timeout for CF tunnel readiness in seconds");
 }
+var collectStrings = (value, prev = []) => [
+  ...prev,
+  value
+];
 async function main(argv) {
   const program = new Command();
   program.name("cf-inspector").description("Drive a Node.js inspector from the command line \u2014 set breakpoints, capture snapshots, evaluate expressions");
   registerSnapshot(program);
   registerLog(program);
+  registerWatch(program);
+  registerException(program);
   registerEval(program);
   registerListScripts(program);
   registerAttach(program);
   await program.parseAsync([...argv]);
 }
 function registerSnapshot(program) {
-  const collectStrings = (value, prev = []) => [
-    ...prev,
-    value
-  ];
   applyTargetOptions(
     program.command("snapshot").description("Set a breakpoint, wait for it to hit, capture expressions, and resume")
-  ).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("--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: 4096)").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("--include-scopes", "Include expanded paused-frame scopes in the snapshot").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) => {
+  ).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("--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: 4096)").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("--include-scopes", "Include expanded paused-frame scopes in the snapshot").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);
   });
 }
 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("--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("--no-json", "Print human-readable lines instead of JSON Lines").action(async (opts) => {
     await handleLog(opts);
   });
 }
+function registerWatch(program) {
+  applyTargetOptions(
+    program.command("watch").description("Stream a snapshot per breakpoint hit (multi-shot watch); resume between hits")
+  ).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("--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("--include-scopes", "Include expanded paused-frame scopes per hit").option("--no-json", "Print human-readable lines instead of JSON Lines").action(async (opts) => {
+    await handleWatch(opts);
+  });
+}
+function registerException(program) {
+  applyTargetOptions(
+    program.command("exception").description("Pause on a thrown exception, capture the value and frame, then resume")
+  ).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: 4096)").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("--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) => {
+    await handleException(opts);
+  });
+}
 function registerEval(program) {
   applyTargetOptions(
     program.command("eval").description("Evaluate an expression against the global Runtime")
@@ -2042,20 +2745,20 @@ function registerAttach(program) {
 // src/cli.ts
 init_types();
 try {
-  await main(process8.argv);
+  await main(process10.argv);
 } catch (err) {
   if (err instanceof CfInspectorError) {
-    process8.stderr.write(`Error [${err.code}]: ${err.message}
+    process10.stderr.write(`Error [${err.code}]: ${err.message}
 `);
     if (err.detail !== void 0) {
-      process8.stderr.write(`  detail: ${err.detail}
+      process10.stderr.write(`  detail: ${err.detail}
 `);
     }
-    process8.exit(1);
+    process10.exit(1);
   }
   const message = err instanceof Error ? err.message : String(err);
-  process8.stderr.write(`Error: ${message}
+  process10.stderr.write(`Error: ${message}
 `);
-  process8.exit(1);
+  process10.exit(1);
 }
 //# sourceMappingURL=cli.js.map