@mjasnikovs/pi-task 0.38.29 → 0.38.30

package/dist/task/yolo.js

@@ -8,13 +8,14 @@
  *
  * WHY PER-SITE, NOT ONE HOOK (the trap this module exists to avoid): the single
  * interactive choke point is SessionUI.ask() (remote/bridge.ts) — auto-picking
- * "index 0" inside it would be one tiny patch, and it would be wrong. The
- * verify-FAIL picker is reached ONLY AFTER MAX_AUTO_AUTOFIX unattended autofix
- * attempts have already failed, yet it STILL tints AUTOFIX as recommended: a
- * central hook would pick AUTOFIX forever and defeat the exact cap that exists to
- * break a non-converging loop. So every site decides for itself, BEFORE ask() is
- * called — which also means the prompt notification (the lone pushNotify in
- * ask()) is suppressed structurally, with zero suppression code.
+ * "index 0" inside it would be one tiny patch, and it would be wrong. One way the
+ * verify-FAIL picker is reached is after MAX_AUTO_AUTOFIX unattended autofix
+ * attempts have all failed, and it STILL tints AUTOFIX as recommended, because the
+ * research still recommends it. A central hook would pick AUTOFIX forever and
+ * defeat the exact cap that exists to break a non-converging loop. So every site
+ * decides for itself, BEFORE ask() is called — which also means the prompt
+ * notification (bridge.ts holds exactly one pushNotify, inside ask()) is
+ * suppressed structurally, with zero suppression code.
  *
  * Guard direction (repo constraint): an auto-pick may cost time, never work.
  * Anything this module cannot stand behind — no recommendation to take, an answer
@@ -27,10 +28,11 @@
  */
 import { getConfig } from '../config/config.js';
 /**
- * Visible provenance marker on EVERY artifact an auto-pick writes (gate trails,
- * task-file Q&A, the debt ledger's reason text). A later audit reading only the
- * artifacts must never mistake an auto-pick for a human decision — that is the
- * same confusion the accept-debt origins were introduced to prevent.
+ * Visible provenance marker on the artifacts an auto-pick writes: gate trail lines
+ * and the task file's Q&A record (qa-transcript.ts `QA_PROVENANCE`). A later audit
+ * reading only the artifacts must never mistake an auto-pick for a human decision.
+ * The debt ledger does not use this stamp — it carries the `'yolo-accepted'` ORIGIN
+ * instead, which is stronger: a typed field rather than text.
  */
 export const YOLO_STAMP = '(YOLO)';
 /** Is unattended auto-pick on for this run? The ONLY config read in this module. */
