@mjasnikovs/pi-task 0.37.4 → 0.37.6

package/dist/task/final-gate.js

@@ -52,6 +52,7 @@ import * as path from 'node:path';
 import { runRepoHealthCheck, discoverHealthCommands } from './repo-health-check.js';
 import { readAcceptDebts, recheckAcceptDebts, writeAcceptDebts, buildAcceptDebtNote, annotateDebtConflicts } from './accept-debt.js';
 import { readDeclaredScripts, missingDeclaredScripts, runnableDeclaredScripts } from './launch-contract.js';
+import { readLaunchManifest, inertLaunchContractNote } from './launch-manifest.js';
 import { readEnvNotes, parseEnvNotes, isExcuseNote } from './env-notes.js';
 import { runRenderCheck } from './render-check.js';
 import { collectProjectEnv, pinnedLocalPort, runDeepRenderCheck } from './deep-render-check.js';
@@ -1378,11 +1379,28 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
     // scripts that fell through decompose and shipped missing, unchecked. Diff the
     // plan-time-extracted declared scripts against the manifest; a missing one is a
     // launch-surface defect. FP-safe: empty declared list (nothing grounded) → no check.
+    //
+    // THE DIFF IS INERT WITHOUT A MANIFEST (nexttask 16A). It used to diff against
+    // `Object.keys(packageScripts(cwd))`, whose catch returns {} — so a project with
+    // NO package.json was indistinguishable from one with no scripts, and every
+    // declared script was reported missing in wording naming a file the project was
+    // never meant to have. Nothing upstream is npm-shaped (the extractor scrapes any
+    // design that says "script"), and this text seeds the autofix child's prompt, so
+    // on a CMake/cargo project the likely repair was to write a package.json.
+    // readLaunchManifest resolves package.json, else a Makefile's targets, else
+    // nothing — and nothing means no failure plus a note, never a silent pass.
     const declared = await readDeclaredScripts(cwd);
