@mjasnikovs/pi-task 0.39.4 → 0.40.0

package/dist/task/plan-orchestrator.js

@@ -277,8 +277,17 @@ async function runPlanCommand(ctx, cwd, planId, task, commandDeps) {
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
+        // A user stop is not a fault, and the sentinel is not a sentence. The
+        // cancel checkpoint in runPlanningChild throws USER_CANCELLED here, so
+        // without this branch a /task-cancel during planning reads as a red
+        // "PLAN_0001 stopped — __user_cancelled__".
+        if (msg === USER_CANCELLED) {
+            await updateTaskFrontMatter(cwd, planId, { state: 'cancelled' }).catch(() => { });
+            announceTerminal(ctx, `${planId} cancelled.`, 'warning', { push: false });
+            return;
+        }
         await updateTaskFrontMatter(cwd, planId, {
-            state: msg === USER_CANCELLED ? 'cancelled' : 'failed',
+            state: 'failed',
             reason: msg.slice(0, 200)
         }).catch(() => { });
         // No push: a plan is a conversation, not a task; the run it hands off

package/dist/task/prompts.d.ts

@@ -26,7 +26,13 @@ export declare const COMPRESS_LABEL_PROMPT: (title: string, maxChars: number) =>
 declare const REFINE_PROMPT: (raw: string, planContext?: string, existingFiles?: string, contracts?: string, directives?: string) => string;
 declare const RESEARCH_READ_ONLY_CONSTRAINT = "IMPORTANT: You are ONLY allowed to READ. Do NOT create, modify, or delete any files. Use the read, grep, find, and ls tools to inspect the repo.";
 declare const RESEARCH_FILES_PROMPT: (refined: string) => string;
-declare const RESEARCH_APIS_PROMPT: (refined: string, filesMap?: string) => string;
+/**
+ * `ecosystems` is what `detectEcosystems` found in the worker's cwd. It is REQUIRED,
+ * and an empty list is a real answer: a directory with no package manifest has no
+ * registry to look a library up in, and the paragraph below has to say so rather
+ * than inviting a lookup that will be refused.
+ */
+declare const RESEARCH_APIS_PROMPT: (refined: string, filesMap: string | undefined, ecosystems: readonly string[]) => string;
 declare const RESEARCH_CONTEXT_PROMPT: (refined: string) => string;
 declare const RESEARCH_TOOLING_PROMPT: (refined: string) => string;
 declare const GRILL_GEN_PROMPT: (refined: string, research: string, priorQA: string) => string;

package/dist/task/prompts.js

@@ -97,13 +97,23 @@ No section header. No other sections. No preamble.
 
 Task:
 ${refined}`;
-const RESEARCH_APIS_PROMPT = (refined, filesMap) => `You are doing targeted research for an AI coding agent. Use the read, grep, find, and ls tools — and \`pi-worker-docs\` for installed npm packages — to identify the commands, functions, types, and interfaces the agent will use for the following task.
+/**
+ * `ecosystems` is what `detectEcosystems` found in the worker's cwd. It is REQUIRED,
+ * and an empty list is a real answer: a directory with no package manifest has no
+ * registry to look a library up in, and the paragraph below has to say so rather
+ * than inviting a lookup that will be refused.
+ */
+const RESEARCH_APIS_PROMPT = (refined, filesMap, ecosystems) => `You are doing targeted research for an AI coding agent. Use the read, grep, find, and ls tools${ecosystems.length ? ' — and `pi-worker-docs` for installed packages —' : ''} to identify the commands, functions, types, and interfaces the agent will use for the following task.
 
-NPM PACKAGES — use pi-worker-docs, NOT file reads: for any third-party npm package (e.g. "zod", "hono", "drizzle-orm"), call \`pi-worker-docs(module, query)\` to get its type signatures and API surface. Do NOT open node_modules source files directly — those reads are expensive and produce far more noise than the tool. The tool returns a compact, focused excerpt in a fraction of the token cost.
+${ecosystems.length ?
+    `LIBRARY PACKAGES — use pi-worker-docs, NOT file reads: for any third-party package, call \`pi-worker-docs(module, query)\` to get its type signatures and API surface. Do NOT open installed-package source files directly — those reads are expensive and produce far more noise than the tool. The tool returns a compact, focused excerpt in a fraction of the token cost. This project's package ecosystems are: ${ecosystems.join(', ')}.`
+    : 'LIBRARY PACKAGES — do NOT look them up: this directory holds no package manifest, so `pi-worker-docs` has no registry to read and will refuse. Do not list an external library API you cannot check here.'}
 
