@mjasnikovs/pi-task 0.38.15 → 0.38.17

package/dist/task/external-context.js

@@ -108,10 +108,10 @@ export async function buildExternalContext(source, deps, lookups, policy = {}) {
  *
  * Returns the `EXTERNAL CONTEXT\n…\n\n` block for the refined spec, or `''`.
  */
-export async function gatherExternalContext(refined, deps, researchDeps = {}) {
-    const docsRawFn = researchDeps.docsRaw ?? docsRaw;
-    const fetchRawFn = researchDeps.fetchRaw ?? fetchRaw;
-    const npmVersionFn = researchDeps.npmVersionLookup ?? npmVersionLookup;
+export async function gatherExternalContext(refined, deps) {
+    const docsRawFn = deps.docsRaw ?? docsRaw;
+    const fetchRawFn = deps.fetchRaw ?? fetchRaw;
+    const npmVersionFn = deps.npmVersionLookup ?? npmVersionLookup;
     const docsQuery = refined.split('\n').find(l => l.trim()) ?? refined;
     return buildExternalContext(refined, deps, {
         docs: async (pkg) => {
@@ -135,7 +135,7 @@ export async function gatherExternalContext(refined, deps, researchDeps = {}) {
             const r = await fetchRawFn({ url, signal: deps.signal });
             return { body: r.markdown.slice(0, RAW_BODY_LIMIT) };
         },
-        search: researchDeps.searchFn
+        search: deps.searchFn
     }, {
         versionLookup: pkg => npmVersionFn(pkg, { signal: deps.signal }),
         subStepLabel: 'enrichment',

package/dist/task/failure-classifier.d.ts

@@ -12,4 +12,12 @@ export interface FailureClass {
     level: NotifyLevel;
 }
 export declare function classifyFailure(err: unknown, aborted: boolean): FailureClass;
-export declare function handleFailure(err: unknown, ctx: ExtensionCommandContext, cwd: string, id: string, aborted: boolean): Promise<void>;
+/**
+ * Persist, flash and announce a failure — and RETURN the classification.
+ *
+ * It used to return `void`, so the name it had just computed died here and the
+ * caller learned how the run ended by re-reading the task file's front matter and
+ * narrowing it to a boolean. Handing the value back is what lets `TaskRunner.run`
+ * say `RunEnd` instead.
+ */
+export declare function handleFailure(err: unknown, ctx: ExtensionCommandContext, cwd: string, id: string, aborted: boolean): Promise<FailureClass>;

package/dist/task/failure-classifier.js

@@ -74,6 +74,14 @@ export function classifyFailure(err, aborted) {
         level: 'error'
     };
 }
+/**
+ * Persist, flash and announce a failure — and RETURN the classification.
+ *
+ * It used to return `void`, so the name it had just computed died here and the
+ * caller learned how the run ended by re-reading the task file's front matter and
+ * narrowing it to a boolean. Handing the value back is what lets `TaskRunner.run`
+ * say `RunEnd` instead.
+ */
 export async function handleFailure(err, ctx, cwd, id, aborted) {
     const c = classifyFailure(err, aborted);
     await updateTaskFrontMatter(cwd, id, { state: c.state, reason: c.reason });
@@ -82,4 +90,5 @@ export async function handleFailure(err, ctx, cwd, id, aborted) {
     // Mirror to remote viewers — ctx.ui.notify is terminal-only, so without this
     // the remote view shows nothing when a task fails.
     publishLifecycleNotice(`${id} ${c.notify}`, c.level);
+    return c;
 }

package/dist/task/final-gate-fix.d.ts

@@ -1,3 +1,4 @@
+import type { FinalGateOutcome } from './final-gate.js';
 import { type TreeChangeSummary, type IgnoredSnapshot } from './write-guard.js';
 /** Same bounded-fix contract as lint-fix: edit in place, bash exists to RUN the
  *  failing command (and the project's own tooling), not to mutate git state. */
@@ -97,22 +98,24 @@ export interface FinalFixResult {
     ok: boolean;
     /** Human-readable outcome (converged gate reason, or why the attempt failed). */
     reason: string;
-    /** On a did-not-converge outcome: the FRESH gate failure, so the caller's next
-     *  picker (and next fix attempt) works from the current state, not the stale one. */
-    gateReason?: string;
-    /** The fresh gate's individual ranked failures (see FinalGateOutcome.failures),
-     *  so the caller can trail each entry — never just the first. */
-    gateFailures?: string[];
-    /** …and which of them a PROBE returned after OBSERVING (see
-     *  FinalGateOutcome.observedFailures). Carried so the caller's non-progress
-     *  classifier can ask the probe's own verdict instead of guessing from the
-     *  failure text — a check that was observed to FAIL is never demote-eligible
-     *  (nexttask 19A). */
-    gateObservedFailures?: string[];
-    /** On a converged outcome: the re-run gate's UNOBSERVED note, if it observed
-     *  nothing dynamic (see FinalGateOutcome.unobserved). Carried so the caller
-     *  labels a converge-on-statics-alone the same way it labels a first-pass one —
-     *  "converged" must never quietly mean "we stopped being able to check". */
+    /**
+     * The re-run gate's OUTCOME, whole — present whenever the gate actually ran
+     * (absent only when the fix child self-declared blocked and the re-run was
+     * skipped).
+     *
+     * This used to be four flattened `gate*` mirrors, and the flattening lost
+     * things. `openDebts` never crossed at all, so `runFinalGateStage` rebuilt
+     * `fin` as a literal three times and each literal dropped it — the recorded
+     * mx5 run-18 defect, fixed by RE-DERIVING the field (`reconcileDebts`) rather
+     * than by keeping the value. Then 19A had to push `observedFailures` across the
+     * same wall as a third parallel field and re-pair it downstream by
+     * `gateObservedFailures?.includes(detail)` — a membership test that exists only
+     * because the pairing was broken in transit.
+     */
+    gate?: FinalGateOutcome;
+    /** On a converged outcome: the UNOBSERVED note the CALLER should show. It is
+     *  the gate's own note plus any downgrade this fix pass added (see the
+     *  ignored-dependency probe below), so it is not simply `gate.unobserved`. */
     unobserved?: string;
     /** Gitignored path(s) this fix pass wrote, exempt classes already removed (see
      *  write-guard.ts). Present whether or not the gate converged — the caller
@@ -141,16 +144,9 @@ export interface FinalFixDeps {
     /** Re-run the final integration gate — the only arbiter of convergence.
      *  Converges only when the gate's FULL aggregated failure list is empty
      *  (ok=true); `failures` rides through so the caller sees every entry. */
-    gate: (cwd: string) => Promise<{
-        ok: boolean;
-        reason: string;
-        failures?: string[];
-        /** Which of them a probe returned after OBSERVING (nexttask 19A) — carried
-         *  through so the caller's demote decision can ask the probe's own verdict
-         *  instead of re-deriving observability from the failure string. */
-        observedFailures?: string[];
-        unobserved?: string;
-    }>;
+    /** Returns the gate's own outcome type, not a structural copy of five of its
+     *  fields — a re-declaration is how `openDebts` came to be silently absent. */
+    gate: (cwd: string) => Promise<FinalGateOutcome>;
     /** Labels of every currently-discoverable gate command (static + integration),
      *  for the shrink guard. Pure discovery — nothing is executed. */
     discoverLabels: (cwd: string) => string[];

package/dist/task/final-gate-fix.js

@@ -43,7 +43,7 @@
  * legitimate whole-repo fix that run needed (migrate.ts — frozen by its own
  * producing task). It activates only when a run-GLOBAL freeze source exists.
  */
-import { USER_CANCELLED } from './child-runner.js';
+import { parseFixMarker, runFixChild } from './fix-child.js';
 import { findForbiddenDeletions, diffIgnoredSnapshots, ignoredWriteTrailLine, ignoredWriteUnobservedNote } from './write-guard.js';
 import { findNarrowedCommands, narrowingRejectionText } from './command-shrink.js';
 /** Same bounded-fix contract as lint-fix: edit in place, bash exists to RUN the
@@ -151,16 +151,7 @@ export function buildFinalFixPrompt(failReason) {
  * early-out on a self-declared BLOCKED.
  */
 export function parseFinalFixMarker(text) {
-    const re = /FINAL-GATE-FIX:\s*(DONE|BLOCKED)\b[ \t]*(.*)/gi;
-    let last = null;
-    for (let m = re.exec(text); m !== null; m = re.exec(text))
-        last = m;
-    if (!last)
-        return { blocked: false };
-    if (last[1].toUpperCase() === 'BLOCKED') {
-        return { blocked: true, note: last[2].trim() || 'no reason given' };
-    }
-    return { blocked: false, note: last[2].trim() || undefined };
+    return parseFixMarker('FINAL-GATE-FIX', text);
 }
 /**
  * STRANDED SUB-FIXES (mx5 run 13, PROMPT 4 item 3).
@@ -219,16 +210,16 @@ export async function runFinalGateAutofix(deps) {
     // ignored files are untracked, so git alone cannot tell a file this pass wrote
     // from one that was already sitting in the worktree.
     const ignoredBefore = deps.ignoredSnapshot ? await deps.ignoredSnapshot() : null;
-    let text;
-    try {
-        text = await deps.runChild(FINAL_FIX_TOOLS, buildFinalFixPrompt(deps.failReason), deps.signal);
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        if (msg === USER_CANCELLED)
-            throw err;
-        return { ok: false, reason: `fix child failed: ${msg}` };
-    }
+    // The four-rung ladder is task/fix-child.ts, shared with the per-task pass.
+    const end = await runFixChild({
+        runChild: deps.runChild,
+        tools: FINAL_FIX_TOOLS,
+        prompt: buildFinalFixPrompt(deps.failReason),
+        signal: deps.signal,
+        marker: 'FINAL-GATE-FIX'
+    });
+    if (end.kind === 'error')
+        return { ok: false, reason: `fix child failed: ${end.msg}` };
     // What the child wrote to gitignored paths. Recorded on the trail IMMEDIATELY —
     // before any guard can reject the attempt — because `discard` reverts tracked
     // edits only: an ignored file the pass wrote survives a rejection, and the trail
@@ -327,20 +318,13 @@ export async function runFinalGateAutofix(deps) {
             return r;
         }
     }
-    const marker = parseFinalFixMarker(text);
-    if (marker.blocked) {
+    if (end.kind === 'blocked') {
         // Self-declared blocked: skip the (expensive) gate re-run; nothing converged.
-        return withIgnored({ ok: false, reason: `fix child blocked: ${marker.note}` });
+        return withIgnored({ ok: false, reason: `fix child blocked: ${end.note}` });
     }
     const fin = await deps.gate(deps.cwd);
     if (!fin.ok) {
-        return withIgnored({
-            ok: false,
-            reason: `did not converge: ${fin.reason}`,
-            gateReason: fin.reason,
-            gateFailures: fin.failures,
-            ...(fin.observedFailures ? { gateObservedFailures: fin.observedFailures } : {})
-        });
+        return withIgnored({ ok: false, reason: `did not converge: ${fin.reason}`, gate: fin });
     }
     // IGNORED-DEPENDENCY DOWNGRADE (mx5 run 19). The gate says PASS; the question
     // this answers is whether that PASS belongs to the REPOSITORY or only to this
@@ -368,6 +352,7 @@ export async function runFinalGateAutofix(deps) {
     return withIgnored({
         ok: true,
         reason: fin.reason,
+        gate: fin,
         ...(notes.length > 0 ? { unobserved: notes.join(' ') } : {}),
         ...(ignoredDependent !== undefined ? { ignoredDependent } : {})
     });

package/dist/task/final-gate.d.ts

@@ -1,6 +1,6 @@
 import { type HealthCommand } from './repo-health-check.js';
 import { deriveOpenDebts, rerunDebtVerifyCommand, type AcceptDebt } from './accept-debt.js';
-import { discoverBootCommand, detectsServedApp, runBootCheck, bootSkipVerdict, nonLaunchScriptReason, rejectedLaunchScript, parseSsListeners, parseNetstatListeners, parseLsofListeners, pickFreePort, preferredDeclaredPort, canEnumerateListeners, type BootDeps } from './boot-probe.js';
+import { discoverBootCommand, detectsServedApp, runBootCheck, runBootSection, bootSkipVerdict, nonLaunchScriptReason, rejectedLaunchScript, parseSsListeners, parseNetstatListeners, parseLsofListeners, pickFreePort, preferredDeclaredPort, canEnumerateListeners, type BootDeps } from './boot-probe.js';
 import { type CommandRunner } from './command-run.js';
 import { taskThatIntroduced } from './task-provenance.js';
 import { type EnvClosure } from './env-template-closure.js';
@@ -133,8 +133,9 @@ export declare function discoverGateCommandBodies(cwd: string): Record<string, s
 export { runVerifyCommandLine, type VerifyRerunOutcome } from './command-run.js';
 export { observabilityGapFailure, unobservedVerdict };
 export { taskThatIntroduced };
-export { discoverBootCommand, detectsServedApp, runBootCheck, bootSkipVerdict, nonLaunchScriptReason, rejectedLaunchScript, parseSsListeners, parseNetstatListeners, parseLsofListeners, pickFreePort, preferredDeclaredPort, canEnumerateListeners };
+export { discoverBootCommand, detectsServedApp, runBootCheck, runBootSection, bootSkipVerdict, nonLaunchScriptReason, rejectedLaunchScript, parseSsListeners, parseNetstatListeners, parseLsofListeners, pickFreePort, preferredDeclaredPort, canEnumerateListeners };
 export type { BootDeps };
+export type { BootSectionVerdict } from './boot-probe.js';
 export { deriveOpenDebts, rerunDebtVerifyCommand };
 /**
  * Where in the gate a closure scan runs. The two stages are NOT interchangeable
@@ -259,5 +260,12 @@ export interface FinalGateOptions {
     envClosure?: (cwd: string) => EnvClosure;
     /** The repo's tracked file list, or null when it cannot be determined. */
     trackedFiles?: (cwd: string) => string[] | null;
+    /**
+     * The run's cancel. Reaches every command the gate spawns — repo-health, the
+     * lockfile/integration/launch sections and the ACCEPT-debt re-runs. Nothing
+     * could be cancelled while `CommandRunner` was synchronous: the event loop
+     * never got a turn in which to notice.
+     */
+    signal?: AbortSignal;
 }
 export declare function runFinalIntegrationGate(cwd: string, opts?: FinalGateOptions): Promise<FinalGateOutcome>;

package/dist/task/final-gate.js

@@ -51,10 +51,8 @@ import { runRepoHealthCheck, discoverHealthCommands } from './repo-health-check.
 import { deriveOpenDebts, rerunDebtVerifyCommand } from './accept-debt.js';
 import { readDeclaredScripts, missingDeclaredScripts, runnableDeclaredScripts } from './launch-contract.js';
 import { readLaunchManifest, inertLaunchContractNote, packageScripts, makeHasTarget } from './launch-manifest.js';
-import { discoverBootCommand, detectsServedApp, runBootCheck, bootSkipVerdict, nonLaunchScriptReason, rejectedLaunchScript, parseSsListeners, parseNetstatListeners, parseLsofListeners, pickFreePort, preferredDeclaredPort, canEnumerateListeners, recoverOrphanPort, defaultFindPortHolder } from './boot-probe.js';
+import { discoverBootCommand, detectsServedApp, runBootCheck, runBootSection, bootSkipVerdict, nonLaunchScriptReason, rejectedLaunchScript, parseSsListeners, parseNetstatListeners, parseLsofListeners, pickFreePort, preferredDeclaredPort, canEnumerateListeners } from './boot-probe.js';
 import { readEnvNotes, parseEnvNotes, isExcuseNote } from './env-notes.js';
-import { runRenderCheck } from './render-check.js';
-import { runDeepRenderCheck } from './deep-render-check.js';
 import { resolveRunner, runnerEnv } from './runner-resolve.js';
 import { classifyCommandRun, spawnCommand, INFRA_GAP_OUTPUT_RE } from './command-run.js';
 import { findLaunchConfigGap, probeEnv, configGapUnobservedNote } from './launch-config-gap.js';
@@ -64,6 +62,7 @@ import { findMissingEnvDeclarations, envGateFailureText, scanEnvTemplateClosure,
 import { findMissingServeEntry, serveEntryGateFailureText } from './serve-entry.js';
 import { makefileRecipe } from './command-shrink.js';
 import { GateTally, observabilityGapFailure, unobservedVerdict } from './gate-tally.js';
+import { VERIFY_FAIL_PREFIX } from './verify-work.js';
 /**
  * The project's OWN whole-repo integration commands (test, then build — test
  * first because it is the richer signal and the more common script). First
@@ -255,19 +254,26 @@ function resolveCommandBody(bin, args, scripts, makefile) {
  * passes `extraGapRe` (launch scripts), missing external infrastructure. Only a
  * command that actually ran and exited non-zero for a real reason fails.
  */
-function runGateCommand(cwd, [bin, args], timeoutMs, extraGapRe, 
+async function runGateCommand(cwd, [bin, args], timeoutMs, extraGapRe, 
 /** Replaces the child's environment wholesale (config-gap probe re-run only —
  *  see launch-config-gap.ts). Absent ⇒ `runnerEnv(runner)`, i.e. unchanged. */
 envOverride, 
 /** The spawner. Injected so the gate's own tests can script a verdict. */
-run = spawnCommand) {
+run = spawnCommand, signal) {
     // Runner resolution (mx5 run 16): a login-shell-stripped PATH left `bun`
     // unspawnable, so every dynamic check skipped and the gate went blind. The
     // resolved binary is spawned, and its directory rides on the child's PATH so
     // the SCRIPT CHAIN can re-invoke the runner (`bun run test` runs `bun test`
     // inside — a bare 127 there is the same blindness one level down).
     const runner = resolveRunner(bin);
-    const verdict = classifyCommandRun(run({ cwd, bin: runner.bin, args, timeoutMs, env: envOverride ?? runnerEnv(runner) }), extraGapRe ? [extraGapRe] : []);
+    const verdict = classifyCommandRun(await run({
+        cwd,
+        bin: runner.bin,
+        args,
+        timeoutMs,
+        env: envOverride ?? runnerEnv(runner),
+        ...(signal === undefined ? {} : { signal })
+    }), extraGapRe ? [extraGapRe] : []);
     if (verdict.outcome === 'gap') {
         return { outcome: 'skip', spawnFailed: verdict.gap === 'spawn-failed' };
     }
@@ -288,7 +294,7 @@ export { taskThatIntroduced };
 // src/). Re-exported so the seven validation harnesses under scripts/ — which have
 // always imported exactly this surface and nothing else from the gate — keep
 // working unchanged. Same pattern as taskThatIntroduced above.
-export { discoverBootCommand, detectsServedApp, runBootCheck, bootSkipVerdict, nonLaunchScriptReason, rejectedLaunchScript, parseSsListeners, parseNetstatListeners, parseLsofListeners, pickFreePort, preferredDeclaredPort, canEnumerateListeners };
+export { discoverBootCommand, detectsServedApp, runBootCheck, runBootSection, bootSkipVerdict, nonLaunchScriptReason, rejectedLaunchScript, parseSsListeners, parseNetstatListeners, parseLsofListeners, pickFreePort, preferredDeclaredPort, canEnumerateListeners };
 // The ACCEPT-debt re-check (`deriveOpenDebts`, `rerunDebtVerifyCommand`) lives in
 // accept-debt.ts with the ledger it reads and writes; re-exported so the
 // orchestrator and the harnesses under scripts/ keep working unchanged.
@@ -394,18 +400,28 @@ export async function runFinalIntegrationGate(cwd, opts = {}) {
             return inertClosure();
         }
     }, trackedFiles: trackedFilesFn = trackedFiles } = opts;
-    const stat = runRepoHealthCheck(cwd);
+    // ASYNC: the run-end gate no longer blocks the event loop for the project's own
+    // lint (measured 15s mx5 / 69s aiz-client with zero timer ticks), so a loader can
+    // paint and a cancel can reach the child.
+    const stat = await runRepoHealthCheck(cwd, {
+        run: runCmd,
+        ...(opts.signal === undefined ? {} : { signal: opts.signal })
+    });
     // Debts are derived once, before any section runs, and ride on every verdict
     // shape (GateTally.verdict): `reason` stays the mechanical failure because it
     // seeds the autofix child's prompt — run 11's fix child executed a recorded
     // claim as an instruction.
-    const debts = await deriveOpenDebts(cwd, stat.ok);
+    const debts = await deriveOpenDebts(cwd, stat.ok, runCmd, opts.signal);
     // Every section below RECORDS into the tally (failures ranked, the four
     // dynamic counters, the notes) and the verdict is assembled ONCE at the end —
     // see gate-tally.ts for what each method means.
     const tally = new GateTally();
+    // The prefix comes from VERIFY_FAIL_PREFIX so this run-level mint and the
+    // task-level `repo health:` one stay linked: both are the deterministic
+    // whole-repo static check, and `isStaticClassDebt` must recognise a debt that
+    // entered the ledger through EITHER altitude.
     if (!stat.ok)
-        tally.fail(`static checks: ${stat.reason}`);
+        tally.fail(`${VERIFY_FAIL_PREFIX['static-checks']} ${stat.reason}`);
     // Launch-contract diff (mx5 run 10 item 4): the design declared `migrate`/`seed`
     // scripts that fell through decompose and shipped missing, unchecked. Diff the
     // plan-time-extracted declared scripts against the manifest; a missing one is a
@@ -446,7 +462,7 @@ export async function runFinalIntegrationGate(cwd, opts = {}) {
         for (const cmd of list) {
             const label = `${cmd[0]} ${cmd[1].join(' ')}`;
             tally.attempted(cmd[0]);
-            const r = runGateCommand(cwd, cmd, timeoutMs, undefined, undefined, runCmd);
+            const r = await runGateCommand(cwd, cmd, timeoutMs, undefined, undefined, runCmd, opts.signal);
             if (r.outcome === 'skip') {
                 if (r.spawnFailed)
                     tally.spawnFailure(cmd[0]);
@@ -496,7 +512,7 @@ export async function runFinalIntegrationGate(cwd, opts = {}) {
             const cmd = ['bun', ['run', name]];
             const label = `${cmd[0]} ${cmd[1].join(' ')}`;
             tally.attempted(cmd[0]);
-            const r = runGateCommand(cwd, cmd, launchTimeout, INFRA_GAP_OUTPUT_RE, undefined, runCmd);
+            const r = await runGateCommand(cwd, cmd, launchTimeout, INFRA_GAP_OUTPUT_RE, undefined, runCmd, opts.signal);
             if (r.outcome === 'skip') {
                 if (r.spawnFailed)
                     tally.spawnFailure(cmd[0]);
@@ -525,7 +541,7 @@ export async function runFinalIntegrationGate(cwd, opts = {}) {
                     env: process.env
                 });
                 if (gap) {
-                    const probe = runGateCommand(cwd, cmd, launchTimeout, INFRA_GAP_OUTPUT_RE, probeEnv(runnerEnv(resolveRunner(cmd[0])), gap), runCmd);
+                    const probe = await runGateCommand(cwd, cmd, launchTimeout, INFRA_GAP_OUTPUT_RE, probeEnv(runnerEnv(resolveRunner(cmd[0])), gap), runCmd, opts.signal);
                     if (probe.outcome === 'pass') {
                         // Nothing about this script was OBSERVED: the real run could
                         // not reach it and the probe run is a diagnostic, never an
@@ -585,83 +601,33 @@ export async function runFinalIntegrationGate(cwd, opts = {}) {
     // statement about when they are meaningful.
     if (!boot && tally.silent())
         return tally.verdict(debts);
-    if (boot) {
-        const label = `${boot[0]} ${boot[1].join(' ')}`;
-        tally.attempted(boot[0]);
-        const expectServer = detectsServedApp(cwd, planText);
-        // 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. Default to the real
-        // probe; tests inject their own. 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 (judgeDeepSession).
-        const bootDepsWithRender = {
-            ...bootDeps,
-            renderProbe: bootDeps.renderProbe ?? runRenderCheck,
-            deepRenderProbe: bootDeps.deepRenderProbe ?? (url => runDeepRenderCheck(url, cwd)),
-            preferredPort: bootDeps.preferredPort ?? (() => preferredDeclaredPort(cwd))
-        };
-        let b = await runBootCheck(cwd, boot, bootGraceMs, {
-            expectServer,
-            deps: bootDepsWithRender
-        });
-        if (b.outcome === 'orphan-port') {
-            b = await recoverOrphanPort(cwd, boot, b, bootGraceMs, bootDepsWithRender, expectServer);
-        }
-        if (b.outcome !== 'skip')
-            tally.observed();
-        else if (b.spawnFailed)
-            tally.spawnFailure(boot[0]);
-        tally.bootUnobserved(bootSkipVerdict({
-            label,
-            skipped: b.outcome === 'skip',
-            expectServer
-        }));
-        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
-            // (`b0f90a7`, final-gate.ts `if (!canEnumerate) return passAndKill(…)`).
-            tally.failObserved(`boot check: \`${label}\` ${b.detail}`, 0);
-        }
-        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.
-            const holder = b.port !== null ? (bootDeps.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`
-                    : '';
-            tally.fail(`boot check: \`${label}\` could not bind: orphaned process / port already in use${who} (harness condition, not an app fault)`, 0);
-        }
-        else if (b.outcome === 'pass') {
-            tally.ran(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)
-                tally.warn(b.renderNote);
-        }
-    }
-    else {
-        // 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 && detectsServedApp(cwd, planText)) {
-            tally.bootUnobserved(`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.');
-        }
+    // The boot CONCEPT lives in boot-probe.ts (runBootSection): discovery,
+    // served-app detection, the probe defaults, the boot check, orphan-port
+    // recovery, the port-holder diagnosis, the skip verdict and the
+    // rejected-launch-script branch. This is the record, and nothing else.
+    const bootSection = await runBootSection(cwd, {
+        ...(planText === undefined ? {} : { planText }),
+        ...(bootGraceMs === undefined ? {} : { graceMs: bootGraceMs }),
+        deps: bootDeps
+    });
+    if (bootSection.attempted)
+        tally.attempted(bootSection.attempted);
+    if (bootSection.observed)
+        tally.observed();
+    else if (bootSection.spawnFailedBin)
+        tally.spawnFailure(bootSection.spawnFailedBin);
+    tally.bootUnobserved(bootSection.unobservedNote ?? null);
+    if (bootSection.failure) {
+        const { detail, rank, observed } = bootSection.failure;
+        if (observed)
+            tally.failObserved(detail, rank);
+        else
+            tally.fail(detail, rank);
     }
+    if (bootSection.ranLabel)
+        tally.ran(bootSection.ranLabel);
+    for (const w of bootSection.warnings)
+        tally.warn(w);
     // Full-skip blindness guard (mx5 run 16): commands were discovered but every
     // one skipped → rank-0 failure, never a static-only PASS. Runner resolvability
     // is checked through resolveRunner so the failure text can name the missing

package/dist/task/fix-child.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Running ONE bounded fix child and deciding what its ending MEANS.
+ *
+ * Two graduated-resolution passes drive a fix child through the same four rungs —
+ * cancel propagates, a thrown child is an error, a self-declared BLOCKED ends the
+ * attempt, anything else is DONE — and `final-gate-fix.ts:12` says so out loud:
+ * it "mirrors the per-task graduated-resolution shape (lint-fix.ts)". This is that
+ * ladder, once.
+ *
+ * NOT the rejected sharing. CONTEXT.md's "the two resolution loops stay two" is
+ * about `runGatesForTask` vs `runFinalGateStage` — the LOOPS, at two altitudes.
+ * This is one altitude down: the single child invocation inside each, where the
+ * two had actually drifted.
+ *
+ *  - **The lint-fix marker was a DEAD protocol.** `buildLintFixPrompt` instructs
+ *    the child to end with `LINT-FIX: DONE` or `LINT-FIX: BLOCKED <why>`, and the
+ *    call site was `await deps.runChild(...)` with the return value DISCARDED —
+ *    nothing in `src/` or `scripts/` parsed it. The twin parsed its own marker and
+ *    used it to skip the expensive gate re-run. So a lint-fix child that reported
+ *    BLOCKED still paid the full guard stack plus a whole repo-health run (15–69s
+ *    measured), and the user was told `did not converge: <health.reason>` instead
+ *    of the child's own stated reason. The suite fed `'LINT-FIX: DONE'` as fake
+ *    output, so it stayed green whether the marker was parsed or deleted.
+ *  - **The cancel rung re-typed its constant.** `lint-fix.ts` compared against a
+ *    literal `'__user_cancelled__'`; it was the only production site in `src/` not
+ *    importing `USER_CANCELLED`.
+ *
+ * What stays per-site: the arbiter (a gate re-run vs a repo-health re-run), the
+ * result shape, and the guard sets. Only the child call is shared.
+ */
+/** How one fix child ended. A CANCEL is not a member: it throws, so the caller's
+ *  own `USER_CANCELLED` path runs unchanged. */
+export type FixChildEnd = {
+    kind: 'done';
+    text: string;
+    note?: string;
+} | {
+    kind: 'blocked';
+    text: string;
+    note: string;
+} | {
+    kind: 'error';
+    msg: string;
+};
+export interface FixChildInput {
+    runChild: (tools: string, prompt: string, signal?: AbortSignal) => Promise<string>;
+    tools: string;
+    prompt: string;
+    signal?: AbortSignal;
+    /** The marker word this pass's prompt instructs — `LINT-FIX`, `FINAL-GATE-FIX`. */
+    marker: string;
+}
+/**
+ * Parse a fix child's final marker. Last match wins: the model reasons before
+ * concluding, and bash output can echo the words. No marker → DONE, because the
+ * pass's own arbiter re-runs either way; a missing marker only forfeits the
+ * early-out on a self-declared BLOCKED.
+ */
+export declare function parseFixMarker(marker: string, text: string): {
+    blocked: boolean;
+    note?: string;
+};
+/** Run one fix child through the four-rung ladder. Cancel THROWS; nothing else does. */
+export declare function runFixChild(input: FixChildInput): Promise<FixChildEnd>;

package/dist/task/fix-child.js

@@ -0,0 +1,66 @@
+/**
+ * Running ONE bounded fix child and deciding what its ending MEANS.
+ *
+ * Two graduated-resolution passes drive a fix child through the same four rungs —
+ * cancel propagates, a thrown child is an error, a self-declared BLOCKED ends the
+ * attempt, anything else is DONE — and `final-gate-fix.ts:12` says so out loud:
+ * it "mirrors the per-task graduated-resolution shape (lint-fix.ts)". This is that
+ * ladder, once.
+ *
+ * NOT the rejected sharing. CONTEXT.md's "the two resolution loops stay two" is
+ * about `runGatesForTask` vs `runFinalGateStage` — the LOOPS, at two altitudes.
+ * This is one altitude down: the single child invocation inside each, where the
+ * two had actually drifted.
+ *
+ *  - **The lint-fix marker was a DEAD protocol.** `buildLintFixPrompt` instructs
+ *    the child to end with `LINT-FIX: DONE` or `LINT-FIX: BLOCKED <why>`, and the
+ *    call site was `await deps.runChild(...)` with the return value DISCARDED —
+ *    nothing in `src/` or `scripts/` parsed it. The twin parsed its own marker and
+ *    used it to skip the expensive gate re-run. So a lint-fix child that reported
+ *    BLOCKED still paid the full guard stack plus a whole repo-health run (15–69s
+ *    measured), and the user was told `did not converge: <health.reason>` instead
+ *    of the child's own stated reason. The suite fed `'LINT-FIX: DONE'` as fake
+ *    output, so it stayed green whether the marker was parsed or deleted.
+ *  - **The cancel rung re-typed its constant.** `lint-fix.ts` compared against a
+ *    literal `'__user_cancelled__'`; it was the only production site in `src/` not
+ *    importing `USER_CANCELLED`.
+ *
+ * What stays per-site: the arbiter (a gate re-run vs a repo-health re-run), the
+ * result shape, and the guard sets. Only the child call is shared.
+ */
+import { USER_CANCELLED } from './child-runner.js';
+/**
+ * Parse a fix child's final marker. Last match wins: the model reasons before
+ * concluding, and bash output can echo the words. No marker → DONE, because the
+ * pass's own arbiter re-runs either way; a missing marker only forfeits the
+ * early-out on a self-declared BLOCKED.
+ */
+export function parseFixMarker(marker, text) {
+    const re = new RegExp(`${marker}:\\s*(DONE|BLOCKED)\\b[ \\t]*(.*)`, 'gi');
+    let last = null;
+    for (let m = re.exec(text); m !== null; m = re.exec(text))
+        last = m;
+    if (!last)
+        return { blocked: false };
+    if (last[1].toUpperCase() === 'BLOCKED') {
+        return { blocked: true, note: last[2].trim() || 'no reason given' };
+    }
+    return { blocked: false, note: last[2].trim() || undefined };
+}
+/** Run one fix child through the four-rung ladder. Cancel THROWS; nothing else does. */
+export async function runFixChild(input) {
+    let text;
+    try {
+        text = await input.runChild(input.tools, input.prompt, input.signal);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg === USER_CANCELLED)
+            throw err;
+        return { kind: 'error', msg };
+    }
+    const parsed = parseFixMarker(input.marker, text);
+    if (parsed.blocked)
+        return { kind: 'blocked', text, note: parsed.note ?? 'no reason given' };
+    return parsed.note ? { kind: 'done', text, note: parsed.note } : { kind: 'done', text };
+}