@mjasnikovs/pi-task 0.14.14 → 0.14.16

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

@@ -3,6 +3,7 @@ import type { RunSingleTaskResult } from './orchestrator.js';
 import { type CommitResult } from './auto-commit.js';
 import { type EnforceOutcome } from './enforce-guidelines.js';
 import { type VerifyOutcome } from './verify-work.js';
+import { type ResolutionOutcome } from './verify-resolution.js';
 /**
  * Injectable seams so the planner and loop are testable without spawning pi.
  * `runChild` is used by planAuto; `runTask` is used by runAutoLoop.
@@ -16,6 +17,9 @@ export interface AutoDeps {
         onStart?: (taskId: string) => void | Promise<void>;
         /** Scope fence naming the sibling steps, forwarded into refine. */
         planContext?: string;
+        /** Verify-FAIL autofix re-attempt: prepended to the delivered spec as
+         *  a RE-ATTEMPT banner so the re-run fixes that specific failure. */
+        fixInstruction?: string;
     }) => Promise<RunSingleTaskResult>;
     /** Snapshot the working tree into one commit after a task passes. */
     commit: (cwd: string, message: string) => Promise<CommitResult>;
@@ -40,6 +44,15 @@ export interface AutoDeps {
      * it). Needs the inner taskId to read that task's spec.
      */
     verify?: (ctx: ExtensionCommandContext, cwd: string, taskTitle: string, taskId: string) => Promise<VerifyOutcome>;