-PROJECT SOURCE — use pi-worker-docs with module ".", NOT file reads: for any function, class, type, or interface defined in THIS project's own .ts/.tsx source (e.g. "what does requireAuth check?", "what does CreateListingSchema look like?", "what does the listings query module export?"), call \`pi-worker-docs(".", query)\` instead of reading the file. The tool indexes all git-tracked source files and returns only the relevant chunks — far cheaper than reading whole files.
+PROJECT SOURCE — use pi-worker-docs with module ".", NOT file reads: for any function, class, type, or interface defined in THIS project's own source (e.g. "what does requireAuth check?", "what does CreateListingSchema look like?", "what does the listings query module export?"), call \`pi-worker-docs(".", query)\` instead of reading the file. The tool indexes all git-tracked source files and returns only the relevant chunks — far cheaper than reading whole files.
 
-RUNTIME BUILTINS — verify, do NOT echo: a task (or the spec doc it references) may name a runtime/builtin import like \`bun:sql\`, \`bun:sqlite\`, \`node:fs\`, or \`Bun.password\`. A runtime exposes only a small FIXED set of \`<runtime>:<submodule>\` modules, and a spec doc can confidently name one that does not exist. Before you list ANY \`<pkg>:<sub>\` specifier, confirm it with \`pi-worker-docs\` (e.g. \`pi-worker-docs("bun:sql", "sql tagged template and SQL class — the import")\` — the tool resolves the runtime's real types) and emit the CANONICAL import the types actually prove, NOT the string copied from the task. Concretely: Bun's SQL client is \`import { sql } from "bun"\` (or \`Bun.sql\` / \`new SQL()\`) — there is NO \`bun:sql\` module. Never pass an unverified colon-specifier through to the APIS list; a phantom import laundered here becomes fabricated \`declare module\` shims in the implementation.
+${ecosystems.includes('npm') ?
+    `RUNTIME BUILTINS — verify, do NOT echo: a task (or the spec doc it references) may name a runtime/builtin import like \`bun:sql\`, \`bun:sqlite\`, \`node:fs\`, or \`Bun.password\`. A runtime exposes only a small FIXED set of \`<runtime>:<submodule>\` modules, and a spec doc can confidently name one that does not exist. Before you list ANY \`<pkg>:<sub>\` specifier, confirm it with \`pi-worker-docs\` (e.g. \`pi-worker-docs("bun:sql", "sql tagged template and SQL class — the import")\` — the tool resolves the runtime's real types) and emit the CANONICAL import the types actually prove, NOT the string copied from the task. Concretely: Bun's SQL client is \`import { sql } from "bun"\` (or \`Bun.sql\` / \`new SQL()\`) — there is NO \`bun:sql\` module. Never pass an unverified colon-specifier through to the APIS list; a phantom import laundered here becomes fabricated \`declare module\` shims in the implementation.`
+    : ''}
 
 APIS owns symbols and commands BY NAME ONLY. Do NOT include any file path or path fragment — no \`package.json\`, no \`./src/foo.ts\`, no \`package.json#scripts.lint\`. If the symbol is a script defined in package.json, write the invocation (\`npm run lint\`), not its location. If the symbol is a config file, it does not belong in APIS at all — it belongs in FILES.
 

package/dist/task/research-worker.js

@@ -20,6 +20,8 @@
  */
 import { classifyWorkerFailure } from '../workers/worker-failure.js';
 import { classifyContextSilence, countBullets } from './context-silence.js';
+import { cancelCheckpoint } from './cancel-points.js';
+import { USER_CANCELLED } from './child-runner.js';
 /**
  * Task-file heading under which a research worker's validated output is cached.
  * A resumed research phase reads these to skip workers that already succeeded,
@@ -403,5 +405,14 @@ export async function runResearchWorker(spec, run, prior = []) {
     // a truncated section can still carry a laundered claim.
     const sectionText = spec.postProcess ? spec.postProcess(rawText) : rawText;
     await run.persistSection(cacheHeading, sectionText);
+    // SAFE CHECKPOINT: this worker's section is on disk and the cache read at the
+    // top of this function is what a resume uses to skip it, so stopping between
+    // workers repeats nothing. Research is the phase's long pole and the workers
+    // run serially, which is what makes this the one seam that costs nothing in
+    // either direction. USER_CANCELLED reuses the phase's existing cancel path.
+    if (cancelCheckpoint(`research:${spec.section}`)) {
+        run.logDebug?.(`cancel: stopping after research worker ${spec.section}`);
+        throw new Error(USER_CANCELLED);
+    }
     return { name: spec.section, text: sectionText };
 }

package/dist/task/run-bracket.js

@@ -1,8 +1,9 @@
 import { armCancelListener, disarmCancelListener } from './cancel-input.js';
-import { beginRun, endRun } from './mid-run-input.js';
+import { beginRun, endRun, isRunActive } from './mid-run-input.js';
 import { reportDroppedInput } from './dropped-input.js';
 import { publishLifecycleNotice } from '../remote/bridge.js';
 import { pushNotify } from '../remote/push.js';
+import { resetCancel } from './cancel-points.js';
 /**
  * Run `fn` as the owner of the session: hold mid-run input and arm the terminal
  * interception for exactly its duration, then release both — on return AND on
@@ -10,6 +11,15 @@ import { pushNotify } from '../remote/push.js';
  * Nests: an inner bracket neither re-renders the surfaces nor un-arms the outer.
  */
 export async function withRun(ctx, opts, fn) {
+    // A cancel is scoped to the run that was asked to stop. runAutoLoop already
+    // cleared the flag at both ends of its own loop; the bracket is what gives
+    // every OTHER entry point the same guarantee, so a /task-cancel raised on a
+    // bare /task cannot survive to stop the next run at its first phase.
+    // Outermost only: an inner bracket clearing it would drop the request the
+    // outer loop has not observed yet.
+    const outermost = !isRunActive();
+    if (outermost)
+        resetCancel();
     beginRun();
     armCancelListener(ctx, opts.onCancel);
     try {
@@ -17,6 +27,8 @@ export async function withRun(ctx, opts, fn) {
     }
     finally {
         disarmCancelListener();
+        if (outermost)
+            resetCancel();
         reportDroppedInput(endRun(), ctx);
     }
 }

package/dist/task/task-gates.js

@@ -10,6 +10,8 @@ import { attributeEnforceFailure } from './enforce-attribution.js';
 // re-check-side parser (extractDeletedDebtPath) have to move together.
 import { crossTaskDeletionReason } from './accept-debt.js';
 import { clampOutput } from './clamp-output.js';
+import { cancelCheckpoint } from './cancel-points.js';
+import { updateTaskFrontMatter } from './task-io.js';
 /**
  * How many times a verify FAIL may be auto-fixed UNATTENDED (the research
  * recommended AUTOFIX, so pi re-runs the impl turn without prompting) before the
@@ -114,6 +116,24 @@ export async function resolveVerifyGate(ctxIn, deps, p, rec, routeRootCause) {
         // YOLO only: has the one-attempt rescue below already been spent on this task?
         let yoloRescueUsed = false;
         while (!verified.ok) {
+            // SAFE CHECKPOINT (before a resolution round): a round is a bounded
+            // lint fix, a research child and possibly a whole implementation
+            // re-run, so a cancel observed only INSIDE one buys all of that
+            // first. At the TOP of the loop because every later position is past
+            // something that already recorded itself — the unattended branch
+            // increments the counter, writes its `## gates` line and toasts
+            // "auto-fixing…" before it reaches any code below.
+            //
+            // The task file still reads `completed` here, written at spec handoff
+            // before any of this ran, and `completed` is not in RESUMABLE_STATES.
+            // Returning `cancelled` without this write would leave the announced
+            // "resume with /task-resume" pointing at a file /task-resume skips —
+            // the work is unverified AND uncommitted at this point, so that is the
+            // one place in the gate where a missed demotion loses it.
+            if (cancelCheckpoint('gate:pre-resolution')) {
+                await updateTaskFrontMatter(p.cwd, p.taskId, { state: 'cancelled' }).catch(() => { });
+                return { stop: { kind: 'cancelled', ctx: active } };
+            }
             const failReason = verified.reason ?? 'did not verify';
             // GRADUATED resolution: a repo-health FAIL (pure static findings) gets ONE
             // bounded fix attempt before the picker — smallest tool first. Applied →
