@mjasnikovs/pi-task 0.18.3 → 0.18.5

package/dist/task/test-assembly.d.ts

@@ -0,0 +1,87 @@
+/**
+ * test-assembly — deterministic detection of TEST-REBUILT PRODUCTION WIRING, feeding
+ * the verify gate's prompt (run-8 F4; third recurrence of the test-the-copy class,
+ * runs 3, 4, 8).
+ *
+ * The failure class: a test file re-constructs wiring that ALSO exists in production
+ * — it builds its own app assembly / its own entry point out of the same leaf modules
+ * the production entry composes, then tests THAT private copy. The copy can be wired
+ * differently from production and stay green while the shipped wiring is broken. Run-8
+ * fixture: `test/photos.test.ts` imports the real `authRoutes` + `photosRoutes` leaves,
+ * mounts them into its OWN app at a DIFFERENT prefix than the production entry, and
+ * runs 102/102 green — while the shipped upload path is dead because production mounts
+ * the same leaf at the wrong prefix. The verify child, judging "do the tests pass",
+ * saw green and counted the photos area verified. The seam the test was supposed to
+ * cover is exactly the seam it re-implemented away.
+ *
+ * This is the VERIFY-SIDE complement of the generation-side wiring probe
+ * (wiring-claims.ts, item #5) and shares the load-bearing lesson of
+ * substitution-probe / skip-escape / wiring-claims: a deterministic finding that NAMES
+ * the suspect file is the reliable lever; a bare prompt rule is weak. rule 3b already
+ * tells the child to spot-check that self-authored tests exercise the real artifact,
+ * but F4 slips through because these tests DO import the real leaf modules — they just
+ * bypass the real ASSEMBLY, which rule 3b's "did it import and call the module" check
+ * does not catch. This probe supplies the missing concrete fact.
+ *
+ * THE SIGNAL is pure import-graph SHAPE, zero stack/framework assumptions (no "app",
+ * no "route", no "mount", no language runtime): a test file T is flagged when there is
+ * a production file E (the assembly/entry) such that
+ *   - T does NOT import E (it bypasses the shipped assembly), AND
+ *   - T and E both import ≥2 of the SAME leaf modules, where each such leaf is
+ *     imported by E and by NO OTHER production file (E is the leaf's SOLE production
+ *     composition site).
+ * The "E-exclusive leaf" condition is the crisp discriminator that keeps ordinary
+ * shared-utility imports out: a test importing an api client + a schema module that
+ * every page also imports is NOT re-assembly (those utilities have many production
+ * importers); a test importing two route modules that only the server entry composes
+ * IS re-assembly. Measured on the run-8 fixture tree: flags exactly the four backend
+ * tests that rebuild the server entry's route composition (including the real
+ * photos seam bug) and leaves clean the single-leaf direct test, the utility-sharing
+ * page test, and the source-grepping test — 0 false positives.
+ *
+ * Findings are ADVISORY (probe+rule): they mandate the child to exercise the REAL
+ * shipped assembly directly before counting the area verified; they never auto-FAIL.
+ * A test that re-composes wiring which happens to match production survives once the
+ * child drives the real entry; only one whose real assembly is broken gets named.
+ */
+/** A source file the probe reasons over: repo-relative path + its full text. */
+export interface RepoFile {
+    /** Path relative to the repo root (used verbatim in the finding text). */
+    path: string;
+    /** Full file contents (import statements are parsed out of it). */
+    text: string;
+}
+/** One test file that rebuilds a production assembly instead of importing it. */
+export interface TestAssemblyFinding {
+    /** The test file re-constructing the wiring. */
+    testFile: string;
+    /** The production assembly / entry it bypasses (sole composer of the leaves). */
+    assemblyFile: string;
+    /** The leaf modules (repo-relative, extensionless) the test re-composes. */
+    leaves: string[];
+}
+/** The importing file's OWN module id (path minus extension / `/index`). */
+export declare function moduleIdOf(filePath: string): string;
+/**
+ * The set of repo-relative, extensionless module ids that `text` imports via RELATIVE
+ * specifiers (a specifier starting with `.`). Bare/external specifiers (`hono`,
+ * `bun:sql`, `node:fs`) are ignored — they never name a repo file, so they cannot be
+ * a re-composed production leaf. Resolution is pure path arithmetic against the
+ * importer's directory; the filesystem is never touched.
+ */
+export declare function relativeImports(filePath: string, text: string): string[];
+/**
+ * Find test files that rebuild a production assembly. `changedTestFiles` are the
+ * task's own authored/changed test files (path + text); `productionFiles` are the
+ * repo's non-test source files (path + text) used to build the import graph and the
+ * per-leaf production in-degree. Returns one finding per re-assembling test, sorted
+ * for determinism. Empty when no test re-composes an E-exclusive leaf set.
+ */
+export declare function findTestRebuiltAssemblies(changedTestFiles: RepoFile[], productionFiles: RepoFile[]): TestAssemblyFinding[];
+/**
+ * Render findings as verify-child prompt lines (probe+rule pattern — the concrete
+ * finding that makes the rule fire reliably). One line per re-assembling test naming
+ * the test, the shipped assembly it bypasses, and the re-composed leaves. Empty
+ * findings → empty array (caller emits no block).
+ */
+export declare function testAssemblyVerifyFindings(findings: TestAssemblyFinding[]): string[];

