@selesai/code 0.13.39 → 0.14.0

package/dist/extensions/mcp/tools.js

@@ -0,0 +1,252 @@
+/**
+ * Adapts MCP tools to pi tool definitions.
+ *
+ * Results map onto pi's model-facing content (text and images). Text over 20KB keeps its start and
+ * end with the middle cut out, like Codex does, and the full text is saved to a temp file the model
+ * can read. Binary resources other than images are saved to temp files too, and resource links name
+ * the `read_mcp_resource` tool. Codemode scripts receive the whole `CallToolResult` without `_meta`
+ * (`content` blocks as sent by the server, `structuredContent`, `isError`), never truncated: it is
+ * the tool's `structuredContent`, and every MCP tool declares a `CallToolResult` output schema. MCP
+ * errors (`isError`) are error results for the model, but scripts still resolve to the result.
+ */
+import { createHash } from "node:crypto";
+import { toLlmContent, } from "@earendil-works/pi-mcp";
+import { Container, Spacer, Text } from "@earendil-works/pi-tui";
+import { READ_MCP_RESOURCE_TOOL } from "../../core/mcp-servers.js";
+import { formatToolCallWithArgs, getTextOutput, replaceTabs } from "../../core/tools/render-utils.js";
+import { formatSize, truncateMiddle } from "../../core/tools/truncate.js";
+import { keyHint } from "../../modes/interactive/components/keybinding-hints.js";
+import { VisualLinePreview } from "../../modes/interactive/components/visual-truncate.js";
+import { writeOutputFile } from "../../utils/output-files.js";
+/**
+ * Tool exposure of an MCP exposure. `codemode` and `deferred` both leave tools out of the codemode
+ * description; they differ only in which tool the MCP extension activates to reach them.
+ */
+export function toToolExposure(exposure) {
+    return exposure === "codemode" ? "deferred" : exposure;
+}
+/** Provider tool names are limited to 64 characters of `[A-Za-z0-9_-]`. */
+const MAX_TOOL_NAME_LENGTH = 64;
+/** Model-facing text of an MCP result beyond this is cut in the middle. */
+export const MCP_OUTPUT_MAX_BYTES = 20 * 1024;
+/** Visual (wrapped) result lines shown before the output is expanded. */
+const OUTPUT_PREVIEW_LINES = 5;
+/** Tool that reads the resources named by resource links. */
+export { READ_MCP_RESOURCE_TOOL };
+export function saveToTempFile(data, extension) {
+    return writeOutputFile("pi-mcp", extension, data);
+}
+/**
+ * `mcp__<server>__<tool>`, sanitized and shortened with a hash suffix when too long. Like Codex,
+ * everything but `[A-Za-z0-9_]` becomes `_`, so the name is also the identifier codemode scripts
+ * call it by. `isTaken` reports names used by a different MCP tool: sanitizing can map two tools to
+ * one name (`a-b` and `a_b`), which then get the hash suffix.
+ */
+export function createMcpToolName(server, tool, isTaken = () => false) {
+    const name = `mcp__${server}__${tool}`.replace(/[^A-Za-z0-9_]/g, "_");
+    if (name.length <= MAX_TOOL_NAME_LENGTH && !isTaken(name))
+        return name;
+    const hash = createHash("sha256").update(`${server}\0${tool}`).digest("hex").slice(0, 8);
+    return `${name.slice(0, MAX_TOOL_NAME_LENGTH - hash.length - 1)}_${hash}`;
+}
+function textOf(content) {
+    return content
+        .filter((block) => block.type === "text")
+        .map((block) => block.text)
+        .join("\n");
+}
+/**
+ * Output schema of every MCP tool: the `CallToolResult` scripts receive, with the tool's own output
+ * schema as `structuredContent`. Codemode detects this shape to render `CallToolResult<T>`
+ * declarations.
+ */
+export function createMcpResultSchema(structuredContentSchema) {
+    return {
+        type: "object",
+        properties: {
+            content: { type: "array", items: { type: "object" } },
+            ...(structuredContentSchema ? { structuredContent: structuredContentSchema } : {}),
+            isError: { type: "boolean" },
+            _meta: { type: "object" },
+        },
+        required: ["content"],
+    };
+}
+/**
+ * Keep model-facing text within {@link MCP_OUTPUT_MAX_BYTES}. Longer text becomes one text block in
+ * Codex's truncation format, followed by the path of the file with the full text; images follow it.
+ */
+export async function limitMcpContent(content, saveOutput = saveToTempFile) {
+    const combined = textOf(content);
+    const truncation = truncateMiddle(combined, MCP_OUTPUT_MAX_BYTES);
+    if (!truncation.truncated)
+        return { content };
+    let fullOutputPath;
+    let where;
+    try {
+        fullOutputPath = await saveOutput(combined, ".txt");
+        where = `[Full output: ${fullOutputPath} (read it with offset/limit)]`;
+    }
+    catch (error) {
+        where = `[Could not save the full output: ${error instanceof Error ? error.message : String(error)}]`;
+    }
+    const tokens = Math.ceil(truncation.totalBytes / 4);
+    const text = `Warning: truncated output (original token count: ${tokens})\nTotal output lines: ${truncation.totalLines}\n\n${truncation.content}\n\n${where}`;
+    return {
+        content: [{ type: "text", text }, ...content.filter((block) => block.type === "image")],
+        ...(fullOutputPath ? { fullOutputPath } : {}),
+    };
+}
+/** File extension for a saved binary resource: the one its URI ends in, else `.bin`. */
+function extensionOf(uri) {
+    const path = URL.canParse(uri) ? new URL(uri).pathname : uri;
+    return /\.[A-Za-z0-9]{1,8}$/.exec(path)?.[0] ?? ".bin";
+}
+/** Blobs of these types are shown as text. */
+function isTextMimeType(mimeType) {
+    if (!mimeType)
+        return false;
+    const type = mimeType.split(";", 1)[0].trim().toLowerCase();
+    return type.startsWith("text/") || type === "application/json" || type.endsWith("+json") || type.endsWith("+xml");
+}
+/** Model-facing content of one block of `server`'s result. */
+async function blockToContent(server, block, options) {
+    if (block.type === "resource_link") {
+        const details = [block.mimeType, block.size === undefined ? undefined : formatSize(block.size)].filter(Boolean);
+        const read = options.readableResources ? `. Read it with ${READ_MCP_RESOURCE_TOOL} (server "${server}")` : "";
+        const description = block.description ? `: ${block.description}` : "";
+        return [
+            {
+                type: "text",
+                text: `[Resource ${block.uri} "${block.title ?? block.name}"${details.length > 0 ? ` (${details.join(", ")})` : ""}${description}${read}]`,
+            },
+        ];
+    }
+    if (block.type === "resource" && "blob" in block.resource && !block.resource.mimeType?.startsWith("image/")) {
+        const { uri, mimeType, blob } = block.resource;
+        const data = Buffer.from(blob, "base64");
+        if (isTextMimeType(mimeType))
+            return [{ type: "text", text: data.toString("utf8") }];
+        const kind = `${mimeType ?? "unknown type"}, ${formatSize(data.length)}`;
+        try {
+            const path = await (options.saveOutput ?? saveToTempFile)(data, extensionOf(uri));
+            return [{ type: "text", text: `[Binary resource ${uri} (${kind}) saved to ${path}]` }];
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            return [{ type: "text", text: `[Binary resource ${uri} (${kind}) could not be saved: ${reason}]` }];
+        }
+    }
+    return toLlmContent({ content: [block] });
+}
+/** Model-facing content of `server`'s content blocks, before the output limit. */
+export async function toModelContent(server, blocks, options = {}) {
+    return (await Promise.all(blocks.map((block) => blockToContent(server, block, options)))).flat();
+}
+/** Convert an MCP result. `isError` results become error results that keep the structured result. */
+export async function convertMcpResult(server, tool, result, options = {}) {
+    // Without content blocks, toLlmContent falls back to the structured content as JSON.
+    const converted = result.content.length > 0 ? await toModelContent(server, result.content, options) : toLlmContent(result);
+    if (result.isError && textOf(converted) === "") {
+        converted.push({ type: "text", text: `MCP tool ${server}/${tool} returned an error` });
+    }
+    const { content, fullOutputPath } = await limitMcpContent(converted, options.saveOutput);
+    const { _meta: _ignored, ...scriptResult } = result;
+    return {
+        content,
+        details: { server, tool, ...(fullOutputPath ? { fullOutputPath } : {}) },
+        structuredContent: scriptResult,
+        ...(result.isError ? { isError: true } : {}),
+    };
+}
+/**
+ * Tool input schemas must be objects. MCP servers may omit `type`, and some providers reject object
+ * schemas without `properties`.
+ */
+function toParameters(schema) {
+    return {
+        ...schema,
+        type: schema.type ?? "object",
+        ...(schema.properties === undefined ? { properties: {} } : {}),
+    };
+}
+const ANNOTATION_HINTS = ["readOnlyHint", "destructiveHint", "idempotentHint", "openWorldHint"];
+/** The boolean hints of an MCP tool's annotations, or undefined when it has none. */
+function toToolAnnotations(tool) {
+    const annotations = {};
+    for (const hint of ANNOTATION_HINTS) {
+        const value = tool.annotations?.[hint];
+        if (typeof value === "boolean")
+            annotations[hint] = value;
+    }
+    return Object.keys(annotations).length > 0 ? annotations : undefined;
+}
+export function createMcpToolDefinition(options) {
+    const { server, tool } = options;
+    const title = tool.title ?? tool.annotations?.title;
+    const annotations = toToolAnnotations(tool);
+    const label = `${server}/${tool.name}`;
+    return {
+        name: options.name,
+        label,
+        description: tool.description?.trim() || title || `MCP tool ${tool.name} from server ${server}`,
+        parameters: toParameters(tool.inputSchema),
+        outputSchema: createMcpResultSchema(tool.outputSchema),
+        exposure: toToolExposure(options.exposure),
+        namespace: options.namespace,
+        ...(annotations ? { annotations } : {}),
+        ...createMcpToolRenderers(label),
+        async execute(_toolCallId, params, signal, onUpdate) {
+            const client = await options.getClient();
+            const result = await client.callTool(tool.name, (params ?? {}), {
+                signal,
+                timeoutMs: options.timeoutMs,
+                onProgress: (progress) => {
+                    const total = progress.total === undefined ? "" : `/${progress.total}`;
+                    const text = progress.message ?? `Progress ${progress.progress}${total}`;
+                    onUpdate?.({ content: [{ type: "text", text }], details: { server, tool: tool.name } });
+                },
+            });
+            return convertMcpResult(server, tool.name, result, { readableResources: options.readableResources?.() });
+        },
+    };
+}
+/** Renderers of calls to an MCP tool, labeled `server/tool`, also used before the tool is registered. */
+export function createMcpToolRenderers(label) {
+    return {
+        renderCall(args, theme, context) {
+            const component = context.lastComponent ?? new Text("", 0, 0);
+            component.setText(formatToolCallWithArgs(label, args, theme, context.expanded));
+            return component;
+        },
+        renderResult(result, options, theme, context) {
+            const component = context.lastComponent ?? new Container();
+            component.clear();
+            const output = getTextOutput(result, context.showImages).trim();
+            if (!output)
+                return component;
+            const color = context.isError ? "error" : "toolOutput";
+            const styled = replaceTabs(output)
+                .split("\n")
+                .map((line) => theme.fg(color, line))
+                .join("\n");
+            component.addChild(new Spacer(1));
+            if (options.expanded) {
+                component.addChild(new Text(styled, 0, 0));
+            }
+            else {
+                // Limit wrapped lines, not logical ones: MCP results are often one long JSON line.
+                component.addChild(new VisualLinePreview({
+                    text: styled,
+                    maxVisualLines: OUTPUT_PREVIEW_LINES,
+                    keep: "start",
+                    formatHint: (hidden) => `${theme.fg("muted", `... (${hidden} more lines,`)} ${keyHint("app.tools.expand", "to expand")}${theme.fg("muted", ")")}`,
+                }));
+                const fullOutputPath = result.details?.fullOutputPath;
+                if (fullOutputPath)
+                    component.addChild(new Text(theme.fg("muted", `Full output: ${fullOutputPath}`), 0, 0));
+            }
+            return component;
+        },
+    };
+}

package/dist/extensions/mcp/ui.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The `/mcp` manager view: menus that rebuild while servers connect, a read-only status screen, and
+ * the sign-in screen that accepts a pasted redirect URL.
+ */
+import { type Component, type Focusable, type SelectItem, type TUI } from "@earendil-works/pi-tui";
+import type { ExtensionCommandContext } from "../../core/extensions/types.ts";
+import type { KeybindingsManager } from "../../core/keybindings.ts";
+import { type Theme } from "../../modes/interactive/theme/theme.ts";
+export interface McpMenu {
+    title: string;
+    /** Shown below the title. */
+    details?: string;
+    /** Shown below the details in the error color. */
+    error?: string;
+    items: SelectItem[];
+    /** Shown when there are no items. */
+    empty?: string;
+    /** Value of the item selected when the menu opens. */
+    selected?: string;
+    /** What the confirm key does, for the key hint. */
+    confirmLabel: string;
+    /** What the cancel key does, for the key hint. */
+    cancelLabel: string;
+}
+export interface McpUi {
+    /**
+     * Show a menu and resolve to the chosen item's value, or undefined when cancelled. `subscribe`
+     * rebuilds the menu on every change, keeping the selected item.
+     */
+    menu(build: () => McpMenu, subscribe?: (listener: () => void) => () => void): Promise<string | undefined>;
+    /** Show a message while an operation runs. With `onCancel`, the cancel key calls it. */
+    status(title: string, message: string, onCancel?: () => void): void;
+    /**
+     * Show the authorization URL and wait for a pasted redirect URL. Resolves to undefined when
+     * cancelled or when `signal` aborts (the browser reached the callback).
+     */
+    redirectUrl(title: string, authorizationUrl: string, signal: AbortSignal): Promise<string | undefined>;
+}
+export declare class McpManagerView implements McpUi, Component, Focusable {
+    private readonly tui;
+    private readonly theme;
+    private readonly keybindings;
+    private content;
+    private inputHandler;
+    private inputTarget;
+    private _focused;
+    constructor(tui: TUI, theme: Theme, keybindings: KeybindingsManager);
+    get focused(): boolean;
+    set focused(value: boolean);
+    private setContent;
+    menu(build: () => McpMenu, subscribe?: (listener: () => void) => () => void): Promise<string | undefined>;
+    status(title: string, message: string, onCancel?: () => void): void;
+    redirectUrl(title: string, authorizationUrl: string, signal: AbortSignal): Promise<string | undefined>;
+    handleInput(data: string): void;
+    render(width: number): string[];
+    invalidate(): void;
+}
+/** Run `manage` in the manager view until it returns. */
+export declare function showMcpManager(ctx: ExtensionCommandContext, manage: (ui: McpUi) => Promise<void>): Promise<void>;

package/dist/extensions/mcp/ui.js

@@ -0,0 +1,185 @@
+/**
+ * The `/mcp` manager view: menus that rebuild while servers connect, a read-only status screen, and
+ * the sign-in screen that accepts a pasted redirect URL.
+ */
+import { Container, Input, SelectList, Spacer, Text, truncateToWidth, visibleWidth, } from "@earendil-works/pi-tui";
+import { AuthUrlComponent } from "../../modes/interactive/components/auth-url.js";
+import { DynamicBorder } from "../../modes/interactive/components/dynamic-border.js";
+import { keyHint } from "../../modes/interactive/components/keybinding-hints.js";
+import { getSelectListTheme } from "../../modes/interactive/theme/theme.js";
+function frame(theme, title, body, footer) {
+    const container = new Container();
+    container.addChild(new DynamicBorder((text) => theme.fg("accent", text)));
+    container.addChild(new Text(theme.fg("accent", theme.bold(title)), 1, 0));
+    for (const child of body)
+        container.addChild(child);
+    if (footer) {
+        container.addChild(new Spacer(1));
+        container.addChild(new Text(theme.fg("dim", footer), 1, 0));
+    }
+    container.addChild(new DynamicBorder((text) => theme.fg("accent", text)));
+    return container;
+}
+const MAX_VISIBLE_ITEMS = 12;
+export class McpManagerView {
+    tui;
+    theme;
+    keybindings;
+    content;
+    inputHandler;
+    inputTarget;
+    _focused = false;
+    constructor(tui, theme, keybindings) {
+        this.tui = tui;
+        this.theme = theme;
+        this.keybindings = keybindings;
+        this.content = frame(theme, "MCP servers", [new Text(theme.fg("muted", "Loading…"), 1, 1)]);
+    }
+    get focused() {
+        return this._focused;
+    }
+    set focused(value) {
+        this._focused = value;
+        if (this.inputTarget)
+            this.inputTarget.focused = value;
+    }
+    setContent(content, inputHandler, inputTarget) {
+        if (this.inputTarget)
+            this.inputTarget.focused = false;
+        this.content = content;
+        this.inputHandler = inputHandler;
+        this.inputTarget = inputTarget;
+        if (this.inputTarget)
+            this.inputTarget.focused = this._focused;
+        this.tui.requestRender();
+    }
+    menu(build, subscribe) {
+        return new Promise((resolve) => {
+            let unsubscribe;
+            let settled = false;
+            const finish = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                unsubscribe?.();
+                resolve(value);
+            };
+            let selected;
+            const render = () => {
+                const menu = build();
+                const wanted = selected ?? menu.selected;
+                const body = [];
+                if (menu.details)
+                    body.push(new Text(this.theme.fg("muted", menu.details), 1, 0));
+                if (menu.error)
+                    body.push(new Text(this.theme.fg("error", menu.error), 1, 0));
+                body.push(new Spacer(1));
+                const footer = `${keyHint("tui.select.confirm", menu.confirmLabel)} • ${keyHint("tui.select.cancel", menu.cancelLabel)}`;
+                if (menu.items.length === 0) {
+                    body.push(new Text(this.theme.fg("muted", menu.empty ?? "Nothing to show."), 1, 0));
+                    this.setContent(frame(this.theme, menu.title, body, keyHint("tui.select.cancel", menu.cancelLabel)), (data) => {
+                        if (this.keybindings.matches(data, "tui.select.cancel"))
+                            finish(undefined);
+                    });
+                    return;
+                }
+                const list = new SelectList(menu.items, Math.min(menu.items.length, MAX_VISIBLE_ITEMS), getSelectListTheme());
+                const index = menu.items.findIndex((item) => item.value === wanted);
+                if (index !== -1)
+                    list.setSelectedIndex(index);
+                selected = list.getSelectedItem()?.value;
+                list.onSelectionChange = (item) => {
+                    selected = item.value;
+                };
+                list.onSelect = (item) => finish(item.value);
+                list.onCancel = () => finish(undefined);
+                body.push(list);
+                this.setContent(frame(this.theme, menu.title, body, footer), (data) => list.handleInput(data));
+            };
+            render();
+            unsubscribe = subscribe?.(() => {
+                if (!settled)
+                    render();
+            });
+        });
+    }
+    status(title, message, onCancel) {
+        const body = [new Spacer(1), new Text(this.theme.fg("muted", message), 1, 0)];
+        if (!onCancel) {
+            this.setContent(frame(this.theme, title, body));
+            return;
+        }
+        this.setContent(frame(this.theme, title, body, keyHint("tui.select.cancel", "cancel")), (data) => {
+            if (this.keybindings.matches(data, "tui.select.cancel"))
+                onCancel();
+        });
+    }
+    redirectUrl(title, authorizationUrl, signal) {
+        return new Promise((resolve) => {
+            let settled = false;
+            const finish = (value) => {
+                if (settled)
+                    return;
+                settled = true;
+                signal.removeEventListener("abort", onAbort);
+                resolve(value);
+            };
+            const onAbort = () => finish(undefined);
+            if (signal.aborted) {
+                finish(undefined);
+                return;
+            }
+            signal.addEventListener("abort", onAbort, { once: true });
+            const input = new Input();
+            const link = new AuthUrlComponent(this.tui, authorizationUrl);
+            const body = [
+                new Spacer(1),
+                new Text(this.theme.fg("muted", "Approve access in your browser. If it did not open, visit:"), 1, 0),
+                link,
+                new Spacer(1),
+                new Text(this.theme.fg("muted", "If the browser runs on another machine, paste the URL it was redirected to:"), 1, 0),
+                input,
+            ];
+            this.setContent(frame(this.theme, title, body, `${keyHint("tui.select.confirm", "submit")} • ${keyHint("tui.select.cancel", "cancel")}`), (data) => {
+                if (this.keybindings.matches(data, "tui.select.confirm")) {
+                    const value = input.getValue().trim();
+                    if (value)
+                        finish(value);
+                    return;
+                }
+                if (this.keybindings.matches(data, "tui.select.cancel")) {
+                    finish(undefined);
+                    return;
+                }
+                if (this.keybindings.matches(data, "app.message.copy")) {
+                    void link.copy();
+                    return;
+                }
+                input.handleInput(data);
+            }, input);
+        });
+    }
+    handleInput(data) {
+        this.inputHandler?.(data);
+        this.tui.requestRender();
+    }
+    render(width) {
+        return this.content
+            .render(width)
+            .map((line) => (visibleWidth(line) > width ? truncateToWidth(line, width, "") : line));
+    }
+    invalidate() {
+        this.content.invalidate();
+    }
+}
+/** Run `manage` in the manager view until it returns. */
+export async function showMcpManager(ctx, manage) {
+    await ctx.ui.custom((tui, theme, keybindings, done) => {
+        const view = new McpManagerView(tui, theme, keybindings);
+        void manage(view).then(() => done(), (error) => {
+            ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+            done();
+        });
+        return view;
+    });
+}