@@ -671,6 +691,20 @@ export async function runGatesForTask(ctxIn, deps, p) {
         else
             notifyBoth(active, line, 'warning');
     }
+    // SAFE CHECKPOINT (post task commit): the work verified, the parent entry is
+    // checked off and the snapshot is in HEAD. Only the enforce pass is skipped,
+    // and enforce is re-runnable.
+    //
+    // Returns `done`, not `cancelled`: this task IS done, and `cancelled` would
+    // announce "resume with /task-resume" over a task whose work is already
+    // committed — a resume there re-runs the whole spec pipeline to redo it. The
+    // flag stays raised, so /task-auto stops one step later at loop-top with the
+    // right wording and a ticked checkbox, and a bare /task simply ends. The trail
+    // line is what keeps the skip from being silent.
+    if (cancelCheckpoint('gate:post-commit')) {
+        await rec('enforce: skipped — cancel requested after the task snapshot committed');
+        return { kind: 'done', ctx: active };
+    }
     await runEnforcePass(active, deps, p, rec, routeRootCause, { cleanPass, commit });
     return { kind: 'done', ctx: active };
 }

package/dist/workers/docs-cache.js

@@ -2,24 +2,37 @@ import { createRequire } from 'node:module';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
+/**
+ * Bump whenever the shape below changes in a way old rows cannot satisfy. The
+ * migration is a DROP and rebuild: this is a derived cache of package sources,
+ * so re-indexing costs a walk, and hand-written ALTERs cost a defect class.
+ */
+const SCHEMA_VERSION = 1;
+/**
+ * `ecosystem` scopes every row to the registry it came from, so `text` on npm and
+ * `text` on Hackage are different packages. Project-source rows use their own
+ * scope value rather than a registry id.
+ */
 const SCHEMA_SQL = `
 CREATE TABLE IF NOT EXISTS packages (
+  ecosystem    TEXT NOT NULL DEFAULT 'npm',
   name         TEXT NOT NULL,
   version      TEXT NOT NULL,
   content_hash TEXT NOT NULL,
   indexed_at   INTEGER NOT NULL,
-  PRIMARY KEY (name, version)
+  PRIMARY KEY (ecosystem, name, version)
 );
 
 CREATE TABLE IF NOT EXISTS chunks (
   id        INTEGER PRIMARY KEY AUTOINCREMENT,
+  ecosystem TEXT NOT NULL DEFAULT 'npm',
   name      TEXT NOT NULL,
   version   TEXT NOT NULL,
   file_path TEXT NOT NULL,
   kind      TEXT NOT NULL CHECK (kind IN ('dts','readme')),
   content   TEXT NOT NULL
 );
-CREATE INDEX IF NOT EXISTS chunks_pkg ON chunks(name, version);
+CREATE INDEX IF NOT EXISTS chunks_pkg ON chunks(ecosystem, name, version);
 
 CREATE VIRTUAL TABLE IF NOT EXISTS chunks_fts USING fts5(
   content,
@@ -34,6 +47,14 @@ CREATE TRIGGER IF NOT EXISTS chunks_ad AFTER DELETE ON chunks BEGIN
   INSERT INTO chunks_fts(chunks_fts, rowid, content) VALUES('delete', old.id, old.content);
 END;
 `;
