@mjasnikovs/pi-task 0.18.49 → 0.18.51

package/dist/remote/register.js

@@ -67,7 +67,9 @@ export function registerRemote(pi) {
             bridge.currentCtx = makeShimmedCtx(ctx);
         }
         if (getConfig().remote) {
-            void ensureServer().catch(err => ctx.ui.notify(`Failed to start remote: ${err.message}`, 'error'));
+            // Optional feature: a bind failure must never take pi down. Degrade
+            // to a one-line warning and keep the agent running without remote.
+            void ensureServer().catch(err => ctx.ui.notify(`Remote UI unavailable: ${err.message}`, 'warning'));
         }
     });
     pi.on('session_shutdown', (event, _ctx) => {
@@ -158,7 +160,7 @@ export function registerRemote(pi) {
                 ctx.ui.notify(`Remote running at ${primaryUrl}`, 'info');
             }
             catch (err) {
-                ctx.ui.notify(`Failed to start remote: ${err.message}`, 'error');
+                ctx.ui.notify(`Remote UI unavailable: ${err.message}`, 'error');
             }
         }
     });

package/dist/remote/server.d.ts

@@ -28,5 +28,19 @@ export declare function getLocalIPs(nets?: NodeJS.Dict<import("node:os").Network
  *  Tailscale line uses the MagicDNS host when known (resolves to the same node,
  *  but is what SSH and webpush certs need), falling back to the raw IP. */
 export declare function formatAddresses(ips: LocalIPs, port: number, tsHost?: string): AddressLine[];
+/** Bind the REAL `server` to the first free port at or above `start`, trying up
+ *  to `max` consecutive ports. On EADDRINUSE we bump the port and re-listen; any
+ *  other error (e.g. EACCES), or exhausting the range, REJECTS the promise —
+ *  never throws uncaught.
+ *
+ *  Binding the real server directly (rather than probing a throwaway socket with
+ *  createServer()/listen()/close() first, then binding the real one) removes a
+ *  TOCTOU race: between "probe says port free" and "real listen", the port can be
+ *  taken by someone else, and on Windows/Bun the PROBE socket's own port isn't
+ *  fully released before the real listen runs — so the real bind hits EADDRINUSE
+ *  on the very port that just tested free, and (with no 'error' listener on the
+ *  real server) escapes as an uncaughtException that crashes pi (issue #7).
+ *  Retrying the real bind has no probe and no window. */
+export declare function listenWithRetry(server: import('node:http').Server, start: number, max: number): Promise<number>;
 export declare function startServer(onMessage: MessageCallback, getHtml: (wsUrl: string) => string, onInterrupt?: () => void): Promise<ServerHandle>;
 export {};

package/dist/remote/server.js

@@ -48,27 +48,60 @@ export function formatAddresses(ips, port, tsHost) {
         out.push({ label: '', url: `http://${ips.primary}:${port}` });
     return out;
 }
-async function tryBind(port) {
-    return new Promise(resolve => {
-        const s = createServer();
-        s.listen(port, '0.0.0.0', () => {
-            s.close(() => resolve(true));
-        });
-        s.on('error', () => resolve(false));
+/** Bind the REAL `server` to the first free port at or above `start`, trying up
+ *  to `max` consecutive ports. On EADDRINUSE we bump the port and re-listen; any
+ *  other error (e.g. EACCES), or exhausting the range, REJECTS the promise —
+ *  never throws uncaught.
+ *
+ *  Binding the real server directly (rather than probing a throwaway socket with
+ *  createServer()/listen()/close() first, then binding the real one) removes a
+ *  TOCTOU race: between "probe says port free" and "real listen", the port can be
+ *  taken by someone else, and on Windows/Bun the PROBE socket's own port isn't
+ *  fully released before the real listen runs — so the real bind hits EADDRINUSE
+ *  on the very port that just tested free, and (with no 'error' listener on the
+ *  real server) escapes as an uncaughtException that crashes pi (issue #7).
+ *  Retrying the real bind has no probe and no window. */
+export function listenWithRetry(server, start, max) {
+    return new Promise((resolve, reject) => {
+        let port = start;
+        // Persistent 'listening'/'error' listeners (not one-shot listen(cb)):
+        // under Bun, a listen(port, host, cb) callback from a FAILED first bind
+        // is NOT carried over to a later listen() retry, so it never fires — the
+        // retry silently hangs. Registering both via .on() and re-calling
+        // listen(port) with no callback routes each attempt's outcome correctly
+        // on both Bun and Node.
+        const cleanup = () => {
+            server.removeListener('error', onError);
+            server.removeListener('listening', onListening);
+        };
+        const onListening = () => {
+            cleanup();
+            resolve(port);
+        };
+        const onError = (err) => {
+            if (err.code === 'EADDRINUSE' && port < start + max - 1) {
+                port++;
+                server.listen(port, '0.0.0.0');
+                return;
+            }
+            cleanup();
+            reject(err.code === 'EADDRINUSE' ?
+                new Error(`No free port found in range ${start}–${start + max - 1}`)
+                : err);
+        };
+        server.on('error', onError);
+        server.on('listening', onListening);
+        server.listen(port, '0.0.0.0');
     });
 }
-async function findPort(start, max) {
-    for (let p = start; p < start + max; p++) {
-        if (await tryBind(p))
-            return p;
-    }
-    throw new Error(`No free port found in range ${start}–${start + max - 1}`);
-}
 export async function startServer(onMessage, getHtml, onInterrupt) {
-    const port = await findPort(8800, 100);
     const ips = getLocalIPs();
     const ip = ips.primary;
-    const wsUrl = `ws://${ip}:${port}/ws`;
+    // The bound port isn't known until listenWithRetry succeeds, and wsUrl
+    // depends on it. The request handler only ever runs once the server is
+    // listening (real client I/O, long after we set wsUrl below), so reading it
+    // lazily from this closure variable is safe.
+    let wsUrl = '';
     const httpServer = createServer((req, res) => {
         if (req.method === 'GET' && (req.url === '/' || req.url === '')) {
             const body = getHtml(wsUrl);
@@ -108,7 +141,6 @@ export async function startServer(onMessage, getHtml, onInterrupt) {
             res.end('Not found');
         }
     });
-    const wss = new WebSocketServer({ server: httpServer, path: '/ws' });
     // Track every accepted TCP socket so stop() can forcibly destroy lingering
     // keep-alive / WebSocket connections. Without this, httpServer.close() only
     // stops accepting new connections and waits for existing ones to drain — an
@@ -124,6 +156,18 @@ export async function startServer(onMessage, getHtml, onInterrupt) {
         sockets.add(s);
         s.on('close', () => sockets.delete(s));
     });
+    // Bind the real server now, retrying past any in-use ports. A bind failure
+    // REJECTS (see listenWithRetry) — register.ts's callers catch it and let pi
+    // continue without the remote UI; the remote server is optional.
+    const port = await listenWithRetry(httpServer, 8800, 100);
+    wsUrl = `ws://${ip}:${port}/ws`;
+    // Attach the WebSocket server only AFTER the http server is bound. ws adds an
+    // 'error' listener to the http server that re-emits on the WebSocketServer
+    // (which has no error listener) — so if it were attached during the bind, an
+    // EADDRINUSE on the first port would be forwarded to wss and thrown as an
+    // uncaughtException, crashing pi even though listenWithRetry handled it. ws
+    // works fine on an already-listening server.
+    const wss = new WebSocketServer({ server: httpServer, path: '/ws' });
     const handle = {
         port,
         ip,
@@ -177,6 +221,5 @@ export async function startServer(onMessage, getHtml, onInterrupt) {
             removeClient(ws);
         });
     });
-    await new Promise(resolve => httpServer.listen(port, '0.0.0.0', resolve));
     return handle;
 }

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;