@mjasnikovs/pi-task 0.17.27 → 0.18.0

package/dist/config/config.d.ts

@@ -5,6 +5,13 @@ export interface PiTaskConfig {
     orientation: boolean;
     enforceGuidelines: boolean;
     verifyWork: boolean;
+    /**
+     * Run the four research workers concurrently instead of one at a time.
+     * DEFAULT OFF: serial was A/B-proven faster on a single-GPU local backend
+     * (concurrent streams split the GPU and slow each other ~4×, see
+     * phases.ts). Turn on only for a parallel-capable backend.
+     */
+    parallelResearchWorkers: boolean;
 }
 export declare function getConfig(): PiTaskConfig;
 export declare function saveConfig(config: PiTaskConfig): Promise<void>;

package/dist/config/config.js

@@ -8,7 +8,8 @@ const DEFAULTS = {
     autoCommit: true,
     orientation: true,
     enforceGuidelines: true,
-    verifyWork: true
+    verifyWork: true,
+    parallelResearchWorkers: false
 };
 const CONFIG_PATH = path.join(os.homedir(), '.config', 'pi-task', 'config.json');
 const _g = globalThis;

package/dist/config/register.js

@@ -72,6 +72,11 @@ const ITEMS = [
         id: 'enforceGuidelines',
         label: 'enforce guidelines',
         description: "Check each /task and /task-auto commit against AGENTS.md/CLAUDE.md. Needs 'verify work' to FIX drift (fixes are reverted if they regress verification); without it, only reports violations. Enabling it makes /task wait for the implementation"
+    },
+    {
+        id: 'parallelResearchWorkers',
+        label: 'parallel research',
+        description: 'Run the 4 research workers concurrently. Leave OFF on a single-GPU local server (serial is measurably faster there); turn on only for a parallel-capable model backend'
     }
 ];
 function makeTheme(theme) {

package/dist/shared/child-process.d.ts

@@ -39,6 +39,13 @@ export interface ChildResult {
      * Only populated in json-events mode.
      */
     modelError?: string;
+    /**
+     * true when the stall guard killed the child: no output for the stall
+     * window AND the model endpoint probe found the backend unreachable.
+     * Callers must check this BEFORE `aborted` — the kill sets aborted too,
+     * and without the flag it would mislabel as a user cancel.
+     */
+    stalled?: boolean;
 }
 export interface ToolCall {
     name: string;
@@ -76,6 +83,20 @@ export interface RunChildJsonEventsOptions {
     onContextUsage?: (snapshot: ContextSnapshot) => void;
     onToolCall?: (call: ToolCall) => LoopHit | null;
     onFirstByte?: () => void;
+    /**
+     * Dead-backend stall guard (mx5 run 7: model server died mid-child, the
+     * child hung MUTE for 64 minutes). Liveness is OUTPUT PROGRESS, not wall
+     * time: any stdout/stderr chunk resets the window, so honest long work is
+     * never killed. Only when nothing arrived for `afterMs` is `probe` asked
+     * whether the model backend is reachable — reachable → keep waiting
+     * (prompt processing legitimately emits nothing for minutes); unreachable
+     * → the child is killed and the result carries `stalled: true` so callers
+     * report the real cause instead of hanging or mislabeling a user cancel.
+     */
+    stall?: {
+        afterMs: number;
+        probe: () => Promise<boolean>;
+    };
 }
 export type RunChildOptions = RunChildTextOptions | RunChildJsonEventsOptions;
 /**

package/dist/shared/child-process.js

@@ -197,8 +197,40 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
             }, KILL_GRACE_MS);
         };
         const sink = opts?.mode === 'json-events' ? new JsonEventSink(opts, killProc) : null;
+        // Dead-backend stall guard (json-events children only; see the option
+        // docs). Any output resets the window; a reachable probe also resets it
+        // so the next probe is a full window away, not every tick.
+        const stall = opts?.mode === 'json-events' ? opts.stall : undefined;
+        let lastActivity = Date.now();
+        let stalled = false;
+        let probing = false;
+        const stallTimer = stall ?
+            setInterval(() => {
+                if (probing || Date.now() - lastActivity < stall.afterMs)
+                    return;
+                probing = true;
+                stall
+                    .probe()
+                    .then(reachable => {
+                    probing = false;
+                    if (reachable || stalled) {
+                        lastActivity = Date.now();
+                        return;
+                    }
+                    stalled = true;
+                    killProc();
+                })
+                    .catch(() => {
+                    // A probe that itself crashed proves nothing —
+                    // benefit of the doubt, keep waiting.
+                    probing = false;
+                    lastActivity = Date.now();
+                });
+            }, Math.max(50, Math.min(stall.afterMs / 2, 15_000)))
+            : undefined;
         let firstByteFired = false;
         proc.stdout?.on('data', (d) => {
+            lastActivity = Date.now();
             if (!firstByteFired) {
                 firstByteFired = true;
                 opts?.onFirstByte?.();
@@ -212,9 +244,12 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
                 stdout += chunk;
         });
         proc.stderr?.on('data', (d) => {
+            lastActivity = Date.now();
             stderr += d.toString();
         });
         proc.on('close', (code) => {
+            if (stallTimer)
+                clearInterval(stallTimer);
             if (sink)
                 sink.flush();
             const text = sink ? sink.text : undefined;
@@ -224,10 +259,13 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
                 exitCode: code ?? 0,
                 aborted,
                 text,
-                modelError: sink?.modelError
+                modelError: sink?.modelError,
+                ...(stalled ? { stalled: true } : {})
             });
         });
         proc.on('error', () => {
+            if (stallTimer)
+                clearInterval(stallTimer);
             resolve({ stdout, stderr, exitCode: 1, aborted });
         });
         if (signal) {
@@ -247,15 +285,25 @@ 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') {
-        const q = a.query.replace(/\s+/g, ' ').trim();
-        const truncated = q.length > 60 ? q.slice(0, 59) + '…' : q;
-        return `${a.module} "${truncated}"`;
+        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);
     }
     if (typeof a.file_path === 'string')
         return a.file_path;

package/dist/shared/model-endpoint.d.ts

@@ -0,0 +1,8 @@
+/** Base URLs of every custom provider pi is configured with (possibly none). */
+export declare function discoverModelEndpoints(agentDir?: string): string[];
+/**
+ * true → at least one endpoint ANSWERED (any HTTP status counts — a 404 still
+ * proves the server is alive); false → every probe was refused or hung past the
+ * timeout. An empty list is true: nothing to probe means never kill.
+ */
+export declare function probeModelEndpoints(urls: string[], timeoutMs?: number): Promise<boolean>;

package/dist/shared/model-endpoint.js

@@ -0,0 +1,56 @@
+/**
+ * model-endpoint — discovery + reachability probe for the model backend(s) a
+ * child pi process talks to.
+ *
+ * The failure this serves (mx5 run 7, validated): the model server went down
+ * mid-gate-child and the child hung MUTE for 64 minutes — pi's own
+ * connection-error handling only fires when a request FAILS, not when the
+ * backend freezes and the open request simply never answers. The stall guard in
+ * runChild uses this module to tell the two apart: no output could be honest
+ * long work (prompt processing emits nothing for minutes), so only "no output
+ * AND the endpoint does not answer" is treated as a dead backend.
+ *
+ * Discovery is generic: the custom providers pi itself is configured with
+ * (models.json `providers.*.baseUrl`), no provider or server names hardcoded.
+ * No discoverable endpoint → nothing to probe → the guard NEVER kills (a child
+ * on a backend we cannot see must get the benefit of the doubt).
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+/** Base URLs of every custom provider pi is configured with (possibly none). */
+export function discoverModelEndpoints(agentDir = path.join(os.homedir(), '.pi', 'agent')) {
+    try {
+        const j = JSON.parse(fs.readFileSync(path.join(agentDir, 'models.json'), 'utf8'));
+        const urls = [];
+        for (const p of Object.values(j.providers ?? {})) {
+            if (typeof p?.baseUrl === 'string' && p.baseUrl.length > 0)
+                urls.push(p.baseUrl);
+        }
+        return [...new Set(urls)];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * true → at least one endpoint ANSWERED (any HTTP status counts — a 404 still
+ * proves the server is alive); false → every probe was refused or hung past the
+ * timeout. An empty list is true: nothing to probe means never kill.
+ */
+export async function probeModelEndpoints(urls, timeoutMs = 5_000) {
+    if (urls.length === 0)
+        return true;
+    const results = await Promise.all(urls.map(async (u) => {
+        try {
+            await fetch(new URL('models', u.endsWith('/') ? u : `${u}/`), {
+                signal: AbortSignal.timeout(timeoutMs)
+            });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }));
+    return results.some(Boolean);
+}

package/dist/task/auto-orchestrator.d.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+import { type FinalGateFixFn } from './gate-deps.js';
 import { type GateDeps } from './task-gates.js';
 /**
  * Injectable seams so the planner and loop are testable without spawning pi.
@@ -32,6 +33,14 @@ export interface AutoDeps extends GateDeps {
         ok: boolean;
         reason: string;
     }>;
+    /**
+     * Bounded model-driven fix pass for a final-gate FAIL (see final-gate-fix.ts),
+     * offered as the picker's third option. Runs the fix child, applies the
+     * command-shrink guard, and re-runs the gate; the result's `ok` means the gate
+     * now passes. Absent (tests / no fix wiring) → the picker keeps only
+     * Leave-failed / Accept, exactly the pre-autofix behavior.
+     */
+    finalGateFix?: FinalGateFixFn;
 }
 /**
  * Expand any @file references in the feature text by appending each referenced

package/dist/task/auto-orchestrator.js

@@ -27,6 +27,7 @@ import { buildGateDeps } from './gate-deps.js';
 import { runGatesForTask } from './task-gates.js';
 import { gitUnmergedPaths, gitStashRef } from './auto-commit.js';
 import { runFinalIntegrationGate } from './final-gate.js';
+import { classifyFinalGateAnswer, MAX_FINAL_GATE_AUTOFIX, FINAL_LEAVE_LABEL, FINAL_LEAVE_VALUE, FINAL_ACCEPT_LABEL, FINAL_ACCEPT_VALUE, FINAL_AUTOFIX_LABEL, FINAL_AUTOFIX_VALUE } from './final-gate-fix.js';
 import { getConfig } from '../config/config.js';
 // Hard ceiling on clarify questions per feature. The loop is open-ended (it stops
 // when the model emits NONE), but a model that never says NONE would otherwise
@@ -547,7 +548,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 => getConfig().verifyWork ?
-            Promise.resolve(runFinalIntegrationGate(cwd2))
+            runFinalIntegrationGate(cwd2)
             : Promise.resolve({ ok: true, reason: 'disabled' })
     };
 }
@@ -598,32 +599,82 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                 // the gate, so fixing and resuming converges.
                 if (deps.finalGate) {
                     active.ui.notify(`${id}: running final integration gate…`, 'info');
-                    const fin = await deps.finalGate(cwd);
-                    if (!fin.ok) {
+                    // Run-level gate trail on the parent task file — same durable
+                    // auditability contract as the per-task `## gates` records.
+                    const recGate = async (line) => {
+                        try {
+                            await deps.record?.(cwd, id, line);
+                        }
+                        catch {
+                            // recording must never break the gate
+                        }
+                    };
+                    let fin = await deps.finalGate(cwd);
+                    if (!fin.ok)
+                        await recGate(`final-gate: FAIL — ${fin.reason.slice(0, 300)}`);
+                    // Resolution loop: Leave-failed (recommended) / Autofix (bounded,
+                    // model-driven fix pass + gate re-run — run 7's gap: the picker
+                    // had NO automated fix path) / Accept. The user always decides;
+                    // after MAX_FINAL_GATE_AUTOFIX attempts that still FAIL the
+                    // autofix card is withdrawn so the loop cannot run unbounded.
+                    let fixAttempts = 0;
+                    while (!fin.ok) {
+                        const canAutofix = deps.finalGateFix !== undefined && fixAttempts < MAX_FINAL_GATE_AUTOFIX;
                         const question = `Final integration gate FAILED for ${id}.\n\n${fin.reason}\n\n`
                             + 'All tasks are checked off — this is the whole-repo check '
-                            + '(the project’s own test/build/static commands, run unaided).';
+                            + '(the project’s own test/build/static commands, run unaided).'
+                            + (fixAttempts > 0 ?
+                                `\n\nAutofix attempts so far: ${fixAttempts}/${MAX_FINAL_GATE_AUTOFIX}.`
+                                : '');
                         const answer = await new SessionUI(active).ask({
                             localTitle: 'Final integration gate failed — how should pi proceed?',
                             displayQuestion: question,
                             question,
-                            recommended: 'Leave failed — I will fix and /task-auto-resume',
-                            recommended2: 'Accept — complete the run anyway',
+                            recommended: FINAL_LEAVE_LABEL,
+                            recommended2: canAutofix ? FINAL_AUTOFIX_LABEL : FINAL_ACCEPT_LABEL,
                             allowSkip: false,
                             options: [
-                                {
-                                    label: 'Leave failed — I will fix and /task-auto-resume',
-                                    value: 'fail'
-                                },
-                                { label: 'Accept — complete the run anyway', value: 'accept' }
+                                { label: FINAL_LEAVE_LABEL, value: FINAL_LEAVE_VALUE },
+                                ...(canAutofix ?
+                                    [{ label: FINAL_AUTOFIX_LABEL, value: FINAL_AUTOFIX_VALUE }]
+                                    : []),
+                                { label: FINAL_ACCEPT_LABEL, value: FINAL_ACCEPT_VALUE }
                             ]
                         });
-                        if (answer === undefined || !/^accept\b/i.test(answer.trim())) {
-                            await updateTaskFrontMatter(cwd, id, { state: 'failed' });
-                            announceDone(active, `${id} finished all tasks but FAILED the final integration gate — ${fin.reason.slice(0, 200)} — fix and /task-auto-resume (the gate re-runs).`, 'error');
-                            return;
+                        const choice = classifyFinalGateAnswer(answer);
+                        if (choice.action === 'accept') {
+                            await recGate('final-gate: FAIL accepted by user');
+                            active.ui.notify(`${id}: final integration gate FAIL accepted by user — completing.`, 'warning');
+                            break;
+                        }
+                        if (choice.action === 'autofix' && canAutofix) {
+                            fixAttempts += 1;
+                            await recGate(`final-gate: user chose AUTOFIX (attempt ${fixAttempts}/${MAX_FINAL_GATE_AUTOFIX})`);
+                            active.ui.notify(`${id}: final-gate autofix (${fixAttempts}/${MAX_FINAL_GATE_AUTOFIX}) — bounded fix pass, then the gate re-runs…`, 'info');
+                            const seed = choice.guidance ?
+                                `${fin.reason}\n\nUser guidance: ${choice.guidance}`
+                                : fin.reason;
+                            const fix = await deps.finalGateFix(active, cwd, seed);
+                            if (fix.ok) {
+                                await deps.commit(cwd, `FINAL GATE AUTOFIX (${id})`);
+                                await recGate(`final-gate: autofix converged — ${fix.reason.slice(0, 200)}`);
+                                active.ui.notify(`${id}: final integration gate PASSES after autofix — ${fix.reason.slice(0, 140)}`, 'info');
+                                fin = { ok: true, reason: fix.reason };
+                                break;
+                            }
+                            await recGate(`final-gate: autofix attempt ${fixAttempts} failed — ${fix.reason.slice(0, 200)}`);
+                            active.ui.notify(`${id}: final-gate autofix did not converge — ${fix.reason.slice(0, 140)}`, 'warning');
+                            // Work from the FRESH gate failure when the fix pass got
+                            // as far as re-running the gate; otherwise keep the last.
+                            fin = { ok: false, reason: fix.gateReason ?? fin.reason };
+                            continue;
                         }
-                        active.ui.notify(`${id}: final integration gate FAIL accepted by user — completing.`, 'warning');
+                        // Leave failed — the dismissal default, unchanged from the
+                        // two-option picker (an unavailable autofix demotes here too).
+                        await recGate('final-gate: left failed (user)');
+                        await updateTaskFrontMatter(cwd, id, { state: 'failed' });
+                        announceDone(active, `${id} finished all tasks but FAILED the final integration gate — ${fin.reason.slice(0, 200)} — fix and /task-auto-resume (the gate re-runs).`, 'error');
+                        return;
                     }
                 }
                 await updateTaskFrontMatter(cwd, id, { state: 'completed' });

package/dist/task/child-runner.js

@@ -33,7 +33,7 @@ export const MAX_LOOP_RESTARTS = 2; // 3 strikes total (initial attempt + 2 rest
  * provider 5xx that names a real fault) still fails fast: re-spawning against
  * the same request won't fix it, so burning the budget only delays the report.
  */
-const CONNECTION_ERROR_RE = /\b(?:connection error|connection (?:lost|closed|reset|refused|aborted)|econnreset|econnrefused|econnaborted|epipe|etimedout|enetunreach|enetdown|eai_again|socket hang up|fetch failed|network (?:error|timeout)|premature close|request timed out|terminated)\b/i;
+const CONNECTION_ERROR_RE = /\b(?:connection error|connection (?:lost|closed|reset|refused|aborted)|econnreset|econnrefused|econnaborted|epipe|etimedout|enetunreach|enetdown|eai_again|socket hang up|fetch failed|network (?:error|timeout)|premature close|request timed out|terminated|unreachable)\b/i;
 export function isConnectionError(cause) {
     return CONNECTION_ERROR_RE.test(cause);
 }

package/dist/task/enforce-guidelines.d.ts

@@ -89,6 +89,7 @@ export interface EnforceChildResult {
     timedOut?: boolean;
     loopHit?: unknown;
     leakedToolCall?: unknown;
+    stalled?: boolean;
 }
 /**
  * Map the enforcement child's runWorker result to a fatal error message, or null

package/dist/task/enforce-guidelines.js

@@ -191,6 +191,12 @@ export function parseEnforceVerdict(text) {
  * effects don't get re-classified as a user cancel or a crash.
  */
 export function classifyEnforceChildFailure(r) {
+    // Stall-kill must be matched BEFORE `aborted`: the kill sets aborted too,
+    // and mislabeling a dead model backend as a user cancel hides the cause
+    // (mx5 run 7: 64 minutes of silence).
+    if (r.stalled) {
+        return 'model server unreachable — the child produced no output and the model endpoint did not respond';
+    }
     if (r.timedOut)
         return 'enforcement child timed out';
     if (r.loopHit)

package/dist/task/env-notes.d.ts

@@ -0,0 +1,23 @@
+export declare function envNotesFile(cwd: string): string;
+/** The cached notes, one fact per line ('' when none were recorded yet). */
+export declare function readEnvNotes(cwd: string): Promise<string>;
+/**
+ * Pull `ENV-NOTE: <fact>` lines out of a child's answer text. Deduplicated,
+ * length-capped; verdict markers can never match (different prefix).
+ */
+export declare function extractEnvNotes(text: string): string[];
+/**
+ * Append newly discovered facts to the cache, deduplicated against what is
+ * already there (case-insensitive full-line match), keeping the newest
+ * MAX_NOTES. Failures are swallowed — the cache is a sharpener, never a
+ * blocker.
+ */
+export declare function appendEnvNotes(cwd: string, notes: string[]): Promise<void>;
+/**
+ * The prompt block a gate child receives when notes exist. The caveat is
+ * load-bearing: facts save re-discovery time but grant no waiver from the
+ * verify-as-shipped rule.
+ */
+export declare function buildEnvNotesBlock(notes: string): string;
+/** The emit instruction appended to bash-capable gate-child prompts. */
+export declare const ENV_NOTE_EMIT_INSTRUCTION: string;

package/dist/task/env-notes.js

@@ -0,0 +1,121 @@
+/**
+ * env-notes — a per-run cache of ENVIRONMENT FACTS shared across gate children.
+ *
+ * The failure this serves (mx5 run 7, F8): every gate child re-discovers the
+ * same environment facts from scratch — where the DB credentials live, which
+ * services are reachable, which tools are installed — burning minutes of
+ * archaeology per child through the serial model bottleneck.
+ *
+ * Mechanism: children EMIT facts as `ENV-NOTE: <fact>` lines in their answer
+ * text; the HOST parses and appends them to `.pi-tasks/env-notes.md` (children
+ * never write the file — no artifact corruption, host-side dedupe). The file
+ * lives under `.pi-tasks/`, so it survives discardEdits and the git-state
+ * guard, both of which exclude that directory by design.
+ *
+ * SCOPE — facts only, never verdicts, never spec content: an endpoint, a
+ * credential LOCATION, a tool's presence/version, a service's reachability.
+ * And the cache must not become a pre-prepared runway that masks missing
+ * project setup: the verify-as-shipped rule ("any prep you needed IS the
+ * defect") still governs every verdict — the block injected into prompts says
+ * so explicitly. The cache only kills re-discovery time.
+ */
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import { tasksDir } from './task-io.js';
+const ENV_NOTES_FILE = 'env-notes.md';
+/** Cap kept notes so a chatty run cannot grow the prompt block unboundedly. */
+const MAX_NOTES = 40;
+/** A single fact is one line; anything longer is prose, not a fact. */
+const MAX_NOTE_LENGTH = 240;
+export function envNotesFile(cwd) {
+    return path.join(tasksDir(cwd), ENV_NOTES_FILE);
+}
+/** The cached notes, one fact per line ('' when none were recorded yet). */
+export async function readEnvNotes(cwd) {
+    try {
+        return (await fsp.readFile(envNotesFile(cwd), 'utf8')).trim();
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Pull `ENV-NOTE: <fact>` lines out of a child's answer text. Deduplicated,
+ * length-capped; verdict markers can never match (different prefix).
+ */
+export function extractEnvNotes(text) {
+    const notes = [];
+    const seen = new Set();
+    for (const m of text.matchAll(/^[ \t]*ENV-NOTE:[ \t]*(.+)$/gm)) {
+        const note = m[1].trim();
+        if (note.length === 0 || note.length > MAX_NOTE_LENGTH)
+            continue;
+        const key = note.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        notes.push(note);
+    }
+    return notes;
+}
+/**
+ * Append newly discovered facts to the cache, deduplicated against what is
+ * already there (case-insensitive full-line match), keeping the newest
+ * MAX_NOTES. Failures are swallowed — the cache is a sharpener, never a
+ * blocker.
+ */
+export async function appendEnvNotes(cwd, notes) {
+    if (notes.length === 0)
+        return;
+    try {
+        const existing = (await readEnvNotes(cwd)).split('\n').filter(l => l.trim().length > 0);
+        const seen = new Set(existing.map(l => l.trim().toLowerCase()));
+        const merged = [...existing];
+        for (const note of notes) {
+            const key = note.trim().toLowerCase();
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            merged.push(note.trim());
+        }
+        const kept = merged.slice(-MAX_NOTES);
+        await fsp.mkdir(tasksDir(cwd), { recursive: true });
+        await fsp.writeFile(envNotesFile(cwd), kept.join('\n') + '\n', 'utf8');
+    }
+    catch {
+        // best-effort cache
+    }
+}
+/**
+ * The prompt block a gate child receives when notes exist. The caveat is
+ * load-bearing: facts save re-discovery time but grant no waiver from the
+ * verify-as-shipped rule.
+ */
+export function buildEnvNotesBlock(notes) {
+    if (notes.trim().length === 0)
+        return '';
+    return [
+        'KNOWN ENVIRONMENT FACTS — discovered by earlier verification passes in this run',
+        '(informational, may be stale):',
+        ...notes
+            .trim()
+            .split('\n')
+            .map(n => `- ${n}`),
+        'These facts only save you re-discovery time (where credentials/config live, which',
+        'tools are installed, which services are reachable). They are NOT a license to',
+        'prepare or repair the run: the verify-as-shipped rules below still govern the',
+        'verdict — if the project needs something its own committed files do not provide,',
+        'that remains the defect no matter what is listed here.',
+        ''
+    ].join('\n');
+}
+/** The emit instruction appended to bash-capable gate-child prompts. */
+export const ENV_NOTE_EMIT_INSTRUCTION = [
+    'ENVIRONMENT FACTS — share what you discover: when you establish a durable fact about',
+    'THIS MACHINE or the project environment (a service reachable/absent at an address, where',
+    'credentials/config live, a tool or runtime present/missing and its version), emit a line',
+    '  ENV-NOTE: <one-line fact>',
+    'anywhere in your answer, one per fact. Facts about the ENVIRONMENT only — never task',
+    'verdicts, never spec content, never code judgments. These are cached for later',
+    'verification passes in this run so they do not re-discover the same things.'
+].join('\n');

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

@@ -0,0 +1,91 @@
+/** 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. */
+export declare const FINAL_FIX_TOOLS = "read,edit,bash";
+/**
+ * How many fix passes the user may launch from the picker before the option is
+ * withdrawn (mirrors the per-task MAX_AUTO_AUTOFIX budget). Each attempt is a
+ * full model child plus a full gate re-run — after this many that still FAIL,
+ * only Leave-failed / Accept remain so a person breaks the loop.
+ */
+export declare const MAX_FINAL_GATE_AUTOFIX = 3;
+/** Picker labels/values. Classification accepts the value token, the label, or
+ *  free text (→ autofix guidance), same contract as the per-task resolution. */
+export declare const FINAL_LEAVE_VALUE = "fail";
+export declare const FINAL_ACCEPT_VALUE = "accept";
+export declare const FINAL_AUTOFIX_VALUE = "autofix";
+export declare const FINAL_LEAVE_LABEL = "Leave failed \u2014 I will fix and /task-auto-resume";
+export declare const FINAL_ACCEPT_LABEL = "Accept \u2014 complete the run anyway";
+export declare const FINAL_AUTOFIX_LABEL = "Autofix \u2014 run a bounded fix pass and re-run the gate";
+export interface FinalGateChoice {
+    /** What the user decided. 'leave' = leave the run failed (also the dismissal
+     *  default — identical to the pre-autofix behavior). */
+    action: 'leave' | 'accept' | 'autofix';
+    /** Free-text guidance typed instead of picking a card; folded into the fix
+     *  child's failure seed. Only set with 'autofix'. */
+    guidance?: string;
+}
+/**
+ * Map a final-gate picker answer to an action. Dismissal (undefined/empty) and
+ * an explicit leave stay "leave" — exactly what the two-option picker did.
+ * Free text becomes autofix guidance, mirroring classifyResolutionAnswer; the
+ * caller demotes autofix back to "leave" when the option was not offered.
+ */
+export declare function classifyFinalGateAnswer(answer: string | undefined): FinalGateChoice;
+/**
+ * The gate's fail reason always carries the failing command in backticks
+ * (`` `bun run test` exited 1 — … `` / ``static checks: `make lint` exited 2``).
+ * Extract it for reporting; the shrink guard itself compares the FULL
+ * discovered-command sets, so a reason this cannot parse still guards.
+ */
+export declare function extractFailingCommand(reason: string): string | null;
+/**
+ * Build the fix child's prompt. Generic by construction: the only project facts
+ * in it are the gate's own failure text — the command comes from the project's
+ * discovered manifest, never from a hardcoded ecosystem.
+ */
+export declare function buildFinalFixPrompt(failReason: string): string;
+/**
+ * Parse the child's final marker. Last match wins (the model reasons before
+ * concluding and bash output can echo the words). No marker → treated as DONE:
+ * the gate re-run is the arbiter either way, so a missing marker only skips the
+ * early-out on a self-declared BLOCKED.
+ */
+export declare function parseFinalFixMarker(text: string): {
+    blocked: boolean;
+    note?: string;
+};
+export interface FinalFixResult {
+    /** true → the fix child ran AND the re-run gate passed. */
+    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;
+}
+export interface FinalFixDeps {
+    cwd: string;
+    signal?: AbortSignal;
+    /** The gate's FAIL reason (command + exit code + output tail), plus any
+     *  user-typed guidance the caller folded in. */
+    failReason: string;
+    /** Run the fix child; same closure shape the other gate children use. */
+    runChild: (tools: string, prompt: string, signal?: AbortSignal) => Promise<string>;
+    /** Re-run the final integration gate — the only arbiter of convergence. */
+    gate: (cwd: string) => Promise<{
+        ok: boolean;
+        reason: string;
+    }>;
+    /** Labels of every currently-discoverable gate command (static + integration),
+     *  for the shrink guard. Pure discovery — nothing is executed. */
+    discoverLabels: (cwd: string) => string[];
+    /** Discard the fix child's working-tree edits (shrink-guard trip only). Absent
+     *  → the violation is still rejected, edits are left for inspection. */
+    discard?: (cwd: string) => Promise<void>;
+}
+/**
+ * Run one bounded final-gate fix attempt: snapshot discovery → child → shrink
+ * guard → gate re-run. Never throws for an outcome; only a user cancel inside
+ * runChild propagates (the caller's USER_CANCELLED path handles it).
+ */
+export declare function runFinalGateAutofix(deps: FinalFixDeps): Promise<FinalFixResult>;