+// Order matters: the triggers and the FTS index reference `chunks`.
+const DROP_SQL = `
+DROP TRIGGER IF EXISTS chunks_ai;
+DROP TRIGGER IF EXISTS chunks_ad;
+DROP TABLE IF EXISTS chunks_fts;
+DROP TABLE IF EXISTS chunks;
+DROP TABLE IF EXISTS packages;
+`;
 const req = createRequire(import.meta.url);
 // Branch on the RUNTIME, not on a try/catch: each builtin exists in exactly one
 // of them. Requiring `bun:sqlite` under node throws MODULE_NOT_FOUND, and
@@ -61,9 +82,35 @@ export function openCache(dbPath) {
     db.exec('PRAGMA journal_mode = WAL;');
     db.exec('PRAGMA synchronous = NORMAL;');
     db.exec('PRAGMA foreign_keys = ON;');
-    db.exec(SCHEMA_SQL);
+    // A blocking busy handler, not a tuned delay: research children open this
+    // cache concurrently, and the loser of the migration lock has to WAIT for the
+    // winner's COMMIT rather than throw SQLITE_BUSY on the spot. The bound only
+    // stops a wedged handle hanging the worker forever.
+    db.exec('PRAGMA busy_timeout = 30000;');
+    migrate(db);
     return {
         db,
         close: () => db.close()
     };
 }
