debugger: surface inspector failures in probe mode

This addresses a few TODOs left from the initial implementation
around the error handling when the inspector session fails
mid-probe - for example because a probe expression terminates
the target, severs the inspector connection, or hangs the
evaluation. Before this patch, these failures would cause the
probe report to silently miss hits or hit the session timeout.
A consumer of these reports could not tell whether the
recorded hits were reliable or a partial trace cut short
by an inspector-side failure.

This patch surfaces those cases as a new `probe_failure` terminal
`error` event on the report, with best-effort attribution to the
implicated probe via `error.probe` and additional context on
`error.details`. Together with `probe_timeout`, it marks the
report as best-effort, and the probing process exits 1 in both
cases. `probe_target_exit` and clean `completed`/`miss` reports
continue to exit 0 because the recorded hits in those cases remain
ground truth, so tooling can use the exit code as a quick
trustworthiness signal. `error.message` now also contains
actionable recovery hints whereever possible.

The per-hit `error` is reshaped to `{ message, details? }`
so that the per-hit and terminal errors share a top-level shape.
Both fields are informative-only, only their top-level type is stable.

Signed-off-by: Joyee Cheung <joyeec9h3@gmail.com>
PR-URL: #63437
Refs: #62713
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: Jan Martin <jan.krems@gmail.com>

Author: joyeecheung

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/63437
+    description: Add `probe_failure` terminal `error` event for inspector-side mid-session
+        failures, and `error.details` for additional context on per-hit and terminal errors.
   - version: v26.2.0
     pr-url: https://github.com/nodejs/node/pull/63286
     description: JSON report schema bumped to v2. Probe `target` is now
@@ -383,7 +387,10 @@ $ node inspect --json --probe cli.js:5 --expr 'rss' cli.js
         "value": 55443456,
         "description": "55443456"
       }
-      // If the expression throws, "error" is present instead of "result".
+      // If the probe expression throws, fails, or never completes, the entry
+      // carries an `error` field instead of `result` with the shape
+      // `{ message: string, details?: object }`. The `message` and `details`
+      // content is informational only and may change between releases.
     },
     {
       "probe": 0,
@@ -415,24 +422,40 @@ $ node inspect --json --probe cli.js:5 --expr 'rss' cli.js
       //      "error": {
       //       "code": "probe_target_exit",
       //       "exitCode": 1,
-      //       "stderr": "[Error: boom]",
+      //       "stderr": "Error: boom",
       //       "message": "Target exited with code 1 before probes: app.js:10"
       //      }
       //    }
+      // 5. {
+      //      "event": "error",
+      //      "pending": [1],
+      //      "error": {
+      //       "code": "probe_failure",
+      //       "probe": 0,
+      //       "stderr": "...",
+      //       "message": "Target process exited during probe evaluation before probes: app.js:12. If the failure repeats, review the probe expression.",
+      //       "details": { "lastCdpMethod": "Debugger.evaluateOnCallFrame" }
+      //      }
+      //    }
     }
   ]
 }
 ```
 
-### Output and exit codes from the probed process
+### Output and exit codes
 
 Probe mode only prints the final probe report to stdout, and otherwise silences
 stdout/stderr from the child process. When the probing session ends,
-`node inspect` typically exits with code `0` and prints a final report to
-stdout. If the child process exits with a non-zero code before the
-probe session ends, the final report records a terminal `error` event along
-with the exit code and captured child stderr. The probing process itself
-still exits with code `0` in this case.
+the probing process typically exits with code `0` and prints a final report to
+stdout. If the child process exits with a non-zero code before the probe
+session ends, or the probe session cannot complete for another reason, the
+final report records a terminal `error` event.
+
+When `error.code` is `'probe_failure'` or `'probe_timeout'`, the probing process
+exits with a non-zero code, indicating recorded hits may be incomplete.
+In this case, `error.message` will contain recovery hints, and `error.probe`,
+when present, is an index into the report's `probes` array that identifies
+the possible culprit probe on a best-effort basis to help guide debugging.
 
 Invalid arguments and fatal launch or connect failures may cause the
 probing process to exit with a non-zero code and print an error message