From 416e09f56d93dc478304436a682ef1940692f155 Mon Sep 17 00:00:00 2001
From: Joyee Cheung <joyeec9h3@gmail.com>
Date: Fri, 29 May 2026 17:05:18 +0200
Subject: [PATCH] debugger: add --max-hit option to probe mode

This option provides a new way of terminating the probing by
specifying a limit for the per-probe hit evaluation. When any
probe reaches the limit, the session removes the V8 breakpoints
and finishes with a `completed` terminal event rather than waiting
for the target to exit or timeout. This would be useful when we
provide a way to attach to and probe a running process in the future.

Signed-off-by: Joyee Cheung <joyeec9h3@gmail.com>
---
 doc/api/debugger.md                           | 18 +++++-
 lib/internal/debugger/inspect.js              | 19 +++---
 lib/internal/debugger/inspect_helpers.js      |  8 ++-
 lib/internal/debugger/inspect_probe.js        | 42 +++++++++++++-
 test/common/debugger-probe.js                 | 11 ++++
 test/fixtures/debugger/probe-max-hit.js       |  7 +++
 .../test-debugger-probe-max-hit-invalid.js    | 40 +++++++++++++
 .../test-debugger-probe-max-hit-miss.js       | 36 ++++++++++++
 .../test-debugger-probe-max-hit-partial.js    | 58 +++++++++++++++++++
 .../test-debugger-probe-max-hit-shared.js     | 53 +++++++++++++++++
 .../test-debugger-probe-max-hit-text.js       | 30 ++++++++++
 test/parallel/test-debugger-probe-max-hit.js  | 51 ++++++++++++++++
 12 files changed, 358 insertions(+), 15 deletions(-)
 create mode 100644 test/fixtures/debugger/probe-max-hit.js
 create mode 100644 test/parallel/test-debugger-probe-max-hit-invalid.js
 create mode 100644 test/parallel/test-debugger-probe-max-hit-miss.js
 create mode 100644 test/parallel/test-debugger-probe-max-hit-partial.js
 create mode 100644 test/parallel/test-debugger-probe-max-hit-shared.js
 create mode 100644 test/parallel/test-debugger-probe-max-hit-text.js
 create mode 100644 test/parallel/test-debugger-probe-max-hit.js

diff --git a/doc/api/debugger.md b/doc/api/debugger.md
index 965c9a5d2a4117..56f36cb133aa08 100644
--- a/doc/api/debugger.md
+++ b/doc/api/debugger.md
@@ -237,6 +237,10 @@ added:
   - v26.1.0
   - v24.16.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/63704
+    description: Add per-probe `--max-hit <n>` option to limit evaluated hits and finish
+        with a `completed` terminal event as soon as any probe reaches its limit.
   - version: v26.3.0
     pr-url: https://github.com/nodejs/node/pull/63437
     description: Add `probe_failure` terminal `error` event for inspector-side mid-session
@@ -265,8 +269,8 @@ printf-style debugging without having to modify the application code and
 clean up afterwards. It also supports structured JSON output for tool use.
 
 ```console
-$ node inspect --probe <file>:<line>[:<col>] --expr <expr>
-              [--probe <file>:<line>[:<col>] --expr <expr> ...]
+$ node inspect --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
+              [--probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>] ...]
               [--json] [--preview] [--timeout=<ms>] [--port=<port>]
               [--] [<node-option> ...] <script> [<script-args> ...]
 ```
@@ -279,6 +283,11 @@ $ node inspect --probe <file>:<line>[:<col>] --expr <expr>
 * `--expr <expr>`: JavaScript expression to evaluate whenever execution reaches
   the location specified by the preceding `--probe`.
   Must immediately follow the `--probe` it belongs to.
+* `--max-hit <n>`: An optional per-probe limit on the number of times the probe
+  can be hit. When not specified, there's no hit limit. When any probe reaches
+  its hit limit, the probing process will detach and report the results. The process
+  being probed will continue to run. If any other probe is never reached by the time
+  the session ends, it will be reported as a missed probe.
 * `--timeout=<ms>`: A global wall-clock deadline for the entire probe session.
   The default is `30000`. This can be used to probe a long-running application
   that can be terminated externally.