+/**
+ * `CREATE TABLE IF NOT EXISTS` is a no-op against an older shape, so the version
+ * check has to run BEFORE it or a stale table survives untouched.
+ */
+function migrate(db) {
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        const row = db.prepare('PRAGMA user_version').get();
+        // A brand-new database also reads 0, hence DROP ... IF EXISTS.
+        if ((row?.user_version ?? 0) < SCHEMA_VERSION) {
+            db.exec(DROP_SQL);
+            db.exec(`PRAGMA user_version = ${SCHEMA_VERSION};`);
+        }
+        db.exec(SCHEMA_SQL);
+        db.exec('COMMIT');
+    }
+    catch (err) {
+        db.exec('ROLLBACK');
+        throw err;
+    }
+}

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

@@ -53,15 +53,18 @@ export declare function splitAtMatches(text: string, re: RegExp): string[];
  */
 export declare function sliceBytes(s: string, maxBytes: number): string[];
 /**
- * Chunk a declaration file (`.d.ts`, `.ts`, `.tsx`), one chunk per declaration,
- * each labelled with the file it came from.
+ * Chunk a declaration file, one chunk per declaration, each labelled with the
+ * file it came from.
  *
  * `relPath` is a MODEL-FACING label and is used exactly as given. docs-index.ts
  * normalises it to POSIX (`.replace(/\\/g, '/')`) so a package index is identical
  * across platforms; docs-project.ts passes `path.relative` through with the native
  * separator. It is never re-joined to the filesystem, so neither is wrong — this
  * leaves the choice with the caller that has a reason for it.
+ *
+ * `splitRe` and `commentPrefix` default to the TypeScript pair, which is what
+ * both the project corpus and npm packages are written in.
  */
-export declare function chunkDeclarations(content: string, relPath: string): string[];
+export declare function chunkDeclarations(content: string, relPath: string, splitRe?: RegExp, commentPrefix?: string): string[];
 /** Chunk a README, one chunk per top-level section, each labelled by heading. */
 export declare function chunkReadme(content: string): string[];

package/dist/workers/docs-chunk.js

@@ -90,22 +90,25 @@ export function sliceBytes(s, maxBytes) {
     return out;
 }
 /**
- * Chunk a declaration file (`.d.ts`, `.ts`, `.tsx`), one chunk per declaration,
- * each labelled with the file it came from.
+ * Chunk a declaration file, one chunk per declaration, each labelled with the
+ * file it came from.
  *
  * `relPath` is a MODEL-FACING label and is used exactly as given. docs-index.ts
  * normalises it to POSIX (`.replace(/\\/g, '/')`) so a package index is identical
  * across platforms; docs-project.ts passes `path.relative` through with the native
  * separator. It is never re-joined to the filesystem, so neither is wrong — this
  * leaves the choice with the caller that has a reason for it.
+ *
+ * `splitRe` and `commentPrefix` default to the TypeScript pair, which is what
+ * both the project corpus and npm packages are written in.
  */
