@mjasnikovs/pi-task 0.38.11 → 0.38.12

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

@@ -0,0 +1,189 @@
+/**
+ * The final gate's tally: everything its sections RECORD, and the one pure
+ * function that turns the record into a `FinalGateOutcome`.
+ *
+ * `runFinalIntegrationGate` used to carry this as twelve mutable locals — the
+ * ranked failure list, four dynamic counters, three note lists, a warning list,
+ * the boot verdict — threaded through ~400 lines by closure, with three sections
+ * hand-incrementing the same counters and one branch doing `dynObserved -= 1`.
+ * The verdict assembly at the end was pure, but reachable only through a temp
+ * dir and real spawns. Here the sections call named methods (an attempt is
+ * `attempted(bin)`, the config-gap un-count is `unobserve()`, a probe that looked
+ * and saw something bad is `failObserved(...)`) and `verdict()` is the ONE place
+ * the PASS / FAIL / UNOBSERVED polarity, note ordering and debt attachment live,
+ * testable with no tree at all.
+ *
+ * The two verdict predicates the gate has always exported — `observabilityGapFailure`
+ * (run-16 full-blindness FAIL) and `unobservedVerdict` (the third, non-blocking
+ * verdict) — live here because they read exactly the counters the tally owns;
+ * `final-gate.ts` re-exports them so every existing importer is unchanged.
+ */
+import type { AcceptDebt } from './accept-debt.js';
+import type { FinalGateOutcome } from './final-gate.js';
+/**
+ * Full-skip blindness guard (mx5 run 16). Per-command env-gap skips stay
+ * legitimate (a missing browser must not fail a suite); what may never happen
+ * again is ALL of them skipping while the gate still reports PASS — a gate that
+ * observed nothing dynamic has no basis to vouch for the assembled app. Pure so
+ * the semantics are unit-tested; the tally feeds it its own counters plus runner
+ * resolvability.
+ */
+export declare function observabilityGapFailure(args: {
+    /** Dynamic commands the gate discovered and tried to run. */
+    attempted: number;
+    /** Of those, how many it actually OBSERVED (a real pass OR a real fail —
+     *  either proves the command ran; only skips observe nothing). */
+    observed: number;
+    /** Of the skips, how many were SPAWN failures (runner never ran, ENOENT).
+     *  Tool-level gaps (missing browser, 127 inside the chain, timeout) prove
+     *  the runner itself works and keep the classic env-gap contract — the
+     *  blindness class fires only when EVERY attempt failed to even spawn. */
+    spawnFailures: number;
+    /** Distinct runner bins across the attempted commands. */
+    runnerBins: string[];
+    /** Is this runner spawnable (bare or via a known install location)? */
+    runnerResolvable: (bin: string) => boolean;
+}): string | null;
+/**
+ * The THIRD verdict. observabilityGapFailure above covers "commands were DISCOVERED
+ * but every one failed to spawn" — a rank-0 FAIL. It deliberately returns null for
+ * `attempted === 0`, and until now that silence fell straight through to
+ * `PASS — no integration command found (statics passed)`: the run-16 blindness class
+ * entering through a different door, where "we never checked" reads exactly like "we
+ * checked and it was fine". Measured 2026-07-27: IAR1 (C++/CMake, no package.json)
+ * shipped that verdict TWICE while carrying 2 and 3 open verify-FAIL debts, and
+ * godot-engine (package.json whose only script is `verify`) reproduces it live today.
+ *
+ * So: observed anything dynamic ⇒ PASS; discovered-but-all-spawn-failed ⇒ the
+ * existing FAIL; observed NOTHING ⇒ this note, carried on an `ok: true` outcome.
+ *
+ * WHY NON-BLOCKING (decided, not deferred — the evidence cuts both ways and this is
+ * the resolution):
+ *  - Blocking's case: both real occurrences also carried open verify-FAIL debt, so
+ *    the runs with no dynamic evidence were exactly the runs already known to be
+ *    carrying defects.
+ *  - Against, and decisive: (1) that debt is ALREADY surfaced unconditionally at the
+ *    gate moment, on PASS as on FAIL — the IAR1 records literally read "PASS — no
+ *    integration command found … UNRESOLVED VERIFY-FAIL DEBT still open (2)". The
+ *    missing signal was never the debt, it was the word PASS endorsing the run, and
+ *    that is what this fixes. (2) `ok: false` routes into the autofix picker, whose
+ *    seed is `reason`; "no integration command is discoverable" is not fixable by
+ *    editing code, so the highest-probability child response is to FABRICATE a
+ *    runnable command to satisfy the gate — the same fabrication class that refuted
+ *    the `## verified tooling` harvest (see discoverIntegrationCommands) and that had
+ *    run 11's fix child `rm` a sibling's deliverable. (3) That harvest being refuted
+ *    means IAR1 and godot-engine can NEVER discover a command, so blocking would end
+ *    every non-npm run in `failed` permanently, with no remedy — the task's own I3
+ *    ("show blocking does not block IAR1/godot post-Task-1") is unsatisfiable, and
+ *    its stated consequence is to downgrade to a warning and say so. This is that.
+ * The teeth are elsewhere and are real: the verdict word changes, the gate trail says
+ * UNOBSERVED, and the caller records a durable final-gate debt that the NEXT run's
+ * gate re-surfaces (it can never auto-close — it is not static-class).
+ */
+export declare function unobservedVerdict(args: {
+    /** Dynamic commands the gate discovered and tried to run (0 ⇒ nothing existed). */
+    discovered: number;
+    /** Of those, how many actually RAN (a real pass or a real fail). */
+    observed: number;
+}): string | null;
+/** What `verdict()` attaches to every outcome, PASS or FAIL: the run's open
+ *  ACCEPT debts, derived once before any section runs (deriveOpenDebts). */
+export interface GateDebts {
+    openDebts: AcceptDebt[];
+    /** Human-facing note listing the open debts; absent/undefined when none. */
+    debtNote?: string;
+}
+export declare class GateTally {
+    private readonly failures;
+    /** Labels of the dynamic commands that ran AND passed — the PASS reason names them. */
+    private readonly passed;
+    private attempts;
+    private observations;
+    private spawnFailures;
+    private readonly bins;
+    private readonly warnings;
+    /** UNOBSERVED notes for launch scripts reclassified as CONFIG GAPS (run 20).
+     *  They ride in `unobserved`, not `warnings`, so the caller's existing
+     *  `recordDebt(cwd, id, fin.unobserved, 'final-gate')` writes the debt —
+     *  never a PASS. */
+    private readonly configGapNotes;
+    /** The inert-launch-contract note (16A): "declared scripts, but no manifest to
+     *  diff against" — a note, never a failure, never a silent pass. */
+    private readonly contractNotes;
+    /** The boot section's own UNOBSERVED verdict (bootSkipVerdict / rejected launch
+     *  script). Lives outside the dynamic counters ON PURPOSE (mx5 run 18): the
+     *  test/build commands that did run cannot cancel it. */
+    private bootNote;
+    /** A failure at `rank` (default 1). Rank 0 is boot/render, the most load-bearing. */
+    fail(text: string, rank?: number): void;
+    /**
+     * A failure a PROBE returned after observing (nexttask 19A — see
+     * FinalGateOutcome.observedFailures). Used by exactly one caller: the boot
+     * section, whose `fail` outcome can only arise from a probe that looked. Every
+     * other `fail()` keeps its class, so nothing else changes.
+     */
+    failObserved(text: string, rank?: number): void;
+    /** A dynamic command that ran and passed; the PASS reason lists these. */
+    ran(label: string): void;
+    /** A dynamic spawn was attempted through runner `bin` (counted whether or not
+     *  it then skips). */
+    attempted(bin: string): void;
+    /** The attempt was OBSERVED — a real pass or a real fail; only skips observe nothing. */
+    observed(): void;
+    /**
+     * Un-count one observation. The config-gap branch (mx5 run 20): a launch
+     * script failed, the four static conditions plus the placeholder re-run said
+     * the failure was a missing env variable the shipped template declares, and
+     * so NOTHING about that script was observed — the real run could not reach
+     * it and the probe run is a diagnostic, never an observation. It un-counts,
+     * exactly like a skip would have.
+     */
+    unobserve(): void;
+    /** The attempt through `bin` never even spawned (ENOENT-class), as opposed to a
+     *  tool-level env gap inside the chain. */
+    spawnFailure(bin: string): void;
+    /** A WARNING appended to a PASS reason (excuse-note-covered skip, render note). */
+    warn(line: string): void;
+    configGap(note: string): void;
+    contractNote(note: string): void;
+    /** The boot section's UNOBSERVED verdict, or null when the boot was observed. */
+    bootUnobserved(note: string | null): void;
+    /** True while nothing dynamic has been attempted and nothing has failed —
+     *  the state the zero-discovery return checks (see runFinalIntegrationGate). */
+    silent(): boolean;
+    /** The run-16 blindness guard over this tally's own counters (see
+     *  observabilityGapFailure); the caller fails it at rank 0. */
+    blindness(runnerResolvable: (bin: string) => boolean): string | null;
+    /**
+     * The verdict. Pure over the tally's state; the same debts ride on every shape.
+     *
+     * FAIL when anything failed: stable-sorted so boot/render (rank 0) leads and
+     * everything else keeps execution order. One failure keeps the exact
+     * single-failure wording; several become a numbered list so the trail, the
+     * ACCEPT picker, and the autofix seed all carry the complete ranked picture.
+     * The observed subset rides along by exact text identity (19A) — the demote
+     * decision downstream reads THIS, instead of re-deriving observability from
+     * the failure string.
+     *
+     * Otherwise `ok: true`, with the UNOBSERVED note when the gate could not
+     * observe something it meant to. Two independent notes, either or both of which
+     * may apply: the boot never ran (run 18), and/or NOTHING dynamic ran at all
+     * (unobservedVerdict — commands WERE discovered, none spawn-failed so the run-16
+     * guard correctly stayed silent, and yet nothing ran: that used to be `statics
+     * passed (integration commands not runnable here)`, the identical "we never
+     * checked" silence wearing different words). The boot note leads because it
+     * names a concrete command and the trail line is sliced at 300 chars; then the
+     * config-gap notes, then the inert-contract note. Unchanged when anything at all
+     * was observed, so a project with runnable commands is byte-for-byte unaffected.
+     *
+     * ZERO ATTEMPTS IS UNOBSERVED, NEVER A PASS: when nothing dynamic was even
+     * attempted, the note IS the reason — there is no `statics passed (…)` suffix,
+     * because "we never checked" must not read like "we checked and it was fine".
+     * IAR1 shipped that verdict TWICE while carrying open verify-FAIL debt.
+     *
+     * The debt note rides in its OWN field: `reason` stays the mechanical failure
+     * because it seeds the autofix child's prompt (see FinalGateOutcome.reason —
+     * run 11's fix child executed a recorded claim as an instruction).
+     */
+    verdict(debts: GateDebts): FinalGateOutcome;
+}