@@ -293,6 +302,10 @@ Additional rules about the `--probe` and `--expr` arguments:
 
 * `--probe <file>:<line>[:<col>]` and `--expr <expr>` are strict pairs. Each
   `--probe` must be followed immediately by exactly one `--expr`.
+* `--max-hit <n>` is an optional per-probe option that applies to the most recent
+  `--probe`/`--expr` pair. It may not appear before the first `--probe` or
+  between a `--probe` and its matching `--expr`, and may be given at most once
+  per probe.
 * `--timeout`, `--json`, `--preview`, and `--port` are global probe options
   for the whole probe session. They may appear before or between probe pairs,
   but not between a `--probe` and its matching `--expr`.
@@ -367,6 +380,7 @@ $ node inspect --json --probe cli.js:5 --expr 'rss' cli.js
         "suffix": "cli.js",
         "line": 5
       }
+      // `maxHit` is present only when the probe was given a --max-hit limit.
     }
   ],
   "results": [
diff --git a/lib/internal/debugger/inspect.js b/lib/internal/debugger/inspect.js
index 41157dab97baa2..97c4b5922c978a 100644
--- a/lib/internal/debugger/inspect.js
+++ b/lib/internal/debugger/inspect.js
@@ -267,16 +267,17 @@ function parseInteractiveArgs(args) {
 }
 
 const kInspectArgOptions = {
-  __proto__: null,
-  expr: { type: 'string' },
-  help: { type: 'boolean', short: 'h' },
-  json: { type: 'boolean' },
-  // Port and timeout use type 'string' because parseArgs has no
+  '__proto__': null,
+  'expr': { type: 'string' },
+  'help': { type: 'boolean', short: 'h' },
+  'json': { type: 'boolean' },
+  // Port, timeout, and max-hit use type 'string' because parseArgs has no
   // numeric type; the values are parsed to integers by parseProbeTokens().
-  port: { type: 'string' },
-  preview: { type: 'boolean' },
-  probe: { type: 'string' },
-  timeout: { type: 'string' },
+  'max-hit': { type: 'string' },
+  'port': { type: 'string' },
+  'preview': { type: 'boolean' },
+  'probe': { type: 'string' },
+  'timeout': { type: 'string' },
 };
 
 // Parses args once and decides whether the user wants the inspect help, probe
diff --git a/lib/internal/debugger/inspect_helpers.js b/lib/internal/debugger/inspect_helpers.js
index d0049acc06cd22..dc0d9709403227 100644
--- a/lib/internal/debugger/inspect_helpers.js
+++ b/lib/internal/debugger/inspect_helpers.js
@@ -69,8 +69,8 @@ function writeInspectUsageAndExit(invokedAs, message, exitCode) {
   }
   out.write(`Usage: ${invokedAs} [--port=<port>] [<node-option> ...]
                       [<script> [<script-args>] | <host>:<port> | -p <pid>]
-       ${invokedAs} --probe <file>:<line>[:<col>] --expr <expr>
-                      [--probe <file>:<line>[:<col>] --expr <expr> ...]
+       ${invokedAs} --probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>]
+                      [--probe <file>:<line>[:<col>] --expr <expr> [--max-hit <n>] ...]
                       [--json] [--preview] [--timeout=<ms>] [--port=<port>]
                       [--] [<node-option> ...] <script> [<script-args> ...]
 
@@ -109,6 +109,10 @@ Options:
                     preceding --probe each time execution reaches it.
                     Avoid probing let/const-bound variables at their
                     declaration site or a ReferenceError may be thrown.
+  --max-hit <n>     Per-probe limit on evaluated hits. When not specified,
+                    there's no hit limit. When any probe reaches its hit LIMIT,
+                    the probing process will detach and report the results.
+                    The probed process will continue to run.
   --json            Output JSON if specified, otherwise human-readable text.
   --preview         Include V8 object previews in JSON output.
   --timeout <ms>    Global session timeout (default: 30000).
diff --git a/lib/internal/debugger/inspect_probe.js b/lib/internal/debugger/inspect_probe.js
index 608fe1ab668175..c7c2d4627e4ae2 100644
--- a/lib/internal/debugger/inspect_probe.js
+++ b/lib/internal/debugger/inspect_probe.js
@@ -7,6 +7,7 @@ const {
   ArrayPrototypeMap,
   ArrayPrototypePush,
   ArrayPrototypeSlice,
+  ArrayPrototypeSome,
   FunctionPrototypeBind,
   JSONStringify,
   NumberIsNaN,
@@ -86,9 +87,14 @@ const kInspectPortRegex = /^--inspect-port=(\d+)$/;
  * @typedef {object} Probe
  * @property {string} expr Expression to evaluate on hit.
  * @property {ProbeTarget} target User's original --probe request shape.
+ * @property {number} maxHit Per-probe hit limit from --max-hit. Infinity when unlimited.
  * @property {number} hits Count of hits observed.
  */
 
+function probeReachedLimit(probe) {
+  return probe.hits >= probe.maxHit;
+}
+
 function parseUnsignedInteger(value, name, allowZero = false) {
   if (typeof value !== 'string' || RegExpPrototypeExec(kDigitsRegex, value) === null) {
     throw new ERR_DEBUGGER_STARTUP_ERROR(`Invalid ${name}: ${value}`);
@@ -371,6 +377,20 @@ function parseProbeTokens(tokens, args) {
         break;
       case 'expr':
         throw new ERR_DEBUGGER_STARTUP_ERROR('Unexpected --expr before --probe');
+      case 'max-hit': {
+        if (probes.length === 0) {
+          throw new ERR_DEBUGGER_STARTUP_ERROR('Unexpected --max-hit before --probe');
+        }
+        if (token.value === undefined) {
+          throw new ERR_DEBUGGER_STARTUP_ERROR(`Missing value for ${token.rawName}`);
+        }
+        const probe = probes[probes.length - 1];
+        if (probe.maxHit !== undefined) {
+          throw new ERR_DEBUGGER_STARTUP_ERROR('Duplicate --max-hit for a single --probe');
+        }
+        probe.maxHit = parseUnsignedInteger(token.value, 'max-hit');
+        break;
+      }
       default:
         if (probes.length > 0) {
           throw new ERR_DEBUGGER_STARTUP_ERROR(
@@ -458,7 +478,9 @@ class ProbeInspectorSession {
     this.completionPromise = promise;
     this.resolveCompletion = resolve;
     /** @type {Probe[]} */
-    this.probes = ArrayPrototypeMap(options.probes, ({ expr, target }) => ({ expr, target, hits: 0 }));
+    this.probes = ArrayPrototypeMap(options.probes,
+                                    ({ expr, target, maxHit }) =>
+                                      ({ expr, target, maxHit: maxHit ?? Infinity, hits: 0 }));
     this.onChildOutput = FunctionPrototypeBind(this.onChildOutput, this);
     this.onChildExit = FunctionPrototypeBind(this.onChildExit, this);
     this.onClientClose = FunctionPrototypeBind(this.onClientClose, this);
@@ -638,6 +660,15 @@ class ProbeInspectorSession {
       }
     }
 
+    // Finish proactively as soon as any probe reaches its hit limit. All probes
+    // hit in this pause are recorded first, then the session ends.
+    // TODO(joyeecheung): When we implement attach mode, this teardown must
+    // resume-and-detach rather than kill, since the target is not ours.
+    if (!this.finished && ArrayPrototypeSome(this.probes, probeReachedLimit)) {
+      this.finishWithTrustedResult({ event: 'completed' });
+      return;
+    }
+
     await this.resume();
   }
 
@@ -908,7 +939,12 @@ class ProbeInspectorSession {
       code: exitCode,
       report: {
         v: kProbeVersion,
-        probes: ArrayPrototypeMap(this.probes, ({ expr, target }) => ({ expr, target })),
+        probes: ArrayPrototypeMap(this.probes, ({ expr, target, maxHit }) => {
+          // Omit an unlimited maxHit, as Infinity would serialize to null in JSON.
+          const probe = { expr, target };
+          if (maxHit !== Infinity) { probe.maxHit = maxHit; }
+          return probe;
+        }),
         results,
       },
     };
@@ -927,6 +963,8 @@ class ProbeInspectorSession {
 
     if (this.child === null) { return; }
 
+    // TODO(joyeecheung): When we implement attach mode, this teardown must
+    // resume-and-detach rather than kill, since the target is not ours.
     if (this.child.exitCode === null && this.child.signalCode === null) {
       this.child.kill();
     }
diff --git a/test/common/debugger-probe.js b/test/common/debugger-probe.js
index c2ed825a26064b..58ecfc24055dad 100644
--- a/test/common/debugger-probe.js
+++ b/test/common/debugger-probe.js
@@ -1,6 +1,7 @@
 'use strict';
 
 const assert = require('assert');
+const { spawnSyncAndExit } = require('./child_process');
 
 // Work around a pre-existing inspector issue: if the debuggee exits too quickly
 // the inspector can segfault while tearing down. For now normalize the segfault
@@ -79,7 +80,17 @@ function assertProbeText(output, expected) {
   assert.strictEqual(normalized, expected);
 }
 
+function assertProbeCliError(inspectArgs, expectedStderr, { cwd } = {}) {
+  spawnSyncAndExit(process.execPath, ['inspect', ...inspectArgs], { cwd }, {
+    signal: null,
+    status: 9,
+    stderr: expectedStderr,
+    trim: true,
+  });
+}
+
 module.exports = {
   assertProbeJson,
+  assertProbeCliError,
   assertProbeText,
 };
diff --git a/test/fixtures/debugger/probe-max-hit.js b/test/fixtures/debugger/probe-max-hit.js
new file mode 100644
index 00000000000000..568e365b105d08
--- /dev/null
+++ b/test/fixtures/debugger/probe-max-hit.js
@@ -0,0 +1,7 @@
+'use strict';
+
+let total = 0;
+for (let index = 0; index < 3; index++) {
+  total += index + 1;
+}
+console.log(total);
diff --git a/test/parallel/test-debugger-probe-max-hit-invalid.js b/test/parallel/test-debugger-probe-max-hit-invalid.js
new file mode 100644
index 00000000000000..cc86a82c37f562
--- /dev/null
+++ b/test/parallel/test-debugger-probe-max-hit-invalid.js
@@ -0,0 +1,40 @@
+// This tests that probe mode rejects malformed --max-hit usage.
+'use strict';
+
+const common = require('../common');
+common.skipIfInspectorDisabled();
+
+const fixtures = require('../common/fixtures');
+const { assertProbeCliError } = require('../common/debugger-probe');
+
+const cwd = fixtures.path('debugger');
+
+// --max-hit before any --probe.
+assertProbeCliError(
+  ['--max-hit', '1', '--probe', 'probe.js:12', '--expr', 'finalValue', 'probe.js'],
+  /Unexpected --max-hit before --probe/, { cwd });
+
+// --max-hit between a --probe and its --expr.
+assertProbeCliError(
+  ['--probe', 'probe.js:12', '--max-hit', '1', '--expr', 'finalValue', 'probe.js'],
+  /Each --probe must be followed immediately by --expr/, { cwd });
+
+// Duplicate --max-hit for a single probe.
+assertProbeCliError(
+  ['--probe', 'probe.js:12', '--expr', 'finalValue', '--max-hit', '1', '--max-hit', '2', 'probe.js'],
+  /Duplicate --max-hit for a single --probe/, { cwd });
+
+// Non-numeric value.
+assertProbeCliError(
+  ['--probe', 'probe.js:12', '--expr', 'finalValue', '--max-hit', 'abc', 'probe.js'],
+  /Invalid max-hit: abc/, { cwd });
+
+// Zero is not allowed (limit must be at least 1).
+assertProbeCliError(
+  ['--probe', 'probe.js:12', '--expr', 'finalValue', '--max-hit', '0', 'probe.js'],
+  /Invalid max-hit: 0/, { cwd });
+
+// Missing value: --max-hit as the final token has nothing to consume.
+assertProbeCliError(
+  ['--probe', 'probe.js:12', '--expr', 'finalValue', '--max-hit'],
+  /Missing value for --max-hit/, { cwd });
diff --git a/test/parallel/test-debugger-probe-max-hit-miss.js b/test/parallel/test-debugger-probe-max-hit-miss.js
new file mode 100644
index 00000000000000..dd47cc76f5076a
--- /dev/null
+++ b/test/parallel/test-debugger-probe-max-hit-miss.js
@@ -0,0 +1,36 @@
+// This tests that a limited probe that is never reached is still reported as a missed probe.
+'use strict';
+
+const common = require('../common');
+common.skipIfInspectorDisabled();
+
+const fixtures = require('../common/fixtures');
+const { spawnSyncAndAssert } = require('../common/child_process');
+const { assertProbeJson } = require('../common/debugger-probe');
+
+const cwd = fixtures.path('debugger');
+
+spawnSyncAndAssert(process.execPath, [
+  'inspect',
+  '--json',
+  '--probe', 'probe-miss.js:99',
+  '--expr', '42',
+  '--max-hit', '3',
+  'probe-miss.js',
+], { cwd }, {
+  stdout(output) {
+    assertProbeJson(output, {
+      v: 2,
+      probes: [{
+        expr: '42',
+        target: { suffix: 'probe-miss.js', line: 99 },
+        maxHit: 3,
+      }],
+      results: [{
+        event: 'miss',
+        pending: [0],
+      }],
+    });
+  },
+  trim: true,
+});
diff --git a/test/parallel/test-debugger-probe-max-hit-partial.js b/test/parallel/test-debugger-probe-max-hit-partial.js
new file mode 100644
index 00000000000000..51cd88e0bf017d
--- /dev/null
+++ b/test/parallel/test-debugger-probe-max-hit-partial.js
@@ -0,0 +1,58 @@
+// This tests that when the target exits before a probe reaches its limit,
+// the session still ends with `completed`.
+'use strict';
+
+const common = require('../common');
+common.skipIfInspectorDisabled();
+
+const fixtures = require('../common/fixtures');
+const { spawnSyncAndAssert } = require('../common/child_process');
+const { assertProbeJson } = require('../common/debugger-probe');
+
+const cwd = fixtures.path('debugger');
+const probeUrl = fixtures.fileURL('debugger', 'probe-max-hit.js').href;
+
+spawnSyncAndAssert(process.execPath, [
+  'inspect',
+  '--json',
+  '--probe', 'probe-max-hit.js:5',
+  '--expr', 'index',
+  '--max-hit', '10',
+  'probe-max-hit.js',
+], { cwd }, {
+  stdout(output) {
+    assertProbeJson(output, {
+      v: 2,
+      probes: [{
+        expr: 'index',
+        target: { suffix: 'probe-max-hit.js', line: 5 },
+        maxHit: 10,
+      }],
+      results: [
+        {
+          probe: 0,
+          event: 'hit',
+          hit: 1,
+          location: { url: probeUrl, line: 5, column: 3 },
+          result: { type: 'number', value: 0, description: '0' },
+        },
+        {
+          probe: 0,
+          event: 'hit',
+          hit: 2,
+          location: { url: probeUrl, line: 5, column: 3 },
+          result: { type: 'number', value: 1, description: '1' },
+        },
+        {
+          probe: 0,
+          event: 'hit',
+          hit: 3,
+          location: { url: probeUrl, line: 5, column: 3 },
+          result: { type: 'number', value: 2, description: '2' },
+        },
+        { event: 'completed' },
+      ],
+    });
+  },
+  trim: true,
+});
diff --git a/test/parallel/test-debugger-probe-max-hit-shared.js b/test/parallel/test-debugger-probe-max-hit-shared.js
new file mode 100644
index 00000000000000..b7b3325aea47cb
--- /dev/null
+++ b/test/parallel/test-debugger-probe-max-hit-shared.js
@@ -0,0 +1,53 @@
+// This tests that when two probes share one location but have different
+// --max-hit limits, the session ends as soon as one of them reaches the limit.
+'use strict';
+
+const common = require('../common');
+common.skipIfInspectorDisabled();
+
+const fixtures = require('../common/fixtures');
+const { spawnSyncAndAssert } = require('../common/child_process');
+const { assertProbeJson } = require('../common/debugger-probe');
+
+const cwd = fixtures.path('debugger');
+const probeUrl = fixtures.fileURL('debugger', 'probe-max-hit.js').href;
+
+spawnSyncAndAssert(process.execPath, [
+  'inspect',
+  '--json',
+  '--probe', 'probe-max-hit.js:5',
+  '--expr', 'index',
+  '--max-hit', '1',
+  '--probe', 'probe-max-hit.js:5',
+  '--expr', 'total',
+  '--max-hit', '2',
+  'probe-max-hit.js',
+], { cwd }, {
+  stdout(output) {
+    assertProbeJson(output, {
+      v: 2,
+      probes: [
+        { expr: 'index', target: { suffix: 'probe-max-hit.js', line: 5 }, maxHit: 1 },
+        { expr: 'total', target: { suffix: 'probe-max-hit.js', line: 5 }, maxHit: 2 },
+      ],
+      results: [
+        {
+          probe: 0,
+          event: 'hit',
+          hit: 1,
+          location: { url: probeUrl, line: 5, column: 3 },
+          result: { type: 'number', value: 0, description: '0' },
+        },
+        {
+          probe: 1,
+          event: 'hit',
+          hit: 1,
+          location: { url: probeUrl, line: 5, column: 3 },
+          result: { type: 'number', value: 0, description: '0' },
+        },
+        { event: 'completed' },
+      ],
+    });
+  },
+  trim: true,
+});
diff --git a/test/parallel/test-debugger-probe-max-hit-text.js b/test/parallel/test-debugger-probe-max-hit-text.js
new file mode 100644
index 00000000000000..28156c31521d32
--- /dev/null
+++ b/test/parallel/test-debugger-probe-max-hit-text.js
@@ -0,0 +1,30 @@
+// This tests that --max-hit works with the text report.
+'use strict';
+
+const common = require('../common');
+common.skipIfInspectorDisabled();
+
+const fixtures = require('../common/fixtures');
+const { spawnSyncAndAssert } = require('../common/child_process');
+const { assertProbeText } = require('../common/debugger-probe');
+
+const cwd = fixtures.path('debugger');
+const probeUrl = fixtures.fileURL('debugger', 'probe-max-hit.js').href;
+
+spawnSyncAndAssert(process.execPath, [
+  'inspect',
+  '--probe', 'probe-max-hit.js:5',
+  '--expr', 'index',
+  '--max-hit', '2',
+  'probe-max-hit.js',
+], { cwd }, {
+  stdout(output) {
+    assertProbeText(output,
+                    `Hit 1 at ${probeUrl}:5:3\n` +
+                    '  index = 0\n' +
+                    `Hit 2 at ${probeUrl}:5:3\n` +
+                    '  index = 1\n' +
+                    'Completed');
+  },
+  trim: true,
+});
diff --git a/test/parallel/test-debugger-probe-max-hit.js b/test/parallel/test-debugger-probe-max-hit.js
new file mode 100644
index 00000000000000..2a577fb0c29368
--- /dev/null
+++ b/test/parallel/test-debugger-probe-max-hit.js
@@ -0,0 +1,51 @@
+// This tests that --max-hit limits evaluated hits for a probe and finishes
+// the session proactively without waiting for the target to exit.
+'use strict';
+
+const common = require('../common');
+common.skipIfInspectorDisabled();
+
+const fixtures = require('../common/fixtures');
+const { spawnSyncAndAssert } = require('../common/child_process');
+const { assertProbeJson } = require('../common/debugger-probe');
+
+const cwd = fixtures.path('debugger');
+const probeUrl = fixtures.fileURL('debugger', 'probe-max-hit.js').href;
+
+spawnSyncAndAssert(process.execPath, [
+  'inspect',
+  '--json',
+  '--probe', 'probe-max-hit.js:5',
+  '--expr', 'index',
+  '--max-hit', '2',
+  'probe-max-hit.js',
+], { cwd }, {
+  stdout(output) {
+    assertProbeJson(output, {
+      v: 2,
+      probes: [{
+        expr: 'index',
+        target: { suffix: 'probe-max-hit.js', line: 5 },
+        maxHit: 2,
+      }],
+      results: [
+        {
+          probe: 0,
+          event: 'hit',
+          hit: 1,
+          location: { url: probeUrl, line: 5, column: 3 },
+          result: { type: 'number', value: 0, description: '0' },
+        },
+        {
+          probe: 0,
+          event: 'hit',
+          hit: 2,
+          location: { url: probeUrl, line: 5, column: 3 },
+          result: { type: 'number', value: 1, description: '1' },
+        },
+        { event: 'completed' },
+      ],
+    });
+  },
+  trim: true,
+});