pi-ui-extend 1.0.35 → 1.0.37

package/README.md

@@ -401,6 +401,27 @@ Configurable areas include:
 
 Use `/settings` to inspect the effective settings summary and `/reload` after changing resources. Some command-driven settings update the relevant config file directly.
 
+### Ignoring legacy context files
+
+If a legacy project already contains an `AGENTS.md` or `CLAUDE.md` that should not be loaded, the simplest project-local workaround for both Pi and Pix is an empty override file in the same directory:
+
+```bash
+touch AGENTS.override.md
+```
+
+Pi and Pix load `AGENTS.override.md` instead of `AGENTS.md`/`CLAUDE.md` from that directory. To keep this local without changing the repository:
+
+```bash
+echo AGENTS.override.md >> .git/info/exclude
+```
+
+To disable discovery of all context files, including files in parent directories:
+
+- start Pi with `pi --no-context-files` (or `pi -nc`);
+- in Pix, run `/no-context-files on`. Pix saves `"ignoreContextFiles": true` to `<workspace>/.pi/pix.jsonc`.
+
+Start a new session or restart Pix after changing this setting. Use `/no-context-files off` to enable context-file loading again.
+
 ## Updates
 
 ```bash

package/dist/app/rendering/conversation-entry-renderer.js

@@ -28,10 +28,15 @@ export function renderConversationEntry(entry, width, options) {
         const lines = renderMarkdownTextLines(userEntry.text, userContentWidth, userContentLeft).map((line) => ({
             ...userLine(line.text, userEntry.id, line.syntaxHighlight, [
                 ...(line.segments ?? []),
+                ...diagramStyledSegments(line.diagramSegments, options.colors),
                 ...(line.links?.map((link) => ({ ...link, foreground: options.colors.info, underline: true })) ?? []),
             ], line.links),
             ...(line.copyText === undefined ? {} : { copyText: line.copyText }),
             ...(line.continuesOnNextLine ? { continuesOnNextLine: true } : {}),
+            ...(line.codeBlock ? {
+                colorOverride: options.colors.codeBlockForeground,
+                backgroundOverride: options.colors.codeBlockBackground,
+            } : {}),
         }));
         return attachImageClickTargets(lines, userEntry.id, userEntry.images, { foreground: options.colors.info, underline: true });
     };
@@ -94,13 +99,16 @@ function renderAssistantLines(text, width, options) {
         const existingSegments = line.segments?.map((segment) => ({ ...segment, start: segment.start + contentLeft, end: segment.end + contentLeft })) ?? [];
         const links = line.links?.map((link) => ({ ...link, start: link.start + contentLeft, end: link.end + contentLeft })) ?? [];
         const linkSegments = links.map((link) => ({ start: link.start, end: link.end, foreground: options.colors.info, underline: true }));
-        const allSegments = headingSegment ? [headingSegment, ...existingSegments, ...linkSegments] : [...existingSegments, ...linkSegments];
+        const diagramSegments = diagramStyledSegments(line.diagramSegments, options.colors, contentLeft);
+        const allSegments = headingSegment
+            ? [headingSegment, ...existingSegments, ...diagramSegments, ...linkSegments]
+            : [...existingSegments, ...diagramSegments, ...linkSegments];
         lines.push({
             text: padHorizontalText(line.text, width),
             ...(line.copyText === undefined ? {} : { copyText: line.copyText }),
             ...(line.continuesOnNextLine ? { continuesOnNextLine: true } : {}),
-            colorOverride: options.colors.assistantForeground,
-            backgroundOverride: options.colors.assistantMessageBackground,
+            colorOverride: line.codeBlock ? options.colors.codeBlockForeground : options.colors.assistantForeground,
+            backgroundOverride: line.codeBlock ? options.colors.codeBlockBackground : options.colors.assistantMessageBackground,
             ...(allSegments.length > 0 ? { segments: allSegments } : {}),
             ...(links.length > 0 ? { links } : {}),
             ...(line.syntaxHighlight ? { syntaxHighlight: line.syntaxHighlight } : {}),
@@ -108,3 +116,17 @@ function renderAssistantLines(text, width, options) {
     }
     return lines;
 }
+function diagramStyledSegments(segments, colors, offset = 0) {
+    return (segments ?? []).map((segment) => {
+        const range = { start: segment.start + offset, end: segment.end + offset };
+        switch (segment.class) {
+            case "border":
+            case "edgeLabel":
+                return { ...range, foreground: colors.muted };
+            case "edge":
+                return { ...range, foreground: colors.accent };
+            case "title":
+                return { ...range, foreground: colors.accent, bold: true };
+        }
+    });
+}

package/dist/markdown-format.d.ts

@@ -1,3 +1,4 @@
+import { type Cls as MermaidSpanClass } from "grok-mermaid";
 import { type SyntaxLineHighlight, type ToolBodySyntaxHighlights } from "./syntax-highlight.js";
 export type RenderedMarkdownLine = {
     text: string;
@@ -22,6 +23,7 @@ export type RenderedMarkdownTextLine = {
     text: string;
     copyText?: string;
     continuesOnNextLine?: boolean;
+    codeBlock?: true;
     segments?: readonly {
         start: number;
         end: number;
@@ -29,8 +31,14 @@ export type RenderedMarkdownTextLine = {
     }[] | undefined;
     links?: readonly RenderedMarkdownLink[] | undefined;
     syntaxHighlight?: SyntaxLineHighlight | undefined;
+    diagramSegments?: readonly RenderedMarkdownDiagramSegment[] | undefined;
     heading?: boolean;
 };
+export type RenderedMarkdownDiagramSegment = {
+    start: number;
+    end: number;
+    class: Exclude<MermaidSpanClass, "none" | "text">;
+};
 export type RenderMarkdownTextLinesOptions = {
     preserveWrappedWordSeparator?: boolean;
 };

package/dist/markdown-format.js

@@ -1,6 +1,12 @@
+import { render as renderMermaid } from "grok-mermaid";
 import { displayGraphemes, expandTabs, stringDisplayWidth } from "./terminal-width.js";
 import { syntaxHighlightLanguageForMarkdownFence, } from "./syntax-highlight.js";
 const MIN_TRAILING_WORD_WIDTH_TO_REBALANCE = 5;
+const MERMAID_CACHE_LIMIT = 100;
+const MERMAID_MAX_PANELS = 4;
+const MERMAID_MIN_PANEL_WIDTH = 40;
+const MERMAID_SEQUENCE_MESSAGE_OPERATORS = ["-->>", "->>", "--x", "-x", "--)", "-)", "-->", "->"];
+const mermaidRenderCache = new Map();
 export function formatMarkdownTables(text, maxWidth) {
     const lines = text.split("\n");
     const formatted = [];
@@ -85,14 +91,40 @@ export function renderMarkdownLine(text, start = 0) {
 export function renderMarkdownTextLines(text, width, start = 0, options = {}) {
     const lines = [];
     let fence;
+    let fenceHasBodyLine = false;
     const formattedText = formatMarkdownTables(sanitizeMarkdownText(text), width);
     if (formattedText.length === 0)
         return [];
-    for (const rawLine of formattedText.split("\n")) {
+    const rawLines = formattedText.split("\n");
+    for (let lineIndex = 0; lineIndex < rawLines.length;) {
+        const rawLine = rawLines[lineIndex] ?? "";
         const nextFence = markdownFence(rawLine);
+        if (!fence && nextFence && isMermaidFence(nextFence)) {
+            const diagram = renderMermaidBlock(rawLines, lineIndex, nextFence, width);
+            if (diagram) {
+                lines.push(...diagram.lines);
+                lineIndex = diagram.nextLineIndex;
+                continue;
+            }
+        }
         const closesFence = Boolean(fence && nextFence && fence.marker === nextFence.marker && nextFence.length >= fence.length);
         const opensFence = !fence && nextFence !== undefined;
-        const syntaxHighlight = markdownLineSyntaxHighlight(fence, Boolean(opensFence || closesFence), start);
+        if (opensFence && nextFence) {
+            fence = { ...nextFence, language: syntaxHighlightLanguageForMarkdownFence(nextFence.info) };
+            fenceHasBodyLine = false;
+            lineIndex += 1;
+            continue;
+        }
+        if (closesFence) {
+            if (!fenceHasBodyLine)
+                lines.push({ text: "", codeBlock: true });
+            fence = undefined;
+            fenceHasBodyLine = false;
+            lineIndex += 1;
+            continue;
+        }
+        const syntaxHighlight = markdownLineSyntaxHighlight(fence, false, start);
+        const codeBlock = fence !== undefined;
         const isHeadingLine = !fence && /^\s{0,3}#{1,6}\s/.test(rawLine);
         const markdownLine = syntaxHighlight?.language === "markdown" || isHeadingLine ? renderMarkdownLine(rawLine) : undefined;
         const logicalLine = markdownLine ?? { text: rawLine, segments: [], links: [] };
@@ -113,21 +145,245 @@ export function renderMarkdownTextLines(text, width, start = 0, options = {}) {
                 text: wrapped.text,
                 ...(wrapped.copyText === undefined ? {} : { copyText: wrapped.copyText }),
                 ...(wrapped.continuesOnNextLine ? { continuesOnNextLine: true } : {}),
+                ...(codeBlock ? { codeBlock: true } : {}),
                 ...(wrapped.segments.length > 0 ? { segments: wrapped.segments } : {}),
                 ...(wrapped.links && wrapped.links.length > 0 ? { links: wrapped.links } : {}),
                 ...(wrappedSyntaxHighlight ? { syntaxHighlight: wrappedSyntaxHighlight } : {}),
                 ...(isHeadingLine ? { heading: true } : {}),
             });
         }
-        if (opensFence && nextFence) {
-            fence = { ...nextFence, language: syntaxHighlightLanguageForMarkdownFence(nextFence.info) };
+        if (codeBlock)
+            fenceHasBodyLine = true;
+        lineIndex += 1;
+    }
+    if (fence && !fenceHasBodyLine)
+        lines.push({ text: "", codeBlock: true });
+    return lines;
+}
+function renderMermaidBlock(rawLines, openingLineIndex, openingFence, width) {
+    let closingLineIndex;
+    for (let index = openingLineIndex + 1; index < rawLines.length; index += 1) {
+        const candidate = markdownFence(rawLines[index] ?? "");
+        if (candidate && candidate.marker === openingFence.marker && candidate.length >= openingFence.length) {
+            closingLineIndex = index;
+            break;
         }
-        else if (closesFence) {
-            fence = undefined;
+    }
+    const sourceEnd = closingLineIndex ?? rawLines.length;
+    const source = rawLines.slice(openingLineIndex + 1, sourceEnd).join("\n");
+    let art = cachedMermaidRender(source);
+    if (!art)
+        return undefined;
+    const availableWidth = Math.max(1, width);
+    let participantLegend = [];
+    let messageLegend = [];
+    if (art.width > availableWidth) {
+        const compactSequence = compactMermaidSequence(source);
+        if (compactSequence) {
+            const compactArt = cachedMermaidRender(compactSequence.source);
+            if (compactArt && compactArt.width < art.width) {
+                art = compactArt;
+                participantLegend = compactSequence.participantLegend;
+                messageLegend = compactSequence.messageLegend;
+            }
+        }
+    }
+    const panelStarts = mermaidPanelStarts(art.width, availableWidth);
+    if (panelStarts.length > 1 && (availableWidth < MERMAID_MIN_PANEL_WIDTH || panelStarts.length > MERMAID_MAX_PANELS)) {
+        return undefined;
+    }
+    return {
+        lines: [
+            ...mermaidArtLines(art, availableWidth, panelStarts),
+            ...mermaidLegendLines("Participants", participantLegend, availableWidth),
+            ...mermaidLegendLines("Messages", messageLegend, availableWidth),
+        ],
+        nextLineIndex: closingLineIndex === undefined ? rawLines.length : closingLineIndex + 1,
+    };
+}
+function compactMermaidSequence(source) {
+    const lines = source.split("\n");
+    const header = lines.find((line) => line.trim().length > 0 && !line.trimStart().startsWith("%%"));
+    if (!header || !/^sequenceDiagram\s*$/iu.test(header.trim()))
+        return undefined;
+    const participantLegend = [];
+    const messageLegend = [];
+    const autonumber = lines.some((line) => /^\s*autonumber(?:\s|$)/iu.test(line));
+    let participantNumber = 0;
+    let messageNumber = 0;
+    const compactLines = lines.map((line) => {
+        const match = /^(\s*)(participant|actor)\s+(\S+?)(?:\s+as\s+(.+?))?\s*$/iu.exec(line);
+        if (match) {
+            const [, indent = "", declaration = "participant", id = "", rawLabel] = match;
+            participantNumber += 1;
+            const marker = `P${participantNumber}`;
+            const label = rawLabel ? normalizeMermaidLegendLabel(rawLabel) : id;
+            participantLegend.push(`${marker} (${id}) — ${label}`);
+            return `${indent}${declaration} ${id} as ${marker}`;
+        }
+        const message = mermaidSequenceMessage(line);
+        if (!message)
+            return line;
+        messageNumber += 1;
+        if (message.label.length === 0)
+            return line;
+        messageLegend.push(`${messageNumber}. ${normalizeMermaidLegendLabel(message.label)}`);
+        return autonumber ? message.prefix : `${message.prefix}: [${messageNumber}]`;
+    });
+    return participantLegend.length > 0 || messageLegend.length > 0
+        ? { source: compactLines.join("\n"), participantLegend, messageLegend }
+        : undefined;
+}
+function mermaidSequenceMessage(line) {
+    for (const operator of MERMAID_SEQUENCE_MESSAGE_OPERATORS) {
+        const operatorIndex = line.indexOf(operator);
+        if (operatorIndex < 0)
+            continue;
+        const colonIndex = line.indexOf(":", operatorIndex + operator.length);
+        const targetEnd = colonIndex < 0 ? line.length : colonIndex;
+        const from = line.slice(0, operatorIndex).trim();
+        const to = line.slice(operatorIndex + operator.length, targetEnd).trim();
+        if (!from || !to || /\s/u.test(from) || /\s/u.test(to))
+            return undefined;
+        return {
+            prefix: line.slice(0, targetEnd).trimEnd(),
+            label: colonIndex < 0 ? "" : line.slice(colonIndex + 1).trim(),
+        };
+    }
+    return undefined;
+}
+function normalizeMermaidLegendLabel(label) {
+    const normalized = label
+        .replace(/<br\s*\/?\s*>/giu, " ")
+        .replace(/<\/?[A-Za-z][^>]*>/gu, "")
+        .replace(/^(?:"([\s\S]*)"|'([\s\S]*)')$/u, "$1$2")
+        .trim();
+    return normalized || label.trim();
+}
+function mermaidPanelStarts(artWidth, panelWidth) {
+    if (artWidth <= panelWidth)
+        return [0];
+    const overlap = Math.min(24, Math.max(8, Math.floor(panelWidth / 5)));
+    const stride = Math.max(1, panelWidth - overlap);
+    const panelCount = 1 + Math.ceil((artWidth - panelWidth) / stride);
+    return Array.from({ length: panelCount }, (_, index) => Math.min(index * stride, artWidth - panelWidth));
+}
+function mermaidArtLines(art, width, panelStarts) {
+    if (panelStarts.length === 1) {
+        return art.plain.map((text, rowIndex) => {
+            const diagramSegments = mermaidDiagramSegments(text, art.styled[rowIndex] ?? []);
+            return { text, ...(diagramSegments.length > 0 ? { diagramSegments } : {}) };
+        });
+    }
+    const lines = [];
+    for (const [panelIndex, startColumn] of panelStarts.entries()) {
+        const continuesLeft = startColumn > 0;
+        const continuesRight = startColumn + width < art.width;
+        const title = `Mermaid ${panelIndex + 1}/${panelStarts.length}${continuesLeft ? " ←" : ""}${continuesRight ? " →" : ""}`;
+        lines.push({
+            text: title,
+            diagramSegments: [{ start: 0, end: title.length, class: "title" }],
+        });
+        for (const [rowIndex, text] of art.plain.entries()) {
+            lines.push(sliceMermaidDiagramRow(text, art.styled[rowIndex] ?? [], startColumn, width));
+        }
+    }
+    return lines;
+}
+function mermaidLegendLines(title, entries, width) {
+    if (entries.length === 0)
+        return [];
+    const lines = [{
+            text: title,
+            diagramSegments: [{ start: 0, end: title.length, class: "title" }],
+        }];
+    for (const entry of entries) {
+        for (const wrapped of wrapRenderedMarkdownLine({ text: entry, segments: [], links: [] }, width, {})) {
+            lines.push({
+                text: wrapped.text,
+                ...(wrapped.continuesOnNextLine ? { continuesOnNextLine: true } : {}),
+            });
         }
     }
     return lines;
 }
+function sliceMermaidDiagramRow(text, spans, startColumn, width) {
+    const endColumn = startColumn + width;
+    const diagramSegments = [];
+    let result = "";
+    let column = 0;
+    let spanIndex = 0;
+    let spanEnd = spans[0]?.text.length ?? 0;
+    for (const grapheme of displayGraphemes(text)) {
+        const nextColumn = column + grapheme.width;
+        if (nextColumn <= startColumn) {
+            column = nextColumn;
+            continue;
+        }
+        if (column >= endColumn)
+            break;
+        while (spanIndex < spans.length - 1 && grapheme.start >= spanEnd) {
+            spanIndex += 1;
+            spanEnd += spans[spanIndex]?.text.length ?? 0;
+        }
+        const fullyVisible = column >= startColumn && nextColumn <= endColumn;
+        const chunk = fullyVisible
+            ? grapheme.text
+            : " ".repeat(Math.max(0, Math.min(nextColumn, endColumn) - Math.max(column, startColumn)));
+        const chunkStart = result.length;
+        result += chunk;
+        const spanClass = spans[spanIndex]?.cls;
+        if (fullyVisible && spanClass && spanClass !== "none" && spanClass !== "text") {
+            const previous = diagramSegments.at(-1);
+            if (previous && previous.class === spanClass && previous.end === chunkStart) {
+                previous.end = result.length;
+            }
+            else {
+                diagramSegments.push({ start: chunkStart, end: result.length, class: spanClass });
+            }
+        }
+        column = nextColumn;
+    }
+    return { text: result, ...(diagramSegments.length > 0 ? { diagramSegments } : {}) };
+}
+function cachedMermaidRender(source) {
+    if (mermaidRenderCache.has(source)) {
+        const cached = mermaidRenderCache.get(source) ?? null;
+        mermaidRenderCache.delete(source);
+        mermaidRenderCache.set(source, cached);
+        return cached;
+    }
+    let art;
+    try {
+        art = renderMermaid(source.replace(/<br\s*\/?\s*>/giu, " "));
+    }
+    catch {
+        art = null;
+    }
+    mermaidRenderCache.set(source, art);
+    if (mermaidRenderCache.size > MERMAID_CACHE_LIMIT) {
+        const oldestKey = mermaidRenderCache.keys().next().value;
+        if (oldestKey !== undefined)
+            mermaidRenderCache.delete(oldestKey);
+    }
+    return art;
+}
+function mermaidDiagramSegments(text, spans) {
+    const segments = [];
+    let start = 0;
+    for (const span of spans) {
+        const end = start + span.text.length;
+        if (start < text.length && span.cls !== "none" && span.cls !== "text") {
+            segments.push({ start, end: Math.min(end, text.length), class: span.cls });
+        }
+        start = end;
+    }
+    return segments;
+}
+function isMermaidFence(fence) {
+    const token = fence.info.trim().split(/\s+/, 1)[0]?.toLowerCase().replace(/^[{.]+|[}.]+$/gu, "") ?? "";
+    return token === "mermaid";
+}
 export function markdownSyntaxHighlightsForText(text, startColumn = 0) {
     const highlights = [];
     let fence;

package/dist/theme.d.ts

@@ -18,6 +18,8 @@ export type Theme = {
         assistantMessageBackground: string;
         userMessageBackground: string;
         thinkingMessageBackground: string;
+        codeBlockForeground: string;
+        codeBlockBackground: string;
         inputCursorBackground: string;
         popupForeground: string;
         popupBackground: string;

package/dist/theme.js

@@ -19,6 +19,8 @@ export const THEMES = {
             assistantMessageBackground: "",
             userMessageBackground: "",
             thinkingMessageBackground: "",
+            codeBlockForeground: "#e6edf3",
+            codeBlockBackground: "#2a2f36",
             inputCursorBackground: "#7fb3c8",
             popupForeground: "#e6edf3",
             popupBackground: "#1e1e1e",
@@ -75,6 +77,8 @@ export const THEMES = {
             assistantMessageBackground: "",
             userMessageBackground: "",
             thinkingMessageBackground: "",
+            codeBlockForeground: "#0f172a",
+            codeBlockBackground: "#f1f5f9",
             inputCursorBackground: "#0284c7",
             popupForeground: "#0f172a",
             popupBackground: "#ffffff",

package/external/pi-tools-suite/README.md

@@ -11,6 +11,7 @@ This package keeps shared Pi tools as ordinary source folders under `src/` and r
 - `src/lsp` — shared LSP diagnostics hook/library that enriches mutating tool results with diagnostics and shuts down language servers on session shutdown
 - `src/comment-checker` — AI-slop comment guard that listens to the `tool_result` event for `write` / `edit` / `apply_patch` mutations, extracts net-new code comment lines, classifies them (filler phrasing, restating code, decorative separators, generic paraphrasing, or — under aggressive strictness — any non-valuable comment), and appends a short nudge to the tool result so the agent removes unnecessary comments on its next turn; TODO/FIXME, license headers, docstrings, pragmas, linter directives, shebangs, and decorators are never flagged; language-agnostic across `//` / `/* */` / `#` / `--` / `<!-- -->` / triple-quote comment styles; per-session deduplication (at most one nudge per 30 s) prevents fix/remark loops; configured via the `commentChecker` section (`enabled`, `strictness`: `conservative` | `balanced` | `aggressive`, default `balanced`) or `PI_COMMENT_CHECKER_ENABLED` / `PI_COMMENT_CHECKER_STRICTNESS`
 - `src/session-name` — `session_name` tool for reading or setting the current session title directly from tool calls, without relying on slash-command parsing
