@mjasnikovs/pi-task 0.18.4 → 0.18.6

package/dist/config/config.d.ts

@@ -1,3 +1,4 @@
+import { type SearchProvider } from '../workers/search-types.js';
 export interface PiTaskConfig {
     remote: boolean;
     compressReasoning: boolean;
@@ -12,6 +13,23 @@ export interface PiTaskConfig {
      * phases.ts). Turn on only for a parallel-capable backend.
      */
     parallelResearchWorkers: boolean;
+    /**
+     * Cache docs/search/fetch worker RESULTS for the duration of one /task-auto run
+     * so sibling tasks re-asking the same (package/url, query) reuse the first
+     * pipeline's digest instead of re-fetching (mx5 run-8 F10: the research phase
+     * burned 75 of 363 min largely re-fetching the same external docs across ~20
+     * siblings). Per-run isolated, external-only (project-source `.` lookups excluded),
+     * success-only. DEFAULT ON — the F10 live A/B showed no answer-quality regression
+     * (a cache hit serves byte-identical text to the first fetch; distinct queries never
+     * collide).
+     */
+    researchCache: boolean;
+    /**
+     * Which engine backs web search (pi-worker-search + freshness/enrichment).
+     * `exa` and `ddg` need no API key; `brave` needs BRAVE_SEARCH_API_KEY.
+     * DEFAULT `exa` so search works out of the box with zero configuration.
+     */
+    searchProvider: SearchProvider;
 }
 export declare function getConfig(): PiTaskConfig;
 export declare function saveConfig(config: PiTaskConfig): Promise<void>;

package/dist/config/config.js

@@ -2,6 +2,7 @@ import * as fs from 'node:fs';
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
 import * as os from 'node:os';