+    /**
+     * After a verify FAIL, research whether to recommend AUTOFIX (re-do the work)
+     * or ACCEPT (the gate misjudged a good artifact) — read-only, same local
+     * model. Only sets which card the picker tints RECOMMENDED; the user always
+     * makes the final call. Optional: absent in tests or when verify is off, in
+     * which case the loop defaults the recommendation to AUTOFIX. Needs the inner
+     * taskId (to read the spec) and the gate's failure reason.
+     */
+    recommend?: (ctx: ExtensionCommandContext, cwd: string, taskTitle: string, taskId: string, failReason: string) => Promise<ResolutionOutcome>;
 }
 /**
  * Expand any @file references in the feature text by appending each referenced

package/dist/task/auto-orchestrator.js

@@ -17,6 +17,7 @@ import { writeTaskFile, readTaskFile, updateTaskFrontMatter, taskFilePath, tasks
 import { gitCommitAll } from './auto-commit.js';
 import { runGuidelineEnforcement, classifyEnforceChildFailure } from './enforce-guidelines.js';
 import { runWorkVerification, extractSpecForVerification } from './verify-work.js';
+import { researchResolution, resolutionOptions, classifyResolutionAnswer } from './verify-resolution.js';
 import { runWorker } from '../workers/pi-worker-core.js';
 import { findPhantomImports, rewritePhantomSpecifiers } from '../workers/phantom-imports.js';
 import { runPhaseChild, prependHint, formatLoopHint, USER_CANCELLED } from './child-runner.js';
@@ -344,6 +345,61 @@ function defaultDeps(ctx, cwd, signal, title) {
     let lastLine;
     let contextUsage;
     const parentContextWindow = getParentContextWindow(ctx);
+    // Shared runner for the per-task GATE children (verify + post-FAIL recommend).
+    // Both are read-only passes of the same local model that must run to
+    // completion: unguarded (no wall-clock timeout, exact-match loop guard only,
+    // path-revisit disabled because re-running the same check is the job), with a
+    // status widget and a per-gate debug log. Returns the closure
+    // runWorkVerification / researchResolution expect as `runChild`.
+    const makeGateChild = (gateCtx, cwd2, taskTitle, kind, logFile) => async (tools, prompt, sig) => {
+        lastLine = undefined;
+        contextUsage = undefined;
+        const startedAt = Date.now();
+        const logPath = path.join(tasksDir(cwd2), logFile);
+        const log = (msg) => {
+            void fsp.appendFile(logPath, `${new Date().toISOString()} ${msg}\n`).catch(() => { });
+        };
+        log(`=== ${kind} start: ${taskTitle} ===`);
+        const stopLoader = startAutoLoader(gateCtx, () => ({
+            title: taskTitle,
+            kind,
+            step: kind,
+            stepNum: 1,
+            stepTotal: 1,
+            startedAt,
+            lastLine,
+            contextUsage
+        }));
+        try {
+            const r = await runWorker({
+                prompt,
+                cwd: cwd2,
+                signal: sig,
+                tools,
+                timeoutMs: 0,
+                loop: { pathThreshold: Number.POSITIVE_INFINITY },
+                onLine: line => {
+                    lastLine = line;
+                    log(line);
+                },
+                onContextUsage: snapshot => {
+                    contextUsage = resolveContextUsage(snapshot, contextUsage, parentContextWindow);
+                }
+            });
+            if (r.loopHit) {
+                log(`=== ${kind} LOOP WARNING — ${formatLoopHint(r.loopHit)} ===`);
+                gateCtx.ui.notify(`${taskTitle}: ${kind} worker looped past the nudges — continuing (not blocked).`, 'warning');
+            }
+            const failure = classifyEnforceChildFailure(r);
+            log(failure ? `=== ${kind} end: FAIL — ${failure} ===` : `=== ${kind} end: ok ===`);
+            if (failure)
+                throw new Error(failure);
+            return r.text;
+        }
+        finally {
+            stopLoader();
+        }
+    };
     const phaseDeps = {
         cwd,
         taskId: '',
@@ -384,7 +440,8 @@ function defaultDeps(ctx, cwd, signal, title) {
             waitForImplementation: true,
             resumeId: opts?.resumeId,
             onStart: opts?.onStart,
-            planContext: opts?.planContext
+            planContext: opts?.planContext,
+            fixInstruction: opts?.fixInstruction
         }),
         commit: (cwd2, message) => getConfig().autoCommit ?
             gitCommitAll(cwd2, message, signal)
@@ -502,70 +559,54 @@ function defaultDeps(ctx, cwd, signal, title) {
                 cwd: cwd2,
                 signal,
                 spec,
-                // Same unguarded child as enforce: no wall-clock timeout (a build
-                // or test suite legitimately takes minutes) and exact-match loop
-                // guard only. Re-running the same VERIFY command is the job, so the
-                // path-revisit heuristic is disabled; only a literally-identical
-                // call repeated past threshold trips, and that warns rather than
-                // blocks.
-                runChild: async (tools, prompt, sig) => {
-                    lastLine = undefined;
-                    contextUsage = undefined;
-                    const startedAt = Date.now();
-                    const verifyLogPath = path.join(tasksDir(cwd2), 'verify-debug.log');
-                    const logVerify = (msg) => {
-                        void fsp
-                            .appendFile(verifyLogPath, `${new Date().toISOString()} ${msg}\n`)
-                            .catch(() => { });
-                    };
-                    logVerify(`=== verify start: ${taskTitle} ===`);
-                    const stopLoader = startAutoLoader(verifyCtx, () => ({
-                        title: taskTitle,
-                        kind: 'verify',
-                        step: 'verify',
-                        stepNum: 1,
-                        stepTotal: 1,
-                        startedAt,
-                        lastLine,
-                        contextUsage
-                    }));
-                    try {
-                        const r = await runWorker({
-                            prompt,
-                            cwd: cwd2,
-                            signal: sig,
-                            tools,
-                            timeoutMs: 0,
-                            loop: { pathThreshold: Number.POSITIVE_INFINITY },
-                            onLine: line => {
-                                lastLine = line;
-                                logVerify(line);
-                            },
-                            onContextUsage: snapshot => {
-                                contextUsage = resolveContextUsage(snapshot, contextUsage, parentContextWindow);
-                            }
-                        });
-                        if (r.loopHit) {
-                            logVerify(`=== verify LOOP WARNING — ${formatLoopHint(r.loopHit)} ===`);
-                            verifyCtx.ui.notify(`${taskTitle}: verify worker looped past the nudges — continuing (not blocked).`, 'warning');
-                        }
-                        const failure = classifyEnforceChildFailure(r);
-                        logVerify(failure ?
-                            `=== verify end: FAIL — ${failure} ===`
-                            : '=== verify end: verdict captured ===');
-                        if (failure)
-                            throw new Error(failure);
-                        return r.text;
-                    }
-                    finally {
-                        stopLoader();
-                    }
-                }
+                runChild: makeGateChild(verifyCtx, cwd2, taskTitle, 'verify', 'verify-debug.log')
+            });
+        },
+        recommend: async (recCtx, cwd2, taskTitle, taskId, failReason) => {
+            // Read the same composed spec the verify gate judged against, so the
+            // recommendation reasons over the real contract (a missing spec is
+            // unusual here — verify already ran — but degrade to the bare title).
+            let spec;
+            try {
+                const { body } = await readTaskFile(cwd2, taskId);
+                spec = extractSpecForVerification(body) ?? taskTitle;
+            }
+            catch {
+                spec = taskTitle;
+            }
+            return researchResolution({
+                cwd: cwd2,
+                signal,
+                spec,
+                failReason,
+                runChild: makeGateChild(recCtx, cwd2, taskTitle, 'recommend', 'verify-debug.log')
             });
         }
     };
 }
 // ─── Loop ────────────────────────────────────────────────────────────────────
+/**
+ * Show the boxed two-choice picker after a verify FAIL and return what the user
+ * decided. The model-recommended card is placed first so the renderer tints it
+ * green; the user ALWAYS makes the final call (there is no auto-pick). Mirrors the
+ * clarify/grill dialog: the same SessionUI.ask races the local boxed picker
+ * against a remote answer, with the two actions also surfaced as remote buttons.
+ */
+async function askVerifyResolution(ctx, title, failReason, rec) {
+    const options = resolutionOptions(rec.recommend);
+    const question = `Verification FAILED for "${title}".\n\n${failReason}\n\n`
+        + `Recommended: ${rec.recommend.toUpperCase()} — ${rec.rationale}`;
+    const answer = await new SessionUI(ctx).ask({
+        localTitle: 'Verification failed — how should pi proceed?',
+        displayQuestion: question,
+        question,
+        recommended: options[0].label,
+        recommended2: options[1].label,
+        allowSkip: false,
+        options
+    });
+    return classifyResolutionAnswer(answer);
+}
 let cancelRequested = false;
 let autoRunning = false;
 export function requestAutoCancel() {
@@ -678,12 +719,64 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
             // task has no composed spec to verify against.
             if (deps.verify) {
                 active.ui.notify(`${id}: verifying "${next.title}"…`, 'info');
-                const verified = await deps.verify(active, cwd, next.title, res.taskId);
-                if (!verified.ok) {
-                    await updateTaskFrontMatter(cwd, id, { state: 'failed' });
-                    announceDone(active, `${id} stopped at "${next.title}" — ${verified.reason ?? 'did not verify'} — fix and run /task-auto-resume.`, 'error');
-                    return;
+                let verified = await deps.verify(active, cwd, next.title, res.taskId);
+                // A FAIL no longer dead-stops the run. The user is offered a boxed
+                // two-choice picker — AUTOFIX (re-run the implementation turn against
+                // the failure, then re-verify) or ACCEPT (the gate misjudged a good
+                // artifact; override and proceed). A read-only research pass picks
+                // which card is recommended, but the USER always decides — there is
+                // no attempt cap: AUTOFIX loops straight back to the gate as many
+                // times as the user keeps choosing it. The run only leaves the loop
+                // when the work verifies, the user ACCEPTs, or the user dismisses
+                // the picker (which pauses the run, resumable).
+                while (!verified.ok) {
+                    const failReason = verified.reason ?? 'did not verify';
+                    const rec = deps.recommend ?
+                        await deps.recommend(active, cwd, next.title, res.taskId, failReason)
+                        : { recommend: 'autofix', rationale: failReason };
+                    const choice = await askVerifyResolution(active, next.title, failReason, rec);
+                    if (choice.action === 'cancel') {
+                        await updateTaskFrontMatter(cwd, id, { state: 'failed' });
+                        announceDone(active, `${id} paused at "${next.title}" — verification failed and you dismissed the choice; resume with /task-auto-resume.`, 'warning');
+                        return;
+                    }
+                    if (choice.action === 'accept') {
+                        active.ui.notify(`${id}: accepted "${next.title}" despite verify FAIL (${failReason.slice(0, 120)}) — proceeding.`, 'warning');
+                        break;
+                    }
+                    // AUTOFIX: re-run the implementation turn with the failure (and
+                    // any typed guidance) prepended as a RE-ATTEMPT banner, then
+                    // re-verify — looping back to the gate. No cap: the user decides
+                    // when to stop (by accepting or dismissing the next picker).
+                    active.ui.notify(`${id}: autofixing "${next.title}"…`, 'info');
+                    const fixInstruction = choice.guidance ?
+                        `${failReason}\n\nUser guidance: ${choice.guidance}`
+                        : failReason;
+                    const fixRes = await deps.runTask(active, cwd, next.title, {
+                        resumeId: res.taskId,
+                        planContext: buildScopeFence(entries.map(e => e.title), next.index),
+                        fixInstruction
+                    });
+                    active = fixRes.ctx ?? active;
+                    if (fixRes.sessionCancelled) {
+                        announceDone(active, `${id} paused — could not start a session for autofix. Run /task-auto-resume to retry.`, 'warning');
+                        return;
+                    }
+                    if (fixRes.interrupted) {
+                        announceDone(active, `${id} paused at "${next.title}" — resume with /task-auto-resume.`, 'warning');
+                        return;
+                    }
+                    if (!fixRes.ok) {
+                        await updateTaskFrontMatter(cwd, id, { state: 'failed' });
+                        const why = fixRes.reason ? ` — ${fixRes.reason.slice(0, 160)}` : '';
+                        announceDone(active, `${id} stopped at "${next.title}"${why} — fix and run /task-auto-resume.`, 'error');
+                        return;
+                    }
+                    // Resume reuses the same inner task id, so res.taskId is stable.
+                    verified = await deps.verify(active, cwd, next.title, res.taskId);
                 }
+                // Loop exited because the work verified OR the user accepted the
+                // artifact — either way fall through to check-off/commit/enforce.
             }
             // res.ok === true means runner.run() completed, so res.taskId is the
             // allocated TASK_NNNN id (never empty here). checkOffTask tolerates an

package/dist/task/orchestrator.d.ts

@@ -27,6 +27,7 @@ export declare class TaskRunner {
     private readonly _sendSpec;
     private readonly _onStart;
     private readonly _planContext;
+    private readonly _fixInstruction;
     private readonly _abort;
     private readonly _startedAt;
     private readonly _widgetState;
@@ -42,7 +43,7 @@ export declare class TaskRunner {
      */
     private readonly _timings;
     private _currentPhaseChildren;
-    constructor(ctx: ExtensionCommandContext, cwd: string, rawPrompt: string, resumeId?: string, sendSpec?: (spec: string) => Promise<void>, spawnFn?: SpawnFn, onStart?: (taskId: string) => void | Promise<void>, planContext?: string);
+    constructor(ctx: ExtensionCommandContext, cwd: string, rawPrompt: string, resumeId?: string, sendSpec?: (spec: string) => Promise<void>, spawnFn?: SpawnFn, onStart?: (taskId: string) => void | Promise<void>, planContext?: string, fixInstruction?: string);
     get taskId(): string;
     get signal(): AbortSignal;
     /** Return the current widget state, or null if not started. */
@@ -102,6 +103,15 @@ export interface RunSingleTaskOptions {
      * a bare /task leaves it undefined and the refine prompt is unchanged.
      */
     planContext?: string;
+    /**
+     * Marks this run as a verify-FAIL re-attempt. When set (only by /task-auto's
+     * autofix path, with `resumeId` pointing at the already-composed task), the
+     * text — the verify gate's failure reason plus any guidance the user typed —
+     * is prepended to the delivered spec as a RE-ATTEMPT banner, so the
+     * implementer fixes the specific failure and re-satisfies the VERIFY block
+     * rather than blindly redoing the task. Empty/undefined on a first attempt.
+     */
+    fixInstruction?: string;
 }
 export interface RunSingleTaskResult {
     taskId: string;

package/dist/task/orchestrator.js

@@ -53,6 +53,7 @@ export class TaskRunner {
     _sendSpec;
     _onStart;
     _planContext;
+    _fixInstruction;
     _abort = new AbortController();
     _startedAt;
     _widgetState;
@@ -68,7 +69,7 @@ export class TaskRunner {
      */
     _timings = [];
     _currentPhaseChildren = null;
-    constructor(ctx, cwd, rawPrompt, resumeId, sendSpec, spawnFn, onStart, planContext) {
+    constructor(ctx, cwd, rawPrompt, resumeId, sendSpec, spawnFn, onStart, planContext, fixInstruction) {
         this._ctx = ctx;
         this._cwd = cwd;
         this._rawPrompt = rawPrompt;
@@ -76,6 +77,7 @@ export class TaskRunner {
         this._sendSpec = sendSpec;
         this._onStart = onStart;
         this._planContext = planContext;
+        this._fixInstruction = fixInstruction;
         this._startedAt = Date.now();
         // We'll populate id/title/phase lazily in run().
         // Placeholder — real values set in run().
@@ -288,11 +290,25 @@ export class TaskRunner {
      */
     _specForDelivery() {
         const phantoms = findDeliveryPhantoms(this._pc.spec, this._cwd);
-        const banner = formatApiOverrideBanner(phantoms);
-        if (!banner)
-            return this._pc.spec;
-        this._deps.logDebug?.(`impl-handoff API override banner prepended for: ${phantoms.map(p => p.spec).join(', ')}`);
-        return `${banner}\n\n${this._pc.spec}`;
+        const apiBanner = formatApiOverrideBanner(phantoms);
+        if (apiBanner) {
+            this._deps.logDebug?.(`impl-handoff API override banner prepended for: ${phantoms.map(p => p.spec).join(', ')}`);
+        }
+        // A verify-FAIL re-attempt: the work was already implemented once and the
+        // verification gate rejected it. Lead with WHY so the model fixes that
+        // specific failure and re-satisfies the VERIFY block, rather than redoing
+        // the task from scratch (or repeating the same mistake).
+        let fixBanner = '';
+        if (this._fixInstruction && this._fixInstruction.trim().length > 0) {
+            this._deps.logDebug?.('impl-handoff RE-ATTEMPT banner prepended (verify FAIL fix)');
+            fixBanner =
+                'RE-ATTEMPT — your previous implementation of this task FAILED verification.\n'
+                    + "Fix the cause below, then make the spec's VERIFY block pass. Do NOT start over;\n"
+                    + 'change only what is needed to resolve the failure.\n\n'
+                    + `VERIFICATION FAILURE:\n${this._fixInstruction.trim()}`;
+        }
+        const banners = [fixBanner, apiBanner].filter(b => b && b.length > 0).join('\n\n');
+        return banners ? `${banners}\n\n${this._pc.spec}` : this._pc.spec;
     }
 }
 /** Dialog copy for the post-interrupt steering prompt. */
@@ -394,7 +410,7 @@ export async function runSingleTask(ctx, cwd, rawPrompt, opts = {}) {
                     if (!interrupted)
                         implError = implementationError(newCtx);
                 }
-            }, opts.spawnFn, opts.onStart, opts.planContext);
+            }, opts.spawnFn, opts.onStart, opts.planContext, opts.fixInstruction);
             await runner.run();
             taskId = runner.taskId;
         }

package/dist/task/verify-resolution.d.ts

@@ -0,0 +1,75 @@
+/** Same read-only contract as the verify pass: observe, never edit. */
+declare const RESOLUTION_TOOLS = "read,bash";
+/** Which card the picker tints RECOMMENDED. */
+export type ResolutionRecommendation = 'autofix' | 'accept';
+export interface ResolutionOutcome {
+    /** The card to recommend. Defaults to 'autofix' (conservative: re-do, don't
+     *  bless) when the research could not run or emitted no verdict. */
+    recommend: ResolutionRecommendation;
+    /** Short, human-readable rationale shown under the picker. Always set. */
+    rationale: string;
+}
+/**
+ * Build the resolution research child's prompt. Pure, so the wording is
+ * unit-tested without spawning pi. The contract: investigate the real workspace
+ * and end on exactly one RESOLUTION verdict line.
+ */
+export declare function buildResolutionPrompt(spec: string, failReason: string): string;
+/**
+ * Parse the child's recommendation. Scans for the LAST
+ * `VERIFY-RESOLUTION: AUTOFIX|ACCEPT` marker (the model reasons before
+ * concluding, and bash output may echo these words, so a distinct token and
+ * last-match-wins both matter).
+ *
+ * No marker → recommend AUTOFIX (conservative: re-do rather than bless), with a
+ * rationale that says the research was inconclusive.
+ */
+export declare function parseResolutionVerdict(text: string): ResolutionOutcome;
+export declare const ACCEPT_VALUE = "accept";
+export declare const AUTOFIX_VALUE = "autofix";
+export declare const ACCEPT_LABEL = "Accept \u2014 keep the artifact as-is and continue";
+export declare const AUTOFIX_LABEL = "Autofix \u2014 re-run the task to fix it, then verify again";
+export interface ResolutionChoice {
+    /** What the user decided. 'cancel' = dismissed the picker (pause, resumable). */
+    action: 'accept' | 'autofix' | 'cancel';
+    /** Free-text guidance the user typed instead of picking a card. Folded into
+     *  the autofix instruction so a re-run can act on it. Only set with 'autofix'. */
+    guidance?: string;
+}
+/**
+ * The two cards for the picker, with the model-recommended one FIRST so the boxed
+ * renderer tints it green (it marks index 0 as recommended). Values are the bare
+ * tokens; remote buttons use the labels — {@link classifyResolutionAnswer}
+ * accepts both.
+ */
+export declare function resolutionOptions(recommend: ResolutionRecommendation): {
+    label: string;
+    value: string;
+    recommended: boolean;
+}[];
+/**
+ * Map a picker answer to an action. Handles the card value tokens, the remote
+ * button labels, an empty/undefined dismissal (cancel), and arbitrary free text
+ * typed via the fallback — which becomes an AUTOFIX with that text as guidance
+ * (the user is steering the re-run rather than blessing the artifact).
+ */
+export declare function classifyResolutionAnswer(answer: string | undefined): ResolutionChoice;
+export interface ResolutionDeps {
+    cwd: string;
+    signal?: AbortSignal;
+    /** The composed spec the task was verified against. */
+    spec: string;
+    /** The verify gate's FAIL reason (VerifyOutcome.reason). */
+    failReason: string;
+    /** Runs the research child and returns its assistant text. Injected so the
+     *  orchestrator wires the real worker and tests use a fake. */
+    runChild: (tools: string, prompt: string, signal?: AbortSignal) => Promise<string>;
+}
+/**
+ * Research a verify FAIL and return which action to recommend. Never throws
+ * (except a user cancel, which propagates so the loop's USER_CANCELLED handler
+ * reports a clean "cancelled — resume"). A child crash defaults to recommending
+ * AUTOFIX — the picker is still shown, only the default tint changes.
+ */
+export declare function researchResolution(deps: ResolutionDeps): Promise<ResolutionOutcome>;
+export { RESOLUTION_TOOLS };

package/dist/task/verify-resolution.js

@@ -0,0 +1,190 @@
+/**
+ * Verify-FAIL resolution research for /task-auto.
+ *
+ * When the work-verification gate (verify-work.ts) returns a FAIL, the run no
+ * longer dead-stops with "fix and run /task-auto-resume". Instead the user is
+ * shown a boxed two-choice picker:
+ *
+ *   • Autofix   — re-run the task's implementation turn against the failure, then
+ *                 re-enter the verify gate.
+ *   • Accept    — treat the artifact as good, override the gate, and proceed
+ *                 (check off + commit) exactly as a PASS would.
+ *
+ * The user ALWAYS makes the final call. This module only computes which of the
+ * two cards is tinted RECOMMENDED, by handing the FAIL reason + the task spec to
+ * a fresh read+bash child of the SAME local model and letting it INVESTIGATE the
+ * real workspace: is the FAIL a genuine defect in the work (→ recommend AUTOFIX),
+ * or a false alarm / an acceptable artifact the gate misjudged (→ recommend
+ * ACCEPT)? This is the same shape of judgement a human reviewer makes when a CI
+ * check is red — sometimes the code is broken, sometimes the check is wrong.
+ *
+ * Tools: `read` + `bash` only — identical to the verify pass. The recommendation
+ * observes; it never edits. (Autofix, when chosen, is what edits — and it goes
+ * through the full implementation runner, not this pass.) A read-only research
+ * step can never itself change the tree it is judging.
+ *
+ * The verdict is advisory: a missing/garbled verdict defaults to recommending
+ * AUTOFIX, the conservative choice (re-do the work rather than bless it). The
+ * picker is shown regardless; this only moves the green tint.
+ */
+import { USER_CANCELLED } from './child-runner.js';
+/** Same read-only contract as the verify pass: observe, never edit. */
+const RESOLUTION_TOOLS = 'read,bash';
+/**
+ * Build the resolution research child's prompt. Pure, so the wording is
+ * unit-tested without spawning pi. The contract: investigate the real workspace
+ * and end on exactly one RESOLUTION verdict line.
+ */
+export function buildResolutionPrompt(spec, failReason) {
+    return [
+        "A strict verification gate just FAILED an AI coding agent's task and the",
+        'run paused. You are the reviewer who decides what to recommend next. The',
+        'agent will NOT act on your verdict automatically — a human picks the final',
+        'action — but your recommendation sets the default, so be right.',
+        '',
+        'You have a `read` tool and a `bash` tool — nothing else. Investigate the',
+        'REAL files in this workspace; you CANNOT edit or create anything.',
+        '',
+        'THE TASK SPEC (its ACCEPTANCE criteria and VERIFY block were the contract):',
+        spec.trim(),
+        '',
+        "THE GATE'S FAILURE REASON:",
+        failReason.trim(),
+        '',
+        'Your job: decide which of these two is the right next step.',
+        '  AUTOFIX — the work is genuinely wrong: a real defect, a missing or broken',
+        '            artifact, behaviour that truly contradicts an ACCEPTANCE criterion.',
+        '            The task should be re-done to fix it.',
+        '  ACCEPT  — the work is actually fine: the gate misjudged it (a false alarm,',
+        '            an over-strict or factually-wrong check, an environment gap, a',
+        '            difference in FORM that still satisfies the intent). The artifact',
+        '            is good as-is and the FAIL should be overridden.',
+        '',
+        'CRITICAL — judge by FUNCTION, not by literal text. Verification gates (and',
+        'even the spec wording above) are frequently OVER-LITERAL. A FAIL that',
+        'complains that something is written in the wrong FORM, SHAPE, SYNTAX, SECTION',
+        'or WORDING — rather than that it BEHAVES wrong — is very often a false alarm:',
+        'the artifact reaches the same result through an equivalent form. The spec',
+        'wording is intent, not a string to diff against. Example: a config value',
+        'written as a nested table header vs. a dotted key are the same value to the',
+        'tool that reads it; demanding one exact spelling is a false alarm if the tool',
+        'accepts both and the intended setting is present.',
+        '',
+        'How to decide:',
+        '1. Do NOT decide from the FAIL text alone. Read the actual file(s) it points',
+        '   at. When the check is runnable, RUN the real tool/command that consumes',
+        '   that artifact (the build, the parser, the test) with `bash` and observe',
+        '   whether it actually works. Reality overrules both the gate and the spec',
+        '   wording.',
+        '2. If the failure is about HOW something is written and you confirm the',
+        '   artifact still FUNCTIONALLY does what the ACCEPTANCE intends (the tool',
+        '   accepts it, the value/element is present and effective, the build runs) —',
+        "   that is ACCEPT, even though the text does not literally match the gate's or",
+        "   the spec's phrasing.",
+        '3. If an intended element is genuinely ABSENT or the artifact actually fails',
+        '   when you run it — that is AUTOFIX. When you cannot positively confirm the',
+        '   artifact works, recommend AUTOFIX: re-doing the work is the safe default;',
+        '   blessing broken work is the failure mode this whole gate exists to stop.',
+        '',
+        'When done, output EXACTLY ONE of these as the final line:',
+        '  VERIFY-RESOLUTION: AUTOFIX <one sentence why the work must be re-done>',
+        '  VERIFY-RESOLUTION: ACCEPT <one sentence why the artifact is good as-is>',
+        'Output the verdict line verbatim — it is parsed mechanically.'
+    ].join('\n');
+}
+/**
+ * Parse the child's recommendation. Scans for the LAST
+ * `VERIFY-RESOLUTION: AUTOFIX|ACCEPT` marker (the model reasons before
+ * concluding, and bash output may echo these words, so a distinct token and
+ * last-match-wins both matter).
+ *
+ * No marker → recommend AUTOFIX (conservative: re-do rather than bless), with a
+ * rationale that says the research was inconclusive.
+ */
+export function parseResolutionVerdict(text) {
+    const re = /VERIFY-RESOLUTION:\s*(AUTOFIX|ACCEPT)\b[ \t]*(.*)/gi;
+    let last = null;
+    for (let m = re.exec(text); m !== null; m = re.exec(text))
+        last = m;
+    if (!last) {
+        return {
+            recommend: 'autofix',
+            rationale: 'research inconclusive — defaulting to re-doing the work'
+        };
+    }
+    const recommend = last[1].toUpperCase() === 'ACCEPT' ? 'accept' : 'autofix';
+    const rationale = last[2].trim()
+        || (recommend === 'accept' ? 'artifact judged acceptable' : 'work judged to need fixing');
+    return { recommend, rationale };
+}
+// ─── Picker plumbing ─────────────────────────────────────────────────────────
+//
+// The user ALWAYS makes the final call on a verify FAIL. These pure helpers shape
+// the boxed two-choice picker (verify-resolution → SessionUI.ask in the loop) and
+// classify whatever comes back — a card value, a remote button label, or free
+// text typed via the "type a different answer" fallback — so the orchestration
+// stays mechanical and unit-tested.
+export const ACCEPT_VALUE = 'accept';
+export const AUTOFIX_VALUE = 'autofix';
+export const ACCEPT_LABEL = 'Accept — keep the artifact as-is and continue';
+export const AUTOFIX_LABEL = 'Autofix — re-run the task to fix it, then verify again';
+/**
+ * The two cards for the picker, with the model-recommended one FIRST so the boxed
+ * renderer tints it green (it marks index 0 as recommended). Values are the bare
+ * tokens; remote buttons use the labels — {@link classifyResolutionAnswer}
+ * accepts both.
+ */
+export function resolutionOptions(recommend) {
+    const accept = { label: ACCEPT_LABEL, value: ACCEPT_VALUE };
+    const autofix = { label: AUTOFIX_LABEL, value: AUTOFIX_VALUE };
+    return recommend === 'accept' ?
+        [
+            { ...accept, recommended: true },
+            { ...autofix, recommended: false }
+        ]
+        : [
+            { ...autofix, recommended: true },
+            { ...accept, recommended: false }
+        ];
+}
+/**
+ * Map a picker answer to an action. Handles the card value tokens, the remote
+ * button labels, an empty/undefined dismissal (cancel), and arbitrary free text
+ * typed via the fallback — which becomes an AUTOFIX with that text as guidance
+ * (the user is steering the re-run rather than blessing the artifact).
+ */
+export function classifyResolutionAnswer(answer) {
+    if (answer === undefined)
+        return { action: 'cancel' };
+    const t = answer.trim();
+    if (t.length === 0)
+        return { action: 'cancel' };
+    if (t === ACCEPT_VALUE || /^accept\b/i.test(t))
+        return { action: 'accept' };
+    if (t === AUTOFIX_VALUE || /^autofix\b/i.test(t))
+        return { action: 'autofix' };
+    // Free-text override → re-run the task with the typed text as fix guidance.
+    return { action: 'autofix', guidance: t };
+}
+/**
+ * Research a verify FAIL and return which action to recommend. Never throws
+ * (except a user cancel, which propagates so the loop's USER_CANCELLED handler
+ * reports a clean "cancelled — resume"). A child crash defaults to recommending
+ * AUTOFIX — the picker is still shown, only the default tint changes.
+ */
+export async function researchResolution(deps) {
+    let text;
+    try {
+        text = await deps.runChild(RESOLUTION_TOOLS, buildResolutionPrompt(deps.spec, deps.failReason), deps.signal);
+    }
+    catch (err) {
+        if (err instanceof Error && err.message === USER_CANCELLED)
+            throw err;
+        return {
+            recommend: 'autofix',
+            rationale: 'resolution research could not run — defaulting to re-doing the work'
+        };
+    }
+    return parseResolutionVerdict(text);
+}
+export { RESOLUTION_TOOLS };

package/dist/task/widget.d.ts

@@ -52,8 +52,9 @@ export interface AutoLoaderState {
     /** Which /task-auto stage this loader is for. Defaults to 'planning' (the
      *  numbered clarify/decompose steps); 'enforce' is the per-task guideline
      *  pass and 'verify' is the per-task work-verification pass, neither of which
-     *  has step numbering. */
-    kind?: 'planning' | 'enforce' | 'verify';
+     *  has step numbering. 'recommend' is the read-only research that picks the
+     *  recommended action after a verify FAIL. */
+    kind?: 'planning' | 'enforce' | 'verify' | 'recommend';
 }
 export declare function buildAutoLoaderLines(s: AutoLoaderState, theme?: WidgetTheme): string[];
 /**

package/dist/task/widget.js

@@ -123,7 +123,8 @@ export function buildAutoLoaderLines(s, theme) {
     const head = `/task-auto · ${s.title}`;
     let detail = s.kind === 'enforce' ? `enforcing guidelines · ${elapsed}`
         : s.kind === 'verify' ? `verifying work · ${elapsed}`
-            : `planning ${s.stepNum}/${s.stepTotal} ${s.step} · ${elapsed}`;
+            : s.kind === 'recommend' ? `assessing the failure · ${elapsed}`
+                : `planning ${s.stepNum}/${s.stepTotal} ${s.step} · ${elapsed}`;
     if (s.contextUsage) {
         const ctxDetail = formatContextDetail(s.contextUsage, theme);
         if (ctxDetail)

package/dist/workers/brave-warning.d.ts

@@ -0,0 +1,10 @@
+/**
+ * One-line startup hint shown when no Brave Search key is configured.
+ *
+ * pi-task's web-search worker needs BRAVE_SEARCH_API_KEY (or BRAVE_API_KEY).
+ * When neither is set we surface a single, unobtrusive widget line on session
+ * start so the user knows search is disabled — it never blocks work and clears
+ * itself on the first interaction (any keystroke).
+ */
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+export declare function registerBraveKeyWarning(pi: ExtensionAPI): void;

package/dist/workers/brave-warning.js

@@ -0,0 +1,46 @@
+/**
+ * One-line startup hint shown when no Brave Search key is configured.
+ *
+ * pi-task's web-search worker needs BRAVE_SEARCH_API_KEY (or BRAVE_API_KEY).
+ * When neither is set we surface a single, unobtrusive widget line on session
+ * start so the user knows search is disabled — it never blocks work and clears
+ * itself on the first interaction (any keystroke).
+ */
+const WIDGET_KEY = 'pi-task-brave-warning';
+const WARNING = '⚠ pi-task: BRAVE_SEARCH_API_KEY not set — web search is disabled. '
+    + 'Get a free key at https://api.search.brave.com/app/keys';
+/** Mirrors the lookup in search-core so the hint matches what the worker reads. */
+function hasBraveKey() {
+    return Boolean(process.env.BRAVE_SEARCH_API_KEY ?? process.env.BRAVE_API_KEY);
+}
+export function registerBraveKeyWarning(pi) {
+    pi.on('session_start', (_event, ctx) => {
+        // Terminal-only hint: needs an interactive TUI to render and to catch the
+        // keystroke that dismisses it. Skip when a key is already present.
+        if (ctx.mode !== 'tui' || hasBraveKey())
+            return;
+        let unsubscribe = null;
+        const clear = () => {
+            try {
+                ctx.ui.setWidget(WIDGET_KEY, undefined);
+            }
+            catch {
+                /* stale ctx after a session switch — nothing to clear */
+            }
+            unsubscribe?.();
+            unsubscribe = null;
+        };
+        try {
+            ctx.ui.setWidget(WIDGET_KEY, [ctx.ui.theme.fg('warning', WARNING)]);
+        }
+        catch {
+            return;
+        }
+        // Disappear on any interaction — the first raw keystroke clears it.
+        // Returning undefined leaves the input untouched (we only observe it).
+        unsubscribe = ctx.ui.onTerminalInput(() => {
+            clear();
+            return undefined;
+        });
+    });
+}

package/dist/workers/index.js

@@ -2,9 +2,11 @@ import { registerPiWorker } from './pi-worker.js';
 import { registerPiWorkerSearch } from './pi-worker-search.js';
 import { registerPiWorkerFetch } from './pi-worker-fetch.js';
 import { registerPiWorkerDocs } from './pi-worker-docs.js';
+import { registerBraveKeyWarning } from './brave-warning.js';
 export function registerWorkers(pi) {
     registerPiWorker(pi);
     registerPiWorkerSearch(pi);
     registerPiWorkerFetch(pi);
     registerPiWorkerDocs(pi);
+    registerBraveKeyWarning(pi);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.14.14",
+    "version": "0.14.16",
     "description": "Deterministic spec-orchestration for local models, with a bundled real-time remote web view and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",