@vibe-agent-toolkit/cli 0.2.0-rc.11 → 0.2.0-rc.12

package/dist/commands/resources/check-supervisor.d.ts

@@ -15,12 +15,20 @@
  *   JS — which is why the parse pool's `terminate()` genuinely works — but a
  *   thread inside a synchronous native call is not spinning in JS. Do NOT
  *   "align" this design with the parse pool's.
- * - **A signal handler is a REGRESSION.** A process blocked in synchronous
- *   `node:sqlite` dies INSTANTLY on SIGINT while no handler is installed, and
- *   SURVIVES both SIGINT and SIGTERM once one is — the handler is a JS callback,
- *   and the event loop that would schedule it is the resource that is blocked.
- *   Installing one removes the operator's Ctrl-C. There is no
- *   `process.on('SIGINT')` here and there must never be.
+ * - **A signal handler in the process RUNNING THE SQL is a REGRESSION.** A
+ *   process blocked in synchronous `node:sqlite` dies INSTANTLY on SIGINT while
+ *   no handler is installed, and SURVIVES both SIGINT and SIGTERM once one is —
+ *   the handler is a JS callback, and the event loop that would schedule it is
+ *   the resource that is blocked. Installing one removes the operator's Ctrl-C.
+ *   That process — the supervised child, or this command under `--budget 0` —
+ *   must never have a `process.on(<signal>)`, and nothing on its path installs
+ *   one.
+ *
+ *   The SUPERVISING process may, and does: its event loop only waits on the
+ *   child, so a handler there fires. It guards every `TERMINATING_SIGNALS`
+ *   member (through `handleTerminatingSignals`, the one way a handler is
+ *   installed) for exactly the duration of a supervision, only to take the
+ *   child down with it and re-raise; see `guardSupervision`.
  * - **The kill is `SIGKILL` because SIGKILL cannot be REGRESSED.** No code the
  *   child runs, now or after any future edit, can handle, ignore or block it.
  *
@@ -82,11 +90,64 @@
  *
  * ## Why the child is the CLI itself
  *
- * The child is `vat resources check` with a hidden `--cost-log` flag, running
+ * The child is `vat resources check` with a hidden `--supervised-by` flag, running
  * the ordinary in-process path. Forking the logic would give the supervised lane
  * and the unsupervised one two implementations of the same gate — and the one
  * nobody runs interactively is the one that would rot.
+ *
+ * ## ⚠️ When the SUPERVISOR dies
+ *
+ * Its signal handlers and `exit` guard take the child down on every ending that
+ * runs its code (see `guardSupervision`). SIGKILL, an OOM killer and, on Windows,
+ * any outside kill run none of it.
+ *
+ * - **Windows**: the OS takes the child down. libuv puts every child spawned
+ *   without `detached` in a job object with `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`
+ *   whose only handle this process holds (`uv__init_global_job_handle`,
+ *   `src/win/process.c`), so its `TerminateProcess` terminates the child too, at
+ *   once and mid-check: none of the child's code runs, nothing is published.
+ * - **POSIX**: the child ends ITSELF. Its stdin is a pipe whose write end only
+ *   this process holds and never writes or ends, so however this process dies
+ *   the OS closes it and the child reads end-of-file (`endWhenSupervisorGone`).
+ *   The child notices when its event loop next turns: at once during the
+ *   population; during the synchronous check loop, once the LAST check has
+ *   returned (a statement blocked inside SQLite reaches nothing until it
+ *   returns) — and still before it publishes anything
+ *   (`letSupervisorLossSurface`). Either way it exits 2 with one stderr line.
+ *   (The pipe is there on Windows too; the job object simply ends the child
+ *   first.)
+ */
+import { type ChildProcess } from 'node:child_process';
+import { type TempDirOutcome } from '@vibe-agent-toolkit/utils';
+import { type ForwardedDocument } from '../../utils/document-writer.js';
+/**
+ * The bound applied when `--budget` is not passed, in seconds.
+ *
+ * Not a round number chosen for looks, and no longer sized against this
+ * repository alone. Population is ~1.2 s warm here and 33-35 s with a cold parse
+ * cache; on a real adopter tree of 9,992 tracked files it is ~5 s warm and
+ * **16.5 s cold**, which is the first time the default was checked outside VAT.
+ * So 300 s is ~18× the worst thing anyone has actually measured — deliberately
+ * loose, because a FALSE kill is far worse than a slow honest failure: it
+ * teaches the operator to pass `--budget 0` and lose the bound entirely. Five
+ * minutes still turns an infinite hang into a clean bounded failure, which is
+ * the whole objective. A tree ten times that adopter's lands near 165 s, still
+ * inside the default but no longer comfortably.
  */
