@mjasnikovs/pi-task 0.18.31 → 0.18.33

package/dist/task/auto-orchestrator.js

@@ -32,7 +32,7 @@ import { describeDebt } from './accept-debt.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, STRANDED_FIX_COMMIT, strandedFixNote } from './final-gate-fix.js';
 import { getConfig } from '../config/config.js';
 import { isYoloMode, yoloPickAnswer, yoloFinalGateChoice, YOLO_STAMP } from './yolo.js';
-import { configureResearchRun } from '../workers/research-cache.js';
+import { configureResearchRun, resumeResearchRun } from '../workers/research-cache.js';
 import { CONTRACT_EXTRACT_PROMPT, parseContractLines, keepGroundedContracts, appendContracts } from './contracts.js';
 import { reconcileTitleSources } from './decompose-fidelity.js';
 import { REQUIREMENT_EXTRACT_PROMPT, COVERAGE_MAP_PROMPT, parseRequirementLines, keepGroundedRequirements, capRequirements, enumerateObligationPassages, uncoveredPassages, extractionRetryHint, parseCoverageMap, accountCoverage, isCrossCuttingRequirement, appendCarriedRequirements, buildRequirementsLedger } from './requirements.js';
@@ -1396,9 +1396,14 @@ 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);
+    // Reuse the interrupted run's research-cache id when the cache proves it still
+    // describes the same dependency surface (F10). mx5 run 13 resumed three times and
+    // each resume's fresh id discarded a working 201-entry cache; anything inconclusive
+    // still falls back to a fresh id and a re-fetch. See resumeResearchRun.
+    const research = await resumeResearchRun(cwd, getConfig().researchCache);
+    if (research.reused) {
+        logPlanDebug(cwd, `research cache: resume reused ${research.entries} entr(ies)`);
+    }
     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/workers/docs-retrieve.js

@@ -3,11 +3,23 @@ const DEFAULT_BUDGET = 24_000;
 const MIN_TOKEN_LEN = 2;
 const FALLBACK_DTS_CHARS = 12_000;
 const FALLBACK_README_CHARS = 4_000;
