@vibe-agent-toolkit/cli 0.2.0-rc.4 → 0.2.0-rc.6

package/dist/commands/resources/check-progress.js

@@ -0,0 +1,205 @@
+/**
+ * The progress log a supervised `vat resources check` writes, and the reader
+ * that turns whatever survived into a report.
+ *
+ * ## 🚨 Why progress goes to a FILE, and never to stdout or IPC
+ *
+ * The run this log exists for is one that gets `SIGKILL`ed. That is not a design
+ * preference: a statement blocked inside synchronous `node:sqlite` never returns
+ * to the event loop, so nothing in-process can interrupt it — measured on Node
+ * 24.13.1, `worker.terminate()` never resolves against such a thread and the
+ * parent's own `process.exit()` does not exit either. An external `SIGKILL` is
+ * the only lever, and `SIGKILL` cannot be handled, deferred or flushed.
+ *
+ * So the child's report of what it has finished has to be DURABLE at every
+ * instant, not merely sent. stdout is buffered by the pipe and lost with the
+ * process; an IPC message needs a live event loop to be delivered, which is the
+ * exact resource the hung child does not have. An `appendFileSync` per unit is
+ * on disk before the next unit starts, which is the only property that matters.
+ *
+ * Keeping it off stdout has a second benefit worth stating: stdout stays the one
+ * parseable document this verb has always published, so `vat resources check |
+ * jq` is unaffected by a mechanism it should never have to know about.
+ *
+ * ## 🪤 The reader must expect DAMAGE, not merely tolerate it
+ *
+ * The signal lands wherever it lands, including part-way through a write, so the
+ * last line of a killed run's log is routinely half a JSON object. A reader that
+ * threw there would replace the bounded failure report with a stack trace at
+ * exactly the moment the report is the only thing the operator gets. A reader
+ * that GUESSED at a damaged line would be worse still: it would publish a cost
+ * record for a measurement nobody took, beside ones somebody did.
+ *
+ * Every line is therefore validated against a `.strict()` schema and silently
+ * dropped when it does not parse. That schema is also the whole of the format
+ * contract — there is no version integer here and there must never be one. This
+ * file is written and read by ONE process pair within ONE run of ONE build; the
+ * question a version integer pretends to answer ("can I read this?") is answered
+ * exactly and automatically by the schema the reader compiles with.
+ */
+import { appendFileSync } from 'node:fs';
+import { z } from 'zod';
+/**
+ * The population finished — how it was obtained, what it cost, and how much of
+ * the tree it covered.
+ *
+ * Written the instant the projection is ready, because a kill BEFORE this line
+ * means there is no projection at all and therefore no honest document to
+ * publish. The parent distinguishes those two endings by this line's presence
+ * and nothing else, so it must never be written early or optimistically.
+ */
+const PopulationEntrySchema = z.object({
+    kind: z.literal('population'),
+    population: z.union([z.literal('derived'), z.literal('store')]),
+    populationMs: z.number(),
+    membersEnumerated: z.number(),
+}).strict();
+/**
+ * A check's statement is ABOUT to run.
+ *
+ * The only record that can name the rule that hung: a check which never returns
+ * never files a cost, so without this line a killed run could say a check was in
+ * flight but not which one — and "one of your forty rules hangs" is not an
+ * actionable report.
+ */
+const StartEntrySchema = z.object({
+    kind: z.literal('start'),
+    name: z.string(),
+}).strict();
+/**
+ * A check completed — the same fields `CheckCost` publishes.
+ *
+ * 🪤 `rows` is optional and `broken` is `true`-or-absent, mirroring `CheckCost`
+ * exactly: a statement that threw has no row count, and `rows: 0` on it would
+ * read as "selected nothing and passed". Keeping the two shapes identical is
+ * what lets the parent hand recovered records to the same `buildCheckOutputData`
+ * a completed run uses, rather than growing a second payload builder that could
+ * drift from it.
+ */
+const CheckEntrySchema = z.object({
+    kind: z.literal('check'),
+    name: z.string(),
+    durationMs: z.number(),
+    rows: z.number().optional(),
+    broken: z.literal(true).optional(),
+}).strict();
+/**
+ * Every check has filed its cost; the document is about to be built.
+ *
+ * 🚨 **The defect this closes is a run killed AFTER it had its answer.** When
+ * the last check files its cost the child is not finished: it still resolves
+ * severities and serialises the document, and a document with 5,000 issues is
+ * 639 KB of YAML. That phase emitted nothing, so the watchdog's clock kept
+ * running from the final cost line and a budget that expired there SIGKILLed a
+ * run whose work was complete — a false failure that discards a correct result.
+ *
+ * One `appendFileSync` buys severity resolution and serialisation a fresh budget
+ * window. It carries no fields: the fact that it was written is the whole
+ * message.
+ *
+ * 🪤 **Emitted by `runDeclaredChecks`, before it resolves severities.** It first
+ * shipped a level up, from `runOutcome` after that function had already
+ * returned, which left `resolveIssueSeverity` charged to the last check's window
+ * while this comment claimed otherwise. What it still does NOT cover is the last
+ * check's row-to-issue conversion — `runChecks` files that check's cost before
+ * converting its rows — which is why the report's `idle` sentence hedges.
+ */
+const ChecksCompleteEntrySchema = z.object({
+    kind: z.literal('checks-complete'),
+}).strict();
+const ProgressEntrySchema = z.discriminatedUnion('kind', [
+    PopulationEntrySchema,
+    StartEntrySchema,
+    CheckEntrySchema,
+    ChecksCompleteEntrySchema,
+]);
+/**
+ * Read whatever of the log survived.
+ *
+ * @param text - The log's raw contents, tail damage and all
+ * @returns The lines that validate, in the order they were written
+ */
+export function parseProgressLog(text) {
+    const entries = [];
+    for (const line of text.split('\n')) {
+        if (line.trim() === '')
+            continue;
+        const entry = readLine(line);
+        if (entry !== undefined)
+            entries.push(entry);
+    }
+    return entries;
+}
+/**
+ * One line, or nothing.
+ *
+ * 🪤 Two separate refusals, deliberately: `JSON.parse` throws on the truncated
+ * tail, and the schema refuses a well-formed object that is not an entry this
+ * build knows. Collapsing them into one `try` around a parse-and-validate would
+ * still work, but the two failures mean different things — damage versus drift —
+ * and only the second is worth a future reader's attention.
+ *
+ * @param line - One line of the log
+ * @returns The entry, or undefined when the line is damaged or unknown
+ */
+function readLine(line) {
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+    const parsed = ProgressEntrySchema.safeParse(value);
+    return parsed.success ? parsed.data : undefined;
+}
+/**
+ * Which unit was running when the log stopped growing.
+ *
+ * 🔑 The population sentinel is keyed on the population line's ABSENCE rather
+ * than on there being no `start` lines. Those are different states: a run killed
+ * during population has no projection and no honest document, while a run killed
+ * between the population and the first statement has both.
+ *
+ * @param entries - What {@link parseProgressLog} recovered
+ * @returns The unit in flight
+ */
+export function unitInFlight(entries) {
+    if (!entries.some((entry) => entry.kind === 'population'))
+        return { kind: 'population' };
+    const completed = new Set(entries.filter((entry) => entry.kind === 'check').map((entry) => entry.name));
+    // 🪤 The `completed` set is what makes this unique, NOT the scan direction.
+    // The runner is serial — one statement at a time, its cost filed before the
+    // next `start` — so at most one `start` can lack a cost, and a scan from
+    // either end reaches the same entry. An earlier version scanned backwards and
+    // justified it as "the LAST unfinished start"; reversing it left all 10 unit
+    // tests green, which is the honest tell that the direction was never the
+    // guard. Dropping the `completed` filter, by contrast, reds immediately.
+    const started = entries.find((entry) => entry.kind === 'start' && !completed.has(entry.name));
+    if (started !== undefined)
+        return { kind: 'check', name: started.name };
+    // 🔑 Checked AFTER the in-flight statement, never before. The line means "no
+    // check is running any more"; a `start` without a cost means one still is, and
+    // a log holding both is damaged in a way that must still name the rule.
+    if (entries.some((entry) => entry.kind === 'checks-complete'))
+        return { kind: 'reporting' };
+    return { kind: 'idle' };
+}
+/**
+ * Open the log for append, and hand back the one-line-per-unit writer.
+ *
+ * ⚠️ `appendFileSync`, and it must stay synchronous. The child that writes these
+ * lines is about to enter a blocking native call; an asynchronous write would be
+ * queued behind work the event loop never gets back to, so the line naming the
+ * rule that hangs would exist only in memory — where `SIGKILL` destroys it.
+ *
+ * @param path - Where the supervisor is watching
+ * @returns A writer that appends one entry and returns once it is on disk
+ */
+export function createProgressWriter(path) {
+    return (entry) => {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- a path this process minted for this run
+        appendFileSync(path, `${JSON.stringify(entry)}\n`, 'utf-8');
+    };
+}
+//# sourceMappingURL=check-progress.js.map

