@mjasnikovs/pi-task 0.17.24 → 0.17.25

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

@@ -20,6 +20,9 @@ export type SpawnFn = (command: string, args: ReadonlyArray<string>, options: {
     cwd: string;
     shell: boolean;
     stdio: ['ignore' | 'pipe', 'pipe', 'pipe'];
+    /** Set only when the invocation needs env overrides (e.g. GIT_INDEX_FILE);
+     *  absent → the child inherits this process's environment as before. */
+    env?: NodeJS.ProcessEnv;
 }) => ProcLike;
 export interface ChildResult {
     stdout: string;
@@ -113,9 +116,11 @@ export declare function runChild(spawn: SpawnFn, invocation: {
     command: string;
     args: ReadonlyArray<string>;
     stdin?: string;
+    env?: NodeJS.ProcessEnv;
 }, cwd: string, signal: AbortSignal | undefined, opts?: RunChildOptions): Promise<ChildResult>;
 export declare function runChildDefault(invocation: {
     command: string;
     args: ReadonlyArray<string>;
+    env?: NodeJS.ProcessEnv;
 }, cwd: string, signal: AbortSignal | undefined, opts?: RunChildOptions, spawnFn?: SpawnFn): Promise<ChildResult>;
 export declare function summarizeToolArgs(toolName: string, args: unknown): string;

package/dist/shared/child-process.js

@@ -178,7 +178,8 @@ export function runChild(spawn, invocation, cwd, signal, opts) {
         const proc = spawn(invocation.command, invocation.args, {
             cwd,
             shell: false,
-            stdio: [usesStdin ? 'pipe' : 'ignore', 'pipe', 'pipe']
+            stdio: [usesStdin ? 'pipe' : 'ignore', 'pipe', 'pipe'],
+            ...(invocation.env ? { env: invocation.env } : {})
         });
         if (usesStdin) {
             // pi reads the prompt from stdin and waits for EOF, so write then end.

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

@@ -29,6 +29,21 @@ export declare function git(cwd: string, args: string[], signal: AbortSignal | u
     exitCode: number;
     aborted: boolean;
 }>;
+/**
+ * Paths with unmerged index entries (an in-progress merge conflict), deduped.
+ * Empty outside a git repo or on any git error — this is a GUARD input, and a
+ * guard that cannot conclude must not block.
+ *
+ * Why it exists (mx5 run 6): a stale `git stash pop` mid-task left two paths UU;
+ * every later commit was doomed, three verify passes ran against a conflicted
+ * tree, and — worse — a blind `git add -A` on that index would have silently
+ * "resolved" the conflict with whatever happened to be on disk.
+ */
+export declare function gitUnmergedPaths(cwd: string, signal?: AbortSignal, spawnFn?: SpawnFn): Promise<string[]>;
+/** Sha of `refs/stash`, or null when there is no stash (or not a git repo). Used
+ *  to detect a stash created (or consumed) during a task and left behind — the
+ *  exact landmine that detonated mx5 run 6 two days after it was pushed. */
+export declare function gitStashRef(cwd: string, signal?: AbortSignal, spawnFn?: SpawnFn): Promise<string | null>;
 /**
  * Stage everything (`git add -A`) and commit it with `message`. Honors
  * .gitignore via git itself. Never throws — failures surface as

package/dist/task/auto-commit.js

@@ -31,6 +31,39 @@ export async function git(cwd, args, signal, spawnFn) {
     const r = await runChildDefault({ command: 'git', args }, cwd, signal, { mode: 'text' }, spawnFn);
     return { stdout: r.stdout, stderr: r.stderr, exitCode: r.exitCode, aborted: r.aborted };
 }
+/**
+ * Paths with unmerged index entries (an in-progress merge conflict), deduped.
+ * Empty outside a git repo or on any git error — this is a GUARD input, and a
+ * guard that cannot conclude must not block.
+ *
+ * Why it exists (mx5 run 6): a stale `git stash pop` mid-task left two paths UU;
+ * every later commit was doomed, three verify passes ran against a conflicted
+ * tree, and — worse — a blind `git add -A` on that index would have silently
+ * "resolved" the conflict with whatever happened to be on disk.
+ */
+export async function gitUnmergedPaths(cwd, signal, spawnFn) {
+    const r = await git(cwd, ['ls-files', '-u'], signal, spawnFn);
+    if (r.exitCode !== 0)
+        return [];
+    const out = [];
+    for (const line of r.stdout.split('\n')) {
+        // `<mode> <sha> <stage>\t<path>`
+        const tab = line.indexOf('\t');
+        if (tab === -1)
+            continue;
+        const p = line.slice(tab + 1).trim();
+        if (p.length > 0 && !out.includes(p))
+            out.push(p);
+    }
+    return out;
+}
+/** Sha of `refs/stash`, or null when there is no stash (or not a git repo). Used
+ *  to detect a stash created (or consumed) during a task and left behind — the
+ *  exact landmine that detonated mx5 run 6 two days after it was pushed. */
+export async function gitStashRef(cwd, signal, spawnFn) {
+    const r = await git(cwd, ['rev-parse', '-q', '--verify', 'refs/stash'], signal, spawnFn);
+    return r.exitCode === 0 ? r.stdout.trim() : null;
+}
 /**
  * Stage everything (`git add -A`) and commit it with `message`. Honors
  * .gitignore via git itself. Never throws — failures surface as
@@ -44,21 +77,32 @@ export async function gitCommitAll(cwd, message, signal, spawnFn) {
     if (inside.exitCode !== 0 || inside.stdout.trim() !== 'true') {
         return { committed: false, reason: 'not a git repository' };
     }
-    // 2. Stage all working-tree changes (new, modified, deleted).
+    // 2. REFUSE on an unmerged index: `git add -A` would silently "resolve" the
+    //    conflict by staging whatever is on disk, and the commit that followed
+    //    would bless a half-merged tree. Surface it instead — this state needs a
+    //    human (or the loop's own loud stop), not a snapshot.
+    const unmerged = await gitUnmergedPaths(cwd, signal, spawnFn);
+    if (unmerged.length > 0) {
+        return {
+            committed: false,
+            reason: `git commit blocked: unresolved merge conflict (${unmerged.slice(0, 3).join(', ')}${unmerged.length > 3 ? `, +${unmerged.length - 3} more` : ''})`
+        };
+    }
+    // 3. Stage all working-tree changes (new, modified, deleted).
     const add = await git(cwd, ['add', '-A'], signal, spawnFn);
     if (add.aborted)
         return { committed: false, reason: 'cancelled' };
     if (add.exitCode !== 0) {
         return { committed: false, reason: `git add failed: ${firstLine(add.stderr)}` };
     }
-    // 3. Anything staged? `git diff --cached --quiet` exits 0 when the index
+    // 4. Anything staged? `git diff --cached --quiet` exits 0 when the index
     //    matches HEAD (nothing to commit), 1 when there are staged changes.
     const diff = await git(cwd, ['diff', '--cached', '--quiet'], signal, spawnFn);
     if (diff.aborted)
         return { committed: false, reason: 'cancelled' };
     if (diff.exitCode === 0)
         return { committed: false, reason: 'nothing to commit' };
-    // 4. Commit. A failure here is usually missing user.name/user.email config —
+    // 5. Commit. A failure here is usually missing user.name/user.email config —
     //    retry once with a self-supplied identity rather than losing the snapshot
     //    (and with it enforce + every differential guard) for the whole run.
     const commit = await git(cwd, ['commit', '-m', message], signal, spawnFn);

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

@@ -8,6 +8,30 @@ import { type GateDeps } from './task-gates.js';
  */
 export interface AutoDeps extends GateDeps {
     runChild: (name: string, tools: string, prompt: string) => Promise<string>;
+    /**
+     * Paths with unmerged index entries (an in-progress merge conflict). The loop
+     * refuses to START a task on a conflicted tree — mx5 run 6 ran a full impl turn
+     * plus three verifies against one, with every commit doomed from the outset.
+     * Absent (tests) → treated as clean.
+     */
+    unmergedPaths?: (cwd: string) => Promise<string[]>;
+    /**
+     * Sha of refs/stash or null. Compared around each task so a stash pushed (or
+     * consumed) during the task and left behind is called out — an orphan stash is
+     * exactly the landmine that detonated as an unresolvable conflict in run 6.
+     * Absent (tests) → the check is skipped.
+     */
+    stashRef?: (cwd: string) => Promise<string | null>;
+    /**
+     * Whole-repo FINAL integration gate, run once when every task is checked off
+     * and BEFORE the run is declared complete (see final-gate.ts): the project's
+     * own static checks plus its own test/build commands, unaided. Absent (tests /
+     * gate off) → the run completes as before.
+     */
+    finalGate?: (cwd: string) => Promise<{
+        ok: boolean;
+        reason: string;
+    }>;
 }
 /**
  * Expand any @file references in the feature text by appending each referenced

package/dist/task/auto-orchestrator.js

@@ -7,7 +7,7 @@
  */
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
-import { gateRunTask } from './orchestrator.js';
+import { gateRunTask, markResumable } from './orchestrator.js';
 import { parseClarifyList, parseAutoAnswer, autoAnswerHasTag, deriveTitle } from './parsers.js';
 import { renderInlineMarkdown, stripInlineMarkdown } from './inline-markdown.js';
 import { AUTO_CLARIFY_PROMPT, AUTO_DECOMPOSE_PROMPT, DECOMPOSE_COVERAGE_PROMPT } from './auto-prompts.js';
@@ -25,6 +25,9 @@ import { startAutoLoader } from './widget.js';
 import { getParentContextWindow, resolveContextUsage } from './context-usage.js';
 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 { 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
 // barrage the user — the real mx5 run asked 10, several of them redundant.
@@ -537,7 +540,15 @@ function defaultDeps(ctx, cwd, signal, title) {
                 stopLoader();
             }
         },
-        ...buildGateDeps({ signal, parentContextWindow, runTask: gateRunTask })
+        ...buildGateDeps({ signal, parentContextWindow, runTask: gateRunTask }),
+        // Loop-level repo integrity + run-end gate glue (see AutoDeps docs).
+        unmergedPaths: cwd2 => gitUnmergedPaths(cwd2, signal),
+        stashRef: cwd2 => gitStashRef(cwd2, signal),
+        // 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))
+            : Promise.resolve({ ok: true, reason: 'disabled' })
     };
 }
 // ─── Loop ────────────────────────────────────────────────────────────────────
@@ -578,10 +589,58 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
             const entries = parseTaskList(body);
             const next = entries.find(e => !e.done);
             if (!next) {
+                // FINAL INTEGRATION GATE: every task passed its own per-slice gates,
+                // but per-slice green has shipped a dead app twice (mx5 runs 3 & 5:
+                // statics clean, every protected route 500ing). Run the project's
+                // OWN whole-repo commands once, unaided, before declaring the run
+                // complete. On a FAIL the user decides: accept (complete anyway) or
+                // leave the run failed — a resume re-enters this branch and re-runs
+                // 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) {
+                        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).';
+                        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',
+                            allowSkip: false,
+                            options: [
+                                {
+                                    label: 'Leave failed — I will fix and /task-auto-resume',
+                                    value: 'fail'
+                                },
+                                { label: 'Accept — complete the run anyway', value: 'accept' }
+                            ]
+                        });
+                        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;
+                        }
+                        active.ui.notify(`${id}: final integration gate FAIL accepted by user — completing.`, 'warning');
+                    }
+                }
                 await updateTaskFrontMatter(cwd, id, { state: 'completed' });
                 announceDone(active, `${id} complete — all ${entries.length} tasks done.`, 'info');
                 return;
             }