+- `src/session-recovery` — branch- and compaction-aware `session_overview`, `session_read_section`, `session_search`, and `session_recovery_context` tools for bounded recovery from Pi's raw append-only session history
 - `src/repo-discovery` — `/idx-init`, `/idx-update`, and indexed-only `repo_architecture` / `repo_structure` / `repo_ast` / `repo_search` / `repo_explain` / `repo_deps`; tools register only when the launch project has `.indexer-cli`
 - `src/antigravity-auth` — `antigravity` custom provider with Google Antigravity OAuth login, startup account list, auth.json-only runtime account loading, `/antigravity-add-account` OAuth append into rotation, `/antigravity-account` status display, account rotation/failover, Antigravity plus Gemini CLI model registration, and streaming through the Cloud Code Assist unified gateway
 - `src/opencode-import` — `/opencode-import` for bounded migration of supported OpenCode OpenAI/Codex, GitHub Copilot, Z.ai, and Antigravity credentials into Pi; existing entries are preserved unless `--force` is passed
@@ -24,7 +25,19 @@ This package keeps shared Pi tools as ordinary source folders under `src/` and r
 
 `index.ts` is intentionally only a thin auto-discovery shim that re-exports `src/index.ts`. There is no `pi.extensions` manifest here, so local Pi auto-discovery loads the suite once via `~/.pi/agent/extensions/pi-tools-suite/index.ts` and does not double-register tools.
 