package/dist/task/test-assembly.js

@@ -0,0 +1,163 @@
+/**
+ * test-assembly — deterministic detection of TEST-REBUILT PRODUCTION WIRING, feeding
+ * the verify gate's prompt (run-8 F4; third recurrence of the test-the-copy class,
+ * runs 3, 4, 8).
+ *
+ * The failure class: a test file re-constructs wiring that ALSO exists in production
+ * — it builds its own app assembly / its own entry point out of the same leaf modules
+ * the production entry composes, then tests THAT private copy. The copy can be wired
+ * differently from production and stay green while the shipped wiring is broken. Run-8
+ * fixture: `test/photos.test.ts` imports the real `authRoutes` + `photosRoutes` leaves,
+ * mounts them into its OWN app at a DIFFERENT prefix than the production entry, and
+ * runs 102/102 green — while the shipped upload path is dead because production mounts
+ * the same leaf at the wrong prefix. The verify child, judging "do the tests pass",
+ * saw green and counted the photos area verified. The seam the test was supposed to
+ * cover is exactly the seam it re-implemented away.
+ *
+ * This is the VERIFY-SIDE complement of the generation-side wiring probe
+ * (wiring-claims.ts, item #5) and shares the load-bearing lesson of
+ * substitution-probe / skip-escape / wiring-claims: a deterministic finding that NAMES
+ * the suspect file is the reliable lever; a bare prompt rule is weak. rule 3b already
+ * tells the child to spot-check that self-authored tests exercise the real artifact,
+ * but F4 slips through because these tests DO import the real leaf modules — they just
+ * bypass the real ASSEMBLY, which rule 3b's "did it import and call the module" check
+ * does not catch. This probe supplies the missing concrete fact.
+ *
+ * THE SIGNAL is pure import-graph SHAPE, zero stack/framework assumptions (no "app",
+ * no "route", no "mount", no language runtime): a test file T is flagged when there is
+ * a production file E (the assembly/entry) such that
+ *   - T does NOT import E (it bypasses the shipped assembly), AND
+ *   - T and E both import ≥2 of the SAME leaf modules, where each such leaf is
+ *     imported by E and by NO OTHER production file (E is the leaf's SOLE production
+ *     composition site).
+ * The "E-exclusive leaf" condition is the crisp discriminator that keeps ordinary
+ * shared-utility imports out: a test importing an api client + a schema module that
+ * every page also imports is NOT re-assembly (those utilities have many production
+ * importers); a test importing two route modules that only the server entry composes
+ * IS re-assembly. Measured on the run-8 fixture tree: flags exactly the four backend
+ * tests that rebuild the server entry's route composition (including the real
+ * photos seam bug) and leaves clean the single-leaf direct test, the utility-sharing
+ * page test, and the source-grepping test — 0 false positives.
+ *
+ * Findings are ADVISORY (probe+rule): they mandate the child to exercise the REAL
+ * shipped assembly directly before counting the area verified; they never auto-FAIL.
+ * A test that re-composes wiring which happens to match production survives once the
+ * child drives the real entry; only one whose real assembly is broken gets named.
+ */
+import { isTestFile } from './substitution-probe.js';
+/** Code file extensions whose relative imports we resolve. Not a stack assumption —
+ *  purely which quoted specifiers name a repo file; other languages simply produce
+ *  no matches and the whole probe degrades to nothing. */
+const CODE_EXT_RE = /\.(?:[cm]?[jt]sx?)$/;
+/**
+ * Static import/re-export declarations: `import … from 'x'`, `import 'x'`,
+ * `export … from 'x'`. Anchored to line start (after optional whitespace) so an
+ * import-shaped STRING inside an assertion (`expect(src).toContain("import x from
+ * '../y'")`, a source-grepping test) is NOT mistaken for a real import — that string
+ * is indented behind `expect(`, never at line start.
+ */
+const STATIC_IMPORT_RE = /^[ \t]*(?:import|export)\s+(?:[^'"\n]*\sfrom\s+)?['"]([^'"]+)['"]/gm;
+/** Dynamic `import('x')` / `require('x')` calls (the call-paren form is unlikely to
+ *  appear inside an assertion string, so matching anywhere is safe enough). */
+const CALL_IMPORT_RE = /(?:require|import)\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+/** Strip a code extension and a trailing `/index` so `./a`, `./a.ts`, and
+ *  `./a/index.ts` all collapse to the same module id. */
+function stripToModuleId(p) {
+    return p.replace(CODE_EXT_RE, '').replace(/\/index$/, '');
+}
+/** Normalise a POSIX-style relative path (resolve `.`/`..` segments) without touching
+ *  the filesystem — the analysis is pure text shape. */
+function normalisePosix(p) {
+    const segments = [];
+    for (const seg of p.split('/')) {
+        if (seg === '' || seg === '.')
+            continue;
+        if (seg === '..')
+            segments.pop();
+        else
+            segments.push(seg);
+    }
+    return segments.join('/');
+}
+/** The importing file's OWN module id (path minus extension / `/index`). */
+export function moduleIdOf(filePath) {
+    return stripToModuleId(filePath);
+}
+/**
+ * The set of repo-relative, extensionless module ids that `text` imports via RELATIVE
+ * specifiers (a specifier starting with `.`). Bare/external specifiers (`hono`,
+ * `bun:sql`, `node:fs`) are ignored — they never name a repo file, so they cannot be
+ * a re-composed production leaf. Resolution is pure path arithmetic against the
+ * importer's directory; the filesystem is never touched.
+ */
+export function relativeImports(filePath, text) {
+    const dir = filePath.includes('/') ? filePath.slice(0, filePath.lastIndexOf('/')) : '';
+    const ids = new Set();
+    for (const re of [STATIC_IMPORT_RE, CALL_IMPORT_RE]) {
+        re.lastIndex = 0;
+        for (let m = re.exec(text); m !== null; m = re.exec(text)) {
+            const spec = m[1];
+            if (!spec.startsWith('.'))
+                continue;
+            ids.add(stripToModuleId(normalisePosix(`${dir}/${spec}`)));
+        }
+    }
+    return [...ids];
+}
+/**
+ * Find test files that rebuild a production assembly. `changedTestFiles` are the
+ * task's own authored/changed test files (path + text); `productionFiles` are the
+ * repo's non-test source files (path + text) used to build the import graph and the
+ * per-leaf production in-degree. Returns one finding per re-assembling test, sorted
+ * for determinism. Empty when no test re-composes an E-exclusive leaf set.
+ */
+export function findTestRebuiltAssemblies(changedTestFiles, productionFiles) {
+    // Only genuine production (non-test) files can be the bypassed assembly.
+    const prod = productionFiles.filter(f => !isTestFile(f.path));
+    const prodImports = new Map();
+    const inDegree = new Map();
+    for (const f of prod) {
+        const imps = relativeImports(f.path, f.text);
+        prodImports.set(f.path, new Set(imps));
+        for (const m of imps)
+            inDegree.set(m, (inDegree.get(m) ?? 0) + 1);
+    }
+    const findings = [];
+    for (const t of [...changedTestFiles].sort((a, b) => a.path.localeCompare(b.path))) {
+        if (!isTestFile(t.path))
+            continue;
+        const tImports = new Set(relativeImports(t.path, t.text));
+        if (tImports.size < 2)
+            continue;
+        let best = null;
+        for (const e of [...prod].sort((a, b) => a.path.localeCompare(b.path))) {
+            if (e.path === t.path)
+                continue;
+            // The test imports the real assembly → it is exercising the shipped wiring,
+            // not a copy. Good citizen, never flagged.
+            if (tImports.has(moduleIdOf(e.path)))
+                continue;
+            const eImports = prodImports.get(e.path);
+            // Leaves E is the SOLE production composer of, that this test re-imports.
+            const leaves = [...tImports].filter(m => eImports.has(m) && inDegree.get(m) === 1);
+            if (leaves.length >= 2 && (best === null || leaves.length > best.leaves.length)) {
+                best = { testFile: t.path, assemblyFile: e.path, leaves: leaves.sort() };
+            }
+        }
+        if (best)
+            findings.push(best);
+    }
+    return findings;
+}
+/**
+ * Render findings as verify-child prompt lines (probe+rule pattern — the concrete
+ * finding that makes the rule fire reliably). One line per re-assembling test naming
+ * the test, the shipped assembly it bypasses, and the re-composed leaves. Empty
+ * findings → empty array (caller emits no block).
+ */
+export function testAssemblyVerifyFindings(findings) {
+    return findings.map(f => `${f.testFile} imports and re-composes ${f.leaves.length} leaf module(s) `
+        + `(${f.leaves.join(', ')}) that ${f.assemblyFile} is the ONLY production file to `
+        + `compose, yet it never imports ${f.assemblyFile} — it builds its OWN assembly of `
+        + `those leaves instead of exercising the shipped one`);
+}

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

@@ -61,7 +61,7 @@ export declare function extractSpecForVerification(taskBody: string): string | n
  * Guard: honest-clean fixture (prohibition in spec, probe silent) 5/5 PASS — no
  * paranoia. Reverted-violation ≡ clean at the diff level (no entry → no finding).
  */
-export declare function buildVerifyPrompt(spec: string, probeFindings?: string[], envNotes?: string, prohibitionFindings?: string[], skipEscapeFindings?: string[], contracts?: string): string;
+export declare function buildVerifyPrompt(spec: string, probeFindings?: string[], envNotes?: string, prohibitionFindings?: string[], skipEscapeFindings?: string[], contracts?: string, testAssemblyFindings?: string[], probeGamingFindings?: string[]): string;
 /**
  * Parse the child's verdict. Scans for the LAST `WORK-VERIFIED: PASS|FAIL|UNOBSERVED`
  * marker (the model discusses before concluding, and bash output may echo the word
@@ -114,6 +114,22 @@ export interface VerificationDeps {
      * no-waiver rule (4b). Advisory, never auto-FAIL — real prohibitions can be
      * conditional prose. ABSENT or empty → no prohibition block. */
     prohibitionProbe?: () => Promise<string[]>;
+    /**
+     * DETERMINISTIC test-assembly probe (see test-assembly.ts): authored test files
+     * that rebuild production WIRING — importing the leaf modules the shipped entry
+     * composes and assembling their own copy instead of the real assembly — become
+     * prompt findings under rule 3f (F4 test-the-copy, 3rd recurrence). Pure import-
+     * graph shape; the child then drives the real assembly before trusting the copy.
+     * ABSENT or empty → no test-assembly block. */
+    testAssemblyProbe?: () => Promise<string[]>;
+    /**
+     * DETERMINISTIC probe-gaming probe (see probe-gaming.ts, run-8 F6): added lines
+     * in the task's diff whose stated purpose is to make a CHECK pass instead of
+     * meeting the requirement it stands for ("return 401 so the verification test
+     * passes"). Injected as findings under rule 4c so the child confirms the
+     * underlying requirement is genuinely met rather than trusting the green check.
+     * Pure diff-text analysis; ABSENT or empty → no probe block. */
+    probeGamingProbe?: () => Promise<string[]>;
     /**
      * Result of the git-state guard for the MOST RECENT runChild call (see
      * git-state-guard.ts): did the child mutate repo state (stash/checkout/file

package/dist/task/verify-work.js

@@ -139,7 +139,7 @@ export function extractSpecForVerification(taskBody) {
  * Guard: honest-clean fixture (prohibition in spec, probe silent) 5/5 PASS — no
  * paranoia. Reverted-violation ≡ clean at the diff level (no entry → no finding).
  */
-export function buildVerifyPrompt(spec, probeFindings, envNotes, prohibitionFindings, skipEscapeFindings, contracts) {
+export function buildVerifyPrompt(spec, probeFindings, envNotes, prohibitionFindings, skipEscapeFindings, contracts, testAssemblyFindings, probeGamingFindings) {
     const probeBlock = probeFindings && probeFindings.length > 0 ?
         [
             'SELF-VERIFICATION NOTICE (deterministic, computed by the orchestrator from the diff):',
@@ -166,6 +166,24 @@ export function buildVerifyPrompt(spec, probeFindings, envNotes, prohibitionFind
             ''
         ]
         : [];
+    const probeGamingBlock = probeGamingFindings && probeGamingFindings.length > 0 ?
+        [
+            'CHECK-GAMING NOTICE (deterministic, computed by the orchestrator from the',
+            "task's diff): these added lines state their own purpose is to make a CHECK",
+            'pass (a test / verification / lint / gate), not to meet the requirement the',
+            'check stands for:',
+            ...probeGamingFindings.map(f => `- ${f}`),
+            'A check is a MESSENGER for a requirement. Code written to quiet the messenger',
+            'instead of meeting the requirement is a defect even when the check is green',
+            '(run-8 F6: a handler returned 401 "so the verification test passes" while the',
+            'real route stayed dead). Do NOT accept the passing check as proof. Read each',
+            "line's surrounding code and confirm the UNDERLYING requirement is genuinely",
+            'met — drive the real behavior directly (rule 4c). If the code only exists to',
+            'satisfy the check while the requirement is unmet, that is a FAIL naming the',
+            'gamed check and the unmet requirement.',
+            ''
+        ]
+        : [];
     const skipEscapeBlock = skipEscapeFindings && skipEscapeFindings.length > 0 ?
         [
             "SKIP-ESCAPE NOTICE (deterministic, computed by the orchestrator from the spec's",
@@ -181,6 +199,23 @@ export function buildVerifyPrompt(spec, probeFindings, envNotes, prohibitionFind
             ''
         ]
         : [];
+    const testAssemblyBlock = testAssemblyFindings && testAssemblyFindings.length > 0 ?
+        [
+            'TEST-ASSEMBLY NOTICE (deterministic, computed by the orchestrator from pure',
+            'import-graph shape): these test files rebuild production WIRING — they import the',
+            'same leaf modules the shipped entry composes and assemble their OWN copy of it,',
+            'instead of importing the production assembly:',
+            ...testAssemblyFindings.map(f => `- ${f}`),
+            'A green result on such a test proves that PRIVATE re-assembly, NOT the shipped',
+            'wiring — the copy can be wired differently (a different mount prefix, order, or',
+            'middleware) and pass while production is broken exactly at the seam the test was',
+            'meant to cover (rule 3f below). Before you count the covered area verified, drive',
+            'the behavior against the REAL shipped assembly/entry named above (start or invoke',
+            "the production entry point, not the test's hand-built app). If the real assembly",
+            'fails where the test passes, report FAIL and name the wiring seam.',
+            ''
+        ]
+        : [];
     const envBlock = envNotes && envNotes.trim().length > 0 ? [buildEnvNotesBlock(envNotes)] : [];
     const contractsBlock = contracts && contracts.trim().length > 0 ? [buildContractsVerifyBlock(contracts)] : [];
     return [
@@ -200,7 +235,9 @@ export function buildVerifyPrompt(spec, probeFindings, envNotes, prohibitionFind
         ...contractsBlock,
         ...probeBlock,
         ...prohibitionBlock,
+        ...probeGamingBlock,
         ...skipEscapeBlock,
+        ...testAssemblyBlock,
         'How to verify — verify the REAL, shipped deliverable exactly as an unaided fresh',
         'checkout (or CI run) would experience it:',
         '',
@@ -280,6 +317,20 @@ export function buildVerifyPrompt(spec, probeFindings, envNotes, prohibitionFind
         '   unverified is a FAIL, never a PASS. A wrong-input control exists for every',
         '   artifact — HTTP request, CLI invocation, library call, schema load, config parse.',
         '',
+        '3f. TEST-REBUILT ASSEMBLY: a test proves only the copy if it RE-CONSTRUCTS wiring that',
+        '   also exists in production — assembling its own app / entry point / config out of the',
+        '   same leaf modules the shipped entry composes, instead of importing and exercising the',
+        '   production assembly. Such a test can wire the leaves differently from production (a',
+        '   different prefix, order, adapter, or middleware) and pass green while the SHIPPED',
+        '   wiring is broken at exactly the seam the test was meant to cover — its green result',
+        '   never touched the production assembly at all. Whenever a spec-required behavior is',
+        '   covered ONLY by tests that build their own composition of the real modules, that',
+        '   behavior is UNVERIFIED off those tests: exercise the REAL shipped entry/assembly (run',
+        '   or invoke the production entry point, hit the real composed surface) and judge THAT.',
+        '   If the real assembly fails where the copy passes, report FAIL naming the wiring seam',
+        '   (e.g. "the entry mounts <module> at <X> but the test mounts it at <Y>, so the real',
+        '   path is dead while the test is green").',
+        '',
         '4. Treat the ACCEPTANCE criteria as the bar. If a command fails, or its real output',
         '   contradicts an ACCEPTANCE criterion, the work has NOT verified.',
         '',
@@ -296,6 +347,18 @@ export function buildVerifyPrompt(spec, probeFindings, envNotes, prohibitionFind
         '   for…") that covers the change — judged against that stated exception, not against',
         '   your view of harmlessness.',
         '',
+        '4c. THE CHECK IS THE MESSENGER, NOT THE REQUIREMENT — code (or a comment) whose',
+        '   stated purpose is to make a check PASS, rather than to satisfy the requirement the',
+        '   check stands for, is a defect even when the check is green. The tell is the intent',
+        '   written down: "return X so the test passes", "hardcode this to satisfy the linter",',
+        '   "stub it out to appease CI". When you see such a line — or the CHECK-GAMING NOTICE',
+        '   above names one — do NOT treat the passing check as proof the requirement is met.',
+        '   Find the actual requirement the check was meant to prove and verify THAT directly',
+        '   against the real artifact (rule 3e negative control is the sharpest tool: a handler',
+        '   that answers the check-shaped request the same way for a WRONG input is gaming the',
+        '   check, not implementing the behavior). If the requirement is genuinely unmet while',
+        '   the check passes, the verdict is FAIL naming the gamed check and the real gap.',
+        '',
         '5. The ONLY thing you may assume is already provided is a genuinely EXTERNAL running',
         '   service or network resource (a database server, an API host) that the project',
         '   documents as a prerequisite. Before you rely on that assumption, PROBE for the',
@@ -446,6 +509,28 @@ export async function runWorkVerification(deps) {
             prohibitions = [];
         }
     }
+    // Test-assembly findings feed the prompt (rule 3f); a probe failure must never
+    // block verification — it is an optional sharpener like the substitution probe.
+    let testAssembly = [];
+    if (deps.testAssemblyProbe) {
+        try {
+            testAssembly = await deps.testAssemblyProbe();
+        }
+        catch {
+            testAssembly = [];
+        }
+    }
+    // Probe-gaming findings feed the prompt (rule 4c, F6); a probe failure must never
+    // block verification — an optional sharpener like the other diff-shape probes.
+    let probeGaming = [];
+    if (deps.probeGamingProbe) {
+        try {
+            probeGaming = await deps.probeGamingProbe();
+        }
+        catch {
+            probeGaming = [];
+        }
+    }
     // Environment facts from earlier gate children (best-effort; a cache failure
     // must never block verification).
     let envNotes = '';
@@ -481,7 +566,7 @@ export async function runWorkVerification(deps) {
     for (let attempt = 1;; attempt++) {
         let text;
         try {
-            text = await deps.runChild(VERIFY_TOOLS, buildVerifyPrompt(deps.spec, findings, envNotes, prohibitions, skipEscapes, contracts), deps.signal);
+            text = await deps.runChild(VERIFY_TOOLS, buildVerifyPrompt(deps.spec, findings, envNotes, prohibitions, skipEscapes, contracts, testAssembly, probeGaming), deps.signal);
         }
         catch (err) {
             if (err instanceof Error && err.message === USER_CANCELLED)

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