package/dist/commands/resources/check-progress.js.map

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

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

@@ -0,0 +1,465 @@
+/**
+ * The time bound on `vat resources check`, enforced from OUTSIDE the process
+ * doing the work.
+ *
+ * ## 🚨 Why an external process, and not any of the cheaper things
+ *
+ * This verb runs adopter-authored SQL as an unattended CI gate. An accidental
+ * cross join, or a `WITH RECURSIVE` with no termination, runs forever — and
+ * every in-process lever was tried and MEASURED on Node 24.13.1 before this
+ * shape was chosen. Do not re-derive them:
+ *
+ * - **A worker thread does not work.** `worker.terminate()` never resolves
+ *   against a thread blocked in native SQLite, and the parent's own
+ *   `process.exit()` does not exit either. V8 can unwind a worker spinning in
+ *   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.
+ * - **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.
+ *
+ *   ⚠️ This header used to claim, as measured fact, that "SIGTERM does not kill
+ *   the child either, for the same reason". **That is false and was measured to
+ *   be false**: `kill -TERM` on a child blocked inside synchronous `node:sqlite`
+ *   `.all()` killed it instantly. The measurement above is about a process that
+ *   HAS a JS handler installed — a handler is a JS callback and the blocked
+ *   event loop is what would schedule it — and with no handler installed
+ *   SIGTERM's default disposition is kernel-delivered termination that needs no
+ *   cooperation at all. So SIGTERM works today only because nothing here
+ *   installs a handler, which is a property one future edit could silently
+ *   remove; SIGKILL is not a property anything can remove. The design did not
+ *   change, only the reason for it — recorded because a false claim is at its
+ *   worst in a section that tells the next reader not to re-derive it.
+ * - **The database cannot be handed over.** `DatabaseSync` has no `serialize()`
+ *   and `:memory:` is per-CONNECTION, so whoever runs the SQL populates its own
+ *   projection. That is why the child is a whole `vat resources check` run and
+ *   not a query executor.
+ *
+ * ## 🔑 The budget is ABSENCE OF PROGRESS, not total runtime
+ *
+ * A total-runtime bound has to be set above the slowest legitimate run on the
+ * largest adopter tree, which makes it useless as a hang detector, and it kills
+ * healthy runs that are merely large. So the parent watches the child's progress
+ * log and resets its clock on every new line — INCLUDING the population line,
+ * which is what bounds the population itself without charging it the first
+ * check's budget. A gate that can hang forever is the thing being fixed, and
+ * that includes hanging before the first statement.
+ *
+ * ⚠️ **That property holds for the CHECKS. It does NOT hold for the population,
+ * and the difference is not a detail.** The population emits exactly ONE line,
+ * at its end, so for the single longest unit in a cold run the budget degrades
+ * to precisely the total-runtime bound this section argues against: a population
+ * that takes longer than the budget is killed however healthily it is working.
+ *
+ * That is not cheap to fix and a half-fix would be worse than saying so.
+ * `onContributorTiming` does fire per contributor, but ~88% of a cold population
+ * is the BLOB stage — one call, remark-parsing every document, 33-35 s of the
+ * 35 s — and it emits nothing. Per-contributor lines would therefore bound the
+ * cheap part, leave the expensive part exactly as unbounded as it is now, and
+ * make the whole thing LOOK instrumented. So the population stays one
+ * un-instrumented unit, the default budget is set well above a cold one, and the
+ * per-unit property is claimed only where it is true.
+ *
+ * ## Why the child is the CLI itself
+ *
+ * The child is `vat resources check` with a hidden `--cost-log` 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.
+ */
+/** What the watchdog remembers between polls. */
+export interface WatchdogState {
+    /** How large the progress log was when it last changed. */
+    readonly bytesSeen: number;
+    /** When that was — the instant the budget is counted from. */
+    readonly quietSince: number;
+}
+/**
+ * Decide whether the child has gone quiet for longer than the budget.
+ *
+ * Pure, and separated from the timer for exactly that reason: the interesting
+ * behaviour is "a run that keeps making progress is never killed, however long
+ * it takes", and a test of that against a real timer would be a twenty-second
+ * test that flakes. Here it is twenty function calls.
+ *
+ * 🪤 Growth is measured in BYTES rather than parsed lines. A partially written
+ * line also grows the file, and treating that as progress is the safe direction:
+ * the child is demonstrably alive and writing. Counting lines instead would mean
+ * a very slow write could look like silence.
+ *
+ * @param state - What the previous poll saw
+ * @param observation - The run
+ * @param observation.bytes - The progress log's current size
+ * @param observation.now - The clock, in milliseconds
+ * @param observation.budgetMs - How long silence is allowed to last
+ * @returns The state to carry forward, and whether the budget was blown
+ */
+export declare function pollWatchdog(state: WatchdogState, observation: {
+    bytes: number;
+    now: number;
+    budgetMs: number;
+}): {
+    state: WatchdogState;
+    breach: boolean;
+};
+/**
+ * Read `--budget`, or supply the default.
+ *
+ * 🪤 A typo is REFUSED rather than defaulted. `--budget 2O` (letter O) would
+ * otherwise run with a five-minute bound while the operator believed they had
+ * set two seconds — and they would only find out from a CI job that hung for
+ * five minutes instead of two. Thrown, so it exits 2 as an operator error, in
+ * line with this command's existing contract for an unknown `--check` name.
+ *
+ * 🚨 **A BLANK value is refused before `Number` ever sees it, and that is the
+ * more important half.** `Number('')`, `Number(' ')` and `Number('\n')` are all
+ * `0` — finite, non-negative, and therefore accepted by the range guard below —
+ * and `0` is this flag's documented escape hatch meaning *no bound at all*. So
+ * `--budget "$CHECK_BUDGET"` with the variable unset did not shorten the bound
+ * and did not complain: it silently REMOVED it, on the one flag whose entire
+ * purpose is to stop an unattended job hanging forever. An unset shell variable
+ * is a far more common CI accident than the typo the guard was written for.
+ *
+ * 🚨 **The blank string was only the visible half of the hazard, and the guard
+ * below it is the rest.** What actually removes the bound is `Number(raw) === 0`
+ * for a raw string nobody would recognise as a zero — `--budget 1e-400`
+ * underflows to `0`, and `--budget -0` is negative zero, which sails past the
+ * `seconds < 0` test because `-0 < 0` is false. Both were MEASURED to run
+ * completely unbounded, in process, exiting 0 with no supervision and no word
+ * said. So a value that PARSES to zero is refused unless the operator literally
+ * wrote a zero: `raw.trim() !== '0'` and it is an operator error. The escape
+ * hatch is still there, it just has to be spelled the one unambiguous way.
+ *
+ * ⚠️ That deliberately refuses `0.0` and `0x0` as well. They are not accidents
+ * an operator can fall into, they cost one character to rewrite, and a guard
+ * with an exception list is a guard whose next exception nobody argues about.
+ *
+ * 🔑 **Non-zero hex is deliberately KEPT.** `Number('0x10')` is 16 and
+ * `--budget 0x10` runs with a sixteen-second bound. That is unambiguous, it
+ * cannot arise by accident the way an empty variable can, and refusing it would
+ * buy nothing — recorded here so the next reader does not "fix" it into a
+ * refusal.
+ *
+ * @param raw - Whatever Commander parsed, or undefined
+ * @returns The budget in seconds; 0 means no bound
+ * @throws When the value is blank, means zero without saying so, or is not a
+ *   non-negative number
+ */
+export declare function parseBudgetSeconds(raw: string | undefined): number;
+/**
+ * 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.
+ *
+ * `--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.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;
+    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.
+ *
+ * @param options - The run
+ * @param options.costLog - The hidden `--cost-log` 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
+ */
+export declare function requireSupervisableFlags(options: {
+    costLog: string | undefined;
+    budgetRaw: string | undefined;
+    budgetSecs: number;
+}): void;
+/**
+ * Why a child ended without completing.
+ *
+ * Structured rather than a prose string because the two common signals point at
+ * DIFFERENT remedies — `SIGABRT` is Node's own heap abort and wants a narrower
+ * statement, `SIGKILL` from outside wants a bigger runner — and the message that
+ * says so belongs beside the other findings, not here.
+ */
+export type AbnormalDeath = {
+    readonly kind: 'signal';
+    readonly signal: string;
+} | {
+    readonly kind: 'spawn-failed';
+    readonly binary: string;
+    readonly detail: string;
+}
+/**
+ * The watchdog fired and the KILL WAS REFUSED — so the child is, as far as
+ * this process can tell, still running.
+ *
+ * 🚨 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
+ * them as a spawn failure, which reported the exact opposite of what happened:
+ * "could not be started at all", "nothing ran at all", "the watchdog never
+ * fired". It started, it ran past its budget, the watchdog fired, and it would
+ * not die.
+ *
+ * `pid` is carried because it is the only handle the operator has left on a
+ * process this command could not stop.
+ */
+ | {
+    readonly kind: 'kill-failed';
+    readonly detail: string;
+    readonly pid: number | undefined;
+} | {
+    readonly kind: 'no-status';
+}
+/**
+ * The child exited with a CODE, and published nothing at all.
+ *
+ * 🚨 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
+ * `(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
+ * parent an empty string to forward. Measured on `windows-latest`: exit 134,
+ * zero bytes of stdout, on precisely the runaway the bound exists to catch.
+ *
+ * It did not fail OPEN — 134 is not 0 — so a gate still went red. But the
+ * report was absent, which is the other half of what the original defect did.
+ *
+ * `code` is carried because it is the only thing left that says HOW the child
+ * died: 128 + n is the conventional encoding of a fatal signal, and
+ * `deathRemedy` reads the signal back out of it.
+ */
+ | {
+    readonly kind: 'no-output';
+    readonly code: number;
+};
+/** What a child's ending MEANT, once the watchdog's belief is reconciled with it. */
+export type RunResolution = {
+    readonly kind: 'completed';
+    readonly code: number;
+} | {
+    readonly kind: 'killed';
+} | {
+    readonly kind: 'abnormal';
+    readonly death: AbnormalDeath;
+};
+/**
+ * Read `close`'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
+ * `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
+ * exited 0, and a CI gate reads that as a clean pass.
+ *
+ * It needed no external actor. A check whose statement materialises an unbounded
+ * result set — `SELECT i FROM <infinite recursive CTE>`, the row-returning twin
+ * of the aggregate this whole module exists for — makes `.all()` fill the heap
+ * until V8 gives up and Node ABORTS. Measured: `PARENT_EXIT=0`, zero bytes of
+ * stdout, on precisely the input the bound exists to catch. Through the
+ * unsupervised lane the identical input exits 134.
+ *
+ * Every memory death arrives here: Node's own heap abort, a kernel OOM killer on
+ * a memory-capped runner (which picks the large CHILD, never the idle parent),
+ * and a container limit. `?? 0` turned all of them into a pass.
+ *
+ * ## 🪤 A kill only counts if it LANDED
+ *
+ * `killed` says the watchdog fired, not that the child died of it. libuv runs
+ * timers BEFORE the poll phase that reaps the child, so the timer can fire in
+ * the same loop turn as a child that has already exited cleanly. A NORMAL ending
+ * — a non-null code with no signal — is therefore honoured whatever `killed`
+ * says: that run finished on its own terms and its answer is real. Reporting it
+ * as killed fails closed, but it discards a correct result, which is its own
+ * kind of wrong.
+ *
+ * ## 🚨 The ORDER of the tests below is load-bearing
+ *
+ * `spawnError` used to be tested FIRST, so `killed` was never consulted on that
+ * branch — and `child.on('error')` is not only a spawn-failure listener. Node
+ * emits `error` on the ChildProcess when `subprocess.kill()` itself fails, so a
+ * refused SIGKILL landed on the spawn-failure branch and the report said the
+ * child "could not be started at all", that "nothing ran at all, so this is an
+ * installation or PATH problem", and that "the watchdog never fired". Three
+ * statements, all false, about a runaway that was still executing.
+ *
+ * So: a real ending first, then what the SUPERVISOR did (a refused kill, then a
+ * 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.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
+ * @returns What actually happened
+ */
+export declare function resolveChildEnding(ending: {
+    code: number | null;
+    signal: string | null;
+    killed: boolean;
+    spawnError?: {
+        binary: string;
+        detail: string;
+    } | undefined;
+    killFailure?: {
+        detail: string;
+        pid: number | undefined;
+    } | 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`
+ * 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
+ * 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
+ * exit code verbatim tells the operator a number and nothing else.
+ *
+ * ## 🪤 Why this is not folded into {@link resolveChildEnding}
+ *
+ * That function's branch ORDER is load-bearing and reasoned entirely about
+ * process endings and supervisor beliefs. The emptiness of stdout belongs to
+ * neither, and threading it through would put an artifact test inside an
+ * 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.
+ *
+ * @param resolution - How the process ended
+ * @param stdout - Everything the child wrote to stdout
+ * @returns The resolution, with a silent completion re-read as abnormal
+ */
+export declare function resolveSilentCompletion(resolution: RunResolution, stdout: string): RunResolution;
+/** How a supervised run ended. */
+export type SupervisedRun = {
+    readonly outcome: 'completed';
+    readonly code: number;
+    readonly stdout: string;
+} | {
+    readonly outcome: 'killed';
+    readonly log: string;
+    readonly elapsedMs: number;
+} | {
+    readonly outcome: 'abnormal';
+    readonly death: AbnormalDeath;
+    readonly log: string;
+    readonly elapsedMs: number;
+};
+/**
+ * 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.
+ *
+ * ⚠️ 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
+ * 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.
+ *
+ * ## 🚨 `error` is NOT only a spawn-failure listener, and reading it as one
+ * ABANDONED A LIVE CHILD
+ *
+ * Node emits `error` on the ChildProcess when `subprocess.kill()` itself fails.
+ * The shipped function ends `else { /* Other error, almost certainly EPERM. *\/
+ * this.emit('error', new ErrnoException(err, 'kill')); }`. So: the watchdog
+ * breached, `killed` was set, the SIGKILL was refused, `error` fired, the
+ * handler recorded a SPAWN failure and resolved immediately — which cleared the
+ * watchdog timer, so no further kill could ever be attempted — and the parent
+ * published a report saying the child "could not be started at all" and "the
+ * watchdog never fired" while the runaway was still executing. The bound this
+ * module exists to enforce became an orphaned unbounded hang, described as its
+ * own opposite.
+ *
+ * The handler therefore forks on `killed`, and the two arms are deliberately
+ * asymmetric:
+ *
+ * - **Before the watchdog fired**, an `error` means the child never started.
+ *   Resolve at once: there is nothing alive to wait for.
+ * - **After it fired**, an `error` means the KILL failed and the child is,
+ *   as far as this process can tell, still running. Do NOT resolve. Resolving
+ *   is what clears the timer, and clearing the timer is what makes the failure
+ *   permanent. The poll keeps breaching (the log is not growing and
+ *   `quietSince` is not reset), so it keeps re-sending SIGKILL, and a transient
+ *   refusal still lands. Only after {@link KILL_ATTEMPTS_BEFORE_REPORTING}
+ *   refusals does it give up — and it gives up by REPORTING, naming the pid,
+ *   never by claiming the child never started.
+ *
+ * ⚠️ Reachability of `EPERM` on one's own child is REASONED rather than
+ * reproduced — it is rare on macOS and Linux. Nothing in production was
+ * contorted to make it testable; the branch ordering and the message
+ * composition are pure functions and are pinned as such.
+ *
+ * @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.budgetMs - How long silence is allowed to last
+ * @returns How the child ended, and what it left behind
+ */
+export declare function superviseCheck(options: {
+    args: readonly string[];
+    logPath: string;
+    budgetMs: number;
+}): Promise<SupervisedRun>;
+/**
+ * Run `work` with a fresh progress log, and remove it however that ends.
+ *
+ * ⚠️ 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
+ */
+export declare function withProgressLog<T>(work: (logPath: string) => Promise<T>): Promise<T>;
+//# sourceMappingURL=check-supervisor.d.ts.map