-Registration order is preserved in `src/index.ts`: coding-discipline, ast-grep, async-subagents, lsp, comment-checker, session-name, repo-discovery command/tool gate, antigravity-auth provider, OpenCode import, todo, model-tools, usage, web-search, dcp, prompt-commands, skill-installer, credential-firewall, then codex-reasoning-fix. Tool metadata and active model-specific tool sets have two modes: standard and repo-aware. When `.indexer-cli` enables `repo_*`, those tools stay active ahead of overlapping lower-level aliases so the indexed discovery surface has priority.
+Registration order is preserved in `src/index.ts`: coding-discipline, ast-grep, async-subagents, lsp, comment-checker, session-name, session-recovery, repo-discovery command/tool gate, antigravity-auth provider, OpenCode import, todo, model-tools, usage, web-search, dcp, prompt-commands, skill-installer, credential-firewall, then codex-reasoning-fix. Tool metadata and active model-specific tool sets have two modes: standard and repo-aware. When `.indexer-cli` enables `repo_*`, those tools stay active ahead of overlapping lower-level aliases so the indexed discovery surface has priority.
+
+## Session recovery
+
+When context compaction obscures the task, start with `session_overview`, inspect a
+relevant ID with `session_read_section`, and use `session_search` once a concrete
+phrase, path, symbol, tool, or error is known. `session_recovery_context` is the
+compact convenience view for original/latest user instructions, file evidence,
+recent errors, pending calls, and the last meaningful action. All four tools read
+through Pi's active `SessionManager`; they do not accept arbitrary session paths.
+They default to the active branch, while `scope: "all"` includes abandoned branches.
+See [`docs/session-recovery.md`](docs/session-recovery.md) for the full contract and
+limits.
 
 ## Disabling modules
 

