@mjasnikovs/pi-task 0.18.48 → 0.18.50

package/README.md

@@ -9,7 +9,7 @@
 [![npm](https://img.shields.io/npm/v/@mjasnikovs/pi-task?color=cb3837&logo=npm)](https://www.npmjs.com/package/@mjasnikovs/pi-task)
 [![license](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](./LICENSE)
 [![pi extension](https://img.shields.io/badge/pi-extension-7c3aed)](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)
-[![tests](https://img.shields.io/badge/tests-1936%20passing-3fb950)](#development)
+[![tests](https://img.shields.io/badge/tests-2077%20passing-3fb950)](#development)
 [![types](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)](./tsconfig.json)
 
 </div>
@@ -65,7 +65,7 @@ A whole plan — `/task-auto` splits it into an ordered task list and runs each
 | `/task-auto <feature>` | Plan a feature into a task list and run each title through `/task` in order (resumable). |
 | `/task-auto-resume [--unattended]` | Resume the active `/task-auto` run at the next unfinished task. `--unattended` is the boot-hook form: in-flight runs only. |
 | `/task-auto-cancel` | Stop the `/task-auto` loop after the current task (still resumable). |
-| `/task-config` | Toggle pi-task settings in an editor dialog: remote server, compress reasoning, auto-commit, orientation, verify work, enforce guidelines, command timeout, stream watchdog, and the extension whitelist for child sessions. |
+| `/task-config` | Toggle pi-task settings in an editor dialog: remote control, compress thinking, auto-commit, verify work, enforce guidelines, project tour, command timeout, stuck reply retry, and one `ext:` toggle per installed host extension. |
 | `/remote` | Show the QR code & URLs for the web view (`/remote stop` to stop). Answer grill questions, start tasks, and watch progress from your phone. |
 
 ## The pipeline
@@ -171,25 +171,25 @@ Run `/task-config` to toggle pi-task's behavior in an editor dialog. Settings pe
 
 | Setting | Default | What it does |
 | --- | --- | --- |
-| **remote** | on | The remote UI server (QR code, phone access). Turn off to never start it. |
-| **compress reasoning** | on | After each message, compresses the model's `<think>` blocks down to the decisions/constraints/facts that matter later — keeping long local-model runs from drowning their own context in self-talk. |
+| **remote control** | on | The remote UI server (QR code, phone access). Turn off to never start it. |
+| **compress thinking** | on | After each message, compresses the model's `<think>` blocks down to the decisions/constraints/facts that matter later — keeping long local-model runs from drowning their own context in self-talk. |
 | **auto-commit** | on | Snapshots the working tree into one git commit per `/task-auto` sub-task (see above). |
-| **orientation** | on | Pre-reads the project's core files (manifest, config, domain types, schema, entrypoints, API surface) once and hands the contents to the read-heavy research workers, so they skip re-discovering the same files cold. Bounded by a hard byte budget; applied only where it helps (FILES/APIS workers). |
 | **verify work** | on | After each `/task` (and `/task-auto` task) implements — but **before** it's checked off or committed — actually **runs** the spec's own `VERIFY` block in the real workspace. pi-task otherwise only _authors_ a VERIFY block and never executes it, so a task that doesn't build is indistinguishable from one that works. A fresh `read` + `bash` child of the same local model runs the declared check, observes the real output, and reports **PASS/FAIL** (a legitimately no-op VERIFY is a PASS). On FAIL the run doesn't dead-stop: you get a boxed picker — **Autofix** (re-run the implementation turn against the failure, then re-verify; no attempt cap) or **Accept** (override a misjudged artifact) — and dismissing it pauses the run, resumable. A genuine clean pass is also the behavioral signal that lets **enforce guidelines** fix in place (see below). |
 | **enforce guidelines** | on | After each `/task` (and `/task-auto` task) is committed, re-checks that commit's work against the project's `AGENTS.md` / `CLAUDE.md` (in the working directory). A bare fix-in-place pass trashes working code (A/B-proven), so enforcement is gated on the **verify work** signal. **With** a genuine verify pass: a fresh `read` + `edit` child of the same local model reads the **last commit's** diff and fixes violations in place; its fixes are committed **separately** as an `ENFORCE GUIDELINES` commit, then the verify signal is re-run against the enforced tree — a regression **reverts** the enforce commit and keeps the verified work. **Without** that signal (verify off, no spec, or an accept-override): the pass runs read-only and only **reports** violations, never rewrites logic. Either way a violation it can't clear (or a pass that can't run) only **warns** — the task commit already landed, so the run continues. Skipped when nothing was committed for the task. |
+| **project tour** | on | Pre-reads the project's core files (manifest, config, domain types, schema, entrypoints, API surface) once and hands the contents to the read-heavy research workers, so they skip re-discovering the same files cold. Bounded by a hard byte budget; applied only where it helps (FILES/APIS workers). |
 | **parallel research** | off | Run the four research workers concurrently instead of one at a time. Leave off on a single-GPU local backend (concurrent streams split the GPU and slow each other down); turn on only for a parallel-capable model server. |
 | **research cache** | on | Cache docs/search/fetch worker results for the duration of one `/task-auto` run so sibling tasks re-asking the same package/URL + query reuse the first pipeline's digest instead of re-fetching. Per-run isolated, external-only (project-source `.` lookups excluded), success-only. |
-| **search provider** | Exa | Engine behind `pi-worker-search` and freshness/enrichment checks. **Exa** (default) and **DuckDuckGo** need no API key; **Brave** requires `BRAVE_SEARCH_API_KEY`. |
+| **search engine** | Exa | Engine behind `pi-worker-search` and freshness/enrichment checks. **Exa** (default) and **DuckDuckGo** need no API key; **Brave** requires `BRAVE_SEARCH_API_KEY`. |
 | **command timeout** | 15 min | Wall-clock ceiling on a **single** tool execution. Local models routinely run a command that never returns (a hung build, a dev server, a check with no timeout) and the run wedges until you abort by hand — pi's bash tool has an optional timeout with no default, so this is the missing one. One knob, two surfaces: in the main session the overrun call is cancelled (killing the tool's whole process tree) plus a reminder turn; in the verify/fix gate children the child is killed and re-spawned with a hint, halving the ceiling on repeat hangs. Choices: 5/10/15/30 min or **off** — off unguards both surfaces, gates included. |
-| **stream watchdog** | 10 min | Inactivity ceiling on the **model stream**. A hung or silently-dropped stream throws nothing at all, so neither the connection-error retry (it needs a reported error) nor the **command timeout** (tool calls only) nor the dead-backend stall guard (a reachable endpoint reads as proof of life) can see it — an mx5 run lost ~2.9h to three of them while the model server stayed healthy. Measured as time since the **last stream event of any kind**, so a slow model emitting one token every 30s is never touched, and it pauses while a tool runs. On expiry the main session aborts the turn (through the same channel the command watchdog uses) and posts a resume reminder; a child is killed and routed into the existing connection-error retry. Choices: 5/10/20/30 min or **off**. Keep it generous on local backends — prompt processing on a large context legitimately emits nothing for minutes. |
+| **stuck reply retry** | 10 min | Inactivity ceiling on the **model stream**. A hung or silently-dropped stream throws nothing at all, so neither the connection-error retry (it needs a reported error) nor the **command timeout** (tool calls only) nor the dead-backend stall guard (a reachable endpoint reads as proof of life) can see it — an mx5 run lost ~2.9h to three of them while the model server stayed healthy. Measured as time since the **last stream event of any kind**, so a slow model emitting one token every 30s is never touched, and it pauses while a tool runs. On expiry the main session aborts the turn (through the same channel the command watchdog uses) and posts a resume reminder; a child is killed and routed into the existing connection-error retry. Choices: 5/10/20/30 min or **off**. Keep it generous on local backends — prompt processing on a large context legitimately emits nothing for minutes. |
 | **yolo mode** | off | **Unattended runs.** Wherever pi-task would stop and ask, it takes the option already marked RECOMMENDED, stamps the artifact `(YOLO)` so an audit can tell a machine decided, and shows no prompt at all — clarify/grill answers, the verify-FAIL picker (auto-**Accept**, recorded as a yolo debt), and the final-gate picker (autofix while the budget lasts, then leave the run FAILED). A question with no recommendation is **skipped**, never invented. For throwaway/test projects nobody is watching; a real run should decide these itself. |
-| **extension whitelist** | empty | Host `pi` extensions to load into every child session by explicit path. Children otherwise run with extensions off, so a provider registered by an extension (e.g. `pi-lmstudio`) doesn't exist in them and they can't resolve the default model. `/task-config` enumerates the currently installed extensions as individual `ext: …` toggles; the list is strictly additive (discovery stays off), and an entry whose file is gone is skipped at spawn time, never fatal. |
+| **ext: …** | all off | One toggle per installed host `pi` extension, loading it into every child session by explicit path. Children otherwise run with extensions off, so a provider registered by an extension (e.g. `pi-lmstudio`) doesn't exist in them and they can't resolve the default model. Children also inherit the extension's tools and hooks, so only enable ones you trust. The list is strictly additive (discovery stays off), and an entry whose file is gone is skipped at spawn time, never fatal. |
 
 ## Configuration
 
 | Variable | Used by | Notes |
 | --- | --- | --- |
-| `BRAVE_SEARCH_API_KEY` / `BRAVE_API_KEY` | `pi-worker-search`, research enrichment | Required only when the **Brave** search provider is selected in `/task-config`. |
+| `BRAVE_SEARCH_API_KEY` / `BRAVE_API_KEY` | `pi-worker-search`, research enrichment | Required only when the **Brave** search engine is selected in `/task-config`. |
 | `XDG_CACHE_HOME` | `pi-worker-docs` | Overrides the docs cache location (defaults to `~/.cache`). |
 | `XDG_DATA_HOME` | remote push | Where the VAPID keypair is stored (defaults to `~/.local/share`). |
 | `PI_REMOTE_PUSH_SUBJECT` | remote push | VAPID JWT `sub` contact. Defaults to the project URL; set your own `mailto:you@domain.com` or `https://…`. |
@@ -202,7 +202,7 @@ Tasks are persisted to `<cwd>/.pi-tasks/TASK_NNNN.md`. Add `.pi-tasks/` to your
 
 ```sh
 bun install
-bun run test       # 1939 tests across 121 files
+bun run test       # 2078 tests across 129 files
 bun run lint       # prettier + eslint + tsc --noEmit
 bun run build      # tsc → dist/
 ```

package/dist/shared/child-output.d.ts

@@ -1,10 +1,3 @@
-/**
- * Shared utilities for parsing and formatting child pi output.
- *
- * Used by both fetch-core (web page extraction) and docs-core (npm package
- * docs extraction). The child pi outputs <answer> and <excerpt> XML tags;
- * these functions parse, verify, and format the result.
- */
 export declare function parseChildOutput(stdout: string): {
     answer: string;
     excerpt?: string;
@@ -13,6 +6,27 @@ export declare function normaliseWhitespace(s: string): string;
 /** Check whether an excerpt appears verbatim in the source content
  *  (whitespace-normalised). Returns false for empty excerpts. */
 export declare function isExcerptInContent(excerpt: string, content: string): boolean;
+/**
+ * The same verdict as {@link isExcerptInContent}, PLUS a retained record of what was
+ * actually checked — the whitespace-normalised excerpt and a hash+length of the normalised
+ * content it was searched in. This is PROMPT-3 item 4: make an `excerptVerified === false`
+ * DIAGNOSABLE after the fact, so it can be attributed to fabrication (the excerpt is nowhere
+ * near the content) versus a normaliser gap (it is a markdown-escape or entity variant of
+ * text that IS present) WITHOUT re-fetching. It deliberately does NOT loosen the verifier:
+ * `.verified` is identical to `isExcerptInContent`. F-3(f) — whether the normaliser needs
+ * markdown-escape handling — is left unproven on purpose; you decide that from the retained
+ * evidence, not by weakening the one working hallucination detector first.
+ */
+export interface ExcerptVerification {
+    verified: boolean;
+    /** sha256 of the whitespace-normalised content the excerpt was checked against. */
+    contentSha256: string;
+    /** Length of that normalised content, so a short/empty page is visible at a glance. */
+    contentLength: number;
+    /** The whitespace-normalised excerpt that was searched for. */
+    normalisedExcerpt: string;
+}
+export declare function verifyExcerpt(excerpt: string, content: string): ExcerptVerification;
 /** Format the child's parsed output with a header and optional excerpt block.
  *  When `verified === false` a warning is prepended. */
 export declare function formatResultText(header: string, parsed: {

package/dist/shared/child-output.js

@@ -5,6 +5,7 @@
  * docs extraction). The child pi outputs <answer> and <excerpt> XML tags;
  * these functions parse, verify, and format the result.
  */
+import { createHash } from 'node:crypto';
 export function parseChildOutput(stdout) {
     const trimmed = stdout.trim();
     const answerMatch = /<answer>([\s\S]*?)<\/answer>/i.exec(trimmed);
@@ -26,6 +27,16 @@ export function isExcerptInContent(excerpt, content) {
         return false;
     return normaliseWhitespace(content).includes(normaliseWhitespace(excerpt));
 }
+export function verifyExcerpt(excerpt, content) {
+    const nc = normaliseWhitespace(content);
+    const ne = normaliseWhitespace(excerpt);
+    return {
+        verified: ne.length > 0 && nc.includes(ne),
+        contentSha256: createHash('sha256').update(nc).digest('hex'),
+        contentLength: nc.length,
+        normalisedExcerpt: ne
+    };
+}
 /** Format the child's parsed output with a header and optional excerpt block.
  *  When `verified === false` a warning is prepended. */
 export function formatResultText(header, parsed, verified) {

package/dist/task/apis-contract.d.ts

@@ -0,0 +1,67 @@
+/**
+ * STAGE 2 LEVER — the APIS OUTPUT CONTRACT.
+ *
+ * ── WHAT STAGE 1 MEASURED, AND WHY THIS IS THE ONLY VARIABLE LEFT ─────────────────────────
+ *
+ * worker:apis terminates when every entry on its output list has a SIGNATURE. That is not an
+ * inference; it is what 16 live reps say (commit 807ffad, raw data ~/tmp/apis-stopping-point):
+ *   - it does not stop at a budget — docs calls/rep mean 8.5, sd 3.8, cv 0.45, range 3-14;
+ *   - it does not stop because it is circling — near-repeats 2/45 = 4.4% over the last three
+ *     calls, LOWER than the 10.2% whole-trajectory rate;
+ *   - it does not stop because nothing new is arriving — the FINAL answer of a rep still
+ *     returns 39 symbols no earlier answer in that rep carried;
+ *   - it does not stop with holes in its own output — ungrounded symbols 2/588 = 0.3%,
+ *     strict open-gap entries 2/277 = 0.7%.
+ * What it does instead: 95.3% of its lookups reach the emitted section and 72.2% of emitted
+ * entries were themselves asked about. The trajectory and the output are the SAME LIST. And
+ * the list's format is `<name>  <one-line signature or use>` — so of 61 package queries across
+ * 15 reps, 52 (85.2%) are signature questions and THREE are behaviour questions.
+ *
+ * The worker stops because the artifact it was asked for is complete by the standard its
+ * format sets, and a signature satisfies that standard. "What does this parameter MEAN" is not
+ * a field of the thing it is building, so nothing in its output is ever left unfilled by not
+ * asking it. That is why it never escalates: escalation answers a question it has no reason to
+ * ask.
+ *
+ * ── WHY THIS BLOCK AND NOT A THIRD INSTRUCTION ────────────────────────────────────────────
+ *
+ * Two levers have already failed against this seam, and they failed for the same reason:
+ *   PROMPT 2  conditioned on RECOGNISING an answer as inadequate (type-only). Reach 9/1680 =
+ *             0.54% of answers. But a type signature is not an inadequate answer to the
+ *             question actually being asked — it is exactly the requested field.
+ *   PROMPT 4  conditioned on nothing at all, and pointed the worker at the exact page that
+ *             would have prevented the fatal bug. 2/20 vs 3/20, Fisher p = 0.50, with delivery
+ *             of the block into the assembled prompt PROVEN separately. A pointer only helps a
+ *             worker that has an unmet slot to fill.
+ * Both acted on the ANSWER side or the TARGET side. This one adds a FIELD A SIGNATURE CANNOT
+ * FILL, which is the variable that is not flat.
+ *
+ * ── STEP 3 OF THE FALLBACK IS LOAD-BEARING. DO NOT "CLOSE" IT ─────────────────────────────
+ *
+ * The `UNVERIFIED:` escape is mandatory and is not a loophole. Forbidding abstention is
+ * precisely how F-1 manufactured the confident wrong claim that killed run 15: worker:context,
+ * holding one true citable fact (the pinned hono version), fused it with an uncheckable one
+ * (what `hc`'s base URL means) under a single attribution — `hc<AppType>('/api')` — and every
+ * request in the shipped product went to /api/api/… and 404'd. A lever that buys behaviour
+ * questions with fabrication is a FAIL, not a win. The A/B asserts it: excerptVerified===false
+ * and the ungrounded-symbol rate must not rise.
+ *
+ * Exported unwired first, wired into RESEARCH_APIS_PROMPT in the same series; the STEP A
+ * feasibility probe splices this exact text into a patched dist so the probe and the shipped
+ * lever can never drift apart.
+ */
+/**
+ * The extra output-contract clause for RESEARCH_APIS_PROMPT.
+ *
+ * Wording notes, because each of these is answering something measured:
+ *  - "NOT DONE WHEN THEY HAVE A SIGNATURE" is the whole lever. Stage 1's mechanism is
+ *    completion-by-format, so the change has to move the completion bar, not add advice.
+ *  - the worked example is the run-15 fatal case verbatim (`hc(baseUrl: Prefix, …)`), because
+ *    a rule without an instance of what does NOT satisfy it reads as satisfied by anything.
+ *  - step 2 says escalation is EXPECTED rather than permitted: bundled .d.ts files genuinely
+ *    do not carry semantics, and a worker that reads "you may escalate" has been told nothing
+ *    it did not already have (PROMPT 4 measured what permission alone achieves: nothing).
+ *  - step 3 is stated as CORRECT and REQUIRED, in those words, so the field cannot be closed
+ *    by guessing. See the header.
+ */
+export declare const APIS_SEMANTICS_CONTRACT = "THIRD-PARTY PACKAGE ENTRIES ARE NOT DONE WHEN THEY HAVE A SIGNATURE. For every entry whose symbol comes from a third-party npm package \u2014 not this project's own source, not a runtime builtin \u2014 the line carries a SECOND field saying what the thing MEANS in use: what one of its arguments stands for, what it defaults to, what a path/URL/prefix it is handed is relative to, or what its return value actually is. Format:\n  <name>  <one-line signature or use>  \u2014 SEMANTICS: <what it means in use>\n\nA TYPE SIGNATURE IS NOT A SEMANTICS CLAUSE, and restating one in prose does not make it one. `hc(baseUrl: Prefix, options?: ClientRequestOptions)` names the argument and says nothing about whether that argument is an origin, or a mount prefix, or how it is joined to each route path \u2014 which is the fact the implementing agent actually needs, and the one it will otherwise guess wrong. An entry whose SEMANTICS field is missing is UNFINISHED, and your section is not ready to emit while any package entry is unfinished.\n\nHOW TO FILL THAT FIELD \u2014 in this order. Do not skip a step, and do not stop after step 1 because you already hold the declaration:\n  1. ASK `pi-worker-docs` A BEHAVIOUR QUESTION about that package. NOT \"what is X's signature\", NOT \"what types does X export\" \u2014 those return the declaration you already have. Ask what an argument MEANS, what it DEFAULTS to, what it is RELATIVE to, what HAPPENS when it is given a particular value. For example: `pi-worker-docs(\"hono/client\", \"what does the baseUrl argument to hc MEAN \u2014 an origin or a mount prefix \u2014 and how is it joined to each route path?\")`.\n  2. IF THE PACKAGE TEXT DOES NOT ANSWER IT, ESCALATE. Expect this: bundled `.d.ts` declarations frequently carry no semantics at all, because the semantics live in the package's documentation. Call `pi-worker-search` with the question, or `pi-worker-fetch` on a documentation URL \u2014 including any `@see {@link https://\u2026}` link that appeared in the text `pi-worker-docs` just returned to you.\n  3. ONLY IF BOTH FAIL, WRITE THE OPEN QUESTION DOWN, in this exact form:\n       <name>  <signature>  \u2014 SEMANTICS: UNVERIFIED: <the exact question you could not answer>\n     THIS IS A CORRECT AND REQUIRED OUTCOME, not a failure. A named open question is worth far more to the implementing agent than a confident guess, and it is the only acceptable way to finish an entry you could not verify. NEVER fill this field from memory, from what the symbol is named, or from what the API \"obviously\" does: a plausible wrong semantics clause is the single most damaging thing this section can carry.";

package/dist/task/apis-contract.js

@@ -0,0 +1,77 @@
+/**
+ * STAGE 2 LEVER — the APIS OUTPUT CONTRACT.
+ *
+ * ── WHAT STAGE 1 MEASURED, AND WHY THIS IS THE ONLY VARIABLE LEFT ─────────────────────────
+ *
+ * worker:apis terminates when every entry on its output list has a SIGNATURE. That is not an
+ * inference; it is what 16 live reps say (commit 807ffad, raw data ~/tmp/apis-stopping-point):
+ *   - it does not stop at a budget — docs calls/rep mean 8.5, sd 3.8, cv 0.45, range 3-14;
+ *   - it does not stop because it is circling — near-repeats 2/45 = 4.4% over the last three
+ *     calls, LOWER than the 10.2% whole-trajectory rate;
+ *   - it does not stop because nothing new is arriving — the FINAL answer of a rep still
+ *     returns 39 symbols no earlier answer in that rep carried;
+ *   - it does not stop with holes in its own output — ungrounded symbols 2/588 = 0.3%,
+ *     strict open-gap entries 2/277 = 0.7%.
+ * What it does instead: 95.3% of its lookups reach the emitted section and 72.2% of emitted
+ * entries were themselves asked about. The trajectory and the output are the SAME LIST. And
+ * the list's format is `<name>  <one-line signature or use>` — so of 61 package queries across
+ * 15 reps, 52 (85.2%) are signature questions and THREE are behaviour questions.
+ *
+ * The worker stops because the artifact it was asked for is complete by the standard its
+ * format sets, and a signature satisfies that standard. "What does this parameter MEAN" is not
+ * a field of the thing it is building, so nothing in its output is ever left unfilled by not
+ * asking it. That is why it never escalates: escalation answers a question it has no reason to
+ * ask.
+ *
+ * ── WHY THIS BLOCK AND NOT A THIRD INSTRUCTION ────────────────────────────────────────────
+ *
+ * Two levers have already failed against this seam, and they failed for the same reason:
+ *   PROMPT 2  conditioned on RECOGNISING an answer as inadequate (type-only). Reach 9/1680 =
+ *             0.54% of answers. But a type signature is not an inadequate answer to the
+ *             question actually being asked — it is exactly the requested field.
+ *   PROMPT 4  conditioned on nothing at all, and pointed the worker at the exact page that
+ *             would have prevented the fatal bug. 2/20 vs 3/20, Fisher p = 0.50, with delivery
+ *             of the block into the assembled prompt PROVEN separately. A pointer only helps a
+ *             worker that has an unmet slot to fill.
+ * Both acted on the ANSWER side or the TARGET side. This one adds a FIELD A SIGNATURE CANNOT
+ * FILL, which is the variable that is not flat.
+ *
+ * ── STEP 3 OF THE FALLBACK IS LOAD-BEARING. DO NOT "CLOSE" IT ─────────────────────────────
+ *
+ * The `UNVERIFIED:` escape is mandatory and is not a loophole. Forbidding abstention is
+ * precisely how F-1 manufactured the confident wrong claim that killed run 15: worker:context,
+ * holding one true citable fact (the pinned hono version), fused it with an uncheckable one
+ * (what `hc`'s base URL means) under a single attribution — `hc<AppType>('/api')` — and every
+ * request in the shipped product went to /api/api/… and 404'd. A lever that buys behaviour
+ * questions with fabrication is a FAIL, not a win. The A/B asserts it: excerptVerified===false
+ * and the ungrounded-symbol rate must not rise.
+ *
+ * Exported unwired first, wired into RESEARCH_APIS_PROMPT in the same series; the STEP A
+ * feasibility probe splices this exact text into a patched dist so the probe and the shipped
+ * lever can never drift apart.
+ */
+/**
+ * The extra output-contract clause for RESEARCH_APIS_PROMPT.
+ *
+ * Wording notes, because each of these is answering something measured:
+ *  - "NOT DONE WHEN THEY HAVE A SIGNATURE" is the whole lever. Stage 1's mechanism is
+ *    completion-by-format, so the change has to move the completion bar, not add advice.
+ *  - the worked example is the run-15 fatal case verbatim (`hc(baseUrl: Prefix, …)`), because
+ *    a rule without an instance of what does NOT satisfy it reads as satisfied by anything.
+ *  - step 2 says escalation is EXPECTED rather than permitted: bundled .d.ts files genuinely
+ *    do not carry semantics, and a worker that reads "you may escalate" has been told nothing
+ *    it did not already have (PROMPT 4 measured what permission alone achieves: nothing).
+ *  - step 3 is stated as CORRECT and REQUIRED, in those words, so the field cannot be closed
+ *    by guessing. See the header.
+ */
+export const APIS_SEMANTICS_CONTRACT = `THIRD-PARTY PACKAGE ENTRIES ARE NOT DONE WHEN THEY HAVE A SIGNATURE. For every entry whose symbol comes from a third-party npm package — not this project's own source, not a runtime builtin — the line carries a SECOND field saying what the thing MEANS in use: what one of its arguments stands for, what it defaults to, what a path/URL/prefix it is handed is relative to, or what its return value actually is. Format:
+  <name>  <one-line signature or use>  — SEMANTICS: <what it means in use>
+
+A TYPE SIGNATURE IS NOT A SEMANTICS CLAUSE, and restating one in prose does not make it one. \`hc(baseUrl: Prefix, options?: ClientRequestOptions)\` names the argument and says nothing about whether that argument is an origin, or a mount prefix, or how it is joined to each route path — which is the fact the implementing agent actually needs, and the one it will otherwise guess wrong. An entry whose SEMANTICS field is missing is UNFINISHED, and your section is not ready to emit while any package entry is unfinished.
+
+HOW TO FILL THAT FIELD — in this order. Do not skip a step, and do not stop after step 1 because you already hold the declaration:
+  1. ASK \`pi-worker-docs\` A BEHAVIOUR QUESTION about that package. NOT "what is X's signature", NOT "what types does X export" — those return the declaration you already have. Ask what an argument MEANS, what it DEFAULTS to, what it is RELATIVE to, what HAPPENS when it is given a particular value. For example: \`pi-worker-docs("hono/client", "what does the baseUrl argument to hc MEAN — an origin or a mount prefix — and how is it joined to each route path?")\`.
+  2. IF THE PACKAGE TEXT DOES NOT ANSWER IT, ESCALATE. Expect this: bundled \`.d.ts\` declarations frequently carry no semantics at all, because the semantics live in the package's documentation. Call \`pi-worker-search\` with the question, or \`pi-worker-fetch\` on a documentation URL — including any \`@see {@link https://…}\` link that appeared in the text \`pi-worker-docs\` just returned to you.
+  3. ONLY IF BOTH FAIL, WRITE THE OPEN QUESTION DOWN, in this exact form:
+       <name>  <signature>  — SEMANTICS: UNVERIFIED: <the exact question you could not answer>
+     THIS IS A CORRECT AND REQUIRED OUTCOME, not a failure. A named open question is worth far more to the implementing agent than a confident guess, and it is the only acceptable way to finish an entry you could not verify. NEVER fill this field from memory, from what the symbol is named, or from what the API "obviously" does: a plausible wrong semantics clause is the single most damaging thing this section can carry.`;

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

@@ -0,0 +1,123 @@
+/**
+ * Deterministic detector for the F-1 laundering shape: a CONTEXT bullet that asserts
+ * external API USAGE SEMANTICS under an attribution cue that no EXTERNAL CONTEXT block
+ * can actually support.
+ *
+ * THE SHAPE, from mx5 run 15 (TASK_0027.md, verbatim):
+ *
+ *   - The `hono` dependency is pinned at `^4.12.31` in package.json, and the external
+ *     context confirms `hc<AppType>` pattern with base URL `/api` for same-origin
+ *     relative paths works correctly (per Hono RPC docs LIVE data).
+ *
+ * worker:context has tools `read,grep` only (phases.ts:623) — it cannot consult any
+ * documentation — so the base-URL claim was necessarily from model memory. It shipped
+ * into TASK_0027's CONSTRAINTS and ACCEPTANCE, the implementation obeyed it exactly
+ * (`hc<AppType>('/api')` plus `api.api.auth.login.$post()`), and every request went to
+ * `/api/api/...` ⇒ 404 ⇒ the product's entire API surface was dead.
+ *
+ * WHY THE OBVIOUS TEST DOES NOT WORK. "Flag a bullet whose package has no EXTERNAL
+ * CONTEXT block" misses this case: EXTERNAL CONTEXT *did* carry a `### npm: hono` block.
+ * That block contains version numbers and nothing else, so it cannot support a claim
+ * about what a base URL MEANS — yet it lends the sentence an air of having been checked.
+ * That is the whole mechanism (F-1e): one citable fact, the pinned version, fused in a
+ * single sentence with an uncitable one under a shared attribution. The true half
+ * launders the false half.
+ *
+ * So the rule keys on what a block CAN support, mirroring the LIVE-DATA RULE's own
+ * taxonomy (RESEARCH_CONTEXT_PROMPT in prompts.ts):
+ *   ### npm:      version numbers only            -> cannot source a semantics claim
+ *   ### docs:     retrieved package doc/.d.ts     -> CAN source a semantics claim
+ *   ### url:      fetched page content            -> CAN source a semantics claim
+ *   ### service:  3 search-result SNIPPETS        -> cannot source a semantics claim
+ *
+ * The `service` exclusion is not a judgement call — it is the LIVE-DATA RULE's own scope.
+ * That rule makes a service block authoritative for "current API surface, deprecation
+ * status, and replacement systems", i.e. versions/status/names. A service block is a
+ * title + URL + one-line description per result (service-blocks.ts:10); it cannot carry
+ * what a parameter MEANS. This matters concretely: TASK_0027's enrichment produced
+ * exactly one service block, `### service: Hono RPC client` (extractEnrichTargets on the
+ * verbatim refined task yields services=[Hono RPC client], urls=[], packages=[any,api,hc]).
+ * Were `service` treated as source-capable for semantics, the subject string "Hono RPC
+ * client" would match the package `hono` and the fatal bullet would pass unflagged — the
+ * detector would be unable to catch the very defect it exists for.
+ *
+ * A bullet is FLAGGED iff all three hold:
+ *   1. it carries an attribution cue ("per ... LIVE data", "the external context
+ *      confirms", "docs confirm", "per the official docs", ...);
+ *   2. it asserts API usage semantics — how something is called, what a parameter means,
+ *      what a default is, what behaviour results — as opposed to a version or a status;
+ *   3. no `### url:` or `### docs:` block exists for any package the bullet names.
+ *
+ * Pure and side-effect free; unit-tested in context-attribution.test.ts against the real
+ * run-15 bullets, including the three legitimate attributed bullets (TASK_0007, _0012,
+ * _0031) that must NOT be flagged.
+ */
+/** A block that actually appears in an EXTERNAL CONTEXT header. */
+export interface ContextBlock {
+    kind: 'npm' | 'docs' | 'url' | 'service' | 'freshness-skipped';
+    /** The block's subject: a package name, a URL, or a service name. */
+    subject: string;
+}
+export interface AttributionFinding {
+    bullet: string;
+    /** The attribution cue that made this bullet a claim of provenance. */
+    cue: string;
+    /** The semantics marker that made it an API-behaviour claim rather than a version. */
+    semantics: string;
+    /** Packages the bullet names that have no source-capable block. */
+    unsourced: string[];
+}
+/** One bullet plus the line range it occupies, so a rewrite can be surgical. */
+export interface BulletSpan {
+    /** The bullet's text, continuation lines folded in, marker stripped. */
+    text: string;
+    /** Index of the line carrying the `-`/`*` marker. */
+    startLine: number;
+    /** Index of the last line belonging to this bullet (inclusive). */
+    endLine: number;
+    /** Leading whitespace of the marker line, preserved on rewrite. */
+    indent: string;
+}
+/**
+ * Split a CONTEXT section into bullets WITH their line ranges. Continuation lines are
+ * folded into the bullet above so a hard-wrapped claim is judged as one sentence — which
+ * is exactly how the fatal run-15 bullet was written.
+ */
+export declare function splitBulletSpans(context: string): BulletSpan[];
+/** Split a CONTEXT section into its bullets, joining hard-wrapped continuation lines. */
+export declare function splitBullets(context: string): string[];
+/** Parse the `### npm:` / `### docs:` / `### url:` / `### service:` blocks out of an EXTERNAL CONTEXT header. */
+export declare function parseContextBlocks(externalContext: string): ContextBlock[];
+/**
+ * Find bullets that assert external API semantics under an attribution no available
+ * block can support.
+ *
+ * @param context          the emitted CONTEXT section text
+ * @param externalContext  the EXTERNAL CONTEXT header actually passed to that worker
+ * @param packages         dependency names to look for in a bullet (from package.json)
+ */
+export declare function findUnsourcedAttributions(context: string, externalContext: string, packages: string[]): AttributionFinding[];
+/** The result of demoting the flagged bullets out of a CONTEXT section. */
+export interface DemotedContext {
+    /** The CONTEXT text with every flagged bullet rewritten as an open question. */
+    text: string;
+    /** What was demoted, in emission order. Empty means the section was untouched. */
+    demoted: AttributionFinding[];
+}
+/**
+ * Rewrite every bullet that findUnsourcedAttributions flags into an OPEN QUESTION, in
+ * place, leaving every other byte of the section alone.
+ *
+ * DEMOTE, DO NOT DELETE. PROMPT 1 allows either, and its invariant is that neither the
+ * bullet count nor the count of legitimately-sourced bullets may collapse — "a worker
+ * silenced into saying nothing is a regression, not a fix". Demotion satisfies that
+ * mechanically: one flagged bullet becomes exactly one bullet, so the count is invariant,
+ * and the observation survives for the grill to ask about instead of reaching compose as
+ * fact. The attribution cue is removed, which is what makes the claim stop reading as
+ * sourced — and it also makes the rewrite idempotent, since the cue was condition (i).
+ *
+ * @param context          the emitted CONTEXT section text
+ * @param externalContext  the EXTERNAL CONTEXT header actually passed to that worker
+ * @param packages         dependency names to look for in a bullet (from package.json)
+ */
+export declare function demoteUnsourcedAttributions(context: string, externalContext: string, packages: string[]): DemotedContext;