+export declare const DEFAULT_BUDGET_SECONDS = 300;
+/**
+ * 🔑 THE text that says what interrupting a supervised checks run does — rendered verbatim into
+ * BOTH `vat validate --help` and `vat resources check --help` (a unit test pins that), so the two
+ * can never describe it differently. Help-text indentation (two spaces), no backticks.
+ *
+ * Each claim is pinned: POSIX signals by `checks-supervisor-orphan.system.test.ts`, the group
+ * Ctrl-C by the same file and `signal-guard-group-ctrl-c.system.test.ts`, the orphan's own ending
+ * by `checks-supervisor-orphan.system.test.ts` (population) and
+ * `checks-supervisor-orphan-loop.system.test.ts` (the check loop) — on Windows the same two cases
+ * pin the job object ending the child with its supervisor — the Windows wrapper by
+ * `supervise-cli.test.ts`.
+ */
+export declare const SUPERVISION_SIGNAL_CONTRACT = "Interrupting a supervised checks run:\n  POSIX: SIGTERM, SIGHUP, SIGINT or SIGQUIT sent to this process, to the\n  'vat' wrapper (which forwards it), or to the terminal's process group\n  (Ctrl-C) kills the checks child, removes the progress directory, publishes\n  nothing, and dies of the signal (status 128+n; exit 2 where the signal\n  cannot kill it, PID 1). A process the child itself started (git) is not\n  killed with it; it ends on its own.\n  POSIX, ended where it runs no code (SIGKILL, an OOM killer), this process\n  cannot kill the child: the child reads end-of-file on the stdin pipe this\n  process held and ends itself -- one stderr line, exit 2, nothing\n  published -- at once during its population, and during the checks once\n  the last check returns (a statement inside SQLite is not reached until it\n  returns). A SIGKILL of the 'vat' wrapper kills the wrapper alone: this\n  process (whose stdin is the terminal's, so it reads no end-of-file) and\n  its child run on to completion, or until --budget seconds pass with no\n  progress.\n  Windows: a console Ctrl-C, Ctrl-Break or window close reaches every process\n  on the console; this one kills the child and exits 2, no document. An\n  outside kill (TerminateProcess, taskkill /F) of the 'vat' wrapper or of\n  this process runs no handler and ends the processes it started with it\n  (the OS job object Node puts them in): exit 1, nothing published, the\n  progress directory left behind.";
 /** What the watchdog remembers between polls. */
 export interface WatchdogState {
     /** How large the progress log was when it last changed. */
@@ -166,57 +227,96 @@ export declare function pollWatchdog(state: WatchdogState, observation: {
  *   non-negative number
  */
 export declare function parseBudgetSeconds(raw: string | undefined): number;
+/**
+ * Who asked for the supervised run: the operator, as `vat resources check`, or an orchestrator,
+ * as its `checks` phase. It decides how a kill's remedy is worded, and whether the child owes the
+ * operator the store notice (see `operator-notices.ts`).
+ */
+export type CheckInvocation = 'standalone' | 'phase';
+/**
+ * What the hidden `--supervised-by` flag carries, read: everything a supervisor tells the child it
+ * spawned, in ONE value so no half of it can arrive without the other.
+ */
+export interface SupervisedChild {
+    /** Who started the supervision. */
+    readonly invoker: CheckInvocation;
+    /**
+     * The supervisor's pid — this process's parent when it started, checked once at boot (see
+     * {@link requireSupervisableFlags}) and named in the line the child prints when it ends itself
+     * because the supervisor is gone (`endWhenSupervisorGone`, which watches stdin, not this pid).
+     */
+    readonly supervisorPid: number;
+    /** The progress log both processes watch; the child appends to it. */
+    readonly progressLog: string;
+}
+/** The hidden flag a supervisor hands the child it spawns, and nothing else passes. */
+export declare const SUPERVISED_BY_FLAG = "--supervised-by";
+/**
+ * The value of {@link SUPERVISED_BY_FLAG} for a child this process is about to spawn:
+ * `<invoker>:<this process's pid>:<progress log>`.
+ *
+ * The pid is what makes the flag unforgeable by accident: the child refuses it unless the pid
+ * named is its own parent's — see {@link requireSupervisableFlags}.
+ *
+ * @param child - Who asked, and where the progress goes (the supervisor is always this process)
+ * @returns The flag's value
+ */
+export declare function supervisedByValue(child: Omit<SupervisedChild, 'supervisorPid'>): string;
 /**
  * Does this process do the work, or supervise a child that does?
  *
- * 🚨 **The recursion guard, and the reason it is a named function.** `--cost-log`
- * is what a supervising parent hands its child, and it must WIN against the
- * budget — a child that consulted the budget first would spawn a child of its
- * own, which would spawn a child of its own. A condition inline in the command
- * would be a fork bomb one refactor away with nothing asserting on it.
+ * 🚨 **The recursion guard, and the reason it is a named function.** `--supervised-by` is what a
+ * supervising parent hands its child, and it must WIN against the budget — a child that consulted
+ * the budget first would spawn a child of its own, which would spawn a child of its own. A
+ * condition inline in the command would be a fork bomb one refactor away with nothing asserting
+ * on it.
  *
- * `--budget 0` also runs here: there is nothing to supervise, and a spawn would
- * cost a second process startup to buy no bound at all.
+ * `--budget 0` also runs here: there is nothing to supervise, and a spawn would cost a second
+ * process startup to buy no bound at all.
  *
  * @param options - The run
- * @param options.costLog - The hidden `--cost-log` value, or undefined
+ * @param options.supervisedBy - The hidden `--supervised-by` value, or undefined
  * @param options.budgetSecs - The bound in seconds; 0 means none
  * @returns True when the checks run in this process
  */
 export declare function runsInThisProcess(options: {
-    costLog: string | undefined;
+    supervisedBy: string | undefined;
     budgetSecs: number;
 }): boolean;
 /**
- * Refuse a combination where one flag the operator passed would do nothing.
- *
- * 🚨 **The defect: `--cost-log` wins the fork above unconditionally**, so
- * `vat resources check --budget 60 --cost-log /tmp/x` ran entirely UNBOUNDED and
- * said nothing about it. That is harmless to the recursion guard — a child must
- * keep winning — but an explicitly-passed, documented flag that is silently
- * inert is exactly the shape an operator never discovers until the hang it was
- * meant to prevent.
- *
- * ⚠️ **The real spawn path must survive this.** {@link runsInThisProcess}'s
- * caller builds the child's argv with `--cost-log` and does NOT forward
- * `--budget` — which is why the RAW flag is the discriminator here rather than
- * the parsed seconds: the child's `budgetSecs` is the 300 s default, not
- * anything the operator typed.
- *
- * `--budget 0` alongside `--cost-log` is allowed: both say "nobody is
- * supervising this", so there is no contradiction to report.
+ * Read `--supervised-by` into the child it describes, refusing it unless this process really is
+ * the child of the supervisor it names — and refuse a `--budget` it would silently ignore.
+ *
+ * 🚨 **Not an operator's flag, and passing it by hand is refused, not tolerated.** It used to be
+ * harmless-looking: the process ran the checks unbounded, printed none of the notices its
+ * supervisor would have, and appended to a log nobody watched. A flag that silently removes the
+ * bound is the shape an operator never discovers until the hang it was meant to prevent. So the
+ * value names its supervisor's pid, and a process whose parent is not that pid is refused
+ * `USAGE_INVALID` in plain words.
+ *
+ * 🔑 **One value, so an invalid combination cannot be written.** The invoker and the progress log
+ * used to be two hidden flags that had to arrive together, refused when one came alone. Now they
+ * are fields of one value, and the only thing left to refuse is a value that does not parse.
+ *
+ * 🚨 **`--budget` beside it is refused.** The flag wins the fork in {@link runsInThisProcess}
+ * unconditionally, so `--budget 60` with it would run UNBOUNDED and say nothing. The RAW
+ * `--budget` is the discriminator, not the parsed seconds: the real spawn path never forwards
+ * `--budget`, so the child's `budgetSecs` is the default, not anything an operator typed.
+ * `--budget 0` beside it is allowed: both say "nobody is supervising this".
  *
  * @param options - The run
- * @param options.costLog - The hidden `--cost-log` value, or undefined
+ * @param options.supervisedBy - The hidden `--supervised-by` value, or undefined
  * @param options.budgetRaw - What the operator actually typed for `--budget`
  * @param options.budgetSecs - The parsed bound; 0 means none
- * @throws When both flags were passed and the budget could not be honoured
+ * @returns The supervised child this process is, or undefined when it is not one
+ * @throws When the flag does not parse, names a supervisor that is not this process's parent, or
+ *   comes with a `--budget` it would ignore
  */
 export declare function requireSupervisableFlags(options: {
-    costLog: string | undefined;
+    supervisedBy: string | undefined;
     budgetRaw: string | undefined;
     budgetSecs: number;
-}): void;
+}): SupervisedChild | undefined;
 /**
  * Why a child ended without completing.
  *
@@ -234,8 +334,11 @@ export type AbnormalDeath = {
     readonly detail: string;
 }
 /**
- * The watchdog fired and the KILL WAS REFUSED — so the child is, as far as
- * this process can tell, still running.
+ * The watchdog fired and the KILL DID NOT END THE CHILD — so the child is, as
+ * far as this process can tell, still running. `refused` says which way: the
+ * kernel refused the SIGKILL (`EPERM`, in practice), or accepted it and the
+ * child still had not ended {@link KILL_POLLS_BEFORE_REPORTING_UNREAPED} polls
+ * later (uninterruptible I/O).
  *
  * 🚨 Distinct from `spawn-failed` and that distinction is the whole point.
  * Both arrive on `child.on('error')` and the handler used to read every one of
@@ -251,6 +354,7 @@ export type AbnormalDeath = {
     readonly kind: 'kill-failed';
     readonly detail: string;
     readonly pid: number | undefined;
+    readonly refused: boolean;
 } | {
     readonly kind: 'no-status';
 }
@@ -259,7 +363,7 @@ export type AbnormalDeath = {
  *
  * 🚨 The Windows half of the signal-death defect, and it survived the fix for
  * the POSIX half. A fatal abort — Node's own heap limit among them — has no
- * signal to report on a platform that has none, so `close` fires with
+ * signal to report on a platform that has none, so `exit` fires with
  * `(134, null)` where macOS and Linux give `(null, 'SIGABRT')`. That shape is
  * indistinguishable from an ordinary nonzero exit to
  * {@link resolveChildEnding}, which read it as a COMPLETED run and handed the
@@ -276,7 +380,37 @@ export type AbnormalDeath = {
  | {
     readonly kind: 'no-output';
     readonly code: number;
+}
+/**
+ * The child exited with a code and wrote something that is not this verb's
+ * document — cut off mid-write, most often. The sibling of `no-output`: the
+ * same situation (no usable report), so the same ending (the interrupted
+ * document from the progress log), never an internal error.
+ */
+ | {
+    readonly kind: 'unparseable-output';
+    readonly code: number;
+    readonly detail: string;
+}
+/**
+ * The child published a whole, valid document — and then exited with a code that document does
+ * not imply.
+ *
+ * 🚨 The document alone decided the forwarded exit, so a complete `ok` report followed by a
+ * non-zero exit was forwarded as a clean pass. Every path through the command ends on the code
+ * its own document derives, so a disagreement means something ended the child AFTER it wrote —
+ * a crash in teardown, a termination from outside that left an exit code — or a defect in vat.
+ * Which of the two is the truth cannot be known here, so neither is forwarded.
+ */
+ | {
+    readonly kind: 'exit-disagrees';
+    readonly code: number;
+    readonly documentExit: number;
 };
+/** A watchdog SIGKILL that did not end the child — the fields of the `kill-failed` death. */
+type KillFailure = Omit<Extract<AbnormalDeath, {
+    kind: 'kill-failed';
+}>, 'kind'>;
 /** What a child's ending MEANT, once the watchdog's belief is reconciled with it. */
 export type RunResolution = {
     readonly kind: 'completed';
@@ -288,11 +422,11 @@ export type RunResolution = {
     readonly death: AbnormalDeath;
 };
 /**
- * Read `close`'s two arguments, and the watchdog's belief, into one answer.
+ * Read `exit`'s two arguments, and the watchdog's belief, into one answer.
  *
  * ## 🚨 The defect this closes: a signal death READ AS SUCCESS
  *
- * `close` fires with `(code, signal)`, and a process that dies from a signal has
+ * `exit` fires with `(code, signal)`, and a process that dies from a signal has
  * `code === null` with `signal` set. This handler used to read only the code and
  * coerce it — `resolve(exitCode ?? 0)` — so every signal death became a
  * COMPLETED run with exit code 0. The parent then forwarded an empty stdout and
@@ -333,12 +467,12 @@ export type RunResolution = {
  * kill), and only then a failure to start. A run whose kill was refused must
  * never claim the watchdog was uninvolved.
  *
- * @param ending - What `close` reported, plus what the supervisor did and saw
- * @param ending.code - `close`'s first argument
- * @param ending.signal - `close`'s second argument
+ * @param ending - What `exit` reported, plus what the supervisor did and saw
+ * @param ending.code - `exit`'s first argument
+ * @param ending.signal - `exit`'s second argument
  * @param ending.killed - Whether the watchdog sent SIGKILL
  * @param ending.spawnError - Set when the child never started at all
- * @param ending.killFailure - Set when the watchdog's SIGKILL was REFUSED
+ * @param ending.killFailure - Set when the watchdog's SIGKILL was refused, or did not end the child
  * @returns What actually happened
  */
 export declare function resolveChildEnding(ending: {
@@ -349,23 +483,20 @@ export declare function resolveChildEnding(ending: {
         binary: string;
         detail: string;
     } | undefined;
-    killFailure?: {
-        detail: string;
-        pid: number | undefined;
-    } | undefined;
+    killFailure?: KillFailure | undefined;
 }): RunResolution;
 /**
  * Reconcile "how the process ended" with "what it left behind".
  *
  * ## 🚨 A completion that PUBLISHED NOTHING did not complete
  *
- * {@link resolveChildEnding} answers a question about the process — what `close`
+ * {@link resolveChildEnding} answers a question about the process — what `exit`
  * reported, reconciled with what the supervisor did. This answers a DIFFERENT
  * one, about the artifact, and the two disagree in exactly one place: a child
  * that exited with a code and wrote no document.
  *
- * Every in-process path through `checkCommand` ends at `emitCheckDocument` or at
- * `handleCommandError`, and both write to stdout — a clean pass, a violation, a
+ * Every in-process path through `checkCommand` ends at `endWithReport` or at
+ * `endWithRefusal`, and both write to stdout — a clean pass, a violation, a
  * bricked config, a mistyped `--check`. There is no exit this command can take
  * that legitimately publishes nothing. So an empty stdout is not a quiet run, it
  * is a run that was cut off before it could say anything, and forwarding its
@@ -379,11 +510,10 @@ export declare function resolveChildEnding(ending: {
  * ordering argument that has already been got wrong twice. It runs AFTER, on the
  * one branch it can change, and it changes no other.
  *
- * ⚠️ **Blank, not unparseable.** The parent forwards the child's document
- * verbatim precisely so it stays `--format`-agnostic, so it cannot ask whether
- * the bytes parse without learning the format. A truncated document — an abort
- * that landed mid-write — therefore still forwards, and that is the honest
- * limit of this test rather than an oversight.
+ * ⚠️ **Blank, not unparseable.** This asks only whether anything was written.
+ * Whether the bytes parse is asked next, by {@link readCompletedDocument}, which
+ * knows the format: a truncated document — an abort that landed mid-write — is
+ * the sibling `unparseable-output` death, and ends the same way.
  *
  * @param resolution - How the process ended
  * @param stdout - Everything the child wrote to stdout
@@ -393,8 +523,7 @@ export declare function resolveSilentCompletion(resolution: RunResolution, stdou
 /** How a supervised run ended. */
 export type SupervisedRun = {
     readonly outcome: 'completed';
-    readonly code: number;
-    readonly stdout: string;
+    readonly document: ForwardedDocument;
 } | {
     readonly outcome: 'killed';
     readonly log: string;
@@ -408,15 +537,19 @@ export type SupervisedRun = {
 /**
  * Run `vat resources check` as a child, bounded by the budget.
  *
- * `stdio` is `['ignore', 'pipe', 'inherit']`: the child's stdout is accumulated
- * so the parent can forward the document verbatim, and its stderr is INHERITED
- * so warnings and blob-stage refusals stream live exactly as they do today.
+ * `stdio` is `['pipe', 'pipe', 'inherit']`. Its stdin is a pipe this process
+ * holds open and NEVER writes to or ends: it exists only so that the child reads
+ * end-of-file the moment this process is gone, however it went (see
+ * `endWhenSupervisorGone`). Node closes this end itself once the child has
+ * exited. The child's stdout is accumulated so the parent can forward the
+ * document verbatim, and its stderr is INHERITED so warnings and blob-stage
+ * refusals stream live exactly as they do today.
  *
  * ⚠️ Asynchronous `spawn`, never `spawnSync`. The parent's event loop is the
  * thing holding the watchdog timer; a synchronous spawn would block it for
  * precisely as long as the run it is supposed to be bounding.
  *
- * 🚨 There is an `error` listener as well as a `close` one, and it is not
+ * 🚨 There is an `error` listener as well as an `exit` one, and it is not
  * optional politeness: without it an unspawnable binary is an unhandled `error`
  * event, which Node turns into a stack dump instead of a report. It fails
  * closed, so this is legibility — but a stack dump is not a report.
@@ -454,26 +587,137 @@ export type SupervisedRun = {
  * contorted to make it testable; the branch ordering and the message
  * composition are pure functions and are pinned as such.
  *
+ * ⏱️ Every interval is read off `performance.now()`, the monotonic clock: a
+ * wall clock stepped by NTP or an operator would grow or shrink the budget.
+ *
  * @param options - The run
- * @param options.args - The child's argv after the node binary, `--cost-log` included
- * @param options.logPath - The progress log both sides agreed on
+ * @param options.args - The child's argv after the node binary, `--supervised-by` included
+ * @param options.log - The progress log both sides agreed on, and the guard {@link withProgressLog} holds over it
  * @param options.budgetMs - How long silence is allowed to last
+ * @param options.format - The format the child was asked for, to read its document in
  * @returns How the child ended, and what it left behind
  */
 export declare function superviseCheck(options: {
     args: readonly string[];
-    logPath: string;
+    log: ProgressLog;
     budgetMs: number;
+    format: 'yaml' | 'json';
 }): Promise<SupervisedRun>;
 /**
- * Run `work` with a fresh progress log, and remove it however that ends.
+ * The guard {@link withProgressLog} holds over one supervision: what {@link superviseCheck} tells it.
+ */
+export interface SupervisionGuard {
+    /** From now on, every ending of this process takes `child` down with it. */
+    watch(child: ChildProcess): void;
+}
+/** A progress log, and the guard over its whole life — one value, so neither travels without the other. */
+export interface ProgressLog {
+    /** The log's path, alone in a directory minted for this run. */
+    readonly path: string;
+    /** The guard over the log's directory and the child that writes it. */
+    readonly guard: SupervisionGuard;
+}
+/**
+ * While a supervision lives, make every way THIS process ends take the child and the progress
+ * directory with it.
+ *
+ * ## 🚨 The defect: a supervisor that ended without its child orphaned an unbounded run
+ *
+ * The bound is enforced by this process's timer. Anything that ends this process ends the timer —
+ * and the child it was bounding was reparented and kept running with nothing left to stop it: the
+ * exact unbounded hang the supervisor exists to abolish. Measured ways in: a SIGTERM, SIGHUP or
+ * SIGINT sent to this pid alone; an uncaught throw anywhere in this process (the last-resort handler
+ * ends it with `process.exit` — the poll's own throw is caught in {@link superviseCheck}, so this is
+ * the second line for it); and a kill the kernel refused, which settles the run while the child
+ * lives on.
+ *
+ * So for the supervision's WHOLE life — from before the progress directory is minted until after
+ * it is removed, see {@link withProgressLog}:
+ *
+ * - **`exit`** SIGKILLs the child (`CHECKS_CHILD_TREE`), once there is one and while it runs, and removes the progress directory, once there is one — every ending of this process that
+ *   runs any of its code passes through it, a last-resort `process.exit` included, and
+ *   `process.exit` runs no `finally`.
+ * - **Every `TERMINATING_SIGNALS` member**, through `handleTerminatingSignals`: does the same,
+ *   synchronously, and RE-RAISES the signal. On POSIX this process then dies of it (status 128 + n),
+ *   as a shell and a CI runner expect. On Windows, or where the signal cannot kill it (PID 1), it
+ *   exits 2 with no document. A repeat with the first is swallowed. The child shares this
+ *   process's group, so a terminal's Ctrl-C reaches it directly too and, with no handler of its
+ *   own, ends it; this guard kills it all the same.
+ *
+ * The release waits for the child's `exit`, not for the run to settle, so a run settled with its
+ * child still alive (a refused kill, a poll that threw) still takes the child down however this
+ * process then ends.
+ *
+ * The module header gives why SIGKILL, and why the CHILD must never install a handler. This
+ * process may: its event loop is never blocked, which is what makes a handler fire at all.
+ *
+ * ## ⚠️ What no guard here reaches
+ *
+ * An ending that runs none of this process's code: SIGKILL, an OOM killer, and on Windows ANY
+ * outside kill — `process.kill(pid, <signal>)` there is `TerminateProcess`, which runs neither a
+ * signal handler nor the `exit` guard. On Windows the OS ends the child with this process (libuv's
+ * kill-on-close job object — see the module header). On POSIX the child covers those itself: it
+ * reads end-of-file on the stdin pipe this process held (`endWhenSupervisorGone`). A child blocked
+ * inside one SQLite statement reaches nothing until the statement returns.
+ *
+ * @returns The guard: `cover` names the progress log once it exists, `watch` the child once it is
+ *   spawned, and `release` ends the guard — at once, or at the watched child's `exit`
+ */
+declare function guardSupervision(): SupervisionGuard & {
+    cover(logPath: string): void;
+    release(): void;
+};
+/**
+ * How often to look at the log.
+ *
+ * Derived from the budget rather than fixed, so `--budget 2` notices in 200 ms
+ * while `--budget 600` does not wake the event loop 12,000 times for nothing.
+ *
+ * @param budgetMs - The budget
+ * @returns The poll interval in milliseconds
+ */
+declare function pollIntervalMs(budgetMs: number): number;
+/**
+ * Run `work` with a fresh progress log, and remove it however that ends — a signal included.
  *
  * ⚠️ Ephemeral, per run, and it carries NO format version — see
  * `check-progress.ts`. It is written and read by one process pair within one run
  * of one build, so the reader's own `.strict()` schema is the entire contract.
  *
- * @param work - Given the log's path
- * @returns Whatever `work` returned
+ * 🔑 The guard ({@link guardSupervision}) is installed BEFORE the directory is
+ * minted and released only AFTER it is removed, so a signal in either window —
+ * not only while the child runs — still removes it. One guard, one lifetime.
+ *
+ * @param work - Given the log
+ * @returns What `work` returned, with the log's directory as a `leftover` when the OS
+ *   would not remove it (see `withTempDir`) — for the caller to report as a warning
  */
-export declare function withProgressLog<T>(work: (logPath: string) => Promise<T>): Promise<T>;
+export declare function withProgressLog<T>(work: (log: ProgressLog) => Promise<T>): Promise<TempDirOutcome<T>>;
+/**
+ * Read what a COMPLETED child wrote as `resources check`'s document, or name
+ * the death when it is not one — or when the child's exit disagrees with it.
+ *
+ * 🔑 The exit is compared with the one the document itself derives. The parent
+ * forwards the DOCUMENT's code, never the process's, so a child that wrote a
+ * clean report and then exited non-zero would otherwise be published as a pass.
+ *
+ * @param stdout - Everything the child wrote (known not to be blank)
+ * @param code - The child's exit code
+ * @param format - The format the child was asked for
+ * @returns The forwardable document, or the `unparseable-output` / `exit-disagrees` death
+ */
+export declare function readCompletedDocument(stdout: string, code: number, format: 'yaml' | 'json'): {
+    readonly document: ForwardedDocument;
+} | {
+    readonly death: AbnormalDeath;
+};
+/** Test-facing seam: the pure decisions of this module, reached by its unit tests. */
+export declare const __internal: {
+    pollIntervalMs: typeof pollIntervalMs;
+    guardSupervision: typeof guardSupervision;
+    KILL_ATTEMPTS_BEFORE_REPORTING: number;
+    KILL_POLLS_BEFORE_REPORTING_UNREAPED: number;
+    STDOUT_GRACE_AFTER_EXIT_MS: number;
+};
+export {};
 //# sourceMappingURL=check-supervisor.d.ts.map

package/dist/commands/resources/check-supervisor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check-supervisor.d.ts","sourceRoot":"","sources":["../../../src/commands/resources/check-supervisor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"check-supervisor.d.ts","sourceRoot":"","sources":["../../../src/commands/resources/check-supervisor.ts"],"names":[],"mappings":"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"}