agent-nuvira 3.5.1 → 3.5.2

package/dist/tools/process-liveness.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Process liveness — is a long-running command WORKING, or is it HUNG?
+ *
+ * WHY THIS EXISTS. Handing a command to monitoring instead of killing it at a
+ * clock (see `run-terminal.ts`) removed the false failure, but it left the
+ * opposite hole open: a command that is genuinely STUCK — waiting on a prompt
+ * with no stdin, holding a lock, blocked on a socket that will never answer —
+ * now runs forever, and "it is still running" is not a diagnosis. Silence alone
+ * cannot tell the two apart, because a real test suite can be quiet for minutes
+ * while it works. The signal that separates them is CPU:
+ *
+ *   - producing output                → it is doing something
+ *   - burning CPU with no output      → it is computing (a build, a solver)
+ *   - NO output AND NO CPU for a long time → it is waiting for something that is
+ *     never coming. That is a hang, and it is a FACT about the process, not a
+ *     guess from a stopwatch.
+ *
+ * So this module samples the process TREE (the shell `spawn(..., { shell: true })`
+ * creates plus everything under it) for cumulative CPU time, and classifies a
+ * run into `working` / `stalled` / `hung` with the evidence attached. Callers
+ * decide what to do with the verdict; the one rule this module enforces is that
+ * `hung` requires POSITIVE evidence (measurable CPU that is not advancing) —
+ * when CPU cannot be measured, a long silence is reported as `stalled`, never as
+ * `hung`, because an unmeasurable process must not be reaped on a guess.
+ *
+ * Platform: on POSIX the table comes from `ps` (macOS + Linux), the same tool
+ * `src/cli/process-control.ts` already relies on. On Windows it comes from ONE
+ * `Get-CimInstance Win32_Process` query — which reports `ParentProcessId` AND
+ * `KernelModeTime` + `UserModeTime` (CPU, in 100ns units) — so the same rule
+ * works there instead of degrading to silence-only: the tree walk and the
+ * zero-CPU evidence are both available, with `wmic` as the fallback the rest of
+ * this repo already uses.
+ *
+ * One Windows semantic difference is worth stating plainly, because `kill`
+ * implies something it cannot deliver there: Windows has no graceful SIGTERM.
+ * `process.kill(pid, 'SIGTERM')` is an immediate termination, so the
+ * SIGTERM→grace→SIGKILL ladder is a POSIX-only refinement.
+ */
+/** How a long run is doing: the state a clock alone cannot distinguish. */
+export type Liveness = 'finished' | 'starting' | 'working' | 'stalled' | 'hung';
+/** The thresholds the classification is made from (ms). */
+export interface LivenessThresholds {
+    /** Silence after which a run is worth *reporting* as stalled. */
+    stallQuietMs: number;
+    /** Silence after which, WITH no CPU, a run is HUNG. */
+    hangQuietMs: number;
+    /** CPU ms over one sample window that counts as "it is computing". */
+    hangCpuFloorMs: number;
+}
+export declare const DEFAULT_LIVENESS_THRESHOLDS: LivenessThresholds;
+/**
+ * The thresholds, with env overrides — read at CALL time, not module load, so a
+ * test (or an operator) can change them without re-importing.
+ *
+ * `NUVIRA_HANG_QUIET_MS` is the one that matters operationally: it is how long a
+ * command may be silent AND idle before the agent is told it is hung.
+ */
+export declare function livenessThresholds(env?: NodeJS.ProcessEnv): LivenessThresholds;
+/**
+ * Parse a `ps -o time=` value into milliseconds of cumulative CPU.
+ *
+ * Formats seen in the wild: `MM:SS.cc` (macOS), `HH:MM:SS` (Linux), and
+ * `DD-HH:MM:SS` (BSD, for a long-lived process). A value that does not parse is
+ * `null` — the caller must treat "no reading" differently from "no CPU", or a
+ * formatting change would read as a hang.
+ */
+export declare function parseCpuTime(text: string): number | null;
+export interface ProcessTreeSample {
+    /** The root pid was found in the process table. */
+    found: boolean;
+    /** Cumulative CPU (ms) of the root AND every descendant; null = unmeasurable. */
+    cpuMs: number | null;
+    /** The tree, root first, children after (deepest last) — the kill order. */
+    pids: number[];
+}
+/** One row of the process table. */
+export interface ProcessRow {
+    ppid: number;
+    /** Cumulative CPU (user+sys) ms of THIS process; null = unmeasurable. */
+    cpuMs: number | null;
+    /** The process line, when the platform reports one (used for identity checks). */
+    command: string | null;
+    /**
+     * When the OS says this process STARTED, as an opaque per-platform token —
+     * `lstart` text on POSIX, Windows file-time ticks. `null` = unreadable.
+     *
+     * It exists to answer one question a pid cannot: is this the SAME process?
+     * A pid is a number the kernel reuses (Windows recycles aggressively, Linux
+     * wraps at a few million), so `pid === 1234` is not identity — it is a hint.
+     * This is a VALUE the kernel will not hand to two different processes, which
+     * is what makes it a witness. Kept as the raw token rather than a parsed date
+     * on purpose: two reads of the same process produce the same token, and
+     * comparing tokens cannot be skewed by a clock step, a timezone change or a
+     * rounding error. Unknown stays `null`, never a fabricated value.
+     */
+    startedAtText: string | null;
+}
+export type ProcessTable = Map<number, ProcessRow>;
+/**
+ * Parse a POSIX process table: `ps -eo pid=,ppid=,time=,lstart=,command=` — and
+ * the older `…,command=` shape, which parses identically minus the start token.
+ *
+ * The command column is LAST on purpose: it may contain spaces and anything else,
+ * so everything after the known fields is taken verbatim.
+ */
+export declare function parsePosixProcessTable(stdout: string): ProcessTable;
+/**
+ * Parse the Windows probe: `<pid>|<ppid>|<kernel 100ns>|<user 100ns>|<command>`.
+ *
+ * The pipe-delimited shape is the one `src/cli/process-control.ts` already uses
+ * for the same reason: it survives command lines that contain spaces, commas or
+ * quotes. A process whose CPU counters are unreadable (`KernelModeTime` is null
+ * for some system processes) yields an EMPTY field, which must stay
+ * "unmeasurable" — not zero — or an unreadable counter would read as a hang.
+ *
+ * 100ns units are converted to ms (÷10 000), the same unit `ps` reports in.
+ */
+export declare function parseWindowsProcessTable(stdout: string): ProcessTable;
+/**
+ * Parse the `wmic … /format:csv` fallback.
+ *
+ * Header-driven, because wmic emits its columns in QUERY order and the values
+ * themselves can contain commas — so the header is the only reliable index.
+ */
+export declare function parseWmicProcessTable(stdout: string): ProcessTable;
+/**
+ * One process table read, for a caller that needs the SAME view several times.
+ *
+ * A sample tick asks about every monitored run and then signals some of them, and
+ * on Windows each read costs a PowerShell start — so the tick reads the table ONCE
+ * and threads it through, instead of N times.
+ *
+ * Deliberately NOT a time-based cache. A cached table can answer about a snapshot
+ * taken before a process existed, and the answer it gives is "not found" — which
+ * a caller reads as "it is gone". That is the one direction this module must never
+ * guess in.
+ */
+export declare function processTableSnapshot(): ProcessTable | null;
+/**
+ * Sample the process tree rooted at `pid`: whether it exists, what it has cost
+ * in CPU so far, and every pid in it.
+ *
+ * The tree is the point. `spawn(command, { shell: true })` means the REAL work
+ * is a child of the shell we hold the handle to, so a sample (and a stop) that
+ * only looked at the root would report the shell's own ~0 CPU while the build
+ * underneath burned a core — the exact false hang this must not produce.
+ */
+export declare function processTreeOf(table: ProcessTable, pid: number): ProcessTreeSample;
+export declare function sampleProcessTree(pid: number, table?: ProcessTable | null): ProcessTreeSample;
+/**
+ * Is this pid running? `null` means THIS PLATFORM CANNOT TELL.
+ *
+ * The distinction is load-bearing for a run recovered from disk: "not found"
+ * must never be read as "finished" on a platform where the process table is not
+ * readable, or a restart would declare live work dead (and a dead run's recorded
+ * exit code would be reported as its verdict).
+ */
+export declare function processAlive(pid: number): boolean | null;
+/**
+ * `processAlive`, answered from a table the caller ALREADY read — so a tick that
+ * samples every monitored run (and reconciles the recovered ones) costs one
+ * process listing, not one per run.
+ */
+export declare function tableAlive(table: ProcessTable | null, pid: number): boolean | null;
+/**
+ * One process's row, cross-platform: `null` when the platform cannot read the
+ * table at all, `{ found: false }` when the pid is simply not there.
+ *
+ * The distinction matters to a caller that has to decide whether a pid is still
+ * OURS: "gone" is an answer, "cannot tell" is not.
+ */
+export declare function lookupProcess(pid: number): {
+    found: boolean;
+    command: string | null;
+    startedAtText: string | null;
+} | null;
+export interface LivenessInput {
+    /** The run still exists (the registry has not seen it exit). */
+    alive: boolean;
+    /** Bytes produced since the run started. */
+    bytes: number;
+    /** ms since the last output byte (or since the start when nothing came). */
+    quietMs: number;
+    /** ms since the run started. */
+    ageMs: number;
+    /** CPU ms now, and at the previous sample (null = unmeasurable). */
+    cpuMs: number | null;
+    prevCpuMs: number | null;
+    /** ms between the two CPU samples. */
+    sampleWindowMs: number;
+}
+export interface LivenessVerdict {
+    verdict: Liveness;
+    /** The evidence, in words — this is what the agent and the operator read. */
+    why: string;
+}
+/** `45s` / `3m 05s` — how long, for a human reading a message. */
+export declare function formatSpan(ms: number): string;
+/**
+ * Classify a run from its evidence. Deterministic and pure, so the decision can
+ * be asserted directly instead of inferred from a message.
+ *
+ * Order matters, and it is deliberately "innocent until proven hung":
+ * output recently → working; CPU advancing → working; only then, silence PLUS a
+ * measurable absence of CPU → hung. Anything we cannot prove lands in `stalled`,
+ * which is reported but never reaped.
+ */
+export declare function classifyLiveness(input: LivenessInput, thresholds?: LivenessThresholds): LivenessVerdict;
+/**
+ * Stop a process TREE, deepest first — the shell we spawned and the real work
+ * under it.
+ *
+ * A plain `child.kill()` reaches only the shell, which is why a "stopped" hung
+ * build can keep running: the shell dies, the compiler it launched does not.
+ * Best-effort throughout — a pid that exited between the sample and the signal
+ * must not throw, and a failed signal falls back to the child handle.
+ *
+ * On Windows the tree comes from WMI (`Get-CimInstance`), so this genuinely
+ * reaches grandchildren there too; if that probe is unavailable the tree is just
+ * the root, which is the old behaviour rather than a regression. Note that a
+ * Windows "signal" takes effect immediately — there is no graceful SIGTERM to
+ * follow with a SIGKILL.
+ */
+export declare function killProcessTree(pid: number, signal: NodeJS.Signals, child?: {
+    kill(signal?: NodeJS.Signals | number): boolean;
+}, table?: ProcessTable | null): number[];
+//# sourceMappingURL=process-liveness.d.ts.map

package/dist/tools/process-liveness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-liveness.d.ts","sourceRoot":"","sources":["../../src/tools/process-liveness.ts"],"names":[],"mappings":"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"}