@mjasnikovs/pi-task 0.38.15 → 0.38.17

package/dist/task/autofix-ledger.d.ts

@@ -0,0 +1,113 @@
+/**
+ * autofix-ledger — what the run-end RESOLUTION LOOP records, and the decisions
+ * that record makes.
+ *
+ * The same deepening `GateTally` already proved one altitude down. That replaced
+ * twelve mutable locals threaded through ~400 lines of `runFinalIntegrationGate`
+ * by closure; this replaces six threaded through ~235 lines of
+ * `runFinalGateStage` — the attempt count, the accumulated gitignored writes, the
+ * stranded sub-fixes, the previous failure signature, the demoted set, and the
+ * rejected-edits flag.
+ *
+ * The reason is not tidiness. `final-gate-progress.ts` holds five pure functions,
+ * each called from exactly ONE site inside that loop — extracted for testability
+ * while the decisions about ORDERING and CARRY-FORWARD stayed in the caller. That
+ * is precisely the shape `isNonProgress`'s own comment indicts:
+ *
+ *   > The fix is NOT a better string pattern — the bug is that the decision was
+ *   > made downstream from the evidence.
+ *
+ * mx5 run 21 shipped a product whose every page was blank as a `completed` run
+ * through that gap. Here the evidence and the decision sit in one module, and the
+ * loop body reads as picker → apply → record.
+ *
+ * What is NOT here: anything that talks to the user, writes a ledger file, or
+ * commits. The loop keeps those, the same way `GateTally` keeps no I/O — a record
+ * that performs effects cannot be driven by a test that only wants the verdict.
+ */
+/** The gate-outcome fields this record reads. Structural, so a caller can hand it
+ *  a `FinalGateOutcome` without this module importing the gate. */
+export interface AutofixOutcomeView {
+    reason: string;
+    failures?: string[];
+    observedFailures?: string[];
+}
+/** What the loop should do about this attempt's ranked-first failure. */
+export interface AttemptVerdict {
+    /** The ranked-first failure, trimmed; null when the outcome names none. */
+    detail: string | null;
+    /**
+     * True ⇒ this check is unfalsifiable here: the attempt edited the tree, the
+     * gate re-ran, and returned the same first failure as the previous one — and
+     * no probe OBSERVED it. Already recorded as demoted when true.
+     */
+    demoted: boolean;
+    /** The debt reason to carry, present exactly when `demoted`. */
+    debtReason?: string;
+}
+export declare class AutofixLedger {
+    private readonly _budget;
+    /** Autofix attempts made in this loop, including the one in flight. */
+    private _attempts;
+    /**
+     * Gitignored paths the fix passes have written so far. ACCUMULATED across
+     * attempts: a `.env` written by a failed attempt is still on disk for the next
+     * one, and that attempt's own before/after diff cannot see it (mx5 run 19).
+     */
+    private _ignoredWritten;
+    /** Sub-fixes a non-converging attempt left uncommitted. REPLACED each attempt. */
+    private _stranded;
+    /** The previous attempt's normalized ranked-first failure. */
+    private _prevFailSig;
+    /** Signatures already carried as debt; a re-run reporting them does not re-fail. */
+    private readonly _demoted;
+    /**
+     * A write-guard rejected an attempt whose edits could NOT be discarded, so
+     * REJECTED edits are sitting in the tree and the terminal paths must not commit
+     * what they find there (mx5 run 14 item 2b — the cheat guard is never weakened
+     * to ease committing).
+     */
+    private _rejectedEditsInTree;
+    constructor(_budget: number);
+    /** One autofix attempt is starting. */
+    attempt(): number;
+    /** Are there attempts left? Drives whether the picker offers the card at all. */
+    canAutofix(): boolean;
+    attempts(): number;
+    /** Gitignored paths this attempt wrote. Accumulated, de-duplicated, order kept. */
+    wroteIgnored(paths: readonly string[] | undefined): void;
+    ignoredWrites(): readonly string[];
+    /** The uncommitted sub-fixes as of now. Replaces, never accumulates. */
+    setStranded(paths: readonly string[]): void;
+    stranded(): readonly string[];
+    /** A guard rejected an attempt and its edits are still in the tree. */
+    rejectedEditsRemain(): void;
+    /**
+     * May a terminal path commit what is in the working tree?
+     *
+     * False once a guard has rejected an attempt without discarding its edits.
+     * This is the ONE question the flag exists to answer, and it is asked at three
+     * terminal sites — as a method rather than a bare boolean read at each.
+     */
+    mayCommitTree(): boolean;
+    /**
+     * Judge this attempt's gate outcome, and record what the judgement implies.
+     *
+     * `edited` is the caller's fact — did this attempt change the tree and survive
+     * the guards. The observed/non-progress rule and the signature carry-forward
+     * are this module's, so they cannot be applied in the wrong order or skipped:
+     * a demoted signature is entered into the set and the previous-signature chain
+     * is broken in the SAME call that decides to demote.
+     */
+    judge(outcome: AutofixOutcomeView | undefined, edited: boolean): AttemptVerdict;
+    demotedCount(): number;
+    /**
+     * What still has to pass for the gate to converge: this outcome's failures with
+     * every already-demoted signature dropped. An EMPTY array means converged
+     * carrying the demotions as debt; `undefined` means the outcome named no list
+     * and there is nothing to reason about.
+     */
+    remaining(outcome: AutofixOutcomeView | undefined): string[] | undefined;
+    /** Has anything been demoted? Only then can a run converge on the remainder. */
+    hasDemotions(): boolean;
+}