+            // REFUSE to start on a conflicted tree: an unmerged index dooms every
+            // commit ahead and a `git add -A` would silently mis-resolve it. mx5
+            // run 6 burned a full impl turn + three verify passes exactly here.
+            const unmerged = deps.unmergedPaths ? await deps.unmergedPaths(cwd) : [];
+            if (unmerged.length > 0) {
+                await updateTaskFrontMatter(cwd, id, { state: 'failed' });
+                announceDone(active, `${id} stopped before "${next.title}" — the repository has unresolved merge conflicts `
+                    + `(${unmerged.slice(0, 3).join(', ')}${unmerged.length > 3 ? `, +${unmerged.length - 3} more` : ''}). `
+                    + 'Resolve them (git status), then /task-auto-resume.', 'error');
+                return;
+            }
             active.ui.notify(`${id}: task ${next.index + 1}/${entries.length} — ${next.title}`, 'info');
             // If this entry already has a stamped inner id, it was started in a
             // previous (interrupted) run — resume it from its saved phase rather
@@ -612,6 +671,10 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
             if (checkpoint.committed) {
                 active.ui.notify(`${id}: checkpointed uncommitted work before "${next.title}".`, 'info');
             }
+            // Stash ref before the task: compared after the gates so a stash pushed
+            // during the task (impl model or any child) and left behind is called
+            // out instead of silently waiting to detonate in a later task.
+            const stashBefore = deps.stashRef ? await deps.stashRef(cwd) : undefined;
             const res = await deps.runTask(active, cwd, next.title, {
                 resumeId,
                 // Fence this step against re-expanding the whole referenced spec:
@@ -634,10 +697,15 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                 // this task's spec to finish it. (A plain ESC that the user
                 // follows with steering text never reaches here — that loops on
                 // the same task inside runSingleTask until a turn completes.)
+                await markResumable(cwd, res.taskId);
                 announceDone(active, `${id} paused at "${next.title}" — resume with /task-auto-resume.`, 'warning');
                 return;
             }
             if (!res.ok) {
+                // Demote the INNER task file too: it reads `completed` from
+                // spec-handoff, and leaving it that way is how a failed run's task
+                // file claimed success in the run 6 audit.
+                await markResumable(cwd, res.taskId);
                 await updateTaskFrontMatter(cwd, id, { state: 'failed' });
                 // res.reason is set when the implementation turn itself died
                 // (e.g. a context-overflow 400) — surface it so the real cause
@@ -668,6 +736,7 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
             });
             active = gate.ctx;
             if (gate.kind === 'paused') {
+                await markResumable(cwd, res.taskId);
                 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;
@@ -677,16 +746,26 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                 return;
             }
             if (gate.kind === 'interrupted') {
+                await markResumable(cwd, res.taskId);
                 announceDone(active, `${id} paused at "${next.title}" — resume with /task-auto-resume.`, 'warning');
                 return;
             }
             if (gate.kind === 'failed') {
+                await markResumable(cwd, res.taskId);
                 await updateTaskFrontMatter(cwd, id, { state: 'failed' });
                 const why = gate.reason ? ` — ${gate.reason.slice(0, 160)}` : '';
                 announceDone(active, `${id} stopped at "${next.title}"${why} — fix and run /task-auto-resume.`, 'error');
                 return;
             }