-export function chunkDeclarations(content, relPath) {
+export function chunkDeclarations(content, relPath, splitRe = DECL_SPLIT_RE, commentPrefix = '//') {
     const chunks = [];
-    for (const part of splitAtMatches(content, new RegExp(DECL_SPLIT_RE.source, 'gm'))) {
+    for (const part of splitAtMatches(content, new RegExp(splitRe.source, 'gm'))) {
         const trimmed = part.trim();
         if (!trimmed)
             continue;
-        const prefixed = `// ${relPath}\n${trimmed}`;
+        const prefixed = `${commentPrefix} ${relPath}\n${trimmed}`;
         if (Buffer.byteLength(prefixed, 'utf8') > MAX_CHUNK_BYTES) {
             for (const slice of sliceBytes(prefixed, MAX_CHUNK_BYTES))
                 chunks.push(slice);

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

@@ -1,5 +1,6 @@
 import { openCache as defaultOpenCache } from './docs-cache.js';
 import { ensureIndexed as defaultEnsureIndexed } from './docs-index.js';
+import { type EcosystemId, type EcosystemIo, type EcosystemProfile } from './docs-ecosystems.js';
 import { resolvePackage as defaultResolvePackage, type ResolvedPackage } from './docs-resolve.js';
 import { retrieveChunks as defaultRetrieveChunks, type RetrievedChunk } from './docs-retrieve.js';
 import { npmVersionLookup as defaultNpmVersionLookup, type NpmVersionInfo } from './npm-version.js';
@@ -37,6 +38,8 @@ export type DocsRawResult = {
     autoInstalled?: boolean;
     autoInstallPin?: AutoInstallPin;
     npmVersion?: NpmVersionInfo | null;
+    /** The registry the answer came from, for the block that leads it. */
+    registryLabel?: string;
 } | {
     kind: 'no_chunks';
     pkg: ResolvedPackage;
@@ -46,10 +49,12 @@ export type DocsRawResult = {
     autoInstalled?: boolean;
     autoInstallPin?: AutoInstallPin;
     npmVersion?: NpmVersionInfo | null;
+    /** The registry the answer came from, for the block that leads it. */
+    registryLabel?: string;
 } | {
     kind: 'error';
     message: string;
-    resolveError?: 'not_installed' | 'invalid_name';
+    resolveError?: 'not_installed' | 'invalid_name' | 'unsupported_ecosystem' | 'ambiguous_ecosystem';
     installError?: string;
     version?: string;
     hitCache?: boolean;
@@ -57,11 +62,15 @@ export type DocsRawResult = {
     autoInstalled?: boolean;
     autoInstallPin?: AutoInstallPin;
     npmVersion?: NpmVersionInfo | null;
+    /** The registry the answer came from, for the block that leads it. */
+    registryLabel?: string;
 };
 export interface DocsRawInput {
     pkg: string;
     query: string;
     cwd: string;
+    /** Which registry to read, for a repo holding more than one manifest. */
+    ecosystem?: EcosystemId;
     autoInstall?: boolean;
     resolvePackage?: typeof defaultResolvePackage;
     ensureIndexed?: typeof defaultEnsureIndexed;
@@ -69,6 +78,8 @@ export interface DocsRawInput {
     openCache?: typeof defaultOpenCache;
     spawn?: SpawnFn;
     npmVersionLookup?: typeof defaultNpmVersionLookup;
+    /** Overrides for the filesystem and network a non-npm row reaches through. */
+    io?: Partial<EcosystemIo>;
     signal?: AbortSignal;
 }
 export interface DocsFocusedResult {
@@ -162,7 +173,7 @@ export declare function findDeclaredRange(parentPkg: string, cwd: string): strin
  * `bun`, and cannot declare `bun-types`, so a sentence about what package.json
  * does or does not say has to be a sentence about `bun`.
  */
-export declare function buildVersionBanner(pin: AutoInstallPin | undefined, resolved: string, version: string, cwd: string): string;
+export declare function buildVersionBanner(pin: AutoInstallPin | undefined, resolved: string, version: string, cwd: string, profile?: EcosystemProfile): string;
 export declare function getDocsModulesDir(): string;
 export declare function ensureDocsModulesDir(dir: string): void;
 /**
@@ -207,8 +218,13 @@ export interface AcquireInput {
     name: string;
     cwd: string;
     spawn: SpawnFn;
-    resolvePackage: typeof defaultResolvePackage;
+    /** Overrides `profile.resolve` when given, for callers that inject a resolver. */
+    resolvePackage?: typeof defaultResolvePackage;
     signal: AbortSignal | undefined;
+    /** Which registry to acquire from. */
+    profile?: EcosystemProfile;
+    /** The row's filesystem and network reach. Built from `spawn` when absent. */
+    io?: EcosystemIo;
 }
 /**
  * Get a package onto disk and resolved: resolve from `cwd`, and on
@@ -231,6 +247,14 @@ export interface AcquireInput {
  * sites should differ only about WHETHER to install, never about HOW.
  */
 export declare function acquirePackage(input: AcquireInput): Promise<AcquireOutcome>;
+/** The docs pipeline's adapter over the shared redirect walk (docs-resolve.ts):
+ *  hops resolve through the auto-installing lookup, so a declaration package that is
+ *  declared but not yet on disk is fetched rather than abandoned. */
+export declare function resolveTypeSourceForDocs(pkg: ResolvedPackage, requested: string, cwd: string, spawn: SpawnFn, resolvePackage: typeof defaultResolvePackage, signal: AbortSignal | undefined): Promise<{
+    pkg: ResolvedPackage;
+    installed: boolean;
+    pin?: AutoInstallPin;
+}>;
 export declare function docsRaw(input: DocsRawInput): Promise<DocsRawResult>;
 export declare function docsFocused(input: DocsFocusedInput): Promise<DocsFocusedResult>;
 export declare function buildPrompt(pkg: ResolvedPackage, query: string, content: string): string;