@mjasnikovs/pi-task 0.38.15 → 0.38.16

package/dist/shared/child-process.js

@@ -1,5 +1,6 @@
 import { spawn as defaultSpawn, spawnSync as spawnSyncDefault } from 'node:child_process';
 import { realStreamTimerDeps, StreamWatchdog } from './stream-watchdog.js';
+import { workerChannel } from '../workers/worker-channels.js';
 /** Grace period between SIGTERM and SIGKILL (ms). */
 export const KILL_GRACE_MS = 5000;
 /** Base flags shared by all child pi invocations. */
@@ -460,25 +461,17 @@ export function summarizeToolArgs(toolName, args) {
     if (!args || typeof args !== 'object')
         return '';
     const a = args;
-    const clip = (s) => {
-        const one = s.replace(/\s+/g, ' ').trim();
-        return one.length > 60 ? one.slice(0, 59) + '…' : one;
-    };
     if (toolName === 'bash' && typeof a.command === 'string') {
         return a.command.replace(/\s+/g, ' ').trim();
     }
-    if (toolName === 'pi-worker-docs'
-        && typeof a.module === 'string'
-        && typeof a.query === 'string') {
-        return `${a.module} "${clip(a.query)}"`;
-    }
-    // Search/fetch workers: without these the debug log shows a bare tool name
-    // and a run audit cannot tell WHAT was searched or fetched.
-    if (toolName === 'pi-worker-search' && typeof a.query === 'string') {
-        return `"${clip(a.query)}"`;
-    }
-    if (toolName === 'pi-worker-fetch' && typeof a.url === 'string') {
-        return clip(a.url);
+    // Each worker tool's argument shape is its own row's fact (worker-channels.ts);
+    // this used to be a third copy of the names AND a re-statement of each one's
+    // parameters. A row that has nothing to say falls through to the generic keys.
+    const channel = workerChannel(toolName);
+    if (channel) {
+        const summary = channel.summarize(a);
+        if (summary)
+            return summary;
     }
     if (typeof a.file_path === 'string')
         return a.file_path;

package/dist/task/accept-debt.d.ts

@@ -190,12 +190,12 @@ export declare function recheckAcceptDebts(debts: AcceptDebt[], opts: {
      * caller is expected to have made `pass` mean "ran, exited 0, and changed
      * nothing tracked" (`inv-no-write`).
      */
-    rerunVerify?: (command: string, debt: AcceptDebt) => VerifyRerunResult;
-}): {
+    rerunVerify?: (command: string, debt: AcceptDebt) => Promise<VerifyRerunResult>;
+}): Promise<{
     open: AcceptDebt[];
     resolved: AcceptDebt[];
     trail: string[];
-};
+}>;
 /**
  * Extract the paths whose EXISTENCE the reason asserts as the failure — a path
  * token immediately followed by "exists" / "still exists", or by "must/should not
@@ -247,7 +247,9 @@ export declare function describeDebt(d: AcceptDebt): string;
  * thing that can auto-close a static-class debt — so a caller that does not know
  * must pass `false` (unprovable ⇒ stays open), never a guess.
  */
