@mjasnikovs/pi-task 0.18.38 → 0.18.39

package/dist/task/auto-orchestrator.js

@@ -1518,13 +1518,15 @@ async function handleTaskAutoResume(_args, ctx) {
     autoRunning = true;
     armTerminalCancel(ctx);
     try {
-        // 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.
+        // Reuse the interrupted run's research-cache id, dropping only the entries whose
+        // own package moved version (F10). mx5 run 13 resumed three times and each
+        // resume's fresh id discarded a working 201-entry cache; run 14 then showed a
+        // whole-file freshness gate can never hold on a greenfield run that installs
+        // packages as it goes, so invalidation is per entry. See resumeResearchRun.
         const research = await resumeResearchRun(cwd, getConfig().researchCache);
         if (research.reused) {
-            logPlanDebug(cwd, `research cache: resume reused ${research.entries} entr(ies)`);
+            logPlanDebug(cwd, `research cache: resume reused ${research.entries} entr(ies), `
+                + `dropped ${research.dropped} stale`);
         }
         const abort = new AbortController();
         // Resume only runs the loop (runTask); no planning children, so the loader

package/dist/workers/pi-worker-docs.d.ts

@@ -5,6 +5,13 @@ import { resolvePackage as defaultResolvePackage } from './docs-resolve.js';
 import { retrieveChunks as defaultRetrieveChunks } from './docs-retrieve.js';
 import { npmVersionLookup as defaultNpmVersionLookup } from './npm-version.js';
 import { type SpawnFn } from '../shared/child-process.js';
+/**
+ * The package NAME a module specifier belongs to — `hono/client` → `hono`,
+ * `@scope/name/sub` → `@scope/name`. The cache stores this (not the raw specifier) as an
+ * entry's package provenance, so a subpath lookup is matched against package.json's key
+ * and invalidated with its package rather than living forever unmatched.
+ */
+export declare function packageRootOf(module: string): string;
 export interface PiWorkerDocsInternals {
     resolvePackage?: typeof defaultResolvePackage;
     ensureIndexed?: typeof defaultEnsureIndexed;

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

@@ -21,6 +21,16 @@ const Params = Type.Object({
         description: 'What to extract from the docs. The child pi reads ranked chunks and returns ONLY content answering this.'
     })
 });
+/**
+ * The package NAME a module specifier belongs to — `hono/client` → `hono`,
+ * `@scope/name/sub` → `@scope/name`. The cache stores this (not the raw specifier) as an
+ * entry's package provenance, so a subpath lookup is matched against package.json's key
+ * and invalidated with its package rather than living forever unmatched.
+ */
+export function packageRootOf(module) {
+    const parts = module.trim().split('/');
+    return parts[0].startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+}
 function pinDetails(pin) {
     return pin ? { versionSource: pin.source, declaredRange: pin.range } : {};
 }
@@ -249,6 +259,12 @@ export function registerPiWorkerDocs(pi, internals = {}) {
         cacheKey: params => params.module === '.' ?
             null
             : `${normalizeQuery(params.module)}::${normalizeQuery(params.query)}`,
+        // Package provenance for per-entry resume invalidation: a docs digest describes
+        // one package at one declared version, so a resume drops it only when THAT
+        // package moves — an unrelated install no longer discards it. Package names are
+        // matched against package.json verbatim (npm names are case-sensitive), unlike
+        // the cache key, which normalises for phrasing collisions.
+        cachePkg: params => (params.module === '.' ? undefined : packageRootOf(params.module)),
         // 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.

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

@@ -23,31 +23,32 @@ export declare function configureResearchRun(enabled: boolean): string | undefin
  */
 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.
+ * The project's declared dependency surface as a name→range map, flattened across every
+ * dependency block (a package listed in two blocks resolves to the first range seen, in
+ * block order — a real manifest does not disagree with itself, and a disagreement can
+ * only make the comparison stricter, i.e. re-fetch).
  *
- * 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.
+ * Returns undefined when the manifest is missing or unparseable: the caller then cannot
+ * prove any package's version and must treat every package-scoped entry as unprovable.
+ * Deliberately NOT the lockfile: it is rewritten by installs that change no resolved
+ * version, which would drop digests for no correctness gain.
  */
-export declare function depsFingerprint(cwd: string): Promise<string | undefined>;
+export declare function depsMap(cwd: string): Promise<Record<string, 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.
+ * Resume hook: keep the interrupted run's cache id and PRUNE the entries the manifest
+ * has invalidated, rather than discarding the whole cache because anything moved. Returns
+ * the id now stamped into the environment (reused or fresh), how many entries survived,
+ * and how many were dropped; undefined id 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.
+ * Falls through to a fresh id only where there is nothing to reuse or nothing to reason
+ * with: caching disabled, no/corrupt cache file, or a file predating per-entry package
+ * provenance (`pkgv`) whose docs entries cannot be told apart from its search entries.
  */
 export declare function resumeResearchRun(cwd: string, enabled: boolean): Promise<{
     runId: string | undefined;
     reused: boolean;
     entries: number;
+    dropped: number;
 }>;
 /**
  * Look up a cached result for `key` in the current run. Returns undefined on a miss,
@@ -61,6 +62,13 @@ export declare function lookupResearch(cwd: string, runId: string, key: string):
  * 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).
+ *
+ * `pkg` is the npm package the answer is ABOUT, supplied by package-scoped tools (docs).
+ * Its declared version is resolved HERE, at store time, so a package installed mid-run
+ * is stamped with the version its own digest was taken against — not with whatever the
+ * manifest happened to say at the run's first write. That is what makes a later resume
+ * able to prune this one entry instead of the whole file.
+ *
  * 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>;
+export declare function storeResearch(cwd: string, runId: string, key: string, text: string, details: unknown, pkg?: string): Promise<void>;

package/dist/workers/research-cache.js

@@ -35,19 +35,38 @@
  * 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.
+ * the digests still describe the same dependency surface.
+ *
+ * PER-PACKAGE INVALIDATION (mx5 run 14). The first shape of that evidence was one md5
+ * over the whole dependency block: any change anywhere ⇒ wipe. That gate can never hold
+ * on the projects /task actually builds — a greenfield run ADDS dependencies every few
+ * tasks (run 14: hono/zod at T10, shadcn at T25, playwright-ct at T28), so all five of
+ * its resumes saw a moved fingerprint and the run ended with ONE cached entry. Adding a
+ * package invalidates nothing that was already cached; only the package a digest is
+ * ABOUT going stale does.
+ *
+ * So invalidation is now per entry. Every docs entry records the package it describes
+ * and the version declared for it at store time (a structured field on the entry, not
+ * something re-parsed out of the key — keys embed the tool name with a \0 separator and
+ * are the wrong place to carry meaning). A resume keeps the run id and drops only the
+ * entries whose package changed version or left the manifest.
+ *
+ * STALENESS TRADE, decided deliberately: search and fetch entries are kept
+ * unconditionally, even across a dependency bump. A kept search result about package X
+ * may describe an older X. That is accepted — docs is the version-sensitive channel (it
+ * is version-pinned to the INSTALLED package since pi-worker fixes #1) and search is
+ * discovery, where re-running every query on every resume costs far more than the rare
+ * staleness costs. A run that must not tolerate it can disable the cache outright.
+ *
+ * A file written before per-entry provenance shipped (no `pkgv` marker) carries no way
+ * to tell its docs entries apart, so it still falls back to a fresh id: 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';
@@ -60,6 +79,12 @@ export const RESEARCH_RUN_ID_ENV = 'PI_TASK_RUN_ID';
  * lookups (dozens), so a real run never evicts a still-useful digest.
  */
 const MAX_ENTRIES = 250;
+/**
+ * Schema marker for per-entry package provenance. A file without it was written by a
+ * version that stored no `pkg` on its entries, so its docs entries are indistinguishable
+ * from its search entries and cannot be pruned selectively ⇒ no reuse.
+ */
+const PKG_PROVENANCE_VERSION = 2;
 export function researchCacheFile(cwd) {
     return path.join(tasksDir(cwd), RESEARCH_CACHE_FILE);
 }
@@ -100,18 +125,17 @@ 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.
+ * The project's declared dependency surface as a name→range map, flattened across every
+ * dependency block (a package listed in two blocks resolves to the first range seen, in
+ * block order — a real manifest does not disagree with itself, and a disagreement can
+ * only make the comparison stricter, i.e. re-fetch).
  *
- * 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.
+ * Returns undefined when the manifest is missing or unparseable: the caller then cannot
+ * prove any package's version and must treat every package-scoped entry as unprovable.
+ * Deliberately NOT the lockfile: it is rewritten by installs that change no resolved
+ * version, which would drop digests for no correctness gain.
  */
-export async function depsFingerprint(cwd) {
+export async function depsMap(cwd) {
     try {
         const raw = await fsp.readFile(path.join(cwd, 'package.json'), 'utf8');
         const pkg = JSON.parse(raw);
@@ -121,49 +145,77 @@ export async function depsFingerprint(cwd) {
             'peerDependencies',
             'optionalDependencies'
         ];
-        const parts = [];
+        const out = {};
         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(',')}`);
+            for (const [name, range] of Object.entries(deps)) {
+                if (typeof range === 'string' && !(name in out))
+                    out[name] = range;
+            }
         }
-        // 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);
+        // No dependency block at all is a real, stable state (a dependency-free repo).
+        return out;
     }
     catch {
         return undefined;
     }
 }
+/** The version declared for `pkg`, or undefined when it is not in the manifest. */
+async function declaredVersion(cwd, pkg) {
+    return (await depsMap(cwd))?.[pkg];
+}
 /**
- * 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.
+ * Is this entry still current against the manifest as it stands now?
  *
- * 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.
+ * - no `pkg` (search/fetch, and docs answers about nothing installable): KEPT — see the
+ *   staleness trade in the file header.
+ * - `pkg` with no recorded version (not in the manifest when stored): KEPT — nothing in
+ *   package.json can have moved under it.
+ * - `pkg` whose declared version is unchanged: KEPT.
+ * - `pkg` whose version moved, which left the manifest, or an unreadable manifest
+ *   (no evidence either way): DROPPED.
+ */
+function entryStillFresh(entry, deps) {
+    if (entry.pkg === undefined || entry.pkgVersion === undefined)
+        return true;
+    return deps?.[entry.pkg] === entry.pkgVersion;
+}
+/**
+ * Resume hook: keep the interrupted run's cache id and PRUNE the entries the manifest
+ * has invalidated, rather than discarding the whole cache because anything moved. Returns
+ * the id now stamped into the environment (reused or fresh), how many entries survived,
+ * and how many were dropped; undefined id when caching is off.
+ *
+ * Falls through to a fresh id only where there is nothing to reuse or nothing to reason
+ * with: caching disabled, no/corrupt cache file, or a file predating per-entry package
+ * provenance (`pkgv`) whose docs entries cannot be told apart from its search entries.
  */
 export async function resumeResearchRun(cwd, enabled) {
     if (!enabled) {
         delete process.env[RESEARCH_RUN_ID_ENV];
-        return { runId: undefined, reused: false, entries: 0 };
+        return { runId: undefined, reused: false, entries: 0, dropped: 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 };
+    if (!file || file.pkgv !== PKG_PROVENANCE_VERSION) {
+        return { runId: configureResearchRun(true), reused: false, entries: 0, dropped: 0 };
     }
-    return { runId: configureResearchRun(true), reused: false, entries: 0 };
+    const deps = await depsMap(cwd);
+    const kept = {};
+    let dropped = 0;
+    for (const [key, entry] of Object.entries(file.entries)) {
+        if (entryStillFresh(entry, deps))
+            kept[key] = entry;
+        else
+            dropped++;
+    }
+    // Persist the pruning now, so a crash between here and the first store cannot leave
+    // stale digests behind under a reused id.
+    if (dropped > 0)
+        await writeCacheFile(cwd, { runId: file.runId, entries: kept, pkgv: file.pkgv });
+    process.env[RESEARCH_RUN_ID_ENV] = file.runId;
+    return { runId: file.runId, reused: true, entries: Object.keys(kept).length, dropped };
 }
 async function readCacheFile(cwd) {
     try {
@@ -193,17 +245,43 @@ export async function lookupResearch(cwd, runId, key) {
     const entry = file.entries[key];
     return entry ? { text: entry.text, details: entry.details } : undefined;
 }
+/** Write the cache file atomic-ish, so a concurrent reader never sees it half-written. */
+async function writeCacheFile(cwd, out) {
+    try {
+        await fsp.mkdir(tasksDir(cwd), { recursive: true });
+        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
+    }
+}
 /**
  * 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).
+ *
+ * `pkg` is the npm package the answer is ABOUT, supplied by package-scoped tools (docs).
+ * Its declared version is resolved HERE, at store time, so a package installed mid-run
+ * is stamped with the version its own digest was taken against — not with whatever the
+ * manifest happened to say at the run's first write. That is what makes a later resume
+ * able to prune this one entry instead of the whole file.
+ *
  * Best-effort: any failure is swallowed, leaving the caller's live result untouched.
  */
-export async function storeResearch(cwd, runId, key, text, details) {
+export async function storeResearch(cwd, runId, key, text, details, pkg) {
     try {
         const existing = await readCacheFile(cwd);
         const entries = existing && existing.runId === runId ? existing.entries : {};
-        entries[key] = { text, details, at: Date.now() };
+        const pkgVersion = pkg === undefined ? undefined : await declaredVersion(cwd, pkg);
+        entries[key] = {
+            text,
+            details,
+            at: Date.now(),
+            ...(pkg === undefined ? {} : { pkg }),
+            ...(pkgVersion === undefined ? {} : { pkgVersion })
+        };
         // Evict oldest by write time if over the cap.
         const keys = Object.keys(entries);
         if (keys.length > MAX_ENTRIES) {
@@ -211,21 +289,7 @@ export async function storeResearch(cwd, runId, key, text, details) {
             for (const k of ordered.slice(0, keys.length - MAX_ENTRIES))
                 delete entries[k];
         }
-        // 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`;
-        await fsp.writeFile(tmp, JSON.stringify(out), 'utf8');
-        await fsp.rename(tmp, researchCacheFile(cwd));
+        await writeCacheFile(cwd, { runId, entries, pkgv: PKG_PROVENANCE_VERSION });
     }
     catch {
         // best-effort cache

package/dist/workers/shared.d.ts

@@ -48,6 +48,14 @@ export interface WorkerToolSpec<TParams extends TSchema, TDetails> {
      * key is namespaced by tool name, so keys need only be unique within a tool.
      */
     cacheKey?(params: Static<TParams>): string | null;
+    /**
+     * The npm package this call's answer is ABOUT, for a package-scoped tool (docs).
+     * Recorded as structured provenance on the cache entry so a resume can drop just the
+     * entries whose package moved version, instead of the whole run's cache (run 14: a
+     * greenfield run adds packages every few tasks, so a whole-file gate never holds).
+     * Omit — or return undefined — and the entry survives every resume of its run.
+     */
+    cachePkg?(params: Static<TParams>): string | undefined;
     /**
      * 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

package/package.json

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