+import { isSearchProvider } from '../workers/search-types.js';
 const DEFAULTS = {
     remote: true,
     compressReasoning: true,
@@ -9,7 +10,11 @@ const DEFAULTS = {
     orientation: true,
     enforceGuidelines: true,
     verifyWork: true,
-    parallelResearchWorkers: false
+    parallelResearchWorkers: false,
+    // ON: the F10 live A/B showed no answer-quality regression (fidelity 3/3, quality
+    // 3/3, 0 collisions; ~14.5s of repeated docs lookups collapse to 0ms on a hit).
+    researchCache: true,
+    searchProvider: 'exa'
 };
 const CONFIG_PATH = path.join(os.homedir(), '.config', 'pi-task', 'config.json');
 const _g = globalThis;
@@ -23,6 +28,10 @@ if (!G.loaded) {
     try {
         const raw = fs.readFileSync(CONFIG_PATH, 'utf8');
         const parsed = JSON.parse(raw);
+        // A hand-edited or stale enum value must not leak an unknown provider
+        // into the dispatch switch — fall back to the default.
+        if (!isSearchProvider(parsed.searchProvider))
+            delete parsed.searchProvider;
         G.config = { ...DEFAULTS, ...parsed };
     }
     catch {

package/dist/config/register.js

@@ -1,5 +1,6 @@
 import { SettingsList, visibleWidth } from '@earendil-works/pi-tui';
 import { registerBridgeCommand } from '../remote/bridge.js';
+import { SEARCH_PROVIDERS, isSearchProvider } from '../workers/search-types.js';
 import { getConfig, saveConfig } from './config.js';
 const CONFIG_TITLE = 'pi-task settings';
 /**
@@ -46,6 +47,10 @@ class BorderedBox {
         this.child.handleInput(data);
     }
 }
+/**
+ * Every setting rendered by /task-config. Boolean settings omit `values` and
+ * toggle on/off; enum settings list their values and cycle through them.
+ */
 const ITEMS = [
     { id: 'remote', label: 'remote', description: 'Remote UI server (QR code, phone access)' },
     {
@@ -77,6 +82,17 @@ const ITEMS = [
         id: 'parallelResearchWorkers',
         label: 'parallel research',
         description: 'Run the 4 research workers concurrently. Leave OFF on a single-GPU local server (serial is measurably faster there); turn on only for a parallel-capable model backend'
+    },
+    {
+        id: 'researchCache',
+        label: 'research cache',
+        description: 'Cache docs/search/fetch results within one /task-auto run so sibling tasks reuse the first pipeline’s digest instead of re-fetching the same external docs. Per-run isolated, external-only, success-only'
+    },
+    {
+        id: 'searchProvider',
+        label: 'search provider',
+        description: 'Engine behind web search (pi-worker-search + freshness checks). exa and ddg need no API key; brave needs BRAVE_SEARCH_API_KEY',
+        values: SEARCH_PROVIDERS
     }
 ];
 function makeTheme(theme) {
@@ -91,21 +107,32 @@ function makeTheme(theme) {
 async function handleTaskConfig(_args, ctx) {
     const cfg = { ...getConfig() };
     if (ctx.mode !== 'tui') {
-        const lines = ITEMS.map(({ id, label }) => `${label.padEnd(22)} ${cfg[id] ? 'on' : 'off'}`);
+        const lines = ITEMS.map(({ id, label, values }) => `${label.padEnd(22)} ${values ? String(cfg[id])
+            : cfg[id] ? 'on'
+                : 'off'}`);
         ctx.ui.notify(lines.join('  |  '), 'info');
         return;
     }
     await ctx.ui.custom((_tui, theme, _kb, done) => {
         const listTheme = makeTheme(theme);
-        const items = ITEMS.map(({ id, label, description }) => ({
+        const items = ITEMS.map(({ id, label, description, values }) => ({
             id,
             label,
             description,
-            currentValue: cfg[id] ? 'on' : 'off',
-            values: ['on', 'off']
+            currentValue: values ? String(cfg[id])
+                : cfg[id] ? 'on'
+                    : 'off',
+            values: values ?? ['on', 'off']
         }));
         const list = new SettingsList(items, 10, listTheme, (id, newValue) => {
-            cfg[id] = newValue === 'on';
+            if (id === 'searchProvider') {
+                if (isSearchProvider(newValue))
+                    cfg.searchProvider = newValue;
+            }
+            else {
+                ;
+                cfg[id] = newValue === 'on';
+            }
             saveConfig(cfg).catch(() => { });
         }, () => done(undefined));
         return new BorderedBox(list, CONFIG_TITLE, s => theme.fg('borderMuted', s), s => theme.fg('accent', theme.bold(s)));

package/dist/task/accept-debt.d.ts

@@ -0,0 +1,52 @@
+/** One accepted-despite-FAIL record: the task and why its VERIFY failed. */
+export interface AcceptDebt {
+    taskId: string;
+    reason: string;
+}
+export declare function acceptDebtFile(cwd: string): string;
+/** The raw stored ledger ('' when none recorded yet). Parse with parseAcceptDebts. */
+export declare function readAcceptDebtsRaw(cwd: string): Promise<string>;
+/**
+ * Parse the stored ledger into records. A line without the separator (a reason but
+ * no id, e.g. hand-edited) parses with an empty taskId rather than being dropped —
+ * a recorded debt is never silently lost.
+ */
+export declare function parseAcceptDebts(raw: string): AcceptDebt[];
+/** Read + parse in one step. */
+export declare function readAcceptDebts(cwd: string): Promise<AcceptDebt[]>;
+/**
+ * Append one accepted-despite-FAIL record, deduplicated against what is already
+ * stored (case-insensitive on task id + reason), keeping the newest MAX_DEBTS.
+ * Failures are swallowed — the ledger is an auditing aid, never a blocker of the
+ * gate sequence that calls it.
+ */
+export declare function recordAcceptDebt(cwd: string, taskId: string, reason: string): Promise<void>;
+/** Overwrite the ledger with exactly these records (used to prune resolved debts). */
+export declare function writeAcceptDebts(cwd: string, debts: AcceptDebt[]): Promise<void>;
+/**
+ * STATIC-CLASS debt: one whose accepted FAIL was the deterministic whole-repo static
+ * health check (`repo health: …`, the prefix runWorkVerification's repoHealth branch
+ * emits). This is the ONE class a deterministic re-check can prove resolved
+ * stack-agnostically — the final gate runs the same static check, so a later task
+ * that fixed the statics resolves the debt. Every other reason is model-judged or
+ * behavioral and cannot be proven resolved without re-running the model.
+ */
+export declare function isStaticClassDebt(reason: string): boolean;
+/**
+ * Re-check the ledger against the current run state. A static-class debt is RESOLVED
+ * iff the final gate's own static check now passes (`staticOk`); every other debt
+ * stays OPEN (unprovable ⇒ surface, never re-hide). FP-safe: the only auto-close is
+ * the one a deterministic check can stand behind.
+ */
+export declare function recheckAcceptDebts(debts: AcceptDebt[], opts: {
+    staticOk: boolean;
+}): {
+    open: AcceptDebt[];
+    resolved: AcceptDebt[];
+};
+/**
+ * A one-line-per-debt suffix appended to the final gate's report reason so the still
+ * -open accepted defects surface in the gate outcome the user sees (and in the fail
+ * picker). Empty when nothing is open.
+ */
+export declare function buildAcceptDebtNote(open: AcceptDebt[]): string;

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

@@ -1,6 +1,7 @@
 import type { ExtensionAPI, ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 import { type FinalGateFixFn } from './gate-deps.js';
 import { type GateDeps } from './task-gates.js';
+import type { AcceptDebt } from './accept-debt.js';
 /**
  * Injectable seams so the planner and loop are testable without spawning pi.
  * `runChild` is the planning-only seam used by planAuto; everything else (runTask,
@@ -32,6 +33,7 @@ export interface AutoDeps extends GateDeps {
     finalGate?: (cwd: string) => Promise<{
         ok: boolean;
         reason: string;
+        openDebts?: AcceptDebt[];
     }>;
     /**
      * Bounded model-driven fix pass for a final-gate FAIL (see final-gate-fix.ts),

package/dist/task/auto-orchestrator.js

@@ -29,6 +29,7 @@ import { gitUnmergedPaths, gitStashRef } from './auto-commit.js';
 import { runFinalIntegrationGate } from './final-gate.js';
 import { classifyFinalGateAnswer, MAX_FINAL_GATE_AUTOFIX, FINAL_LEAVE_LABEL, FINAL_LEAVE_VALUE, FINAL_ACCEPT_LABEL, FINAL_ACCEPT_VALUE, FINAL_AUTOFIX_LABEL, FINAL_AUTOFIX_VALUE } from './final-gate-fix.js';
 import { getConfig } from '../config/config.js';
+import { configureResearchRun } from '../workers/research-cache.js';
 import { CONTRACT_EXTRACT_PROMPT, parseContractLines, keepGroundedContracts, appendContracts } from './contracts.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
@@ -681,6 +682,18 @@ export async function runAutoLoop(ctx, cwd, id, deps) {
                     let fin = await deps.finalGate(cwd);
                     if (!fin.ok)
                         await recGate(`final-gate: FAIL — ${fin.reason.slice(0, 300)}`);
+                    // ACCEPT-debt re-check surfacing (mx5 run 4 B3 / run 8 TASK_0012):
+                    // tasks the user accepted despite a verify-FAIL that the gate could
+                    // not prove resolved against the current tree. Surface them at the
+                    // gate moment — on PASS or FAIL — so a run never completes silently
+                    // carrying an accepted defect. Informational: the per-task ACCEPT was
+                    // already a human decision, so this reports, it does not re-fail.
+                    if (fin.openDebts && fin.openDebts.length > 0) {
+                        for (const d of fin.openDebts) {
+                            await recGate(`accept-debt STILL OPEN — ${d.taskId || '(unknown task)'} was ACCEPTED despite verify-FAIL: ${d.reason.slice(0, 240)}`);
+                        }
+                        active.ui.notify(`${id}: ${fin.openDebts.length} task(s) accepted despite verify-FAIL are STILL unresolved at run end — see the gate trail.`, 'warning');
+                    }
                     // Resolution loop: Leave-failed (recommended) / Autofix (bounded,
                     // model-driven fix pass + gate re-run — run 7's gap: the picker
                     // had NO automated fix path) / Accept. The user always decides;
@@ -916,6 +929,10 @@ async function handleTaskAuto(args, ctx) {
         return;
     }
     autoRunning = true;
+    // Stamp a fresh per-run research-cache id (F10) BEFORE planning so enrichment and
+    // every task's research phase share one run's cache; disabled ⇒ clears any token a
+    // prior run left, so nothing is cached.
+    configureResearchRun(getConfig().researchCache);
     const abort = new AbortController();
     const deps = defaultDeps(ctx, cwd, abort.signal, deriveTitle(raw));
     let id;
@@ -958,6 +975,9 @@ async function handleTaskAutoResume(_args, ctx) {
     ctx.ui.notify(`Resuming ${id}…`, 'info');
     await updateTaskFrontMatter(cwd, id, { state: 'in_progress' });
     autoRunning = true;
+    // Fresh per-run research-cache id for the resumed run (F10); a resume re-fetches
+    // rather than reusing the interrupted run's digest — safe, only slightly less reuse.
+    configureResearchRun(getConfig().researchCache);
     const abort = new AbortController();
     // Resume only runs the loop (runTask); no planning children, so the loader
     // title is unused here — pass the id for clarity if that ever changes.

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

@@ -1,9 +1,17 @@
 import { type HealthCommand } from './repo-health-check.js';
+import { type AcceptDebt } from './accept-debt.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;
+    /**
+     * ACCEPT-despite-verify-FAIL debts still open at run end (mx5 run 4 B3 / run 8
+     * TASK_0012): tasks the user blessed as-is despite a verify-FAIL that a
+     * deterministic re-check could not prove resolved. The caller surfaces them so a
+     * run never completes silently carrying an accepted defect. Empty/absent = none.
+     */
+    openDebts?: AcceptDebt[];
 }
 /**
  * The project's OWN whole-repo integration commands (test, then build — test

package/dist/task/final-gate.js

@@ -42,6 +42,7 @@ import { spawn, spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import * as path from 'node:path';
 import { runRepoHealthCheck, discoverHealthCommands } from './repo-health-check.js';
+import { readAcceptDebts, recheckAcceptDebts, writeAcceptDebts, buildAcceptDebtNote } from './accept-debt.js';
 function packageScripts(cwd) {
     try {
         const j = JSON.parse(readFileSync(path.join(cwd, 'package.json'), 'utf8'));
@@ -280,13 +281,32 @@ function runGateCommand(cwd, [bin, args], timeoutMs) {
  */
 export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGraceMs = 10_000) {
     const stat = runRepoHealthCheck(cwd);
+    // ACCEPT-debt re-check (mx5 run 4 B3 / run 8 TASK_0012): read the ledger of tasks
+    // the user accepted despite a verify-FAIL and re-check each against the current
+    // tree. A static-class debt whose statics now pass is provably RESOLVED (a later
+    // task fixed it) and pruned; every other debt cannot be proven resolved
+    // deterministically, so it stays OPEN and is surfaced in this gate's report — a
+    // run may not complete silently carrying an accepted defect. FP-safe by
+    // construction (see accept-debt.ts). Best-effort: a ledger read/write failure
+    // must never break the gate.
+    const { open: openDebts, resolved } = recheckAcceptDebts(await readAcceptDebts(cwd), {
+        staticOk: stat.ok
+    });
+    if (resolved.length > 0)
+        await writeAcceptDebts(cwd, openDebts);
+    const debtNote = buildAcceptDebtNote(openDebts);
+    const withDebts = (o) => ({
+        ...o,
+        reason: `${o.reason}${debtNote}`,
+        openDebts
+    });
     if (!stat.ok)
-        return { ok: false, reason: `static checks: ${stat.reason}` };
+        return withDebts({ ok: false, reason: `static checks: ${stat.reason}` });
     const lockCmds = discoverLockfileChecks(cwd);
     const { cmds } = discoverIntegrationCommands(cwd);
     const boot = discoverBootCommand(cwd);
     if (lockCmds.length === 0 && cmds.length === 0 && !boot) {
-        return { ok: true, reason: 'no integration command found (statics passed)' };
+        return withDebts({ ok: true, reason: 'no integration command found (statics passed)' });
     }
     const ran = [];
     for (const { prefix, list } of [
@@ -299,10 +319,10 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
             if (r.outcome === 'skip')
                 continue;
             if (r.outcome === 'fail') {
-                return {
+                return withDebts({
                     ok: false,
                     reason: `${prefix}\`${label}\` exited ${r.status}${r.tail ? ` — ${r.tail}` : ''}`
-                };
+                });
             }
             ran.push(label);
         }
@@ -311,15 +331,15 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
         const label = `${boot[0]} ${boot[1].join(' ')}`;
         const b = await runBootCheck(cwd, boot, bootGraceMs);
         if (b.outcome === 'fail') {
-            return { ok: false, reason: `boot check: \`${label}\` ${b.detail}` };
+            return withDebts({ ok: false, reason: `boot check: \`${label}\` ${b.detail}` });
         }
         if (b.outcome === 'pass')
             ran.push(label);
     }
-    return {
+    return withDebts({
         ok: true,
         reason: ran.length > 0 ?
             `statics + ${ran.map(c => `\`${c}\``).join(', ')} passed`
             : 'statics passed (integration commands not runnable here)'
-    };
+    });
 }

package/dist/task/frozen-path-guard.d.ts

@@ -0,0 +1,39 @@
+/** Run a git subcommand in the guard's cwd; only stdout + exit code are read. */
+export type FrozenGit = (args: string[]) => Promise<{
+    stdout: string;
+    exitCode: number;
+}>;
+/**
+ * The concrete paths the spec forbids modifying, normalized and de-duplicated —
+ * the SAME extraction the verify prohibition-probe and the accept-debt ledger
+ * consume, so "frozen" means one thing across the gates. Empty when the spec is
+ * null or names no path-like token on a modification-ban line: the guard is then a
+ * no-op by construction.
+ */
+export declare function frozenPathsFromSpec(spec: string | null | undefined): string[];
+/**
+ * Parse `git status --porcelain` output (already scoped to the frozen pathspec)
+ * into the list of changed files, for the gate-trail record and to decide whether
+ * anything must be reverted at all. A rename line (`R  old -> new`) yields the NEW
+ * path — the side that carries the child's write. Deterministic and pure so the
+ * parsing is unit-tested without a real repo.
+ */
+export declare function parseChangedFrozenFiles(porcelain: string): string[];
+/**
+ * Restore the spec-frozen paths to their committed (HEAD) state, undoing any
+ * change a just-run write-capable gate child made to them, and return the list of
+ * files that had to be reverted (empty ⇒ the pass respected every frozen path).
+ *
+ * Runs AFTER the task's own work is committed (HEAD), so "restore to HEAD" keeps
+ * the verified task's version of the frozen file and discards ONLY the gate
+ * child's edit on top of it — the task's own frozen-path edits, if any, are a
+ * separate concern the verify prohibition-probe surfaces. `git checkout HEAD`
+ * covers modified/deleted tracked files under each pathspec; `git clean` removes
+ * any untracked file the pass created under a frozen directory. Both are scoped to
+ * the frozen pathspec, so nothing else in the tree is touched.
+ *
+ * Best-effort: an empty frozen list, a non-git tree, or any git error yields an
+ * empty result — the guard must never break the gate on a project it cannot reason
+ * about.
+ */
+export declare function revertFrozenPaths(paths: string[], git: FrozenGit): Promise<string[]>;

package/dist/task/frozen-path-guard.js

@@ -0,0 +1,116 @@
+/**
+ * frozen-path-guard — deterministic write-deny on spec-frozen paths for the
+ * write-capable gate children (the enforce EDIT pass especially).
+ *
+ * The failure class (carried from mx5 run 6, deferred there as the last unshipped
+ * piece of the frozen-contract work): a spec's CONSTRAINTS pin a path as
+ * off-limits ("**Do NOT modify** `src/server/index.ts`"), and a later
+ * write-enabled GATE pass — the enforce child runs `read,edit` — edits that path
+ * anyway. Its edits are judged only locally (a guideline-compliance verdict), then
+ * committed as an "ENFORCE GUIDELINES" snapshot on top of the verified task. The
+ * frozen contract is silently mutated by the very pass meant to police the work.
+ *
+ * Prompt framing is A/B-PROVEN insufficient for this class (the "FROZEN CONTRACT,
+ * MUST NOT edit" instruction held 0/5 unguarded, ~1/5 with framing — the weak
+ * local model ignores an explicit capitalized MUST-NOT most of the time). A
+ * chmod-style physical deny holds 5/5 but makes the model THRASH on the bare
+ * EACCES (1000+ futile re-attempts observed) — unacceptable on the enforce child,
+ * which runs UNGUARDED (no wall-clock timeout). pi itself has no path-level edit
+ * interception (only tool-NAME allow/deny), so the achievable, thrash-free,
+ * stack-agnostic realization of a tool-layer deny is this: let the pass edit
+ * freely, then deterministically UNDO any frozen-path change it made before those
+ * edits can be committed. The violating write never lands in a commit, regardless
+ * of what the model intended — no model in the loop, same discipline as
+ * git-state-guard.
+ *
+ * Everything degrades to a no-op when the spec froze nothing (a single-`/task`
+ * run, or a spec with no `Do NOT modify` line naming a path → no frozen paths →
+ * nothing snapshotted, nothing reverted) and on any git error. Pure git shape,
+ * zero stack assumptions — a frozen path exists for a CLI, a library, a script
+ * collection exactly as for a web app.
+ */
+import { extractProhibitions } from './prohibition-probe.js';
+/**
+ * The concrete paths the spec forbids modifying, normalized and de-duplicated —
+ * the SAME extraction the verify prohibition-probe and the accept-debt ledger
+ * consume, so "frozen" means one thing across the gates. Empty when the spec is
+ * null or names no path-like token on a modification-ban line: the guard is then a
+ * no-op by construction.
+ */
+export function frozenPathsFromSpec(spec) {
+    if (!spec)
+        return [];
+    const seen = new Set();
+    for (const p of extractProhibitions(spec)) {
+        const n = p.path.replace(/^\.\//, '').replace(/\/+$/, '');
+        if (n.length > 0)
+            seen.add(n);
+    }
+    return [...seen];
+}
+/**
+ * Parse `git status --porcelain` output (already scoped to the frozen pathspec)
+ * into the list of changed files, for the gate-trail record and to decide whether
+ * anything must be reverted at all. A rename line (`R  old -> new`) yields the NEW
+ * path — the side that carries the child's write. Deterministic and pure so the
+ * parsing is unit-tested without a real repo.
+ */
+export function parseChangedFrozenFiles(porcelain) {
+    const out = [];
+    const seen = new Set();
+    for (const raw of porcelain.split('\n')) {
+        // Porcelain v1: two status chars, a space, then the path. Blank/short lines
+        // (trailing newline) carry no entry.
+        if (raw.length < 4)
+            continue;
+        let file = raw.slice(3).trim();
+        if (file.length === 0)
+            continue;
+        // Rename/copy: "orig -> new" — the new path is the one the write produced.
+        const arrow = file.indexOf(' -> ');
+        if (arrow !== -1)
+            file = file.slice(arrow + 4).trim();
+        // Porcelain quotes paths with unusual chars; strip the surrounding quotes.
+        if (file.startsWith('"') && file.endsWith('"') && file.length >= 2) {
+            file = file.slice(1, -1);
+        }
+        if (file.length === 0 || seen.has(file))
+            continue;
+        seen.add(file);
+        out.push(file);
+    }
+    return out;
+}
+/**
+ * Restore the spec-frozen paths to their committed (HEAD) state, undoing any
+ * change a just-run write-capable gate child made to them, and return the list of
+ * files that had to be reverted (empty ⇒ the pass respected every frozen path).
+ *
+ * Runs AFTER the task's own work is committed (HEAD), so "restore to HEAD" keeps
+ * the verified task's version of the frozen file and discards ONLY the gate
+ * child's edit on top of it — the task's own frozen-path edits, if any, are a
+ * separate concern the verify prohibition-probe surfaces. `git checkout HEAD`
+ * covers modified/deleted tracked files under each pathspec; `git clean` removes
+ * any untracked file the pass created under a frozen directory. Both are scoped to
+ * the frozen pathspec, so nothing else in the tree is touched.
+ *
+ * Best-effort: an empty frozen list, a non-git tree, or any git error yields an
+ * empty result — the guard must never break the gate on a project it cannot reason
+ * about.
+ */
+export async function revertFrozenPaths(paths, git) {
+    if (paths.length === 0)
+        return [];
+    const status = await git(['status', '--porcelain', '--', ...paths]);
+    if (status.exitCode !== 0)
+        return [];
+    const changed = parseChangedFrozenFiles(status.stdout);
+    if (changed.length === 0)
+        return [];
+    // Restore tracked modifications/deletions from HEAD, then remove any untracked
+    // additions — both confined to the frozen pathspec so the pass's legitimate
+    // edits to OTHER files survive untouched.
+    await git(['checkout', '-f', 'HEAD', '--', ...paths]);
+    await git(['clean', '-fdq', '--', ...paths]);
+    return changed;
+}

package/dist/task/gate-deps.js

@@ -21,11 +21,13 @@ import { runGuidelineEnforcement, classifyEnforceChildFailure } from './enforce-
 import { runWorkVerification, extractSpecForVerification } from './verify-work.js';
 import { readEnvNotes, appendEnvNotes } from './env-notes.js';
 import { readContracts } from './contracts.js';
+import { recordAcceptDebt } from './accept-debt.js';
 import { runRepoHealthCheck } from './repo-health-check.js';
 import { runFinalIntegrationGate, discoverGateCommandLabels } from './final-gate.js';
 import { runFinalGateAutofix } from './final-gate-fix.js';
 import { researchResolution } from './verify-resolution.js';
 import { extractProhibitions, findProhibitionViolations } from './prohibition-probe.js';
+import { frozenPathsFromSpec, revertFrozenPaths } from './frozen-path-guard.js';
 import { findProbeGaming, parseAddedLines } from './probe-gaming.js';
 import { findSubstitutionSuspects, isTestFile } from './substitution-probe.js';
 import { findTestRebuiltAssemblies, testAssemblyVerifyFindings } from './test-assembly.js';
@@ -264,6 +266,29 @@ export function buildGateDeps(params) {
         // Durable per-task gate trail: every verdict/decision lands in the task
         // file's `## gates` section so gate behavior is auditable from artifacts.
         record: (cwd2, taskId, line) => appendGateRecord(cwd2, taskId, line),
+        // Durable ACCEPT-despite-verify-FAIL ledger under .pi-tasks/ (survives
+        // discardEdits): the final integration gate re-checks each debt at run end.
+        recordAcceptDebt: (cwd2, taskId, reason) => recordAcceptDebt(cwd2, taskId, reason),
+        // Frozen-path write-deny (see frozen-path-guard.ts): the concrete paths this
+        // task's spec forbids modifying, so the gate sequence can UNDO any edit the
+        // enforce EDIT pass makes to them before those edits are committed. Reads the
+        // same composed spec + extractProhibitions the verify probe consumes; empty on
+        // a spec that froze nothing → the guard is a no-op.
+        frozenPaths: async (cwd2, taskId) => {
+            try {
+                const { body } = await readTaskFile(cwd2, taskId);
+                return frozenPathsFromSpec(extractSpecForVerification(body));
+            }
+            catch {
+                return [];
+            }
+        },
+        // Restore those frozen paths to HEAD, discarding a gate child's edits to them;
+        // returns the files actually reverted (for the trail). Best-effort git shape.
+        revertFrozenPaths: (cwd2, paths) => revertFrozenPaths(paths, async (args) => {
+            const r = await git(cwd2, args, signal);
+            return { stdout: r.stdout, exitCode: r.exitCode };
+        }),
         commit: (cwd2, message) => getConfig().autoCommit ?
             gitCommitAll(cwd2, message, signal)
             : Promise.resolve({ committed: false, reason: 'auto-commit disabled' }),

package/dist/task/phases.d.ts

@@ -6,6 +6,7 @@ import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
 import { docsFocused } from '../workers/docs-core.js';
 import { fetchFocused } from '../workers/fetch-core.js';
 import type { SearchCoreInput, SearchCoreResult } from '../workers/search-core.js';
+import type { SearchProvider } from '../workers/search-types.js';
 import { type ExternalContextDeps } from './external-context.js';
 import { MAX_GRILL_QUESTIONS } from './prompts.js';
 import { type PhaseName } from './task-types.js';
@@ -63,8 +64,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;
+/**
+ * Is live web search configured for this process? The keyless providers (exa,
+ * ddg) always are; only brave needs its API key — mirrors search-core's lookup.
+ */
+export declare function searchConfigured(getEnv?: (k: string) => string | undefined, provider?: SearchProvider): 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;

package/dist/task/phases.js

@@ -166,8 +166,13 @@ const DOCS_EXTENSION_PATH = new URL('../workers/docs-extension.js', import.meta.
  *  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]) {
+/**
+ * Is live web search configured for this process? The keyless providers (exa,
+ * ddg) always are; only brave needs its API key — mirrors search-core's lookup.
+ */
+export function searchConfigured(getEnv = k => process.env[k], provider = getConfig().searchProvider) {
+    if (provider !== 'brave')
+        return true;
     return Boolean(getEnv('BRAVE_SEARCH_API_KEY') ?? getEnv('BRAVE_API_KEY'));
 }
 /** Extra prompt block for the APIS worker when search is available — trigger-framed

package/dist/task/repo-health-check.d.ts

@@ -6,7 +6,18 @@ export interface HealthOutcome {
     reason: string;
     /** Which manifest drove discovery, or null when none was found. */
     ecosystem: string | null;
+    /**
+     * First lines of the failing command's combined stderr+stdout — captured so a
+     * FAIL is explainable from artifacts alone. Run-8 F8: five enforce passes were
+     * discarded on "`bun run lint` exited 2" and the cause was unreproducible
+     * post-run because only the exit code was recorded (exit 2 is the linter's
+     * CRASH class; findings exit 1 — the captured output is what tells them apart).
+     * Empty string on pass / skip.
+     */
+    output: string;
 }
+/** Combine a failing command's stderr+stdout into a bounded, first-N-lines snippet. */
+export declare function captureHealthOutput(stdout: string, stderr: string): string;
 /** One discovered command: the binary and its args, run from the repo root. */
 export type HealthCommand = [bin: string, args: string[]];
 /**