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

package/dist/commands/resources/check.js

@@ -29,106 +29,22 @@
  *   a runtime optimizer to schedule between.
  */
 import { performance } from 'node:perf_hooks';
-import { bindBuiltinChecks, BUILTIN_CHECK_NAMES, issuesFromCheckRows, LIMIT_DIRECTIONS, } from '@vibe-agent-toolkit/resources';
-import { buildReport, CUSTOM_CHECK_CODE_PREFIX, ExitCode, isCustomCheckCode, reportSchema, toFindings, } from '@vibe-agent-toolkit/schema';
+import { bindBuiltinChecks, BUILTIN_CHECK_NAMES, issuesFromCheckRows, } from '@vibe-agent-toolkit/resources';
+import { buildErrorReport, buildReport, CUSTOM_CHECK_CODE_PREFIX, isCustomCheckCode, toFindings, withAddedFindings, } from '@vibe-agent-toolkit/schema';
 import { safePath } from '@vibe-agent-toolkit/utils';
-import { z } from 'zod';
-import { handleReportCommandError } from '../../utils/command-error.js';
+import { CommandRefusalError, refusalCodeOf } from '../../utils/command-refusal.js';
 import { loadConfigCached } from '../../utils/config-loader.js';
+import { endWithForwardedDocument, endWithRefusal, endWithReport, leftoverIssueOf, NOTHING_FINISHED, } from '../../utils/document-writer.js';
 import { formatDurationSecs } from '../../utils/duration.js';
 import { resolveIssueSeverity } from '../../utils/issue-severity.js';
 import { createLogger } from '../../utils/logger.js';
-import { writeStdoutSync, writeStructuredOutput } from '../../utils/output.js';
+import { EVERY_NOTICE, withNoticeAudience } from '../../utils/operator-notices.js';
 import { assertDirectoryArgument, projectRootOrLoudCwd, projectRootOrNull } from '../../utils/project-root-policy.js';
 import { withQueriedProjection, } from '../../utils/projection-query.js';
 import { relationBoundsFor } from '../../utils/relation-limits.js';