-            // gate.kind === 'done' → fall through to the next task.
+            // gate.kind === 'done' → fall through to the next task, after checking
+            // no landmine stash was left behind by anything that ran in between.
+            if (deps.stashRef && stashBefore !== undefined) {
+                const stashAfter = await deps.stashRef(cwd);
+                if (stashAfter !== stashBefore) {
+                    active.ui.notify(`${id}: the git stash stack changed during "${next.title}" and was left that way — `
+                        + 'inspect `git stash list`; an orphan stash later pops as an unresolvable conflict.', 'warning');
+                }
+            }
         }
     }
     catch (err) {

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

@@ -0,0 +1,23 @@
+import { type HealthCommand } from './repo-health-check.js';
+export interface FinalGateOutcome {
+    /** true → statics and every runnable integration command passed (or nothing to run). */
+    ok: boolean;
+    /** On a fail: the exact command, its exit code, and the tail of its output. */
+    reason: string;
+}
+/**
+ * The project's OWN whole-repo integration commands (test, then build — test
+ * first because it is the richer signal and the more common script). First
+ * manifest that exists wins, mirroring discoverHealthCommands. Empty means
+ * "nothing to run" — the static half may still gate.
+ */
+export declare function discoverIntegrationCommands(cwd: string): {
+    ecosystem: string | null;
+    cmds: HealthCommand[];
+};
+/**
+ * Run the final gate: static analysis first, then the discovered integration
+ * commands, whole-repo, verbatim, unaided. Deterministic and synchronous under
+ * the hood (callers wrap in Promise.resolve). First real failure wins.
+ */
+export declare function runFinalIntegrationGate(cwd: string, timeoutMs?: number): FinalGateOutcome;

package/dist/task/final-gate.js

@@ -0,0 +1,143 @@
+/**
+ * final-gate — the run-level integration gate /task-auto runs ONCE, after every
+ * task is checked off and before the run is declared complete.
+ *
+ * The failure this closes (mx5 runs 3 and 5, validated): every existing gate is
+ * per-task/per-slice, so a run can finish with each slice individually blessed
+ * while the ASSEMBLED project is dead — statics green yet every protected route
+ * 500ing, 105/174 tests failing across slices, later tasks breaking files earlier
+ * tasks verified. Per-task repo-health closes the static half; nothing ever ran
+ * the project's own test/build commands against the finished whole.
+ *
+ * Like repo-health-check (whose discovery style this mirrors), it is deterministic
+ * — no model, no per-file narrowing, no "not my task" gray area. It discovers the
+ * project's OWN integration commands (the ones a fresh checkout / CI would run)
+ * and lets their REAL exit codes decide:
+ *
+ *   - static analysis first (runRepoHealthCheck — cheap, precise), then
+ *   - the project's own `test` and `build` commands, run verbatim and unaided.
+ *
+ * Environment-gap safety, same contract as repo-health-check: a command that
+ * CANNOT run (ENOENT, exit 127 = command-not-found inside the script chain, or a
+ * timeout) is an environment problem, not a code fault — it is SKIPPED, never
+ * failed. Only a command that actually ran and exited non-zero fails the gate,
+ * and the reason carries the tail of its real output so the user (and a resume
+ * fix) can act on it. A test suite that needs a database will fail here when the
+ * database is genuinely reachable-but-mis-wired — which is exactly the class the
+ * per-task gates kept excusing — and the caller puts a human on the decision
+ * (accept / leave failed), so a genuine external gap can still be overridden.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import * as path from 'node:path';
+import { runRepoHealthCheck } from './repo-health-check.js';
+function packageScripts(cwd) {
+    try {
+        const j = JSON.parse(readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+        return j.scripts ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+function makeHasTarget(cwd, target) {
+    try {
+        const mk = readFileSync(path.join(cwd, 'Makefile'), 'utf8');
+        return new RegExp(`^${target}:`, 'm').test(mk);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The project's OWN whole-repo integration commands (test, then build — test
+ * first because it is the richer signal and the more common script). First
+ * manifest that exists wins, mirroring discoverHealthCommands. Empty means
+ * "nothing to run" — the static half may still gate.
+ */
+export function discoverIntegrationCommands(cwd) {
+    if (existsSync(path.join(cwd, 'package.json'))) {
+        const s = packageScripts(cwd);
+        const cmds = [];
+        for (const name of ['test', 'build']) {
+            if (s[name])
+                cmds.push(['bun', ['run', name]]);
+        }
+        return { ecosystem: 'package.json', cmds };
+    }
+    if (existsSync(path.join(cwd, 'Makefile'))) {
+        const cmds = [];
+        for (const target of ['test', 'build']) {
+            if (makeHasTarget(cwd, target))
+                cmds.push(['make', [target]]);
+        }
+        return { ecosystem: 'Makefile', cmds };
+    }
+    if (existsSync(path.join(cwd, 'Cargo.toml'))) {
+        return {
+            ecosystem: 'Cargo.toml',
+            cmds: [
+                ['cargo', ['test', '--quiet']],
+                ['cargo', ['build', '--quiet']]
+            ]
+        };
+    }
+    if (existsSync(path.join(cwd, 'go.mod'))) {
+        return {
+            ecosystem: 'go.mod',
+            cmds: [
+                ['go', ['test', './...']],
+                ['go', ['build', './...']]
+            ]
+        };
+    }
+    if (existsSync(path.join(cwd, 'pyproject.toml'))) {
+        return { ecosystem: 'pyproject.toml', cmds: [['pytest', ['-q']]] };
+    }
+    return { ecosystem: null, cmds: [] };
+}
+/** Last ~`limit` chars of the command's combined output, one line, for the reason. */
+function outputTail(stdout, stderr, limit = 400) {
+    const combined = `${stdout}\n${stderr}`.trim();
+    if (combined.length === 0)
+        return '';
+    const tail = combined.slice(-limit).replace(/\s+/g, ' ').trim();
+    return combined.length > limit ? `…${tail}` : tail;
+}
+/**
+ * Run the final gate: static analysis first, then the discovered integration
+ * commands, whole-repo, verbatim, unaided. Deterministic and synchronous under
+ * the hood (callers wrap in Promise.resolve). First real failure wins.
+ */
+export function runFinalIntegrationGate(cwd, timeoutMs = 900_000) {
+    const stat = runRepoHealthCheck(cwd);
+    if (!stat.ok)
+        return { ok: false, reason: `static checks: ${stat.reason}` };
+    const { ecosystem, cmds } = discoverIntegrationCommands(cwd);
+    if (!ecosystem || cmds.length === 0) {
+        return { ok: true, reason: 'no integration command found (statics passed)' };
+    }
+    const ran = [];
+    for (const [bin, args] of cmds) {
+        const label = `${bin} ${args.join(' ')}`;
+        const r = spawnSync(bin, args, { cwd, encoding: 'utf8', timeout: timeoutMs });
+        // Tool missing, timeout, or command-not-found inside the script chain →
+        // environment gap, not a code fault; skip (same contract as repo-health).
+        if (r.error || r.status === null || r.status === 127)
+            continue;
+        if (r.status !== 0) {
+            const tail = outputTail(r.stdout ?? '', r.stderr ?? '');
+            return {
+                ok: false,
+                reason: `\`${label}\` exited ${r.status}${tail ? ` — ${tail}` : ''}`
+            };
+        }
+        ran.push(label);
+    }
+    return {
+        ok: true,
+        reason: ran.length > 0 ?
+            `statics + ${ran.map(c => `\`${c}\``).join(', ')} passed`
+            : 'statics passed (integration commands not runnable here)'
+    };
+}

package/dist/task/gate-deps.js

@@ -23,6 +23,7 @@ import { runRepoHealthCheck } from './repo-health-check.js';
 import { researchResolution } from './verify-resolution.js';
 import { findSubstitutionSuspects } from './substitution-probe.js';
 import { runBoundedLintFix } from './lint-fix.js';
+import { captureGitState, reconcileGitState } from './git-state-guard.js';
 import { runWorker } from '../workers/pi-worker-core.js';
 import { formatLoopHint } from './child-runner.js';
 import { getConfig } from '../config/config.js';
@@ -83,6 +84,10 @@ export function buildGateDeps(params) {
     // output line and context usage, exactly like the single-task phase widget.
     let lastLine;
     let contextUsage;
+    // What the git-state guard had to restore after the MOST RECENT verify/recommend
+    // child run (see git-state-guard.ts). runWorkVerification reads this through its
+    // mutationCheck dep to discard a verdict computed on a mutated tree.
+    let lastGuardReconcile = null;
     // 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
@@ -92,12 +97,20 @@ export function buildGateDeps(params) {
     const makeGateChild = (gateCtx, cwd2, taskTitle, kind, logFile) => async (tools, prompt, sig) => {
         lastLine = undefined;
         contextUsage = undefined;
+        lastGuardReconcile = null;
         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} ===`);
