@mjasnikovs/pi-task 0.18.4 → 0.18.5

package/dist/config/config.d.ts

@@ -12,6 +12,17 @@ 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;
 }
 export declare function getConfig(): PiTaskConfig;
 export declare function saveConfig(config: PiTaskConfig): Promise<void>;

package/dist/config/config.js

@@ -9,7 +9,10 @@ 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
 };
 const CONFIG_PATH = path.join(os.homedir(), '.config', 'pi-task', 'config.json');
 const _g = globalThis;

package/dist/config/register.js

@@ -77,6 +77,11 @@ 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'
     }
 ];
 function makeTheme(theme) {

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/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[]];
 /**

package/dist/task/repo-health-check.js

@@ -32,6 +32,23 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import * as path from 'node:path';
+/** How much of a failing command's output to keep — bounded so a wedged tool that
+ *  spews megabytes cannot bloat the trail. stderr leads (a crash trace lives there). */
+const HEALTH_OUTPUT_MAX_LINES = 40;
+const HEALTH_OUTPUT_MAX_CHARS = 4000;
+/** Combine a failing command's stderr+stdout into a bounded, first-N-lines snippet. */
+export function captureHealthOutput(stdout, stderr) {
+    const combined = [stderr, stdout]
+        .map(s => (s ?? '').trim())
+        .filter(s => s.length > 0)
+        .join('\n');
+    if (combined.length === 0)
+        return '';
+    let snippet = combined.split('\n').slice(0, HEALTH_OUTPUT_MAX_LINES).join('\n');
+    if (snippet.length > HEALTH_OUTPUT_MAX_CHARS)
+        snippet = `${snippet.slice(0, HEALTH_OUTPUT_MAX_CHARS)}…`;
+    return snippet;
+}
 function packageScripts(cwd) {
     try {
         const j = JSON.parse(readFileSync(path.join(cwd, 'package.json'), 'utf8'));
@@ -103,7 +120,12 @@ export function discoverHealthCommands(cwd) {
 export function runRepoHealthCheck(cwd, timeoutMs = 600_000) {
     const { ecosystem, cmds } = discoverHealthCommands(cwd);
     if (!ecosystem || cmds.length === 0) {
-        return { ok: true, reason: 'no repo-wide static-analysis command found', ecosystem };
+        return {
+            ok: true,
+            reason: 'no repo-wide static-analysis command found',
+            ecosystem,
+            output: ''
+        };
     }
     for (const [bin, args] of cmds) {
         const r = spawnSync(bin, args, { cwd, encoding: 'utf8', timeout: timeoutMs });
@@ -119,9 +141,10 @@ export function runRepoHealthCheck(cwd, timeoutMs = 600_000) {
             return {
                 ok: false,
                 reason: `\`${bin} ${args.join(' ')}\` exited ${r.status}`,
-                ecosystem
+                ecosystem,
+                output: captureHealthOutput(r.stdout, r.stderr)
             };
         }
     }
-    return { ok: true, reason: `${ecosystem}: static checks passed`, ecosystem };
+    return { ok: true, reason: `${ecosystem}: static checks passed`, ecosystem, output: '' };
 }

package/dist/task/task-gates.d.ts

@@ -101,6 +101,7 @@ export interface GateDeps {
     repoHealth?: (cwd: string) => Promise<{
         ok: boolean;
         reason: string;
+        output?: string;
     }>;
     /** Does the working tree hold changes (excluding .pi-tasks)? Lets the pre-commit
      *  health check run only when the enforce pass actually edited something. */
@@ -118,6 +119,29 @@ export interface GateDeps {
      * swallowed by the implementation, never by this sequence.
      */
     record?: (cwd: string, taskId: string, line: string) => Promise<void>;
+    /**
+     * Record a durable ACCEPT-despite-verify-FAIL debt (task id + FAIL reason) to the
+     * run-level ledger (`.pi-tasks/accept-debt.md`, see accept-debt.ts). Called only on
+     * the picker's ACCEPT branch — the human blessed a failing artifact as-is, so the
+     * defect is real and recorded; the final integration gate re-checks it at run end
+     * and surfaces it if still open. Best-effort; absent in tests → no ledger written.
+     */
+    recordAcceptDebt?: (cwd: string, taskId: string, reason: string) => Promise<void>;
+    /**
+     * The concrete paths this task's spec forbids modifying (its `Do NOT modify`
+     * CONSTRAINTS — see frozen-path-guard.ts / prohibition-probe.ts). Used to
+     * write-deny the enforce EDIT pass: a violating edit is reverted before it can
+     * be committed. Empty when the spec froze nothing → the guard is a no-op.
+     * Absent in tests / on a bare `/task` → the guard is skipped.
+     */
+    frozenPaths?: (cwd: string, taskId: string) => Promise<string[]>;
+    /**
+     * Restore the given frozen paths to their committed (HEAD) state, discarding a
+     * gate child's edits to them, and return the files actually reverted. Prompt
+     * framing is A/B-proven insufficient for this class, so the deny is mechanical:
+     * the write is undone, not merely warned about. Absent → the guard warns only.
+     */
+    revertFrozenPaths?: (cwd: string, paths: string[]) => Promise<string[]>;
 }
 /** Inputs the sequence needs that vary per caller. */
 export interface GateParams {

package/dist/task/task-gates.js

@@ -10,6 +10,18 @@ import { SessionUI } from '../remote/bridge.js';
  * regardless of this count (blessing an artifact as-is is a human's call).
  */
 export const MAX_AUTO_AUTOFIX = 3;
+/**
+ * Bound a captured health-check output before it is embedded in a gate-trail line.
+ * appendGateRecord flattens newlines to spaces, so the trail stays one line per
+ * entry; this just caps the volume (a wedged tool can emit megabytes). The health
+ * check already trims to its own first-N lines — this is the trail-side ceiling.
+ */
+const TRAIL_OUTPUT_MAX_CHARS = 1200;
+function clampOutput(output) {
+    return output.length > TRAIL_OUTPUT_MAX_CHARS ?
+        `${output.slice(0, TRAIL_OUTPUT_MAX_CHARS)}…`
+        : output;
+}
 /**
  * Show the boxed two-choice picker after a verify FAIL and return what the user
  * decided. The model-recommended card is placed first so the renderer tints it
@@ -135,6 +147,16 @@ export async function runGatesForTask(ctxIn, deps, p) {
             }
             if (choice.action === 'accept') {
                 await rec('resolution: user ACCEPTED the work despite verify FAIL');
+                // Durable debt: the human blessed a FAILing artifact as-is, so the
+                // defect ships and nothing else revisits it (mx5 run 4 B3 / run 8
+                // TASK_0012). Record it to the run ledger; the final integration gate
+                // re-checks it at run end and surfaces it if still open. Best-effort.
+                try {
+                    await deps.recordAcceptDebt?.(p.cwd, p.taskId, failReason);
+                }
+                catch {
+                    // recording must never break the gate sequence
+                }
                 active.ui.notify(`${p.tag}: accepted "${p.title}" despite verify FAIL (${failReason.slice(0, 120)}) — proceeding.`, 'warning');
                 break;
             }
@@ -202,13 +224,40 @@ export async function runGatesForTask(ctxIn, deps, p) {
     // with no enforce dep.
     if (deps.enforce && commit.committed) {
         const mode = verifyCleanPass ? 'edit' : 'flag';
-        active.ui.notify(mode === 'edit' ?
-            `${p.tag}: enforcing AGENTS.md/CLAUDE.md on "${p.title}"…`
-            : `${p.tag}: reviewing "${p.title}" against AGENTS.md/CLAUDE.md (no verify signal — report only)…`, 'info');
+        // BASELINE repo health, captured BEFORE the edit pass touches the tree, so the
+        // pre-commit gate below is DIFFERENTIAL: it can tell an enforce-CAUSED
+        // regression (was clean, now fails) from a repo that was ALREADY unhealthy
+        // (run-8 F8: five enforce passes were discarded on a lint that was already
+        // crashing — exit 2 — before enforce edited anything; the discard threw away
+        // good work for a fault it did not cause). Only meaningful in edit mode (flag
+        // makes no edits); the task's work is already committed so this reflects the
+        // committed state the pass is about to build on.
+        const healthBefore = mode === 'edit' && deps.repoHealth ? await deps.repoHealth(p.cwd) : undefined;
         const verdict = await deps.enforce(active, p.cwd, p.title, mode);
+        // FROZEN-PATH WRITE-DENY (mechanical, not prompt — the "MUST NOT edit"
+        // instruction is A/B-proven ~0–1/5 reliable on the weak model): the enforce
+        // EDIT pass runs read,edit and has been seen mutating a path the spec froze.
+        // Before its edits are inspected/committed below, restore any frozen path it
+        // touched to the committed task state, so the violating write cannot land in
+        // the ENFORCE GUIDELINES commit regardless of what the model intended. The
+        // task's OWN frozen-path edits (if any) are already in HEAD and are the verify
+        // prohibition-probe's job — this only undoes the gate child's edits on top.
+        // No-op when the spec froze nothing or the deps are absent (bare /task, tests).
+        if (mode === 'edit' && deps.frozenPaths && deps.revertFrozenPaths) {
+            const frozen = await deps.frozenPaths(p.cwd, p.taskId);
+            if (frozen.length > 0) {
+                const reverted = await deps.revertFrozenPaths(p.cwd, frozen);
+                if (reverted.length > 0) {
+                    await rec(`enforce: frozen-path write DENIED — reverted ${reverted.length} spec-frozen file(s) the edit pass modified: ${reverted.join(', ')}`);
+                    active.ui.notify(`${p.tag}: guideline edits on "${p.title}" touched spec-frozen path(s) (${reverted.join(', ').slice(0, 120)}) — reverted before commit.`, 'warning');
+                }
+            }
+        }
         // The child's verdict and its edits are independent facts: the pass has been
         // observed declaring "clean" while having edited files (which then get
         // committed as fixes) — record both so the trail cannot contradict itself.
+        // `editsMade` is read AFTER the frozen-path revert so a pass whose only edit
+        // was to a frozen path correctly shows a clean tree (nothing left to commit).
         const editsMade = mode === 'edit' && deps.dirty ? await deps.dirty(p.cwd) : undefined;
         await rec(`enforce(${mode}): ${verdict.ok ? `clean${verdict.reason ? ` (${verdict.reason})` : ''}` : (verdict.reason ?? 'not clean')}${editsMade ? ' — edits in tree' : ''}`);
         if (!verdict.ok) {
@@ -220,19 +269,40 @@ export async function runGatesForTask(ctxIn, deps, p) {
         // and discards the bad edits outright. Only runs when the tree is actually
         // dirty (or dirtiness is unknowable); the differential guard below still
         // catches behavioral regressions the static check cannot see.
+        //
+        // The gate is DIFFERENTIAL, not absolute (run-8 F8): discard the edits only
+        // when they REGRESSED the health signal — clean before, failing after. A repo
+        // that was already failing before enforce ran is not enforce's fault, so its
+        // edits are KEPT (and the pre-existing failure is recorded, to be caught by the
+        // final integration gate, not blamed on this pass). The failing command's
+        // output is captured into the trail so the discard is explainable — F8 was
+        // unreproducible precisely because only the exit code was recorded.
         let enforceEditsBlocked = false;
         if (mode === 'edit' && deps.repoHealth && editsMade !== false) {
-            const h = await deps.repoHealth(p.cwd);
-            if (!h.ok) {
+            const after = await deps.repoHealth(p.cwd);
+            // A regression needs a clean (or unknown) baseline turning to a fail. If
+            // healthBefore is undefined (repoHealth was absent at baseline time) treat
+            // the baseline as clean — the conservative absolute behavior.
+            const wasHealthyBefore = healthBefore?.ok ?? true;
+            const regressed = !after.ok && wasHealthyBefore;
+            if (regressed) {
                 enforceEditsBlocked = true;
+                const outputTail = after.output ? ` — output:\n${clampOutput(after.output)}` : '';
                 if (deps.discardEdits) {
                     await deps.discardEdits(p.cwd);
-                    await rec(`enforce: edits discarded pre-commit (repo health: ${h.reason})`);
+                    await rec(`enforce: edits discarded pre-commit — REGRESSED repo health (${after.reason})${outputTail}`);
                 }
                 else {
-                    await rec(`enforce: edits FAILED repo health pre-commit (${h.reason}) — no discard available, left uncommitted`);
+                    await rec(`enforce: edits REGRESSED repo health pre-commit (${after.reason}) — no discard available, left uncommitted${outputTail}`);
                 }
-                active.ui.notify(`${p.tag}: guideline edits on "${p.title}" failed repo health (${h.reason.slice(0, 120)}) — discarded before commit.`, 'warning');
+                active.ui.notify(`${p.tag}: guideline edits on "${p.title}" regressed repo health (${after.reason.slice(0, 120)}) — discarded before commit.`, 'warning');
+            }
+            else if (!after.ok) {
+                // Failing both before and after → not enforce's fault. Keep the edits;
+                // record that the repo entered the gate already unhealthy so the trail
+                // explains why a still-failing repo did NOT trigger a discard here.
+                const outputTail = after.output ? ` — output:\n${clampOutput(after.output)}` : '';
+                await rec(`enforce: repo health still failing after edits but was ALREADY failing before the pass (${after.reason}) — pre-existing, edits kept${outputTail}`);
             }
         }
         if (mode === 'edit' && !enforceEditsBlocked && editsMade === false) {

package/dist/workers/pi-worker-docs.js

@@ -8,6 +8,7 @@ import { runChild, CHILD_BASE_ARGS } from '../shared/child-process.js';
 import { parseChildOutput, isExcerptInContent } from '../shared/child-output.js';
 import { getPiInvocation } from '../shared/pi-invocation.js';
 import { formatChildFailure, makeWorkerTool } from './shared.js';
+import { normalizeQuery } from './research-cache.js';
 import { projectDocsRaw, buildProjectPrompt } from './docs-project.js';
 const CHILD_ARGS = [...CHILD_BASE_ARGS, '--no-tools'];
 const RENDER_QUERY_MAX = 100;
@@ -239,6 +240,17 @@ export function registerPiWorkerDocs(pi, internals = {}) {
             text += theme.fg('accent', label);
             text += `\n${theme.fg('dim', `  query: ${truncated}`)}`;
             return new Text(text, 0, 0);
-        }
+        },
+        // Cache npm-package answers per run (a package's installed types/README + latest
+        // version do not change within a run). A project-source `.` lookup is NOT cached:
+        // the working tree mutates as tasks implement, so its answer can go stale mid-run
+        // (the docs SQLite index already keys those on file mtime).
+        cacheKey: params => params.module === '.' ?
+            null
+            : `${normalizeQuery(params.module)}::${normalizeQuery(params.query)}`,
+        // Only a completed lookup (child exited 0) is a real answer; not-installed,
+        // no-chunks, resolve/cache errors, and aborts omit childExitCode:0 and fall
+        // through to a live retry next time.
+        cacheable: d => d.childExitCode === 0
     });
 }

package/dist/workers/pi-worker-fetch.js

@@ -3,6 +3,7 @@ import { Text } from '@earendil-works/pi-tui';
 import { FetchAndCleanError } from './html-clean.js';
 import { fetchFocused, formatResultText } from './fetch-core.js';
 import { formatChildFailure, makeWorkerTool } from './shared.js';
+import { normalizeQuery } from './research-cache.js';
 const RENDER_QUERY_MAX = 100;
 const Params = Type.Object({
     url: Type.String({ description: 'URL to fetch. Must be http or https.' }),
@@ -79,6 +80,14 @@ export function registerPiWorkerFetch(pi, internals = {}) {
             text += theme.fg('accent', args.url);
             text += `\n${theme.fg('dim', `  query: ${truncatedQuery}`)}`;
             return new Text(text, 0, 0);
-        }
+        },
+        // Cache fetch answers per run (the same page re-fetched across sibling tasks
+        // otherwise). The URL is kept verbatim (path case can matter); the query is
+        // normalised. Both parts key the entry — same page, different question is a
+        // different answer.
+        cacheKey: params => `${params.url.trim()}::${normalizeQuery(params.query)}`,
+        // Only a completed fetch (child exited 0) is a real answer; invalid-URL,
+        // fetch failures, and aborts omit childExitCode:0 and fall through.
+        cacheable: d => d.childExitCode === 0
     });
 }

package/dist/workers/pi-worker-search.js

@@ -2,6 +2,7 @@ import { Type } from '@sinclair/typebox';
 import { Text } from '@earendil-works/pi-tui';
 import { search } from './search-core.js';
 import { makeWorkerTool } from './shared.js';
+import { normalizeQuery } from './research-cache.js';
 const Params = Type.Object({
     query: Type.String({ description: 'Search query.' }),
     count: Type.Optional(Type.Integer({
@@ -49,6 +50,13 @@ export function registerPiWorkerSearch(pi, internals = {}) {
                 text += theme.fg('dim', ` (count=${args.count})`);
             }
             return new Text(text, 0, 0);
-        }
+        },
+        // Cache search results per run (the same query re-run across sibling tasks hits
+        // the live web anew otherwise). Count is part of the key — a larger request is a
+        // different result set.
+        cacheKey: params => `${normalizeQuery(params.query)}::${params.count ?? ''}`,
+        // Only a non-empty result set is worth caching; no-key, error, and empty results
+        // (resultCount 0) fall through so a later attempt can succeed.
+        cacheable: d => d.resultCount > 0
     });
 }

package/dist/workers/research-cache.d.ts

@@ -0,0 +1,39 @@
+/** The env var the orchestrator stamps with the per-run id children inherit. */
+export declare const RESEARCH_RUN_ID_ENV = "PI_TASK_RUN_ID";
+export declare function researchCacheFile(cwd: string): string;
+/**
+ * The current run's id, or undefined when caching is off (the orchestrator did not
+ * stamp one for this run). A worker treats undefined as "do not cache".
+ */
+export declare function researchRunId(): string | undefined;
+/** A fresh, per-invocation run token — stable within one run, unique across runs. */
+export declare function newRunToken(): string;
+/**
+ * Orchestrator hook: called once at the start of every /task-auto invocation. When
+ * caching is enabled it stamps a FRESH token (so a long-lived host never reuses a
+ * prior run's token, and planAuto + the task loop of THIS run share one id); when
+ * disabled it clears any token a prior run left, so the workers cache nothing.
+ */
+export declare function configureResearchRun(enabled: boolean): string | undefined;
+/**
+ * Normalise a query/module string for the cache KEY: collapse whitespace and
+ * lowercase, so trivially-varied phrasings of the same question share a digest. The
+ * stored value is the real answer, so a case/spacing collision only means two ways
+ * of asking the same thing resolve to the same (correct) result.
+ */
+export declare function normalizeQuery(s: string): string;
+/**
+ * Look up a cached result for `key` in the current run. Returns undefined on a miss,
+ * a stale-run file (different id ⇒ another run's digest, ignored), or any failure.
+ */
+export declare function lookupResearch(cwd: string, runId: string, key: string): Promise<{
+    text: string;
+    details: unknown;
+} | undefined>;
+/**
+ * Store a successful result under `key` for the current run. A file written for a
+ * different run id is discarded and started fresh (first write of a new run drops the
+ * prior run's contents — self-healing per-run isolation without an explicit clear).
+ * Best-effort: any failure is swallowed, leaving the caller's live result untouched.
+ */
+export declare function storeResearch(cwd: string, runId: string, key: string, text: string, details: unknown): Promise<void>;

package/dist/workers/research-cache.js

@@ -0,0 +1,140 @@
+/**
+ * research-cache — a per-run cache of docs/search/fetch worker RESULTS, shared
+ * across the sibling task pipelines of one /task-auto run.
+ *
+ * The failure this serves (mx5 run 8, F10): the research phase alone burned 75 of
+ * 363 minutes because ~20 sibling task pipelines each re-fetched the SAME external
+ * docs and re-ran the SAME searches (the tailwind CLI docs fetched anew for task
+ * after task). Each of those worker results is a deterministic function of (tool,
+ * package/url, query) that does not change within a run — so the first pipeline to
+ * ask a question can answer every later one from a shared digest instead of a fresh
+ * network round-trip plus child-summariser spawn.
+ *
+ * SCOPE — stable external lookups only: npm-package docs, web search, web fetch. A
+ * PROJECT-SOURCE (`.`) docs lookup is deliberately NOT cached: the working tree
+ * mutates as tasks implement, so a `.` answer from an early task can be stale by a
+ * later one (the docs SQLite index already keys those on file mtime). Only a result
+ * the tool marks successful is cached — an error, an empty result, or an abort is
+ * never memoised, so a transient failure cannot poison the run.
+ *
+ * PER-RUN ISOLATION: the orchestrator stamps a FRESH run id into the environment
+ * (PI_TASK_RUN_ID) at the start of every /task-auto invocation; the research-worker
+ * children inherit it. The cache file records the run id it was written for, and any
+ * read or write for a different id discards the stale contents. So a long-lived host
+ * process running many /task-auto runs never serves one run's digest to another, and
+ * a run started with the feature flag OFF (no id in the environment) does not cache
+ * at all — the cache is inert unless the orchestrator turned it on for this run.
+ *
+ * Stored under `.pi-tasks/` (sibling of env-notes.md / contracts.md), which the
+ * git-state guard and discardEdits both exclude. Best-effort throughout: any I/O or
+ * parse failure falls back to a live fetch — the cache only ever saves time, it can
+ * never change an answer or block a worker.
+ */
+import * as fsp from 'node:fs/promises';
+import * as path from 'node:path';
+import { tasksDir } from '../task/task-io.js';
+const RESEARCH_CACHE_FILE = 'research-cache.json';
+/** The env var the orchestrator stamps with the per-run id children inherit. */
+export const RESEARCH_RUN_ID_ENV = 'PI_TASK_RUN_ID';
+/**
+ * Cap stored entries so a chatty run cannot grow the file unboundedly; the newest
+ * (by write time) are kept. Sized well above a 20-task run's distinct external
+ * lookups (dozens), so a real run never evicts a still-useful digest.
+ */
+const MAX_ENTRIES = 250;
+export function researchCacheFile(cwd) {
+    return path.join(tasksDir(cwd), RESEARCH_CACHE_FILE);
+}
+/**
+ * The current run's id, or undefined when caching is off (the orchestrator did not
+ * stamp one for this run). A worker treats undefined as "do not cache".
+ */
+export function researchRunId() {
+    const v = process.env[RESEARCH_RUN_ID_ENV]?.trim();
+    return v && v.length > 0 ? v : undefined;
+}
+/** A fresh, per-invocation run token — stable within one run, unique across runs. */
+export function newRunToken() {
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+/**
+ * Orchestrator hook: called once at the start of every /task-auto invocation. When
+ * caching is enabled it stamps a FRESH token (so a long-lived host never reuses a
+ * prior run's token, and planAuto + the task loop of THIS run share one id); when
+ * disabled it clears any token a prior run left, so the workers cache nothing.
+ */
+export function configureResearchRun(enabled) {
+    if (!enabled) {
+        delete process.env[RESEARCH_RUN_ID_ENV];
+        return undefined;
+    }
+    const token = newRunToken();
+    process.env[RESEARCH_RUN_ID_ENV] = token;
+    return token;
+}
+/**
+ * Normalise a query/module string for the cache KEY: collapse whitespace and
+ * lowercase, so trivially-varied phrasings of the same question share a digest. The
+ * stored value is the real answer, so a case/spacing collision only means two ways
+ * of asking the same thing resolve to the same (correct) result.
+ */
+export function normalizeQuery(s) {
+    return s.replace(/\s+/g, ' ').trim().toLowerCase();
+}
+async function readCacheFile(cwd) {
+    try {
+        const raw = await fsp.readFile(researchCacheFile(cwd), 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed
+            && typeof parsed === 'object'
+            && typeof parsed.runId === 'string'
+            && typeof parsed.entries === 'object'
+            && parsed.entries !== null) {
+            return parsed;
+        }
+    }
+    catch {
+        // missing or corrupt ⇒ treated as empty
+    }
+    return null;
+}
+/**
+ * Look up a cached result for `key` in the current run. Returns undefined on a miss,
+ * a stale-run file (different id ⇒ another run's digest, ignored), or any failure.
+ */
+export async function lookupResearch(cwd, runId, key) {
+    const file = await readCacheFile(cwd);
+    if (!file || file.runId !== runId)
+        return undefined;
+    const entry = file.entries[key];
+    return entry ? { text: entry.text, details: entry.details } : undefined;
+}
+/**
+ * Store a successful result under `key` for the current run. A file written for a
+ * different run id is discarded and started fresh (first write of a new run drops the
+ * prior run's contents — self-healing per-run isolation without an explicit clear).
+ * Best-effort: any failure is swallowed, leaving the caller's live result untouched.
+ */
+export async function storeResearch(cwd, runId, key, text, details) {
+    try {
+        const existing = await readCacheFile(cwd);
+        const entries = existing && existing.runId === runId ? existing.entries : {};
+        entries[key] = { text, details, at: Date.now() };
+        // Evict oldest by write time if over the cap.
+        const keys = Object.keys(entries);
+        if (keys.length > MAX_ENTRIES) {
+            const ordered = keys.sort((a, b) => entries[a].at - entries[b].at);
+            for (const k of ordered.slice(0, keys.length - MAX_ENTRIES))
+                delete entries[k];
+        }
+        const out = { runId, entries };
+        await fsp.mkdir(tasksDir(cwd), { recursive: true });
+        // Atomic-ish write so a concurrent reader never sees a half-written file.
+        const tmp = `${researchCacheFile(cwd)}.${process.pid}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+        await fsp.writeFile(tmp, JSON.stringify(out), 'utf8');
+        await fsp.rename(tmp, researchCacheFile(cwd));
+    }
+    catch {
+        // best-effort cache
+    }
+}

package/dist/workers/shared.d.ts

@@ -38,6 +38,23 @@ export interface WorkerToolSpec<TParams extends TSchema, TDetails> {
         details: TDetails;
     }>;
     renderCall(args: Static<TParams>, theme: Theme): Text;
+    /**
+     * Per-run research-cache policy (F10). Return a stable cache key for this call —
+     * a result keyed on it is a deterministic function of the inputs that does not
+     * change within a run, so a later sibling task can reuse it instead of re-running
+     * the network fetch + child summariser. Return `null` to opt a particular call
+     * OUT of caching (e.g. a project-source `.` lookup, whose answer the working tree
+     * mutates within a run). Omit entirely and the tool is never cached. The stored
+     * key is namespaced by tool name, so keys need only be unique within a tool.
+     */
+    cacheKey?(params: Static<TParams>): string | null;
+    /**
+     * Whether a produced result is safe to cache. Only a SUCCESS is memoised — an
+     * error, empty, or aborted result must fall through so a transient failure never
+     * poisons the run. Defaults to always-cacheable when omitted (but a tool with a
+     * cacheKey should always supply this).
+     */
+    cacheable?(details: TDetails, text: string): boolean;
 }
 /** Register a worker tool from its spec, supplying the shared registration ritual. */
 export declare function makeWorkerTool<TParams extends TSchema, TDetails>(pi: ExtensionAPI, spec: WorkerToolSpec<TParams, TDetails>): void;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.18.4",
+    "version": "0.18.5",
     "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",