@mjasnikovs/pi-task 0.40.0 → 0.40.2

package/README.md

@@ -9,7 +9,7 @@
 [![npm](https://img.shields.io/npm/v/@mjasnikovs/pi-task?color=cb3837&logo=npm)](https://www.npmjs.com/package/@mjasnikovs/pi-task)
 [![license](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](./LICENSE)
 [![pi extension](https://img.shields.io/badge/pi-extension-7c3aed)](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)
-[![tests](https://img.shields.io/badge/tests-4118%20passing-3fb950)](#development)
+[![tests](https://img.shields.io/badge/tests-4280%20passing-3fb950)](#development)
 [![types](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)](./tsconfig.json)
 
 </div>
@@ -66,7 +66,7 @@ A whole plan — `/task-auto` splits it into an ordered task list and runs each
 | --- | --- |
 | `/task <prompt>` | Start a new task and run it through the full pipeline. |
 | `/task-plan <prompt>` | Plan one task with the model — it asks, you answer, ask it something back, or proceed — then run it through `/task`. |
-| `/task-list` | Open the task list in an editor dialog. |
+| `/task-list` | Show a table of tasks in `.pi-tasks/` — id, state, phase, date, title — newest first, with a resume hint. |
 | `/task-resume [id]` | Resume the most recent (or named) unfinished task. |
 | `/task-cancel` | Stop the running task at the next safe checkpoint (still resumable). Mid-phase it kills the running child; during the implementation turn it lets the turn finish and stops before the gates. |
 | `/task-auto <feature>` | Plan a feature into a task list and run each title through `/task` in order (resumable). |
@@ -171,7 +171,7 @@ VAPID keys are generated once and persisted to `${XDG_DATA_HOME:-~/.local/share}
 `pi-task` also registers four MCP-style worker tools (formerly `@mjasnikovs/pi-worker`). All are parallel-execution-capable, so the parent session can issue several calls in one turn.
 
 ### `pi-worker`
-Spawns an isolated child `pi --print` session with read + bash tools. Use it for noisy file/code work that would otherwise flood the main context.
+Spawns an isolated child `pi --print` session with read-only tools (`read`, `grep`, `find`, `ls` — no bash, no writes). Use it for noisy file/code work that would otherwise flood the main context.
 
 ### `pi-worker-search`
 Runs a web search and returns a compact markdown list (title · URL · snippet). Use it to discover candidate URLs before fetching. The search engine is set in `/task-config` (default: **Exa**):
@@ -228,7 +228,7 @@ Run `/task-config` to toggle pi-task's behavior in an editor dialog. Settings pe
 | **stuck reply retry** | 10 min | Inactivity ceiling on the **model stream**. A hung or silently-dropped stream throws nothing at all, so neither the connection-error retry (it needs a reported error) nor the **command timeout** (tool calls only) nor the dead-backend stall guard (a reachable endpoint reads as proof of life) can see it — an mx5 run lost ~2.9h to three of them while the model server stayed healthy. Measured as time since the **last stream event of any kind**, so a slow model emitting one token every 30s is never touched, and it pauses while a tool runs. On expiry the main session aborts the turn (through the same channel the command watchdog uses) and posts a resume reminder; a child is killed and routed into the existing connection-error retry. Choices: 5/10/20/30 min or **off**. Keep it generous on local backends — prompt processing on a large context legitimately emits nothing for minutes. |
 | **yolo mode** | off | **Unattended runs.** Wherever pi-task would stop and ask, it takes the option already marked RECOMMENDED, stamps the artifact `(YOLO)` so an audit can tell a machine decided, and shows no prompt at all — clarify/grill answers, the verify-FAIL picker (auto-**Accept**, recorded as a yolo debt), and the final-gate picker (autofix while the budget lasts, then leave the run FAILED). A question with no recommendation is **skipped**, never invented. For throwaway/test projects nobody is watching; a real run should decide these itself. |
 | **profile** | default | How much the helper sessions think, in one word, for every step at once. Local models differ sharply here: some break without reasoning, some waste minutes with it, and some cannot do it at all. **default** uses the per-step table pi-task has measured, **on** and **off** force one answer everywhere and ignore that table, and **custom** is whatever the step rows say — changing any of them switches this to custom. A step on **inherit** passes no flag at all, so it uses whatever thinking level pi itself is set to, which is what every step did before this setting existed. |
-| **steps: …** | all `inherit` | One row per group of steps, carrying BOTH dials: the model those children run on and the level they think at, shown as `level · model`. Enter walks a two-step picker — model first, then level — and **the level step offers only what that model declares, opening on the one that will actually run**. That is the whole point of the merge: pi silently CLAMPS a level a model cannot do (a level you set can be erased, and an `off` can be clamped back up to `medium`), so instead of discovering that later you watch the cursor land on the level you are really getting. Models are offered from `pi.modelRegistry.getAvailable()` and stored as the canonical `provider/id` that pi's own `--model` takes. **inherit** on the model half emits no flag, so an all-inherit table is byte-identical to a build without this feature; that is the shipped default, because which models exist is a property of your machine and nothing here can be measured for you. A stored model this machine cannot resolve is never erased (you may have set it on another machine): the flag is dropped, the step runs on pi's default, and a startup hint names the step. Two need care — a provider registered by a host **extension** needs that extension enabled under **ext: …** or those children exit 1; and **implementation** is not free, because it is *your* session moved for the turn and moved back, and a model switch re-bills the whole prompt as a cache miss, twice per task. |
+| **steps: …** | models `inherit`; levels per the shipped table | One row per group of steps, carrying BOTH dials: the model those children run on and the level they think at, shown as `level · model`. Enter walks a two-step picker — model first, then level — and **the level step offers only what that model declares, opening on the one that will actually run**. That is the whole point of the merge: pi silently CLAMPS a level a model cannot do (a level you set can be erased, and an `off` can be clamped back up to `medium`), so instead of discovering that later you watch the cursor land on the level you are really getting. Models are offered from `pi.modelRegistry.getAvailable()` and stored as the canonical `provider/id` that pi's own `--model` takes. **inherit** on the model half emits no flag, so an all-inherit table is byte-identical to a build without this feature; that is the shipped default, because which models exist is a property of your machine and nothing here can be measured for you. A stored model this machine cannot resolve is never erased (you may have set it on another machine): the flag is dropped, the step runs on pi's default, and a startup hint names the step. Two need care — a provider registered by a host **extension** needs that extension enabled under **ext: …** or those children exit 1; and **implementation** is not free, because it is *your* session moved for the turn and moved back, and a model switch re-bills the whole prompt as a cache miss, twice per task. |
 | **debug logs** | events | How much of a run is written to `.pi-tasks/*-debug.log`. **`events`** keeps decisions and guard actions — which phase ran, why a worker was retried, what the git-state guard restored, what a write-capable child changed on disk, why a gate returned FAIL — a few lines per task. **`full`** adds every line the child model emitted and every tool result; that's ~85% of the bytes (a real 247 KB `verify-debug.log` is 1315 lines, 521 of them tool dumps) and is what you want while actively debugging. **`off`** writes nothing. Nothing in pi-task ever reads these files back, so the setting cannot change how a run behaves — only whether you can explain it afterwards, and a log not written can't be recovered later. |
 | **watch: …** | all on | One toggle per tool in the live session, deciding whether **command timeout** applies to it. The list is discovered from `pi.getAllTools()` when the menu opens — built-ins first, then each extension's tools with the owning entry-point path in the description — so nothing is typed by hand and an uninstalled tool just stops being listed. Turn one **off** only for a tool that already owns a longer bounded, cancellable contract of its own (the guard exists because pi's `bash` has an optional timeout with *no* default — that reasoning doesn't transfer to a tool that has one). Two things to know before you do: a genuine hang in an unwatched tool is caught by nothing, since **stuck reply retry** is paused for the whole time any tool runs; and an unwatched tool is still killed as collateral if a *watched* sibling in the same turn overruns, because pi runs sibling tool calls concurrently and the abort ends the whole turn. Stored as exemptions, so the default and every tool pi-task has never seen stay guarded. |
 | **ext: …** | all off | One toggle per installed host `pi` extension, loading it into every child session by explicit path. Children otherwise run with extensions off, so a provider registered by an extension (e.g. `pi-lmstudio`) doesn't exist in them and they can't resolve the default model. Children also inherit the extension's tools and hooks, so only enable ones you trust. The list is strictly additive (discovery stays off), and an entry whose file is gone is skipped at spawn time, never fatal. |
@@ -259,12 +259,12 @@ them checked in.
 
 ```sh
 bun install
-bun run test       # 4119 tests across 227 files
+bun run test       # 4281 tests across 234 files
 bun run lint       # prettier + eslint + tsc --noEmit
 bun run build      # tsc → dist/
 ```
 
-Built with [Bun](https://bun.sh), TypeScript (strict), and [TypeBox](https://github.com/sinclairzx81/typebox) for tool schemas. Design docs and plans live in [`docs/`](./docs).
+Built with [Bun](https://bun.sh), TypeScript (strict), and [TypeBox](https://github.com/sinclairzx81/typebox) for tool schemas. Design plans live in [`plans/`](./plans).
 
 ## License
 

package/dist/task/enrichment.d.ts

@@ -6,8 +6,21 @@
  * denylisted shell names are dropped, a URL's trailing sentence punctuation is
  * stripped, docs targets stop at ENRICH_CAP while version targets continue to
  * ENRICH_VERSION_CAP, and the version list is a strict superset of the docs list.
+ *
+ * Package extraction is additionally gated on the caller's declared dependencies;
+ * see the `declared` parameter on {@link extractEnrichTargets}.
+ */
+export declare function extractEnrichTargets(text: string, 
+/**
+ * The project's declared dependencies. A backticked name outside this set is
+ * not enriched: the model backticks filenames (`config.ts`, `tsconfig.json`)
+ * and field names (`name`, `port`) far more often than package names, and each
+ * of those is also a real, unrelated package on the public registry — so the
+ * permissive read fetched and indexed a stranger's code under the project's
+ * own filename. Omit when the manifest is unreadable, which is not the same
+ * fact as "declares nothing".
  */
-export declare function extractEnrichTargets(text: string): {
+declared?: ReadonlySet<string>): {
     /** Packages that get a (heavy) docs fetch — capped at ENRICH_CAP. */
     packages: string[];
     /**

package/dist/task/enrichment.js

@@ -6,6 +6,9 @@
  * denylisted shell names are dropped, a URL's trailing sentence punctuation is
  * stripped, docs targets stop at ENRICH_CAP while version targets continue to
  * ENRICH_VERSION_CAP, and the version list is a strict superset of the docs list.
+ *
+ * Package extraction is additionally gated on the caller's declared dependencies;
+ * see the `declared` parameter on {@link extractEnrichTargets}.
  */
 const ENRICH_PKG_RE = /`((?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*)`/g;
 const ENRICH_URL_RE = /https?:\/\/[^\s)`>]+/g;
@@ -79,13 +82,25 @@ function parseServices(text) {
     }
     return out;
 }
-export function extractEnrichTargets(text) {
+export function extractEnrichTargets(text, 
+/**
+ * The project's declared dependencies. A backticked name outside this set is
+ * not enriched: the model backticks filenames (`config.ts`, `tsconfig.json`)
+ * and field names (`name`, `port`) far more often than package names, and each
+ * of those is also a real, unrelated package on the public registry — so the
+ * permissive read fetched and indexed a stranger's code under the project's
+ * own filename. Omit when the manifest is unreadable, which is not the same
+ * fact as "declares nothing".
+ */
+declared) {
     const pkgs = [];
     const seen = new Set();
     for (const m of text.matchAll(ENRICH_PKG_RE)) {
         const t = m[1];
         if (ENRICH_DENYLIST.has(t) || seen.has(t))
             continue;
+        if (declared && !declared.has(t))
+            continue;
         seen.add(t);
         pkgs.push(t);
         if (pkgs.length >= ENRICH_VERSION_CAP)

package/dist/task/external-context.d.ts

@@ -83,6 +83,18 @@ export interface ExternalContextPolicy {
     targetCap?: number;
     /** Max services fanned out. Omit for uncapped; the auto-answer path caps at 2. */
     serviceCap?: number;
+    /**
+     * Fan named packages out to a docs body. The RESEARCH path does not, and the
+     * auto-answer path does.
+     *
+     * Research retrieves against `refined.split('\n')[0]` — the literal word
+     * "GOAL" for every refined spec — so its bodies are whatever ranks against
+     * that, pasted raw. The live run of 2026-09-05 found no research output
+     * citing one, while the model's own docs tool answered 49 real questions
+     * across the same three runs. The auto-answer path asks a focused child an
+     * actual question, which is the shape that works.
+     */
+    packageDocs?: boolean;
     /**
      * A cheap live version lookup for every named dep that did NOT get a docs
      * target, so a version block exists for ALL of them. Omit to disable, as the

package/dist/task/external-context.js

@@ -22,7 +22,7 @@
  * Run against a mixed source, the emitted headings come out in exactly that order:
  * `### npm:` then `### docs:` then `### url:` then `### service:`.
  */
-import { chooseEcosystem, defaultEcosystemIo } from '../workers/docs-ecosystems.js';
+import { chooseEcosystem, declaredDepNames, defaultEcosystemIo } from '../workers/docs-ecosystems.js';
 import { docsRaw } from '../workers/docs-core.js';
 import { fetchRaw } from '../workers/fetch-core.js';
 import { formatNpmVersionSection, npmVersionLookup } from '../workers/npm-version.js';
@@ -39,18 +39,24 @@ const RAW_BODY_LIMIT = 4000;
  */
 export async function buildExternalContext(source, deps, lookups, policy = {}) {
     const searchFn = lookups.search ?? defaultSearch;
-    const enrichTargets = extractEnrichTargets(source);
+    const enrichTargets = extractEnrichTargets(source, declaredDepNames(deps.cwd));
     // Packages lead urls, then the combined cap applies — so a capped run spends
     // its budget on named deps first. Uncapped, this is just "packages, then urls".
+    const docsPackages = policy.packageDocs === false ? [] : enrichTargets.packages;
     const targets = [
-        ...enrichTargets.packages.map(name => ({ kind: 'pkg', name })),
+        ...docsPackages.map(name => ({ kind: 'pkg', name })),
         ...enrichTargets.urls.map(name => ({ kind: 'url', name }))
     ].slice(0, policy.targetCap ?? Number.POSITIVE_INFINITY);
     const services = enrichTargets.services.slice(0, policy.serviceCap ?? Number.POSITIVE_INFINITY);
     const versionLookup = policy.versionLookup;
     const docsTargets = new Set(targets.filter(t => t.kind === 'pkg').map(t => t.name));
     const extraVersionPkgs = versionLookup ? enrichTargets.versionPackages.filter(p => !docsTargets.has(p)) : [];
-    if (policy.earlyReturnOnNoTargets && targets.length === 0 && services.length === 0)
+    // Version packages count as work here: with `packageDocs: false` a named dep
+    // produces no target at all, and returning early would drop its version block.
+    if (policy.earlyReturnOnNoTargets
+        && targets.length === 0
+        && services.length === 0
+        && extraVersionPkgs.length === 0)
         return '';
     const startedAt = Date.now();
     const [targetResults, serviceResults, extraVersionResults] = await Promise.all([
@@ -191,6 +197,7 @@ export async function gatherExternalContext(refined, deps) {
         search: deps.searchFn
     }, {
         versionLookup,
+        packageDocs: false,
         subStepLabel: 'enrichment',
         earlyReturnOnNoTargets: true
     });

package/dist/workers/docs-core.js

@@ -128,9 +128,32 @@ export function findDeclaredRange(parentPkg, cwd) {
  * does or does not say has to be a sentence about `bun`.
  */
 export function buildVersionBanner(pin, resolved, version, cwd, profile = ECOSYSTEMS.npm) {
+    const asked = pin?.asked ?? resolved;
+    // Resolvable is not usable. A lock file, a cabal plan and `node_modules` are
+    // all the transitive CLOSURE, so the tool can answer in full confidence about
+    // a package the project may not import. That is what made the Rust run of
+    // 2026-09-05 a hard fail: a correct `tower::util::ServiceExt` answer, the
+    // import written, and E0433 "cannot find module or crate tower" from the compiler.
+    const undeclared = undeclaredNotice(asked, cwd, profile);
     if (!pin)
+        return undeclared;
+    return undeclared + pinBanner(pin, asked, resolved, version, cwd, profile);
+}
+/**
+ * The one sentence a package present-but-not-declared needs, or `''` when it is
+ * declared or when no manifest could be read.
+ */
+function undeclaredNotice(asked, cwd, profile) {
+    const declared = profile.manifestDeps(cwd);
+    const root = profile.parentPackage(asked);
+    if (!declared || declared.has(root) || declared.has(asked))
         return '';
-    const asked = pin.asked ?? resolved;
+    return (`[DEPENDENCY] "${root}" is present in this project but is not a declared `
+        + `dependency in ${profile.manifestLabel} — it resolves only because something `
+        + `else pulled it in. Add it to ${profile.manifestLabel} before importing it, or `
+        + `the build will not find it.\n\n`);
+}
+function pinBanner(pin, asked, resolved, version, cwd, profile) {
     const grounded = resolved !== asked ? ` The types this answer reads come from ${resolved}.` : '';
     const manifest = profile.manifestLabel;
     const registry = profile.registryLabel;
@@ -485,7 +508,8 @@ function docsRawCached(cache, pkg, profile, query, ensureIndexed, retrieveChunks
             version: pkg.version,
             query,
             limit: DEFAULT_LIMIT,
-            contentBudget: DEFAULT_BUDGET
+            contentBudget: DEFAULT_BUDGET,
+            typeKeywords: profile.typeKeywords
         });
     }
     catch (err) {

package/dist/workers/docs-ecosystems.d.ts

@@ -84,6 +84,11 @@ export interface EcosystemProfile {
     surface: (content: string) => string;
     /** Where a declaration begins, so a chunk never splits a signature. */
     declSplitRe: RegExp;
+    /**
+     * The keywords that INTRODUCE a named type in this language, for finding the
+     * chunk that defines a name rather than the many that use it.
+     */
+    typeKeywords: readonly string[];
     /** Line-comment marker, used to label a chunk with the file it came from. */
     commentPrefix: string;
     /** Directories the surface walk never descends into: tests, build output. */
@@ -105,6 +110,15 @@ export interface EcosystemProfile {
      * package's version, which is a different fact from "declares nothing".
      */
     declaredDeps: (cwd: string) => Record<string, string> | undefined;
+    /**
+     * The names the MANIFEST itself declares — what the project may import.
+     *
+     * Distinct from {@link declaredDeps}, which for cargo and hackage reads a
+     * lock or plan file: that is the whole transitive closure, so it answers
+     * "does this resolve" and not "may this be used". Undefined when there is no
+     * readable manifest, which is not the same fact as "declares nothing".
+     */
+    manifestDeps: (cwd: string) => Set<string> | undefined;
 }
 /** Overrides a caller has already been given its own copies of. */
 export interface NpmProfileHooks {
@@ -134,6 +148,12 @@ export declare const ECOSYSTEMS: {
 };
 /** Which ecosystems `cwd` looks like a project of, in roster order. */
 export declare function detectEcosystems(cwd: string, roster?: readonly EcosystemProfile[]): EcosystemId[];
+/**
+ * Every dependency `cwd`'s manifests declare, across the ecosystems it is a
+ * project of. Undefined when no detected ecosystem could read its manifest —
+ * "we cannot tell", which callers must not read as "declares nothing".
+ */
+export declare function declaredDepNames(cwd: string, roster?: readonly EcosystemProfile[]): Set<string> | undefined;
 export type EcosystemChoice = {
     ok: true;
     profile: EcosystemProfile;

package/dist/workers/docs-ecosystems.js

@@ -21,8 +21,8 @@ import { runAutoInstall, findDeclaredRange, extractParentPackage, resolveTypeSou
 import { resolvePackage, isDtsFile, isValidModuleName } from './docs-resolve.js';
 import { DECL_SPLIT_RE } from './docs-chunk.js';
 import { npmVersionLookup } from './npm-version.js';
-import { resolveCrate, cratesLatest, crateTarballUrl, crateOf, isValidCrateName, isRustFile, lockedVersion, rustSurface, cargoProjectName, childDirs, lockedDeps, CARGO_DECL_SPLIT_RE } from './eco-cargo.js';
-import { resolveHackage, hackageLatest, hackageVersion, hackageTarballUrl, hackageExtractDir, hackageProjectName, findCabalTarball, cachedVersions, resolvedVersions, isValidHackageName, isHaskellFile, haskellSurface, HACKAGE_DECL_SPLIT_RE, HACKAGE_SKIP_DIRS } from './eco-hackage.js';
+import { resolveCrate, cratesLatest, crateTarballUrl, crateOf, isValidCrateName, isRustFile, lockedVersion, rustSurface, cargoProjectName, childDirs, lockedDeps, manifestCrates, CARGO_DECL_SPLIT_RE } from './eco-cargo.js';
+import { resolveHackage, hackageLatest, hackageVersion, hackageTarballUrl, hackageExtractDir, hackageProjectName, findCabalTarball, cachedVersions, resolvedVersions, manifestPackages, isValidHackageName, isHaskellFile, haskellSurface, HACKAGE_DECL_SPLIT_RE, HACKAGE_SKIP_DIRS } from './eco-hackage.js';
 import { runChild } from '../shared/child-process.js';
 /**
  * Is any of `names` present at `cwd` or above it?
@@ -128,6 +128,7 @@ export function npmProfile(hooks = {}) {
         isSurfaceFile: isDtsFile,
         surface: content => content,
         declSplitRe: DECL_SPLIT_RE,
+        typeKeywords: ['interface', 'type', 'class', 'enum'],
         commentPrefix: '//',
         // A nested node_modules is another package's surface, never this one's.
         skipDirs: ['node_modules'],
@@ -135,7 +136,11 @@ export function npmProfile(hooks = {}) {
         packageSubject: 'an npm package',
         projectGlobs: ['*.ts', '*.tsx'],
         projectName: npmProjectName,
-        declaredDeps: npmDeclaredDeps
+        declaredDeps: npmDeclaredDeps,
+        manifestDeps: cwd => {
+            const deps = npmDeclaredDeps(cwd);
+            return deps && new Set(Object.keys(deps));
+        }
     };
 }
 const NPM_DEP_BLOCKS = [
@@ -266,13 +271,15 @@ const cargoProfile = {
     isSurfaceFile: isRustFile,
     surface: content => rustSurface(content),
     declSplitRe: CARGO_DECL_SPLIT_RE,
+    typeKeywords: ['struct', 'trait', 'enum', 'type', 'union'],
     commentPrefix: '//',
     skipDirs: ['tests', 'benches', 'examples', 'target'],
     surfaceLabel: '.rs source or README',
     packageSubject: 'a Rust crate from crates.io',
     projectGlobs: ['*.rs'],
     projectName: cargoProjectName,
-    declaredDeps: lockedDeps
+    declaredDeps: lockedDeps,
+    manifestDeps: manifestCrates
 };
 /**
  * Unpack a Hackage tarball into the tool's own directory. Whether it came from
@@ -351,13 +358,15 @@ const hackageProfile = {
     isSurfaceFile: isHaskellFile,
     surface: haskellSurface,
     declSplitRe: HACKAGE_DECL_SPLIT_RE,
+    typeKeywords: ['type', 'data', 'newtype', 'class'],
     commentPrefix: '--',
     skipDirs: HACKAGE_SKIP_DIRS,
     surfaceLabel: '.hs source or README',
     packageSubject: 'a Haskell package from Hackage',
     projectGlobs: ['*.hs'],
     projectName: hackageProjectName,
-    declaredDeps: resolvedVersions
+    declaredDeps: resolvedVersions,
+    manifestDeps: manifestPackages
 };
 /** A cabal, stack or hpack project declares itself with one of these. */
 function hasCabalManifest(cwd) {
@@ -385,6 +394,26 @@ export const ECOSYSTEMS = {
 export function detectEcosystems(cwd, roster = Object.values(ECOSYSTEMS)) {
     return roster.filter(p => p.detect(cwd)).map(p => p.id);
 }
+/**
+ * Every dependency `cwd`'s manifests declare, across the ecosystems it is a
+ * project of. Undefined when no detected ecosystem could read its manifest —
+ * "we cannot tell", which callers must not read as "declares nothing".
+ */
+export function declaredDepNames(cwd, roster = Object.values(ECOSYSTEMS)) {
+    let any = false;
+    const names = new Set();
+    for (const p of roster) {
+        if (!p.detect(cwd))
+            continue;
+        const deps = p.manifestDeps(cwd);
+        if (!deps)
+            continue;
+        any = true;
+        for (const name of deps)
+            names.add(name);
+    }
+    return any ? names : undefined;
+}
 /**
  * Which ecosystem a lookup belongs to. The MANIFEST decides, never the model:
  * `text`, `base`, `aeson`, `tokio` and `clap` are all real npm packages as well

package/dist/workers/docs-index.js

@@ -16,7 +16,9 @@ const ZERO_SEP = Buffer.from([0]);
  * question actually being asked: would re-reading produce the same chunks?
  *
  * The CHUNKER counts too, for the same reason: the rows are chunks, not surface,
- * so a fix to where a declaration is cut leaves stale rows behind on its own.
+ * so a fix to where a declaration is cut leaves stale rows behind on its own. So
+ * does WHICH FILES are read: dropping a package's duplicate `.d.cts` twins
+ * changes the rows without changing a byte on disk.
  *
  * It is not total. An extractor change that alters only files BELOW the entry
  * goes unnoticed; deleting the cache is still the escape hatch for that.
@@ -27,6 +29,11 @@ function computeContentHash(pkg, profile) {
     hash.update(ZERO_SEP);
     hash.update(Buffer.from(`${profile.declSplitRe.source}\u0000${profile.commentPrefix}`, 'utf8'));
     hash.update(ZERO_SEP);
+    // Source text, the same trick as `declSplitRe.source`: the fingerprint moves
+    // whenever the selection rule does, with nothing to remember to bump.
+    hash.update(Buffer.from(`${String(profile.isSurfaceFile)}\u0000${String(dropParallelDeclarations)}`
+        + `\u0000${String(dropDeadMajors)}`, 'utf8'));
+    hash.update(ZERO_SEP);
     if (pkg.entry && fs.existsSync(pkg.entry)) {
         try {
             hash.update(Buffer.from(profile.surface(fs.readFileSync(pkg.entry, 'utf8')), 'utf8'));
@@ -83,9 +90,56 @@ function walkSurface(root, profile) {
     }
     return out.sort();
 }
+/**
+ * Drop a `.d.cts` / `.d.mts` that sits beside a `.d.ts` of the same name.
+ *
+ * Modern npm packages ship parallel declarations for ESM and CJS: the same API
+ * written twice. zod 4.5.4 indexed to 2565 chunks over 1215 distinct bodies,
+ * 1280 of them from `.d.cts`; hono, which ships none, had 704 distinct of 708.
+ * The cost is the eight-chunk retrieval budget — half of it can go to text the
+ * reader already has.
+ *
+ * The sibling test, not a blanket ban on the extensions: a package shipping only
+ * `.d.cts` still has to be readable, and all 123 of zod's had a `.d.ts` twin.
+ */
+function dropParallelDeclarations(files) {
+    const esm = new Set(files.filter(f => f.endsWith('.d.ts')).map(f => f.slice(0, -'.d.ts'.length)));
+    return files.filter(f => {
+        const base = /\.d\.[cm]ts$/.exec(f) ? f.slice(0, -'.d.cts'.length) : null;
+        return base === null || !esm.has(base);
+    });
+}
+/**
+ * Drop a top-level `vN/` directory holding a major the package is no longer on.
+ *
+ * zod@4.5.4 ships `v3/` for back-compat, and 414 of its 2565 chunks came from
+ * it. Nothing downstream can separate them: same identifiers, same package, same
+ * version banner, and the file path is not a ranking signal. An answer went out
+ * under `Per zod@4.5.4:` carrying v3's `email(message?): ZodString` — wrong
+ * parameter, wrong return, and silent about the `@deprecated` line sitting
+ * directly above the real declaration.
+ *
+ * Only a MISMATCHING major goes. `v4/` under 4.5.4 is the current API and is
+ * most of the package; a package whose only content lives under `v1/` keeps it.
+ */
+function dropDeadMajors(files, root, version) {
+    const major = /^(\d+)\./.exec(version)?.[1];
+    if (major === undefined)
+        return files;
+    const kept = files.filter(abs => {
+        const top = path.relative(root, abs).replace(/\\/g, '/').split('/')[0];
+        const dir = /^v(\d+)$/.exec(top);
+        return dir === null || dir[1] === major;
+    });
+    // A package whose whole surface lives under a `vN/` that does not match its
+    // own version is not shipping a dead major — it is shipping its API there.
+    return kept.length > 0 ? kept : files;
+}
 function collectFiles(pkg, profile) {
+    const walked = walkSurface(pkg.root, profile);
+    const surface = dropDeadMajors(walked, pkg.root, pkg.version);
     return {
-        surface: walkSurface(pkg.root, profile),
+        surface: profile.id === 'npm' ? dropParallelDeclarations(surface) : surface,
         readme: pkg.readme
     };
 }

package/dist/workers/docs-project.js

@@ -234,7 +234,11 @@ listFiles = getProjectFiles) {
             version,
             query,
             limit: DEFAULT_LIMIT,
-            contentBudget: DEFAULT_BUDGET
+            contentBudget: DEFAULT_BUDGET,
+            // Every detected ecosystem's keywords: a polyglot project's own
+            // source has no single language, and the extra keywords only widen
+            // which definition the hop can find.
+            typeKeywords: [...new Set(projectProfiles(cwd).flatMap(p => p.typeKeywords))]
         });
     }
     catch (err) {

package/dist/workers/docs-retrieve.d.ts

@@ -12,6 +12,13 @@ export interface RetrieveOptions {
     version: string;
     query: string;
     limit?: number;
+    /**
+     * The keywords that introduce a named type, for the definition hop. Passed by
+     * the caller rather than read off `EcosystemProfile` here: docs-ecosystems
+     * imports docs-core, which imports this module, and reaching back for the
+     * profile closes that cycle at run time.
+     */
+    typeKeywords?: readonly string[];
     contentBudget?: number;
 }
 /**

package/dist/workers/docs-retrieve.js

@@ -16,6 +16,19 @@ export const RETRIEVE_CONTENT_BUDGET = 24_000;
 const DEFAULT_LIMIT = PROJECT_RETRIEVE_LIMIT;
 const DEFAULT_BUDGET = RETRIEVE_CONTENT_BUDGET;
 const MIN_TOKEN_LEN = 2;
+/**
+ * How many alias definitions one retrieval will chase. Three covers the observed
+ * case — hono's `get`/`json` pair plus one — without letting a chunk full of
+ * aliased members spend the whole budget on hops.
+ */
+const MAX_ALIAS_HOPS = 3;
+/** Backstop for a caller that names no ecosystem; every real one passes its own. */
+const DEFAULT_TYPE_KEYWORDS = ['interface', 'type', 'class', 'enum'];
+/** A member declared as a bare capitalised type: `get: HandlerInterface<…>`. */
+const MEMBER_TYPE_RE = /^\s*(?:readonly\s+)?([A-Za-z_$][\w$]*)\??\s*:\s*([A-Z][A-Za-z0-9_]*)\s*[<;,)|&]/gm;
+const TYPE_DECL_RE = /\b(?:interface|type|class|data|newtype|struct|trait|enum)\s+([A-Z][A-Za-z0-9_]*)/g;
+/** The `<E extends Env, BasePath extends string>` a declaration introduces itself. */
+const TYPE_PARAMS_RE = /<([^<>]*)>/g;
 const FALLBACK_DTS_CHARS = 12_000;
 const FALLBACK_README_CHARS = 4_000;
 /**
@@ -86,6 +99,77 @@ function enforceBudget(chunks, budget) {
     }
     return out;
 }
+/**
+ * The type names the retrieved text declares MEMBERS as, whose own definitions
+ * are not in hand and which the query itself names — by the member or by the
+ * type.
+ *
+ * This is the alias hop. A package that types its public surface through
+ * interface aliases puts every real signature one declaration away from the name
+ * a query matches: hono writes `get: HandlerInterface<…>` in hono-base.d.ts and
+ * keeps the call signatures in `HandlerInterface`, in types.d.ts. BM25 ranks
+ * chunks independently, so retrieval lands on the alias and the extraction child
+ * sees a name where a signature should be. Measured on hono 4.13.5: three real
+ * lookups, three abstentions, and the definition in one chunk of 708.
+ *
+ * Ranking hops by frequency does not work — `Response` and the English word
+ * `The` both outrank `HandlerInterface` in the same text. What the query names
+ * is the signal.
+ */
+function hopNames(text, tokens) {
+    const declared = new Set([...text.matchAll(TYPE_DECL_RE)].map(m => m[1]));
+    const typeParams = new Set();
+    for (const m of text.matchAll(TYPE_PARAMS_RE)) {
+        for (const part of m[1].split(',')) {
+            const name = /^\s*([A-Z][A-Za-z0-9_]*)\s*(?:extends|=|$)/.exec(part);
+            if (name)
+                typeParams.add(name[1]);
+        }
+    }
+    const asked = new Set(tokens.map(t => t.toLowerCase()));
+    const out = [];
+    // A capitalised name the QUERY itself asks about. scotty's seven failures were
+    // all of this shape: `type ActionM = ActionT IO` sits in one chunk of 312
+    // while 67 chunks USE the name, and a chunk carrying BOTH query terms
+    // (`get :: RoutePattern -> ActionM () -> ScottyM ()`) outranks the definition
+    // every time. Reading the ranked output, all eight slots went to uses.
+    for (const t of tokens) {
+        if (!/^[A-Z][A-Za-z0-9_]{2,}$/.test(t) || declared.has(t) || out.includes(t))
+            continue;
+        out.push(t);
+        if (out.length >= MAX_ALIAS_HOPS)
+            return out;
+    }
+    for (const m of text.matchAll(MEMBER_TYPE_RE)) {
+        const [, member, typeName] = m;
+        if (declared.has(typeName) || typeParams.has(typeName))
+            continue;
+        if (!asked.has(member.toLowerCase()) && !asked.has(typeName.toLowerCase()))
+            continue;
+        if (out.includes(typeName))
+            continue;
+        out.push(typeName);
+        if (out.length >= MAX_ALIAS_HOPS)
+            break;
+    }
+    return out;
+}
+/** The smallest chunk that DECLARES `name`, or null. */
+function definitionChunk(cache, opts, name) {
+    const keywords = opts.typeKeywords ?? DEFAULT_TYPE_KEYWORDS;
+    // Smallest first: the DEFINITION of a name is a short declaration, while the
+    // long chunks holding it are the ones that merely use it.
+    const where = keywords.map((_, i) => `content GLOB ?${i + 4}`).join(' OR ');
+    const row = cache.db
+        .prepare(`SELECT file_path, kind, content, 0 AS rank FROM chunks
+             WHERE ecosystem = ?1 AND name = ?2 AND version = ?3
+               AND (${where})
+             ORDER BY length(content) LIMIT 1`)
+        .get(opts.ecosystem, opts.name, opts.version, ...keywords.map(k => `*${k} ${name}[ <={(=]*`));
+    if (!row)
+        return null;
+    return { filePath: row.file_path, kind: row.kind, content: row.content, rank: row.rank };
+}
 export function retrieveChunks(cache, opts) {
     const limit = opts.limit ?? DEFAULT_LIMIT;
     const budget = opts.contentBudget ?? DEFAULT_BUDGET;
@@ -117,5 +201,20 @@ export function retrieveChunks(cache, opts) {
         content: r.content,
         rank: r.rank
     }));
-    return enforceBudget(mapped, budget);
+    const kept = enforceBudget(mapped, budget);
+    const key = (c) => `${c.filePath}\u0000${c.content.length}`;
+    const have = new Set(kept.map(key));
+    const hops = [];
+    for (const name of hopNames(kept.map(c => c.content).join('\n'), tokens)) {
+        const def = definitionChunk(cache, opts, name);
+        if (!def || have.has(key(def)))
+            continue;
+        hops.push(def);
+    }
+    if (hops.length === 0)
+        return kept;
+    // Hops sit directly behind the top-ranked chunk, so re-budgeting drops the
+    // WEAKEST original rather than the definition that explains the strongest.
+    // The budget itself does not move.
+    return enforceBudget([kept[0], ...hops, ...kept.slice(1)], budget);
 }

package/dist/workers/eco-cargo.d.ts

@@ -6,9 +6,9 @@
  * bodies and private items dropped. That is what `surface` below does, and it is
  * why this row needs code where the npm row needed none.
  *
- * Nothing here parses TOML. `Cargo.lock` is a generated file with a fixed
- * `[[package]]` shape, and a line reader over it costs one small function where
- * a TOML dependency would cost a dependency.
+ * No TOML parser. `Cargo.lock` is generated with a fixed `[[package]]` shape, and
+ * `Cargo.toml`'s dependency tables are read for their KEYS only, so a line reader
+ * covers both where a TOML dependency would cost a dependency.
  */
 import { type ResolvedPackage } from './docs-resolve.js';
 import type { NpmVersionInfo } from './npm-version.js';
@@ -112,4 +112,15 @@ export declare function rustSurface(src: string, insideTrait?: boolean, topLevel
 export declare function isRustFile(name: string): boolean;
 /** The `[package] name` of a cargo project, for labelling its own source. */
 export declare function cargoProjectName(cwd: string): string | null;
+/**
+ * The crate names `Cargo.toml` itself declares, under both `-` and `_` spellings.
+ *
+ * NOT {@link lockedDeps}: a lock file is the whole transitive closure, so it
+ * answers "can this resolve" and not "may this crate `use` it". The live run of
+ * 2026-09-05 answered about `tower` — in the lock via axum, absent from
+ * `[dependencies]` — and the crate did not compile.
+ *
+ * Undefined when there is no readable manifest, which is not "declares nothing".
+ */
+export declare function manifestCrates(cwd: string): Set<string> | undefined;
 export {};

package/dist/workers/eco-cargo.js

@@ -6,9 +6,9 @@
  * bodies and private items dropped. That is what `surface` below does, and it is
  * why this row needs code where the npm row needed none.
  *
- * Nothing here parses TOML. `Cargo.lock` is a generated file with a fixed
- * `[[package]]` shape, and a line reader over it costs one small function where
- * a TOML dependency would cost a dependency.
+ * No TOML parser. `Cargo.lock` is generated with a fixed `[[package]]` shape, and
+ * `Cargo.toml`'s dependency tables are read for their KEYS only, so a line reader
+ * covers both where a TOML dependency would cost a dependency.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
@@ -791,3 +791,44 @@ export function cargoProjectName(cwd) {
     const match = /^\s*name\s*=\s*"([^"]+)"/m.exec(section?.[1] ?? '');
     return match ? match[1] : null;
 }
+/**
+ * The crate names `Cargo.toml` itself declares, under both `-` and `_` spellings.
+ *
+ * NOT {@link lockedDeps}: a lock file is the whole transitive closure, so it
+ * answers "can this resolve" and not "may this crate `use` it". The live run of
+ * 2026-09-05 answered about `tower` — in the lock via axum, absent from
+ * `[dependencies]` — and the crate did not compile.
+ *
+ * Undefined when there is no readable manifest, which is not "declares nothing".
+ */
+export function manifestCrates(cwd) {
+    const text = safeRead(path.join(cwd, 'Cargo.toml'));
+    if (text === null)
+        return undefined;
+    const out = new Set();
+    const add = (name) => {
+        for (const key of new Set([name, canonical(name)]))
+            out.add(key);
+    };
+    let inDeps = false;
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        const header = /^\[([^\]]+)\]$/.exec(line);
+        if (header) {
+            const section = header[1];
+            // `[dependencies.serde]` and `[target.'cfg(unix)'.dependencies]` both
+            // declare, and the first names its crate in the header itself.
+            const table = /^(?:target\.[^.]*\.)?(?:dev-|build-)?dependencies(?:\.(.+))?$/.exec(section);
+            inDeps = table !== null && table[1] === undefined;
+            if (table?.[1])
+                add(table[1]);
+            continue;
+        }
+        if (!inDeps)
+            continue;
+        const key = /^([A-Za-z0-9_-]+)\s*=/.exec(line);
+        if (key)
+            add(key[1]);
+    }
+    return out;
+}

package/dist/workers/eco-hackage.d.ts

@@ -91,3 +91,12 @@ export declare function haskellSurface(rawSrc: string): string;
 export declare function isHaskellFile(name: string): boolean;
 /** The `name:` field of the project's own `.cabal` file. */
 export declare function hackageProjectName(cwd: string): string | null;
+/**
+ * The package names the project's `.cabal` file declares in `build-depends`,
+ * across every stanza.
+ *
+ * NOT {@link resolvedVersions}: that reads the cabal install plan, which is the
+ * whole transitive closure, so it cannot say whether a module may be imported.
+ * Undefined when there is no readable `.cabal` file.
+ */
+export declare function manifestPackages(cwd: string): Set<string> | undefined;

package/dist/workers/eco-hackage.js

@@ -506,3 +506,49 @@ export function hackageProjectName(cwd) {
     const match = /^\s*name\s*:\s*(\S+)/m.exec(safeRead(path.join(cwd, cabal)) ?? '');
     return match ? match[1] : null;
 }
+/**
+ * The package names the project's `.cabal` file declares in `build-depends`,
+ * across every stanza.
+ *
+ * NOT {@link resolvedVersions}: that reads the cabal install plan, which is the
+ * whole transitive closure, so it cannot say whether a module may be imported.
+ * Undefined when there is no readable `.cabal` file.
+ */
+export function manifestPackages(cwd) {
+    let entries;
+    try {
+        entries = fs.readdirSync(cwd);
+    }
+    catch {
+        return undefined;
+    }
+    const cabal = entries.find(e => e.endsWith('.cabal'));
+    if (!cabal)
+        return undefined;
+    const text = safeRead(path.join(cwd, cabal));
+    if (text === null)
+        return undefined;
+    const out = new Set();
+    let inDepends = false;
+    for (const raw of text.split('\n')) {
+        const line = raw.replace(/--.*$/, '');
+        const start = /^\s*build-depends\s*:(.*)$/i.exec(line);
+        const body = start ? start[1] : line;
+        if (start)
+            inDepends = true;
+        else if (!inDepends)
+            continue;
+        // A continuation is indented; a new field at the stanza's own indent ends
+        // the list. Both `,`-leading and `,`-trailing layouts are in the wild.
+        else if (/^\s*[A-Za-z-]+\s*:/.test(line) || line.trim() === '') {
+            inDepends = false;
+            continue;
+        }
+        for (const part of body.split(',')) {
+            const name = /^\s*([A-Za-z0-9][A-Za-z0-9_-]*)/.exec(part);
+            if (name)
+                out.add(name[1]);
+        }
+    }
+    return out;
+}

package/package.json

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