-export declare function deriveOpenDebts(cwd: string, staticOk: boolean): Promise<{
+export declare function deriveOpenDebts(cwd: string, staticOk: boolean, 
+/** The spawner for the VERIFY-COMMAND re-runs. Defaults to the real one. */
+run?: CommandRunner, signal?: AbortSignal): Promise<{
     openDebts: AcceptDebt[];
     debtNote?: string;
     trail?: string[];
@@ -272,4 +274,4 @@ export declare function deriveOpenDebts(cwd: string, staticOk: boolean): Promise
 export declare function rerunDebtVerifyCommand(cwd: string, command: string, 
 /** The spawner, for BOTH the command and the tracked-state reads. Injected so
  *  the guard's four outcomes are testable without a repo or a real command. */
-run?: CommandRunner): VerifyRerunResult;
+run?: CommandRunner, signal?: AbortSignal): Promise<VerifyRerunResult>;

package/dist/task/accept-debt.js

@@ -339,7 +339,7 @@ const MAX_VERIFY_RERUNS = 3;
  * passed. FP-safe: the only auto-closes are ones a deterministic check can stand
  * behind, and here the check is the task spec's own command.
  */
-export function recheckAcceptDebts(debts, opts) {
+export async function recheckAcceptDebts(debts, opts) {
     const open = [];
     const resolved = [];
     const trail = [];
@@ -381,7 +381,7 @@ export function recheckAcceptDebts(debts, opts) {
         rerunsLeft -= 1;
         let r;
         try {
-            r = opts.rerunVerify(cmd, d);
+            r = await opts.rerunVerify(cmd, d);
         }
         catch {
             // A harness fault observes nothing, so it proves nothing.
@@ -499,8 +499,10 @@ export function describeDebt(d) {
  * thing that can auto-close a static-class debt — so a caller that does not know
  * must pass `false` (unprovable ⇒ stays open), never a guess.
  */
-export async function deriveOpenDebts(cwd, staticOk) {
-    const { open: openRaw, resolved, trail } = recheckAcceptDebts(await readAcceptDebts(cwd), {
+export async function deriveOpenDebts(cwd, staticOk, 
+/** The spawner for the VERIFY-COMMAND re-runs. Defaults to the real one. */
+run = spawnCommand, signal) {
+    const { open: openRaw, resolved, trail } = await recheckAcceptDebts(await readAcceptDebts(cwd), {
         staticOk,
         // Cross-task-deletion debts auto-close iff the deleted file is back in the
         // tree — a deterministic existence check, corroborating the per-file
@@ -509,7 +511,7 @@ export async function deriveOpenDebts(cwd, staticOk) {
         // VERIFY-COMMAND class (nexttask 5): a debt that NAMES a command is settled
         // by running that command, under the gate's own env-gap contract and behind
         // the no-write guard below.
-        rerunVerify: cmd => rerunDebtVerifyCommand(cwd, cmd)
+        rerunVerify: cmd => rerunDebtVerifyCommand(cwd, cmd, run, signal)
     });
     if (resolved.length > 0)
         await writeAcceptDebts(cwd, openRaw);
@@ -552,26 +554,27 @@ const DEBT_INFRA_GAP_RE = /ERR_POSTGRES_CONNECTION_CLOSED|ERR_MYSQL_CONNECTION|E
  * the guard: the re-run is INCONCLUSIVE there, because "nothing changed" would be an
  * assumption rather than an observation.
  */
-export function rerunDebtVerifyCommand(cwd, command, 
+export async function rerunDebtVerifyCommand(cwd, command, 
 /** The spawner, for BOTH the command and the tracked-state reads. Injected so
  *  the guard's four outcomes are testable without a repo or a real command. */
-run = spawnCommand) {
-    const tracked = () => {
-        const r = run({
+run = spawnCommand, signal) {
+    const tracked = async () => {
+        const r = await run({
             cwd,
             bin: 'git',
             args: ['status', '--porcelain', '--untracked-files=no'],
-            timeoutMs: 60_000
+            timeoutMs: 60_000,
+            ...(signal === undefined ? {} : { signal })
         });
         return r.failedToStart || r.status !== 0 ? null : r.stdout;
     };
-    const before = tracked();
-    const r = runVerifyCommandLine(cwd, command, DEBT_RERUN_TIMEOUT_MS, DEBT_INFRA_GAP_RE, run);
+    const before = await tracked();
+    const r = await runVerifyCommandLine(cwd, command, DEBT_RERUN_TIMEOUT_MS, DEBT_INFRA_GAP_RE, run, signal);
     if (r.outcome === 'fail')
         return { outcome: 'fail', detail: `exit ${r.status} — ${r.tail}` };
     if (r.outcome === 'gap')
         return { outcome: 'gap', detail: r.detail };
-    const after = tracked();
+    const after = await tracked();
     if (before === null || after === null) {
         return { outcome: 'gap', detail: 'tracked-state guard could not read git status' };
     }

package/dist/task/auto-orchestrator.js

@@ -9,6 +9,7 @@ import { existsSync } from 'node:fs';
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
 import { gateRunTask, markResumable } from './orchestrator.js';
+import { RUN_END_POLICY, runSucceeded } from './run-end.js';
 import { parseClarifyList, parseAutoAnswer, autoAnswerHasTag, deriveTitle } from './parsers.js';
 import { renderInlineMarkdown, stripInlineMarkdown } from './inline-markdown.js';
 import { AUTO_CLARIFY_PROMPT, AUTO_DECOMPOSE_PROMPT, DECOMPOSE_COVERAGE_PROMPT } from './auto-prompts.js';
@@ -32,6 +33,7 @@ import { runGatesForTask } from './task-gates.js';
 import { runFinalGateStage } from './run-final-gate.js';
 import { gitUnmergedPaths, gitStashRef } from './auto-commit.js';
 import { runFinalIntegrationGate, deriveOpenDebts } from './final-gate.js';
+import { spawnCommand } from './command-run.js';
 import { getConfig } from '../config/config.js';
 import { debugLogLevel, shouldLogDebug } from './debug-log.js';
 import { isYoloMode, yoloPickAnswer, YOLO_STAMP } from './yolo.js';
@@ -1171,7 +1173,7 @@ function defaultDeps(ctx, cwd, signal, title) {
         // The final integration gate follows the `verify work` switch: it is the
         // run-level half of the same verification story.
         finalGate: (cwd2, planText) => getConfig().verifyWork ?
-            runFinalIntegrationGate(cwd2, { planText })
+            runFinalIntegrationGate(cwd2, { planText, signal })
             : Promise.resolve({ ok: true, reason: 'disabled' }),
         // Uncommitted paths, for the stranded-sub-fix handling around the final-gate
         // picker (mx5 run 13 PROMPT 4 item 3). Every task is committed by the time
@@ -1183,7 +1185,9 @@ function defaultDeps(ctx, cwd, signal, title) {
         // Re-derive the debt ledger against the FINAL tree after a converged
         // autofix (nexttask 6). Only ever reached from inside the gate's own
         // resolution loop, so it needs no `verify work` switch of its own.
-        recheckOpenDebts: (cwd2, staticOk) => deriveOpenDebts(cwd2, staticOk)
+        // Same section, same cancel: this re-runs every ACCEPT-debt VERIFY command
+        // against the final tree, each under its own 300s cap.
+        recheckOpenDebts: (cwd2, staticOk) => deriveOpenDebts(cwd2, staticOk, spawnCommand, signal)
     };
 }
 // ─── Loop ────────────────────────────────────────────────────────────────────
@@ -1317,42 +1321,40 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                 onStart: resumeId ? undefined : (innerId => stampTaskInProgress(cwd, id, next.index, innerId, next.title))
             });
             active = res.ctx ?? active;
-            if (res.sessionCancelled) {
-                announceDone(active, `${id} paused — could not start a session. Run /task-auto-resume to retry.`, 'warning');
-                return;
-            }
-            if (res.interrupted) {
-                // The user interrupted implementation (ESC) and then declined to
-                // steer (empty steer prompt) — they want to stop here. Pause
-                // without checking the task off, so /task-auto-resume re-delivers
-                // this task's spec to finish it. (A plain ESC that the user
-                // follows with steering text never reaches here — that loops on
-                // the same task inside runSingleTask until a turn completes.)
-                await markResumable(cwd, res.taskId);
-                announceDone(active, `${id} paused at "${next.title}" — resume with /task-auto-resume.`, 'warning');
-                return;
-            }
-            // A phase-boundary cancel surfaces here as a plain !res.ok: the runner
-            // caught its own USER_CANCELLED and wrote state 'cancelled' (resumable)
-            // to the inner file. Claim it BEFORE the failure branch, or a
-            // user-requested stop is announced in red as "stopped … fix and
-            // resume". The inner file is already resumable and the parent stays
-            // in_progress, matching the loop-top cancel.
-            if (!res.ok && isCancelRequested()) {
-                announceDone(active, `${id} cancelled during "${next.title}" — resume with /task-auto-resume.`, 'warning');
-                return;
-            }
-            if (!res.ok) {
-                // Demote the INNER task file too: it reads `completed` from
+            // One dispatch over the named ending. The five-branch ladder this
+            // replaces had to ask `isCancelRequested()` — a module global
+            // `/task-cancel` never sets — to tell a user stop from a fault, so a
+            // cancel during a task was announced in red as "stopped … fix and
+            // resume" and the inner file's `cancelled` was overwritten with
+            // `failed`. The runner names the ending now; resumability is
+            // RUN_END_POLICY's; only the wording is this command's.
+            if (!runSucceeded(res.end)) {
+                const policy = RUN_END_POLICY[res.end.kind];
+                // Demote the INNER task file: it reads `completed` from
                 // spec-handoff, and leaving it that way is how a failed run's task
                 // file claimed success in the run 6 audit.
-                await markResumable(cwd, res.taskId);
-                await updateTaskFrontMatter(cwd, id, { state: 'failed' });
-                // res.reason is set when the implementation turn itself died
-                // (e.g. a context-overflow 400) — surface it so the real cause
-                // isn't lost behind the generic "stopped" message.
-                const why = res.reason ? ` — ${res.reason.slice(0, 160)}` : '';
-                announceDone(active, `${id} stopped at "${next.title}"${why} — fix and run /task-auto-resume.`, 'error');
+                if (policy.resumable)
+                    await markResumable(cwd, res.taskId);
+                // The PLAN fails only on a fault. A declined-steer interrupt leaves
+                // it in progress so /task-auto-resume re-delivers this task's spec.
+                if (policy.failsRun)
+                    await updateTaskFrontMatter(cwd, id, { state: 'failed' });
+                const why = res.end.kind === 'failed' && res.end.reason ?
+                    ` — ${res.end.reason.slice(0, 160)}`
+                    : '';
+                const msg = res.end.kind === 'no-session' ?
+                    `${id} paused — could not start a session. Run /task-auto-resume to retry.`
+                    : res.end.kind === 'cancelled' ?
+                        `${id} cancelled during "${next.title}" — resume with /task-auto-resume.`
+                        : res.end.kind === 'interrupted' ?
+                            // The user interrupted implementation (ESC) and then declined
+                            // to steer — they want to stop here. Paused without checking
+                            // the task off, so /task-auto-resume re-delivers this task's
+                            // spec. (A plain ESC followed by steering text never reaches
+                            // here — that loops inside runSingleTask until a turn ends.)
+                            `${id} paused at "${next.title}" — resume with /task-auto-resume.`
+                            : `${id} stopped at "${next.title}"${why} — fix and run /task-auto-resume.`;
+                announceDone(active, msg, policy.level);
                 return;
             }
             // GATE: actually RUN the task's verification against the just-finished

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

@@ -294,5 +294,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 {};