@descryy/runtime-orchestrator 0.0.0

package/dist/attach-to-running-jvm-process.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Retroactive attach to an already-running **JVM (Java/Kotlin/…)** process —
+ * the JVM item on `RT-attach-to-running-process-scope.md`'s own
+ * "deliberately not built" list, and `RT-attach-to-running-jvm-process.md`
+ * (decisions-inbox) is the short record of what got measured before any of
+ * this was written and why the slice below is the honest first one, not a
+ * full CDP-equivalent.
+ *
+ * **The real mechanism, measured against a live JVM on this machine, not
+ * assumed from docs.** The JVM ships no built-in signal-to-inspector path
+ * the way Node's `SIGUSR1` does. What it does ship, since JDK 6, is the
+ * HotSpot Dynamic Attach mechanism: a launcher process calls
+ * `com.sun.tools.attach.VirtualMachine.attach(pid)`, which creates
+ * `.attach_pid<pid>` and signals the target with `SIGQUIT`; the target's own
+ * attach-listener thread (started lazily on first use, already running in
+ * every stock HotSpot JVM — nothing needs to be enabled at the target's own
+ * launch) opens a Unix-domain socket at `.java_pid<pid>` in its temp
+ * directory and accepts commands over it. `jcmd`/`jstack`/`VisualVM` all use
+ * exactly this. Measured directly here: attached to a plain `java
+ * QuietServer` process with no `-agentlib`/`-Djdk.attach` flags of any kind
+ * and no restart, confirming this is genuinely retroactive, the same
+ * standing Node's `SIGUSR1` slice has.
+ *
+ * **What this channel can actually give — measured, and narrower than
+ * CDP.** `VirtualMachine.loadAgent(jar, args)` loads a real Java agent
+ * (`java.lang.instrument.Instrumentation`) into the target's own JVM,
+ * running as that JVM's own code — a strictly more powerful primitive than
+ * CDP's remote-debugging protocol. This first slice used only the cheapest
+ * real capability inside it: `Thread.setDefaultUncaughtExceptionHandler`
+ * (`jvm-agent/Agent.java`), which needs no bytecode instrumentation at all,
+ * and **did not see an exception a framework already caught** — a request
+ * handler's own try/catch, a servlet container's default error page, any
+ * `@ExceptionHandler` — because by definition those exceptions never reach
+ * "uncaught." `SelfFailingServer.java` (the existing execute-mode fixture)
+ * catches and logs its own thrown exception for exactly this reason, so it
+ * is not a fixture this module's own test can reuse; see
+ * `test/fixtures/jvm-attach/BackgroundThreadThrows.java`, a real thread that
+ * throws with nothing catching it, the one shape that first slice could see.
+ *
+ * **RT-201 closed one specific, real instance of that gap**, using the same
+ * `Instrumentation` this module already hands the agent: `Agent.java` now
+ * also installs a ByteBuddy `ClassFileTransformer` (see that file's own
+ * header comment for the full mechanism and what was measured) that taps
+ * `org.springframework.web.servlet.DispatcherServlet#processHandlerException`
+ * — Spring MVC's single stable choke point for every exception-handling
+ * path — and reports what it catches as a `"framework-caught-exception"`
+ * event, parsed below as `isFrameworkCaughtExceptionEvent` and emitted as
+ * `EXCEPTION` evidence with `payload.handled === true`. **This closes only
+ * that one choke point.** A catch that never reaches Spring's dispatcher —
+ * absorbed inside a `@Service` method, logged nowhere — is still invisible,
+ * and no non-Spring framework is instrumented at all. `Runtime.exceptionThrown`'s
+ * CDP-side reach (any throw the debugger is configured to pause on,
+ * regardless of framework) still has no equivalent here.
+ *
+ * **No console-output capture in this slice.** Unlike CDP's
+ * `Runtime.consoleAPICalled`, `System.out`/`System.err` are not intercepted
+ * — a target already logging to a file is exactly `attachToRunningProcess`'s
+ * (the file-based sibling) job, and duplicating that here would be two
+ * mechanisms claiming the same evidence. `capabilities()` reports
+ * `backendLogAccess` unavailable for that reason, unlike the Node slice.
+ *
+ * **Launcher is a real JDK tool process, not a library call.** There is no
+ * Node/native binding for the Attach API in this repo and none is added —
+ * `jvm-agent/build.ts` compiles `Attacher.java` once (cached by mtime, same
+ * rule `kotlin-server/build.ts` already uses) and this module spawns it as a
+ * short-lived `java` child process, the same "one helper invocation, not a
+ * new protocol client" shape `discoverNodeInspectorUrl`'s `process.kill`
+ * call has, just through a JDK tool instead of a POSIX signal.
+ */
+import type { Collector } from "@descryy/runtime-contracts";
+export interface AttachToRunningJvmProcessOptions {
+    readonly processId: string;
+    /** The pid of the already-running target JVM. Verified alive before attach is attempted, and never spawned or supervised by this collector. */
+    readonly pid: number;
+    readonly service?: string;
+    /** How long to wait for the Attacher helper process to complete the attach + loadAgent call. The attach itself is normally sub-second; generous default for a loaded machine. */
+    readonly attachTimeoutMs?: number;
+    /** How often to check the agent's output file for new events. */
+    readonly pollIntervalMs?: number;
+    /**
+     * Repo-relative source roots plus the absolute repo root, enabling a JVM
+     * frame's bare basename to be reconstructed into a repo-relative path that
+     * graph correlation can actually join on (RT-202, extending RT-162's fix
+     * from the log-tailing path to this one).
+     *
+     * ## Why the attach path needed this too, and why it went unnoticed
+     *
+     * `JvmRuntimeAdapterOptions.sourceRoots` (`@descryhq-wq/runtime-adapter-jvm`)
+     * already fixed this for evidence produced by `createJvmStackTraceParser`
+     * — the JVM prints a bare basename (`ProbeApplication.java`), never a
+     * path, so `resolveSymbolNode` correctly refuses to match on it alone
+     * (RT-031's identity-proxy rule), and reconstruction from the frame's
+     * declaring type is what lets the two sides join. This collector builds
+     * its `StackFrame.location` directly from the Java agent's own captured
+     * `StackTraceElement` fields (`frameToStackFrame` below) and never went
+     * through that parser at all, so it never got the fix — invisible until
+     * RT-202, because this mechanism's only fixture before then
+     * (`BackgroundThreadThrows.java`) is in the default package, where
+     * reconstruction is a no-op regardless (no dot in the declaring type).
+     *
+     * ## Reimplemented here, not imported — a deliberate, disclosed duplication
+     *
+     * `packages/orchestrator`'s own `src/` has never taken a real dependency
+     * on any `@descryhq-wq/runtime-adapter-*` package — only
+     * `@descryy/runtime-adapter-typescript` is one, for an unrelated
+     * default-path reason, and every other language adapter (including
+     * `@descryhq-wq/runtime-adapter-jvm`) is a devDependency used solely by this
+     * package's own tests. Importing the JVM-specific reconstruction function
+     * into this language-agnostic-by-convention module would be a bigger
+     * architectural change than this gap warrants, so
+     * `reconstructJvmSourcePath` below is a second copy of the exact same
+     * algorithm (declaring type + basename + candidate roots + `existsSync`
+     * check, discarded rather than fabricated when nothing is on disk) —
+     * unlike other duplication this project has measured drifting silently,
+     * both copies are tiny, pure, and named after the one behaviour they
+     * implement, so a future change to one is easy to notice is missing from
+     * the other.
+     */
+    readonly sourceRoots?: {
+        readonly repoRoot: string;
+        readonly roots: readonly string[];
+    };
+}
+/**
+ * Attach to an already-running JVM process via the HotSpot Dynamic Attach
+ * mechanism, load a minimal Java agent, and start capturing genuinely
+ * uncaught exceptions as `EXCEPTION` evidence from that moment forward.
+ *
+ * **Retroactive, not historical** — same as the Node slice: an exception
+ * thrown before the agent finishes loading is not captured, because the
+ * default handler was not installed yet. There is no backlog to catch up on.
+ *
+ * Discovery, build, and attach all happen inside `start()`, matching every
+ * other `Collector` in this repo — a routine failure to attach resolves as
+ * `{ available: false, reason }`, never a thrown exception a caller has to
+ * remember to catch.
+ */
+export declare function attachToRunningJvmProcess(options: AttachToRunningJvmProcessOptions): Collector;
+//# sourceMappingURL=attach-to-running-jvm-process.d.ts.map

