@code-yeongyu/senpi 2026.11.2-3 → 2026.11.3-2

package/dist/core/extensions/builtin/todotools/normalize.js

@@ -1,3 +1,4 @@
+import { DEFAULT_INIT_PHASE } from "./todo-types.js";
 const CONFLICTING_SHAPES = 'conflicting shapes. Use {"op":"init","list":[...]} to replace the list or {"op":"append","phase":"<active phase>","items":[...]} to add tasks.';
 function isRecord(value) {
     return typeof value === "object" && value !== null;
@@ -66,12 +67,257 @@ function unwrapTodoList(value) {
     }
     return Array.isArray(current) && current.length > 0 ? current : value;
 }
-/** The todo tool's `prepareArguments`: returns the arguments with `list` unwrapped to its canonical shape. */
-export function prepareTodoArguments(args) {
-    if (!isRecord(args) || Array.isArray(args) || !("list" in args))
+/**
+ * Reserved string key under which `prepareTodoArguments` carries its correction notices to
+ * `execute`. `validateToolArguments` clones prepared arguments with `structuredClone`, which
+ * drops symbol keys, so the channel must be a string key; `execute` strips it before
+ * `normalizeTodoParams` and prepends the notices. The key is never persisted or rendered,
+ * but prepared arguments flow to the agent loop's `beforeToolCall`/`afterToolCall` hooks, so
+ * extension `tool_call`/`tool_result` hooks may observe it on the arguments they receive.
+ */
+const TODO_PREPARED_CORRECTIONS_KEY = "__todoPreparedCorrections";
+function isPhaseRecord(value) {
+    return isRecord(value) && typeof value.phase === "string" && Array.isArray(value.items);
+}
+function isContentRecord(value) {
+    return isRecord(value) && typeof value.content === "string";
+}
+function quoted(values) {
+    return values.map((value) => JSON.stringify(value)).join(", ");
+}
+/**
+ * Rewrites near-canonical `list` entries (senpi#5332) to the canonical shape: an entry whose
+ * `items` are all nested `{phase, items}` records is replaced by them, `items` entries that
+ * are records carrying a string `content` become that string, entries with missing or empty
+ * `items` and stray string entries are dropped, and entries with tasks but no usable `phase`
+ * name get sequential default names. An `items` array that mixes strings with phase records
+ * is ambiguous and returns `null`, as does nothing else here: the caller then leaves the
+ * whole call untouched so validation rejects it as before. The input array and its entries
+ * are never mutated; when nothing changes, the same array reference is returned.
+ */
+function normalizeTodoListEntries(input, notices) {
+    let list = [...input];
+    let changed = false;
+    const promotedOuter = [];
+    for (let depth = 0; depth < 5; depth++) {
+        const next = [];
+        let promotedThisPass = false;
+        for (const entry of list) {
+            if (isPhaseRecord(entry) && entry.items.length > 0 && entry.items.every(isPhaseRecord)) {
+                next.push(...entry.items);
+                promotedOuter.push(entry.phase);
+                promotedThisPass = true;
+            }
+            else {
+                next.push(entry);
+            }
+        }
+        if (!promotedThisPass)
+            break;
+        list = next;
+    }
+    if (promotedOuter.length > 0) {
+        changed = true;
+        notices.push(`[auto-corrected] "list" ${promotedOuter.length === 1 ? "entry" : "entries"} ${quoted(promotedOuter)} contained only nested phases; promoted the nested phases to top level. Each "list" entry is exactly one phase: {"phase":"<name>","items":["<task>", ...]}`);
+    }
+    let unwrappedContent = 0;
+    for (let index = 0; index < list.length; index++) {
+        const entry = list[index];
+        if (!isPhaseRecord(entry))
+            continue;
+        const mapped = entry.items.map((item) => {
+            if (isContentRecord(item) && !isPhaseRecord(item)) {
+                unwrappedContent += 1;
+                return item.content;
+            }
+            return item;
+        });
+        // Strings and nested phase records in one items array cannot be told apart, so no
+        // correction may guess: leave the whole call to validation.
+        if (mapped.some((item) => typeof item === "string") && mapped.some(isPhaseRecord))
+            return null;
+        if (!mapped.every((item) => typeof item === "string"))
+            continue;
+        if (mapped.some((item, position) => item !== entry.items[position])) {
+            list[index] = { ...entry, items: mapped };
+            changed = true;
+        }
+    }
+    if (unwrappedContent > 0) {
+        notices.push(`[auto-corrected] unwrapped ${unwrappedContent} "items" ${unwrappedContent === 1 ? "entry" : "entries"} carrying a "content" field into their task strings. "items" holds only task strings.`);
+    }
+    const withoutEmptyPhases = list.filter((entry) => {
+        if (!isRecord(entry))
+            return true;
+        if (typeof entry.phase !== "string" && !("items" in entry))
+            return true;
+        return entry.items !== undefined && (!Array.isArray(entry.items) || entry.items.length > 0);
+    });
+    if (withoutEmptyPhases.length !== list.length) {
+        changed = true;
+        const dropped = list.length - withoutEmptyPhases.length;
+        notices.push(`[auto-corrected] dropped ${dropped} "list" ${dropped === 1 ? "entry" : "entries"} with no tasks. Every phase needs at least one task in "items".`);
+        list = withoutEmptyPhases;
+    }
+    const hasObjectEntries = list.some((entry) => isRecord(entry));
+    const strayStrings = list.filter((entry) => typeof entry === "string");
+    if (strayStrings.length > 0 && hasObjectEntries) {
+        changed = true;
+        notices.push(`[auto-corrected] dropped ${strayStrings.length} stray ${strayStrings.length === 1 ? "entry" : "entries"} from "list". "list" holds only phase objects: {"phase":"<name>","items":["<task>", ...]}`);
+        list = list.filter((entry) => typeof entry !== "string");
+    }
+    const usedNames = new Set();
+    for (const entry of list) {
+        if (isRecord(entry) && typeof entry.phase === "string" && entry.phase.trim() !== "")
+            usedNames.add(entry.phase);
+    }
+    const generatedNames = [];
+    for (let index = 0; index < list.length; index++) {
+        const entry = list[index];
+        if (!isRecord(entry) ||
+            !Array.isArray(entry.items) ||
+            entry.items.length === 0 ||
+            !entry.items.every((item) => typeof item === "string") ||
+            (typeof entry.phase === "string" && entry.phase.trim() !== "")) {
+            continue;
+        }
+        let counter = 1;
+        let name = DEFAULT_INIT_PHASE;
+        while (usedNames.has(name)) {
+            counter += 1;
+            name = `${DEFAULT_INIT_PHASE} ${counter}`;
+        }
+        usedNames.add(name);
+        generatedNames.push(name);
+        const { phase: _replaced, ...rest } = entry;
+        list[index] = { phase: name, ...rest };
+        changed = true;
+    }
+    if (generatedNames.length > 0) {
+        notices.push(`[auto-corrected] named ${generatedNames.length} "list" ${generatedNames.length === 1 ? "entry" : "entries"} without a phase name: ${quoted(generatedNames)}. Pass "phase" explicitly: {"phase":"<name>","items":["<task>", ...]}`);
+    }
+    return changed ? list : input;
+}
+/**
+ * The todo tool's `prepareArguments`: rewrites near-canonical shapes (senpi#5148 wrappers,
+ * senpi#5332 list/op corrections) to the canonical one before schema validation. Any call a
+ * rule does not correct is returned as the SAME reference, and a correction that would leave
+ * `list` empty is abandoned entirely so the malformed call still fails validation instead of
+ * clearing the todo list. A caller-sent `TODO_PREPARED_CORRECTIONS_KEY` is never trusted
+ * (senpi#5332): it is dropped on a copy before any rule runs, and when that removal is the
+ * only change the stripped copy is returned instead of the same reference.
+ */
+export function prepareTodoArguments(input) {
+    if (!isRecord(input) || Array.isArray(input))
+        return input;
+    const { [TODO_PREPARED_CORRECTIONS_KEY]: _callerSent, ...stripped } = input;
+    const args = TODO_PREPARED_CORRECTIONS_KEY in input ? stripped : input;
+    const notices = [];
+    let draft;
+    const revise = (mutate) => {
+        draft ??= { ...args };
+        mutate(draft);
+    };
+    const rawOp = args.op;
+    let op = rawOp;
+    if (typeof rawOp === "string" && !isOperation(rawOp)) {
+        // Only stray leading/trailing characters that are neither letters nor digits are
+        // stripped ("view}", " done."); digits survive, so "rm 2" and " 2rm" stay invalid
+        // ops, and the middle must already be exactly a known operation ("re-move").
+        const stripped = rawOp.replace(/^[^a-z0-9]+|[^a-z0-9]+$/gi, "");
+        // A corrected rm/done/drop/start without a non-blank "task"/"phase" would act on every
+        // task (senpi#5332 review): leave such a call for validation to reject unchanged.
+        const carriesTarget = nonBlank(args.task) !== undefined || nonBlank(args.phase) !== undefined;
+        const needsTarget = stripped === "rm" || stripped === "done" || stripped === "drop" || stripped === "start";
+        if (isOperation(stripped) && (!needsTarget || carriesTarget)) {
+            op = stripped;
+            revise((draftArgs) => {
+                draftArgs.op = stripped;
+            });
+            notices.push(`[auto-corrected] "op" ${JSON.stringify(rawOp)} is not a known operation; used "${stripped}" after stripping stray leading or trailing non-alphanumeric characters. Pass "op" exactly: init, start, done, rm, drop, append, view.`);
+        }
+    }
+    // A `list` always means init, so its rules also run when op is missing. The top-level
+    // `items` rules do not: an op-less `items` call is only inferred as init against an empty
+    // list and as append with a phase, so promoting or unwrapping it here would bypass those
+    // guards (senpi#5332 review). Only an explicit "init" — after the op correction above —
+    // may adopt the `items` rules.
+    if (op === undefined || op === "init") {
+        if ("list" in args) {
+            let listValue = args.list;
+            if (typeof listValue === "string") {
+                try {
+                    const parsed = JSON.parse(listValue);
+                    if (Array.isArray(parsed) || isRecord(parsed)) {
+                        listValue = parsed;
+                        notices.push('[auto-corrected] "list" was sent as a JSON string; parsed it. Pass "list" as an array of phases.');
+                    }
+                }
+                catch {
+                    // Unparseable: leave the string for validation to reject.
+                }
+            }
+            let candidate = unwrapTodoList(listValue);
+            if (Array.isArray(candidate)) {
+                const normalized = normalizeTodoListEntries(candidate, notices);
+                if (normalized === null)
+                    return args;
+                candidate = normalized;
+            }
+            // A correction must never widen a malformed call into a list clear.
+            if (Array.isArray(candidate) && candidate.length === 0)
+                return args;
+            if (candidate !== args.list) {
+                const adopted = candidate;
+                revise((draftArgs) => {
+                    draftArgs.list = adopted;
+                });
+            }
+        }
+    }
+    if (op === "init" && args.list === undefined && Array.isArray(args.items) && args.items.length > 0) {
+        const items = args.items;
+        if (items.every(isPhaseRecord)) {
+            const normalized = normalizeTodoListEntries([...items], notices);
+            if (normalized === null || normalized.length === 0)
+                return args;
+            const adopted = normalized;
+            revise((draftArgs) => {
+                draftArgs.list = adopted;
+                delete draftArgs.items;
+            });
+            notices.push('[auto-corrected] "items" held phase records; moved them to "list". Pass phases under "list": {"op":"init","list":[{"phase":"<name>","items":["<task>", ...]}]}');
+        }
+        else {
+            const mapped = items.map((item) => (isContentRecord(item) && !isPhaseRecord(item) ? item.content : item));
+            if (mapped.some((item) => typeof item === "string") && mapped.some(isPhaseRecord))
+                return args;
+            const unwrapped = items.filter((item) => isContentRecord(item) && !isPhaseRecord(item)).length;
+            if (unwrapped > 0 && mapped.every((item) => typeof item === "string")) {
+                revise((draftArgs) => {
+                    draftArgs.items = mapped;
+                });
+                notices.push(`[auto-corrected] unwrapped ${unwrapped} top-level "items" ${unwrapped === 1 ? "entry" : "entries"} carrying a "content" field into their task strings. "items" holds only task strings.`);
+            }
+        }
+    }
+    if (!draft)
         return args;
-    const unwrapped = unwrapTodoList(args.list);
-    return unwrapped === args.list ? args : { ...args, list: unwrapped };
+    return notices.length > 0 ? { ...draft, [TODO_PREPARED_CORRECTIONS_KEY]: [...notices] } : draft;
+}
+/**
+ * Splits the prepare-time correction notices off prepared arguments (see
+ * `TODO_PREPARED_CORRECTIONS_KEY`): the arguments without the reserved key, plus the notices
+ * to prepend to `normalizeTodoParams`'s own corrections.
+ */
+export function splitPreparedCorrections(args) {
+    const { [TODO_PREPARED_CORRECTIONS_KEY]: notices, ...rest } = args;
+    return {
+        args: rest,
+        corrections: Array.isArray(notices)
+            ? notices.filter((notice) => typeof notice === "string")
+            : [],
+    };
 }
 function nonBlank(value) {
     return typeof value === "string" && value.trim() !== "" ? value : undefined;

package/dist/core/extensions/builtin/todotools/prompt.d.ts

@@ -1,3 +1,3 @@
-export declare const TODO_TOOL_DESCRIPTION = "**Tasks referenced by verbatim content string, NEVER an auto-generated ID: no \"task-1\"/\"task-N\" exists. Pass the content text in the task field.**\n\nOn each completion the earliest still-open task (in phase order) auto-promotes to in_progress.\nCompleting tasks out of phase order can move this pointer **back** to an earlier phase. This is expected; completed tasks are never reverted.\n\n## Operations\n\n| op | Required fields | Effect |\n|---|---|---|\n| init | list: [{phase, items: string[]}] | Initialize full list (replaces existing) |\n| init | items: string[] | Flattened single-phase init |\n| start | task | Mark in progress |\n| done | task or phase | Mark completed |\n| drop | task or phase | Mark abandoned |\n| rm | task or phase (optional) | Remove task or phase; omit both to clear |\n| append | phase?, items: string[] | Append tasks to phase; lazily creates phase |\n| view | - | Read-only: echo list |\n\nExample: {\"op\":\"init\",\"list\":[{\"phase\":\"Setup\",\"items\":[\"Survey code\",\"Write tests\"]}]}\n\n## Anatomy\n- **Task content**: 5\u201310 words; what, not how. Unique identifier.\n- **Phase name**: short noun phrase (e.g. Foundation, Auth, Verification). Unique identifier. NEVER prefix 1., A), Phase 1:.\n\n## Rules\n- Mark tasks done immediately after finishing, then re-check the list against the newest user message. Complete phases in order.\n- NEVER end a turn with a todo call as its only tool call - batch it with the real work: init with the first reads/edits, each done/start with the next action.\n- Blocked? append a task to the active phase, or drop.\n- Keep task/phase strings stable once introduced. done/start/drop take the task's EXACT text: copy it verbatim from the latest todo result; when it is lost, view echoes the list.\n\n## When to create a list\n- User explicitly requests one\n- User provides a set of tasks\n- New instructions arrive mid-task (reconcile before acting): keep what they don't conflict with, amend what they contradict, append what they add; replace only on explicit redirect\n\n<critical>\nUser hands you a multi-step plan (phased todo, numbered/bulleted checklist, or \"N bugs/items/tasks\"):\n- You MUST init the list with EVERY item as its own task before working.\n- Enumerate all; NEVER summarize into fewer tasks, sample \"the important ones\", drop items, or track the rest from memory.\n</critical>";
-export declare const TASK_MANAGEMENT_SECTION = "\n<Task_Management>\n## Todo Management\n\nA request with three or more distinct steps gets a phased todo before the first edit - investigation, implementation, verification, final report - in the todo tool; its description carries the operations, anatomy, and rules. Mark each item done the moment it finishes and reconcile the list against the newest user message before ending a turn.\n\n## Evidence\n- File edit: inspect the changed files and diagnostics.\n- Build command: require exit code 0.\n- Test run: require passing output, or state the pre-existing failure.\n</Task_Management>\n";
+export declare const TODO_TOOL_DESCRIPTION = "**Tasks referenced by verbatim content string, NEVER an auto-generated ID: no \"task-1\"/\"task-N\" exists. Pass the content text in the task field.**\n\nOn each completion the earliest still-open task (in phase order) auto-promotes to in_progress.\nCompleting tasks out of phase order can move this pointer **back** to an earlier phase. This is expected; completed tasks are never reverted.\n\n## Operations\n\n| op | Required fields | Effect |\n|---|---|---|\n| init | list: [{phase, items: string[]}] | Initialize full list (replaces existing). Each list entry is exactly one phase; items holds only task strings |\n| init | items: string[] | Flattened single-phase init |\n| start | task | Mark in progress |\n| done | task or phase | Mark completed |\n| drop | task or phase | Mark abandoned |\n| rm | task or phase (optional) | Remove task or phase; omit both to clear |\n| append | phase?, items: string[] | Append tasks to phase; lazily creates phase |\n| view | - | Read-only: echo list |\n\nExample: {\"op\":\"init\",\"list\":[{\"phase\":\"Setup\",\"items\":[\"Survey code\",\"Write tests\"]}]}\n\n## Anatomy\n- **Task content**: 5\u201310 words; what, not how. Unique identifier.\n- **Phase name**: short noun phrase (e.g. Foundation, Auth, Verification). Unique identifier. NEVER prefix 1., A), Phase 1:.\n\n## Rules\n- Mark tasks done immediately after finishing, then re-check the list against the newest user message. Complete phases in order.\n- NEVER end a turn with a todo call as its only tool call - batch it with the real work: init with the first reads/edits, each done/start with the next action.\n- Blocked? append a task to the active phase, or drop.\n- Keep task/phase strings stable once introduced. done/start/drop take the task's EXACT text: copy it verbatim from the latest todo result; when it is lost, view echoes the list.\n\n## When to create a list\n- User explicitly requests one\n- User provides a set of tasks\n- New instructions arrive mid-task (reconcile before acting): keep what they don't conflict with, amend what they contradict, append what they add; replace only on explicit redirect\n\n<critical>\nUser hands you a multi-step plan (phased todo, numbered/bulleted checklist, or \"N bugs/items/tasks\"):\n- You MUST init the list with EVERY item as its own task before working.\n- Enumerate all; NEVER summarize into fewer tasks, sample \"the important ones\", drop items, or track the rest from memory.\n</critical>";
+export declare const TASK_MANAGEMENT_SECTION = "\n<Task_Management>\n## Todo Management\n\nRequest with 3+ distinct steps -> phased todo in the todo tool before first edit: investigation, implementation, verification, final report.\n\n## Evidence\n- File edit: inspect changed files + diagnostics.\n- Build: exit code 0.\n- Test run: passing output, or state the pre-existing failure.\n</Task_Management>\n";
 //# sourceMappingURL=prompt.d.ts.map

package/dist/core/extensions/builtin/todotools/prompt.js

@@ -11,7 +11,7 @@ Completing tasks out of phase order can move this pointer **back** to an earlier
 
 | op | Required fields | Effect |
 |---|---|---|
-| init | list: [{phase, items: string[]}] | Initialize full list (replaces existing) |
+| init | list: [{phase, items: string[]}] | Initialize full list (replaces existing). Each list entry is exactly one phase; items holds only task strings |
 | init | items: string[] | Flattened single-phase init |
 | start | task | Mark in progress |
 | done | task or phase | Mark completed |
@@ -46,12 +46,12 @@ export const TASK_MANAGEMENT_SECTION = `
 <Task_Management>
 ## Todo Management
 
-A request with three or more distinct steps gets a phased todo before the first edit - investigation, implementation, verification, final report - in the todo tool; its description carries the operations, anatomy, and rules. Mark each item done the moment it finishes and reconcile the list against the newest user message before ending a turn.
+Request with 3+ distinct steps -> phased todo in the todo tool before first edit: investigation, implementation, verification, final report.
 
 ## Evidence
-- File edit: inspect the changed files and diagnostics.
-- Build command: require exit code 0.
-- Test run: require passing output, or state the pre-existing failure.
+- File edit: inspect changed files + diagnostics.
+- Build: exit code 0.
+- Test run: passing output, or state the pre-existing failure.
 </Task_Management>
 `;
 //# sourceMappingURL=prompt.js.map

package/dist/core/extensions/builtin/todotools/tools/todo.js

@@ -6,7 +6,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { partialStrikethrough, strikeRevealCount } from "../../../../../modes/interactive/components/todo-strike.js";
 import { resolvePromptSurface } from "../../../../dynamic-prompt/build.js";
-import { normalizeTodoParams, prepareTodoArguments } from "../normalize.js";
+import { normalizeTodoParams, prepareTodoArguments, splitPreparedCorrections } from "../normalize.js";
 import { TODO_TOOL_DESCRIPTION } from "../prompt.js";
 import { applyParams, captureListAsk, clonePhases, findTaskByContent, formatHandoffCue, formatSummary, getCompletionTransitions, getTodoMarker, handoffMomentOf, nextActionableTask, sanitizeTodoText, TODO_STATE_ENTRY_TYPE, } from "../state.js";
 const TodoOperationSchema = Type.Union([
@@ -212,24 +212,25 @@ export function registerTodoTool(pi, accessors) {
         label: "Todo",
         description: TODO_TOOL_DESCRIPTION,
         promptSnippet: "Track phased tasks with one op-based todo tool; reference tasks by their exact content.",
-        promptGuidelines: [
-            "Use one todo operation at a time, batched with the real work; never end a turn with a todo call as its only tool call.",
-            "Reference tasks and phases by their exact content/name; use view when the text is uncertain.",
-            "Mark work done immediately and use drop for tasks that are no longer needed.",
-        ],
         parameters: TODO_PARAMS_SCHEMA,
         prepareArguments: (args) => prepareTodoArguments(args),
         executionMode: "sequential",
         async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             const previousPhases = clonePhases(accessors.getCurrentPhases());
             const previousAsk = accessors.getCurrentAsk();
-            const normalized = normalizeTodoParams(params, previousPhases);
+            // prepareTodoArguments carries its notices on the prepared args under a reserved key
+            // (#5332). The key is stripped here before normalizing and is never persisted or
+            // rendered, but the prepared arguments — key included — flow to the agent loop's
+            // beforeToolCall/afterToolCall hooks, so extension tool_call/tool_result hooks may
+            // observe it on the arguments they receive.
+            const prepared = splitPreparedCorrections(params);
+            const normalized = normalizeTodoParams(prepared.args, previousPhases);
             if (normalized.error || !normalized.entry) {
                 const error = normalized.error ?? 'Missing "op". Example: {"op":"init","list":[{"phase":"Setup","items":["..."]}]}';
                 throw new Error(`${error}\n\n${formatSummary(previousPhases, [], true, previousAsk)}`);
             }
             const entry = normalized.entry;
-            const corrections = normalized.corrections;
+            const corrections = [...prepared.corrections, ...normalized.corrections];
             const readOnly = entry.op === "view";
             const errors = [];
             const applied = readOnly

package/dist/core/extensions/builtin/webfetch/webfetch/tool.js

@@ -19,11 +19,6 @@ export const webfetch = defineTool({
     description: "Fetches content from a URL and returns it as markdown, plain text, or HTML. " +
         "Network use is bounded by timeout and response size limits.",
     promptSnippet: "webfetch: retrieve URL content as markdown, text, or html",
-    promptGuidelines: [
-        "Use webfetch when a specific URL must be retrieved.",
-        "Prefer markdown format unless raw HTML or plain text is explicitly needed.",
-        "The tool is read-only and does not modify files.",
-    ],
     parameters: Params,
     async execute(_toolCallId, params, signal, onUpdate, _ctx) {
         const format = parseWebfetchFormat(params.format);

package/dist/core/extensions/builtin/websearch/index.js

@@ -8,7 +8,7 @@ import { loadWebsearchConfig } from "./websearch/config.js";
 import { attemptRouteLabel } from "./websearch/route-attempts.js";
 import { providerEntryLabel } from "./websearch/search.js";
 import { resolveNativeSearchModel } from "./websearch/search-model.js";
-import { createWebSearchTool } from "./websearch/tool.js";
+import { createWebSearchTool, WEB_SEARCH_CITE_GUIDELINE } from "./websearch/tool.js";
 const STATUS_KEY = "pi-websearch";
 const WIDGET_KEY = "pi-websearch";
 const NATIVE_BYPASS_MESSAGE = "Native provider web search is handled by the built-in provider extension.";
@@ -127,13 +127,18 @@ export default function (pi) {
         }
         if (!hasServerSearch(ctx.model))
             return undefined;
-        const systemPrompt = event.systemPrompt
+        const failed = hasServerSearchFailed(ctx.sessionManager, ctx.model);
+        const withoutSections = event.systemPrompt
             .replace(ANTHROPIC_WEB_SEARCH_SECTION, "")
             .replace(OPENAI_WEB_SEARCH_SECTION, "");
+        // Server search: the section below carries the cite rule, so the tool's guideline bullet goes.
+        const systemPrompt = failed
+            ? withoutSections
+            : withoutSections.replace(`- ${WEB_SEARCH_CITE_GUIDELINE}\n`, "");
         return {
-            systemPrompt: `${systemPrompt}\n## Web Search\n${hasServerSearchFailed(ctx.sessionManager, ctx.model)
+            systemPrompt: `${systemPrompt}\n## Web Search\n${failed
                 ? "Use the standalone web_search tool when current information is needed. Native search failed for this session model."
-                : "Use the provider's in-turn server web search when current information is needed."}`,
+                : "web_search = provider server-side search. Use when current info needed; cite returned URLs in final answer."}`,
         };
     }, { previewSafe: true });
     pi.on("before_provider_request", (event, ctx) => {

package/dist/core/extensions/builtin/websearch/websearch/tool.d.ts

@@ -12,6 +12,8 @@ type WebSearchTool = ReturnType<typeof defineTool<typeof Params, SearchRenderDet
 export interface WebSearchToolOptions {
     onSearchComplete?: (details: SearchDetails) => void;
 }
+/** The one Tool Guidelines bullet; the server-search `## Web Search` section states it instead (senpi#5335). */
+export declare const WEB_SEARCH_CITE_GUIDELINE = "web_search used -> cite returned URLs in final answer.";
 export declare function createWebSearchTool(getConfig: ConfigProvider, options?: WebSearchToolOptions): WebSearchTool;
 export declare const web_search: import("../../../types.ts").ToolDefinition<Type.TObject<{
     query: Type.TString;

package/dist/core/extensions/builtin/websearch/websearch/tool.js

@@ -40,6 +40,8 @@ function formatSearchProgressText(details) {
 function searchErrorDetails(query, error, reason) {
     return { phase: "error", query, error, ...(reason ? { reason } : {}) };
 }
+/** The one Tool Guidelines bullet; the server-search `## Web Search` section states it instead (senpi#5335). */
+export const WEB_SEARCH_CITE_GUIDELINE = "web_search used -> cite returned URLs in final answer.";
 export function createWebSearchTool(getConfig, options = {}) {
     let routingState;
     let routingKey = "";
@@ -49,7 +51,7 @@ export function createWebSearchTool(getConfig, options = {}) {
         label: "Web Search",
         description: "Search the web for current information and return source URLs for citation.",
         promptSnippet: "Search the web for current information, documentation, news, or external facts.",
-        promptGuidelines: ["After using web_search, cite relevant returned URLs in the final answer."],
+        promptGuidelines: [WEB_SEARCH_CITE_GUIDELINE],
         parameters: Params,
         async execute(_toolCallId, params, signal, onUpdate, ctx) {
             if (params.allowed_domains?.length && params.blocked_domains?.length) {

package/dist/core/model-registry.d.ts

@@ -43,12 +43,20 @@ export declare class ModelRegistry {
     /**
      * The live auth check reads the in-memory credentials. When the last read found the store
      * locked they were never loaded, so re-read now (bounded by the sync lock budget) instead
-     * of answering from the empty fallback for the rest of the process.
+     * of answering from the empty fallback for the rest of the process. A store that could not be
+     * loaded is re-read the same way, so a repaired auth.json is seen without a restart (#4413).
      */
     private retryBusyCredentialRead;
     getUpstreamModelId(model: Model<Api>): string | undefined;
     getServiceTier(model: Model<Api>): "auto" | "flex" | "priority" | "ultrafast" | undefined;
-    getApiKeyAndHeaders(model: Model<Api>): Promise<ResolvedRequestAuth>;
+    /**
+     * Request auth for a direct provider call. A caller acting for a session passes its id so the
+     * key belongs to the account that session's turns use; without it the stored credential is
+     * resolved as for session-less callers.
+     */
+    getApiKeyAndHeaders(model: Model<Api>, options?: {
+        sessionId?: string;
+    }): Promise<ResolvedRequestAuth>;
     getProviderAuthStatus(provider: string): AuthStatus;
     /** `getProviderAuthStatus` plus whether it is a non-stored sign-in, from one resolution (#3537). */
     resolveProviderAuth(provider: string): {

package/dist/core/model-registry.js

@@ -59,10 +59,11 @@ export class ModelRegistry {
     /**
      * The live auth check reads the in-memory credentials. When the last read found the store
      * locked they were never loaded, so re-read now (bounded by the sync lock budget) instead
-     * of answering from the empty fallback for the rest of the process.
+     * of answering from the empty fallback for the rest of the process. A store that could not be
+     * loaded is re-read the same way, so a repaired auth.json is seen without a restart (#4413).
      */
     retryBusyCredentialRead() {
-        if (this.authStorage.isCredentialStoreBusy())
+        if (this.authStorage.isCredentialStoreBusy() || this.authStorage.getLoadError())
             this.authStorage.reload();
     }
     getUpstreamModelId(model) {
@@ -71,9 +72,16 @@ export class ModelRegistry {
     getServiceTier(model) {
         return this.runtime.getCompatibilityRequestConfig(model).serviceTier;
     }
-    async getApiKeyAndHeaders(model) {
+    /**
+     * Request auth for a direct provider call. A caller acting for a session passes its id so the
+     * key belongs to the account that session's turns use; without it the stored credential is
+     * resolved as for session-less callers.
+     */
+    async getApiKeyAndHeaders(model, options = {}) {
         try {
-            const resolution = await this.runtime.getAuth(model);
+            const resolution = options.sessionId === undefined
+                ? await this.runtime.getAuth(model)
+                : await this.runtime.getSessionAuth(model, options.sessionId);
             const compatibility = this.runtime.getCompatibilityRequestConfig(model);
             if (!resolution) {
                 if (compatibility.authHeader) {

package/dist/core/model-runtime.d.ts

@@ -168,6 +168,14 @@ export declare class ModelRuntime implements Models {
     isFallbackEligible(providerId: string): boolean;
     getAuth(providerId: string, overrides?: ModelRuntimeAuthOverrides): Promise<AuthResult | undefined>;
     getAuth(model: AnyModel, overrides?: ModelRuntimeAuthOverrides): Promise<AuthResult | undefined>;
+    /**
+     * Auth for a request a session sends outside the rotation stream (compaction, /btw, look-at,
+     * cache keepalive). The key must belong to the account the session's own turns use, so a pooled
+     * provider resolves the slot the stream would pick for this session; without a pool, or when
+     * the stream would not rotate either, it is `getAuth(model)`.
+     */
+    getSessionAuth(model: Model<Api>, sessionId: string): Promise<AuthResult | undefined>;
+    private sessionSlotAuth;
     private enqueueCredentialOperation;
     private synchronizeCredentialState;
     setRuntimeApiKey(providerId: string, apiKey: string, options?: AuthOperationOptions): Promise<void>;

package/dist/core/model-runtime.js

@@ -1,6 +1,7 @@
 import { dirname, join } from "node:path";
 import { clampThinkingLevel, createModels, getCurrentTools, isModelType, lazyStream, ModelsError, normalizeContext, normalizeProviderId, providerNotConfiguredMessage, setWireIdentity, wrapStreamWithModelRecovery, } from "@earendil-works/pi-ai";
 import * as builtinProviderCatalog from "@earendil-works/pi-ai/providers/all";
+import { setOAuthPageBrand } from "@earendil-works/pi-ai/utils/oauth-page";
 import { assertChatModel, assertClassifierModel, assertImageModel, classifierErrorResult, imageErrorResult, } from "@earendil-works/pi-ai/utils/model-operations";
 import { APP_NAME, BRAND, getAgentDir } from "../config.js";
 import { operationSignal, raceWithAbortSignal } from "../utils/abort.js";
@@ -23,6 +24,7 @@ import { createVirtualModel, findLatestResponse, isVirtualModel, withVirtualMode
 // The product's identity must ride outgoing requests. This lives here because the AI package
 // is already part of this module's graph; the CLI bootstrap deliberately does not import it.
 setWireIdentity(BRAND?.userAgent ?? APP_NAME);
+setOAuthPageBrand({ name: APP_NAME, ...(BRAND?.logo ? { logo: BRAND.logo } : {}) });
 /** Availability re-reads after a busy credential store: 250, 500, 1000, 2000, 4000 ms. */
 const BUSY_AVAILABILITY_RETRY_LIMIT = 5;
 const BUSY_AVAILABILITY_RETRY_BASE_MS = 250;
@@ -550,6 +552,42 @@ export class ModelRuntime {
             },
         };
     }
+    /**
+     * Auth for a request a session sends outside the rotation stream (compaction, /btw, look-at,
+     * cache keepalive). The key must belong to the account the session's own turns use, so a pooled
+     * provider resolves the slot the stream would pick for this session; without a pool, or when
+     * the stream would not rotate either, it is `getAuth(model)`.
+     */
+    async getSessionAuth(model, sessionId) {
+        return this.getAuth(model, (await this.sessionSlotAuth(model, sessionId)) ?? {});
+    }
+    async sessionSlotAuth(model, sessionId) {
+        // The stream's own synchronous admission check, so a provider the stream would not rotate costs
+        // nothing beyond getAuth. Remote compaction's before_provider_request hook calls this on every
+        // request to such a model; there a pooled provider pays one extra credential read and two slot
+        // listings (each reads the pool's health state) before getAuth.
+        if (!this.couldRotateCredentials(model, undefined))
+            return undefined;
+        const sources = await this.credentialRotationSources(model, undefined);
+        if (!sources)
+            return undefined;
+        const { rotation } = await this.loadCredentialPool();
+        const { selectSessionSlot } = await import("./credential-pool/session-slot.js");
+        const slots = await rotation.listRotationSlots(sources, {
+            acquireLeases: false,
+            modelId: this.getCompatibilityRequestConfig(model).upstreamModelId ?? model.id,
+        });
+        const pooled = sources.credential;
+        const slot = selectSessionSlot(slots, {
+            affinityKey: sessionId,
+            useAffinity: sources.policy?.affinity !== false,
+            hasher: rotation.sha256SlotHasher,
+            ...(pooled?.order === undefined ? {} : { order: pooled.order }),
+        }, Date.now());
+        if (!slot)
+            return undefined;
+        return slot.lane === "env" ? { apiKey: slot.envKey } : { slotName: slot.name };
+    }
     enqueueCredentialOperation(providerId, signal, task) {
         const previous = this.credentialOperations.get(providerId) ?? Promise.resolve();
         let markStarted;
@@ -946,7 +984,7 @@ export class ModelRuntime {
         return this.enqueueCredentialOperation(providerId, signal, async () => {
             const store = this.credentials.backingStore;
             const before = await store.read(providerId, { signal });
-            const credential = await this.models.login(providerId, type, { ...interaction, signal }, options);
+            const credential = await this.models.login(providerId, type, { ...interaction, signal }, { ...options, appName: APP_NAME });
             if (this.poolStatePath !== undefined) {
                 const { retireLoginSlotHealth } = await import("./credential-pool/login-health.js");
                 await retireLoginSlotHealth(this.poolStatePath, providerId, before, await store.read(providerId, { signal }));

package/dist/core/provider-failure.d.ts

@@ -1,5 +1,6 @@
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import { type Api, type AssistantMessage, type Model, type ProviderDiagnostic, type ProviderDiagnosticCategory } from "@earendil-works/pi-ai";
+import { type TransportTrustFailure } from "../engine-trust/transport-failure.ts";
 import { type FallbackModelLookup } from "./retry-fallback/chains.ts";
 /**
  * `request_refused`: an `auth` failure on a credential that served a response moments before, so the
@@ -33,6 +34,11 @@ export interface ProviderFailure {
     readonly resetsAt?: number;
     readonly reason: string;
     readonly action: string;
+    /**
+     * Present when the request failed TLS chain verification while the engine runs on a fallback trust
+     * generation: the fallback reason and its repair action id (senpi#5244).
+     */
+    readonly trust?: TransportTrustFailure;
 }
 /** An `auth` failure on a credential that served a response moments before: the request was refused, not the key. */
 export declare function isRequestLevelRefusal(message: AssistantMessage): boolean;

package/dist/core/provider-failure.js

@@ -1,4 +1,5 @@
 import { PROVIDER_NOT_CONFIGURED_PREFIX, sanitizeProviderDiagnostic, stripTurnRetrySuppressionPrefix, } from "@earendil-works/pi-ai";
+import { transportTrustFailure } from "../engine-trust/transport-failure.js";
 import { parseFallbackSelector } from "./retry-fallback/chains.js";
 const ACTIONS = {
     auth: { reason: "the provider rejected the credentials", action: "re-authenticate the provider" },
@@ -82,11 +83,14 @@ export function providerFailureOf(messages, selected) {
     const last = messages.findLast((message) => message.role === "assistant");
     if (last === undefined || last.role !== "assistant" || last.stopReason !== "error")
         return undefined;
-    const failure = notConfiguredFailure(last) ??
-        describeProviderFailure(sanitizeProviderDiagnostic(last.providerDiagnostic), last.provider, {
+    const diagnostic = sanitizeProviderDiagnostic(last.providerDiagnostic);
+    const described = notConfiguredFailure(last) ??
+        describeProviderFailure(diagnostic, last.provider, {
             model: last.model,
             requestRefused: isRequestLevelRefusal(last),
         });
+    const trust = transportTrustFailure(diagnostic);
+    const failure = trust === undefined ? described : { ...described, trust };
     if (selected === undefined || (selected.provider === last.provider && selected.model === last.model)) {
         return failure;
     }

package/dist/core/retry-fallback/controller-types.d.ts

@@ -14,6 +14,8 @@ export interface ActiveFallbackState {
     pinnedByBilling: boolean;
     /** Derived OR of the two provenance flags - the only field consumers read. */
     pinned: boolean;
+    /** The original provider's login id when the episode began; a sign-in moves it and releases a billing pin (senpi#4099). */
+    recoveryRevision?: string;
 }
 export type FallbackReason = "transient" | "refusal" | "hard-error" | "billing";
 /** Absent: the original recovered after its cooldown. `fallback-unusable`: the fallback itself could not serve. */
@@ -64,5 +66,10 @@ export interface RetryFallbackControllerDeps {
         thinkingLevel?: ThinkingLevel;
     } | undefined;
     isAuthAvailable(provider: string): boolean;
+    /**
+     * The `loginId` the last sign-in stored for `provider` ("" when none did), never key material;
+     * `undefined` when it cannot be read. Only a sign-in writes a new id; a token refresh keeps it or drops it to "" (senpi#4099).
+     */
+    recoveryRevision?(provider: string): Promise<string | undefined>;
 }
 //# sourceMappingURL=controller-types.d.ts.map