@@ -38,16 +40,17 @@ export function isYoloMode() {
     return getConfig().yoloMode;
 }
 /**
- * The clarify/grill policy: take the RECOMMENDED option — which is positional,
- * index 0 of the card list (question-box.ts tints it green), i.e. `suggested`,
- * falling back to the B-side `alt` when a fork offers only that.
+ * The clarify/grill policy: take the RECOMMENDED option — `suggested`, falling
+ * back to the B-side `alt` when a fork offers only that. Recommended is positional
+ * for a human too: bridge.ts marks card index 0, and question-box.ts tints the
+ * marked card green.
  *
  * `unsafe` is the step-aside channel: a caller that KNOWS the recommendation must
- * not be auto-accepted passes why, and the question is skipped instead. Its one
- * producer today is the anti-synthesis demotion — an answer proven to name a
- * hallucinated API identifier. Auto-accepting that would re-promote exactly the
- * invention the demotion was built to stop (it reached requirements AND the VERIFY
- * block in mx5 run 13), so a machine may never take it; a human still can.
+ * not be auto-accepted passes why, and the question is skipped instead. The only
+ * thing that supplies it is `yoloPickAutoAnswer` below, on the anti-synthesis
+ * demotion — an answer proven to name an unverified API identifier. Auto-accepting
+ * that would re-promote exactly the invention the demotion exists to stop, so a
+ * machine may never take it; a human still can.
  */
 export function yoloPickAnswer(enabled, opts) {
     if (!enabled)
@@ -62,12 +65,12 @@ export function yoloPickAnswer(enabled, opts) {
     return { kind: 'answer', answer: pick };
 }
 /**
- * The same policy expressed over an {@link AutoAnswer}, for the grill site. Only
- * the ANTI-SYNTHESIS unknown is unsafe: the other two producers (an integration
- * unknown research could not ground, a child that threw) carry an ordinary
- * best-effort recommendation, which is precisely what a human would be shown as
- * the green card. The variants are told apart by the union's `reason` tag — never
- * by pattern-matching the answer text.
+ * The same policy expressed over an {@link AutoAnswer}, for the grill site. Of the
+ * four `reason` tags an unknown can carry — `api-synthesis`, `integration`,
+ * `threw`, `model-unknown` — only ANTI-SYNTHESIS is unsafe. The other three carry
+ * an ordinary best-effort recommendation, which is precisely what a human would be
+ * shown as the green card. The variants are told apart by that tag, never by
+ * pattern-matching the answer text.
  */
 export function yoloPickAutoAnswer(enabled, auto) {
     if (!enabled)
@@ -85,25 +88,27 @@ export function yoloPickAutoAnswer(enabled, auto) {
 /**
  * The verify-FAIL picker policy: ACCEPT (and write a debt), never AUTOFIX.
  *
- * Not a preference — a bound. Every branch that REACHES this picker has already
- * spent its unattended budget: the loop auto-runs AUTOFIX while the research
- * recommends it, up to MAX_AUTO_AUTOFIX consecutive failures, and only then hands
- * over. Answering AUTOFIX here would restart that budget from a site whose whole
- * purpose is that the budget ran out. So YOLO takes the terminal option and
- * records the defect ('yolo-accepted' — an origin a human never produces).
+ * Not a preference — a bound. task-gates.ts consults this only after its own
+ * unattended paths are exhausted: `autoFixNow` has run AUTOFIX up to
+ * MAX_AUTO_AUTOFIX times while the research recommended it, and the YOLO rescue has
+ * spent its one attempt on an ACCEPT recommendation with an untouched budget.
+ * Answering AUTOFIX here would restart that budget from the very site that proves
+ * it ran out. So YOLO takes the terminal option and records the defect under the
+ * `'yolo-accepted'` debt origin, which a human decision never produces.
  */
 export function yoloVerifyResolution(enabled) {
     return enabled ? { action: 'accept' } : null;
 }
 /**
- * The final-integration-gate policy: keep autofixing WHILE the picker still
- * offers that card (the loop withdraws it after MAX_FINAL_GATE_AUTOFIX attempts),
- * then leave the run FAILED.
+ * The final-integration-gate policy: keep autofixing WHILE the picker still offers
+ * that card — run-final-gate.ts withdraws it from `options` after
+ * MAX_FINAL_GATE_AUTOFIX attempts, and passes that as `canAutofix` — then leave the
+ * run FAILED.
  *
  * 'leave', not 'accept': an unattended run that cannot fix the whole-repo gate has
- * not produced a working project, and the honest terminal state is a failed run a
- * resume can re-enter — mx5 run 13 ended "FAIL accepted by user" on an app that
- * 404'd at `/`, and that acceptance is what made the failure look like a success.
+ * not produced a working project. The honest terminal state is a failed run a
+ * resume can re-enter. Accepting instead would make the failure read as a success
+ * in every artifact that survives the run.
  */
 export function yoloFinalGateChoice(enabled, canAutofix) {
     if (!enabled)

package/dist/workers/abstention.d.ts

@@ -3,31 +3,19 @@
  * content it was given cannot answer the question, and the one place both halves
  * of that contract live.
  *
- * Why one module. The sentinel has two halves that MUST agree: the sentence a
+ * WHY ONE MODULE. The sentinel has two halves that MUST agree: the sentence a
  * prompt instructs the child to emit, and the predicate that later recognises it.
- * They used to be independent. Three prompts wrote three phrasings — two of them
- * as bare string literals buried in a template — and four regexes matched
- * different subsets of the three:
- *
- *   pi-worker-docs   /unclear from this package/i          (package only)
- *   typeonly-log     /unclear from this (package|project)/i (no page)
- *   type-only-answer /unclear from this (package|page)/i    (no project)
- *   pi-worker-fetch  no check at all
- *
- * That already cost one bug, recorded in typeonly-log: matching only the first
- * silently scored every PROJECT abstention as a valid answer. The fix went into
- * that one regex; the other three never learned.
- *
- * And it was still live on the fetch channel. pi-worker-docs documents F-2(e) at
- * length — an "unclear" non-answer exits 0, so it was memoised into the research
- * cache and re-served to every sibling task (52 of run 15's cached entries were
- * "unclear" with hitCache true), one dead end paid for many times, with
- * escalation unable to re-fire because the miss never recurred. `pi-worker-fetch`
- * cached on `childExitCode === 0` alone, so "unclear from this page" reproduced
- * exactly that failure on pages instead of packages.
- *
- * With emitter and matcher reading one table, a fourth corpus is one row and
- * cannot be half-wired.
+ * Held apart, each corpus grows its own phrasing and its own regex, and a regex
+ * that names only some of the corpora scores the rest as real answers — silently,
+ * because a non-answer is well-formed output. Here `buildExtractionPrompt` and
+ * `ABSTENTION_RE` are both built from `NOUNS`, so a new corpus is one row in that
+ * table and cannot be half-wired.
+ *
+ * The consumers split two ways. It must not be SCORED as an answer
+ * (typeonly-log.ts, task/type-only-answer.ts) and it must not be CACHED as one
+ * (`docsCacheable` in pi-worker-docs.ts, `fetchCacheable` in pi-worker-fetch.ts) —
+ * a non-answer exits 0 like any other, so a cache keyed on exit code alone
+ * memoises the dead end and re-serves it to every later sibling.
  */
 /** The content a focused extractor was pointed at. One row per corpus. */
 export type AbstentionKind = 'package' | 'project' | 'page';
@@ -37,28 +25,20 @@ export type AbstentionKind = 'package' | 'project' | 'page';
  * describing what the prompts actually ask for.
  */
 export declare function abstentionSentence(kind: AbstentionKind): string;
-/**
- * True when the child declined to answer rather than answering.
- *
- * Callers use this for two different decisions and both matter: it must not be
- * SCORED as an answer (typeonly-log, type-only-answer), and it must not be
- * CACHED as one (pi-worker-docs, pi-worker-fetch) — a memoised non-answer is
- * re-served to every later sibling and permanently suppresses escalation.
- */
+/** True when the child declined to answer rather than answering. See the header
+ *  for the two decisions this drives. */
 export declare function isAbstention(text: string): boolean;
 /**
- * The extraction prompt every corpus shares.
+ * The extraction prompt every corpus shares — docs-core.ts and docs-project.ts
+ * both build theirs here, differing only in the nouns this signature takes.
  *
- * Rules 1–5 were word-for-word identical in the npm and project prompt builders,
- * differing only in the four nouns this signature takes — and one of those, the
- * abstention sentence in rule 4, was a bare literal that the matchers above then
- * had to guess at. Building the prompt from the same table that recognises its
- * output is the whole point: rule 4 tells the child to write EXACTLY the sentence
- * `isAbstention` looks for, by construction.
+ * Rule 4 interpolates `abstentionSentence`, so the sentence the child is told to
+ * write is by construction the sentence `isAbstention` looks for. Typing the words
+ * instead is what lets the two drift.
  *
  * `subject` is the prose noun ("npm package", "local project's source code");
- * `tag` names both the identity element and the content element, which must match
- * because rules 1, 2 and 4 all refer to `<{tag}-content>`.
+ * `tag` names both the identity element and the content element, and the two must
+ * match because rules 1, 2 and 4 all refer to `<{tag}-content>`.
  */
 export declare function buildExtractionPrompt(opts: {
     kind: AbstentionKind;

package/dist/workers/abstention.js

@@ -3,31 +3,19 @@
  * content it was given cannot answer the question, and the one place both halves
  * of that contract live.
  *
- * Why one module. The sentinel has two halves that MUST agree: the sentence a
+ * WHY ONE MODULE. The sentinel has two halves that MUST agree: the sentence a
  * prompt instructs the child to emit, and the predicate that later recognises it.
- * They used to be independent. Three prompts wrote three phrasings — two of them
- * as bare string literals buried in a template — and four regexes matched
- * different subsets of the three:
+ * Held apart, each corpus grows its own phrasing and its own regex, and a regex
+ * that names only some of the corpora scores the rest as real answers — silently,
+ * because a non-answer is well-formed output. Here `buildExtractionPrompt` and
+ * `ABSTENTION_RE` are both built from `NOUNS`, so a new corpus is one row in that
+ * table and cannot be half-wired.
  *
- *   pi-worker-docs   /unclear from this package/i          (package only)
- *   typeonly-log     /unclear from this (package|project)/i (no page)
- *   type-only-answer /unclear from this (package|page)/i    (no project)
- *   pi-worker-fetch  no check at all
- *
- * That already cost one bug, recorded in typeonly-log: matching only the first
- * silently scored every PROJECT abstention as a valid answer. The fix went into
- * that one regex; the other three never learned.
- *
- * And it was still live on the fetch channel. pi-worker-docs documents F-2(e) at
- * length — an "unclear" non-answer exits 0, so it was memoised into the research
- * cache and re-served to every sibling task (52 of run 15's cached entries were
- * "unclear" with hitCache true), one dead end paid for many times, with
- * escalation unable to re-fire because the miss never recurred. `pi-worker-fetch`
- * cached on `childExitCode === 0` alone, so "unclear from this page" reproduced
- * exactly that failure on pages instead of packages.
- *
- * With emitter and matcher reading one table, a fourth corpus is one row and
- * cannot be half-wired.
+ * The consumers split two ways. It must not be SCORED as an answer
+ * (typeonly-log.ts, task/type-only-answer.ts) and it must not be CACHED as one
+ * (`docsCacheable` in pi-worker-docs.ts, `fetchCacheable` in pi-worker-fetch.ts) —
+ * a non-answer exits 0 like any other, so a cache keyed on exit code alone
+ * memoises the dead end and re-serves it to every later sibling.
  */
 /**
  * The noun each corpus calls itself IN THE PROMPT. The sentinel is built from
@@ -51,40 +39,31 @@ export function abstentionSentence(kind) {
  * Matches any corpus's abstention. Built from the same table the prompts read, so
  * adding a corpus cannot leave a matcher behind.
  *
- * Deliberately a SUBSTRING match, unlike fetch-core's separate
- * `not covered by this page` sentinel, which is anchored. The two differ because
- * the instructions differ: the "not covered" rule asks for a partial answer that
- * NAMES what is missing, so a sourced answer can legitimately contain the phrase
- * and an anchored match is required to avoid filing it as a coverage miss. The
- * abstention rule asks for the sentinel INSTEAD of an answer, and models wrap it
- * ("Unclear from this package — the README does not mention it."), so anchoring
- * here would miss the real non-answers this exists to catch.
+ * A SUBSTRING match, unlike fetch-core's separate `not covered by this page`
+ * sentinel, which is anchored. The instructions differ, so the matchers must. The
+ * "not covered" rule asks for a partial answer that NAMES what is missing, so a
+ * sourced answer legitimately contains the phrase and only an anchored match keeps
+ * it from being filed as a coverage miss. Rule 4 below asks for this sentinel
+ * INSTEAD of an answer, so nothing sourced can contain it, and a substring match
+ * still catches a child that wraps the sentence in an explanation.
  */
 const ABSTENTION_RE = new RegExp(`unclear\\s+from\\s+this\\s+(${Object.values(NOUNS).join('|')})\\b`, 'i');
-/**
- * True when the child declined to answer rather than answering.
- *
- * Callers use this for two different decisions and both matter: it must not be
- * SCORED as an answer (typeonly-log, type-only-answer), and it must not be
- * CACHED as one (pi-worker-docs, pi-worker-fetch) — a memoised non-answer is
- * re-served to every later sibling and permanently suppresses escalation.
- */
+/** True when the child declined to answer rather than answering. See the header
+ *  for the two decisions this drives. */
 export function isAbstention(text) {
     return ABSTENTION_RE.test(text);
 }
 /**
- * The extraction prompt every corpus shares.
+ * The extraction prompt every corpus shares — docs-core.ts and docs-project.ts
+ * both build theirs here, differing only in the nouns this signature takes.
  *
- * Rules 1–5 were word-for-word identical in the npm and project prompt builders,
- * differing only in the four nouns this signature takes — and one of those, the
- * abstention sentence in rule 4, was a bare literal that the matchers above then
- * had to guess at. Building the prompt from the same table that recognises its
- * output is the whole point: rule 4 tells the child to write EXACTLY the sentence
- * `isAbstention` looks for, by construction.
+ * Rule 4 interpolates `abstentionSentence`, so the sentence the child is told to
+ * write is by construction the sentence `isAbstention` looks for. Typing the words
+ * instead is what lets the two drift.
  *
  * `subject` is the prose noun ("npm package", "local project's source code");
- * `tag` names both the identity element and the content element, which must match
- * because rules 1, 2 and 4 all refer to `<{tag}-content>`.
+ * `tag` names both the identity element and the content element, and the two must
+ * match because rules 1, 2 and 4 all refer to `<{tag}-content>`.
  */
 export function buildExtractionPrompt(opts) {
     const { tag } = opts;

package/dist/workers/brave-search.d.ts

@@ -7,9 +7,10 @@ export interface BraveSearchOpts {
     timeoutMs?: number;
     signal?: AbortSignal;
     /**
-     * Injectable fetch. Brave was the ONE provider without this: exa and ddg both
-     * took a `fetchImpl`, so brave's status ladder — the widest of the three — was
-     * the only one no test could drive at the request level.
+     * Injectable fetch. All three search providers accept one. Brave gets the most
+     * out of it: its status ladder is the widest — three branches (auth,
+     * rate-limit, http) against DuckDuckGo's two and Exa's one — and
+     * http-request.test.ts drives 401/403/429/503 straight through this seam.
      */
     fetchImpl?: FetchLike;
 }

package/dist/workers/brave-search.js

@@ -27,8 +27,11 @@ export async function braveSearch(query, opts) {
                 'x-subscription-token': opts.apiKey
             }
         }, async (response) => {
-            // Brave's own status policy: a rejected key and a rate limit are
-            // different problems for the user, and neither is a plain HTTP fault.
+            // A rejected key and a rate limit are different problems for the
+            // user, so each throws its own MESSAGE rather than the generic
+            // `Brave Search HTTP <n>`. That message is what reaches the user:
+            // search-core turns any BraveSearchError into
+            // `{kind: 'error', message}` and passes the text through verbatim.
             if (response.status === 401 || response.status === 403) {
                 throw new BraveSearchError(`Brave Search rejected the key (HTTP ${response.status}). Check BRAVE_SEARCH_API_KEY.`, 'auth', response.status);
             }

package/dist/workers/brave-warning.d.ts

@@ -1,8 +1,11 @@
 /**
- * One-line startup hint shown when Brave is the selected search provider but
- * no key is configured (Brave is the only provider that needs one — exa and
- * ddg are keyless, so no hint renders for them). It never blocks work and
- * clears itself on the first interaction (any keystroke).
+ * One-line startup hint shown when Brave is the selected search provider but no
+ * key is configured. Brave is the only provider that needs one:
+ * `SEARCH_PROVIDER_KEY_ENV` in search-types.ts gives exa and ddg an empty var
+ * list, so no hint can render for them.
+ *
+ * It never blocks work. registerSessionHint renders it only in TUI mode and
+ * clears it on the first raw keystroke.
  */
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 export declare function registerBraveKeyWarning(pi: ExtensionAPI): void;

package/dist/workers/brave-warning.js

@@ -1,8 +1,11 @@
 /**
- * One-line startup hint shown when Brave is the selected search provider but
- * no key is configured (Brave is the only provider that needs one — exa and
- * ddg are keyless, so no hint renders for them). It never blocks work and
- * clears itself on the first interaction (any keystroke).
+ * One-line startup hint shown when Brave is the selected search provider but no
+ * key is configured. Brave is the only provider that needs one:
+ * `SEARCH_PROVIDER_KEY_ENV` in search-types.ts gives exa and ddg an empty var
+ * list, so no hint can render for them.
+ *
+ * It never blocks work. registerSessionHint renders it only in TUI mode and
+ * clears it on the first raw keystroke.
  */
 import { getConfig } from '../config/config.js';
 import { registerSessionHint } from './session-hint.js';
@@ -10,12 +13,21 @@ const WIDGET_KEY = 'pi-task-brave-warning';
 const WARNING = '⚠ pi-task: search provider is Brave but BRAVE_SEARCH_API_KEY is not set — web search '
     + 'is disabled. Get a free key at https://api.search.brave.com/app/keys or switch '
     + 'provider in /task-config';
-/** Mirrors the lookup in search-core so the hint matches what the worker reads. */
+/**
+ * The same two env vars, in the same order, that `SEARCH_PROVIDER_KEY_ENV` lists
+ * for brave — a second copy, because this runs at session_start with no provider
+ * in hand.
+ *
+ * The two are not byte-equivalent. `??` skips only null/undefined, while
+ * `searchProviderKey` skips any falsy value, so `BRAVE_SEARCH_API_KEY=""` with
+ * `BRAVE_API_KEY` set makes search work while this still warns. Erring toward
+ * showing the hint is the harmless direction.
+ */
 function hasBraveKey() {
     return Boolean(process.env.BRAVE_SEARCH_API_KEY ?? process.env.BRAVE_API_KEY);
 }
 export function registerBraveKeyWarning(pi) {
-    // Only the brave provider can be misconfigured; say nothing whenever another
-    // provider is selected or a key is already present.
+    // Only the brave provider can be misconfigured, so returning null — say
+    // nothing — is the answer for every other provider and for a key already set.
     registerSessionHint(pi, WIDGET_KEY, () => getConfig().searchProvider !== 'brave' || hasBraveKey() ? null : { text: WARNING });
 }

package/dist/workers/ddg-search.d.ts

@@ -1,11 +1,11 @@
 /**
- * Web search via DuckDuckGo's HTML endpoint — no API key required.
+ * Web search by scraping DuckDuckGo's HTML endpoint. No API key: search-types.ts
+ * gives `ddg` an empty env-var list.
  *
- * DDG has no official web-results API; html.duckduckgo.com/html serves plain
- * HTML result pages that parse cleanly with linkedom. Result links are wrapped
- * in a `duckduckgo.com/l/?uddg=<encoded>` redirect that we unwrap so callers
- * get the destination URL. Ad rows redirect through duckduckgo.com itself and
- * are dropped.
+ * `html.duckduckgo.com/html/?q=…` serves an ordinary result page that linkedom
+ * parses. Its result links are wrapped in a `//duckduckgo.com/l/?uddg=<encoded>`
+ * redirect, which `unwrapDdgRedirect` below decodes so callers get the
+ * destination URL rather than the tracker.
  */
 import { type FetchLike } from './http-request.js';
 import type { SearchResult } from './search-types.js';

package/dist/workers/ddg-search.js

@@ -1,11 +1,11 @@
 /**
- * Web search via DuckDuckGo's HTML endpoint — no API key required.
+ * Web search by scraping DuckDuckGo's HTML endpoint. No API key: search-types.ts
+ * gives `ddg` an empty env-var list.
  *
- * DDG has no official web-results API; html.duckduckgo.com/html serves plain
- * HTML result pages that parse cleanly with linkedom. Result links are wrapped
- * in a `duckduckgo.com/l/?uddg=<encoded>` redirect that we unwrap so callers
- * get the destination URL. Ad rows redirect through duckduckgo.com itself and
- * are dropped.
+ * `html.duckduckgo.com/html/?q=…` serves an ordinary result page that linkedom
+ * parses. Its result links are wrapped in a `//duckduckgo.com/l/?uddg=<encoded>`
+ * redirect, which `unwrapDdgRedirect` below decodes so callers get the
+ * destination URL rather than the tracker.
  */
 import { parseHTML } from 'linkedom';
 import { httpRequest, HttpRequestError } from './http-request.js';
@@ -13,7 +13,9 @@ const DDG_ENDPOINT = 'https://html.duckduckgo.com/html/';
 const DEFAULT_COUNT = 10;
 const MAX_COUNT = 20;
 const DEFAULT_TIMEOUT_MS = 15_000;
-// DDG serves a bot-challenge page to clients without a browser-ish UA.
+// Required. Without a browser-ish UA the same request answers HTTP 202 with a
+// different page — no `result__a` rows at all, and the words "anomaly" and
+// "challenge" in the body — so the parser would return an empty list.
 const USER_AGENT = 'Mozilla/5.0 (X11; Linux x86_64; rv:127.0) Gecko/20100101 Firefox/127.0';
 export class DdgSearchError extends Error {
     kind;
@@ -39,7 +41,8 @@ export async function ddgSearch(query, opts = {}) {
                 accept: 'text/html'
             }
         }, async (response) => {
-            // DDG's own status policy: 429/403 is throttling, not a plain HTTP fault.
+            // 429 and 403 both mean throttling here, so they share one `kind` and
+            // one message rather than falling into the generic HTTP branch.
             if (response.status === 429 || response.status === 403) {
                 throw new DdgSearchError(`DuckDuckGo is rate-limiting this client (HTTP ${response.status}). Try again in a moment.`, 'rate-limit', response.status);
             }
@@ -67,7 +70,9 @@ export function parseDdgHtml(html) {
             continue;
         const href = anchor.getAttribute('href');
         const targetUrl = href === null ? null : unwrapDdgRedirect(href);
-        // A row whose link never leaves duckduckgo.com is an ad/module, not a hit.
+        // A row whose link never leaves duckduckgo.com is an ad or a module, not a
+        // hit. This also drops an `l/?` href carrying no `uddg`, and one whose
+        // `uddg` does not decode to a URL.
         if (targetUrl === null)
             continue;
         const title = collapse(anchor.textContent ?? '');
@@ -80,9 +85,10 @@ export function parseDdgHtml(html) {
     return results;
 }
 /**
- * Result hrefs look like `//duckduckgo.com/l/?uddg=<encoded-destination>&rut=…`;
- * return the decoded destination, a non-DDG href unchanged, or null for links
- * that stay on duckduckgo.com (ad click-trackers).
+ * Result hrefs look like `//duckduckgo.com/l/?uddg=<encoded-destination>&rut=…`.
+ * Returns the decoded destination, a non-DDG href unchanged, or null for a link
+ * that stays on duckduckgo.com — no `uddg`, an undecodable one, or an unparseable
+ * href.
  */
 function unwrapDdgRedirect(href) {
     let parsed;

package/dist/workers/docs-cache.js

@@ -35,13 +35,16 @@ CREATE TRIGGER IF NOT EXISTS chunks_ad AFTER DELETE ON chunks BEGIN
 END;
 `;
 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
+// `node:sqlite` under bun throws ERR_UNKNOWN_BUILTIN_MODULE. `createRequire`
+// keeps both specifiers out of the static import graph, so neither bundler nor
+// type-checker has to resolve the one that is absent.
 function openDb(dbPath) {
     if (typeof globalThis.Bun !== 'undefined') {
-        // Bun runtime: use bun:sqlite
         const { Database } = req('bun:sqlite');
         return new Database(dbPath);
     }
-    // Node.js runtime: use node:sqlite
     const { DatabaseSync } = req('node:sqlite');
     return new DatabaseSync(dbPath);
 }

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

@@ -1,29 +1,24 @@
 /**
- * docs-chunk — cutting source text into retrievable chunks, for every corpus the
- * docs Worker tool indexes.
+ * docs-chunk — cutting source text into retrievable chunks, for both corpora the
+ * docs Worker tool indexes: an npm package's `.d.ts` + README (docs-index.ts),
+ * and the local project's own `.ts`/`.tsx` (docs-project.ts).
  *
- * There are two corpora — an npm package's `.d.ts` + README, and the local
- * project's own `.ts`/`.tsx` — and they were chunked by two copies of this code.
- * Not similar code: the same chunk-split regex, the same size cap, byte-identical
- * `chunkDts`/`chunkTs` bodies, and byte-identical `splitAtMatches`/`sliceBytes`,
- * in `docs-index.ts` and `docs-project.ts`. One copy had tests; the other
- * (`docs-project.ts`, 319 lines) had no test file at all and was only ever
- * reached incidentally through the worker's own suite.
+ * The chunk boundary is load-bearing for retrieval: a chunk that splits a
+ * declaration in half matches on neither half's terms, so one boundary rule for
+ * both corpora is the point of this module.
  *
- * The chunk boundary is load-bearing for retrieval quality — a chunk that splits
- * a declaration in half retrieves as neither — so having it in two places was two
- * places for it to drift.
- *
- * What is NOT unified: the two INDEX bodies. They key on genuinely different
- * provenance (a package is name+version with a content hash and keeps its old
- * versions; the project is a cwd key with a max-mtime version and drops its old
- * ones on every re-index), and collapsing them would change one of those
- * behaviours rather than describe them.
+ * What is NOT shared: the two INDEX bodies. They key on genuinely different
+ * provenance. A package is `(name, version)` with a content hash, and re-indexing
+ * runs `DELETE FROM chunks WHERE name = ? AND version = ?`, so older versions
+ * survive. The project is a cwd-hash name with a max-mtime version, and
+ * re-indexing runs `DELETE FROM chunks WHERE name = ?`, dropping every older
+ * version. Collapsing them would change one of those behaviours, not describe it.
  */
 /**
- * Chunk ceiling. Chosen against the retrieval budget: chunks are assembled into
- * a fixed character budget for the extraction child, so a chunk larger than this
- * would crowd out every other result.
+ * Chunk ceiling, in UTF-8 bytes. Sized against the retrieval budget: retrieved
+ * chunks are assembled into `RETRIEVE_CONTENT_BUDGET` (24,000 characters) before
+ * going to the extraction child, so this caps any one chunk at about a third of
+ * what the child will ever see.
  */
 export declare const MAX_CHUNK_BYTES: number;
 /**
@@ -44,30 +39,28 @@ export declare function splitAtMatches(text: string, re: RegExp): string[];
  * Cut a string into pieces of at most `maxBytes` UTF-8 bytes, never splitting a
  * character.
  *
- * The cut point is walked BACK to a UTF-8 lead byte first. Both copies of this
- * function used to cut at exactly `maxBytes` and rely on
- * `Buffer.toString('utf8')` to tidy up, which it does not: decoding a buffer that
- * ends mid-character yields a U+FFFD replacement character. That replacement is
- * 3 bytes wide, so measuring the advance by the decoded slice's byte length then
- * skipped PAST the straddling character. A `€`-dense chunk came out as
- * `€€€�€€€�…` — corrupted, and one character shorter per slice.
+ * The cut point is walked BACK to a UTF-8 lead byte first. Cutting at exactly
+ * `maxBytes` and letting `Buffer.toString('utf8')` tidy up does not work: decoding
+ * a buffer that ends mid-character yields U+FFFD. That replacement is 3 bytes
+ * wide, so the decoded slice measures LONGER than the cut — a 100-byte cut of
+ * `€`-dense text decodes to 102 bytes — and advancing by the decoded length then
+ * skips past the straddling character entirely.
  *
  * It matters beyond looking wrong: a chunk is quoted back as an `<excerpt>` and
- * checked verbatim against the source, and an excerpt carrying a replacement
- * character can never be found, so the answer is flagged as a possible
- * hallucination. Only reachable on non-ASCII text past the 8 KB chunk ceiling,
- * which is why two copies of it survived untested.
+ * checked verbatim against the source (`excerptVerified`), and an excerpt carrying
+ * a replacement character can never be found, so the answer is flagged as a
+ * possible hallucination. Only reachable on non-ASCII text past the chunk ceiling.
  */
 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.
  *
- * `relPath` is a MODEL-FACING label and is used exactly as given — the npm path
- * normalises it to POSIX first so an index is identical across platforms, while
- * the project path keeps the native separator. It is never re-joined to the
- * filesystem, so neither choice is wrong; passing it through keeps that decision
- * with the caller that has a reason for it.
+ * `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.
  */
 export declare function chunkDeclarations(content: string, relPath: string): string[];
 /** Chunk a README, one chunk per top-level section, each labelled by heading. */