@mjasnikovs/pi-task 0.14.10 → 0.14.12

package/dist/remote/bridge.d.ts

@@ -20,6 +20,9 @@ export declare function answerPrompt(id: string, value: string | undefined): voi
 export interface AskSpec {
     /** Themed, possibly multi-line title for the local TUI input. */
     localTitle: string;
+    /** Themed (markdown-rendered) question shown as the boxed picker header.
+     *  Falls back to `question` when absent. */
+    displayQuestion?: string;
     /** Plain question text for the browser card. */
     question: string;
     /** Primary recommended option, prefilled in the local TUI. */
@@ -52,12 +55,12 @@ export declare class SessionUI {
     /** Race the local input against a remote answer; first to settle wins. */
     ask(spec: AskSpec): Promise<string | undefined>;
     /**
-     * The local-TUI half of ask(). With `spec.options` it renders a select()
-     * picker (each option on its own line) plus a trailing "type a different
-     * answer" entry that drops to a text input; the chosen entry's `value` is
-     * returned. Without options it falls back to a single text input. Cancelling
-     * either dialog (or an abort when the remote wins the race) resolves to
-     * undefined.
+     * The local-TUI half of ask(). With `spec.options` it renders the boxed
+     * picker (each answer in its own bounding box, the first/recommended one
+     * tinted green) plus a trailing "type a different answer" entry that drops to
+     * a text input; the chosen entry's `value` is returned. Without options it
+     * falls back to a single text input. Cancelling either dialog (or an abort
+     * when the remote wins the race) resolves to undefined.
      */
     private askLocal;
 }

package/dist/remote/bridge.js

@@ -1,6 +1,7 @@
 import { broadcast as wsBroadcast } from './broadcast.js';
 import { pushNotify } from './push.js';
 import { setPrompt, clearPrompt } from './session-state.js';
+import { askQuestionBox } from '../task/question-box.js';
 const g = globalThis;
 export function getBridge() {
     if (!g.__piBridge) {
@@ -25,9 +26,6 @@ export function answerPrompt(id, value) {
     b.pending.delete(id);
     settle(value);
 }
-/** Trailing picker entry that drops to a free-text input — the local mirror of
- *  the remote card's "✎ Manual answer" button. */
-const TYPE_OWN_LABEL = 'Type a different answer…';
 /** Wraps a live command ctx and fans interactions out to local TUI + browsers. */
 export class SessionUI {
     ctx;
@@ -83,27 +81,26 @@ export class SessionUI {
         }
     }
     /**
-     * The local-TUI half of ask(). With `spec.options` it renders a select()
-     * picker (each option on its own line) plus a trailing "type a different
-     * answer" entry that drops to a text input; the chosen entry's `value` is
-     * returned. Without options it falls back to a single text input. Cancelling
-     * either dialog (or an abort when the remote wins the race) resolves to
-     * undefined.
+     * The local-TUI half of ask(). With `spec.options` it renders the boxed
+     * picker (each answer in its own bounding box, the first/recommended one
+     * tinted green) plus a trailing "type a different answer" entry that drops to
+     * a text input; the chosen entry's `value` is returned. Without options it
+     * falls back to a single text input. Cancelling either dialog (or an abort
+     * when the remote wins the race) resolves to undefined.
      */
     async askLocal(spec, signal) {
         const opts = spec.options;
         if (opts && opts.length > 0) {
-            const labels = opts.map(o => o.label);
-            const choice = await this.ctx.ui.select(spec.localTitle, [...labels, TYPE_OWN_LABEL], {
+            return askQuestionBox(this.ctx, {
+                question: spec.displayQuestion ?? spec.question,
+                inputTitle: spec.localTitle,
+                options: opts.map((o, i) => ({
+                    label: o.label,
+                    value: o.value,
+                    recommended: i === 0
+                })),
                 signal
             });
-            if (choice === undefined)
-                return undefined; // cancelled / aborted
-            if (choice === TYPE_OWN_LABEL) {
-                return this.ctx.ui.input(spec.localTitle, undefined, { signal });
-            }
-            const hit = opts.find(o => o.label === choice);
-            return hit ? hit.value : choice;
         }
         return this.ctx.ui.input(spec.localTitle, spec.recommended, { signal });
     }

package/dist/task/auto-orchestrator.js

@@ -246,30 +246,30 @@ export async function planAuto(ctx, cwd, feature, deps) {
         askedQuestions.push(plainQ);
         const plainSuggested = suggested === undefined ? undefined : stripInlineMarkdown(suggested);
         const plainAlt = alt === undefined ? undefined : stripInlineMarkdown(alt);
-        // Identical to /task's grill dialog: a binary fork becomes a select()
-        // picker locally — each option on its own line, labelled A/B; a single
-        // recommendation rides under the question as the input default; an open
-        // question shows the bare prompt. No verbose "Recommended:" /
-        // "press Enter to accept" scaffolding.
+        // Identical to /task's grill dialog: a recommendation (or A/B fork)
+        // becomes the boxed picker locally — each answer in its own bounding box,
+        // the recommended one tinted green; an open question shows the bare text
+        // prompt. No verbose "Recommended:" / "press Enter to accept" scaffolding.
         const twoOption = plainSuggested !== undefined && plainAlt !== undefined;
-        const title = !twoOption && plainSuggested ?
-            `${shownQ}\n${renderInlineMarkdown(suggested, theme)}`
-            : shownQ;
+        const options = twoOption ?
+            [
+                {
+                    label: `A: ${renderInlineMarkdown(suggested, theme)}`,
+                    value: plainSuggested
+                },
+                { label: `B: ${renderInlineMarkdown(alt, theme)}`, value: plainAlt }
+            ]
+            : plainSuggested !== undefined ?
+                [{ label: renderInlineMarkdown(suggested, theme), value: plainSuggested }]
+                : undefined;
         const a = await ui.ask({
-            localTitle: title,
+            localTitle: shownQ,
+            displayQuestion: shownQ,
             question: plainQ,
             recommended: plainSuggested,
             ...(plainAlt !== undefined && { recommended2: plainAlt }),
             allowSkip: plainSuggested === undefined && plainAlt === undefined,
-            ...(twoOption && {
-                options: [
-                    {
-                        label: `A: ${renderInlineMarkdown(suggested, theme)}`,
-                        value: plainSuggested
-                    },
-                    { label: `B: ${renderInlineMarkdown(alt, theme)}`, value: plainAlt }
-                ]
-            })
+            ...(options && { options })
         });
         if (a === undefined) {
             announceDone(ctx, '/task-auto cancelled.', 'warning');
@@ -292,6 +292,11 @@ export async function planAuto(ctx, cwd, feature, deps) {
         else if (twoOption && /^b[.)]?$/i.test(typed)) {
             answer = plainAlt;
         }
+        else if (!twoOption && plainSuggested !== undefined && typed === plainSuggested) {
+            // Single recommendation accepted by picking its (green) card in the
+            // boxed picker — same provenance as an empty-submit accept.
+            answer = `${plainSuggested} (accepted recommendation)`;
+        }
         else {
             answer = typed;
         }

package/dist/task/orchestrator.d.ts

@@ -57,6 +57,16 @@ export declare class TaskRunner {
      *  finally block's call. */
     private _disposeWidget;
     private _deliverSpec;
+    /**
+     * The spec as the implementer should receive it (Layer B). Layer A strips phantom
+     * specifiers from the upstream pipeline text, but a residual affirmative can survive
+     * into the composed spec, or arrive when pi expands an `@design.md` the spec
+     * references — and the implementer is told that doc is authoritative. Prepend a
+     * VERIFIED API OVERRIDES banner that outranks the spec for any specifier the
+     * deterministic check proves does not exist. No-op (returns the spec unchanged) when
+     * nothing is flagged or the runtime's types aren't installed.
+     */
+    private _specForDelivery;
 }
 export interface RunSingleTaskOptions {
     /** Await the session going idle after the spec is delivered, so the caller

package/dist/task/orchestrator.js

@@ -26,6 +26,7 @@ import { startWidget } from './widget.js';
 import { publishViewer, publishNotify, registerBridgeCommand, getBridge } from '../remote/bridge.js';
 import { pushNotify } from '../remote/push.js';
 import { parseVerifyBlock } from './spec-validation.js';
+import { findDeliveryPhantoms, formatApiOverrideBanner } from '../workers/phantom-imports.js';
 import { titleForDisplay } from './parsers.js';
 import { formatTimings } from './timings.js';
 import { getParentContextWindow, resolveContextUsage } from './context-usage.js';
@@ -261,20 +262,38 @@ export class TaskRunner {
         this._stopWidget = null;
     }
     async _deliverSpec(ctx) {
+        const spec = this._specForDelivery();
         if (this._sendSpec) {
-            await this._sendSpec(this._pc.spec);
+            await this._sendSpec(spec);
             return;
         }
         if (!piApi) {
             throw new Error('extension not initialised (no ExtensionAPI captured)');
         }
         if (ctx.isIdle()) {
-            piApi.sendUserMessage(this._pc.spec);
+            piApi.sendUserMessage(spec);
         }
         else {
-            piApi.sendUserMessage(this._pc.spec, { deliverAs: 'followUp' });
+            piApi.sendUserMessage(spec, { deliverAs: 'followUp' });
         }
     }
+    /**
+     * The spec as the implementer should receive it (Layer B). Layer A strips phantom
+     * specifiers from the upstream pipeline text, but a residual affirmative can survive
+     * into the composed spec, or arrive when pi expands an `@design.md` the spec
+     * references — and the implementer is told that doc is authoritative. Prepend a
+     * VERIFIED API OVERRIDES banner that outranks the spec for any specifier the
+     * deterministic check proves does not exist. No-op (returns the spec unchanged) when
+     * nothing is flagged or the runtime's types aren't installed.
+     */
+    _specForDelivery() {
+        const phantoms = findDeliveryPhantoms(this._pc.spec, this._cwd);
+        const banner = formatApiOverrideBanner(phantoms);
+        if (!banner)
+            return this._pc.spec;
+        this._deps.logDebug?.(`impl-handoff API override banner prepended for: ${phantoms.map(p => p.spec).join(', ')}`);
+        return `${banner}\n\n${this._pc.spec}`;
+    }
 }
 /** Dialog copy for the post-interrupt steering prompt. */
 const STEER_TITLE = 'Paused — steer the model';

package/dist/task/phases.js

@@ -517,30 +517,30 @@ export async function phaseGrill(deps, ctx, widgetState, refined, research) {
         else {
             const plainSuggested = auto.suggested === undefined ? undefined : stripInlineMarkdown(auto.suggested);
             const plainAlt = auto.alt === undefined ? undefined : stripInlineMarkdown(auto.alt);
-            // A binary fork (suggested + alt) becomes a select() picker locally —
-            // each option on its own line, labelled A/B. A single recommendation
-            // rides along under the question as the input default; an open
-            // question shows the bare prompt.
+            // A recommendation (or suggested+alt fork) becomes the boxed picker
+            // locally — each answer in its own bounding box, the recommended one
+            // tinted green; an open question shows the bare text prompt.
             const twoOption = plainSuggested !== undefined && plainAlt !== undefined;
-            const localTitle = !twoOption && plainSuggested ?
-                `${shownQ}\n${renderInlineMarkdown(auto.suggested, theme)}`
-                : shownQ;
+            const options = twoOption ?
+                [
+                    {
+                        label: `A: ${renderInlineMarkdown(auto.suggested, theme)}`,
+                        value: plainSuggested
+                    },
+                    { label: `B: ${renderInlineMarkdown(auto.alt, theme)}`, value: plainAlt }
+                ]
+                : plainSuggested !== undefined ?
+                    [{ label: renderInlineMarkdown(auto.suggested, theme), value: plainSuggested }]
+                    : undefined;
             widgetState.lastLine = `awaiting Q${n + 1}`;
             const a = await ui.ask({
-                localTitle,
+                localTitle: shownQ,
+                displayQuestion: shownQ,
                 question: plainQ,
                 recommended: plainSuggested,
                 recommended2: plainAlt,
                 allowSkip: plainSuggested === undefined && plainAlt === undefined,
-                ...(twoOption && {
-                    options: [
-                        {
-                            label: `A: ${renderInlineMarkdown(auto.suggested, theme)}`,
-                            value: plainSuggested
-                        },
-                        { label: `B: ${renderInlineMarkdown(auto.alt, theme)}`, value: plainAlt }
-                    ]
-                })
+                ...(options && { options })
             });
             if (a === undefined)
                 throw new Error(USER_CANCELLED);

package/dist/task/question-box.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Boxed question dialog for the clarify / grill phases.
+ *
+ * The built-in `ctx.ui.select` renders every option as a bare line under one
+ * outer frame — the question, the recommendation, and the choices all read as a
+ * single blob. The remote (browser) prompt card instead gives each response its
+ * own bounded panel, tints the recommended one green, and separates everything
+ * with margins. This module mirrors that remote style in the terminal: a custom
+ * `ctx.ui.custom` component that draws each answer in its own bounding box with a
+ * green RECOMMENDED tag, an accent-highlighted cursor box, and clear vertical
+ * spacing.
+ *
+ * `renderQuestionBox` is the pure layout — width in, lines out — so the visual
+ * structure (borders, tag, cursor arrow, padding) is unit-testable without a
+ * live TUI. The component and `askQuestionBox` wire it to keyboard input and the
+ * "type a different answer" free-text fallback.
+ */
+import type { Component } from '@earendil-works/pi-tui';
+import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+/** One answer card. `label` may carry ANSI (rendered markdown); width math is
+ *  ANSI-aware so the box borders still line up. */
+export interface BoxCard {
+    label: string;
+    /** Recommended answer → green chrome + RECOMMENDED tag. */
+    recommended?: boolean;
+}
+/** Chrome colourers, injected so tests can pass identity fns and assert on the
+ *  plain box structure. A real theme is adapted by {@link boxColors}. */
+export interface BoxColors {
+    border: (s: string) => string;
+    borderRecommended: (s: string) => string;
+    borderSelected: (s: string) => string;
+    recommendedTag: (s: string) => string;
+    questionLabel: (s: string) => string;
+    hint: (s: string) => string;
+    arrow: (s: string) => string;
+}
+type ThemeLike = ExtensionCommandContext['ui']['theme'];
+export declare const QUESTION_LABEL = "QUESTION";
+export declare const HINT_TEXT = "\u2191\u2193 navigate \u00B7 enter select \u00B7 esc cancel";
+export declare const MANUAL_CARD_LABEL = "\u270E Type a different answer\u2026";
+/**
+ * Lay the whole dialog out for `width` columns: a QUESTION label + wrapped
+ * question, one bounding box per card (recommended tinted green, the cursor box
+ * highlighted with an accent border and "▸" arrow), and a key-hint footer.
+ */
+export declare function renderQuestionBox(width: number, question: string, cards: BoxCard[], selected: number, c: BoxColors, hintText?: string): string[];
+export declare function boxColors(theme: ThemeLike): BoxColors;
+/** Focusable picker component; navigation mirrors the built-in select dialog. */
+export declare class QuestionBoxComponent implements Component {
+    private readonly question;
+    private readonly cards;
+    private readonly colors;
+    private readonly onChoose;
+    private readonly onCancel;
+    private selected;
+    /** Card labels in display order (recommended first, manual last). Read-only
+     *  view for tests that drive the picker without parsing rendered output. */
+    get cardLabels(): string[];
+    /** The question header text. Read-only view for tests. */
+    get headerText(): string;
+    constructor(question: string, cards: BoxCard[], colors: BoxColors, onChoose: (index: number) => void, onCancel: () => void);
+    render(width: number): string[];
+    invalidate(): void;
+    handleInput(data: string): void;
+}
+export interface BoxOption {
+    label: string;
+    value: string;
+    recommended?: boolean;
+}
+export interface AskQuestionBoxSpec {
+    /** Display question for the box header (may carry ANSI). */
+    question: string;
+    /** Plain title for the free-text fallback input dialog. */
+    inputTitle: string;
+    options: BoxOption[];
+    signal: AbortSignal;
+}
+/**
+ * Show the boxed picker and resolve to the chosen option's `value`, the text the
+ * user typed via "type a different answer", or undefined when cancelled/aborted.
+ */
+export declare function askQuestionBox(ctx: ExtensionCommandContext, spec: AskQuestionBoxSpec): Promise<string | undefined>;
+export {};

package/dist/task/question-box.js

@@ -0,0 +1,166 @@
+/**
+ * Boxed question dialog for the clarify / grill phases.
+ *
+ * The built-in `ctx.ui.select` renders every option as a bare line under one
+ * outer frame — the question, the recommendation, and the choices all read as a
+ * single blob. The remote (browser) prompt card instead gives each response its
+ * own bounded panel, tints the recommended one green, and separates everything
+ * with margins. This module mirrors that remote style in the terminal: a custom
+ * `ctx.ui.custom` component that draws each answer in its own bounding box with a
+ * green RECOMMENDED tag, an accent-highlighted cursor box, and clear vertical
+ * spacing.
+ *
+ * `renderQuestionBox` is the pure layout — width in, lines out — so the visual
+ * structure (borders, tag, cursor arrow, padding) is unit-testable without a
+ * live TUI. The component and `askQuestionBox` wire it to keyboard input and the
+ * "type a different answer" free-text fallback.
+ */
+import { getKeybindings, visibleWidth, wrapTextWithAnsi } from '@earendil-works/pi-tui';
+// ─── Constants ───────────────────────────────────────────────────────────────
+/** Left gutter: two columns reserved for the "▸ " cursor so boxes stay aligned. */
+const GUTTER = 2;
+const RECOMMENDED_TAG = 'RECOMMENDED';
+/** Smallest box that still fits "┌─ RECOMMENDED ─┐". Below this we drop the tag. */
+const TAG_MIN_BOX_WIDTH = visibleWidth(`┌─ ${RECOMMENDED_TAG} ─┐`);
+export const QUESTION_LABEL = 'QUESTION';
+export const HINT_TEXT = '↑↓ navigate · enter select · esc cancel';
+export const MANUAL_CARD_LABEL = '✎ Type a different answer…';
+// ─── Pure renderer ─────────────────────────────────────────────────────────────
+function padTo(line, width) {
+    const pad = width - visibleWidth(line);
+    return pad > 0 ? line + ' '.repeat(pad) : line;
+}
+function renderCard(card, selected, boxWidth, c) {
+    const borderFn = selected ? c.borderSelected
+        : card.recommended ? c.borderRecommended
+            : c.border;
+    const innerWidth = Math.max(1, boxWidth - 4); // "│ " + content + " │"
+    const dash = (n) => '─'.repeat(Math.max(0, n));
+    // Top border, with a RECOMMENDED tag woven in when it fits.
+    let top;
+    if (card.recommended && boxWidth >= TAG_MIN_BOX_WIDTH) {
+        // TAG_MIN_BOX_WIDTH is the width at one trailing dash, so add it back.
+        const dashes = boxWidth - TAG_MIN_BOX_WIDTH + 1;
+        top = borderFn('┌─ ') + c.recommendedTag(RECOMMENDED_TAG) + borderFn(` ${dash(dashes)}┐`);
+    }
+    else {
+        top = borderFn(`┌${dash(boxWidth - 2)}┐`);
+    }
+    const bodyLines = wrapTextWithAnsi(card.label, innerWidth);
+    const body = (bodyLines.length > 0 ? bodyLines : ['']).map(line => borderFn('│ ') + padTo(line, innerWidth) + borderFn(' │'));
+    const bottom = borderFn(`└${dash(boxWidth - 2)}┘`);
+    const arrow = selected ? c.arrow('▸') + ' ' : '  ';
+    const pad = '  ';
+    return [arrow + top, ...body.map(b => pad + b), pad + bottom];
+}
+/**
+ * Lay the whole dialog out for `width` columns: a QUESTION label + wrapped
+ * question, one bounding box per card (recommended tinted green, the cursor box
+ * highlighted with an accent border and "▸" arrow), and a key-hint footer.
+ */
+export function renderQuestionBox(width, question, cards, selected, c, hintText = HINT_TEXT) {
+    const W = Math.max(width, 12);
+    const boxWidth = Math.max(6, W - GUTTER);
+    const out = [''];
+    out.push('  ' + c.questionLabel(QUESTION_LABEL));
+    for (const line of wrapTextWithAnsi(question, W - GUTTER))
+        out.push('  ' + line);
+    out.push('');
+    for (let i = 0; i < cards.length; i++) {
+        out.push(...renderCard(cards[i], i === selected, boxWidth, c));
+        out.push('');
+    }
+    for (const line of wrapTextWithAnsi(hintText, W - GUTTER))
+        out.push('  ' + c.hint(line));
+    out.push('');
+    return out;
+}
+// ─── Theme adapter ─────────────────────────────────────────────────────────────
+export function boxColors(theme) {
+    return {
+        border: s => theme.fg('borderMuted', s),
+        borderRecommended: s => theme.fg('success', s),
+        borderSelected: s => theme.fg('accent', s),
+        recommendedTag: s => theme.fg('success', theme.bold(s)),
+        questionLabel: s => theme.fg('accent', theme.bold(s)),
+        hint: s => theme.fg('muted', s),
+        arrow: s => theme.fg('accent', theme.bold(s))
+    };
+}
+// ─── Component ─────────────────────────────────────────────────────────────────
+/** Focusable picker component; navigation mirrors the built-in select dialog. */
+export class QuestionBoxComponent {
+    question;
+    cards;
+    colors;
+    onChoose;
+    onCancel;
+    selected = 0;
+    /** Card labels in display order (recommended first, manual last). Read-only
+     *  view for tests that drive the picker without parsing rendered output. */
+    get cardLabels() {
+        return this.cards.map(c => c.label);
+    }
+    /** The question header text. Read-only view for tests. */
+    get headerText() {
+        return this.question;
+    }
+    constructor(question, cards, colors, onChoose, onCancel) {
+        this.question = question;
+        this.cards = cards;
+        this.colors = colors;
+        this.onChoose = onChoose;
+        this.onCancel = onCancel;
+    }
+    render(width) {
+        return renderQuestionBox(width, this.question, this.cards, this.selected, this.colors);
+    }
+    invalidate() { }
+    handleInput(data) {
+        const kb = getKeybindings();
+        if (kb.matches(data, 'tui.select.up') || data === 'k') {
+            this.selected = Math.max(0, this.selected - 1);
+        }
+        else if (kb.matches(data, 'tui.select.down') || data === 'j') {
+            this.selected = Math.min(this.cards.length - 1, this.selected + 1);
+        }
+        else if (kb.matches(data, 'tui.select.confirm') || data === '\n' || data === '\r') {
+            this.onChoose(this.selected);
+        }
+        else if (kb.matches(data, 'tui.select.cancel')) {
+            this.onCancel();
+        }
+    }
+}
+/**
+ * Show the boxed picker and resolve to the chosen option's `value`, the text the
+ * user typed via "type a different answer", or undefined when cancelled/aborted.
+ */
+export async function askQuestionBox(ctx, spec) {
+    const { question, options, inputTitle, signal } = spec;
+    const cards = [
+        ...options.map(o => ({ label: o.label, recommended: o.recommended })),
+        { label: MANUAL_CARD_LABEL }
+    ];
+    const colors = boxColors(ctx.ui.theme);
+    const manualIndex = options.length;
+    const choice = await ctx.ui.custom((_tui, _theme, _kb, done) => {
+        if (signal.aborted) {
+            done(undefined);
+            return new QuestionBoxComponent(question, cards, colors, () => { }, () => { });
+        }
+        const onAbort = () => done(undefined);
+        signal.addEventListener('abort', onAbort, { once: true });
+        const finish = (result) => {
+            signal.removeEventListener('abort', onAbort);
+            done(result);
+        };
+        return new QuestionBoxComponent(question, cards, colors, index => finish(index), () => finish(undefined));
+    });
+    if (choice === undefined)
+        return undefined;
+    if (choice === manualIndex) {
+        return ctx.ui.input(inputTitle, undefined, { signal });
+    }
+    return options[choice]?.value;
+}

package/dist/workers/phantom-imports.d.ts

@@ -36,6 +36,25 @@ export declare function loadRuntimeTypeText(runtime: string, cwd: string): strin
 export declare function findPhantomImports(text: string, cwd: string, loadText?: (runtime: string, cwd: string) => string | null): PhantomImport[];
 /** Render flagged phantoms as an authoritative research section, or '' if none. */
 export declare function formatApiCorrections(phantoms: PhantomImport[]): string;
+/**
+ * A top-of-handoff override banner (Layer B). The deterministic check has proven —
+ * against the installed type definitions — that the spec, or a design doc it
+ * references, names an API that does NOT exist. The implementer is told the spec/doc
+ * is authoritative, so a residual affirmative that survived into the composed spec, or
+ * one re-injected when pi expands an `@design.md` the spec references, can still push it
+ * to write `bun:sql` / a `declare module` shim. This banner sits ABOVE the spec and is
+ * declared to outrank it for these specifiers only. Empty when nothing is flagged.
+ */
+export declare function formatApiOverrideBanner(phantoms: PhantomImport[]): string;
+/**
+ * The phantoms the IMPLEMENTER would actually encounter: those named in the delivered
+ * spec text itself, PLUS those in any @-file the spec references (pi expands that
+ * mention at send time, re-injecting the doc's affirmative). Concatenates the spec with
+ * each readable referenced doc and runs the standard deterministic check over the whole.
+ * Unreadable mentions are skipped; silent when types are absent or nothing is flagged.
+ * Drives the impl-handoff override banner (Layer B).
+ */
+export declare function findDeliveryPhantoms(spec: string, cwd: string): PhantomImport[];
 /**
  * Subtractively rewrite every flagged phantom specifier in `text` to the canonical
  * import the installed types prove, so NO affirmative occurrence of the non-existent

package/dist/workers/phantom-imports.js

@@ -186,6 +186,56 @@ export function formatApiCorrections(phantoms) {
     const lines = phantoms.map(p => `  - ${p.suggestion}`);
     return `API CORRECTIONS\n${lines.join('\n')}`;
 }
+/**
+ * A top-of-handoff override banner (Layer B). The deterministic check has proven —
+ * against the installed type definitions — that the spec, or a design doc it
+ * references, names an API that does NOT exist. The implementer is told the spec/doc
+ * is authoritative, so a residual affirmative that survived into the composed spec, or
+ * one re-injected when pi expands an `@design.md` the spec references, can still push it
+ * to write `bun:sql` / a `declare module` shim. This banner sits ABOVE the spec and is
+ * declared to outrank it for these specifiers only. Empty when nothing is flagged.
+ */
+export function formatApiOverrideBanner(phantoms) {
+    if (phantoms.length === 0)
+        return '';
+    const lines = phantoms.map(p => `  - ${p.suggestion}`);
+    return ('VERIFIED API OVERRIDES — checked against the installed type definitions. These '
+        + 'SUPERSEDE the spec below and any design/spec document it references: the doc is '
+        + 'WRONG about these specifiers, so do NOT follow it here.\n'
+        + lines.join('\n')
+        + '\nUse the corrected import shown for each. Never write the phantom specifier, '
+        + 'and never add a `declare module` shim to make it resolve.');
+}
+// An @-file mention in a spec ("@DESIGN/foo.md", path until whitespace) minus the
+// trailing prose punctuation a sentence adds. Mirrors auto-orchestrator's mention
+// rules so we read the same docs pi re-expands when delivering the spec.
+const MENTION_RE = /(?:^|\s)@([^\s]+)/g;
+const MENTION_TRAILING_PUNCT = /[.,;:!?)\]}>"']+$/;
+/**
+ * The phantoms the IMPLEMENTER would actually encounter: those named in the delivered
+ * spec text itself, PLUS those in any @-file the spec references (pi expands that
+ * mention at send time, re-injecting the doc's affirmative). Concatenates the spec with
+ * each readable referenced doc and runs the standard deterministic check over the whole.
+ * Unreadable mentions are skipped; silent when types are absent or nothing is flagged.
+ * Drives the impl-handoff override banner (Layer B).
+ */
+export function findDeliveryPhantoms(spec, cwd) {
+    let text = spec;
+    const seen = new Set();
+    for (const m of spec.matchAll(MENTION_RE)) {
+        const rel = m[1].replace(MENTION_TRAILING_PUNCT, '');
+        if (rel === '' || seen.has(rel))
+            continue;
+        seen.add(rel);
+        try {
+            text += '\n' + fs.readFileSync(path.resolve(cwd, rel), 'utf8');
+        }
+        catch {
+            // not a readable file — leave the @token, skip it
+        }
+    }
+    return findPhantomImports(text, cwd);
+}
 /**
  * Subtractively rewrite every flagged phantom specifier in `text` to the canonical
  * import the installed types prove, so NO affirmative occurrence of the non-existent

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mjasnikovs/pi-task",
-    "version": "0.14.10",
+    "version": "0.14.12",
     "description": "Deterministic spec-orchestration for local models, with a bundled real-time remote web view and web/docs/fetch/worker subagent tools.",
     "type": "module",
     "main": "./dist/index.js",