+    const contractNotes = [];
     if (declared.length > 0) {
-        const missing = missingDeclaredScripts(declared, Object.keys(packageScripts(cwd)));
-        if (missing.length > 0) {
-            fail(`launch contract: the design declares script(s) the shipped package.json does not expose: ${missing.join(', ')} (declared: ${declared.join(', ')})`);
+        const manifest = readLaunchManifest(cwd);
+        if (manifest.kind === 'none') {
+            contractNotes.push(inertLaunchContractNote(declared, manifest));
+        }
+        else {
+            const missing = missingDeclaredScripts(declared, manifest.names);
+            if (missing.length > 0) {
+                fail(`launch contract: the design declares script(s) the shipped ${manifest.file} does not expose: ${missing.join(', ')} (declared: ${declared.join(', ')})`);
+            }
         }
     }
     // Serve-entry closure (mx5 run 18, nexttask 2B): the tree builds a server app,
@@ -1416,7 +1434,12 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
     // harvest lever refuted at discoverIntegrationCommands it cannot inject a fabricated
     // failure.
     if (lockCmds.length === 0 && cmds.length === 0 && !boot && failures.length === 0) {
-        const note = unobservedVerdict({ discovered: 0, observed: 0 }) ?? '';
+        // The inert-contract note rides here too: a non-npm project carrying a launch
+        // contract usually discovers no command either, and that is exactly the run
+        // whose silence must not read as "the contract was checked and was fine".
+        const note = [unobservedVerdict({ discovered: 0, observed: 0 }) ?? '', ...contractNotes]
+            .filter(n => n !== '')
+            .join(' ');
         return withDebts({ ok: true, unobserved: note, reason: note });
     }
     const ran = [];
@@ -1471,6 +1494,11 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
         // A declared script the manifest doesn't expose is already a launch-contract
         // failure above; executing it too would double-report (pre-aggregation the
         // contract diff early-returned, so this loop could assume presence).
+        // EXECUTION STAYS npm-ONLY. The diff above now also speaks Makefile (16A),
+        // but the runner below is literally `bun run <name>`; on a Makefile project
+        // `present` is empty, so every declared target is skipped rather than run
+        // through the wrong tool. Widening the RUNNER is a separate lever with its
+        // own A/B, not a free rider on an inertness fix.
         const present = new Set(Object.keys(packageScripts(cwd)).map(s => s.toLowerCase()));
         const scripts = packageScripts(cwd);
         // CONFIG-GAP INPUTS (mx5 run 20), read once: the tracked file list and the
@@ -1704,7 +1732,8 @@ export async function runFinalIntegrationGate(cwd, timeoutMs = 900_000, bootGrac
     const unobserved = [
         bootUnobserved,
         unobservedVerdict({ discovered: dynAttempted, observed: dynObserved }),
-        ...configGapNotes
+        ...configGapNotes,
+        ...contractNotes
     ]
         .filter(n => n !== null)
         .join(' ');

package/dist/task/launch-manifest.d.ts

@@ -0,0 +1,37 @@
+/** Which manifest kind the diff resolved for a tree. `none` ⇒ the diff is INERT. */
+export type LaunchManifestKind = 'npm' | 'make' | 'none';
+export interface LaunchManifest {
+    kind: LaunchManifestKind;
+    /** The manifest the diff is taken against, for the failure text. '' when none. */
+    file: string;
+    /** Entrypoint names the manifest exposes: npm script keys / Makefile targets. */
+    names: string[];
+    /** Why nothing is checkable (kind === 'none' only). */
+    why?: string;
+}
+/**
+ * The explicit targets a Makefile declares. Deliberately conservative — this list
+ * only ever has to answer "does the project expose `migrate`", so a missed exotic
+ * target costs a false FAIL and is the one error worth avoiding:
+ *   • recipe lines (leading TAB) are skipped — they are shell, not targets;
+ *   • `:=` / `::=` / `?=` / `+=` assignments are skipped;
+ *   • pattern rules (`%.o: %.c`) and dot-targets (`.PHONY:`) fail TARGET_NAME_RE,
+ *     which is also why the names listed AFTER `.PHONY:` are ignored here: they are
+ *     prerequisites, and every one of them that is real is declared by its own rule.
+ * Multiple targets on one line (`build test:`) all count.
+ */
+export declare function makeTargets(src: string): string[];
+/**
+ * Resolve the manifest the launch contract may be diffed against.
+ *
+ * A package.json that exists but does not parse resolves to `none`, not to "zero
+ * scripts": diffing against a manifest you could not read is exactly the mistake
+ * this module exists to stop, and a broken manifest is the static checks' business.
+ */
+export declare function readLaunchManifest(cwd: string): LaunchManifest;
+/**
+ * The one line an INERT contract leaves behind. It rides in the gate's UNOBSERVED
+ * channel rather than in `warnings` for the reason nexttask 16A gives: a check that
+ * silently did nothing must not read later as a check that passed.
+ */
+export declare function inertLaunchContractNote(declared: string[], manifest: LaunchManifest): string;

package/dist/task/launch-manifest.js

@@ -0,0 +1,151 @@
+/**
+ * launch-manifest — WHICH manifest the launch-contract diff is entitled to diff
+ * against, and whether there is one at all (nexttask 16A).
+ *
+ * The defect this closes (unobserved, proven by construction). The extraction end
+ * of the launch contract has no ecosystem test anywhere in it:
+ * `enumerateScriptCandidates` scrapes backticked, script-name-shaped tokens out of
+ * any design paragraph that says "script", and `keepGroundedScripts` can only DROP
+ * a candidate. So a CMake / cargo / poetry / Makefile design saying *"the Makefile
+ * must expose `build`, `test`, `migrate`"* records exactly the same artifact an npm
+ * design does. The diff end hardcoded the ecosystem anyway:
+ *
+ *     missingDeclaredScripts(declared, Object.keys(packageScripts(cwd)))
+ *     …where packageScripts' catch returns {} — so "this project has no
+ *     package.json" was indistinguishable from "its package.json declares no
+ *     scripts", and every declared script was reported missing, at rank 1, in
+ *     wording that NAMES a file the project was never meant to have.
+ *
+ * That text seeds the autofix child's prompt (final-gate.ts's FinalGateOutcome.reason),
+ * so the most likely repair on a CMake project was to write a package.json.
+ *
+ * IAR1 is how close this got: `plan-debug.log:10` records "launch-contract
+ * extraction: 0 grounded script(s) kept from 3 emitted" — a non-npm project that
+ * reached extraction and emitted three candidates, saved only by its design not
+ * backticking them in a "script" paragraph.
+ *
+ * THE RULE, and it is deliberately two ecosystems wide, not three:
+ *   • package.json present and parseable ⇒ diff against its `scripts` keys, exactly
+ *     as before (byte-identical failure text on every npm tree — mx5's missing
+ *     `build`/`seed` is a TRUE positive and must keep failing).
+ *   • no package.json but a Makefile ⇒ diff against its TARGETS. The capability was
+ *     already in final-gate.ts (`makeHasTarget`); the diff simply never called it.
+ *   • neither ⇒ the check is INERT. No failure, and a note saying the contract was
+ *     recorded but is not checkable here, so the silence is not read later as a pass
+ *     (the repo-health-check / env-template-closure discipline: ENOENT = pass, and a
+ *     check must never invent a file the project chose not to have).
+ *
+ * cargo/poetry/gradle are NOT here on purpose. The corpus on this box contains one
+ * project that ever recorded a launch contract (mx5, npm) and one non-npm project
+ * that reached extraction (IAR1, CMake). A third ecosystem would be a guess.
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import * as path from 'node:path';
+/** GNU make's own lookup order, and nothing beyond it — this is one ecosystem. */
+const MAKEFILE_NAMES = ['GNUmakefile', 'makefile', 'Makefile'];
+/** A target we are willing to name in a failure: an ordinary word-shaped target. */
+const TARGET_NAME_RE = /^[a-z0-9][a-z0-9._-]{0,39}$/i;
+/**
+ * A variable assignment, in every form make accepts (`=`, `:=`, `::=`, `?=`, `+=`,
+ * `!=`, with an optional `override`/`export`). Matched BEFORE the target rule
+ * because `FLAGS ::= -O2` otherwise reads as a target named `FLAGS`.
+ */
+const ASSIGN_RE = /^(?:override\s+|export\s+)?[A-Za-z_][A-Za-z0-9_.]*\s*(?:::|:|\?|\+|!)?=/;
+/**
+ * The explicit targets a Makefile declares. Deliberately conservative — this list
+ * only ever has to answer "does the project expose `migrate`", so a missed exotic
+ * target costs a false FAIL and is the one error worth avoiding:
+ *   • recipe lines (leading TAB) are skipped — they are shell, not targets;
+ *   • `:=` / `::=` / `?=` / `+=` assignments are skipped;
+ *   • pattern rules (`%.o: %.c`) and dot-targets (`.PHONY:`) fail TARGET_NAME_RE,
+ *     which is also why the names listed AFTER `.PHONY:` are ignored here: they are
+ *     prerequisites, and every one of them that is real is declared by its own rule.
+ * Multiple targets on one line (`build test:`) all count.
+ */
+export function makeTargets(src) {
+    const out = [];
+    const seen = new Set();
+    for (const raw of src.replace(/\r\n?/g, '\n').split('\n')) {
+        if (raw.startsWith('\t') || raw.trim().length === 0 || raw.trimStart().startsWith('#'))
+            continue;
+        if (ASSIGN_RE.test(raw))
+            continue;
+        const m = /^([^:#=]+):(?![=])/.exec(raw);
+        if (!m)
+            continue;
+        for (const tok of m[1].trim().split(/\s+/)) {
+            if (!TARGET_NAME_RE.test(tok))
+                continue;
+            const key = tok.toLowerCase();
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push(tok);
+        }
+    }
+    return out;
+}
+/**
+ * The makefiles that really exist in `cwd`, in GNU make's lookup order, named as
+ * the DIRECTORY spells them. `existsSync` cannot do this job: on a case-insensitive
+ * filesystem (Windows, macOS) `existsSync('makefile')` is true for a `Makefile`, and
+ * the failure text would then name a file the project does not have.
+ */
+function makefilesOnDisk(cwd) {
+    let entries;
+    try {
+        entries = readdirSync(cwd);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const want of MAKEFILE_NAMES) {
+        const hit = entries.find(e => e.toLowerCase() === want.toLowerCase());
+        if (hit && !out.includes(hit))
+            out.push(hit);
+    }
+    return out;
+}
+/**
+ * Resolve the manifest the launch contract may be diffed against.
+ *
+ * A package.json that exists but does not parse resolves to `none`, not to "zero
+ * scripts": diffing against a manifest you could not read is exactly the mistake
+ * this module exists to stop, and a broken manifest is the static checks' business.
+ */
+export function readLaunchManifest(cwd) {
+    const pkg = path.join(cwd, 'package.json');
+    if (existsSync(pkg)) {
+        try {
+            const j = JSON.parse(readFileSync(pkg, 'utf8'));
+            return { kind: 'npm', file: 'package.json', names: Object.keys(j.scripts ?? {}) };
+        }
+        catch {
+            return { kind: 'none', file: '', names: [], why: 'its package.json could not be parsed' };
+        }
+    }
+    for (const name of makefilesOnDisk(cwd)) {
+        try {
+            return {
+                kind: 'make',
+                file: name,
+                names: makeTargets(readFileSync(path.join(cwd, name), 'utf8'))
+            };
+        }
+        catch {
+            break;
+        }
+    }
+    return { kind: 'none', file: '', names: [], why: 'it has no npm manifest and no Makefile' };
+}
+/**
+ * The one line an INERT contract leaves behind. It rides in the gate's UNOBSERVED
+ * channel rather than in `warnings` for the reason nexttask 16A gives: a check that
+ * silently did nothing must not read later as a check that passed.
+ */
+export function inertLaunchContractNote(declared, manifest) {
+    return (`launch contract: ${declared.length} declared script(s) (${declared.join(', ')}) were recorded, `
+        + `but this project could not be diffed against a manifest — ${manifest.why ?? 'no manifest'}. `
+        + 'The contract was NOT checked here.');
+}

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

@@ -16,6 +16,13 @@ import { type SpawnFn } from '../shared/child-process.js';
 export interface AutoInstallPin {
     source: 'declared-range' | 'npm-latest';
     range?: string;
+    /**
+     * The package the CALLER asked about — the HEAD of the resolution chain, not
+     * its terminal. `bun -> @types/bun -> bun-types` resolves correctly and must
+     * keep doing so, but the sentence a banner writes is about `bun`: the project
+     * cannot declare `bun-types`, and was never asked about it.
+     */
+    asked?: string;
 }
 export type DocsRawResult = {
     kind: 'ok';
@@ -85,14 +92,48 @@ export interface DocsFocusedResult {
 }
 export type DocsFocusedInput = DocsRawInput;
 export declare function extractParentPackage(moduleName: string): string;
+/** What a project's package.json says about one package, whether or not the
+ *  value is something the install path could use. */
+export interface Declaration {
+    /** The dependency-map KEY the declaration was found under. */
+    pkg: string;
+    /** Its value, trimmed — `^1.2.0`, `latest`, `workspace:*`. */
+    value: string;
+    /** False for dist-tags, wildcards and non-registry protocols. */
+    usable: boolean;
+}
+/**
+ * The names a declaration for `asked` can honestly live under, nearest first:
+ * the package itself, its DefinitelyTyped package, and the terminal the type
+ * resolution chain landed on. A project that uses Bun declares `@types/bun`, not
+ * `bun`; asking only about the terminal `bun-types` finds nothing at all, which
+ * is how 35 of run 20's 48 banners came to report on a package nobody asked
+ * about.
+ */
+export declare function declarationChain(asked: string, resolved?: string): string[];
+/**
+ * The first declaration for any name in `names`, searching the four standard
+ * dependency maps of `cwd`'s package.json. A USABLE declaration always wins;
+ * only if none of the names has one does an unusable declaration (a dist-tag or
+ * a non-registry protocol) come back, so the caller can tell "declared as
+ * `latest`" apart from "not declared at all" — two different facts that used to
+ * produce the same sentence. Returns null when no name appears anywhere, or the
+ * package.json is missing or unparseable. Best-effort; never throws.
+ */
+export declare function findDeclaration(names: string[], cwd: string): Declaration | null;
 /**
  * The version range a project DECLARES for `parentPkg` in its package.json under
  * `cwd`. Lets a not-yet-installed scaffolding dependency be documented against
  * the major the project intends, instead of whatever npm currently tags
- * `latest`. Scans the four standard dependency maps in priority order. Returns
- * null — caller falls back to latest — when the dep is undeclared, the
- * package.json is missing/unreadable, or the declared value is not a usable
- * range. Best-effort; never throws.
+ * `latest`. Returns null — caller falls back to latest — when the dep is
+ * undeclared, the package.json is missing/unreadable, or the declared value is
+ * not a usable range.
+ *
+ * This is the INSTALL target and takes one name deliberately: `npm install
+ * <parentPkg>@<range>` must use the range declared for `parentPkg` itself.
+ * `@types/bun`'s range is not `bun`'s. The banner's wider, chain-aware question
+ * is `findDeclaration`; keeping them apart is what stops a wording fix from
+ * silently changing what gets installed.
  */
 export declare function findDeclaredRange(parentPkg: string, cwd: string): string | null;
 /**
@@ -102,8 +143,14 @@ export declare function findDeclaredRange(parentPkg: string, cwd: string): strin
  * the prose the impl model reads, rather than burying it in tool `details`.
  * Empty string when there was no auto-install (already-installed packages need
  * no banner — their version is the project's own).
+ *
+ * `resolved` is the package the types were finally read from — the TERMINAL of
+ * the redirect chain. The banner names `pin.asked`, the package the caller asked
+ * about, and mentions the terminal only as provenance: a project can declare
+ * `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, pkgName: string, version: string): string;
+export declare function buildVersionBanner(pin: AutoInstallPin | undefined, resolved: string, version: string, cwd: string): string;
 export declare function getDocsModulesDir(): string;
 export declare function ensureDocsModulesDir(dir: string): void;
 export declare function runAutoInstall(spawn: SpawnFn, packageName: string, signal: AbortSignal | undefined, versionRange?: string): Promise<{

package/dist/workers/docs-core.js

@@ -43,15 +43,32 @@ function isUsableRange(range) {
     return true;
 }
 /**
- * The version range a project DECLARES for `parentPkg` in its package.json under
- * `cwd`. Lets a not-yet-installed scaffolding dependency be documented against
- * the major the project intends, instead of whatever npm currently tags
- * `latest`. Scans the four standard dependency maps in priority order. Returns
- * null — caller falls back to latest — when the dep is undeclared, the
- * package.json is missing/unreadable, or the declared value is not a usable
- * range. Best-effort; never throws.
+ * The names a declaration for `asked` can honestly live under, nearest first:
+ * the package itself, its DefinitelyTyped package, and the terminal the type
+ * resolution chain landed on. A project that uses Bun declares `@types/bun`, not
+ * `bun`; asking only about the terminal `bun-types` finds nothing at all, which
+ * is how 35 of run 20's 48 banners came to report on a package nobody asked
+ * about.
  */
-export function findDeclaredRange(parentPkg, cwd) {
+export function declarationChain(asked, resolved) {
+    const out = [asked];
+    const types = typesPackageName(asked);
+    if (types && !out.includes(types))
+        out.push(types);
+    if (resolved && !out.includes(resolved))
+        out.push(resolved);
+    return out;
+}
+/**
+ * The first declaration for any name in `names`, searching the four standard
+ * dependency maps of `cwd`'s package.json. A USABLE declaration always wins;
+ * only if none of the names has one does an unusable declaration (a dist-tag or
+ * a non-registry protocol) come back, so the caller can tell "declared as
+ * `latest`" apart from "not declared at all" — two different facts that used to
+ * produce the same sentence. Returns null when no name appears anywhere, or the
+ * package.json is missing or unparseable. Best-effort; never throws.
+ */
+export function findDeclaration(names, cwd) {
     let json;
     try {
         json = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
@@ -59,15 +76,40 @@ export function findDeclaredRange(parentPkg, cwd) {
     catch {
         return null;
     }
-    for (const field of DEP_FIELDS) {
-        const map = json[field];
-        if (!map || typeof map !== 'object')
-            continue;
-        const range = map[parentPkg];
-        if (typeof range === 'string' && isUsableRange(range))
-            return range.trim();
+    let unusable = null;
+    for (const name of names) {
+        for (const field of DEP_FIELDS) {
+            const map = json[field];
+            if (!map || typeof map !== 'object')
+                continue;
+            const range = map[name];
+            if (typeof range !== 'string')
+                continue;
+            const value = range.trim();
+            if (isUsableRange(value))
+                return { pkg: name, value, usable: true };
+            unusable ??= { pkg: name, value, usable: false };
+        }
     }
-    return null;
+    return unusable;
+}
+/**
+ * The version range a project DECLARES for `parentPkg` in its package.json under
+ * `cwd`. Lets a not-yet-installed scaffolding dependency be documented against
+ * the major the project intends, instead of whatever npm currently tags
+ * `latest`. Returns null — caller falls back to latest — when the dep is
+ * undeclared, the package.json is missing/unreadable, or the declared value is
+ * not a usable range.
+ *
+ * This is the INSTALL target and takes one name deliberately: `npm install
+ * <parentPkg>@<range>` must use the range declared for `parentPkg` itself.
+ * `@types/bun`'s range is not `bun`'s. The banner's wider, chain-aware question
+ * is `findDeclaration`; keeping them apart is what stops a wording fix from
+ * silently changing what gets installed.
+ */
+export function findDeclaredRange(parentPkg, cwd) {
+    const found = findDeclaration([parentPkg], cwd);
+    return found?.usable === true ? found.value : null;
 }
 /**
  * One-line version-provenance banner that LEADS a docs answer for a package the
@@ -76,18 +118,54 @@ export function findDeclaredRange(parentPkg, cwd) {
  * the prose the impl model reads, rather than burying it in tool `details`.
  * Empty string when there was no auto-install (already-installed packages need
  * no banner — their version is the project's own).
+ *
+ * `resolved` is the package the types were finally read from — the TERMINAL of
+ * the redirect chain. The banner names `pin.asked`, the package the caller asked
+ * about, and mentions the terminal only as provenance: a project can declare
+ * `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 function buildVersionBanner(pin, pkgName, version) {
+export function buildVersionBanner(pin, resolved, version, cwd) {
     if (!pin)
         return '';
+    const asked = pin.asked ?? resolved;
+    const grounded = resolved !== asked ? ` The types this answer reads come from ${resolved}.` : '';
     if (pin.source === 'declared-range') {
-        return (`[VERSION] "${pkgName}" resolved to this project's declared range `
-            + `${pin.range} (installed v${version}); the answer below is pinned to that version.\n\n`);
+        return (`[VERSION] "${asked}" resolved to this project's declared range `
+            + `${pin.range} (installed v${version}); the answer below is pinned to that `
+            + `version.${grounded}\n\n`);
+    }
+    // The install fell back to npm latest. A usable declaration can still exist
+    // further along the chain (`@types/<name>`) — it did not pin THIS install, so
+    // the banner reports it as provenance, not as a pin.
+    const decl = findDeclaration(declarationChain(asked, resolved), cwd);
+    // Declared, but as a dist-tag or a non-registry protocol. That is NOT the
+    // same fact as undeclared: the project did say what it wants, `latest` is
+    // exactly what this answer is grounded in, and so there is no other major to
+    // confirm and nothing to hold as unverified. Only the SENTENCE splits —
+    // `isUsableRange` still rejects the value and the install path still cannot
+    // use it as an `install <pkg>@<range>` target.
+    if (decl && !decl.usable) {
+        const where = decl.pkg === asked ? '' : ` only through ${decl.pkg},`;
+        return (`[VERSION] "${asked}" is declared in this project's package.json${where} as `
+            + `\`${decl.value}\` — a moving tag, not a pinned range — so this answer is based `
+            + `on npm latest (v${version}), which is what that declaration resolves to `
+            + `today.${grounded}\n\n`);
+    }
+    // A usable range on the ASKED name with an npm-latest pin means package.json
+    // gained the declaration between the install and this sentence. Rare, but the
+    // alternative wording would flatly contradict itself.
+    if (decl?.usable === true && decl.pkg === asked) {
+        return (`[VERSION — verify] "${asked}" is declared as ${decl.value}, but this answer is `
+            + `based on npm latest (v${version}) — the install was not pinned to that range. `
+            + `Confirm the version you intend before relying on an API that differs across `
+            + `majors.${grounded}\n\n`);
     }
-    return (`[VERSION — verify] "${pkgName}" is not declared in this project's package.json, `
+    const via = decl?.usable === true ? ` — only its types are, as ${decl.pkg} ${decl.value} —` : ',';
+    return (`[VERSION — verify] "${asked}" is not declared in this project's package.json${via} `
         + `so this answer is based on npm latest (v${version}). Your project may target a `
         + `different MAJOR — confirm the version you intend to install and treat any API that `
-        + `differs across majors as unverified until you check it against that version.\n\n`);
+        + `differs across majors as unverified until you check it against that version.${grounded}\n\n`);
 }
 export function getDocsModulesDir() {
     const base = process.env.XDG_CACHE_HOME?.trim() || path.join(os.homedir(), '.cache');
@@ -208,8 +286,8 @@ export async function docsRaw(input) {
             const declaredRange = findDeclaredRange(parentPkg, input.cwd);
             autoInstallPin =
                 declaredRange ?
-                    { source: 'declared-range', range: declaredRange }
-                    : { source: 'npm-latest' };
+                    { source: 'declared-range', range: declaredRange, asked: parentPkg }
+                    : { source: 'npm-latest', asked: parentPkg };
             const installResult = await runAutoInstall(spawn, parentPkg, undefined, declaredRange ?? undefined);
             if (!installResult.success) {
                 return {

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

@@ -251,7 +251,7 @@ export function registerPiWorkerDocs(pi, internals = {}) {
                 };
             }
             if (rawResult.kind === 'no_chunks') {
-                const banner = buildVersionBanner(rawResult.autoInstallPin, rawResult.pkg.name, rawResult.pkg.version);
+                const banner = buildVersionBanner(rawResult.autoInstallPin, rawResult.pkg.name, rawResult.pkg.version, ctx.cwd);
                 return {
                     text: banner
                         + npmHeader
@@ -269,7 +269,7 @@ export function registerPiWorkerDocs(pi, internals = {}) {
             }
             // kind === 'ok'
             const { pkg, chunks, hitCache, indexingMs, cacheError, autoInstalled } = rawResult;
-            const versionBanner = buildVersionBanner(rawResult.autoInstallPin, pkg.name, pkg.version);
+            const versionBanner = buildVersionBanner(rawResult.autoInstallPin, pkg.name, pkg.version, ctx.cwd);
             const baseDetails = {
                 version: pkg.version,
                 hitCache,

package/package.json

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