package/dist/extensions/package.json

@@ -29,7 +29,7 @@
 			"./pi-tool-display",
 			"./pi-hermes-memory",
 			"./tps.ts",
-			"./capability-gateway",
+			"./skills-index",
 			"./pi-zentui/extensions/zentui/index.ts"
 		]
 	}

package/dist/extensions/pi-graft/tools.ts

@@ -128,6 +128,7 @@ export function registerGraftTools(pi: ExtensionAPI, runtime: GraftToolRuntime):
 	const scoped = (explicit: string | undefined): string | undefined => explicit ?? runtime.settings().in;
 
 	pi.registerTool({
+		exposure: "direct",
 		name: "graft_find_code",
 		label: "Graft: find code",
 		description:
@@ -172,6 +173,7 @@ export function registerGraftTools(pi: ExtensionAPI, runtime: GraftToolRuntime):
 	});
 
 	pi.registerTool({
+		exposure: "direct",
 		name: "graft_file_api",
 		label: "Graft: file API",
 		description:
@@ -197,6 +199,7 @@ export function registerGraftTools(pi: ExtensionAPI, runtime: GraftToolRuntime):
 	});
 
 	pi.registerTool({
+		exposure: "direct",
 		name: "graft_trace_calls",
 		label: "Graft: trace calls",
 		description:
@@ -240,6 +243,7 @@ export function registerGraftTools(pi: ExtensionAPI, runtime: GraftToolRuntime):
 	});
 
 	pi.registerTool({
+		exposure: "direct",
 		name: "graft_find_all",
 		label: "Graft: find all",
 		description:
@@ -278,6 +282,7 @@ export function registerGraftTools(pi: ExtensionAPI, runtime: GraftToolRuntime):
 	});
 
 	pi.registerTool({
+		exposure: "direct",
 		name: "graft_repo_map",
 		label: "Graft: repo map",
 		description:
@@ -303,6 +308,7 @@ export function registerGraftTools(pi: ExtensionAPI, runtime: GraftToolRuntime):
 	});
 
 	pi.registerTool({
+		exposure: "direct",
 		name: "graft_check_freshness",
 		label: "Graft: check freshness",
 		description:

package/dist/extensions/pi-hermes-memory/CHANGELOG.md

@@ -7,8 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **Opt-in chunked subprocess consolidation** (`consolidationChunking`, default `false`): stores above `consolidationChunkChars` (new, default `4000`) consolidate in bounded rounds — a head slice of entries per child run, reloading from disk between rounds, so a killed run resumes from partial progress instead of restarting. The rounds share one overall time budget (`consolidationTimeoutMs`, same worst case as the single call this replaces), the loop stops at the target's capacity goal (failure memory is a 2× tier and is no longer over-merged down to the slice size), a slice that cannot shrink is skipped rather than blocking later slices, A store that fits one prompt runs a single unscoped decisive round with the whole remaining store; a child exiting 0 without shrinking is reported as an honest partial instead of silent success, and an over-chunk store already within its capacity goal is a clean no-op. Partial runs report `partial: true` with the reason and are surfaced by the warning path, the store's add-retry error, and `/memory-consolidate`; disappearances outside a round's slice (rogue child deletions, legitimate cross-slice dedup, or concurrent writers — indistinguishable to the parent) are detected and reported rather than resurrected, because re-adding through the cap-enforcing add path cannot converge and resurrection ping-pongs across triggers. An over-chunk store already within its capacity goal is a clean no-op. Single-shot behavior below the threshold is unchanged.
+
 ### Added
 
+- **Usage-hit tracking — the promotion gate for consolidation** (`usageHitTrackingEnabled` / `consolidationUsageSignals`, both default `true`): `memory_search` now records a per-entry recall counter (`hit_count`) and last-recall date (`last_hit_at`), giving consolidation the usage signal neither the write nor the read path could see before — the prompt's "entries older than 30 days without recent references" rule finally has data behind it. Recording is one batched counter update per search and is invisible to search results, ranking, and prompts. Consolidation (direct and subprocess transports, auto and manual) appends a "Usage Signals" section listing the presented entries' recall counts — both halves capped at 20 lines (tracked entries ranked by hits descending, remainders folded into summary lines), framed as tie-breakers: well-recalled entries are load-bearing (prefer keep/merge), never-recalled entries are weaker keep candidates. The section only appears once at least one presented entry has actually been recalled, so stores without tracking history keep byte-identical prompts. `/memory-insights` gains a usage section (top-recalled entries, tracked/total counts). Counters live on the memory row itself — they die with the entry, need no pruning, and survive the legacy schema rebuild and corruption-recovery copies.
+
+- **One-time provider misconfiguration notice** ([#197](https://github.com/chandra447/pi-hermes-memory/issues/197)): when a review or consolidation completion comes back with an empty answer channel and the whole payload parked in the thinking channel, the extension logs a single warning per session naming the provider/model, explaining that a server-side thinking default is swallowing the answer and that the thinking-channel recovery is best-effort, and pointing the user to fix the provider (`Ask your Pi to fix this as well.`). Normal answers, redacted-only completions, and fully empty completions never trigger it.
+
 - **Opt-in memory lifecycle timings**: `PI_TIMING=1` now reports startup synchronization and loading, backfill and live-index callbacks, shutdown flush/index/wait/close, and database open/integrity-check/checkpoint durations. Normal runs produce no timing output.
 
 - **Opt-in SQLite session retention** ([#183](https://github.com/chandra447/pi-hermes-memory/issues/183)): new `sessionRetentionDays` setting (default `0`, disabled). When set to a positive value, sessions whose JSONL source file has not been updated within the window are pruned from SQLite at startup — rows only, the JSONL files themselves are never deleted — and both the deferred backfill and `/memory-index-sessions` skip files outside the window, so pruned sessions stay pruned instead of being re-indexed on every startup. With the default `0`, pruning is fully disabled and startup keeps the legacy count-only backfill preflight.
@@ -16,13 +24,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - **Natural-language search now filters common stop words** ([#184](https://github.com/chandra447/pi-hermes-memory/pull/184)): session and memory searches drop function words (`the`, `is`, `what`, …) before FTS5 matching, improving precision for natural-language queries. Intent-bearing words (`can`, `need`, `off`, `like`, `get`, …) are deliberately kept. A query made up entirely of stop words no longer returns an empty result — it degrades to a scoped literal substring search over the original terms.
+- **Startup markdown→SQLite reconcile is gated per scope** ([#227](https://github.com/chandra447/pi-hermes-memory/issues/227)): `session-start.persistence-sync` previously parsed every markdown file and re-upserted every entry into SQLite on every launch, measured at 2.1–7.2s on large stores. Each markdown scope now carries a fingerprint (`extension_metadata`, written in the same transaction as the reconcile), so an unchanged scope skips the per-entry SQL and an unchanged store's startup cost drops to a directory walk plus a few indexed reads per scope. The fingerprint binds markdown bytes and a row count, not the mirror's content, so mirror drift that preserves the count — a hand-edited row, or a search index that lost rows — now waits for a repair instead of being rewritten on every launch; `/memory-sync-markdown` is the forced full repair for both. New and deleted project dirs are still detected by the walk, and a corruption rebuild re-mirrors markdown exactly once.
+- **Compact flush runs on one shared window** ([#225](https://github.com/chandra447/pi-hermes-memory/issues/225)): the pre-compaction flush previously handed its full 30-second timeout to the direct transport and then again to the subprocess fallback, so a failing direct call re-sent the same large prompt to the subprocess and could spend ~60s saving nothing, silently. The flush now owns a single wall-clock window — new `flushCompactTimeoutMs` setting (default `60000`, raised from the hardcoded `30000`); the direct transport runs first and the subprocess receives only the remaining time. Escape still cancels immediately, and the shutdown flush keeps its own shorter silent cap.
+- **Skill discovery guidance now matches how Pi indexes skills** ([#244](https://github.com/chandra447/pi-hermes-memory/issues/244), [#249](https://github.com/chandra447/pi-hermes-memory/pull/249)): `skill_manage`'s parameter hints, tool description, one-shot example, and prompt guidelines had left the indexed `description` as a what-summary while the "when to use" text went into the body — where Pi never looks at discovery time, so a correct skill could silently never load. The guidance now states that `description` is the only indexed field, demonstrates trigger signals in the one-shot example, and keeps `when_to_use` for the expanded scenario and boundaries; the README section and example frontmatter teach the same rule. A behavioural canary (`tests/skill-discovery-contract.test.ts`) pins the index contract through Pi's public `loadSkills`/`formatSkillsForPrompt` API, so a change in how Pi indexes skills fails in CI instead of silently degrading discovery.
 
 ### Fixed
 
+- **Direct review works for providers with ambient credentials**: Pi resolves `amazon-bedrock` with an AWS profile or SSO session to request auth with no API key and no credential header, because the AWS SDK signs the request itself. The direct transport treated that as `no_auth`, so every review, flush, correction save, and consolidation fell back to the `pi -p` subprocess. The auth check now also accepts a provider that Pi reports as configured (`modelRegistry.hasConfiguredAuth`), the same check Pi runs before a prompt. OAuth providers that resolve to no credentials still report `no_auth`.
+
+- **Background memory jobs work on OpenCode** ([#250](https://github.com/chandra447/pi-hermes-memory/issues/250), reported by [@fallleave001](https://github.com/fallleave001)): the direct transport calls `completeSimple` itself, so it bypassed the session plumbing Pi applies to its own completions, and the OpenCode gateway rejected every review, flush, and correction-save completion with `400 missing_session_id` before the model was reached — losing the memory write, then spending an extra `pi -p` spawn on the fallback. The transport now sends `x-opencode-session` with the real Pi session id from `ctx.sessionManager.getSessionId()`, scoped per model to the `opencode` and `opencode-go` providers and to the `opencode.ai` host, alongside the `x-opencode-client` header Pi sends. Other providers are untouched, an operator-configured session header is never overwritten, and a missing session id degrades to the previous behaviour rather than throwing.
+
 - **FTS5 index errors during markdown sync are surfaced instead of hidden** ([#184](https://github.com/chandra447/pi-hermes-memory/pull/184)): when the FTS5 search index is broken, memory writes still succeed in Markdown, but the tool result and `/memory-sync-markdown` now report the degraded search state together with the repair command instead of showing a silent zero-count success. Genuine database corruption is unaffected by the fallback and now recovers through the markdown sync path too: reconciliation runs inside `DatabaseManager.withCorruptionRecovery()`, so a corrupt `sessions.db` is quarantined, rebuilt, and the sync retried instead of failing every memory write.
+- **A failed compact flush is now visible** ([#225](https://github.com/chandra447/pi-hermes-memory/issues/225)): when the flush cannot save before compaction — budget spent, child process killed by its watchdog, or a child error — the TUI shows one warning naming `flushCompactTimeoutMs` instead of failing silently. The watchdog-killed child path was invisible before. Setting `flushCompactTimeoutMs` to `0` or lower now skips the flush silently (an explicit disable, not a failure), and non-finite values fall back to the default.
 - **Rapid Markdown memory writes now reuse a recent recovery snapshot** ([#214](https://github.com/chandra447/pi-hermes-memory/issues/214)): successive overwrites within one hour publish atomically without creating another `.recovery-*` sidecar, while slower writes still take a fresh snapshot for crash recovery.
 - **Policy-only memory writes bypass the Markdown character cap** ([#218](https://github.com/chandra447/pi-hermes-memory/issues/218)): SQLite is the query authority in policy-only mode, so adds, replacements, and atomic mutation plans can exceed the Markdown export limit without triggering automatic consolidation. Legacy-inject mode keeps its existing caps, grace windows, auto-consolidation, failure limits, and FIFO eviction.
 
+- **Policy-only memory usage is reported as a count, not a percentage** ([#248](https://github.com/chandra447/pi-hermes-memory/issues/248), [#252](https://github.com/chandra447/pi-hermes-memory/pull/252), [#258](https://github.com/chandra447/pi-hermes-memory/pull/258)): policy-only mode intentionally does not apply the Markdown character cap, so a capacity percentage named a ceiling nothing was holding the store to — and, clamped at 100%, it read `100% — <count>/<limit> chars` on every write of an over-cap store. The write tool result and the rendered `MEMORY`, `USER PROFILE`, and `PROJECT MEMORY` headers now render `${current} chars` through one `usageLabel(current, limit)` helper gated on the same `capEnforced` predicate the write gates use, so the report and the gates cannot drift apart again; enforced modes keep the previous percentage strings byte-identical.
+
+- **The memory policy no longer forces the rendered system prompt** ([#251](https://github.com/chandra447/pi-hermes-memory/issues/251)): `before_agent_start` returned a full `systemPrompt`, which Pi documents as replacing the complete prompt for the turn, so the structured sections were flattened into opaque text — a section-aware extension (`pi-doppelclaude` rewrites the named sections and refuses to send when its wording survives) or provider lost the sections it keys on, and its guard fired on every turn. The policy now appends through the structured prompt options, which Pi re-renders from on 0.86+; 0.80.6–0.85.x keep the previous replacement path, because there the session applies only a returned `systemPrompt` and never reads the options back.
+- **Corruption rebuilds no longer carry markdown-scope fingerprints** ([#227](https://github.com/chandra447/pi-hermes-memory/issues/227)): the recovery copies coerce invalid values instead of dropping rows, so a copied fingerprint could agree with coerced rows while content drifted; a rebuilt database now re-mirrors markdown exactly once instead of trusting copied fingerprints.
+
 - **SQLite open integrity scans can be disabled** ([#194](https://github.com/chandra447/pi-hermes-memory/issues/194)): set `quickCheckOnOpen` to `false` to skip the asynchronous startup `PRAGMA quick_check`; operation-time corruption recovery remains enabled.
 
 ### Fixed
@@ -37,6 +58,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **`memory_search` ranks by relevance instead of recency** ([#118](https://github.com/chandra447/pi-hermes-memory/pull/118)): FTS5 matches were ordered by `last_referenced DESC` alone, so a long note that mentions a query term once outranked a short memory that is entirely about it, purely because it had been touched more recently. The match now joins `memory_fts` and orders by `bm25(memory_fts)` ascending with `last_referenced DESC` as the tie-break, so the densest match wins and recency only decides between equally relevant rows. Result *sets* are unchanged; only their order is.
 
+### Performance
+
+- **The process-incarnation probe no longer runs at extension load** ([#245](https://github.com/chandra447/pi-hermes-memory/issues/245)): `AtomicLockCoordinator` probed its own incarnation at module scope, so merely importing the module — which happens on every Pi launch, before any hermes code runs — paid a `spawnSync` for a lock most sessions never take. On Windows that is `powershell.exe`, measured at **515ms of the 2108ms** `pi-hermes-memory` module import (`PI_TIMING=1`, six extensions loaded). The probe is now memoized and deferred to the first coordinator construction; `AtomicLockCoordinator.shared()` already builds the coordinator on first lock use and the session-start path takes no lock, so the same profile drops to **1466ms** with no change in locking behavior. Separately, the 500ms `timeout` means the probe always returns `null` where PowerShell takes longer than that to start, which this change does not address.
+
 ## [0.9.4] - 2026-08-08
 
 ### Added