package/external/pi-tools-suite/docs/session-recovery.md

@@ -0,0 +1,84 @@
+# Session recovery tools
+
+Status: implemented MVP contract (semantic search is intentionally deferred).
+
+## Goal
+
+Let an agent recover the task, recent instructions, file activity, and useful raw
+session history after context compaction. Recovery reads the session already
+owned by Pi's `SessionManager`; it never opens an arbitrary session path.
+
+## Scope
+
+The `session-recovery` module registers four read-only, headless tools:
+
+- `session_overview` maps a session into stable, bounded sections.
+- `session_read_section` renders one section by ID.
+- `session_search` performs bounded lexical search over raw entries.
+- `session_recovery_context` summarizes deterministic recovery signals.
+
+Every tool defaults to the active root-to-leaf branch. `scope: "all"` includes
+abandoned branches through `SessionManager.getEntries()`. Both modes use raw
+append-only entries, not `buildContextEntries()`, so content hidden from the
+active model context by compaction remains discoverable.
+
+## Contracts
+
+### Sections
+
+A section starts at the first selected entry, a user message, a compaction, or a
+branch summary. Its stable ID is derived from the start entry ID. The overview
+reports bounded head and tail sections with entry ranges, counts, and compact
+role/tool/error/file statistics. Labels are previews, not inferred decisions.
+
+### Reading and search
+
+`session_read_section` requires a section ID produced for the same scope. It
+renders message roles and text, tool calls and arguments, tool results,
+compaction summaries, and branch summaries with per-entry and total output
+limits.
+
+`session_search` is case-insensitive by default and searches message text, tool
+arguments/results, custom-message content, and compaction or branch summaries.
+It returns entry and section IDs plus bounded snippets. Regex and semantic
+search are out of scope for the MVP.
+
+### Recovery context
+
+`session_recovery_context` reports only evidence that can be derived
+deterministically: the original and latest user messages, recent tool errors,
+unmatched tool calls, read and modified files, the last meaningful action, and
+compaction count. It calls errors `recentErrors`; it does not claim that they
+remain unresolved. It does not infer decisions. The currently executing
+recovery tool call is excluded from unmatched-call reporting.
+
+File activity comes from recognized tool calls and Pi-generated compaction or
+branch-summary details. Read and modified paths remain separate, and unknown
+tools are not guessed to be mutations.
+
+## Limits and edge cases
+
+- Results use small defaults and hard caps for result count, entry body size,
+  and total text size.
+- Empty or in-memory sessions return a normal explanatory result.
+- Unknown or partially shaped entries are ignored or rendered conservatively.
+- Concurrent sibling tool results might not yet be visible when recovery runs.
+- A section ID is stable while its start entry ID is stable, but scope changes
+  can change section membership.
+- Parent-session metadata is reported when Pi exposes it; parent files are not
+  traversed.
+
+## Verification
+
+Deterministic tests cover active versus all branches, raw pre-compaction search,
+stable section IDs, Unicode case-insensitive search, bounded output, empty
+sessions, current-call exclusion, recent errors, file carry-forward details,
+and conservative handling of unknown entries. Release verification runs the
+suite typecheck/tests/smoke gate, host `npm run check`, and then syncs the suite
+with `npm run sync:pi-tools-suite`.
+
+## Evidence
+
+Evidence is recorded by the implementation tests in
+`test/session-recovery.test.ts` and the verification commands reported with the
+change.

package/external/pi-tools-suite/src/index.ts

@@ -16,6 +16,7 @@ export const MODULES: Array<{ name: string; load: () => Promise<ExtensionModule>
 	{ name: "lsp", load: () => import("./lsp/index") },
 	{ name: "comment-checker", load: () => import("./comment-checker/index") },
 	{ name: "session-name", load: () => import("./session-name/index") },
+	{ name: "session-recovery", load: () => import("./session-recovery/index") },
 	{ name: "repo-discovery", load: () => import("./repo-discovery/index") },
 	{ name: "antigravity-auth", load: () => import("./antigravity-auth/index") },
 	{ name: "opencode-import", load: () => import("./opencode-import/index") },