@mjasnikovs/pi-task 0.38.28 → 0.38.30

package/dist/task/env-notes.js

@@ -1,7 +1,7 @@
 /**
  * env-notes — a per-run cache of ENVIRONMENT FACTS shared across gate children.
  *
- * The failure this serves (mx5 run 7, F8): every gate child re-discovers the
+ * The failure this serves: every gate child re-discovers the
  * same environment facts from scratch — where the DB credentials live, which
  * services are reachable, which tools are installed — burning minutes of
  * archaeology per child through the serial model bottleneck.
@@ -19,18 +19,21 @@
  * defect") still governs every verdict — the block injected into prompts says
  * so explicitly. The cache only kills re-discovery time.
  *
- * PROVENANCE + RE-VALIDATION (run 8, F7): a verify child once grepped component
- * names in a MINIFIED bundle (identifiers mangled ⇒ 0 hits by construction),
- * wrote "build tree-shakes ALL route components — pre-existing issue" to the
- * cache, and ten later tasks inherited it verbatim as a standing "pre-existing,
- * unrelated" excuse to wave off a genuinely broken deliverable — nobody
- * re-checked. Two guards close that class: (a) each note is stamped host-side
- * with the ORIGIN task that recorded it (a note is second-hand hearsay, not the
- * reader's own observation); (b) the injected block demands the reader
- * RE-VALIDATE a note in the CURRENT tree before citing it to excuse a failure,
- * flags EXCUSE-CLASS notes ("pre-existing", "unrelated", "tree-shaken") for
- * exactly that scrutiny, and forbids treating a grep of a generated artifact as
- * evidence of absence. Provenance is mechanical; re-validation is prompt-level.
+ * PROVENANCE + RE-VALIDATION. A shared cache has a failure mode a per-child one
+ * does not: a WRONG fact propagates. The shape to fear is a verify child grepping
+ * component names in a MINIFIED bundle — identifiers there are mangled, so zero
+ * hits is guaranteed regardless of the truth — concluding "the build tree-shakes
+ * all route components, pre-existing issue", and every later task inheriting that
+ * verbatim as a standing excuse to wave off a genuinely broken deliverable.
+ * Nobody re-checks a fact that is already written down.
+ *
+ * Two guards close it. (a) Each note is stamped host-side with the ORIGIN task
+ * that recorded it, so it reads as second-hand hearsay rather than the reader's
+ * own observation. (b) The injected block demands the reader RE-VALIDATE a note
+ * in the CURRENT tree before citing it to excuse a failure, marks EXCUSE-CLASS
+ * notes for exactly that scrutiny, and states outright that a zero-hit grep of a
+ * generated artifact is not evidence of absence. Provenance is mechanical;
+ * re-validation is prompt-level.
  */
 import { makeLedger } from './ledger.js';
 const ENV_NOTES_FILE = 'env-notes.md';