+/**
+ * Split on any run of non-identifier characters — NOT on whitespace alone.
+ *
+ * Splitting on /\s+/ and then stripping punctuation INSIDE each token silently welds
+ * multi-part identifiers into one string that occurs nowhere in the corpus:
+ *   "src/server/routes/auth.ts"  ->  "srcserverroutesauthts"
+ *   "Bun.password.hash"          ->  "Bunpasswordhash"
+ * Because buildFtsQuery ORs the tokens, such a token contributes no MATCH at all, so the
+ * single most informative term in the query — the path, or the dotted API symbol — was
+ * dropped and ranking fell to the surrounding prose. Measured on the 141 real project
+ * queries of mx5 run 13, that cost 18% of them any chunk from the file they named
+ * (82% -> 99% retrieved once split on punctuation); on the 44 gradable npm queries,
+ * discriminative-symbol recall 89.5% -> 96.4%.
+ * See scripts/live-project-docs-retrieval-ab.ts and scripts/live-npm-tokenizer-regression.ts.
+ */
 function tokenize(query) {
-    return query
-        .split(/\s+/)
-        .map(t => t.replace(/[^a-zA-Z0-9_]/g, ''))
-        .filter(t => t.length >= MIN_TOKEN_LEN);
+    return query.split(/[^a-zA-Z0-9_]+/).filter(t => t.length >= MIN_TOKEN_LEN);
 }
 function buildFtsQuery(tokens) {
     return tokens.map(t => `"${t}"`).join(' OR ');

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

@@ -22,6 +22,33 @@ export declare function configureResearchRun(enabled: boolean): string | undefin
  * of asking the same thing resolve to the same (correct) result.
  */
 export declare function normalizeQuery(s: string): string;
+/**
+ * A stable fingerprint of the project's declared dependency surface — the only input a
+ * cached docs digest actually depends on (a digest summarises a package's INSTALLED
+ * types/README at a pinned version). Built from package.json's dependency blocks with
+ * keys sorted, so formatting churn or an unrelated field edit does not invalidate it,
+ * while any add/remove/version-bump does.
+ *
+ * Returns undefined when the manifest is missing or unparseable — the caller then has
+ * NO positive evidence of freshness and must not reuse. Deliberately NOT the lockfile's
+ * hash or mtime: a lockfile is rewritten by installs that do not change any resolved
+ * version, which would defeat reuse for no correctness gain.
+ */
+export declare function depsFingerprint(cwd: string): Promise<string | undefined>;
+/**
+ * Resume hook: reuse the interrupted run's cache id when — and only when — the file
+ * proves it describes the same dependency surface. Returns the id now stamped into the
+ * environment (reused or fresh), or undefined when caching is off.
+ *
+ * Every uncertain path falls through to a fresh id, which merely re-fetches:
+ * caching disabled, no/corrupt cache file, a file with no fingerprint (written before
+ * this shipped), an unreadable manifest, or a fingerprint that no longer matches.
+ */
+export declare function resumeResearchRun(cwd: string, enabled: boolean): Promise<{
+    runId: string | undefined;
+    reused: boolean;
+    entries: number;
+}>;
 /**
  * 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.

package/dist/workers/research-cache.js

@@ -25,11 +25,29 @@
  * 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.
  *
+ * RESUME REUSE (mx5 run 13, measured from the file's own git history — the cache is
+ * committed with every task, so the whole run is recoverable): a 32-task run built the
+ * cache to 201 entries over 20 tasks under one run id, then three /task-auto-resume
+ * invocations each stamped a fresh id and the first store of each dropped everything —
+ * 201 → 11 → 3 → 5 → 8. The audit read the 8-entry tail and concluded the cache was
+ * near-useless; it was in fact working, and the resume threw the work away. The old
+ * comment called a resume re-fetch "only slightly less reuse", which holds for a
+ * 5-task run and fails badly for a 32-task one.
+ *
+ * So a resume now REUSES the interrupted run's id — but only on POSITIVE evidence that
+ * the digests still describe the same dependency surface. The staleness that matters is
+ * a package version moving under a cached answer (a docs digest summarises the
+ * INSTALLED types of a pinned package), so the file records a fingerprint of the
+ * manifest's dependency block and a resume reuses the id only when that fingerprint is
+ * unchanged. Missing, unparseable, or fingerprint-less file ⇒ fresh id and a re-fetch:
+ * every inconclusive path costs time, never correctness.
+ *
  * 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 { createHash } from 'node:crypto';
 import * as fsp from 'node:fs/promises';
 import * as path from 'node:path';
 import { tasksDir } from '../task/task-io.js';
@@ -81,6 +99,72 @@ export function configureResearchRun(enabled) {
 export function normalizeQuery(s) {
     return s.replace(/\s+/g, ' ').trim().toLowerCase();
 }
+/**
+ * A stable fingerprint of the project's declared dependency surface — the only input a
+ * cached docs digest actually depends on (a digest summarises a package's INSTALLED
+ * types/README at a pinned version). Built from package.json's dependency blocks with
+ * keys sorted, so formatting churn or an unrelated field edit does not invalidate it,
+ * while any add/remove/version-bump does.
+ *
+ * Returns undefined when the manifest is missing or unparseable — the caller then has
+ * NO positive evidence of freshness and must not reuse. Deliberately NOT the lockfile's
+ * hash or mtime: a lockfile is rewritten by installs that do not change any resolved
+ * version, which would defeat reuse for no correctness gain.
+ */
+export async function depsFingerprint(cwd) {
+    try {
+        const raw = await fsp.readFile(path.join(cwd, 'package.json'), 'utf8');
+        const pkg = JSON.parse(raw);
+        const blocks = [
+            'dependencies',
+            'devDependencies',
+            'peerDependencies',
+            'optionalDependencies'
+        ];
+        const parts = [];
+        for (const block of blocks) {
+            const deps = pkg[block];
+            if (!deps || typeof deps !== 'object')
+                continue;
+            const entries = Object.entries(deps)
+                .filter(([, v]) => typeof v === 'string')
+                .sort(([a], [b]) => a < b ? -1
+                : a > b ? 1
+                    : 0)
+                .map(([k, v]) => `${k}@${String(v)}`);
+            if (entries.length > 0)
+                parts.push(`${block}:${entries.join(',')}`);
+        }
+        // No dependency block at all is a real, stable state (a dependency-free repo) —
+        // fingerprint it as such rather than failing, so reuse still works there.
+        return createHash('sha256').update(parts.join('|')).digest('hex').slice(0, 32);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resume hook: reuse the interrupted run's cache id when — and only when — the file
+ * proves it describes the same dependency surface. Returns the id now stamped into the
+ * environment (reused or fresh), or undefined when caching is off.
+ *
+ * Every uncertain path falls through to a fresh id, which merely re-fetches:
+ * caching disabled, no/corrupt cache file, a file with no fingerprint (written before
+ * this shipped), an unreadable manifest, or a fingerprint that no longer matches.
+ */
+export async function resumeResearchRun(cwd, enabled) {
+    if (!enabled) {
+        delete process.env[RESEARCH_RUN_ID_ENV];
+        return { runId: undefined, reused: false, entries: 0 };
+    }
+    const file = await readCacheFile(cwd);
+    const current = await depsFingerprint(cwd);
+    if (file && file.deps !== undefined && current !== undefined && file.deps === current) {
+        process.env[RESEARCH_RUN_ID_ENV] = file.runId;
+        return { runId: file.runId, reused: true, entries: Object.keys(file.entries).length };
+    }
+    return { runId: configureResearchRun(true), reused: false, entries: 0 };
+}
 async function readCacheFile(cwd) {
     try {
         const raw = await fsp.readFile(researchCacheFile(cwd), 'utf8');
@@ -127,7 +211,16 @@ export async function storeResearch(cwd, runId, key, text, details) {
             for (const k of ordered.slice(0, keys.length - MAX_ENTRIES))
                 delete entries[k];
         }
-        const out = { runId, entries };
+        // Stamp the dependency surface these entries were produced against, so a later
+        // resume can prove they are still fresh. Unreadable manifest ⇒ field omitted,
+        // which reads as "cannot prove freshness" and simply denies reuse.
+        //
+        // FROZEN at the run's first write, deliberately: if a task installs a package
+        // mid-run and we re-fingerprinted here, the new fingerprint would bless digests
+        // taken BEFORE the install as current. Keeping the original means a mid-run
+        // install makes a later resume mismatch and re-fetch — the safe direction.
+        const deps = existing && existing.runId === runId ? existing.deps : await depsFingerprint(cwd);
+        const out = deps === undefined ? { runId, entries } : { runId, entries, deps };
         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`;

package/package.json

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