@mjasnikovs/pi-task 0.17.23 → 0.17.25

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');