@@ -45,8 +48,10 @@ const MAX_NOTE_LENGTH = 240;
  */
 const ORIGIN_SEP = '\t';
 /**
- * Parse the stored file into fact+origin records. Legacy lines written before
- * provenance (no separator) parse with an empty origin, so old caches still read.
+ * Parse the stored file into fact+origin records. A line with no separator parses
+ * with an empty origin rather than being dropped, so a cache written before
+ * provenance existed still reads — and `buildEnvNotesBlock` renders those as
+ * "origin unrecorded" instead of silently claiming an author.
  */
 export function parseEnvNotes(raw) {
     const out = [];
@@ -82,8 +87,10 @@ export async function readEnvNotes(cwd) {
     return ledger.readRaw(cwd);
 }
 /**
- * Pull `ENV-NOTE: <fact>` lines out of a child's answer text. Deduplicated,
- * length-capped; verdict markers can never match (different prefix).
+ * Pull `ENV-NOTE: <fact>` lines out of a child's answer text: trimmed,
+ * deduplicated case-insensitively, and dropped when empty or over
+ * MAX_NOTE_LENGTH. Run: a `VERDICT:` line and even a near-miss `ENV-NOTES:` line
+ * match nothing, so a verdict cannot leak into the fact cache.
  */
 export function extractEnvNotes(text) {
     const notes = [];
@@ -101,17 +108,22 @@ export function extractEnvNotes(text) {
     return notes;
 }
 /**
- * EXCUSE-CLASS wording: a note that waves a problem off as someone else's or a
- * prior condition ("pre-existing … mismatch", "unrelated to this task",
- * "tree-shaken", "not applicable"). These are the notes that propagate across
- * slices as standing excuses (mx5 run-8 F7) — every one of the run-8 cache's
- * dozen such notes was either the false tree-shake fact or the schema mismatch
- * the final gate later proved was a REAL defect. Pure text, stack-agnostic; the
- * flag never drops or fails a note, it only marks it as needing live
- * re-validation before it may EXCUSE a failure. FP is harmless by construction:
- * a benign fact re-validates and is used, the marker only bites a citation-to-
- * wave-off. Benign status facts ("5 pre-existing warnings") do not match — a
- * "pre-existing" match requires a co-located problem word.
+ * EXCUSE-CLASS wording: a note that waves a problem off as someone else's or as a
+ * prior condition. These are the notes that propagate across slices as standing
+ * excuses, and the ones most likely to be masking a real defect rather than
+ * describing the environment.
+ *
+ * Pure text, stack-agnostic. The flag never drops or fails a note — it only marks
+ * it as needing live re-validation before it may EXCUSE a failure, so a false
+ * positive is harmless: a benign fact re-validates and is used, and the marker
+ * only bites a citation-to-wave-off.
+ *
+ * Run against the shapes it has to separate: "unrelated to this task",
+ * "tree-shaken by the build", "pre-existing mismatch in the schema", "not
+ * applicable here" and "affects all routes" all flag, while the benign status
+ * fact "5 pre-existing warnings" does NOT — a "pre-existing" match needs a
+ * co-located problem word — and neither do ordinary facts like "postgres
+ * reachable on 5432".
  */
 const EXCUSE_PATTERNS = [
     /\bunrelated\b/i,
@@ -130,9 +142,14 @@ export function isExcuseNote(fact) {
 /**
  * Append newly discovered facts to the cache, deduplicated against what is
  * already there (case-insensitive fact match), keeping the newest MAX_NOTES.
- * Each new fact is stamped with the `origin` task that recorded it; a fact
- * already present keeps its ORIGINAL origin (provenance traces to who first
- * established it). Failures are swallowed — the cache is a sharpener, never a
+ * Each new fact is stamped with the `origin` task that recorded it; a fact already
+ * present keeps its ORIGINAL origin, so provenance traces to whoever first
+ * established it. Confirmed by re-appending the same fact under a different task:
+ * one entry survives, still carrying the first writer.
+ *
+ * Tabs in an emitted fact are normalised to spaces before storage, which is what
+ * keeps the separator unambiguous. The cap holds too — sixty further facts leave
+ * MAX_NOTES stored. Failures are swallowed: the cache is a sharpener, never a
  * blocker.
  */
 export async function appendEnvNotes(cwd, notes, origin = '') {

package/dist/task/env-template-closure.d.ts

@@ -2,10 +2,10 @@
  *  entry is a name no `.env.example` is expected to carry. */
 export declare const AMBIENT_ENV: Set<string>;
 /** The same rule by MECHANISM rather than by name: a variable INJECTED by a
- *  platform (CI runner, package manager, freedesktop base dirs). STEP 0 found
- *  `GITHUB_ENV` (written by GitHub Actions), `npm_execpath` and `XDG_CACHE_HOME`
- *  classified as required in real trees; a template that declared them would be
- *  wrong, so the exclusion is the prefix, not a growing list of names. */
+ *  platform — a CI runner, a package manager, freedesktop base dirs. `GITHUB_ENV`,
+ *  `npm_execpath` and `XDG_CACHE_HOME` all read as "required" to a naive scan in
+ *  real trees, and a template that declared any of them would be wrong. So the
+ *  exclusion is the PREFIX, not a list of names that would have to keep growing. */
 export declare const AMBIENT_PREFIXES: string[];
 /** Rule 4: is this variable the platform's to supply? */
 export declare function isAmbient(name: string): boolean;

package/dist/task/env-template-closure.js

@@ -1,26 +1,31 @@
 /**
  * env-template-closure — a shipped source file requires an env var the shipped
- * template never mentions (nexttask 10).
+ * template never mentions.
  *
- * The failure this closes (mx5 run 19, `dfbdd6f`, validated): `src/server/seed.ts`
- * reads `process.env.ADMIN_PHONE` / `ADMIN_PASSWORD` with no default, the tracked
- * `.env.example` declares only `DATABASE_URL` + `APP_URL`, and `bun run seed` was
- * one of the run's final-gate commands. It exited 1; the gate's autofix wrote the
- * two vars into `.env`, which is GITIGNORED (nexttask 4) — so the committed tree
- * still cannot seed and nothing at run end ever said why. Coverage credits the
- * CONSUMING side (seed.ts exists, is owned, passes its own VERIFY); the template is
- * a separate artifact nobody re-reads after TASK_0001.
+ * The failure this closes: a seed script reads `process.env.ADMIN_PHONE` and
+ * `ADMIN_PASSWORD` with no default while the tracked `.env.example` declares only
+ * `DATABASE_URL` and `APP_URL`. The seed command then exits 1, and an autofix
+ * "resolves" it by writing the two vars into `.env` — which is GITIGNORED, so the
+ * COMMITTED tree still cannot seed and nothing at run end says why.
+ *
+ * Coverage cannot see it: it credits the CONSUMING side, because the script exists,
+ * is owned, and passes its own VERIFY. The template is a separate artifact nobody
+ * re-reads after the task that wrote it.
+ *
+ * That exact shape, run against a real repo, produces the two findings and no
+ * others — `DATABASE_URL` is declared and stays silent.
  *
  * THE RULE. Every REQUIRED env read in TRACKED source must appear in the TRACKED
  * env template. One-directional: a variable DECLARED but never read is silence, not
- * a finding (dace-pro ships 13 declared / 7 required and must stay clean).
+ * a finding — a template carrying entries nothing reads yields zero findings, which
+ * is what keeps a deliberately over-declared template clean.
  *
  * REQUIRED is mechanical. A read steps aside when it:
  *   1. carries a default — `?? …`, `|| …`, `os.getenv('X', d)`, `environ.get('X', d)`;
  *   2. is compared, not consumed — `===`, `!==`, `==`, `!=` on either side;
  *   3. is an assignment TARGET — `process.env.DATABASE_URL = testDbUrl`, which is
- *      what every one of mx5's seven test files does and is the single largest FP
- *      source in the corpus;
+ *      what a test file typically does, and is the readiest source of false
+ *      positives;
  *   4. names an AMBIENT variable — a short fixed allowlist (below) of things the
  *      platform, not the project, supplies.
  *
@@ -32,14 +37,19 @@
  *     untracked scratch file can neither declare nor require anything.
  *   • generated/vendored trees (`dist/`, `build/`, `node_modules/`, …) are not
  *     authored source and are skipped; they only ever mirror a read we already saw.
- *   • NO TEMPLATE IN THE TREE ⇒ THE CHECK IS INERT (as `repo-health-check` does
- *     with a missing manifest). This must never invent a file the project chose
- *     not to have.
+ *   • NO TEMPLATE IN THE TREE ⇒ THE CHECK IS INERT, the way `repo-health-check`
+ *     treats a missing manifest. Confirmed: a repo with a required read and no
+ *     template at all yields zero findings, and so does a directory that is not a
+ *     git repo. This must never invent a file the project chose not to have.
+ *
+ * Not npm-shaped: JS/TS (`process.env` / `Bun.env`), Python (`os.environ[…]`,
+ * `os.environ.get`, `os.getenv`) and Go (`os.Getenv`) all read the same way. Go's
+ * `os.LookupEnv` is the explicit may-be-absent API and gets its own step-aside,
+ * `optional-api`.
  *
- * Not npm-shaped (`memory/gate-blind-on-non-npm-projects.md`): JS/TS
- * (`process.env` / `Bun.env`), Python (`os.environ[…]`, `os.environ.get`,
- * `os.getenv`) and Go (`os.Getenv`) read the same way. Go's `os.LookupEnv` is the
- * explicit may-be-absent API and is treated as its own step-aside.
+ * Every rule above was run: each of the four step-asides fires with its own label,
+ * comparison is caught on either side, all three languages produce a REQUIRED read,
+ * `os.LookupEnv` steps aside, and both dynamic forms extract nothing at all.
  */
 import { spawnSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
@@ -58,9 +68,8 @@ export const AMBIENT_ENV = new Set([
     'TMPDIR',
     'LANG',
     // Windows/OS equivalents of the above, and the package manager's own vars —
-    // every one of these was OBSERVED as a "required" read during STEP 0's
-    // hand-read (gofer-rag `npm_execpath`, the pi-task corpus's `LOCALAPPDATA` /
-    // `XDG_CACHE_HOME`), and none of them belongs in a project's template.
+    // every one of these reads as "required" to a naive scan (`npm_execpath`,
+    // `LOCALAPPDATA`, `XDG_CACHE_HOME`), and none belongs in a project's template.
     'APPDATA',
     'LOCALAPPDATA',
     'USERPROFILE',
@@ -73,10 +82,10 @@ export const AMBIENT_ENV = new Set([
     'COMSPEC'
 ]);
 /** The same rule by MECHANISM rather than by name: a variable INJECTED by a
- *  platform (CI runner, package manager, freedesktop base dirs). STEP 0 found
- *  `GITHUB_ENV` (written by GitHub Actions), `npm_execpath` and `XDG_CACHE_HOME`
- *  classified as required in real trees; a template that declared them would be
- *  wrong, so the exclusion is the prefix, not a growing list of names. */
+ *  platform — a CI runner, a package manager, freedesktop base dirs. `GITHUB_ENV`,
+ *  `npm_execpath` and `XDG_CACHE_HOME` all read as "required" to a naive scan in
+ *  real trees, and a template that declared any of them would be wrong. So the
+ *  exclusion is the PREFIX, not a list of names that would have to keep growing. */
 export const AMBIENT_PREFIXES = ['npm_', 'GITHUB_', 'RUNNER_', 'CI_', 'XDG_', 'BUN_', 'NODE_'];
 /** Rule 4: is this variable the platform's to supply? */
 export function isAmbient(name) {
@@ -160,7 +169,7 @@ const MATCHERS = [
  *  that opens with one? (`process.env.X\n    ?? 'y'` is one expression.)
  *
  *  A ternary CONDITION counts: `process.env.npm_execpath ? a : b` names both
- *  outcomes, so nothing is required (gofer-rag, hand-read in STEP 0). `?.` is
+ *  outcomes, so nothing is required. `?.` is
  *  optional chaining, not a ternary, and must not match. */
 function hasDefault(before, after, nextLine) {
     // The read IS the fallback: `X ?? process.env.BRAVE_API_KEY` (brave-warning.ts)
@@ -183,14 +192,14 @@ function hasDefault(before, after, nextLine) {
  *   `if (c) …`                               Playwright cache when unset
  *
  * The discriminator is the SIGN of the guard, and it is exactly what separates
- * those from the lead: mx5's seed.ts writes `const phone = process.env.ADMIN_PHONE`
+ * those from the lead: a seed script writes `const phone = process.env.ADMIN_PHONE`
  * … `if (!phone) throw`. A NEGATED guard means the variable is required and the
  * program stops without it; a POSITIVE guard means it is an override. So a bare
  * `if (` / `while (` head steps aside, `if (!` does not, and an assign-then-guard
  * is resolved by looking ahead for the FIRST guard on that variable.
  */
 const GUARD_HEAD_RE = /\b(?:if|while)\s*\(\s*$/;
-/** How far an assign-then-guard may reach. mx5's is 4 lines; 10 is slack. */
+/** How far an assign-then-guard may reach. A few lines is typical; 10 is slack. */
 const GUARD_LOOKAHEAD = 10;
 function isProbeHead(before) {
     return GUARD_HEAD_RE.test(before);
@@ -202,7 +211,7 @@ function assignedTo(before) {
 }
 /**
  * What the guard's own body does. A NEGATED guard only means "required" when the
- * program STOPS without the variable — `if (!phone) throw` (mx5, the lead). When
+ * program STOPS without the variable — `if (!phone) throw`. When
  * it merely returns or falls through — `if (!process.env.PI_REMOTE_PUSH_DEBUG)
  * return` (push.ts, a debug flag) — the variable is optional and the negation
  * proves nothing. Same syntax, opposite meaning; the body is the discriminator.
@@ -243,7 +252,7 @@ function locallySupplied(text, name) {
  *  it as an override, so every read of it in that file is a probe. Without this,
  *  the CONSUMING read inside the guarded branch — `if (process.env.PI_BIN) return
  *  {command: process.env.PI_BIN}` (pi-invocation.ts), `process.env.GOFER_PYTHON ?
- *  [process.env.GOFER_PYTHON] : [...]` (gofer) — reads as required. */
+ *  [process.env.PYTHON_BIN] : [...]` — reads as required. */
 function locallyProbed(text, name) {
     const e = `(?:process|Bun)\\.env\\s*\\.\\s*${name}`;
     return (new RegExp(`\\b(?:if|while)\\s*\\(\\s*${e}\\b`).test(text)
@@ -260,7 +269,7 @@ function isCompared(before, after) {
 }
 /** Rule 3: the read is a WRITE — `process.env.X = …` (but not `==`/`===`), or
  *  `delete process.env.X`. Both mean the file SUPPLIES the variable rather than
- *  consuming it; mx5's seven test files are the assignment case and gofer's
+ *  consuming it; a suite of test files is the assignment case and a
  *  `wdio.packaged.conf.ts` (`delete process.env.GOFER_GDFORMAT`) is the delete
  *  case — a scrub of a developer override, the opposite of a requirement. */
 function isAssigned(before, after) {
@@ -290,8 +299,7 @@ export function scanSource(file, text) {
                 // the RESULT is seen (`os.Getenv("X") == ""`).
                 const after = matcher.call ? raw.replace(/^\s*\)/, '') : raw;
                 // …and past any WRAPPING call's brackets, so `Number(process.env.X)
-                // || 32` (gofer-rag, the largest FP class the STEP-0 hand-read
-                // found) reads as defaulted. Stepping aside when the `||` in fact
+                // || 32` — the largest false-positive class — reads as defaulted. Stepping aside when the `||` in fact
                 // defaults an enclosing expression is a false NEGATIVE, which this
                 // check spends freely; a false rank-0 gate failure it does not.
                 // …and past a trailing accessor chain, so `process.env.X?.trim() ||

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

@@ -8,16 +8,19 @@
  * from the four research workers. `enrichment.ts` stays a pure parser; the I/O
  * lives here.
  *
- * There were TWO copies of this assembly: {@link gatherExternalContext} (the
- * research phase, raw workers) and an 87-line inline block in `phaseAutoAnswer`
- * (the grill auto-answer, focused workers). They agreed on everything that
- * shows up in the output — the 8-step shape, the "npm blocks lead" ordering,
- * the `### docs:` / `### url:` headings, the service loop's `no_key` / `error`
- * handling, the block terminator — and disagreed only on POLICY. So the shape
- * is {@link buildExternalContext} once, the disagreements are
- * {@link ExternalContextPolicy}, and the worker variant is
- * {@link ExternalContextLookups} — an adapter, expressible only since the
- * focused-extractor seam landed.
+ * TWO call paths share this assembly: the research phase via
+ * {@link gatherExternalContext} (raw workers) and the grill auto-answer via
+ * {@link buildExternalContext} directly (focused workers). Everything that shows
+ * up in the OUTPUT is identical between them — the "npm blocks lead" ordering, the
+ * `### docs:` / `### url:` headings, the service loop's `no_key` / `error`
+ * handling, the trailing blank-line terminator — and they differ only on POLICY.
+ *
+ * So the shape lives here once, the differences are {@link ExternalContextPolicy},
+ * and the raw-vs-focused worker choice is {@link ExternalContextLookups}, an
+ * adapter the focused-extractor seam made expressible.
+ *
+ * Run against a mixed source, the emitted headings come out in exactly that order:
+ * `### npm:` then `### docs:` then `### url:` then `### service:`.
  */
 import { type NpmVersionInfo } from '../workers/npm-version.js';
 import type { SearchCoreInput, SearchCoreResult } from '../workers/search-core.js';
@@ -48,8 +51,9 @@ export interface ExternalTargetResult {
  * whole page markdown, truncated), `phaseAutoAnswer` binds the FOCUSED ones (a
  * child's one-question answer). Everything else about the block is identical.
  *
- * A rejected lookup is caught by the builder and yields no blocks for that
- * target, so adapters may throw freely.
+ * A rejected lookup is caught by the builder and yields no blocks for that target,
+ * so adapters may throw freely. Confirmed: one adapter rejecting mid-fan-out
+ * leaves the other targets' blocks intact and contributes nothing of its own.
  */
 export interface ExternalContextLookups {
     docs(pkg: string): Promise<ExternalTargetResult | null>;
@@ -58,10 +62,11 @@ export interface ExternalContextLookups {
     search?: (input: SearchCoreInput) => Promise<SearchCoreResult>;
 }
 /**
- * The six places the two call paths genuinely disagreed. Each is a knob rather
- * than a default, because every one of them is a deliberate, measured choice on
- * at least one path — the auto-answer block is capped and records nothing
- * because it runs per grill question, in front of a waiting user.
+ * The five places the two call paths genuinely disagree. Each is a knob rather
+ * than a default, because every one is a deliberate choice on at least one path:
+ * the auto-answer block is capped and records nothing because it runs per grill
+ * question, in front of a waiting user, while research is uncapped and trails its
+ * sub-step.
  */
 export interface ExternalContextPolicy {
     /**
@@ -74,9 +79,9 @@ export interface ExternalContextPolicy {
     /**
      * 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
-     * auto-answer path does. Without this on the research path, deps past the
-     * docs cap had no live version and a "which version?" question fell back to
-     * the model's stale training data — how tailwindcss got pinned to an old major.
+     * auto-answer path does. Without it, any dep past the docs cap carries no live
+     * version at all, and a "which version?" question falls back to whatever the
+     * model remembers — which is how a dependency gets pinned to a stale major.
      */
     versionLookup?: (pkg: string) => Promise<NpmVersionInfo | null>;
     /** Sub-step label recorded via `deps.recordSubStep`. Omit to record nothing. */
@@ -89,8 +94,10 @@ export interface ExternalContextPolicy {
     earlyReturnOnNoTargets?: boolean;
 }
 /**
- * Assemble the `EXTERNAL CONTEXT\n…\n\n` block for `source`, or `''` when there
- * is nothing to enrich (no targets, or every lookup failed).
+ * Assemble the `EXTERNAL CONTEXT\n…\n\n` block for `source`, or `''` when there is
+ * nothing to enrich — no targets, or every lookup failed. Both were run: a source
+ * naming nothing returns `''`, and so does one whose only target is a service
+ * search that errored.
  */
 export declare function buildExternalContext(source: string, deps: GatherDeps, lookups: ExternalContextLookups, policy?: ExternalContextPolicy): Promise<string>;
 /**

package/dist/task/external-context.js

@@ -8,16 +8,19 @@
  * from the four research workers. `enrichment.ts` stays a pure parser; the I/O
  * lives here.
  *
- * There were TWO copies of this assembly: {@link gatherExternalContext} (the
- * research phase, raw workers) and an 87-line inline block in `phaseAutoAnswer`
- * (the grill auto-answer, focused workers). They agreed on everything that
- * shows up in the output — the 8-step shape, the "npm blocks lead" ordering,
- * the `### docs:` / `### url:` headings, the service loop's `no_key` / `error`
- * handling, the block terminator — and disagreed only on POLICY. So the shape
- * is {@link buildExternalContext} once, the disagreements are
- * {@link ExternalContextPolicy}, and the worker variant is
- * {@link ExternalContextLookups} — an adapter, expressible only since the
- * focused-extractor seam landed.
+ * TWO call paths share this assembly: the research phase via
+ * {@link gatherExternalContext} (raw workers) and the grill auto-answer via
+ * {@link buildExternalContext} directly (focused workers). Everything that shows
+ * up in the OUTPUT is identical between them — the "npm blocks lead" ordering, the
+ * `### docs:` / `### url:` headings, the service loop's `no_key` / `error`
+ * handling, the trailing blank-line terminator — and they differ only on POLICY.
+ *
+ * So the shape lives here once, the differences are {@link ExternalContextPolicy},
+ * and the raw-vs-focused worker choice is {@link ExternalContextLookups}, an
+ * adapter the focused-extractor seam made expressible.
+ *
+ * Run against a mixed source, the emitted headings come out in exactly that order:
+ * `### npm:` then `### docs:` then `### url:` then `### service:`.
  */
 import { docsRaw } from '../workers/docs-core.js';
 import { fetchRaw } from '../workers/fetch-core.js';
@@ -28,8 +31,10 @@ import { formatServiceBlock, formatFreshnessSkippedBlock } from './service-block
 /** How much of a docs/url body survives into the block, for the raw-worker lookups. */
 const RAW_BODY_LIMIT = 4000;
 /**
- * Assemble the `EXTERNAL CONTEXT\n…\n\n` block for `source`, or `''` when there
- * is nothing to enrich (no targets, or every lookup failed).
+ * Assemble the `EXTERNAL CONTEXT\n…\n\n` block for `source`, or `''` when there is
+ * nothing to enrich — no targets, or every lookup failed. Both were run: a source
+ * naming nothing returns `''`, and so does one whose only target is a service
+ * search that errored.
  */
 export async function buildExternalContext(source, deps, lookups, policy = {}) {
     const searchFn = lookups.search ?? defaultSearch;

package/dist/task/failure-classifier.d.ts

@@ -13,11 +13,10 @@ export interface FailureClass {
 }
 export declare function classifyFailure(err: unknown, aborted: boolean): FailureClass;
 /**
- * Persist, flash and announce a failure — and RETURN the classification.
+ * Persist, flash and announce a failure, and return the classification.
  *
- * It used to return `void`, so the name it had just computed died here and the
- * caller learned how the run ended by re-reading the task file's front matter and
- * narrowing it to a boolean. Handing the value back is what lets `TaskRunner.run`
- * say `RunEnd` instead.
+ * `TaskRunner.run` builds its `RunEnd` from the returned `state` and `reason`.
+ * The front-matter write here is what a later resume reads, not the channel
+ * this process uses to learn how the run ended.
  */
 export declare function handleFailure(err: unknown, ctx: ExtensionCommandContext, cwd: string, id: string, aborted: boolean): Promise<FailureClass>;

package/dist/task/failure-classifier.js

@@ -75,20 +75,19 @@ export function classifyFailure(err, aborted) {
     };
 }
 /**
- * Persist, flash and announce a failure — and RETURN the classification.
+ * Persist, flash and announce a failure, and return the classification.
  *
- * It used to return `void`, so the name it had just computed died here and the
- * caller learned how the run ended by re-reading the task file's front matter and
- * narrowing it to a boolean. Handing the value back is what lets `TaskRunner.run`
- * say `RunEnd` instead.
+ * `TaskRunner.run` builds its `RunEnd` from the returned `state` and `reason`.
+ * The front-matter write here is what a later resume reads, not the channel
+ * this process uses to learn how the run ended.
  */
 export async function handleFailure(err, ctx, cwd, id, aborted) {
     const c = classifyFailure(err, aborted);
     await updateTaskFrontMatter(cwd, id, { state: c.state, reason: c.reason });
     flashTerminalWidget(ctx, c.state, id, c.flash);
     ctx.ui.notify(`${id} ${c.notify}`, c.level);
-    // Mirror to remote viewers — ctx.ui.notify is terminal-only, so without this
-    // the remote view shows nothing when a task fails.
+    // Mirror to remote viewers. `ctx.ui.notify` reaches the terminal UI only, so
+    // without this call the remote view shows nothing when a task fails.
     publishLifecycleNotice(`${id} ${c.notify}`, c.level);
     return c;
 }

package/dist/task/file-inventory.d.ts

@@ -1,17 +1,21 @@
 /**
- * Project file inventory — runs `git ls-files` once per /task run so research
- * workers can skip their own discovery loops and jump straight to targeted
- * read/grep on known paths. Returns '' on failure (non-git repo, git missing,
- * timeout) so callers can fall back to the pre-inventory behavior.
+ * Project file inventory — `git ls-files`, capped, with the task directory
+ * stripped. `phaseResearch` computes it once and puts it in the header every
+ * research worker gets; `refineExistingFilesBlock` also uses it to pick the
+ * paths orientation pre-reads.
+ *
+ * Returns '' on failure: a non-git tree exits 128, and a missing binary reaches
+ * `runChildDefault`'s `error` handler as exit 1. Both callers treat '' as "no
+ * inventory" and carry on.
  */
 /**
- * Drop the committed task directory from the inventory. `git ls-files` lists
- * tracked files regardless of `.ignore`, so once tasks are committed they would
- * otherwise be handed to every research worker (and feed orientation). The user
- * wants tasks committable but invisible to workers and the local model, so we
- * strip `.pi-tasks/` here — the inventory's single chokepoint. (`git ls-files`
- * always emits posix-style paths, so the forward-slash prefix is correct on all
- * platforms.)
+ * Drop the committed task directory from the inventory. `git ls-files` lists a
+ * TRACKED file even when `.gitignore` matches it — confirmed against a real
+ * repo where `.pi-tasks/` is both ignored and committed — so once tasks are
+ * committed they reach every research worker and feed orientation unless they
+ * are stripped here. This is the only filter on the inventory path.
+ *
+ * `git ls-files` prints forward slashes, so the prefix matches as written.
  */
 export declare function stripTasksDir(raw: string): string;
 /** Cap output to maxLines real (non-blank) paths; tag truncation when cut. */

package/dist/task/file-inventory.js

@@ -1,20 +1,24 @@
 /**
- * Project file inventory — runs `git ls-files` once per /task run so research
- * workers can skip their own discovery loops and jump straight to targeted
- * read/grep on known paths. Returns '' on failure (non-git repo, git missing,
- * timeout) so callers can fall back to the pre-inventory behavior.
+ * Project file inventory — `git ls-files`, capped, with the task directory
+ * stripped. `phaseResearch` computes it once and puts it in the header every
+ * research worker gets; `refineExistingFilesBlock` also uses it to pick the
+ * paths orientation pre-reads.
+ *
+ * Returns '' on failure: a non-git tree exits 128, and a missing binary reaches
+ * `runChildDefault`'s `error` handler as exit 1. Both callers treat '' as "no
+ * inventory" and carry on.
  */
 import { makeGit } from '../shared/git-runner.js';
 import { TASKS_DIR_NAME } from './task-types.js';
 const DEFAULT_MAX_LINES = 2000;
 /**
- * Drop the committed task directory from the inventory. `git ls-files` lists
- * tracked files regardless of `.ignore`, so once tasks are committed they would
- * otherwise be handed to every research worker (and feed orientation). The user
- * wants tasks committable but invisible to workers and the local model, so we
- * strip `.pi-tasks/` here — the inventory's single chokepoint. (`git ls-files`
- * always emits posix-style paths, so the forward-slash prefix is correct on all
- * platforms.)
+ * Drop the committed task directory from the inventory. `git ls-files` lists a
+ * TRACKED file even when `.gitignore` matches it — confirmed against a real
+ * repo where `.pi-tasks/` is both ignored and committed — so once tasks are
+ * committed they reach every research worker and feed orientation unless they
+ * are stripped here. This is the only filter on the inventory path.
+ *
+ * `git ls-files` prints forward slashes, so the prefix matches as written.
  */
 export function stripTasksDir(raw) {
     const prefix = `${TASKS_DIR_NAME}/`;
@@ -24,19 +28,18 @@ export function stripTasksDir(raw) {
         .join('\n');
 }
 /**
- * `git ls-files`, or '' on ANY failure — non-git tree, missing git, cancelled run.
- * The empty string is the caller's fall-back-to-pre-inventory signal, so every
- * unhappy path has to collapse to it.
+ * `git ls-files`, or '' on ANY failure — non-git tree, missing git, cancelled
+ * run. '' is the signal both callers branch on, so every unhappy path has to
+ * collapse to it.
  *
- * Runs on the shared GitRunner (`shared/git-runner.ts`), which brings the abort
- * discipline this used to hand-roll: the listener is detached when the child
- * settles normally, so a run-long orchestrator signal does not accumulate one
- * retained child per invocation (GitHub issue #9).
+ * Runs on the shared GitRunner, whose child detaches its abort listener when it
+ * settles: one AbortController is shared across a whole run, so a listener left
+ * attached per call would retain each finished child.
  *
- * The `signal.aborted` check is what preserves this function's OWN contract on
- * cancellation. A killed child closes with a null exit code, which the runner
- * reports as 0 — so without it a cancelled run would hand back a truncated
- * inventory as if it were complete, where the hand-rolled version returned ''.
+ * The `signal.aborted` check is what holds the contract on cancellation. A
+ * killed child closes with a null exit code and `runChild` reports `code ?? 0`,
+ * so without the check a cancelled run would return partial stdout as if the
+ * listing were complete.
  */
 async function runGitLsFiles(cwd, signal) {
     const git = makeGit(cwd, signal);