package/dist/attach-to-running-jvm-process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach-to-running-jvm-process.d.ts","sourceRoot":"","sources":["../src/attach-to-running-jvm-process.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AAOH,OAAO,KAAK,EAAE,SAAS,EAAyF,MAAM,4BAA4B,CAAC;AAMnJ,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,+IAA+I;IAC/I,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,iLAAiL;IACjL,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,iEAAiE;IACjE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE;QACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;KACnC,CAAC;CACH;AAsKD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,gCAAgC,GAAG,SAAS,CAwH9F"}

package/dist/attach-to-running-jvm-process.js

@@ -0,0 +1,338 @@
+/**
+ * Retroactive attach to an already-running **JVM (Java/Kotlin/…)** process —
+ * the JVM item on `RT-attach-to-running-process-scope.md`'s own
+ * "deliberately not built" list, and `RT-attach-to-running-jvm-process.md`
+ * (decisions-inbox) is the short record of what got measured before any of
+ * this was written and why the slice below is the honest first one, not a
+ * full CDP-equivalent.
+ *
+ * **The real mechanism, measured against a live JVM on this machine, not
+ * assumed from docs.** The JVM ships no built-in signal-to-inspector path
+ * the way Node's `SIGUSR1` does. What it does ship, since JDK 6, is the
+ * HotSpot Dynamic Attach mechanism: a launcher process calls
+ * `com.sun.tools.attach.VirtualMachine.attach(pid)`, which creates
+ * `.attach_pid<pid>` and signals the target with `SIGQUIT`; the target's own
+ * attach-listener thread (started lazily on first use, already running in
+ * every stock HotSpot JVM — nothing needs to be enabled at the target's own
+ * launch) opens a Unix-domain socket at `.java_pid<pid>` in its temp
+ * directory and accepts commands over it. `jcmd`/`jstack`/`VisualVM` all use
+ * exactly this. Measured directly here: attached to a plain `java
+ * QuietServer` process with no `-agentlib`/`-Djdk.attach` flags of any kind
+ * and no restart, confirming this is genuinely retroactive, the same
+ * standing Node's `SIGUSR1` slice has.
+ *
+ * **What this channel can actually give — measured, and narrower than
+ * CDP.** `VirtualMachine.loadAgent(jar, args)` loads a real Java agent
+ * (`java.lang.instrument.Instrumentation`) into the target's own JVM,
+ * running as that JVM's own code — a strictly more powerful primitive than
+ * CDP's remote-debugging protocol. This first slice used only the cheapest
+ * real capability inside it: `Thread.setDefaultUncaughtExceptionHandler`
+ * (`jvm-agent/Agent.java`), which needs no bytecode instrumentation at all,
+ * and **did not see an exception a framework already caught** — a request
+ * handler's own try/catch, a servlet container's default error page, any
+ * `@ExceptionHandler` — because by definition those exceptions never reach
+ * "uncaught." `SelfFailingServer.java` (the existing execute-mode fixture)
+ * catches and logs its own thrown exception for exactly this reason, so it
+ * is not a fixture this module's own test can reuse; see
+ * `test/fixtures/jvm-attach/BackgroundThreadThrows.java`, a real thread that
+ * throws with nothing catching it, the one shape that first slice could see.
+ *
+ * **RT-201 closed one specific, real instance of that gap**, using the same
+ * `Instrumentation` this module already hands the agent: `Agent.java` now
+ * also installs a ByteBuddy `ClassFileTransformer` (see that file's own
+ * header comment for the full mechanism and what was measured) that taps
+ * `org.springframework.web.servlet.DispatcherServlet#processHandlerException`
+ * — Spring MVC's single stable choke point for every exception-handling
+ * path — and reports what it catches as a `"framework-caught-exception"`
+ * event, parsed below as `isFrameworkCaughtExceptionEvent` and emitted as
+ * `EXCEPTION` evidence with `payload.handled === true`. **This closes only
+ * that one choke point.** A catch that never reaches Spring's dispatcher —
+ * absorbed inside a `@Service` method, logged nowhere — is still invisible,
+ * and no non-Spring framework is instrumented at all. `Runtime.exceptionThrown`'s
+ * CDP-side reach (any throw the debugger is configured to pause on,
+ * regardless of framework) still has no equivalent here.
+ *
+ * **No console-output capture in this slice.** Unlike CDP's
+ * `Runtime.consoleAPICalled`, `System.out`/`System.err` are not intercepted
+ * — a target already logging to a file is exactly `attachToRunningProcess`'s
+ * (the file-based sibling) job, and duplicating that here would be two
+ * mechanisms claiming the same evidence. `capabilities()` reports
+ * `backendLogAccess` unavailable for that reason, unlike the Node slice.
+ *
+ * **Launcher is a real JDK tool process, not a library call.** There is no
+ * Node/native binding for the Attach API in this repo and none is added —
+ * `jvm-agent/build.ts` compiles `Attacher.java` once (cached by mtime, same
+ * rule `kotlin-server/build.ts` already uses) and this module spawns it as a
+ * short-lived `java` child process, the same "one helper invocation, not a
+ * new protocol client" shape `discoverNodeInspectorUrl`'s `process.kill`
+ * call has, just through a JDK tool instead of a POSIX signal.
+ */
+import { existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { isProcessAlive } from "./attach-to-running-process.js";
+import { buildJvmAgentJar, buildAttacherClass, findToolsJarIfPresent } from "./jvm-agent/build.js";
+import { COLLECTOR_VERSION } from "./collector-version.js";
+/**
+ * Reconstruct a repo-relative source path from a JVM frame's fully-qualified
+ * declaring class name and basename, or `null` when it cannot be done
+ * exactly — the attach path's copy of
+ * `jvm-stack-trace-parser.ts`'s `reconstructPath`; see this file's own
+ * `AttachToRunningJvmProcessOptions.sourceRoots` doc for why it is a copy
+ * rather than a shared import.
+ *
+ * Null in four cases, each a real one rather than a fallback: no source
+ * roots declared, no basename, no package (a default-package class, where
+ * `declaringType` has no dot), or no candidate that exists on disk.
+ */
+function reconstructJvmSourcePath(declaringType, file, sourceRoots) {
+    if (sourceRoots === undefined || file === null)
+        return null;
+    if (file.includes("/"))
+        return null;
+    const lastDot = declaringType.lastIndexOf(".");
+    if (lastDot === -1)
+        return null;
+    const packagePath = declaringType.slice(0, lastDot).split(".").join("/");
+    for (const root of sourceRoots.roots) {
+        const candidate = `${root}/${packagePath}/${file}`;
+        if (existsSync(join(sourceRoots.repoRoot, candidate)))
+            return candidate;
+    }
+    return null;
+}
+function isUncaughtExceptionEvent(value) {
+    return typeof value === "object" && value !== null && value.type === "uncaught-exception";
+}
+function isFrameworkCaughtExceptionEvent(value) {
+    return typeof value === "object" && value !== null && value.type === "framework-caught-exception";
+}
+/**
+ * `StackTraceElement.getFileName()` is always a BARE name — `"ProbeApplication.java"`,
+ * never `"probe/ProbeApplication.java"` — because the JVM never recorded a
+ * package-relative path in the first place, only a plain source-file
+ * attribute. Found while proving RT-201's graph correlation directly (this
+ * collector's own pre-existing uncaught-exception path had never been
+ * pushed through `resolveSymbolNode`, so this was never exercised): a bare
+ * filename resolves nothing against a graph, whose nodes carry
+ * `src/main/java/probe/ProbeApplication.java`-shaped repo-relative paths.
+ *
+ * `className` (the fully-qualified class name, always present) is what
+ * recovers the missing directory — the same information `logback-log-envelope.ts`'s
+ * parser already uses on the log-tailing side, applied here for the attach
+ * side, which had never needed it before this collector's evidence was
+ * first asked to resolve against a graph. `className.split("$")[0]` drops
+ * a nested/anonymous-class suffix (`Outer$Inner`, `Outer$1`) to recover the
+ * OUTER class's package — nested classes are declared in their outer
+ * class's own file, never their own. The result is package-*relative*, not
+ * repo-relative — this is the fallback `frameToStackFrame` uses when
+ * `reconstructJvmSourcePath` above cannot produce a validated repo-relative
+ * path (no `sourceRoots` declared, or no candidate exists on disk); a
+ * caller with no `sourceRoots` still gets a directory instead of a bare
+ * basename, and can supply the rest via `resolveSymbolNode`'s own `cwd`
+ * option, exactly as documented there.
+ *
+ * Deliberately does NOT rename or reshape `frame.fileName` itself — Kotlin
+ * breaks the "file name matches class name" assumption outright (a class
+ * `Foo` may be declared in `Bar.kt`), so only the *directory* is derived
+ * from the class name; the file's own name is always the runtime's, verbatim.
+ */
+function packageRelativeFile(frame) {
+    if (frame.fileName === null)
+        return null;
+    const outerClassName = frame.className.split("$")[0];
+    const lastDot = outerClassName.lastIndexOf(".");
+    if (lastDot === -1)
+        return frame.fileName; // default package — no directory to prepend
+    const packagePath = outerClassName.slice(0, lastDot).replaceAll(".", "/");
+    return `${packagePath}/${frame.fileName}`;
+}
+function frameToStackFrame(frame, sourceRoots) {
+    return {
+        location: {
+            file: reconstructJvmSourcePath(frame.className, frame.fileName, sourceRoots) ?? packageRelativeFile(frame),
+            line: frame.lineNumber > 0 ? frame.lineNumber : null,
+            column: null,
+            functionName: `${frame.className}.${frame.methodName}`,
+            // Self-contained: `StackTraceElement` is the JVM's own reported state,
+            // captured live off the running process — never a side artifact this
+            // collector resolved through, the same standing CDP's call frames get
+            // in the Node slice.
+            reliability: "self-contained",
+            resolvedVia: null,
+        },
+        raw: `${frame.className}.${frame.methodName}(${frame.fileName ?? "unknown"}:${String(frame.lineNumber)})`,
+    };
+}
+function notThisCollectorsJob(what) {
+    return { availability: "unavailable", reason: `attachToRunningJvmProcess observes only genuinely uncaught JVM exceptions via a loaded agent's default handler, not ${what}.` };
+}
+const CAPABILITIES = {
+    domObservation: notThisCollectorsJob("DOM inspection"),
+    consoleObservation: notThisCollectorsJob("a browser page's console"),
+    networkObservation: notThisCollectorsJob("network traffic"),
+    // Deliberately unavailable, unlike the Node slice — this module does not
+    // intercept System.out/err; that is attachToRunningProcess's job for a
+    // target already logging to a file, and duplicating it here would be two
+    // mechanisms claiming the same evidence.
+    backendLogAccess: notThisCollectorsJob("console/log output — see attachToRunningProcess for a target logging to a file"),
+    distributedTrace: notThisCollectorsJob("trace-id/request-id correlation — the loaded agent extracts none"),
+    sourceMapping: { availability: "available", reason: null },
+    stackCapture: { availability: "available", reason: null },
+    processLifecycle: notThisCollectorsJob("process lifecycle — spawn/ready/exit are ProcessCollector's to observe"),
+    databaseObservation: notThisCollectorsJob("database queries"),
+    externalServiceObservation: notThisCollectorsJob("outbound external requests"),
+};
+/**
+ * Runs the compiled `Attacher` helper against `pid`, loading `agent.jar`
+ * with `outputFilePath` as its argument. Resolves once the helper process
+ * exits 0 (attach + loadAgent both succeeded); rejects with the helper's own
+ * stderr otherwise — never guesses at success from silence.
+ */
+function runAttacher(pid, agentJarPath, outputFilePath, attacherDir, attachTimeoutMs) {
+    const toolsJar = findToolsJarIfPresent();
+    const classpath = toolsJar !== null ? `${attacherDir}:${toolsJar}` : attacherDir;
+    const result = spawnSync("java", ["-cp", classpath, "Attacher", String(pid), agentJarPath, outputFilePath], {
+        encoding: "utf8",
+        timeout: attachTimeoutMs,
+    });
+    if (result.error !== undefined) {
+        return { ok: false, reason: `attachToRunningJvmProcess: could not launch the java Attacher helper: ${result.error.message}` };
+    }
+    if (result.status !== 0) {
+        const detail = (result.stderr ?? "").trim() || (result.stdout ?? "").trim() || `exit code ${String(result.status)}`;
+        return { ok: false, reason: `attachToRunningJvmProcess: Attacher failed to attach to pid ${String(pid)}: ${detail}` };
+    }
+    return { ok: true };
+}
+/**
+ * Attach to an already-running JVM process via the HotSpot Dynamic Attach
+ * mechanism, load a minimal Java agent, and start capturing genuinely
+ * uncaught exceptions as `EXCEPTION` evidence from that moment forward.
+ *
+ * **Retroactive, not historical** — same as the Node slice: an exception
+ * thrown before the agent finishes loading is not captured, because the
+ * default handler was not installed yet. There is no backlog to catch up on.
+ *
+ * Discovery, build, and attach all happen inside `start()`, matching every
+ * other `Collector` in this repo — a routine failure to attach resolves as
+ * `{ available: false, reason }`, never a thrown exception a caller has to
+ * remember to catch.
+ */
+export function attachToRunningJvmProcess(options) {
+    let stopped = false;
+    return {
+        collectorId: `attach-jvm-agent:${options.processId}`,
+        async start(context) {
+            if (!isProcessAlive(options.pid)) {
+                return { available: false, reason: `attachToRunningJvmProcess: pid ${String(options.pid)} is not running — cannot attach to a target that does not exist.` };
+            }
+            if (process.platform === "win32") {
+                return { available: false, reason: "attachToRunningJvmProcess: HotSpot Dynamic Attach as used here relies on a Unix domain socket; not available on win32." };
+            }
+            let agentJarPath;
+            let attacherDir;
+            try {
+                agentJarPath = await buildJvmAgentJar();
+                attacherDir = buildAttacherClass();
+            }
+            catch (error) {
+                return { available: false, reason: error instanceof Error ? error.message : String(error) };
+            }
+            const dir = mkdtempSync(join(tmpdir(), "descry-jvm-attach-"));
+            const outFile = join(dir, "events.log");
+            writeFileSync(outFile, "");
+            const attached = runAttacher(options.pid, agentJarPath, outFile, attacherDir, options.attachTimeoutMs ?? 10_000);
+            if (!attached.ok) {
+                return { available: false, reason: attached.reason };
+            }
+            const pollIntervalMs = options.pollIntervalMs ?? 50;
+            let consumed = 0;
+            const poll = async () => {
+                for (;;) {
+                    if (stopped)
+                        return;
+                    if (!existsSync(outFile)) {
+                        await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+                        continue;
+                    }
+                    const whole = readFileSync(outFile, "utf8");
+                    if (whole.length > consumed) {
+                        const chunk = whole.slice(consumed);
+                        consumed = whole.length;
+                        for (const rawLine of chunk.split("\n")) {
+                            const line = rawLine.trim();
+                            if (line === "")
+                                continue;
+                            let parsed;
+                            try {
+                                parsed = JSON.parse(line);
+                            }
+                            catch {
+                                // A partially-flushed line read mid-write — will be
+                                // re-attempted whole once the writer finishes, since
+                                // `consumed` only advances past what was actually parsed
+                                // here... except it already advanced past this chunk. In
+                                // practice this cannot happen: Agent.java opens, writes one
+                                // full line, and closes the file per event (see its own
+                                // module doc), so a poll tick never observes a half-written
+                                // line. Dropped rather than guessed at if it ever does.
+                                continue;
+                            }
+                            if (isUncaughtExceptionEvent(parsed) || isFrameworkCaughtExceptionEvent(parsed)) {
+                                const frames = parsed.frames.map((frame) => frameToStackFrame(frame, options.sourceRoots));
+                                const stackTrace = frames.length > 0
+                                    ? { fidelity: "synchronous", frames, primaryFrameIndex: 0 }
+                                    : { fidelity: "synchronous", frames: [], primaryFrameIndex: 0 };
+                                context.emit({
+                                    timestamp: new Date().toISOString(),
+                                    source: "backend-process",
+                                    service: options.service ?? null,
+                                    process: options.processId,
+                                    eventType: "EXCEPTION",
+                                    // `handled` distinguishes the two channels within the same
+                                    // `RuntimeEventType` rather than adding a new event type to
+                                    // that closed vocabulary (see `runtime-event.ts`'s own "the
+                                    // graph vocabulary is frozen; this one is not" — still, a
+                                    // new *member* is a deliberate, reviewed change, not one to
+                                    // make for a single collector's internal distinction) —
+                                    // `true` for RT-201's DispatcherServlet advice tap, `false`
+                                    // for a genuinely uncaught exception nothing in the JVM
+                                    // ever caught. Additive: existing consumers reading only
+                                    // `.message`/`.stack` off this payload are unaffected.
+                                    payload: { message: `${parsed.exceptionClass}: ${parsed.message ?? ""}`.trim(), stack: null, handled: parsed.type === "framework-caught-exception" },
+                                    traceId: null,
+                                    requestId: null,
+                                    correlationId: null,
+                                    graphNodeId: null,
+                                    sourceLocation: frames[0]?.location ?? null,
+                                    stackTrace: frames.length > 0 ? stackTrace : null,
+                                    confidence: 1,
+                                    redactionStatus: "pending-redaction",
+                                    collectorVersion: COLLECTOR_VERSION,
+                                });
+                            }
+                            // "agent-loaded", "framework-instrumentation-installed",
+                            // "framework-instrumentation-unavailable", and any future
+                            // marker type: acknowledged by being parsed, not turned into
+                            // evidence — internal bookkeeping, not something observed
+                            // about the target.
+                        }
+                    }
+                    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+                }
+            };
+            void poll();
+            return { available: true };
+        },
+        stop() {
+            stopped = true;
+            return Promise.resolve();
+        },
+        capabilities() {
+            return CAPABILITIES;
+        },
+    };
+}
+//# sourceMappingURL=attach-to-running-jvm-process.js.map

package/dist/attach-to-running-jvm-process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach-to-running-jvm-process.js","sourceRoot":"","sources":["../src/attach-to-running-jvm-process.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC/E,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAI/C,OAAO,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACnG,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAwD3D;;;;;;;;;;;GAWG;AACH,SAAS,wBAAwB,CAC/B,aAAqB,EACrB,IAAmB,EACnB,WAA4D;IAE5D,IAAI,WAAW,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC5D,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAEpC,MAAM,OAAO,GAAG,aAAa,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC/C,IAAI,OAAO,KAAK,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAChC,MAAM,WAAW,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAEzE,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,KAAK,EAAE,CAAC;QACrC,MAAM,SAAS,GAAG,GAAG,IAAI,IAAI,WAAW,IAAI,IAAI,EAAE,CAAC;QACnD,IAAI,UAAU,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;YAAE,OAAO,SAAS,CAAC;IAC1E,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AA0BD,SAAS,wBAAwB,CAAC,KAAc;IAC9C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAK,KAA4B,CAAC,IAAI,KAAK,oBAAoB,CAAC;AACpH,CAAC;AAED,SAAS,+BAA+B,CAAC,KAAc;IACrD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAK,KAA4B,CAAC,IAAI,KAAK,4BAA4B,CAAC;AAC5H,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,SAAS,mBAAmB,CAAC,KAAwB;IACnD,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACzC,MAAM,cAAc,GAAG,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC;IACtD,MAAM,OAAO,GAAG,cAAc,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAChD,IAAI,OAAO,KAAK,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC,QAAQ,CAAC,CAAC,4CAA4C;IACvF,MAAM,WAAW,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC1E,OAAO,GAAG,WAAW,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;AAC5C,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAwB,EAAE,WAA4D;IAC/G,OAAO;QACL,QAAQ,EAAE;YACR,IAAI,EAAE,wBAAwB,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,QAAQ,EAAE,WAAW,CAAC,IAAI,mBAAmB,CAAC,KAAK,CAAC;YAC1G,IAAI,EAAE,KAAK,CAAC,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI;YACpD,MAAM,EAAE,IAAI;YACZ,YAAY,EAAE,GAAG,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,UAAU,EAAE;YACtD,uEAAuE;YACvE,qEAAqE;YACrE,sEAAsE;YACtE,qBAAqB;YACrB,WAAW,EAAE,gBAAgB;YAC7B,WAAW,EAAE,IAAI;SAClB;QACD,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,UAAU,IAAI,KAAK,CAAC,QAAQ,IAAI,SAAS,IAAI,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG;KAC1G,CAAC;AACJ,CAAC;AAED,SAAS,oBAAoB,CAAC,IAAY;IACxC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,EAAE,uHAAuH,IAAI,GAAG,EAAE,CAAC;AACjL,CAAC;AAED,MAAM,YAAY,GAA0B;IAC1C,cAAc,EAAE,oBAAoB,CAAC,gBAAgB,CAAC;IACtD,kBAAkB,EAAE,oBAAoB,CAAC,0BAA0B,CAAC;IACpE,kBAAkB,EAAE,oBAAoB,CAAC,iBAAiB,CAAC;IAC3D,yEAAyE;IACzE,uEAAuE;IACvE,yEAAyE;IACzE,yCAAyC;IACzC,gBAAgB,EAAE,oBAAoB,CAAC,gFAAgF,CAAC;IACxH,gBAAgB,EAAE,oBAAoB,CAAC,kEAAkE,CAAC;IAC1G,aAAa,EAAE,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE;IAC1D,YAAY,EAAE,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE;IACzD,gBAAgB,EAAE,oBAAoB,CAAC,wEAAwE,CAAC;IAChH,mBAAmB,EAAE,oBAAoB,CAAC,kBAAkB,CAAC;IAC7D,0BAA0B,EAAE,oBAAoB,CAAC,4BAA4B,CAAC;CAC/E,CAAC;AAEF;;;;;GAKG;AACH,SAAS,WAAW,CAAC,GAAW,EAAE,YAAoB,EAAE,cAAsB,EAAE,WAAmB,EAAE,eAAuB;IAC1H,MAAM,QAAQ,GAAG,qBAAqB,EAAE,CAAC;IACzC,MAAM,SAAS,GAAG,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,GAAG,WAAW,IAAI,QAAQ,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC;IACjF,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,YAAY,EAAE,cAAc,CAAC,EAAE;QAC1G,QAAQ,EAAE,MAAM;QAChB,OAAO,EAAE,eAAe;KACzB,CAAC,CAAC;IACH,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,yEAAyE,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;IAChI,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,MAAM,GAAG,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,aAAa,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;QACpH,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,+DAA+D,MAAM,CAAC,GAAG,CAAC,KAAK,MAAM,EAAE,EAAE,CAAC;IACxH,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAAyC;IACjF,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,OAAO;QACL,WAAW,EAAE,oBAAoB,OAAO,CAAC,SAAS,EAAE;QAEpD,KAAK,CAAC,KAAK,CAAC,OAAyB;YACnC,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;gBACjC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,kCAAkC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,kEAAkE,EAAE,CAAC;YAC/J,CAAC;YACD,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;gBACjC,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,wHAAwH,EAAE,CAAC;YAChK,CAAC;YAED,IAAI,YAAoB,CAAC;YACzB,IAAI,WAAmB,CAAC;YACxB,IAAI,CAAC;gBACH,YAAY,GAAG,MAAM,gBAAgB,EAAE,CAAC;gBACxC,WAAW,GAAG,kBAAkB,EAAE,CAAC;YACrC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9F,CAAC;YAED,MAAM,GAAG,GAAG,WAAW,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,oBAAoB,CAAC,CAAC,CAAC;YAC9D,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;YACxC,aAAa,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YAE3B,MAAM,QAAQ,GAAG,WAAW,CAAC,OAAO,CAAC,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,CAAC,eAAe,IAAI,MAAM,CAAC,CAAC;YACjH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;YACvD,CAAC;YAED,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,EAAE,CAAC;YACpD,IAAI,QAAQ,GAAG,CAAC,CAAC;YAEjB,MAAM,IAAI,GAAG,KAAK,IAAmB,EAAE;gBACrC,SAAS,CAAC;oBACR,IAAI,OAAO;wBAAE,OAAO;oBACpB,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;wBACzB,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC;wBACpE,SAAS;oBACX,CAAC;oBACD,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;oBAC5C,IAAI,KAAK,CAAC,MAAM,GAAG,QAAQ,EAAE,CAAC;wBAC5B,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;wBACpC,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC;wBACxB,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;4BACxC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;4BAC5B,IAAI,IAAI,KAAK,EAAE;gCAAE,SAAS;4BAC1B,IAAI,MAAe,CAAC;4BACpB,IAAI,CAAC;gCACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;4BAC5B,CAAC;4BAAC,MAAM,CAAC;gCACP,oDAAoD;gCACpD,qDAAqD;gCACrD,yDAAyD;gCACzD,yDAAyD;gCACzD,4DAA4D;gCAC5D,wDAAwD;gCACxD,4DAA4D;gCAC5D,wDAAwD;gCACxD,SAAS;4BACX,CAAC;4BACD,IAAI,wBAAwB,CAAC,MAAM,CAAC,IAAI,+BAA+B,CAAC,MAAM,CAAC,EAAE,CAAC;gCAChF,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,iBAAiB,CAAC,KAAK,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;gCAC3F,MAAM,UAAU,GAAe,MAAM,CAAC,MAAM,GAAG,CAAC;oCAC9C,CAAC,CAAC,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC,EAAE;oCAC3D,CAAC,CAAC,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,EAAE,EAAE,iBAAiB,EAAE,CAAC,EAAE,CAAC;gCAClE,OAAO,CAAC,IAAI,CAAC;oCACX,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;oCACnC,MAAM,EAAE,iBAAiB;oCACzB,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,IAAI;oCAChC,OAAO,EAAE,OAAO,CAAC,SAAS;oCAC1B,SAAS,EAAE,WAAW;oCACtB,2DAA2D;oCAC3D,4DAA4D;oCAC5D,4DAA4D;oCAC5D,0DAA0D;oCAC1D,4DAA4D;oCAC5D,wDAAwD;oCACxD,4DAA4D;oCAC5D,wDAAwD;oCACxD,yDAAyD;oCACzD,uDAAuD;oCACvD,OAAO,EAAE,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,cAAc,KAAK,MAAM,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,KAAK,4BAA4B,EAAE;oCACpJ,OAAO,EAAE,IAAI;oCACb,SAAS,EAAE,IAAI;oCACf,aAAa,EAAE,IAAI;oCACnB,WAAW,EAAE,IAAI;oCACjB,cAAc,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,QAAQ,IAAI,IAAI;oCAC3C,UAAU,EAAE,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI;oCACjD,UAAU,EAAE,CAAC;oCACb,eAAe,EAAE,mBAAmB;oCACpC,gBAAgB,EAAE,iBAAiB;iCACpC,CAAC,CAAC;4BACL,CAAC;4BACD,yDAAyD;4BACzD,0DAA0D;4BAC1D,6DAA6D;4BAC7D,0DAA0D;4BAC1D,oBAAoB;wBACtB,CAAC;oBACH,CAAC;oBACD,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC;gBACtE,CAAC;YACH,CAAC,CAAC;YACF,KAAK,IAAI,EAAE,CAAC;YAEZ,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QAC7B,CAAC;QAED,IAAI;YACF,OAAO,GAAG,IAAI,CAAC;YACf,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC;QAC3B,CAAC;QAED,YAAY;YACV,OAAO,YAAY,CAAC;QACtB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/attach-to-running-node-process.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Retroactive attach to an already-running **Node** process, via its own
+ * inspector protocol — the specific, buildable slice
+ * `documents/decisions-inbox/RT-attach-to-running-process-scope.md`
+ * deliberately did not build. That entry's own "deliberately not built"
+ * list names it directly: "Node's `SIGUSR1` inspector activation + a CDP
+ * WebSocket client — real, but Node-only and a new protocol surface, not
+ * built this pass." This is that pass, for Node only — the other two items
+ * on that list (JVM Attach API, ptrace) remain out of scope, unchanged.
+ *
+ * **What makes this genuinely retroactive, unlike `attachToRunningProcess`
+ * (the file-based sibling in this same package).** That one needs the
+ * target to have already been told, at its own launch time, to write
+ * output somewhere reachable (`> server.log 2>&1`) — narrower than "attach
+ * to anything already running." This one needs nothing declared at launch:
+ * `SIGUSR1` (POSIX only; Node's own signal handler, not something this
+ * process installs) turns on the target's inspector **after the fact**, on
+ * a process that was never started with `--inspect` and never expected to
+ * be debugged. From that moment its debugger discovery endpoint is
+ * reachable at `http://127.0.0.1:<port>/json`, by the target itself, not by
+ * anything this collector primed in advance.
+ *
+ * **The one real limit, disclosed rather than hidden.** `SIGUSR1` does not
+ * report back which port the inspector actually bound — Node prints
+ * `Debugger listening on ws://host:port/<uuid>` to the target's own
+ * *stderr*, which is exactly the channel this module's own doc (and RT-024
+ * before it) says cannot be read for a process we did not spawn. So
+ * discovery is: try the default port (9229, Node's own default and the one
+ * `SIGUSR1` binds to when nothing else is already listening there), and if
+ * a caller already knows the target was configured for a different port
+ * (`--inspect-port`, `NODE_OPTIONS`), they supply it. **If the port is
+ * genuinely unknown and is not 9229, this module cannot discover it** — not
+ * attempted, not guessed at by scanning a port range, which would risk
+ * attaching to the wrong process's inspector entirely.
+ *
+ * **CDP client: written here, not reused, because nothing reusable
+ * exists.** `packages/browser`'s console collector speaks CDP only through
+ * Playwright's own browser-automation abstraction (`page.on("console")`),
+ * which assumes a `Target`/`Page`-domain browser session — a Node inspector
+ * session has neither domain, being a single top-level `Runtime` session
+ * instead. `cdp-client.ts` in this package is the actual reusable piece:
+ * protocol-family-generic, so a future browser-side raw-CDP need could
+ * reuse it too, instead of a third client getting written.
+ *
+ * **Measured: a freshly-spawned target has a brief window, sometimes under
+ * 100ms, before Node installs its own `SIGUSR1` handler** — a signal sent
+ * inside that window hits POSIX's default action for an unhandled
+ * `SIGUSR1` (terminate) instead of toggling the inspector, killing the
+ * target rather than attaching to it. Irrelevant to this module's actual
+ * purpose — attaching to something genuinely already running, which by
+ * definition has been alive far longer than that window — but real, and
+ * worth naming for a caller tempted to attach immediately after spawning
+ * something themselves.
+ *
+ * **Measured side effect: attaching changes the target's crash behaviour.**
+ * Once a CDP client is connected, V8 no longer terminates the process
+ * immediately on an uncaught exception — it prints "Waiting for the
+ * debugger to disconnect..." to stderr and blocks, exactly as it would
+ * under a launched `--inspect-brk` session, so a human debugger gets to
+ * inspect the paused, crashed state before the process actually exits.
+ * Measured directly (a naive test that waited for the child's own `exit`
+ * event after attach hung indefinitely) rather than assumed from docs. This
+ * is standard CDP/V8 behaviour, not a defect this collector introduces, and
+ * not silently worked around: the process resumes its exit exactly when
+ * `stop()` closes the CDP session, which is also when the exception's own
+ * evidence has already been captured, so nothing about the timing costs a
+ * caller the evidence. A caller relying on "did the target exit yet?" as a
+ * signal must call `stop()` first.
+ *
+ * **What is captured, and under which vocabulary.** `Runtime.consoleAPICalled`
+ * → `CONSOLE_MESSAGE`, `Runtime.exceptionThrown` → `EXCEPTION` — the same
+ * two `RuntimeEventType`s `browser-console-collector.ts` already claims for
+ * the analogous browser-page concepts, because they are the same concepts
+ * (console output; an uncaught exception), observed on a different kind of
+ * process. `source: "backend-process"`, not a new source value — this is a
+ * backend process being observed, and `EvidenceSource` already names what
+ * was observed rather than which mechanism did it (`inbound-proxy.ts`'s own
+ * precedent, restated there for exactly this reason). `capabilities()`
+ * reports `backendLogAccess`, not `consoleObservation` — `consoleObservation`
+ * is `browser-console-collector`'s claim on a *browser page's* console,
+ * kept apart from a backend process's console the same way `LogCollector`
+ * already keeps them apart for its own text-based capture.
+ */
+import type { Collector } from "@descryy/runtime-contracts";
+export interface AttachToRunningNodeProcessOptions {
+    readonly processId: string;
+    /** The pid of the already-running target. Verified alive before SIGUSR1 is sent, and never spawned or supervised by this collector. */
+    readonly pid: number;
+    readonly service?: string;
+    /** Node's own default inspector bind address. Overridable for a target known to bind elsewhere. */
+    readonly discoveryHost?: string;
+    /**
+     * Node's own default inspector port, and the only one `SIGUSR1` reliably
+     * produces on an unmodified target. See this file's own module doc for
+     * why a non-default port cannot be discovered from outside and must be
+     * supplied here when known.
+     */
+    readonly discoveryPort?: number;
+    /** How long to poll the discovery endpoint after sending SIGUSR1 before giving up. The inspector does not bind instantaneously. */
+    readonly discoveryTimeoutMs?: number;
+}
+/**
+ * Sends `SIGUSR1` to `pid`, then polls `http://<host>:<port>/json` until the
+ * target's inspector answers or `timeoutMs` elapses. Resolves with the
+ * `webSocketDebuggerUrl` of the first entry — an already-running Node
+ * process presents exactly one inspectable target for its main thread,
+ * unlike a browser's `/json`, which lists one entry per open tab.
+ *
+ * Rejects, naming the exact blocker, rather than hanging or guessing: a pid
+ * that was never alive, a POSIX-only signal on a non-POSIX platform, or a
+ * port that never answers (most often because the real inspector bound
+ * somewhere other than `port`, which this function has no way to learn —
+ * see the module doc).
+ */
+export declare function discoverNodeInspectorUrl(pid: number, options?: {
+    readonly host?: string;
+    readonly port?: number;
+    readonly timeoutMs?: number;
+}): Promise<string>;
+/**
+ * Attach to an already-running Node process via `SIGUSR1` + CDP, and start
+ * capturing `CONSOLE_MESSAGE`/`EXCEPTION` evidence from that moment forward.
+ *
+ * **Retroactive, not historical.** Anything the target logged or threw
+ * *before* this attaches is gone — `SIGUSR1` turns the inspector on, it
+ * does not hand over a backlog. `attachToRunningProcess` (the file-based
+ * sibling) is the one that can recover pre-attach lines, and only because a
+ * file on disk already held them; nothing analogous exists for CDP, which
+ * is a live event stream with no buffer of its own.
+ *
+ * Discovery and connection happen inside `start()`, not here — matching
+ * every other `Collector` in this repo (`createBrowserConsoleCollector`,
+ * `createTestRunnerCollector`): a routine failure to attach resolves as
+ * `{ available: false, reason }`, never a thrown exception a caller has to
+ * remember to catch.
+ */
+export declare function attachToRunningNodeProcess(options: AttachToRunningNodeProcessOptions): Collector;
+//# sourceMappingURL=attach-to-running-node-process.d.ts.map

package/dist/attach-to-running-node-process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach-to-running-node-process.d.ts","sourceRoot":"","sources":["../src/attach-to-running-node-process.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkFG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAyG,MAAM,4BAA4B,CAAC;AAMnK,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uIAAuI;IACvI,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,mGAAmG;IACnG,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,mIAAmI;IACnI,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAOD;;;;;;;;;;;;GAYG;AACH,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5F,OAAO,CAAC,MAAM,CAAC,CAyCjB;AA6ED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,iCAAiC,GAAG,SAAS,CAqHhG"}