package/dist/task/autofix-ledger.js

@@ -0,0 +1,152 @@
+/**
+ * autofix-ledger — what the run-end RESOLUTION LOOP records, and the decisions
+ * that record makes.
+ *
+ * The same deepening `GateTally` already proved one altitude down. That replaced
+ * twelve mutable locals threaded through ~400 lines of `runFinalIntegrationGate`
+ * by closure; this replaces six threaded through ~235 lines of
+ * `runFinalGateStage` — the attempt count, the accumulated gitignored writes, the
+ * stranded sub-fixes, the previous failure signature, the demoted set, and the
+ * rejected-edits flag.
+ *
+ * The reason is not tidiness. `final-gate-progress.ts` holds five pure functions,
+ * each called from exactly ONE site inside that loop — extracted for testability
+ * while the decisions about ORDERING and CARRY-FORWARD stayed in the caller. That
+ * is precisely the shape `isNonProgress`'s own comment indicts:
+ *
+ *   > The fix is NOT a better string pattern — the bug is that the decision was
+ *   > made downstream from the evidence.
+ *
+ * mx5 run 21 shipped a product whose every page was blank as a `completed` run
+ * through that gap. Here the evidence and the decision sit in one module, and the
+ * loop body reads as picker → apply → record.
+ *
+ * What is NOT here: anything that talks to the user, writes a ledger file, or
+ * commits. The loop keeps those, the same way `GateTally` keeps no I/O — a record
+ * that performs effects cannot be driven by a test that only wants the verdict.
+ */
+import { applyDemotions, isNonProgress, normalizeFailureDetail, rankedFirstFailure, unobservedDebtReason } from './final-gate-progress.js';
+export class AutofixLedger {
+    _budget;
+    /** Autofix attempts made in this loop, including the one in flight. */
+    _attempts = 0;
+    /**
+     * Gitignored paths the fix passes have written so far. ACCUMULATED across
+     * attempts: a `.env` written by a failed attempt is still on disk for the next
+     * one, and that attempt's own before/after diff cannot see it (mx5 run 19).
+     */
+    _ignoredWritten = [];
+    /** Sub-fixes a non-converging attempt left uncommitted. REPLACED each attempt. */
+    _stranded = [];
+    /** The previous attempt's normalized ranked-first failure. */
+    _prevFailSig = null;
+    /** Signatures already carried as debt; a re-run reporting them does not re-fail. */
+    _demoted = new Set();
+    /**
+     * A write-guard rejected an attempt whose edits could NOT be discarded, so
+     * REJECTED edits are sitting in the tree and the terminal paths must not commit
+     * what they find there (mx5 run 14 item 2b — the cheat guard is never weakened
+     * to ease committing).
+     */
+    _rejectedEditsInTree = false;
+    constructor(_budget) {
+        this._budget = _budget;
+    }
+    // ─── Record ──────────────────────────────────────────────────────────────
+    /** One autofix attempt is starting. */
+    attempt() {
+        return ++this._attempts;
+    }
+    /** Are there attempts left? Drives whether the picker offers the card at all. */
+    canAutofix() {
+        return this._attempts < this._budget;
+    }
+    attempts() {
+        return this._attempts;
+    }
+    /** Gitignored paths this attempt wrote. Accumulated, de-duplicated, order kept. */
+    wroteIgnored(paths) {
+        if (!paths || paths.length === 0)
+            return;
+        for (const p of paths)
+            if (!this._ignoredWritten.includes(p))
+                this._ignoredWritten.push(p);
+    }
+    ignoredWrites() {
+        return this._ignoredWritten;
+    }
+    /** The uncommitted sub-fixes as of now. Replaces, never accumulates. */
+    setStranded(paths) {
+        this._stranded = [...paths];
+    }
+    stranded() {
+        return this._stranded;
+    }
+    /** A guard rejected an attempt and its edits are still in the tree. */
+    rejectedEditsRemain() {
+        this._rejectedEditsInTree = true;
+    }
+    /**
+     * May a terminal path commit what is in the working tree?
+     *
+     * False once a guard has rejected an attempt without discarding its edits.
+     * This is the ONE question the flag exists to answer, and it is asked at three
+     * terminal sites — as a method rather than a bare boolean read at each.
+     */
+    mayCommitTree() {
+        return !this._rejectedEditsInTree;
+    }
+    // ─── Decide ──────────────────────────────────────────────────────────────
+    /**
+     * Judge this attempt's gate outcome, and record what the judgement implies.
+     *
+     * `edited` is the caller's fact — did this attempt change the tree and survive
+     * the guards. The observed/non-progress rule and the signature carry-forward
+     * are this module's, so they cannot be applied in the wrong order or skipped:
+     * a demoted signature is entered into the set and the previous-signature chain
+     * is broken in the SAME call that decides to demote.
+     */
+    judge(outcome, edited) {
+        const detail = rankedFirstFailure({
+            ...(outcome ? { reason: outcome.reason } : {}),
+            ...(outcome?.failures ? { failures: outcome.failures } : {})
+        });
+        // Whether a PROBE OBSERVED this failure, read off the SAME outcome the
+        // failure came from — exact text identity, never a second string pattern.
+        const observed = outcome?.observedFailures?.includes(detail ?? '') === true;
+        if (detail !== null
+            && isNonProgress({
+                previousSignature: this._prevFailSig,
+                currentDetail: detail,
+                edited,
+                observed
+            })) {
+            this._demoted.add(normalizeFailureDetail(detail));
+            // A demotion ends the chain: the next attempt has no previous signature
+            // to match, so one demotion cannot cascade into a second.
+            this._prevFailSig = null;
+            return { detail, demoted: true, debtReason: unobservedDebtReason(detail) };
+        }
+        this._prevFailSig = detail !== null ? normalizeFailureDetail(detail) : null;
+        return { detail, demoted: false };
+    }
+    demotedCount() {
+        return this._demoted.size;
+    }
+    /**
+     * What still has to pass for the gate to converge: this outcome's failures with
+     * every already-demoted signature dropped. An EMPTY array means converged
+     * carrying the demotions as debt; `undefined` means the outcome named no list
+     * and there is nothing to reason about.
+     */
+    remaining(outcome) {
+        const failures = outcome?.failures ?? (outcome ? [outcome.reason] : undefined);
+        if (failures === undefined)
+            return undefined;
+        return applyDemotions(failures, this._demoted);
+    }
+    /** Has anything been demoted? Only then can a run converge on the remainder. */
+    hasDemotions() {
+        return this._demoted.size > 0;
+    }
+}