package/dist/task/gate-tally.js

@@ -0,0 +1,249 @@
+/**
+ * Full-skip blindness guard (mx5 run 16). Per-command env-gap skips stay
+ * legitimate (a missing browser must not fail a suite); what may never happen
+ * again is ALL of them skipping while the gate still reports PASS — a gate that
+ * observed nothing dynamic has no basis to vouch for the assembled app. Pure so
+ * the semantics are unit-tested; the tally feeds it its own counters plus runner
+ * resolvability.
+ */
+export function observabilityGapFailure(args) {
+    if (args.attempted === 0 || args.observed > 0)
+        return null;
+    if (args.spawnFailures < args.attempted)
+        return null;
+    const unresolvable = args.runnerBins.filter(b => !args.runnerResolvable(b));
+    const runnerNote = unresolvable.length > 0 ?
+        ` — the project's own runner ${unresolvable
+            .map(b => `\`${b}\``)
+            .join(', ')} is not spawnable here (not on PATH nor any known install location)`
+        : '';
+    return (`observability gap: ${args.attempted} integration/boot command(s) exist but NONE `
+        + `could even spawn in this environment${runnerNote}; `
+        + `the gate observed nothing dynamic and cannot vouch for the assembled app`);
+}
+/**
+ * The THIRD verdict. observabilityGapFailure above covers "commands were DISCOVERED
+ * but every one failed to spawn" — a rank-0 FAIL. It deliberately returns null for
+ * `attempted === 0`, and until now that silence fell straight through to
+ * `PASS — no integration command found (statics passed)`: the run-16 blindness class
+ * entering through a different door, where "we never checked" reads exactly like "we
+ * checked and it was fine". Measured 2026-07-27: IAR1 (C++/CMake, no package.json)
+ * shipped that verdict TWICE while carrying 2 and 3 open verify-FAIL debts, and
+ * godot-engine (package.json whose only script is `verify`) reproduces it live today.
+ *
+ * So: observed anything dynamic ⇒ PASS; discovered-but-all-spawn-failed ⇒ the
+ * existing FAIL; observed NOTHING ⇒ this note, carried on an `ok: true` outcome.
+ *
+ * WHY NON-BLOCKING (decided, not deferred — the evidence cuts both ways and this is
+ * the resolution):
+ *  - Blocking's case: both real occurrences also carried open verify-FAIL debt, so
+ *    the runs with no dynamic evidence were exactly the runs already known to be
+ *    carrying defects.
+ *  - Against, and decisive: (1) that debt is ALREADY surfaced unconditionally at the
+ *    gate moment, on PASS as on FAIL — the IAR1 records literally read "PASS — no
+ *    integration command found … UNRESOLVED VERIFY-FAIL DEBT still open (2)". The
+ *    missing signal was never the debt, it was the word PASS endorsing the run, and
+ *    that is what this fixes. (2) `ok: false` routes into the autofix picker, whose
+ *    seed is `reason`; "no integration command is discoverable" is not fixable by
+ *    editing code, so the highest-probability child response is to FABRICATE a
+ *    runnable command to satisfy the gate — the same fabrication class that refuted
+ *    the `## verified tooling` harvest (see discoverIntegrationCommands) and that had
+ *    run 11's fix child `rm` a sibling's deliverable. (3) That harvest being refuted
+ *    means IAR1 and godot-engine can NEVER discover a command, so blocking would end
+ *    every non-npm run in `failed` permanently, with no remedy — the task's own I3
+ *    ("show blocking does not block IAR1/godot post-Task-1") is unsatisfiable, and
+ *    its stated consequence is to downgrade to a warning and say so. This is that.
+ * The teeth are elsewhere and are real: the verdict word changes, the gate trail says
+ * UNOBSERVED, and the caller records a durable final-gate debt that the NEXT run's
+ * gate re-surfaces (it can never auto-close — it is not static-class).
+ */
+export function unobservedVerdict(args) {
+    if (args.observed > 0)
+        return null;
+    // Kept short ON PURPOSE: the run-level trail line slices the reason at 300 chars,
+    // and the whole point of this verdict is that the durable record carries it.
+    const why = args.discovered === 0 ?
+        'no integration, lockfile or boot command was discoverable here, so the gate ran '
+            + 'nothing at all'
+        : `all ${args.discovered} discovered command(s) skipped as environment gaps, so the `
+            + 'gate ran nothing observable';
+    return (`UNOBSERVED — NOT a pass: ${why}; statics passed, but this run produced NO evidence `
+        + 'that the assembled product builds, boots or works.');
+}
+export class GateTally {
+    // Aggregated failures across ALL sections (mx5 run 13 — see runFinalIntegrationGate's
+    // doc). rank 0 = boot/render ("does not serve/render" is the most load-bearing
+    // signal); rank 1 = everything else, kept in execution order by stable sort.
+    failures = [];
+    /** Labels of the dynamic commands that ran AND passed — the PASS reason names them. */
+    passed = [];
+    // Full-skip blindness counters (mx5 run 16): every dynamic spawn counts an
+    // attempt; a real pass OR a real fail counts an observation; skips observe
+    // nothing. If everything discovered ends up skipped, observabilityGapFailure
+    // turns the silence into a rank-0 failure instead of a static-only PASS.
+    attempts = 0;
+    observations = 0;
+    spawnFailures = 0;
+    bins = new Set();
+    warnings = [];
+    /** UNOBSERVED notes for launch scripts reclassified as CONFIG GAPS (run 20).
+     *  They ride in `unobserved`, not `warnings`, so the caller's existing
+     *  `recordDebt(cwd, id, fin.unobserved, 'final-gate')` writes the debt —
+     *  never a PASS. */
+    configGapNotes = [];
+    /** The inert-launch-contract note (16A): "declared scripts, but no manifest to
+     *  diff against" — a note, never a failure, never a silent pass. */
+    contractNotes = [];
+    /** The boot section's own UNOBSERVED verdict (bootSkipVerdict / rejected launch
+     *  script). Lives outside the dynamic counters ON PURPOSE (mx5 run 18): the
+     *  test/build commands that did run cannot cancel it. */
+    bootNote = null;
+    /** A failure at `rank` (default 1). Rank 0 is boot/render, the most load-bearing. */
+    fail(text, rank = 1) {
+        this.failures.push({ rank, text });
+    }
+    /**
+     * A failure a PROBE returned after observing (nexttask 19A — see
+     * FinalGateOutcome.observedFailures). Used by exactly one caller: the boot
+     * section, whose `fail` outcome can only arise from a probe that looked. Every
+     * other `fail()` keeps its class, so nothing else changes.
+     */
+    failObserved(text, rank = 1) {
+        this.failures.push({ rank, text, observed: true });
+    }
+    /** A dynamic command that ran and passed; the PASS reason lists these. */
+    ran(label) {
+        this.passed.push(label);
+    }
+    /** A dynamic spawn was attempted through runner `bin` (counted whether or not
+     *  it then skips). */
+    attempted(bin) {
+        this.attempts += 1;
+        this.bins.add(bin);
+    }
+    /** The attempt was OBSERVED — a real pass or a real fail; only skips observe nothing. */
+    observed() {
+        this.observations += 1;
+    }
+    /**
+     * Un-count one observation. The config-gap branch (mx5 run 20): a launch
+     * script failed, the four static conditions plus the placeholder re-run said
+     * the failure was a missing env variable the shipped template declares, and
+     * so NOTHING about that script was observed — the real run could not reach
+     * it and the probe run is a diagnostic, never an observation. It un-counts,
+     * exactly like a skip would have.
+     */
+    unobserve() {
+        this.observations -= 1;
+    }
+    /** The attempt through `bin` never even spawned (ENOENT-class), as opposed to a
+     *  tool-level env gap inside the chain. */
+    spawnFailure(bin) {
+        this.spawnFailures += 1;
+        this.bins.add(bin);
+    }
+    /** A WARNING appended to a PASS reason (excuse-note-covered skip, render note). */
+    warn(line) {
+        this.warnings.push(line);
+    }
+    configGap(note) {
+        this.configGapNotes.push(note);
+    }
+    contractNote(note) {
+        this.contractNotes.push(note);
+    }
+    /** The boot section's UNOBSERVED verdict, or null when the boot was observed. */
+    bootUnobserved(note) {
+        this.bootNote = note;
+    }
+    /** True while nothing dynamic has been attempted and nothing has failed —
+     *  the state the zero-discovery return checks (see runFinalIntegrationGate). */
+    silent() {
+        return this.attempts === 0 && this.failures.length === 0;
+    }
+    /** The run-16 blindness guard over this tally's own counters (see
+     *  observabilityGapFailure); the caller fails it at rank 0. */
+    blindness(runnerResolvable) {
+        return observabilityGapFailure({
+            attempted: this.attempts,
+            observed: this.observations,
+            spawnFailures: this.spawnFailures,
+            runnerBins: [...this.bins],
+            runnerResolvable
+        });
+    }
+    /**
+     * The verdict. Pure over the tally's state; the same debts ride on every shape.
+     *
+     * FAIL when anything failed: stable-sorted so boot/render (rank 0) leads and
+     * everything else keeps execution order. One failure keeps the exact
+     * single-failure wording; several become a numbered list so the trail, the
+     * ACCEPT picker, and the autofix seed all carry the complete ranked picture.
+     * The observed subset rides along by exact text identity (19A) — the demote
+     * decision downstream reads THIS, instead of re-deriving observability from
+     * the failure string.
+     *
+     * Otherwise `ok: true`, with the UNOBSERVED note when the gate could not
+     * observe something it meant to. Two independent notes, either or both of which
+     * may apply: the boot never ran (run 18), and/or NOTHING dynamic ran at all
+     * (unobservedVerdict — commands WERE discovered, none spawn-failed so the run-16
+     * guard correctly stayed silent, and yet nothing ran: that used to be `statics
+     * passed (integration commands not runnable here)`, the identical "we never
+     * checked" silence wearing different words). The boot note leads because it
+     * names a concrete command and the trail line is sliced at 300 chars; then the
+     * config-gap notes, then the inert-contract note. Unchanged when anything at all
+     * was observed, so a project with runnable commands is byte-for-byte unaffected.
+     *
+     * ZERO ATTEMPTS IS UNOBSERVED, NEVER A PASS: when nothing dynamic was even
+     * attempted, the note IS the reason — there is no `statics passed (…)` suffix,
+     * because "we never checked" must not read like "we checked and it was fine".
+     * IAR1 shipped that verdict TWICE while carrying open verify-FAIL debt.
+     *
+     * The debt note rides in its OWN field: `reason` stays the mechanical failure
+     * because it seeds the autofix child's prompt (see FinalGateOutcome.reason —
+     * run 11's fix child executed a recorded claim as an instruction).
+     */
+    verdict(debts) {
+        const withDebts = (o) => ({
+            ...o,
+            ...(debts.debtNote ? { debtNote: debts.debtNote } : {}),
+            openDebts: debts.openDebts
+        });
+        if (this.failures.length > 0) {
+            const ranked = [...this.failures].sort((a, b) => a.rank - b.rank);
+            const texts = ranked.map(f => f.text);
+            const observed = ranked.filter(f => f.observed === true).map(f => f.text);
+            return withDebts({
+                ok: false,
+                reason: texts.length === 1 ?
+                    texts[0]
+                    : `${texts.length} failures (ranked, most load-bearing first):\n${texts
+                        .map((t, i) => `${i + 1}. ${t}`)
+                        .join('\n')}`,
+                failures: texts,
+                ...(observed.length > 0 ? { observedFailures: observed } : {})
+            });
+        }
+        const unobserved = [
+            this.bootNote,
+            unobservedVerdict({ discovered: this.attempts, observed: this.observations }),
+            ...this.configGapNotes,
+            ...this.contractNotes
+        ]
+            .filter(n => n !== null)
+            .join(' ');
+        if (this.attempts === 0) {
+            return withDebts({ ok: true, unobserved, reason: unobserved });
+        }
+        const warningNote = this.warnings.length > 0 ? ` — WARNING: ${this.warnings.join('; WARNING: ')}` : '';
+        return withDebts({
+            ok: true,
+            ...(unobserved ? { unobserved } : {}),
+            reason: (unobserved ? `${unobserved} — ` : '')
+                + (this.passed.length > 0 ?
+                    `statics + ${this.passed.map(c => `\`${c}\``).join(', ')} passed`
+                    : 'statics passed (integration commands not runnable here)')
+                + warningNote
+        });
+    }
+}

package/dist/task/implementation-turn.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Implementation-turn supervision — what happens between "the spec was delivered
+ * to the main session" and "we know how the implementation turn REALLY ended".
+ *
+ * A single `waitForIdle` resolves for four different reasons, and three of them
+ * are not "the model finished":
+ *   • `aborted`     — a user ESC (or the command watchdog) cut the turn short;
+ *   • `compaction`  — a threshold auto-compaction parked the turn at idle without
+ *                     auto-continuing (the runtime expects a manual continue);
+ *   • `error`       — the model/provider died mid-turn after pi's own retries;
+ *   • `stop`        — genuine completion.
+ * `classifyTurnEnd` reads the session entries and names ONE of those, in the
+ * precedence the supervision sequence needs; `superviseImplementation` then
+ * resumes across compactions, lets the user steer after an interrupt, and reports
+ * the terminal outcome. The orchestrator calls it once.
+ */
+import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+/** How the most recent implementation turn ended. See {@link classifyTurnEnd}. */
+export type TurnEnd = 'stop' | 'aborted' | 'error' | 'compaction';
+/**
+ * The slice of a session entry the classifier reads. Structural on purpose: the
+ * runtime's `SessionEntry` union is wider than we need, and the tests build
+ * entries from plain literals.
+ */
+export type SessionEntryLike = {
+    type?: string;
+    message?: {
+        role?: string;
+        stopReason?: string;
+        errorMessage?: string;
+        content?: unknown;
+    };
+};
+/**
+ * Classify how the most recent turn ended, from the session entries alone.
+ *
+ * Precedence, when several signals are present at once (this is the order the
+ * supervision sequence has always applied, now stated in one place):
+ *   1. `aborted`    — the last assistant message has stopReason "aborted". A user
+ *                     ESC (or watchdog abort) wins over everything: it is not a
+ *                     compaction pause, and the steer loop owns it.
+ *   2. `compaction` — a `compaction` entry sits AFTER the last assistant message.
+ *                     Position-based, not timestamp-based: the runtime appends the
+ *                     boundary to the tail of the branch after the message that
+ *                     triggered it (`appendCompaction` → `_appendEntry` push), so a
+ *                     trailing compaction means we are parked with no continuation.
+ *                     A finished turn ends on an assistant message; an *overflow*
+ *                     compaction self-retries and never leaves us idle here.
+ *   3. `error`      — the last assistant message has stopReason "error": the
+ *                     model/provider died (context-overflow 400, disconnect, 5xx)
+ *                     after pi exhausted its own retries.
+ *   4. `stop`       — anything else, including a session with no assistant turn.
+ */
+export declare function classifyTurnEnd(entries: ReadonlyArray<SessionEntryLike>): TurnEnd;
+/**
+ * The provider's error cause for an `error` turn end — the message the run's
+ * "stopped at …" line quotes so the real cause is not lost. Undefined unless the
+ * last assistant message ended with stopReason "error".
+ */
+export declare function turnErrorMessage(entries: ReadonlyArray<SessionEntryLike>): string | undefined;
+/**
+ * True when the watchdog's reminder follow-up has been DELIVERED into the session
+ * after the aborted assistant turn but its own turn has not finished yet — the
+ * artifact that confirms a pending watchdog recovery. Scoped after the LAST
+ * assistant entry so an earlier fire's reminder (already answered by its own
+ * turn) never matches.
+ */
+export declare function watchdogReminderDelivered(entries: ReadonlyArray<SessionEntryLike>): boolean;
+/**
+ * The slice of the replacement-session context the supervision needs.
+ * `sendUserMessage` lives on ReplacedSessionContext (not the base command ctx,
+ * and not re-exported from the package), so we narrow to just what we call.
+ */
+export type SteerCtx = ExtensionCommandContext & {
+    sendUserMessage(content: string, options?: {
+        deliverAs?: 'steer' | 'followUp';
+    }): Promise<void>;
+};
+/**
+ * Timing knobs for the watchdog-abort guard in {@link steerUntilDone}, injectable
+ * so tests exercise the grace expiry without a 10-second wait. `graceMs` bounds
+ * how long the loop waits for the watchdog's follow-up to be DELIVERED (not to
+ * finish — its turn may legitimately run for minutes afterwards); delivery is
+ * normally near-instant, so the grace only expires on a stale flag.
+ */
+export interface SteerWatchdogDeps {
+    consume: () => boolean;
+    graceMs: number;
+    pollMs: number;
+}
+/**
+ * What the resume/steer loops genuinely need from the session — no more. Built
+ * from a live ctx by {@link turnDepsFor}; a test builds one from plain fakes.
+ */
+export interface ImplementationTurnDeps {
+    /** The live session entries — the only thing the classifier reads. */
+    entries: () => ReadonlyArray<SessionEntryLike>;
+    /** Queue a follow-up user turn on the (idle) session. */
+    send: (text: string) => Promise<void>;
+    /** Wait for the session to go idle again. */
+    waitForIdle: () => Promise<void>;
+    /** Solicit steering text after an interrupt; undefined/empty = pause the run. */
+    ask: () => Promise<string | undefined>;
+    /** The watchdog one-shot flag and the bounded wait for its follow-up. */
+    watchdog: SteerWatchdogDeps;
+    /** Optional trail for the decisions taken; absent → silent. */
+    log?: (msg: string) => void;
+}
+export interface SuperviseOptions {
+    /**
+     * Ask the user for a steering message after they interrupt (ESC) the
+     * implementation turn. Return text to continue the same task as another turn,
+     * or undefined/empty to pause the run. Defaults to a bridged SessionUI.ask
+     * (local TUI input raced against a remote browser card); injectable so the
+     * steer loop is testable without a real dialog.
+     */
+    promptSteer?: (ctx: ExtensionCommandContext) => Promise<string | undefined>;
+    /** Watchdog-guard timing overrides (tests); absent → production defaults. */
+    watchdog?: Partial<SteerWatchdogDeps>;
+    log?: (msg: string) => void;
+}
+/** Bind the supervision deps to a live session context. */
+export declare function turnDepsFor(ctx: SteerCtx, opts?: SuperviseOptions): ImplementationTurnDeps;
+/**
+ * Nudge that resumes an implementation turn the runtime parked at a compaction
+ * boundary. It must let a turn that was genuinely finished (then tipped over the
+ * threshold by its own final message) confirm completion without inventing busywork
+ * — we cannot tell "paused mid-task by compaction" from "finished, then compacted"
+ * from the boundary alone, so the wording lets a done turn end in one line.
+ */
+export declare const CONTINUE_AFTER_COMPACTION: string;
+/**
+ * Safety cap on compaction-driven resumes for a single implementation turn. Each
+ * resume follows a real compaction (which only fires after the model produced a
+ * turn large enough to cross the threshold), so a legitimately large task may
+ * resume a handful of times; the cap exists only to stop a pathological loop from
+ * auto-sending forever with no user in the loop. Hitting it stops resuming and lets
+ * the verify gate / `/task-auto-resume` catch any leftover incompleteness.
+ */
+export declare const MAX_COMPACTION_RESUMES = 20;
+/**
+ * Resume an implementation turn that went idle at a threshold-compaction boundary.
+ * The runtime compacts and parks at idle without auto-continuing; we send a
+ * continue and wait again, repeating across successive compactions until the turn
+ * ends on a real assistant message (genuine completion). A user ESC takes priority
+ * (`classifyTurnEnd` ranks `aborted` above `compaction`, so the steer loop handles
+ * it), and the safety cap bounds a runaway. Returns the number of resumes
+ * performed (0 when the turn did not end on a compaction).
+ */
+export declare function resumeAcrossCompactions(deps: ImplementationTurnDeps): Promise<number>;
+/**
+ * After the implementation turn settles, honour a user ESC by letting them steer.
+ *
+ * `waitForIdle` resolves both on natural completion AND on an ESC (which aborts
+ * the turn → idle). When the last turn was aborted, the host's main input loop is
+ * blocked inside our command handler, so a message typed in the editor would only
+ * queue, never run (interactive-mode routes idle input through onInputCallback,
+ * which is unset while we hold the loop). We therefore solicit the steering text
+ * ourselves and feed it back as another turn via sendUserMessage — which runs to
+ * completion when the session is idle. Repeat until a turn finishes uninterrupted.
+ *
+ * A WATCHDOG abort also ends the turn with stopReason 'aborted' — indistinguishable
+ * from a human ESC by the session entries alone at that instant. The watchdog
+ * queues its own recovery follow-up, so prompting there would show a steering
+ * dialog to an empty room and wedge an unattended run on the race. The one-shot
+ * flag (set synchronously before the abort) routes that case to
+ * {@link awaitWatchdogFollowUp} instead; a stale flag degrades to a bounded wait
+ * followed by the ordinary prompt, never to a suppressed one.
+ *
+ * Returns true when the user declined to steer (empty/cancelled) and the run
+ * should pause; false when the implementation completed (steered or not).
+ */
+export declare function steerUntilDone(deps: ImplementationTurnDeps): Promise<boolean>;
+export interface ImplementationOutcome {
+    /**
+     * The user interrupted the implementation (ESC) and then declined to steer
+     * (empty steer prompt) — they want the run to pause rather than continue. A
+     * plain ESC followed by steering text does NOT set this: that case loops on the
+     * same task until a turn finishes uninterrupted.
+     */
+    interrupted: boolean;
+    /**
+     * The failure cause when the turn ended with stopReason "error" (the
+     * model/provider died mid-implementation after the task file was already
+     * marked `completed` at spec-handoff). Undefined when the turn ended cleanly,
+     * and never set alongside `interrupted`.
+     */
+    error?: string;
+    /** Compaction resumes performed before the turn reached its real end. */
+    resumes: number;
+}
+/**
+ * Supervise an implementation turn from the first idle after spec delivery until
+ * its REAL end: resume across any compaction boundaries first (so steering and
+ * error inspection see the turn's actual end, not a compaction pause), then let
+ * the user steer across interrupts, then read how the final turn ended. The
+ * caller has already awaited the first idle.
+ */
+export declare function superviseImplementation(ctx: SteerCtx, opts?: SuperviseOptions): Promise<ImplementationOutcome>;
+/** {@link superviseImplementation} over an already-bound deps object (tests). */
+export declare function superviseWith(deps: ImplementationTurnDeps): Promise<ImplementationOutcome>;