+        // GIT-STATE GUARD: these children are read-only BY CONTRACT, but the
+        // contract is prompt-level and the live model breaks it (mx5 run 6: the
+        // verify child `git stash`ed the task's uncommitted work and never popped
+        // — the impl was destroyed and the orphan stash detonated 2 days later).
+        // Snapshot before, deterministically restore after; lint-fix is excluded
+        // because editing is its job (it carries its own revert guard).
+        const guardSnapshot = kind === 'verify' || kind === 'recommend' ? await captureGitState(cwd2, sig) : null;
         const stopLoader = startAutoLoader(gateCtx, () => ({
             title: taskTitle,
             kind,
@@ -109,21 +122,36 @@ export function buildGateDeps(params) {
             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);
+            let r;
+            try {
+                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);
+                    }
+                });
+            }
+            finally {
+                // Restore whatever the child moved BEFORE any verdict/failure is
+                // acted on — a crashed child must not skip the restore either.
+                if (guardSnapshot) {
+                    const rec = await reconcileGitState(cwd2, guardSnapshot, sig);
+                    lastGuardReconcile = rec;
+                    if (rec.mutated) {
+                        log(`=== ${kind} GIT-STATE GUARD — child mutated repo state; restored: ${rec.actions.join('; ')} ===`);
+                        gateCtx.ui.notify(`${taskTitle}: ${kind} child mutated repo state — restored (${rec.actions.join('; ').slice(0, 140)}).`, 'warning');
+                    }
                 }
-            });
+            }
             if (r.loopHit) {
                 log(`=== ${kind} LOOP WARNING — ${formatLoopHint(r.loopHit)} ===`);
                 gateCtx.ui.notify(`${taskTitle}: ${kind} worker looped past the nudges — continuing (not blocked).`, 'warning');
@@ -251,7 +279,13 @@ export function buildGateDeps(params) {
                 // Deterministic self-verification probe: test files the task itself
                 // authored/changed become prompt-level findings mandating the child
                 // to drive the real artifact before trusting their green result.
-                probe: () => collectChangedFiles(cwd2, signal).then(findSubstitutionSuspects)
+                probe: () => collectChangedFiles(cwd2, signal).then(findSubstitutionSuspects),
+                // Git-state guard result of the most recent child run: a verdict
+                // computed on a tree the child itself mutated is discarded (the
+                // guard already restored the state — see git-state-guard.ts).
+                mutationCheck: () => lastGuardReconcile?.mutated ?
+                    { mutated: true, detail: lastGuardReconcile.actions.join('; ') }
+                    : { mutated: false, detail: '' }
             });
         },
         lintFix: (fixCtx, cwd2, taskTitle, failReason) => runBoundedLintFix({

package/dist/task/git-state-guard.d.ts

@@ -0,0 +1,44 @@
+import { type SpawnFn } from '../shared/child-process.js';
+export interface GitStateSnapshot {
+    /** false → not a usable git worktree; the guard is disabled for this run. */
+    ok: boolean;
+    headSha: string;
+    /** Symbolic ref ("refs/heads/main") when HEAD is on a branch, else null (detached). */
+    branchRef: string | null;
+    /** Sha of refs/stash, or null when there is no stash. */
+    stashSha: string | null;
+    /** Tree object capturing the worktree content (tracked + untracked, minus .pi-tasks). */
+    treeSha: string | null;
+}
+export interface ReconcileResult {
+    /** true → the child moved repo state; every detected move was restored. */
+    mutated: boolean;
+    /** Human-readable restore actions, for the debug log / notify / gate trail. */
+    actions: string[];
+}
+/** Capture the repo state a gate child must leave untouched. */
+export declare function captureGitState(cwd: string, signal?: AbortSignal, spawnFn?: SpawnFn): Promise<GitStateSnapshot>;
+/**
+ * Compare the repo state against a pre-run snapshot and deterministically undo
+ * whatever a gate child moved. Ordering matters:
+ *
+ *   1. HEAD first — a child parked on another commit must be back on the original
+ *      ref before the worktree comparison/restore makes sense.
+ *   2. Worktree content from the snapshot TREE (not from any stash the child may
+ *      have pushed — the snapshot is the authoritative "as the child found it").
+ *   3. Child-pushed stash entries are dropped LAST, once the work they swallowed
+ *      is already restored — this is exactly the orphan that detonated mx5 run 6.
+ *
+ * Never throws; failures degrade to actions[] lines so the caller can log them.
+ */
+export declare function reconcileGitState(cwd: string, before: GitStateSnapshot, signal?: AbortSignal, spawnFn?: SpawnFn): Promise<ReconcileResult>;
+/**
+ * Convenience wrapper for gate call-sites: run `fn` between a capture and a
+ * reconcile, and hand back both the result and what (if anything) had to be
+ * restored. `fn` errors propagate AFTER the reconcile runs — a crashed child must
+ * not skip the restore.
+ */
+export declare function withGitStateGuard<T>(cwd: string, fn: () => Promise<T>, signal?: AbortSignal, spawnFn?: SpawnFn): Promise<{
+    result: T;
+    reconcile: ReconcileResult;
+}>;

package/dist/task/git-state-guard.js

@@ -0,0 +1,240 @@
+/**
+ * git-state-guard — deterministic repo-state snapshot/reconcile around the
+ * read-only gate children (verify, recommend).
+ *
+ * The failure this closes (proven twice on mx5): those children hold a `read,bash`
+ * contract whose "never modify the tree" clause is prompt-level only, and the live
+ * local model breaks it. Run 6's verify child ran `git stash; git checkout HEAD~1;
+ * tsc; git checkout HEAD` with NO pop — the task's whole uncommitted implementation
+ * vanished into a stash, the verify judged an empty tree (a full re-implementation
+ * was burned), and the orphaned stash detonated two days later when a later impl
+ * turn popped it onto a 14-commits-newer HEAD (unresolvable UU conflict, the
+ * /task-auto checklist reverted to a stale state). The same child has been observed
+ * running `eslint --fix .` mid-verification and ad-hoc DDL against the test DB.
+ *
+ * Prompt rules are evidence-insufficient for this class (FROZEN-CONTRACT framing
+ * A/B'd 0–1/5 compliance), so this is a capability-shaped fix: snapshot the repo
+ * state BEFORE the child runs, and afterwards deterministically restore anything
+ * it moved — no model in the loop.
+ *
+ * What is captured / reconciled:
+ *   - HEAD (sha + symbolic branch ref): a child that checked out another commit
+ *     and never came back is checked back out.
+ *   - The WORKTREE CONTENT as a git tree object, built through a temporary index
+ *     (`read-tree --empty` + `add -A` + `write-tree`, excluding .pi-tasks — the
+ *     gate's own debug logs land there DURING the run). This snapshots tracked
+ *     *and* untracked (non-ignored) files without touching the real index or the
+ *     stash. Restoration re-materialises every changed/deleted file from the
+ *     snapshot tree and deletes files the child created.
+ *   - The STASH ref: entries the child pushed are dropped AFTER the worktree is
+ *     restored from the snapshot (the snapshot, not the stash, is the source of
+ *     truth), so no landmine stash survives the reconcile.
+ *
+ * The real index's staging state is deliberately NOT restored: pre-commit gate
+ * children run against a tree whose work is unstaged, and the auto-commit that
+ * follows re-stages everything with `add -A` anyway.
+ *
+ * Everything is best-effort: a repo where git itself fails (not a work tree, git
+ * missing) disables the guard (capture returns ok:false and reconcile no-ops) —
+ * the gate must keep working in non-git projects exactly as before.
+ */
+import * as fsp from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { runChildDefault } from '../shared/child-process.js';
+/** Keep the gate machinery's own artifacts out of the snapshot and the restore. */
+const EXCLUDE_TASKS_DIR = ':(exclude).pi-tasks';
+function makeGit(cwd, signal, spawnFn) {
+    return async (args, env) => {
+        const r = await runChildDefault({ command: 'git', args, ...(env ? { env: { ...process.env, ...env } } : {}) }, cwd, signal, { mode: 'text' }, spawnFn);
+        return { stdout: r.stdout, exitCode: r.exitCode };
+    };
+}
+/**
+ * Snapshot the worktree content into a tree object via a THROWAWAY index file, so
+ * neither the real index nor the stash is touched. Returns null when git cannot
+ * build the tree (odd states — the guard then skips tree reconciliation).
+ */
+async function captureWorktreeTree(git) {
+    const tmpIndex = path.join(os.tmpdir(), `pi-task-guard-index-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    const env = { GIT_INDEX_FILE: tmpIndex };
+    try {
+        const empty = await git(['read-tree', '--empty'], env);
+        if (empty.exitCode !== 0)
+            return null;
+        const add = await git(['add', '-A', '--', '.', EXCLUDE_TASKS_DIR], env);
+        if (add.exitCode !== 0)
+            return null;
+        const tree = await git(['write-tree'], env);
+        return tree.exitCode === 0 ? tree.stdout.trim() : null;
+    }
+    finally {
+        await fsp.rm(tmpIndex, { force: true }).catch(() => { });
+    }
+}
+/** Capture the repo state a gate child must leave untouched. */
+export async function captureGitState(cwd, signal, spawnFn) {
+    const git = makeGit(cwd, signal, spawnFn);
+    const disabled = {
+        ok: false,
+        headSha: '',
+        branchRef: null,
+        stashSha: null,
+        treeSha: null
+    };
+    const inside = await git(['rev-parse', '--is-inside-work-tree']);
+    if (inside.exitCode !== 0 || inside.stdout.trim() !== 'true')
+        return disabled;
+    const head = await git(['rev-parse', '-q', '--verify', 'HEAD']);
+    // An unborn HEAD (fresh init, no commits) has nothing to restore to — disable.
+    if (head.exitCode !== 0)
+        return disabled;
+    const branch = await git(['symbolic-ref', '-q', 'HEAD']);
+    const stash = await git(['rev-parse', '-q', '--verify', 'refs/stash']);
+    return {
+        ok: true,
+        headSha: head.stdout.trim(),
+        branchRef: branch.exitCode === 0 ? branch.stdout.trim() : null,
+        stashSha: stash.exitCode === 0 ? stash.stdout.trim() : null,
+        treeSha: await captureWorktreeTree(git)
+    };
+}
+/**
+ * Restore every file recorded in `beforeTree` (content + deletions) and remove
+ * files that exist in `afterTree` but not in `beforeTree` (files the child
+ * created). Uses a throwaway index seeded from the snapshot tree; `checkout-index
+ * -a -f` re-materialises the snapshot verbatim.
+ */
+async function restoreWorktree(cwd, git, beforeTree, afterTree, actions) {
+    const tmpIndex = path.join(os.tmpdir(), `pi-task-guard-restore-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    const env = { GIT_INDEX_FILE: tmpIndex };
+    try {
+        // Files present only in afterTree were created by the child — delete them
+        // BEFORE checkout so a restore failure cannot leave both halves stale.
+        const added = await git([
+            'diff-tree',
+            '-r',
+            '--diff-filter=A',
+            '--name-only',
+            beforeTree,
+            afterTree
+        ]);
+        if (added.exitCode === 0) {
+            for (const rel of added.stdout.split('\n')) {
+                const name = rel.trim();
+                if (name.length === 0)
+                    continue;
+                await fsp.rm(path.join(cwd, name), { force: true }).catch(() => { });
+                actions.push(`removed child-created file ${name}`);
+            }
+        }
+        const read = await git(['read-tree', beforeTree], env);
+        if (read.exitCode !== 0) {
+            actions.push('worktree restore FAILED (read-tree)');
+            return;
+        }
+        const co = await git(['checkout-index', '-a', '-f'], env);
+        actions.push(co.exitCode === 0 ?
+            'restored worktree files from pre-run snapshot'
+            : 'worktree restore FAILED (checkout-index)');
+    }
+    finally {
+        await fsp.rm(tmpIndex, { force: true }).catch(() => { });
+    }
+}
+/**
+ * Compare the repo state against a pre-run snapshot and deterministically undo
+ * whatever a gate child moved. Ordering matters:
+ *
+ *   1. HEAD first — a child parked on another commit must be back on the original
+ *      ref before the worktree comparison/restore makes sense.
+ *   2. Worktree content from the snapshot TREE (not from any stash the child may
+ *      have pushed — the snapshot is the authoritative "as the child found it").
+ *   3. Child-pushed stash entries are dropped LAST, once the work they swallowed
+ *      is already restored — this is exactly the orphan that detonated mx5 run 6.
+ *
+ * Never throws; failures degrade to actions[] lines so the caller can log them.
+ */
+export async function reconcileGitState(cwd, before, signal, spawnFn) {
+    if (!before.ok)
+        return { mutated: false, actions: [] };
+    const git = makeGit(cwd, signal, spawnFn);
+    const actions = [];
+    // 1. HEAD / branch.
+    const head = await git(['rev-parse', '-q', '--verify', 'HEAD']);
+    const branch = await git(['symbolic-ref', '-q', 'HEAD']);
+    const headSha = head.exitCode === 0 ? head.stdout.trim() : '';
+    const branchRef = branch.exitCode === 0 ? branch.stdout.trim() : null;
+    if (headSha !== before.headSha || branchRef !== before.branchRef) {
+        const target = before.branchRef ? before.branchRef.replace(/^refs\/heads\//, '') : before.headSha;
+        const co = await git(['checkout', '-f', target]);
+        actions.push(co.exitCode === 0 ?
+            `checked HEAD back out to ${target}`
+            : `HEAD restore FAILED (checkout ${target})`);
+    }
+    // 2. Worktree content.
+    if (before.treeSha) {
+        const afterTree = await captureWorktreeTree(git);
+        if (afterTree && afterTree !== before.treeSha) {
+            await restoreWorktree(cwd, git, before.treeSha, afterTree, actions);
+        }
+    }
+    // 3. Stash entries the child pushed. Drop stash@{0} until the ref matches the
+    //    snapshot again (bounded — a child pushes at most a handful; 10 is beyond
+    //    anything observed). A stash the child POPPED (ref gone/behind) cannot be
+    //    reconstructed — report it instead of guessing.
+    const stashNow = async () => {
+        const s = await git(['rev-parse', '-q', '--verify', 'refs/stash']);
+        return s.exitCode === 0 ? s.stdout.trim() : null;
+    };
+    let stash = await stashNow();
+    if (stash !== before.stashSha) {
+        if (before.stashSha === null || (await stashContains(git, stash, before.stashSha))) {
+            let dropped = 0;
+            while (stash !== before.stashSha && stash !== null && dropped < 10) {
+                const drop = await git(['stash', 'drop', 'stash@{0}']);
+                if (drop.exitCode !== 0)
+                    break;
+                dropped++;
+                stash = await stashNow();
+            }
+            actions.push(stash === before.stashSha ?
+                `dropped ${dropped} stash entr${dropped === 1 ? 'y' : 'ies'} the child pushed`
+                : 'stash restore INCOMPLETE (drop failed)');
+        }
+        else {
+            actions.push('stash ref changed in a way that cannot be undone (entry popped/dropped)');
+        }
+    }
+    return { mutated: actions.length > 0, actions };
+}
+/** Is `ancestorStash` still reachable in the stash reflog chain at `tipSha`? Used to
+ *  tell "child pushed on top" (droppable) from "child popped/dropped ours" (not). */
+async function stashContains(git, tipSha, wantedSha) {
+    if (tipSha === null)
+        return false;
+    const log = await git(['rev-list', '-g', 'refs/stash']);
+    if (log.exitCode !== 0)
+        return false;
+    return log.stdout
+        .split('\n')
+        .map(l => l.trim())
+        .includes(wantedSha);
+}
+/**
+ * Convenience wrapper for gate call-sites: run `fn` between a capture and a
+ * reconcile, and hand back both the result and what (if anything) had to be
+ * restored. `fn` errors propagate AFTER the reconcile runs — a crashed child must
+ * not skip the restore.
+ */
+export async function withGitStateGuard(cwd, fn, signal, spawnFn) {
+    const before = await captureGitState(cwd, signal, spawnFn);
+    try {
+        const result = await fn();
+        return { result, reconcile: await reconcileGitState(cwd, before, signal, spawnFn) };
+    }
+    catch (err) {
+        await reconcileGitState(cwd, before, signal, spawnFn).catch(() => { });
+        throw err;
+    }
+}

package/dist/task/orchestrator.d.ts

@@ -226,6 +226,14 @@ export declare function runSingleTask(ctx: ExtensionCommandContext, cwd: string,
  * orchestrators, to keep the dependency graph acyclic).
  */
 export declare const gateRunTask: RunTaskFn;
+/**
+ * Demote a task file to a resumable state after a gate (or its implementation)
+ * stopped short. The file is marked `completed` at spec-handoff — before the work
+ * is even verified — so a gate FAIL would otherwise leave it un-resumable
+ * (`completed` is not in RESUMABLE_STATES). Best-effort; a missing/empty id is a
+ * no-op. Mirrors how /task-auto marks the parent run `failed` so resume re-runs it.
+ */
+export declare function markResumable(cwd: string, taskId: string): Promise<void>;
 /**
  * Run a single /task through implementation AND the shared verify + enforce gates,
  * blocking until both finish. Used instead of the fire-and-forget handoff whenever

package/dist/task/orchestrator.js

@@ -581,7 +581,7 @@ export const gateRunTask = (c, cwd, t, opts) => runSingleTask(c, cwd, t, {
  * (`completed` is not in RESUMABLE_STATES). Best-effort; a missing/empty id is a
  * no-op. Mirrors how /task-auto marks the parent run `failed` so resume re-runs it.
  */
-async function markResumable(cwd, taskId) {
+export async function markResumable(cwd, taskId) {
     if (!taskId)
         return;
     try {

package/dist/task/phases.d.ts

@@ -55,6 +55,11 @@ export declare function phaseVerifyTooling(deps: PhaseDeps, research: string): P
 export interface PhaseResearchDeps extends ExternalContextDeps {
     getFileInventory?: (cwd: string, signal?: AbortSignal) => Promise<string>;
 }
+/** Is live web search configured for this process? Mirrors search-core's env lookup. */
+export declare function searchConfigured(getEnv?: (k: string) => string | undefined): boolean;
+/** Extra prompt block for the APIS worker when search is available — trigger-framed
+ *  (the validated shape for getting a local model to actually reach for search). */
+export declare const RESEARCH_SEARCH_HINT: string;
 /**
  * The TOOLING worker only needs to know which verification commands the task
  * cares about — never the per-file edit list. Big refined prompts embed a long

package/dist/task/phases.js

@@ -145,6 +145,24 @@ export async function phaseVerifyTooling(deps, research) {
     return replaceToolingWithVerified(research, parsed.verified);
 }
 const DOCS_EXTENSION_PATH = new URL('../workers/docs-extension.js', import.meta.url).pathname;
+/** pi-worker-search + pi-worker-fetch, loaded into the APIS research worker only
+ *  when a Brave key is configured (the tool without a key just errors, and a weak
+ *  model burns calls on it). Search being absent from the research toolset was
+ *  STRUCTURAL: three consecutive audited runs made 0 search calls because the
+ *  child literally did not have the tool. */
+const SEARCH_EXTENSION_PATH = new URL('../workers/search-extension.js', import.meta.url).pathname;
+/** Is live web search configured for this process? Mirrors search-core's env lookup. */
+export function searchConfigured(getEnv = k => process.env[k]) {
+    return Boolean(getEnv('BRAVE_SEARCH_API_KEY') ?? getEnv('BRAVE_API_KEY'));
+}
+/** Extra prompt block for the APIS worker when search is available — trigger-framed
+ *  (the validated shape for getting a local model to actually reach for search). */
+export const RESEARCH_SEARCH_HINT = '\n\nLIVE WEB — use pi-worker-search for external facts your training data may have stale: '
+    + 'the CURRENT version of a framework/runtime the task pins, a breaking API change you are '
+    + 'not sure shipped, an error message you cannot explain from the code. Call '
+    + '`pi-worker-search(query)` first, then `pi-worker-fetch(url)` on the result you want to '
+    + 'read. Do NOT answer version or release questions from memory. Skip search entirely for '
+    + "anything the project's own files or pi-worker-docs already answer.";
 /**
  * In-process guards loaded into the TOOLING worker only: block a re-read of any
  * file already read, and block any byte-identical grep/find/ls repeat, feeding
@@ -338,10 +356,18 @@ export async function phaseResearch(deps, refined, researchDeps = {}) {
         {
             section: 'APIS',
             label: 'worker:apis',
-            // Read-heavy: gets the orientation core (see note above).
-            prompt: appendNoThink(orientation.block + promptHeader + RESEARCH_APIS_PROMPT(refined)),
-            tools: 'read,grep,find,ls,pi-worker-docs',
-            extensions: [DOCS_EXTENSION_PATH]
+            // Read-heavy: gets the orientation core (see note above). Search/fetch
+            // ride along only when a Brave key exists — see SEARCH_EXTENSION_PATH.
+            prompt: appendNoThink(orientation.block
+                + promptHeader
+                + RESEARCH_APIS_PROMPT(refined)
+                + (searchConfigured() ? RESEARCH_SEARCH_HINT : '')),
+            tools: 'read,grep,find,ls,pi-worker-docs'
+                + (searchConfigured() ? ',pi-worker-search,pi-worker-fetch' : ''),
+            extensions: [
+                DOCS_EXTENSION_PATH,
+                ...(searchConfigured() ? [SEARCH_EXTENSION_PATH] : [])
+            ]
         },
         {
             section: 'CONTEXT',

package/dist/task/task-gates.js

@@ -127,10 +127,20 @@ export async function runGatesForTask(ctxIn, deps, p) {
                 break;
             }
             // AUTOFIX: re-run the implementation turn with the failure (and any typed
-            // guidance) prepended as a RE-ATTEMPT banner, then re-verify.
+            // guidance) prepended as a RE-ATTEMPT banner, then re-verify. The
+            // recommendation child already LOCATED the defect while deciding (mx5
+            // run 6: it pinned the exact SQL alias bug and the afterAll DB-drop) —
+            // hand that diagnosis to the re-run so it fixes the located cause
+            // instead of re-deriving it from the bare FAIL line. Skipped when there
+            // is no researched rationale beyond the failure text itself.
             await rec('resolution: user chose AUTOFIX — re-running the implementation turn');
             active.ui.notify(`${p.tag}: autofixing "${p.title}"…`, 'info');
-            const fixInstruction = choice.guidance ? `${failReason}\n\nUser guidance: ${choice.guidance}` : failReason;
+            const diagnosis = (recOutcome.recommend === 'autofix'
+                && recOutcome.rationale.length > 0
+                && recOutcome.rationale !== failReason) ?
+                `\n\nDIAGNOSIS (a read-only investigation of this failure found):\n${recOutcome.rationale}`
+                : '';
+            const fixInstruction = `${failReason}${diagnosis}${choice.guidance ? `\n\nUser guidance: ${choice.guidance}` : ''}`;
             const fixRes = await deps.runTask(active, p.cwd, p.title, {
                 resumeId: p.taskId,
                 planContext: p.planContext,
@@ -167,8 +177,9 @@ export async function runGatesForTask(ctxIn, deps, p) {
         // A benign skip ("nothing to commit", auto-commit off) is a warning. A real
         // git failure is louder: it silently disables enforce AND every commit-based
         // guard — mx5 run 4 lost all 10 commits (no container git identity) with only
-        // per-task warnings to show for it.
-        const gitFailure = /^git (commit|add) failed/.test(commit.reason ?? '');
+        // per-task warnings to show for it. "blocked" is the unmerged-index refusal
+        // (gitCommitAll) — the same severity: nothing can commit until it's resolved.
+        const gitFailure = /^git (commit|add) (failed|blocked)/.test(commit.reason ?? '');
         active.ui.notify(gitFailure ?
             `${p.tag}: COMMIT FAILED (${commit.reason}) — enforce and revert guards are disabled for this task.`
             : `${p.tag}: not committed (${commit.reason ?? 'unknown'}) — continuing.`, gitFailure ? 'error' : 'warning');

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

@@ -82,6 +82,18 @@ export interface VerificationDeps {
      * into the child's prompt. A/B-proven load-bearing: the prompt rule alone caught
      * the class 2/5, rule + probe finding 5/5. ABSENT or empty → no probe block. */
     probe?: () => Promise<string[]>;
+    /**
+     * Result of the git-state guard for the MOST RECENT runChild call (see
+     * git-state-guard.ts): did the child mutate repo state (stash/checkout/file
+     * rewrites), which the guard then restored? A verdict computed on a mutated
+     * tree is untrustworthy in BOTH directions — the mx5 run 6 child stashed the
+     * work away and judged an empty tree — so it is discarded: the first mutated
+     * run is retried once on the restored tree; a second mutation is a FAIL that
+     * names the behavior. ABSENT → no guard (tests / non-git repos), unchanged. */
+    mutationCheck?: () => {
+        mutated: boolean;
+        detail: string;
+    };
 }
 /**
  * Run the verification pass for one task. A missing spec is a pass. Otherwise run

package/dist/task/verify-work.js

@@ -320,6 +320,20 @@ export async function runWorkVerification(deps) {
             const msg = err instanceof Error ? err.message : String(err);
             return { ok: false, reason: `verification pass could not run: ${msg}` };
         }
+        // A child that mutated the repo (git-state guard fired) judged a tree it had
+        // itself changed — its verdict is meaningless in both directions, so discard
+        // it BEFORE parsing. The guard already restored the state, so one retry runs
+        // on the pristine tree; a child that mutates again is reported as the fault.
+        const mutation = deps.mutationCheck?.();
+        if (mutation?.mutated) {
+            if (attempt === 1)
+                continue;
+            return {
+                ok: false,
+                reason: 'verify child mutated repo state and its verdict was discarded '
+                    + `(state restored: ${mutation.detail.slice(0, 200)})`
+            };
+        }
         const verdict = parseVerifyVerdict(text);
         if (verdict.pass)
             return { ok: true };

package/dist/workers/search-extension.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+export default function (pi: ExtensionAPI): void;

package/dist/workers/search-extension.js

@@ -0,0 +1,6 @@
+import { registerPiWorkerSearch } from './pi-worker-search.js';
+import { registerPiWorkerFetch } from './pi-worker-fetch.js';
+export default function (pi) {
+    registerPiWorkerSearch(pi);
+    registerPiWorkerFetch(pi);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.17.24",
+    "version": "0.17.25",
     "description": "Deterministic task planning and spec-orchestration for local models — crash-safe /task pipelines with verify/enforce gates, a real-time remote web view, and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",