package/dist/task/boot-probe.d.ts

@@ -135,6 +135,52 @@ export interface BootDeps {
     preferredPort?: () => Promise<number | null>;
     /** Does anything answer HTTP on 127.0.0.1:`port`? Injected for tests. */
     httpProbe?: (port: number) => boolean;
+    /**
+     * Spawn the boot child. THE SUBJECT of this check, and the one thing `BootDeps`
+     * did not seam.
+     *
+     * Nine fields above inject something the check LOOKS AT; `spawn` was imported
+     * directly, so the ~220-line state machine below — seven locals threaded by
+     * closure, four `BootOutcome` kinds, five exit arms — was reachable only through
+     * a real process on a real clock. Measured: 52 tests / 13.6s, with 300–5000ms
+     * grace windows scripted as real `process.execPath -e` children.
+     *
+     * `BootChild` is defined from what this function CALLS, not from Node's
+     * `ChildProcess` — the same way `driveSession(cdp: CdpLike, …)` was defined from
+     * the two `Cdp` methods it uses. A scripted fake is a dozen lines.
+     */
+    spawnBoot?: (bin: string, args: string[], opts: BootSpawnOptions) => BootChild;
+    /**
+     * Tear down the child's whole process group. Injected with `spawnBoot`, because
+     * a fake child has no group to kill and a real `process.kill(-pid)` against a
+     * fake pid would signal something else entirely.
+     */
+    killGroup?: (pid: number, signal: NodeJS.Signals) => void;
+}
+/** What `runBootCheck` passes to its spawn. */
+export interface BootSpawnOptions {
+    cwd: string;
+    detached: true;
+    stdio: ['ignore', 'pipe', 'pipe'];
+    env: Record<string, string | undefined>;
+}
+/** A stream the boot check reads output from. */
+export interface BootStream {
+    on: (event: 'data', cb: (chunk: Buffer | string) => void) => void;
+}
+/**
+ * The boot child, as the check actually uses it: a pid, two output streams, an
+ * `error` event and an `exit` event carrying (status, signal).
+ */
+export interface BootChild {
+    pid?: number | undefined;
+    unref?: () => void;
+    stdout?: BootStream | null;
+    stderr?: BootStream | null;
+    on: {
+        (event: 'error', cb: (err: Error) => void): void;
+        (event: 'exit', cb: (status: number | null, signal: NodeJS.Signals | null) => void): void;
+    };
 }
 /**
  * Does the finished run stand up a listening HTTP server? Deterministic, from the
@@ -294,5 +340,67 @@ export declare function recoverOrphanPort(cwd: string, boot: HealthCommand, firs
     outcome: 'orphan-port';
     detail: string;
     port: number | null;
-}, bootGraceMs: number, deps: BootDeps, expectServer: boolean): Promise<BootOutcome>;
+}, 
+/** One options object, not four trailing positionals — `bootGraceMs` and a
+ *  boolean sat adjacent and swapped without a type error. */
+opts: {
+    graceMs?: number;
+    deps: BootDeps;
+    expectServer: boolean;
+}): Promise<BootOutcome>;
+/**
+ * Everything the run-end gate records about "did the assembled product start?".
+ *
+ * This module owned the mechanics but not the CONCEPT: answering that question
+ * meant reading ~110 lines of `final-gate.ts` as well, where the four-armed
+ * {@link BootOutcome} union was destructured, the render/deep-render/port probe
+ * defaults were bound, `recoverOrphanPort` was re-invoked with six positional
+ * arguments, and the port-holder diagnosis reached back into `BootDeps` a SECOND
+ * time to build its own sentence. CONTEXT.md records the earlier extraction as
+ * "a file move, not a re-shaping"; this is the re-shaping it left open.
+ *
+ * The gate's boot branch is now: call this, write the fields into the tally.
+ * `runBootCheck` stays exported unchanged — seven harnesses under `scripts/`
+ * drive it directly.
+ */
+export interface BootSectionVerdict {
+    /** The bin the gate counts as ATTEMPTED. Absent ⇒ there was nothing to boot. */
+    attempted?: string;
+    /** A probe LOOKED. False for a skip, and for a project with no launch surface. */
+    observed: boolean;
+    /** The runner binary never spawned — feeds the full-blindness guard. */
+    spawnFailedBin?: string;
+    /** The UNOBSERVED note, offered on both branches (a rejected launch script has one). */
+    unobservedNote?: string;
+    /**
+     * The one failure this section can produce, with the rank the gate gives it (0 —
+     * boot failures lead the aggregate) and whether a probe OBSERVED it. A harness
+     * condition (a port we could not clear) is a failure that nothing observed about
+     * the APP, which is why `observed` is a field and not implied by `failure`.
+     */
+    failure?: {
+        detail: string;
+        rank: number;
+        observed: boolean;
+    };
+    /** The label recorded as having RUN, on a clean boot. */
+    ranLabel?: string;
+    /** UNOBSERVED warnings — a listener that served but whose page could not be judged. */
+    warnings: string[];
+}
+export interface BootSectionOptions {
+    /** The plan text, for served-app detection. */
+    planText?: string;
+    /** Grace period for the boot check. */
+    graceMs?: number;
+    /**
+     * Probe overrides. The render, deep-render and preferred-port defaults are
+     * bound HERE now: they were the gate's, so a caller that wanted the real boot
+     * behaviour had to know to supply three functions it should never have had to
+     * name — `findPortHolder` was already defaulted inside this module, and the
+     * other three now match it.
+     */
+    deps?: BootDeps;
+}
+export declare function runBootSection(cwd: string, opts?: BootSectionOptions): Promise<BootSectionVerdict>;
 export {};