-import { nothingCheckedFinding, runIntegrityFinding } from '../../utils/run-integrity.js';
-import { createProgressWriter, parseProgressLog, unitInFlight, } from './check-progress.js';
-import { parseBudgetSeconds, requireSupervisableFlags, runsInThisProcess, superviseCheck, withProgressLog, } from './check-supervisor.js';
-/** What one rule cost, as the document publishes it. */
-const PublishedCheckCostSchema = z.object({
-    name: z.string(),
-    /** Three significant figures, so a 0.4 ms rule serializes as 0.0004 rather than a zero that reads as "not measured". */
-    durationSecs: z.number().nonnegative(),
-    /** Rows the statement returned. ABSENT, never 0, when the statement did not complete. */
-    rows: z.number().int().nonnegative().optional(),
-    broken: z.literal(true).optional(),
-    /** Present and `true` only for a rule VAT supplied — see {@link CheckCost.builtin}. */
-    builtin: z.literal(true).optional(),
-}).strict();
-/**
- * The published copy of {@link relationBoundsFor}'s answer.
- *
- * The registry lists are `readonly` and this document is handed to a serializer,
- * so the arrays are copied rather than referenced — the same rule
- * `lensesEvaluated` follows one field above: a published document owns no
- * reference into the run's own state.
- *
- * @param lensesEvaluated - The lenses this run evaluated
- * @returns The bounds keys to spread, or nothing
- */
-function structuredBounds(lensesEvaluated) {
-    const bounds = relationBoundsFor(lensesEvaluated);
-    if (bounds.boundsStatement === undefined || bounds.limits === undefined)
-        return {};
-    return { boundsStatement: bounds.boundsStatement, limits: bounds.limits.map((limit) => ({ ...limit })) };
-}
-/**
- * A signed bound on what the derived rows settle, as `@vibe-agent-toolkit/resources`
- * states it.
- *
- * ⛔ The direction vocabulary is IMPORTED, never respelled: `LIMIT_DIRECTIONS`
- * is the one list, tied to `StatedLimit['direction']` by `satisfies`, so a
- * fifth direction cannot leave this schema quietly rejecting it.
- */
-const StatedLimitSchema = z.object({
-    id: z.string(),
-    direction: z.enum(LIMIT_DIRECTIONS),
-    statement: z.string(),
-}).strict();
-/**
- * What the check run reports beyond its findings.
- *
- * The envelope's `examined` is `membersEnumerated` — what the rules ran
- * AGAINST. `checksRun` is the other denominator, the number of RULES, and both
- * are needed: zero findings is the pass condition and either number at zero
- * makes that pass vacuous.
- */
-export const CheckDataSchema = z.object({
-    root: z.string(),
-    /** Whether the projection was derived this run or read from the store. */
-    population: z.enum(['derived', 'store']),
-    /** What the population cost — charged to no check, see `CheckCost`. */
-    populationSecs: z.number().nonnegative(),
-    /** What evaluating the lenses cost, paid before the first statement ran. */
-    lensSecs: z.number().nonnegative(),
-    /**
-     * Which lenses that covers — the derived relations this run's checks could
-     * actually read. 🔑 An empty list says "no check asked for a derived relation"
-     * rather than "a lens stopped running"; without it `lensSecs: 0` is the same
-     * document either way, and a gate whose rules silently read empty relations is
-     * a gate that cannot fail.
-     */
-    lensesEvaluated: z.array(z.string()),
-    /**
-     * The prose frame {@link CheckDataSchema.limits} is read under. Present
-     * exactly when a lens with stated bounds was evaluated.
-     */
-    boundsStatement: z.string().optional(),
-    /**
-     * What the derived rows this run could read do NOT settle — signed and
-     * directional, the same list `vat claude context` publishes beside its own
-     * answer. Absent when no bounded lens ran: an empty list would claim nothing
-     * bounds the answer, which is stronger than "the answer holds no such row".
-     */
-    limits: z.array(StatedLimitSchema).optional(),
-    /** The number of rules that EXECUTED. Derived from `checks`, never carried beside it. */
-    checksRun: z.number().int().nonnegative(),
-    /** What each rule cost, directly under the denominator it is the breakdown of. */
-    checks: z.array(PublishedCheckCostSchema),
-}).strict();
-/** The document this command publishes. */
-export const CHECK_REPORT_SCHEMA = reportSchema(CheckDataSchema);
+import { RUN_INTEGRITY_CODE, runIntegrityFinding } from '../../utils/run-integrity.js';
+import { createProgressWriter, endWhenSupervisorGone, letSupervisorLossSurface, parseProgressLog, unitInFlight, } from './check-progress.js';
+import { DEFAULT_BUDGET_SECONDS, parseBudgetSeconds, requireSupervisableFlags, runsInThisProcess, SUPERVISED_BY_FLAG, superviseCheck, supervisedByValue, withProgressLog, } from './check-supervisor.js';
 /**
  * The refusal for a run in which NO check executed.
  *
@@ -156,10 +72,10 @@ export const CHECK_REPORT_SCHEMA = reportSchema(CheckDataSchema);
  * having to remember it. It also lands after `resolveIssueSeverity`, which is
  * belt and braces: the code is already unreachable from a `severity` key.
  *
- * The mechanism — ask the DENOMINATOR never the config, one report per
- * situation, stand down behind an existing run-integrity finding — is the shared
- * {@link nothingCheckedFinding}; this wrapper owns only the message. The
- * stand-down matters here for an interrupted run, which recovers zero costs when
+ * The writer refuses a run that examined no RESOURCE; this is the other
+ * denominator, CHECKS, which only this verb knows — so it asks that count,
+ * never the config, and stands down behind an existing run-integrity finding
+ * (one report per situation). The stand-down matters here for an interrupted run, which recovers zero costs when
  * the kill landed before the first statement finished and already carries
  * {@link interruptedRunFinding}, the more specific of the two claims. A `--check`
  * filter that matched nothing is refused earlier by {@link requireKnownCheck},
@@ -177,13 +93,15 @@ export const CHECK_REPORT_SCHEMA = reportSchema(CheckDataSchema);
  * @returns The finding, or nothing when at least one check ran
  */
 function noCheckRanFinding(costs, issues) {
-    return nothingCheckedFinding(costs.length, issues, () => 'No check ran at all, so this document is not a verdict: a gate that checked nothing'
-        + ' produces the same report as a gate that was removed, and this run cannot tell'
-        + ' you which happened.'
-        + ' This is not an absent `resources.checks` block — VAT\'s own built-in checks run'
-        + ' whether or not a project declares any, so reaching zero means not even those'
-        + ' executed. Re-run with --debug and report it; if the run was filtered, check that'
-        + ' --check named a rule this build still ships.');
+    if (costs.length > 0 || issues.some((issue) => issue.code === RUN_INTEGRITY_CODE))
+        return [];
+    return [runIntegrityFinding('No check ran at all, so this document is not a verdict: a gate that checked nothing'
+            + ' produces the same report as a gate that was removed, and this run cannot tell'
+            + ' you which happened.'
+            + ' This is not an absent `resources.checks` block — VAT\'s own built-in checks run'
+            + ' whether or not a project declares any, so reaching zero means not even those'
+            + ' executed. Re-run with --debug and report it; if the run was filtered, check that'
+            + ' --check named a rule this build still ships.')];
 }
 /**
  * Build the check report.
@@ -208,6 +126,13 @@ function noCheckRanFinding(costs, issues) {
  * passes through, so deriving the refusal in it is what makes "checked nothing,
  * status clean" unrepresentable rather than merely unwritten.
  *
+ * 🔑 **A run with no population is `status: error`, and that is decided HERE.**
+ * Nothing was examined, so it is not a gate that failed (exit 1) but a command
+ * that could not do its job (exit 2) — the exit code follows from the document
+ * through `exitCodeForReport`, so no caller can publish one and exit the other.
+ * The document is still published, with the population fields `null`, and the
+ * reason moves from `findings` to `error` as the envelope's error branch requires.
+ *
  * 🪤 The findings are NOT run through `relativizePathEntries`. Every other
  * payload builder re-bases here because its producer keeps absolute paths
  * internally; these arrive project-relative instead, and re-basing an
@@ -224,35 +149,20 @@ function noCheckRanFinding(costs, issues) {
  */
 export function buildCheckOutputData(input) {
     const issues = [...noCheckRanFinding(input.costs, input.issues), ...input.issues];
-    return buildReport({
+    const { populated } = input;
+    const report = buildReport({
+        // `vat resources check` offers no `--strict`: warnings never fail it.
+        gate: { strict: false },
         // The OTHER denominator, and the one whose absence shipped a green gate over
         // an empty repository. `checksRun` counts rules; this counts what they ran
-        // against.
-        examined: input.membersEnumerated,
+        // against. 🔑 0 for a run with no population is not a placeholder: nothing
+        // WAS examined, and the interrupted run's own finding says why.
+        examined: populated === null ? 0 : populated.membersEnumerated,
         findings: toFindings(issues),
         durationMs: input.durationMs,
         data: {
             root: input.root,
-            population: input.population,
-            // Beside the origin, because a `population: store` a reader cannot price is
-            // a label taken on faith. Charged to no check — see {@link CheckCost}.
-            populationSecs: formatDurationSecs(input.populationMs),
-            // Published here too, and not only by `query`, because this verb pays it
-            // identically — the lens is evaluated before the first statement runs. A
-            // document that priced the population but not the lens would attribute the
-            // lens's cost to whichever rule the reader happened to be looking at, which
-            // is the same defect `populationSecs` exists to prevent.
-            lensSecs: formatDurationSecs(input.lensMs),
-            // What that number covers — see `CheckDataSchema.lensesEvaluated`. Copied
-            // into a plain array so the published document owns no reference into the
-            // run's own state.
-            lensesEvaluated: [...input.lensesEvaluated],
-            // The bounds of the rows those lenses produced, stated ONCE and only when
-            // a bounded lens ran. This is the verb an adopter makes GATE, so it is the
-            // one that most owes them — `utils/relation-limits.ts` carries why.
-            // Copied out of the readonly registry lists: the published document owns
-            // no reference into module state a later render could mutate.
-            ...structuredBounds(input.lensesEvaluated),
+            ...populationData(populated),
             // The denominator of rules. Derived from `checks`, never carried beside it.
             checksRun: input.costs.length,
             // What each rule cost, directly under the denominator it is a breakdown
@@ -278,6 +188,65 @@ export function buildCheckOutputData(input) {
             })),
         },
     });
+    return populated === null ? couldNotRun(report) : report;
+}
+/**
+ * The error branch of the envelope, for a run that never had a population.
+ *
+ * `status: error`, nothing in `findings`, zero `summary`, and the reason in
+ * `error` under the registered refusal `RUN_INCOMPLETE` — the run started and
+ * stopped before its population completed — and `data` is KEPT: it names the
+ * root and says, with `null`, that there was no projection, which is more than
+ * `data: null` could. No `durationMs`: no refusal document carries one.
+ *
+ * @param report - The document as the findings would have built it
+ * @returns The same document on the error branch
+ */
+function couldNotRun(report) {
+    // The one construction of the error branch — the same `buildErrorReport`
+    // every refusal the writer publishes goes through.
+    return buildErrorReport({
+        error: { code: 'RUN_INCOMPLETE', message: report.findings.map((finding) => finding.message).join('\n') },
+        gate: report.gate,
+        examined: report.examined,
+        findings: [],
+        data: report.data,
+    });
+}
+/**
+ * The document's population fields — all present, or all `null`.
+ *
+ * @param populated - What the population reported, or null when it never completed
+ * @returns The fields to spread into `data`
+ */
+function populationData(populated) {
+    if (populated === null) {
+        return { population: null, populationSecs: null, lensSecs: null, lensesEvaluated: null, lensPopulation: null };
+    }
+    return {
+        population: populated.population,
+        // Beside the origin, because a `population: store` a reader cannot price is
+        // a label taken on faith. Charged to no check — see {@link CheckCost}.
+        populationSecs: formatDurationSecs(populated.populationMs),
+        // Published here too, and not only by `query`, because this verb pays it
+        // identically — the lens is evaluated before the first statement runs. A
+        // document that priced the population but not the lens would attribute the
+        // lens's cost to whichever rule the reader happened to be looking at, which
+        // is the same defect `populationSecs` exists to prevent.
+        lensSecs: formatDurationSecs(populated.lensMs),
+        // What that number covers — see `CheckDataSchema.lensesEvaluated`. Copied
+        // into a plain array so the published document owns no reference into the
+        // run's own state.
+        lensesEvaluated: [...populated.lensesEvaluated],
+        // Where those lenses' own populations came from — see `CheckDataSchema.lensPopulation`.
+        lensPopulation: populated.lensPopulation,
+        // The bounds of the rows those lenses produced, stated ONCE and only when
+        // a bounded lens ran. This is the verb an adopter makes GATE, so it is the
+        // one that most owes them — `utils/relation-limits.ts` carries why.
+        // Copied out of the readonly registry lists: the published document owns
+        // no reference into module state a later render could mutate.
+        ...relationBoundsFor(populated.lensesEvaluated),
+    };
 }
 /**
  * Run a thunk between two readings of the clock, and report both.
@@ -505,7 +474,7 @@ export function requireKnownCheck(builtinNames, checks, only) {
     if (only === undefined || builtinNames.includes(only) || Object.hasOwn(checks, only))
         return;
     const declared = Object.keys(checks);
-    throw new Error(`No check named "${only}" exists. `
+    throw new CommandRefusalError('USAGE_INVALID', `No check named "${only}" exists. `
         + `Built in: ${builtinNames.join(', ')}. `
         + (declared.length === 0
             ? 'This project declares none of its own — add them under `resources.checks` in'
@@ -579,10 +548,10 @@ export function warnUndeclaredOverrides(checks, validation, logger) {
  * nothing all produce it — and because population DECLINES ignored members
  * rather than flagging them, the tables carry no trace of the difference.
  *
- * The precedent is `population-wiring.ts`, which makes `onBlobPopulation`
- * mandatory because "a tree whose every document was declined as binary
- * otherwise populates as empty and reports success". That guard covers blob
- * refusals only; this one covers the extent.
+ * The precedent is `populateAndReport` in `population-wiring.ts`, which names
+ * a tree whose every document was declined as binary rather than letting it
+ * populate as empty and report success. That report covers blob refusals only;
+ * this guard covers the extent.
  *
  * 🪤 **Only when checks actually RAN.** A run with no rules at all is refused
  * too — it is the same class one level further out — but by
@@ -612,6 +581,28 @@ function emptyCorpusFinding(checksRun, membersEnumerated) {
             + ' `root` in this report is the directory you meant.'
             + ' `vat resources scan` over the same path lists what an enumeration finds.')];
 }
+/**
+ * How to give the run more time, as one sentence — by who ran the checks.
+ *
+ * 🔑 A kill remedy names a flag only the verb that accepts it can be given. `--budget` is
+ * `vat resources check`'s alone, and in this release `vat validate` has NO way to give its checks
+ * phase more time: the phase always runs under {@link DEFAULT_BUDGET_SECONDS}. So the phase's
+ * sentence says exactly that — what the bound measures, its value, and that running the checks
+ * standalone with a larger `--budget` lets THEM pass but does not make `vat validate` pass. A
+ * remedy promising otherwise sends the operator round a loop that cannot end.
+ *
+ * @param invocation - Who ran the checks
+ * @returns The sentence, with a leading space
+ */
+function raiseBoundSentence(invocation) {
+    return invocation === 'standalone'
+        ? ' Raise it with `--budget <seconds>`.'
+        : ' `vat validate` cannot give it more time: its checks phase always runs under the default'
+            + ` bound of ${DEFAULT_BUDGET_SECONDS}s WITHOUT PROGRESS (a total bound on the population,`
+            + ' which reports progress only when it finishes), and this release has no way to change'
+            + ' it. Running the same checks on their own with `vat resources check --budget <seconds>`'
+            + ' can let them pass there, but `vat validate` will still fail on this tree.';
+}
 /**
  * Where the run was when it stopped, as a phrase.
  *
@@ -619,6 +610,10 @@ function emptyCorpusFinding(checksRun, membersEnumerated) {
  * @returns A clause naming the unit
  */
 function inFlightPhrase(inFlight) {
+    if (inFlight.kind === 'startup')
+        return 'before the child process had finished starting';
+    if (inFlight.kind === 'population')
+        return 'before its population completed';
     if (inFlight.kind === 'check')
         return `while the check "${inFlight.name}" was running`;
     if (inFlight.kind === 'reporting') {
@@ -637,6 +632,8 @@ function inFlightPhrase(inFlight) {
     return 'while no check was running — either between the population and the first'
         + ' statement, or after the last one had filed its cost';
 }
+/** The supervisor's kind for a child whose exit contradicts its own complete document. */
+const EXIT_DISAGREES = 'exit-disagrees';
 /**
  * What ended the child, as a phrase.
  *
@@ -650,12 +647,21 @@ function deathPhrase(death) {
         return `the child process could not be started at all (${death.binary}: ${death.detail})`;
     }
     if (death.kind === 'kill-failed') {
-        return 'the budget was blown and the SIGKILL that should have ended the run was REFUSED'
-            + ` (${death.detail})`;
+        return death.refused
+            ? `the budget was blown and the SIGKILL that should have ended the run was REFUSED (${death.detail})`
+            : `the budget was blown and the SIGKILL that should have ended the run DID NOT END IT (${death.detail})`;
     }
     if (death.kind === 'no-output') {
         return `the child process exited ${death.code} and published no report at all`;
     }
+    if (death.kind === 'unparseable-output') {
+        return `the child process exited ${death.code} and published a report that is not this`
+            + ` command's document, most likely cut off mid-write (${death.detail})`;
+    }
+    if (death.kind === EXIT_DISAGREES) {
+        return `the child process published a complete report whose own verdict is exit ${death.documentExit},`
+            + ` and then exited ${death.code}`;
+    }
     return 'the child process ended with neither an exit code nor a signal';
 }
 /**
@@ -681,21 +687,25 @@ function spawnFailedRemedy(detail) {
         + ' anything about the SQL.';
 }
 /**
- * What to do about a kill the kernel refused.
+ * What to do about a kill that did not end the child — refused, or accepted and ineffective.
  *
  * ⛔ This must never be composed from the spawn-failure sentence, however
  * similar the plumbing is. The two are opposites: one child never existed, and
  * this one is, as far as this process can tell, STILL RUNNING.
  *
- * @param death - The refused kill, and the pid it left behind
+ * @param death - The kill that failed, and the pid it left behind
  * @returns The remedy sentence
  */
-function killFailedRemedy(detail, pid) {
-    const handle = pid === undefined
+function killFailedRemedy(death) {
+    const handle = death.pid === undefined
         ? ' The child\'s pid is not known to this process.'
-        : ` The child was process ${pid}.`;
+        : ` The child was process ${death.pid}.`;
+    const how = death.refused
+        ? ` SIGKILL and the kernel would not deliver it (${death.detail}), which normally means EPERM.`
+        : ` SIGKILL, the kernel accepted it, and the process still did not end (${death.detail}) —`
+            + ' which normally means it is stuck in uninterruptible I/O (a hung network mount, a wedged disk).';
     return ' The run started, ran past its budget, and then REFUSED TO DIE: the watchdog sent'
-        + ` SIGKILL and the kernel would not deliver it (${detail}), which normally means EPERM.`
+        + how
         + handle
         + ' It may still be running and still holding whatever the statement was holding, so'
         + ' check for it and end it by hand before starting another run. Nothing about the SQL'
@@ -803,7 +813,7 @@ function noOutputRemedy(code) {
             + ' — surfaces as an exit code what macOS and Linux report as SIGABRT itself, and it is the'
             + ' same event.' + signalRemedy('SIGABRT');
     }
-    return ` Exit ${code} is not Node's abort code, and the child published none of the document`
+    return ` Exit ${code} is not Node's abort code, and the child published no usable copy of the document`
         + ' every path through this command ends by writing — so this is either a termination from'
         + ' outside that left an exit code instead of a signal, or a defect in vat. The child\'s stderr'
         + ' was inherited, so whatever it managed to say is above this report; if there is nothing'
@@ -829,16 +839,33 @@ function noOutputRemedy(code) {
  */
 function deathRemedy(death) {
     if (death.kind === 'kill-failed')
-        return killFailedRemedy(death.detail, death.pid);
+        return killFailedRemedy(death);
     if (death.kind === 'spawn-failed')
         return spawnFailedRemedy(death.detail) + WATCHDOG_UNINVOLVED;
     if (death.kind === 'signal')
         return signalRemedy(death.signal) + WATCHDOG_UNINVOLVED;
-    if (death.kind === 'no-output')
+    if (death.kind === 'no-output' || death.kind === 'unparseable-output') {
         return noOutputRemedy(death.code) + WATCHDOG_UNINVOLVED;
+    }
+    if (death.kind === EXIT_DISAGREES)
+        return EXIT_DISAGREES_REMEDY + WATCHDOG_UNINVOLVED;
     return ' The cause is outside anything this command can observe; the child left no exit code'
         + ' to report.' + WATCHDOG_UNINVOLVED;
 }
+/**
+ * Why a child whose exit disagrees with its own document is not forwarded, and where to look.
+ *
+ * ⚠️ It does not guess which of the two is true. Every path through this command ends on the code
+ * its document derives, so the disagreement is either something ending the child after it wrote
+ * (a crash in teardown, an external termination that left a code) or a defect in vat — and the
+ * report cannot tell them apart.
+ */
+const EXIT_DISAGREES_REMEDY = ' Every path through this command ends on the exit code its own document derives, so the two'
+    + ' should never disagree: either something ended the child AFTER it wrote its report — a crash'
+    + ' during shutdown, or a termination from outside that left an exit code — or vat has a defect.'
+    + ' Which one cannot be told from here, so the report is withheld rather than forwarded as the'
+    + ' verdict. The child\'s stderr was inherited, so whatever it said is above this report; re-run'
+    + ' it, and if the disagreement repeats, report the exit code with the platform.';
 /**
  * The sentence that keeps an abnormal death from being blamed on the bound.
  *
@@ -852,6 +879,9 @@ const WATCHDOG_UNINVOLVED = ' The budget was not what ended this run — the wat
 /**
  * The sentence that says what this document does NOT contain.
  *
+ * @param checksCompleted - How many checks filed a cost before the run stopped
+ * @returns The sentence
+ *
  * 🚨 Load-bearing, and shared by both endings. The progress log records COSTS,
  * not findings: a check that completed contributes its `rows` (how many rows its
  * statement selected) but not the violations those rows would have become,
@@ -859,9 +889,18 @@ const WATCHDOG_UNINVOLVED = ' The budget was not what ended this run — the wat
  * issue list as the complete account would conclude the finished rules found
  * nothing.
  */
-const INCOMPLETE_NOTICE = ' ⚠️ The checks listed under `checks` DID complete and `rows` is what each'
-    + ' statement selected, but their individual violations are NOT in `issues`: the'
-    + ' progress log records costs, not findings. Read that list as incomplete.';
+function incompleteNotice(checksCompleted) {
+    // 🚨 Only when something completed. It used to be appended unconditionally,
+    // so a run killed before its first statement told the operator that the
+    // checks under an EMPTY `checks` list "DID complete".
+    if (checksCompleted === 0) {
+        return ' No check completed before the run stopped, so `checks` is empty and no result'
+            + ' of this run is missing from `issues` — there were none.';
+    }
+    return ' ⚠️ The checks listed under `checks` DID complete and `rows` is what each'
+        + ' statement selected, but their individual violations are NOT in `issues`: the'
+        + ' progress log records costs, not findings. Read that list as incomplete.';
+}
 /**
  * The finding for a run that was interrupted, however it was interrupted.
  *
@@ -878,16 +917,35 @@ const INCOMPLETE_NOTICE = ' ⚠️ The checks listed under `checks` DID complete
  *
  * @param inFlight - What the run was doing when the log stopped growing
  * @param ending - Which way the run ended, and what the operator can do
+ * @param checksCompleted - How many checks filed a cost before it stopped
  * @returns The run-integrity finding
  */
-function interruptedRunFinding(inFlight, ending) {
+function interruptedRunFinding(inFlight, ending, checksCompleted) {
     const where = inFlightPhrase(inFlight);
     const message = ending.kind === 'budget'
-        ? budgetKillMessage(inFlight, ending.budgetSecs, where)
-        : `This run DIED before it finished: ${deathPhrase(ending.death)} ${where}, so the checks`
-            + ' after it never executed and this document is not a verdict.'
-            + deathRemedy(ending.death);
-    return runIntegrityFinding(message + INCOMPLETE_NOTICE);
+        ? budgetKillMessage(inFlight, ending, where)
+        : deathMessage(ending.death, where);
+    return runIntegrityFinding(message + incompleteNotice(checksCompleted));
+}
+/**
+ * What an abnormal death means.
+ *
+ * 🪤 A child whose exit disagrees with its document did NOT die mid-run — it finished every check
+ * and wrote a whole report — so it gets its own sentence rather than "DIED before it finished …
+ * the checks after it never executed", which would be false about it.
+ *
+ * @param death - The ending the supervisor resolved
+ * @param where - The clause naming the unit, from {@link inFlightPhrase}
+ * @returns The message body
+ */
+function deathMessage(death, where) {
+    if (death.kind === EXIT_DISAGREES) {
+        return `This run's exit contradicts its own report: ${deathPhrase(death)}, so neither can be`
+            + ' trusted as the verdict and this document replaces the report.' + deathRemedy(death);
+    }
+    return `This run DIED before it finished: ${deathPhrase(death)} ${where}, so the checks`
+        + ' after it never executed and this document is not a verdict.'
+        + deathRemedy(death);
 }
 /**
  * What a WATCHDOG kill means, which depends entirely on what was in flight.
@@ -906,12 +964,23 @@ function interruptedRunFinding(inFlight, ending) {
  * issues takes ~17 s after `checks-complete` is filed, which is one budget
  * window on its own.
  *
+ * 🔑 Every remedy names the bound through {@link raiseBoundSentence}, so a phase is never told to
+ * pass a flag its own verb (`vat validate`) rejects, nor promised a way to raise its bound.
+ *
  * @param inFlight - What the log's last state says
- * @param budgetSecs - The bound that was blown
+ * @param ending - The kill: the bound that was blown, and who ran the checks
  * @param where - The clause naming the unit, from {@link inFlightPhrase}
  * @returns The message body
  */
-function budgetKillMessage(inFlight, budgetSecs, where) {
+function budgetKillMessage(inFlight, ending, where) {
+    const { budgetSecs, invocation } = ending;
+    const raise = raiseBoundSentence(invocation);
+    if (inFlight.kind === 'startup' || inFlight.kind === 'population') {
+        return `This run made no progress for ${budgetSecs}s and was killed ${where}, so no`
+            + ' check ran and this document is not a verdict. There is no projection, so the'
+            + ' population fields in `data` are null and `examined` is 0.'
+            + (inFlight.kind === 'startup' ? startupRemedy(raise) : populationRemedy(raise));
+    }
     if (inFlight.kind === 'reporting') {
         return `This run made no progress for ${budgetSecs}s and was killed ${where}.`
             + ' Every declared check had already finished and filed its cost, so no statement was'
@@ -919,37 +988,48 @@ function budgetKillMessage(inFlight, budgetSecs, where) {
             + ' being assembled, not a rule that would not return. Serialising a large result is'
             + ' linear in how much there is — 2,000,000 issues take about 17 seconds — so look at'
             + ' the rules under `checks` that produced the most rows and narrow them (a `LIMIT`, or'
-            + ' one row per violation rather than one per member), or raise the bound with'
-            + ' `--budget <seconds>` so the document has time to be written.';
+            + ' one row per violation rather than one per member), or give the document more time to'
+            + ` be written.${raise}`;
     }
     return `This run made no progress for ${budgetSecs}s and was killed ${where}, so the`
         + ' checks after it never executed and this document is not a verdict.'
         + ' A statement that will not finish cannot be stopped from inside the process —'
         + ' the query is synchronous and holds the event loop — so the bound is enforced by'
-        + ' killing the run. Raise it with `--budget <seconds>` if the work is legitimately'
-        + ' slow, or `--budget 0` to remove it (the run can then hang forever).';
+        + ' killing the run. If the work is legitimately slow, it needs more time.'
+        + raise
+        + (invocation === 'standalone'
+            ? ' `--budget 0` removes it (the run can then hang forever).'
+            : '');
 }
 /**
- * The refusal when there is no population line to build a document from.
+ * What to do about a kill that landed before the child had BOOTED.
  *
- * Separate wording per ending for the same reason the finding is: telling an
- * operator whose child was OOM-killed to raise `--budget` sends them to change
- * the one thing that had nothing to do with it.
+ * Nothing had touched the tree yet — Node and the CLI were still loading — so
+ * sizing the budget against the population would be advice about a unit that
+ * never began. A boot that outlasts the budget is a saturated machine or a bound
+ * too small to be one.
  *
- * @param ending - Which way the run ended
- * @returns The operator-error message
+ * @param raise - How to raise the bound, from {@link raiseBoundSentence}
+ * @returns The remedy sentence
  */
-function noPopulationMessage(ending) {
-    const tail = ' There is no projection to report on and no honest document to publish.';
-    if (ending.kind === 'abnormal') {
-        return `This run DIED before its population completed: ${deathPhrase(ending.death)}.`
-            + tail + deathRemedy(ending.death);
-    }
-    return `The run made no progress for ${ending.budgetSecs}s and was killed before its`
-        + ' population completed.' + tail
-        + ' Population is legitimately slow on a large tree, and it reports progress only when it'
-        + ' FINISHES, so the budget is a total bound for that one unit — raise it with'
-        + ' `--budget <seconds>` before assuming the crawl is stuck.'
+function startupRemedy(raise) {
+    return ' Node and vat were still loading, so neither your tree nor your SQL is implicated: a'
+        + ' boot that outlasts the bound means a heavily loaded machine or a bound far smaller than'
+        + ` any run can meet.${raise}`;
+}
+/**
+ * What to do about a kill that landed during the population.
+ *
+ * 🔑 The measured numbers are labelled as someone else's trees. An operator
+ * given one number reads it as a promise about theirs.
+ *
+ * @param raise - How to raise the bound, from {@link raiseBoundSentence}
+ * @returns The remedy sentence
+ */
+function populationRemedy(raise) {
+    return ' Population is legitimately slow on a large tree, and it reports progress only when it'
+        + ' FINISHES, so the budget is a total bound for that one unit — a crawl that outlasts it is'
+        + ` not necessarily stuck.${raise}`
         + ' For scale, two MEASURED trees, neither of them yours: VAT\'s own repository is ~1.2s'
         + ' warm and 33-35s with a cold parse cache; a 10,000-file adopter tree is ~5s warm and'
         + ' 16.5s cold. Your tree is a third number.';
@@ -967,12 +1047,15 @@ function noPopulationMessage(ending) {
  * keep in step with every future field — and the failure mode is silent, because
  * nobody reads an interrupted run's document until the day they need it.
  *
- * 🚨 **A run interrupted during POPULATION gets no document at all.** There is no
- * projection, so `population`, `populationSecs` and `membersEnumerated` have no
- * honest value — and inventing `membersEnumerated: 0` would be worse than a
- * blank, because that value already MEANS "this gate ran over an empty corpus",
- * which is a different and wrong claim. The throw becomes an operator error
- * (exit 2) through the same `handleReportCommandError` path everything else here uses.
+ * 🚨 **The exit code follows the CAUSE, and the cause is what was in flight.**
+ * A run killed or dead while a check's statement ran examined the tree, and
+ * that check is broken: `status: findings`, `RESOURCE_CHECK_BROKEN`, exit 1. A
+ * run stopped during STARTUP or POPULATION examined nothing: it is a command
+ * that could not do its job — `status: error`, exit 2 — decided by
+ * {@link buildCheckOutputData} from `populated: null`, never by the caller. It
+ * used to THROW there, which lost the document; now the document is published,
+ * with the population's fields `null` rather than invented, and the reason in
+ * `error`.
  *
  * @param options - The wreckage
  * @param options.entries - What `parseProgressLog` recovered
@@ -980,34 +1063,37 @@ function noPopulationMessage(ending) {
  * @param options.ending - Which way the run was interrupted
  * @param options.durationMs - Wall time from spawn to ending
  * @returns The input to {@link buildCheckOutputData}
- * @throws When the child never reported a completed population
  */
 export function buildInterruptedCheckInput(options) {
     const { entries, root, ending, durationMs } = options;
     const population = entries.find((entry) => entry.kind === 'population');
-    if (population === undefined)
-        throw new Error(noPopulationMessage(ending));
+    // 🪤 Rebuilt field by field rather than passed through. The log's check
+    // entry carries a `kind` discriminator that `CheckCost` does not, and the
+    // conditional spreads keep `rows`/`broken` ABSENT rather than `undefined` —
+    // which is what makes `rows: 0` on a statement that never returned
+    // impossible, exactly as it is on the completed path.
+    const costs = entries.filter((entry) => entry.kind === 'check').map((entry) => ({
+        name: entry.name,
+        durationMs: entry.durationMs,
+        ...(entry.rows === undefined ? {} : { rows: entry.rows }),
+        ...(entry.broken === undefined ? {} : { broken: entry.broken }),
+        ...(entry.builtin === undefined ? {} : { builtin: entry.builtin }),
+    }));
     return {
         root,
         durationMs,
-        population: population.population,
-        populationMs: population.populationMs,
-        lensMs: population.lensMs,
-        lensesEvaluated: population.lensesEvaluated,
-        membersEnumerated: population.membersEnumerated,
-        issues: [interruptedRunFinding(unitInFlight(entries), ending)],
-        // 🪤 Rebuilt field by field rather than passed through. The log's check
-        // entry carries a `kind` discriminator that `CheckCost` does not, and the
-        // conditional spreads keep `rows`/`broken` ABSENT rather than `undefined` —
-        // which is what makes `rows: 0` on a statement that never returned
-        // impossible, exactly as it is on the completed path.
-        costs: entries.filter((entry) => entry.kind === 'check').map((entry) => ({
-            name: entry.name,
-            durationMs: entry.durationMs,
-            ...(entry.rows === undefined ? {} : { rows: entry.rows }),
-            ...(entry.broken === undefined ? {} : { broken: entry.broken }),
-            ...(entry.builtin === undefined ? {} : { builtin: entry.builtin }),
-        })),
+        populated: population === undefined
+            ? null
+            : {
+                population: population.population,
+                lensPopulation: population.lensPopulation,
+                populationMs: population.populationMs,
+                lensMs: population.lensMs,
+                lensesEvaluated: population.lensesEvaluated,
+                membersEnumerated: population.membersEnumerated,
+            },
+        issues: [interruptedRunFinding(unitInFlight(entries), ending, costs.length)],
+        costs,
     };
 }
 /**
@@ -1090,42 +1176,43 @@ export function runProjectChecks(options) {
         costs,
     };
 }
-/**
- * Serialize the document in the format the operator asked for.
- *
- * Extracted because BOTH endings publish one — a completed run and a killed one
- * — and two copies of a two-branch format switch is how one of them ends up
- * ignoring `--format json`.
- *
- * @param payload - The document
- * @param format - `json`, or anything else for YAML
- */
-function emitCheckDocument(payload, format) {
-    writeStructuredOutput(payload, format);
-}
 /**
  * The child's argv — this very command, plus the hidden flag that stops it
  * spawning a child of its own.
  *
- * 🚨 `--cost-log` is ALWAYS appended, and that is the recursion guard. Its
+ * 🚨 `--supervised-by` is ALWAYS appended, and that is the recursion guard. Its
  * presence is the sole discriminator between "supervise a child" and "do the
- * work"; a path that built these arguments without it would fork bomb.
- *
- * @param pathArg - The corpus root the operator named, or undefined
- * @param options - What the operator passed
+ * work"; a path that built these arguments without it would fork bomb. Its one
+ * value carries who started the child (which decides the notices the child owes
+ * the operator), this process's pid (which the child checks is its parent's) and
+ * the progress log — see `supervisedByValue`.
+ *
+ * 🔑 The operand is the root the PARENT resolved, always. The child is spawned
+ * with no `cwd`, so without it the child would resolve its own root from the
+ * INHERITED working directory — which differs from the parent's root whenever
+ * the operator named the project rather than standing in it: `vat resources
+ * check <inner>` run from an outer project would check the outer tree and
+ * report it as the inner one. (`vat validate` takes no operand and resolves its
+ * root from the working directory the child inherits, so for it the operand
+ * restates what the child would have found — it is passed so the phase cannot
+ * depend on that coincidence.)
+ *
+ * @param root - The project root the parent resolved
+ * @param request - What the child is asked to run, and in which format
  * @param logPath - The progress log both sides watch
  * @returns The child's arguments after the CLI entry point
  */
-function childArgs(pathArg, options, logPath) {
+function childArgs(root, request, logPath) {
     return [
         'resources',
         'check',
-        ...(pathArg === undefined ? [] : [pathArg]),
-        ...(options.check === undefined ? [] : ['--check', options.check]),
-        ...(options.format === undefined ? [] : ['--format', options.format]),
-        ...(options.debug === true ? ['--debug'] : []),
-        '--cost-log',
-        logPath,
+        root,
+        ...(request.check === undefined ? [] : ['--check', request.check]),
+        '--format',
+        request.format,
+        ...(request.debug ? ['--debug'] : []),
+        SUPERVISED_BY_FLAG,
+        supervisedByValue({ invoker: request.invocation, progressLog: logPath }),
     ];
 }
 /**
@@ -1138,27 +1225,23 @@ function childArgs(pathArg, options, logPath) {
  * which are all of them but one, that would accumulate.
  *
  * @param options - The run
- * @param options.pathArg - The corpus root the operator named, or undefined
- * @param options.options - What the operator passed
+ * @param options.root - The project root the caller resolved. REQUIRED: the
+ *   child checks exactly this tree, and a killed run's document is labelled with it
+ * @param options.request - What the child is asked to run, and who asked
  * @param options.budgetSecs - The bound, in seconds
  * @returns What to publish, and with what exit code
- * @throws When the child was killed before its population completed
  */
 async function superviseCheckRun(options) {
-    const startDir = options.pathArg ?? process.cwd();
-    // 🪤 The SILENT resolution, deliberately. `projectRootOrLoudCwd` warns on
-    // stderr when there is no project ancestor, and the CHILD runs that policy for
-    // real — a parent that ran it too would print the same warning twice for one
-    // run. The parent needs a root only to label a KILLED run's document.
-    const root = projectRootOrNull(startDir) ?? safePath.resolve(startDir);
-    return withProgressLog(async (logPath) => {
+    const { root, request } = options;
+    const { value: ending, leftover } = await withProgressLog(async (log) => {
         const run = await superviseCheck({
-            args: childArgs(options.pathArg, options.options, logPath),
-            logPath,
+            args: childArgs(root, request, log.path),
+            log,
             budgetMs: options.budgetSecs * 1000,
+            format: request.format,
         });
         if (run.outcome === 'completed')
-            return { forward: run.stdout, code: run.code };
+            return { forward: run.document };
         return {
             payload: buildCheckOutputData(buildInterruptedCheckInput({
                 entries: parseProgressLog(run.log),
@@ -1169,12 +1252,76 @@ async function superviseCheckRun(options) {
                 // argument — so a child that aborted on its heap limit printed nothing
                 // and exited 0, on precisely the runaway shape the bound exists for.
                 ending: run.outcome === 'killed'
-                    ? { kind: 'budget', budgetSecs: options.budgetSecs }
+                    ? { kind: 'budget', budgetSecs: options.budgetSecs, invocation: request.invocation }
                     : { kind: 'abnormal', death: run.death },
                 durationMs: run.elapsedMs,
             })),
         };
     });
+    return withLeftover(ending, leftover);
+}
+/**
+ * `ending` with the progress log's directory, when the OS would not remove it, as one
+ * `TREE_CLEANUP_INCOMPLETE` warning beside the checks that ran. A forwarded document is then
+ * published re-built rather than byte for byte: it gained a finding the child never knew of.
+ */
+function withLeftover(ending, leftover) {
+    if (leftover === undefined)
+        return ending;
+    const added = toFindings([leftoverIssueOf(leftover)]);
+    // The child's document was validated against this verb's schema when it was read.
+    const report = 'forward' in ending ? ending.forward.report : ending.payload;
+    return { payload: withAddedFindings(report, added) };
+}
+/**
+ * The `checks` phase of an orchestrator: the same supervised child `vat resources check` runs,
+ * over the whole project, and its report is the phase's report.
+ *
+ * 🔑 **The report is the ending's own, in both arms** — the child's forwarded document, or the
+ * document a killed or dead child's progress log rebuilt. There is no per-arm exit mapping: the
+ * report's status already says what was in flight (findings with `RESOURCE_CHECK_BROKEN` once
+ * the population was recorded, `error` before it), and the orchestrator derives the exit from it
+ * as it does for every phase.
+ *
+ * @param options - The phase
+ * @param options.root - The project root the orchestrator resolved. REQUIRED, so no caller can
+ *   fall back to the working directory and check a different project from the one it validated
+ * @param options.debug - Whether the orchestrator was run with `--debug`, forwarded to the child
+ * @returns The phase's report
+ */
+export async function runResourcesCheckPhase(options) {
+    const ending = await superviseCheckRun({
+        root: options.root,
+        request: { check: undefined, format: 'json', debug: options.debug, invocation: 'phase' },
+        budgetSecs: DEFAULT_BUDGET_SECONDS,
+    });
+    return { report: 'forward' in ending ? ending.forward.report : ending.payload };
+}
+/**
+ * Warn, on the invoked process's stderr, that the project declares no checks of its own.
+ *
+ * 🪤 Stderr only, and it decides NOTHING — the document is what the exit code is computed from
+ * and what CI parses. ⚠️ It does not stand beside a refusal: the built-in set runs, so the run
+ * DID assert something. What the operator needs to know is that the project is relying entirely
+ * on VAT's defaults, which is what a deleted `checks:` block looks like.
+ *
+ * Printed only by the process the operator ran as `vat resources check` — never by a supervised
+ * child (any `--supervised-by` process) and so never by an orchestrator's `checks` phase, where a
+ * project with `resources:` and no `resources.checks` still runs the built-ins and "no checks of
+ * its own" is not news on every run.
+ *
+ * @param checks - The project's declared checks, or undefined
+ * @param logger - Where the warning goes
+ */
+function warnWhenNoOwnChecks(checks, logger) {
+    if (checks !== undefined && Object.keys(checks).length > 0)
+        return;
+    logger.warn(`No checks of this project's own are declared, so this run asserted only VAT's`
+        + ` built-in set (${BUILTIN_CHECK_NAMES.join(', ')}).`
+        + ' Add your own under `resources.checks` in vibe-agent-toolkit.config.yaml;'
+        + ' each is a description plus one SQL statement selecting the rows that VIOLATE it.'
+        + ' `vat resources check --help` prints the SQL each built-in is equivalent to,'
+        + ' as a starting point.');
 }
 /**
  * Run the project's declared checks against its projection.
@@ -1187,11 +1334,14 @@ async function superviseCheckRun(options) {
  *
  * `query`'s author is at the keyboard, and Ctrl-C already works for them. It
  * works for one reason worth stating, because it is fragile: NO signal handler
- * is installed anywhere on this path. A process blocked in synchronous
+ * is installed in a process that runs the SQL. A process blocked in synchronous
  * `node:sqlite` dies instantly on SIGINT while that remains true, and SURVIVES
  * SIGINT and SIGTERM the moment a handler exists — the handler is a JS callback
  * and the event loop that would schedule it is the blocked resource. Adding one
- * would take Ctrl-C away from `query` without adding anything to `check`.
+ * would take Ctrl-C away from `query`, and from `check`'s child and its
+ * `--budget 0` run. (`check`'s SUPERVISING process does install handlers while
+ * it supervises — its event loop is free — only to take its child down with it;
+ * see `check-supervisor.ts`.)
  *
  * `check` runs unattended in CI, where nobody is there to press it. So it gets a
  * bound enforced from outside itself, and a hang becomes a bounded failure
@@ -1212,89 +1362,163 @@ async function superviseCheckRun(options) {
 export async function checkCommand(pathArg, options) {
     const logger = createLogger({ debug: options.debug ?? false });
     const startTime = Date.now();
+    // The two formats this verb offers (Commander refuses any other).
+    const format = options.format === 'json' ? 'json' : 'yaml';
     try {
         if (pathArg !== undefined)
             assertDirectoryArgument(pathArg);
         const budgetSecs = parseBudgetSeconds(options.budget);
         // Before anything is spawned: a budget the fork below would silently ignore
         // is an operator error, not a bound.
-        requireSupervisableFlags({
-            costLog: options.costLog,
+        const child = requireSupervisableFlags({
+            supervisedBy: options.supervisedBy,
             budgetRaw: options.budget,
             budgetSecs,
         });
-        // The presence of `--cost-log` says "you ARE the child". `--budget 0` says
+        // The process the operator ran — never a supervised child — says when the
+        // project declares no checks of its own, and prints the config's warnings
+        // with it. See {@link warnWhenNoOwnChecks}.
+        const root = standaloneRoot(pathArg);
+        if (child === undefined) {
+            warnWhenNoOwnChecks(loadConfigCached(root, 'source')?.resources?.checks, logger);
+        }
+        // The presence of `--supervised-by` says "you ARE the child". `--budget 0` says
         // the operator declined the bound; both run the work here, and the second
         // can therefore hang forever, which its help text says.
-        if (!runsInThisProcess({ costLog: options.costLog, budgetSecs })) {
-            const ending = await superviseCheckRun({ pathArg, options, budgetSecs });
-            if ('forward' in ending) {
-                // Verbatim. The child already built the document the operator's
-                // `--format` asked for, and re-serializing it here would be a second
-                // place for that shape to live.
-                //
-                // ⚠️ `durationSecs` in it is therefore the CHILD's wall time and does
-                // not include this process's own startup and spawn (~0.15 s measured).
-                // Deliberate: the field is a breakdown that `populationSecs` and the
-                // per-rule costs have to reconcile against, and folding in a supervisor
-                // overhead none of them can account for would leave a remainder a
-                // reader would attribute to whichever rule they were looking at — the
-                // exact defect `CheckCost` documents.
-                writeStdoutSync(ending.forward);
-                process.exit(ending.code);
-            }
-            emitCheckDocument(ending.payload, options.format);
-            // ⛔ Never OK. A run that did not finish — killed by the watchdog OR dead of
-            // its own memory — must not look like a pass. FINDINGS, because the
-            // document it just published says `status: findings` with the killed
-            // check named as one: the checks that completed are kept, and the exit
-            // code follows the document, as everywhere else.
-            process.exit(ExitCode.FINDINGS);
-        }
-        const projectRoot = projectRootOrLoudCwd(pathArg ?? process.cwd(), logger);
-        const config = loadConfigCached(projectRoot);
-        const checks = config?.resources?.checks;
-        if (checks === undefined || Object.keys(checks).length === 0) {
-            // 🪤 Stderr only, and it decides NOTHING — the document is what the exit
-            // code is computed from and what CI parses. ⚠️ It does not stand beside a
-            // refusal: the built-in set runs here, so this run DID assert something.
-            // What the operator needs to know is that the project is relying entirely
-            // on VAT's defaults, which is what a deleted `checks:` block looks like.
-            logger.warn(`No checks of this project's own are declared, so this run asserted only VAT's`
-                + ` built-in set (${BUILTIN_CHECK_NAMES.join(', ')}).`
-                + ' Add your own under `resources.checks` in vibe-agent-toolkit.config.yaml;'
-                + ' each is a description plus one SQL statement selecting the rows that VIOLATE it.'
-                + ' `vat resources check --help` prints the SQL each built-in is equivalent to,'
-                + ' as a starting point.');
+        const ending = runsInThisProcess({ supervisedBy: options.supervisedBy, budgetSecs })
+            ? { payload: await withNoticeAudience(noticeAudienceOf(child), () => runChecksHere(pathArg, options, child, logger, startTime)) }
+            : await superviseStandalone(root, options, format, budgetSecs);
+        if ('forward' in ending) {
+            // Verbatim (unless `withLeftover` had to add a finding to it) — the supervisor already checked it is
+            // this verb's document — and on the code that document derives. The child already built what the operator's `--format` asked for, and
+            // re-serializing it here would be a second place for that shape to live.
+            //
+            // ⚠️ `durationSecs` in it is therefore the CHILD's wall time and does
+            // not include this process's own startup and spawn (~0.15 s measured).
+            // Deliberate: the field is a breakdown that `populationSecs` and the
+            // per-rule costs have to reconcile against, and folding in a supervisor
+            // overhead none of them can account for would leave a remainder a
+            // reader would attribute to whichever rule they were looking at — the
+            // exact defect `CheckCost` documents.
+            //
+            // 🪤 `return` it, though its type is `never`: under a test's returning
+            // exit spy a bare call would fall through to the second ending below.
+            return endWithForwardedDocument(ending.forward);
         }
-        // Before the crawl: a mistyped flag is an operator error and pays nothing.
-        requireKnownCheck(BUILTIN_CHECK_NAMES, checks ?? {}, options.check);
-        // Also before the crawl, and for the same reason: an override that overrides
-        // nothing is knowable from the config alone, and the operator should read it
-        // beside the other config news rather than after a full population.
-        warnUndeclaredOverrides(checks ?? {}, config?.resources?.validation, logger);
-        const outcome = await runOutcome({
-            root: projectRoot,
-            checks: checks ?? {},
-            only: options.check,
-            logger,
-            validation: config?.resources?.validation,
-            onProgress: options.costLog === undefined
-                ? undefined
-                : createProgressWriter(options.costLog),
-        });
-        const payload = buildCheckOutputData({
-            ...outcome,
-            root: projectRoot,
-            durationMs: Date.now() - startTime,
-        });
-        emitCheckDocument(payload, options.format);
-        process.exit(payload.summary.errors > 0 ? ExitCode.FINDINGS : ExitCode.OK);
+        // A killed child is never OK and never decided here: its document carries
+        // a RUN_INTEGRITY finding (exit 1) or the error branch (exit 2), and the
+        // writer derives the code from it, as everywhere else.
+        endWithReport('resources check', ending.payload, format);
     }
     catch (error) {
-        handleReportCommandError(error, logger, startTime, 'Check', options.format);
+        // `vat resources check` offers no `--strict`: warnings never fail it.
+        endWithRefusal('resources check', refusalCodeOf(error), error, format, { strict: false }, NOTHING_FINISHED);
     }
 }
+/**
+ * Which notices the process running the checks prints.
+ *
+ * Any process that is not a supervised child prints every notice. A supervised child prints no
+ * config warning — its invoking process loaded the same config and printed them — and prints the
+ * store notice only when a standalone `vat resources check` started it: that supervisor opens no
+ * store (keying one is a git snapshot, unbounded work it must not do before its watchdog exists),
+ * while `vat validate` opened its store scope, and printed the notice, before any phase ran.
+ *
+ * @param child - The supervised child this process is, or undefined when it is not one
+ * @returns The audience
+ */
+function noticeAudienceOf(child) {
+    if (child === undefined)
+        return EVERY_NOTICE;
+    return { config: false, store: child.invoker === 'standalone' };
+}
+/**
+ * Supervise the checks child for a standalone `vat resources check`.
+ *
+ * 🔑 Nothing unbounded runs here before the spawn: no store is opened and no tree is snapshotted,
+ * so the watchdog exists before any work that could hang. The store notice is the child's to print
+ * (see {@link noticeAudienceOf}).
+ *
+ * @param root - The project root this process resolved, which the child checks
+ * @param options - Parsed command-line options
+ * @param format - The document format the operator asked for
+ * @param budgetSecs - The bound, in seconds
+ * @returns What to publish
+ */
+function superviseStandalone(root, options, format, budgetSecs) {
+    return superviseCheckRun({
+        root,
+        request: { check: options.check, format, debug: options.debug === true, invocation: 'standalone' },
+        budgetSecs,
+    });
+}
+/**
+ * The project root a standalone `vat resources check` names, resolved SILENTLY.
+ *
+ * 🪤 Silent deliberately. `projectRootOrLoudCwd` warns on stderr when there is
+ * no project ancestor, and the process that runs the checks (the child, or this
+ * one under `--budget 0`) runs that policy for real — resolving loudly here too
+ * would print the same warning twice for one run.
+ *
+ * @param pathArg - Where to look for the project, or omitted for the current directory
+ * @returns The project root, or the resolved start directory when there is none
+ */
+function standaloneRoot(pathArg) {
+    const startDir = pathArg ?? process.cwd();
+    return projectRootOrNull(startDir) ?? safePath.resolve(startDir);
+}
+/**
+ * Run the checks in this process and build the document.
+ *
+ * @param pathArg - Where to look for the project, or omitted for the current directory
+ * @param options - Parsed command-line options
+ * @param child - The supervised child this process is (its progress log), or undefined
+ * @param logger - Where warnings go
+ * @param startTime - When the command started (from Date.now())
+ * @returns The document
+ */
+async function runChecksHere(pathArg, options, child, logger, startTime) {
+    // 🔑 FIRST, before anything that touches the tree: the child has booted.
+    // The watchdog's clock started at the spawn, so without this line Node's
+    // startup and the CLI's import were charged to the population — the one
+    // unit the budget is already a total bound for. See `StartedEntrySchema`.
+    // And before that line: the child that outlives its supervisor ends itself — see
+    // `endWhenSupervisorGone` for when that can and cannot be noticed.
+    if (child !== undefined)
+        endWhenSupervisorGone(child.supervisorPid, process.stdin);
+    const onProgress = child === undefined
+        ? undefined
+        : createProgressWriter(child);
+    onProgress?.({ kind: 'started' });
+    const projectRoot = projectRootOrLoudCwd(pathArg ?? process.cwd(), logger);
+    const config = loadConfigCached(projectRoot, 'source');
+    const checks = config?.resources?.checks;
+    // Before the crawl: a mistyped flag is an operator error and pays nothing.
+    requireKnownCheck(BUILTIN_CHECK_NAMES, checks ?? {}, options.check);
+    // Also before the crawl, and for the same reason: an override that overrides
+    // nothing is knowable from the config alone, and the operator should read it
+    // beside the other config news rather than after a full population.
+    warnUndeclaredOverrides(checks ?? {}, config?.resources?.validation, logger);
+    const outcome = await runOutcome({
+        root: projectRoot,
+        checks: checks ?? {},
+        only: options.check,
+        logger,
+        validation: config?.resources?.validation,
+        onProgress,
+    });
+    const { issues, costs, ...populated } = outcome;
+    // The checks ran synchronously: a supervisor lost meanwhile ends this child HERE, unpublished.
+    if (child !== undefined)
+        await letSupervisorLossSurface();
+    return buildCheckOutputData({
+        issues,
+        costs,
+        populated,
+        root: projectRoot,
+        durationMs: Date.now() - startTime,
+    });
+}
 /**
  * Populate once, run the checks, resolve their severities.
  *
@@ -1308,7 +1532,7 @@ export async function checkCommand(pathArg, options) {
  *   outside this process, or undefined when nothing is watching
  * @returns The findings and the provenance of the population behind them
  */
-async function runOutcome(options) {
+function runOutcome(options) {
     const { root, checks, only, logger, validation, onProgress } = options;
     // 🪤 **No `preflight` here, deliberately.** `withQueriedProjection` can compile
     // statements against the empty schema before populating — `vat resources query`
@@ -1336,6 +1560,7 @@ async function runOutcome(options) {
         onProgress?.({
             kind: 'population',
             population: provenance.population,
+            lensPopulation: provenance.lensPopulation,
             populationMs: provenance.populationMs,
             lensMs: provenance.lensMs,
             lensesEvaluated: [...provenance.lensesEvaluated],
@@ -1362,4 +1587,6 @@ async function runOutcome(options) {
         return { ...ran, ...provenance, ...extent };
     });
 }
+/** The test-facing seam: helpers the unit tests reach that are not part of this module's API. */
+export const __internal = { noticeAudienceOf };
 //# sourceMappingURL=check.js.map