package/dist/task/boot-probe.js

@@ -23,10 +23,11 @@ import { spawn, spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import * as net from 'node:net';
 import * as path from 'node:path';
+import { runRenderCheck } from './render-check.js';
 import { resolveRunner, runnerEnv, isCommandNotFound } from './runner-resolve.js';
 import { outputTail } from './command-run.js';
 import { packageScripts, makeHasTarget } from './launch-manifest.js';
-import { collectProjectEnv, pinnedLocalPort } from './deep-render-check.js';
+import { collectProjectEnv, pinnedLocalPort, runDeepRenderCheck } from './deep-render-check.js';
 /** Leading `FOO=bar` env assignments and `sudo`/`exec` wrappers carry no verb. */
 function commandTokens(member) {
     const t = member.trim().split(/\s+/).filter(Boolean);
@@ -485,6 +486,30 @@ function holderIsOurs(command, boot) {
     return ((c.includes('bun') || c.includes('node') || c.includes('npm') || c.includes('make'))
         && (c.includes(` ${script}`) || c.endsWith(script)));
 }
+/** The real spawn. Kept beside the seam so the default is one line to read. */
+function defaultSpawnBoot(bin, args, o) {
+    return spawn(bin, args, o);
+}
+/**
+ * The real group teardown, best-effort. A group already gone is not an error.
+ *
+ * Windows has no process groups / negative-pid kill: `taskkill /T` tears down the
+ * whole tree (the detached child plus any grandchildren it spawned) and `/F`
+ * forces it, so the SIGTERM→SIGKILL escalation collapses to one idempotent call.
+ */
+function defaultKillGroup(pid, sig) {
+    try {
+        if (process.platform === 'win32') {
+            spawnSync('taskkill', ['/pid', String(pid), '/T', '/F']);
+        }
+        else {
+            process.kill(-pid, sig);
+        }
+    }
+    catch {
+        // group already gone
+    }
+}
 /**
  * Exercise the start command ONCE. For a CLI project (`expectServer` false) the
  * command's own fate within the grace window decides:
@@ -546,8 +571,9 @@ export async function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}
     // the runner and carry its directory on PATH so the boot script's own chain
     // can re-invoke it.
     const runner = resolveRunner(bin);
+    const spawnBoot = opts.deps?.spawnBoot ?? defaultSpawnBoot;
     return new Promise(resolve => {
-        const child = spawn(runner.bin, args, {
+        const child = spawnBoot(runner.bin, args, {
             cwd,
             detached: true,
             stdio: ['ignore', 'pipe', 'pipe'],
@@ -561,13 +587,17 @@ export async function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}
         // runner where the group-kill did not take, hanging the whole `bun test
         // --isolate` run on the leaked child's piped stdio). unref() so a child
         // we already tried to kill can never itself keep this process alive.
-        child.unref();
+        child.unref?.();
         let out = '';
         let err = '';
         let listenerSeen = false;
         const cap = (s) => (s.length > 8000 ? s.slice(-8000) : s);
-        child.stdout?.on('data', (d) => (out = cap(out + String(d))));
-        child.stderr?.on('data', (d) => (err = cap(err + String(d))));
+        child.stdout?.on('data', d => {
+            out = cap(out + String(d));
+        });
+        child.stderr?.on('data', d => {
+            err = cap(err + String(d));
+        });
         let settled = false;
         const settle = (r) => {
             if (settled)
@@ -578,24 +608,15 @@ export async function runBootCheck(cwd, [bin, args], graceMs = 10_000, opts = {}
                 clearInterval(poll);
             resolve(r);
         };
+        const reapGroup = opts.deps?.killGroup ?? defaultKillGroup;
         const killGroup = (sig) => {
-            try {
-                if (!child.pid)
-                    return;
-                if (process.platform === 'win32') {
-                    // Windows has no process groups / negative-pid kill. taskkill
-                    // /T tears down the whole tree (the detached child plus any
-                    // grandchildren it spawned); /F forces it, so the SIGTERM→
-                    // SIGKILL escalation collapses to one idempotent call.
-                    spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F']);
-                }
-                else {
-                    process.kill(-child.pid, sig);
-                }
-            }
-            catch {
-                // group already gone
-            }
+            // Truthiness, deliberately: `process.kill(-0, sig)` signals the
+            // CALLER's own process group, so a pid of 0 turns a best-effort
+            // teardown into self-termination. Node's spawn never yields 0, but
+            // `spawnBoot` is a seam now and a fake or future child could.
+            if (!child.pid)
+                return;
+            reapGroup(child.pid, sig);
         };
         const passAndKill = (renderNote) => {
             settle(renderNote ? { outcome: 'pass', renderNote } : { outcome: 'pass' });
@@ -791,7 +812,11 @@ export function bootSkipVerdict(args) {
  * the caller emit the harness diagnosis. Never reaps a process we cannot attribute
  * to ourselves.
  */
-export async function recoverOrphanPort(cwd, boot, first, bootGraceMs, deps, expectServer) {
+export async function recoverOrphanPort(cwd, boot, first, 
+/** One options object, not four trailing positionals — `bootGraceMs` and a
+ *  boolean sat adjacent and swapped without a type error. */
+opts) {
+    const { graceMs: bootGraceMs, deps, expectServer } = opts;
     if (first.port === null)
         return first;
     const holder = (deps.findPortHolder ?? defaultFindPortHolder)(first.port);
@@ -804,3 +829,94 @@ export async function recoverOrphanPort(cwd, boot, first, bootGraceMs, deps, exp
     await new Promise(r => setTimeout(r, 1_500));
     return runBootCheck(cwd, boot, bootGraceMs, { expectServer, deps });
 }
+export async function runBootSection(cwd, opts = {}) {
+    const boot = discoverBootCommand(cwd);
+    const expectServer = detectsServedApp(cwd, opts.planText);
+    const warnings = [];
+    if (!boot) {
+        // Nothing to boot — but if the reason is that the project's only launch
+        // script was REJECTED as not-a-launch (2A), that is not the same thing as a
+        // project with no launch surface, and it must not degrade into silence.
+        const rejected = rejectedLaunchScript(cwd);
+        if (rejected && expectServer) {
+            return {
+                observed: false,
+                warnings,
+                unobservedNote: `boot check: this project's only launch script (\`${rejected.name}\`) is not a `
+                    + `launch — ${rejected.reason} — so nothing was started and the app was never `
+                    + 'observed to run.'
+            };
+        }
+        return { observed: false, warnings };
+    }
+    const label = `${boot[0]} ${boot[1].join(' ')}`;
+    // Render check (mx5 runs 8/11): for a served app, load the live page in a
+    // headless browser and judge the RENDERED DOM — curl can't run JS, so a
+    // blank-mount app passed every prior "renders" check. runRenderCheck
+    // env-gap-SKIPs when no browser exists, so a box without one never gets a
+    // false FAIL.
+    //
+    // Authenticated deep-render check (mx5 run 17): the page above renders, so now
+    // sign in with the account the project's own dotenv declares (the same
+    // ADMIN_PHONE/ADMIN_PASSWORD the launch contract's seed step consumes) and
+    // require the session to actually work. WEB-ONLY by construction — it hangs off
+    // the served-app branch and never runs for C++, Godot, CLI or library projects.
+    // It may only FAIL when the SERVER authenticated us; no browser, no
+    // credentials, an undrivable form or rejected credentials all skip as env gaps.
+    const deps = {
+        ...opts.deps,
+        renderProbe: opts.deps?.renderProbe ?? runRenderCheck,
+        deepRenderProbe: opts.deps?.deepRenderProbe ?? (url => runDeepRenderCheck(url, cwd)),
+        preferredPort: opts.deps?.preferredPort ?? (() => preferredDeclaredPort(cwd))
+    };
+    let b = await runBootCheck(cwd, boot, opts.graceMs, { expectServer, deps });
+    if (b.outcome === 'orphan-port') {
+        b = await recoverOrphanPort(cwd, boot, b, {
+            ...(opts.graceMs === undefined ? {} : { graceMs: opts.graceMs }),
+            deps,
+            expectServer
+        });
+    }
+    const verdict = {
+        attempted: boot[0],
+        observed: b.outcome !== 'skip',
+        warnings,
+        ...(b.outcome === 'skip' && b.spawnFailed ? { spawnFailedBin: boot[0] } : {})
+    };
+    const unobserved = bootSkipVerdict({ label, skipped: b.outcome === 'skip', expectServer });
+    if (unobserved !== null)
+        verdict.unobservedNote = unobserved;
+    if (b.outcome === 'fail') {
+        // OBSERVED (nexttask 19A). Every path that produces `fail` here is a probe
+        // that looked: the render judge saw an empty body, the deep session saw the
+        // authenticated half dead, the enumerator saw no listener, or the launch
+        // command itself exited non-zero. The one condition that means "we could not
+        // look" — no ss/netstat/lsof, mx5 run 14 — returns PASS stamped UNOBSERVED
+        // and never reaches here.
+        verdict.failure = { detail: `boot check: \`${label}\` ${b.detail}`, rank: 0, observed: true };
+    }
+    else if (b.outcome === 'orphan-port') {
+        // Could not clear the port. Distinct HARNESS diagnosis, never a bare app
+        // FAIL: name the port and (when known) the process squatting on it. The
+        // holder lookup reads the SAME deps the boot ran under — it used to be a
+        // second reach into `BootDeps` from the gate, one layer away from the run.
+        const holder = b.port !== null ? (deps.findPortHolder ?? defaultFindPortHolder)(b.port) : null;
+        const who = holder ? ` — held by an orphaned process (pid ${holder.pid}: ${holder.command})`
+            : b.port !== null ? ` — port ${b.port} is held by another process`
+                : '';
+        verdict.failure = {
+            detail: `boot check: \`${label}\` could not bind: orphaned process / port already in `
+                + `use${who} (harness condition, not an app fault)`,
+            rank: 0,
+            observed: false
+        };
+    }
+    else if (b.outcome === 'pass') {
+        verdict.ranLabel = label;
+        // A listener that served, but whose page could not be OBSERVED to render
+        // (no browser, undeterminable port) → UNOBSERVED warning, not a silent pass.
+        if (b.renderNote)
+            warnings.push(b.renderNote);
+    }
+    return verdict;
+}