pi-ast-sgrep 2.5.2 → 2.5.4

package/README.md

@@ -6,7 +6,9 @@ Native Code Mode, structural, graph, and semantic code search for [Pi](https://g
 
 `pi-ast-sgrep` gives Pi a warm, project-aware search engine for understanding code. It finds behavior by intent, resolves definitions and callers, traces relationships, matches syntax-aware patterns, joins two indexed channels, and searches local semantic embeddings. The primary `asgrep` tool lets Pi compose several searches in one JavaScript program instead of spending one model round trip per lookup.
 
-**v2.0.0** · 13 languages · local-first semantic · critic + two-channel `AND` · **Code Mode** (on by default, no API key)
+**v2.5.3** (native engine 2.5.2) · 15 languages · local-first semantic · critic + two-channel `AND` · **Code Mode** (on by default, no API key)
+
+**2.5.3 recovery fix:** Missing `ASGREP_BIN`/`AST_SGREP_BINARY` developer builds now fall back to the verified bundled binary with a warning. Explicit `binaryPath` settings and invalid binaries remain strict. `asgrep_read` works without a search backend or index, `/asgrep-doctor` reports component versions, and the launcher dependency now requires at least 2.5.2. Update with `pi update npm:pi-ast-sgrep`, then reload Pi.
 
 **Upgrading to 2.0:** this is a breaking semver release because the cloud/Ollama embedding backends were removed. Update the Pi package normally; local hashed semantic search remains the default, optional neural embeddings remain in-process, and indexes that still store `embed_backend=cloud|ollama` fail closed until `/asgrep-reindex`. One-shot tools and Code Mode now put bounded hits in `content` so the model sees them, not only display-only `details`.
 

package/dist/code-mode.js

@@ -1,5 +1,6 @@
 import { constants } from "node:fs";
-import { lstat, open, realpath } from "node:fs/promises";
+import { lstat, open } from "node:fs/promises";
+import { realpathUtf8 as realpath } from "./runtime/index-health.js";
 import { isAbsolute, relative, resolve, sep } from "node:path";
 import { RuntimeError } from "./runtime/runtime.js";
 const DEFAULT_LIMIT = 20;
@@ -179,7 +180,7 @@ async function readLineWindow(handle, parsed, contextLines, maxChars, signal) {
         throw new RuntimeError("READ_FAILED", `${parsed.file} is not a regular file`);
     const wantedStart = Math.max(1, parsed.start - contextLines);
     const wantedEnd = Math.min(MAX_LINE_NUMBER, parsed.end + contextLines);
-    const decoder = new TextDecoder("utf-8", { fatal: true });
+    const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
     const stream = handle.createReadStream({
         autoClose: false,
         highWaterMark: 64 * 1024,
@@ -195,20 +196,22 @@ async function readLineWindow(handle, parsed, contextLines, maxChars, signal) {
     let truncated = false;
     let rangeComplete = false;
     let scannedBytes = 0;
-    const consumeLine = (line) => {
-        if (lineNumber >= wantedStart && lineNumber <= wantedEnd) {
-            selectedStart ??= lineNumber;
-            selectedEnd = lineNumber;
-            if (!truncated) {
-                const rawLine = line.endsWith("\r") ? line.slice(0, -1) : line;
-                const clamped = rawLine.length > MAX_LINE_CHARS ? `${rawLine.slice(0, MAX_LINE_CHARS)}…` : rawLine;
-                const addition = `${selectedLines > 0 ? "\n" : ""}${clamped}`;
-                const bounded = boundedPrefix(addition, maxChars - contentChars);
+    const consumeLine = (line, terminated = false) => {
+        if (lineNumber >= wantedStart && lineNumber <= wantedEnd && !truncated) {
+            const rawLine = terminated && line.endsWith("\r") ? line.slice(0, -1) : line;
+            const clamped = boundedPrefix(rawLine, MAX_LINE_CHARS);
+            const addition = `${selectedLines > 0 ? "\n" : ""}${clamped.text}`;
+            const bounded = boundedPrefix(addition, maxChars - contentChars);
+            // Continue scanning to validate the requested range, but do not advance
+            // the returned ref/resume offset over text the caller never received.
+            if (bounded.text.length > 0 || addition.length === 0) {
+                selectedStart ??= lineNumber;
+                selectedEnd = lineNumber;
                 content += bounded.text;
                 contentChars += bounded.chars;
-                truncated = bounded.truncated;
+                selectedLines += 1;
             }
-            selectedLines += 1;
+            truncated = clamped.truncated || bounded.truncated;
         }
         if (lineNumber >= wantedEnd)
             rangeComplete = true;
@@ -231,7 +234,7 @@ async function readLineWindow(handle, parsed, contextLines, maxChars, signal) {
             }
             let newline = pending.indexOf("\n");
             while (newline >= 0) {
-                consumeLine(pending.slice(0, newline));
+                consumeLine(pending.slice(0, newline), true);
                 pending = pending.slice(newline + 1);
                 if (rangeComplete)
                     break;
@@ -252,7 +255,7 @@ async function readLineWindow(handle, parsed, contextLines, maxChars, signal) {
             catch {
                 throw new RuntimeError("BINARY_FILE", `${parsed.file} is not valid UTF-8 text`);
             }
-            if (pending.length > 0 || lineNumber === 1)
+            if (pending.length > 0)
                 consumeLine(pending);
         }
     }

package/dist/codemode/connector.d.ts

@@ -23,6 +23,12 @@ export type DispatchSurface = {
         signal?: AbortSignal;
     }): Promise<MachineEnvelope>;
 };
+type SymbolArgs = Omit<SearchArgs, "query"> & {
+    symbol: string;
+};
+type ImportArgs = Omit<SearchArgs, "query"> & {
+    module: string;
+};
 export type AsgrepConnector = {
     search(input: SearchArgs, options?: {
         signal?: AbortSignal;
@@ -42,25 +48,13 @@ export type AsgrepConnector = {
     chain(input: ChainArgs, options?: {
         signal?: AbortSignal;
     }): Promise<MachineEnvelope>;
-    defs(input: {
-        symbol: string;
-        limit?: number;
-        excerptLines?: number;
-    }, options?: {
+    defs(input: SymbolArgs, options?: {
         signal?: AbortSignal;
     }): Promise<MachineEnvelope>;
-    callers(input: {
-        symbol: string;
-        limit?: number;
-        excerptLines?: number;
-    }, options?: {
+    callers(input: SymbolArgs, options?: {
         signal?: AbortSignal;
     }): Promise<MachineEnvelope>;
-    imports(input: {
-        module: string;
-        limit?: number;
-        excerptLines?: number;
-    }, options?: {
+    imports(input: ImportArgs, options?: {
         signal?: AbortSignal;
     }): Promise<MachineEnvelope>;
     indexStatus(options?: {
@@ -104,4 +98,6 @@ export declare function createAsgrepConnector(host: BatchCapableHost, context: {
 }, options?: {
     signal?: AbortSignal;
     scope?: string;
+    localReads?: boolean;
 }): ConnectorBundle;
+export {};

package/dist/codemode/connector.js

@@ -1,3 +1,4 @@
+import { isAbsolute } from "node:path";
 import { argvFor, asEnvelope, createCodemodeDispatcher, } from "./dispatch.js";
 import { editFilesFallback, readWindowsFallback } from "./fallback.js";
 import { coerceHostArgs } from "./guest-api.js";
@@ -36,14 +37,25 @@ export function createAsgrepConnector(host, context, options = {}) {
         ? options.scope.replace(/^(?:\.\/)+/u, "").replace(/\/+$/u, "")
         : undefined;
     const rebasePath = (path) => {
-        if (!scope || path.startsWith("/") || path.startsWith("~"))
+        if (!scope || isAbsolute(path))
             return path;
         const clean = path.replace(/^(?:\.\/)+/u, "");
+        if (clean === scope || clean.startsWith(`${scope}/`))
+            return clean;
         return clean === "" || clean === "." ? scope : `${scope}/${clean}`;
     };
-    const rebaseRef = (ref) => {
-        const hash = ref.indexOf("#");
-        return hash === -1 ? rebasePath(ref) : rebasePath(ref.slice(0, hash)) + ref.slice(hash);
+    const rebaseReadSpec = (value) => {
+        // Refs emitted by search/read are already checkout-relative. Path-form
+        // requests may be cwd-relative, including objects inside refs[].
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return value;
+        const spec = value;
+        if (typeof spec.ref === "string")
+            return spec;
+        return { ...spec,
+            ...(typeof spec.path === "string" ? { path: rebasePath(spec.path) } : {}),
+            ...(typeof spec.file === "string" ? { file: rebasePath(spec.file) } : {}),
+        };
     };
     /** Directories below the checkout combine with the anchor scope, never replace it. */
     const withScope = (input) => {
@@ -80,6 +92,8 @@ export function createAsgrepConnector(host, context, options = {}) {
     };
     const call = async (tool, args, signal) => {
         const opts = callOptions(signal);
+        if (tool === "read" && options.localReads)
+            return fallbackCall(tool, args, opts.signal);
         if (NATIVE_FALLBACK_TOOLS.has(tool) && nativeMissing.has(tool))
             return fallbackCall(tool, args, opts.signal);
         try {
@@ -107,6 +121,15 @@ export function createAsgrepConnector(host, context, options = {}) {
             payload.lang = scoped.lang.trim();
         return payload;
     };
+    const symbolCall = (tool, input, signal) => {
+        const args = coerceHostArgs(tool, input);
+        const key = tool === "imports" ? "module" : "symbol";
+        if (scope || ["in", "fileFilter", "file_filter", "lang"].some(key => typeof args[key] === "string" && args[key].trim())) {
+            return call("search", searchPayload("search", { ...args, query: `${tool}:${args[key] ?? ""}` }), signal);
+        }
+        return call(tool, defined({ [key]: args[key], limit: clampLimit(args.limit),
+            excerpt_lines: clampExcerpt(args.excerptLines) }), signal);
+    };
     // Bound function properties (not methods) so vm call sites cannot lose `this`.
     const asgrep = {
         search: (input, callOptions) => call("search", searchPayload("search", input), callOptions?.signal),
@@ -115,8 +138,8 @@ export function createAsgrepConnector(host, context, options = {}) {
             path: typeof input.path === "string" ? rebasePath(input.path) : input.path,
             start: input.start,
             end: input.end,
-            ref: typeof input.ref === "string" ? rebaseRef(input.ref) : input.ref,
-            refs: Array.isArray(input.refs) ? input.refs.map((ref) => (typeof ref === "string" ? rebaseRef(ref) : ref)) : input.refs,
+            ref: input.ref,
+            refs: Array.isArray(input.refs) ? input.refs.map(rebaseReadSpec) : input.refs,
             context_lines: input.contextLines,
             max_chars: input.maxChars,
         }), callOptions?.signal),
@@ -137,28 +160,18 @@ export function createAsgrepConnector(host, context, options = {}) {
         },
         semantic: (input, callOptions) => call("semantic", searchPayload("semantic", input), callOptions?.signal),
         chain: (input, callOptions) => call("chain", { query: input.query, limit: clampLimit(input.limit), top_n: 20 }, callOptions?.signal),
-        defs: (input, callOptions) => {
-            const scoped = coerceHostArgs("defs", { ...input });
-            return call("defs", {
-                symbol: scoped.symbol,
-                limit: clampLimit(input.limit),
-                excerpt_lines: clampExcerpt(input.excerptLines),
-            }, callOptions?.signal);
-        },
-        callers: (input, callOptions) => {
-            const scoped = coerceHostArgs("callers", { ...input });
-            return call("callers", {
-                symbol: scoped.symbol,
-                limit: clampLimit(input.limit),
-                excerpt_lines: clampExcerpt(input.excerptLines),
-            }, callOptions?.signal);
-        },
-        imports: (input, callOptions) => call("imports", defined({ module: input.module, limit: clampLimit(input.limit), excerpt_lines: clampExcerpt(input.excerptLines) }), callOptions?.signal),
+        defs: (input, callOptions) => symbolCall("defs", input, callOptions?.signal),
+        callers: (input, callOptions) => symbolCall("callers", input, callOptions?.signal),
+        imports: (input, callOptions) => symbolCall("imports", input, callOptions?.signal),
         indexStatus: (callOptions) => call("index_status", {}, callOptions?.signal),
         indexRepo: (input = {}, callOptions) => call("index_repo", { force: input.force === true }, callOptions?.signal),
         catalogSearch: (input, callOptions) => call("catalog_search", { query: input.query }, callOptions?.signal),
         catalogDescribe: (input, callOptions) => call("catalog_describe", { name: input.name }, callOptions?.signal),
-        doctor: (callOptions) => host.run(["doctor", ".", "--json"], context, callOptions),
+        doctor: async (perCall) => {
+            const opts = callOptions(perCall?.signal);
+            opts.signal?.throwIfAborted();
+            return host.run(["doctor", ".", "--json"], context, opts);
+        },
     };
     return {
         asgrep,

package/dist/codemode/dispatch.d.ts

@@ -67,6 +67,7 @@ export type BatchCapableHost = ConnectorHost & {
     /** Sticky NDJSON worker for the whole Code Mode program (preferred). */
     sticky?: StickyWorker | null;
 };
+export declare const MUTATING_TOOLS: ReadonlySet<string>;
 /**
  * Wraps a host so Promise.all([asgrep.search, asgrep.defs, …]) collapses into
  * one microtask wave. Prefers sticky serve → one-shot batch → overlapped spawn.

package/dist/codemode/dispatch.js

@@ -16,7 +16,7 @@ function callTarget(args) {
     return text.length > 60 ? text.slice(0, 59) + "…" : text;
 }
 const MAX_WAVE = 32;
-const MUTATING_TOOLS = new Set(["index_repo", "edit"]);
+export const MUTATING_TOOLS = new Set(["index_repo", "edit"]);
 const abortError = () => Object.assign(new Error("codemode aborted"), { name: "AbortError" });
 function rejectWave(wave, cause) {
     for (const item of wave)

package/dist/codemode/fallback.d.ts

@@ -3,11 +3,9 @@
  *
  * Severed-lane contract: when native answers `unknown tool: <name>` for
  * read/edit/find, the connector serves the call here instead of failing, so
- * an extension tracking main keeps working on an official launcher. Every
- * shape, default, cap, jail rule, and error string mirrors
- * crates/ast-sgrep-codemode/src/io.rs exactly — callers cannot distinguish
- * this lane from a native one. Errors are plain Errors carrying the native
- * text (the native lane surfaces them the same way); no new error codes.
+ * an extension tracking main keeps working on an official launcher. Shapes,
+ * defaults, caps, and confinement follow crates/ast-sgrep-codemode/src/io.rs.
+ * Errors are plain Errors; adapter-specific filesystem messages can differ.
  *
  * Deliberate divergences from native, both strictly safer:
  * - Reads come from disk, never the index (the extension has no row reader

package/dist/codemode/fallback.js

@@ -3,11 +3,9 @@
  *
  * Severed-lane contract: when native answers `unknown tool: <name>` for
  * read/edit/find, the connector serves the call here instead of failing, so
- * an extension tracking main keeps working on an official launcher. Every
- * shape, default, cap, jail rule, and error string mirrors
- * crates/ast-sgrep-codemode/src/io.rs exactly — callers cannot distinguish
- * this lane from a native one. Errors are plain Errors carrying the native
- * text (the native lane surfaces them the same way); no new error codes.
+ * an extension tracking main keeps working on an official launcher. Shapes,
+ * defaults, caps, and confinement follow crates/ast-sgrep-codemode/src/io.rs.
+ * Errors are plain Errors; adapter-specific filesystem messages can differ.
  *
  * Deliberate divergences from native, both strictly safer:
  * - Reads come from disk, never the index (the extension has no row reader
@@ -15,9 +13,9 @@
  * - Edits skip the native targeted reindex. A fallback edit is exactly like
  *   an external editor write, which the freshness layer already reconciles.
  */
-import { readFile, realpath, writeFile } from "node:fs/promises";
-import { isAbsolute, join, relative } from "node:path";
-import { pathContained } from "../runtime/index-health.js";
+import { readFile, writeFile } from "node:fs/promises";
+import { isAbsolute, join, relative, sep } from "node:path";
+import { pathContained, realpathUtf8 as realpath } from "../runtime/index-health.js";
 // Native caps (crates/ast-sgrep-codemode/src/io.rs + core limits).
 const MAX_READ_REFS = 32;
 const MAX_READ_CHARS = 100_000;
@@ -26,6 +24,11 @@ const MAX_LINE_CHARS = 2_000;
 const MAX_INDEX_FILE_BYTES = 64 * 1024 * 1024;
 const MAX_EXCERPT_LINES = 100;
 const U32_MAX = 4_294_967_295;
+const editTails = new Map();
+function assertUnicode(text) {
+    if (Buffer.from(text, "utf8").toString("utf8") !== text)
+        throw new Error("invalid Unicode: unpaired UTF-16 surrogate");
+}
 /** Mirror serde as_u64 (integers only, then wrapping `as u32`). */
 function u32(value) {
     if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > Number.MAX_SAFE_INTEGER)
@@ -49,7 +52,7 @@ function present(args, ...keys) {
 function rustLines(text) {
     if (text === "")
         return [];
-    const lines = text.split("\n").map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line));
+    const lines = text.split("\n").map((line, index, all) => index < all.length - 1 && line.endsWith("\r") ? line.slice(0, -1) : line);
     if (text.endsWith("\n"))
         lines.pop();
     return lines;
@@ -70,6 +73,7 @@ async function jailRoot(configuredCwd, args) {
     const raw = args.root;
     if (typeof raw !== "string")
         return configured;
+    assertUnicode(raw);
     const candidate = isAbsolute(raw) ? raw : join(configured, raw);
     const resolved = await realpath(candidate).catch(() => {
         throw new Error(`cannot resolve requested root: ${candidate}`);
@@ -81,7 +85,8 @@ async function jailRoot(configuredCwd, args) {
 }
 /** Mirror jail_rel_path: explicit '..' rejection, canonicalize, containment. */
 async function jailPath(root, raw) {
-    if (raw.split(/[\\/]/u).includes(".."))
+    assertUnicode(raw);
+    if (raw.split(sep === "\\" ? /[\\/]/u : "/").includes(".."))
         throw new Error("path must not contain '..'");
     const candidate = isAbsolute(raw) ? raw : join(root, raw);
     const abs = await realpath(candidate).catch(() => {
@@ -89,7 +94,7 @@ async function jailPath(root, raw) {
     });
     if (!pathContained(root, abs))
         throw new Error(`path escapes session root: ${raw}`);
-    return { abs, display: relative(root, abs).replace(/\\/g, "/") };
+    return { abs, display: relative(root, abs).split(sep).join("/") };
 }
 function parseU32Strict(text) {
     const digits = /^(?:\+)?(\d+)$/.exec(text)?.[1];
@@ -127,9 +132,9 @@ function parseRefValue(value) {
     const path = present(obj, "path", "file");
     if (typeof path !== "string")
         throw new Error("ref.path is required");
-    const start = u32(present(obj, "start", "line_start")) ?? 1;
+    const start = Math.max(1, u32(present(obj, "start", "line_start")) ?? 1);
     const end = u32(present(obj, "end", "line_end")) ?? start;
-    return { path, start: Math.max(1, start), end: Math.max(start, end) };
+    return { path, start, end: Math.max(start, end) };
 }
 function collectRefs(args) {
     if (Array.isArray(args.refs))
@@ -139,9 +144,9 @@ function collectRefs(args) {
     const path = present(args, "path", "file");
     if (typeof path !== "string")
         throw new Error("path is required");
-    const start = u32(present(args, "start", "line_start")) ?? 1;
+    const start = Math.max(1, u32(present(args, "start", "line_start")) ?? 1);
     const end = u32(present(args, "end", "line_end")) ?? start;
-    return [{ path, start: Math.max(1, start), end: Math.max(start, end) }];
+    return [{ path, start, end: Math.max(start, end) }];
 }
 function sliceWindow(numbered, start, end, maxChars) {
     let out = "";
@@ -167,24 +172,33 @@ function sliceWindow(numbered, start, end, maxChars) {
             actualStart = no;
             first = false;
         }
-        if (out !== "")
+        else {
             out += "\n";
+        }
         out += line;
         actualEnd = no;
         chars += add;
     }
     if (first)
-        return { text: "", actualStart: start, actualEnd: start, truncated: false };
+        return { text: "", actualStart: start, actualEnd: start, truncated };
     return { text: out, actualStart, actualEnd, truncated };
 }
 async function readFileCapped(abs, display, signal) {
-    const text = await readFile(abs, "utf8").catch(() => {
+    const bytes = await readFile(abs, { signal }).catch(() => {
+        signal?.throwIfAborted();
         throw new Error(`cannot read ${display}`);
     });
-    if (Buffer.byteLength(text) > MAX_INDEX_FILE_BYTES)
+    if (bytes.length > MAX_INDEX_FILE_BYTES)
         throw new Error(`${display} exceeds max ${MAX_INDEX_FILE_BYTES} bytes`);
     signal?.throwIfAborted();
-    return text;
+    try {
+        // Match Rust's strict UTF-8 reads. Replacement decoding would corrupt bytes
+        // outside the requested edit; ignoreBOM retains a literal source BOM.
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        throw new Error(`cannot read ${display}: invalid UTF-8`);
+    }
 }
 /** Mirror read_windows (disk-backed; see module note). */
 export async function readWindowsFallback(configuredCwd, args, signal) {
@@ -232,6 +246,8 @@ function parseEditValue(value) {
         throw new Error("newText is required");
     if (oldText === "")
         throw new Error("oldText must not be empty");
+    assertUnicode(oldText);
+    assertUnicode(newText);
     return { path, oldText, newText };
 }
 function collectEdits(args) {
@@ -252,6 +268,21 @@ function matchLine(buffer, offset) {
 export async function editFilesFallback(configuredCwd, args, signal) {
     signal?.throwIfAborted();
     const root = await jailRoot(configuredCwd, args);
+    // Native mutations serialize per session. Fallbacks can be reached through
+    // different connectors, so their read/modify/write queue belongs here.
+    const operation = (editTails.get(root) ?? Promise.resolve()).then(() => applyEdits(root, args, signal));
+    const tail = operation.then(() => undefined, () => undefined);
+    editTails.set(root, tail);
+    try {
+        return await operation;
+    }
+    finally {
+        if (editTails.get(root) === tail)
+            editTails.delete(root);
+    }
+}
+async function applyEdits(root, args, signal) {
+    signal?.throwIfAborted();
     const edits = collectEdits(args);
     if (edits.length === 0)
         throw new Error("edit requires path+oldText+newText or edits[]");

package/dist/codemode/native.d.ts

@@ -13,7 +13,7 @@
  * generation (an ABI mismatch risks crashes, not errors). Older launchers
  * serve Code Mode over CLI sticky/batch/spawn instead — same tools, slower.
  */
-export declare const CODEMODE_BINDING_VERSION = "2.5.2";
+export declare const CODEMODE_BINDING_VERSION = "2.5.4";
 export type NativeSessionConfig = {
     root?: string;
     indexPath?: string;

package/dist/codemode/native.js

@@ -17,7 +17,7 @@ import { createRequire } from "node:module";
 import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-export const CODEMODE_BINDING_VERSION = "2.5.2";
+export const CODEMODE_BINDING_VERSION = "2.5.4";
 let cached;
 function platformTriple() {
     const { platform, arch } = process;
@@ -60,7 +60,7 @@ function candidatePaths() {
         join(here, "..", "..", "native"),
         join(here, "..", "native"),
         // Workspace release output
-        join(here, "..", "..", "..", "..", "target", "release"),
+        join(here, "..", "..", "..", "..", "..", "target", "release"),
     ];
     const cargoTarget = process.env.CARGO_TARGET_DIR;
     if (cargoTarget)

package/dist/codemode/session-pool.js

@@ -7,7 +7,7 @@
  * Fallback: sticky `codemode-serve` child only when the `.node` addon is missing
  * (unsupported host / incomplete install). Doctor reports that as degraded.
  */
-import { asEnvelope } from "./dispatch.js";
+import { asEnvelope, MUTATING_TOOLS } from "./dispatch.js";
 import { loadCodemodeNative } from "./native.js";
 import { defined } from "./types.js";
 import { startStickyWorker } from "./worker.js";
@@ -200,7 +200,7 @@ export class NativeSessionPool {
             return await worker.call(tool, args, options);
         }
         catch (cause) {
-            if (options?.signal?.aborted || !isClosedWorkerError(cause))
+            if (options?.signal?.aborted || MUTATING_TOOLS.has(tool) || !isClosedWorkerError(cause))
                 throw cause;
             await this.invalidate(root);
             const retry = await this.acquire(root);

package/dist/host/commands.js

@@ -14,17 +14,25 @@ async function runCommand(runtime, command, ctx, args) {
             error: { code: "INVALID_ARGUMENTS", message: `/${command} does not accept arguments`, details: { args } },
         };
     }
+    let diagnostics;
     try {
+        if (command === "asgrep-doctor")
+            diagnostics = await runtime.diagnostics?.({ cwd: ctx.cwd });
         const response = await runtime.run([command.slice("asgrep-".length), ".", "--json"], { cwd: ctx.cwd });
-        return { ok: true, command, response };
+        return { ok: true, command, response, ...(diagnostics ? { diagnostics } : {}) };
     }
     catch (cause) {
-        return { ok: false, command, error: errorDetails(cause) };
+        return { ok: false, command, error: errorDetails(cause), ...(diagnostics ? { diagnostics } : {}) };
     }
 }
 function compactCommandResult(result) {
+    const diagnostics = result.diagnostics;
+    const versions = diagnostics
+        ? `extension=${diagnostics.extension ?? "unknown"} launcher=${diagnostics.launcher ?? "unknown"} native=${diagnostics.native ?? "unavailable"}`
+        : "";
+    const warning = typeof diagnostics?.warning === "string" ? diagnostics.warning : "";
     if (!result.ok)
-        return `${result.command} failed [${result.error.code}]: ${result.error.message}`;
+        return bounded([`${result.command} failed [${result.error.code}]: ${result.error.message}`, versions, warning].filter(Boolean).join(" · "));
     const response = result.response;
     const counts = response.counts && typeof response.counts === "object"
         ? Object.entries(response.counts).map(([key, value]) => `${key}=${String(value)}`).join(" ")
@@ -32,7 +40,7 @@ function compactCommandResult(result) {
     const state = typeof response.status === "string" ? response.status
         : typeof response.index_status === "string" ? response.index_status
             : response.ok ? "healthy" : "failed";
-    return bounded([`${result.command}: ${state}`, counts].filter(Boolean).join(" · "));
+    return bounded([`${result.command}: ${state}`, counts, versions, warning].filter(Boolean).join(" · "));
 }
 export function registerAstSgrepCommands(pi, runtime = new AstSgrepRuntime(pi)) {
     for (const [name, description] of COMMANDS) {
@@ -42,7 +50,7 @@ export function registerAstSgrepCommands(pi, runtime = new AstSgrepRuntime(pi))
                 const ctx = context;
                 const result = await runCommand(runtime, name, ctx, args);
                 const output = ctx.hasUI ? compactCommandResult(result) : JSON.stringify(result);
-                ctx.ui.notify(output, result.ok ? "info" : "error");
+                ctx.ui.notify(output, result.ok ? result.diagnostics?.warning ? "warning" : "info" : "error");
             },
         });
     }

package/dist/host/results.d.ts

@@ -14,6 +14,10 @@ export type RuntimeLike = {
     nativeEnv?(options?: {
         env?: NodeJS.ProcessEnv;
     }): NodeJS.ProcessEnv;
+    binaryWarning?(): string | undefined;
+    diagnostics?(context: {
+        cwd: string;
+    }): Promise<Record<string, unknown>>;
     config?: {
         timeoutMs?: number;
         maxOutputBytes?: number;
@@ -42,6 +46,8 @@ export type CommandContext = ToolContext & {
     };
 };
 export type CommandResult = {
+    diagnostics?: Record<string, unknown>;
+} & ({
     ok: true;
     command: string;
     response: MachineEnvelope;
@@ -53,7 +59,7 @@ export type CommandResult = {
         message: string;
         details: Readonly<Record<string, unknown>>;
     };
-};
+});
 export type Update = (result: {
     content: Array<{
         type: "text";
@@ -61,7 +67,8 @@ export type Update = (result: {
     }>;
     details: Record<string, unknown>;
 }) => void;
-export declare function bounded(text: string): string;
+export declare function bounded(text: string, maxChars?: number): string;
+export declare function withNotes(text: string, notes?: string[]): string;
 export declare function success(command: string, response: MachineEnvelope, extra?: {
     query?: string;
     mode?: string;

package/dist/host/results.js

@@ -4,12 +4,18 @@
  */
 import { isClosedWorkerError } from "../codemode/index.js";
 import { RuntimeError } from "../runtime/types.js";
-import { formatEditResult, formatIndexResult, formatReadResult, formatSearchResult, formatStatusResult } from "../ui/present.js";
+import { boundedText, formatEditResult, formatIndexResult, formatReadResult, formatSearchResult, formatStatusResult } from "../ui/present.js";
 export const MAX_CONTENT_CHARS = 8_000;
-export function bounded(text) {
-    return text.length <= MAX_CONTENT_CHARS ? text : `${text.slice(0, MAX_CONTENT_CHARS - 1)}…`;
+export function bounded(text, maxChars = MAX_CONTENT_CHARS) {
+    return boundedText(text, maxChars);
+}
+const noteText = (notes = []) => bounded(notes.map(note => `  ! ${note}`).join("\n"), 2000);
+export function withNotes(text, notes = []) {
+    const prefix = noteText(notes);
+    return prefix ? `${prefix}\n${bounded(text, MAX_CONTENT_CHARS - prefix.length - 1)}` : bounded(text);
 }
 export function success(command, response, extra = {}) {
+    const notes = noteText(extra.notes);
     const text = command === "status"
         ? formatStatusResult(response)
         : command === "index" || command === "reindex"
@@ -17,13 +23,11 @@ export function success(command, response, extra = {}) {
             : command === "edit"
                 ? formatEditResult(response)
                 : command === "read"
-                    ? formatReadResult(response)
+                    ? formatReadResult(response, undefined, MAX_CONTENT_CHARS - (notes ? notes.length + 1 : 0))
                     : formatSearchResult(response, { command, ...extra });
     // Notes qualify the answer the agent is about to trust (stale index, empty
     // index): they stay in the model-visible text, not only in the details bag.
-    const body = (extra.notes ?? []).length > 0
-        ? `${text}\n${(extra.notes ?? []).map((note) => `  ! ${note}`).join("\n")}`
-        : text;
+    const body = withNotes(text, extra.notes);
     return {
         content: [{ type: "text", text: bounded(body) }],
         // The tool execute owns its machine command: normalize the envelope's

package/dist/host/tools.js

@@ -6,7 +6,7 @@ import { AstSgrepRuntime, FreshnessCoordinator, RuntimeError } from "../runtime/
 import { RESOLVED_ROOT } from "../runtime/types.js";
 import { ASGREP_PROMPT_GUIDELINES, ASGREP_PROMPT_GUIDELINES_HOST_FILES, ASGREP_PROMPT_SNIPPET, formatCodemodeResult, } from "../ui/present.js";
 import { EMPTY_CALL, renderAsgrepResult } from "../ui/card.js";
-import { bounded, errorDetails, failure, isFreshnessTimeout, extractInPath, report, success, } from "./results.js";
+import { bounded, errorDetails, failure, isFreshnessTimeout, report, success, withNotes, } from "./results.js";
 export const DEFAULT_LIMIT = 8;
 const MAX_LIMIT = 100;
 const MAX_EXCERPT_LINES = 100;
@@ -33,7 +33,7 @@ const editParameters = Type.Object({
         path: Type.Optional(Type.String({ minLength: 1, maxLength: 512 })),
         oldText: Type.String({ minLength: 1 }),
         newText: Type.String(),
-    }), { maxItems: 64, description: "Multi-edit entries; top-level path is the default" })),
+    }), { maxItems: 16, description: "Multi-edit entries; top-level path is the default" })),
 }, { additionalProperties: false });
 const readParameters = Type.Object({
     path: Type.Optional(Type.String({ maxLength: 512 })),
@@ -281,7 +281,7 @@ export function registerAstSgrepTools(pi, runtime = new AstSgrepRuntime(pi), fre
     const requireBackend = (availability, context) => {
         if (availability.kind !== "unavailable")
             return;
-        throw new RuntimeError("BACKEND_UNAVAILABLE", "ast-sgrep backend unavailable (no NAPI session and no CLI binary)", {
+        throw new RuntimeError("BACKEND_UNAVAILABLE", `ast-sgrep backend unavailable (no NAPI session and no CLI binary)${availability.cause ? `: ${availability.cause}` : ""}. Run /asgrep-doctor for recovery details.`, {
             backend: "unavailable",
             // Agent-facing mirrors of the closed unavailable variant (not an open product).
             napi: false,
@@ -352,8 +352,8 @@ export function registerAstSgrepTools(pi, runtime = new AstSgrepRuntime(pi), fre
         };
     }
     /**
-     * Freshness gate shared by the one-shot tools: ensureFresh with a bounded
-     * timeout fallback, or a scoped-path index when the query carries in:/fileFilter.
+     * Shared freshness gate. Query scopes (including directories and globs) filter
+     * retrieval; they are not file-only index --path mutation requests.
      *
      * Bounded means serve-stale, not fail: a caller that ran out of freshness
      * budget still queries the current index and is told the result may be stale.
@@ -361,23 +361,10 @@ export function registerAstSgrepTools(pi, runtime = new AstSgrepRuntime(pi), fre
      * invalidating would kill the index work the caller just stopped waiting for
      * and leave the root permanently stale.
      */
-    const freshRoot = async (cwd, signal, scopedPath) => {
+    const freshRoot = async (cwd, signal) => {
         const options = signal ? { signal } : {};
         const anchor = await anchorRoot(cwd);
         const scope = anchor.scope;
-        // A subtree refresh still lands in the checkout's own index.
-        const target = scopedPath ? (scope ? `${scope}/${scopedPath}` : scopedPath) : undefined;
-        if (target) {
-            try {
-                await nativeCall("index_repo", { paths: [target] }, rootedAt(anchor.root), options);
-            }
-            catch (cause) {
-                if (!isFreshnessTimeout(cause, signal))
-                    throw cause;
-                return { root: anchor.root, ...(scope ? { scope } : {}), freshness: "stale" };
-            }
-            return { root: anchor.root, ...(scope ? { scope } : {}) };
-        }
         try {
             const resolved = await freshness.ensureFresh(warmRuntime, rootedAt(anchor.root), options);
             // The contract is a root string; a host/test double that returns nothing
@@ -502,6 +489,11 @@ export function registerAstSgrepTools(pi, runtime = new AstSgrepRuntime(pi), fre
             catch {
                 // Doctor reports backend errors; a failed warmup must not block the session.
             }
+            finally {
+                const warning = runtime.binaryWarning?.();
+                if (warning && ctx.hasUI)
+                    ctx.ui.notify(warning, "warning");
+            }
         })();
     });
     pi.on("session_shutdown", () => {
@@ -536,18 +528,19 @@ export function registerAstSgrepTools(pi, runtime = new AstSgrepRuntime(pi), fre
         },
         async execute(_toolCallId, params, signal, onUpdate, ctx) {
             report(onUpdate, "codemode", "started");
+            const timeoutMs = typeof params.timeoutMs === "number"
+                ? params.timeoutMs
+                : runtime.config?.timeoutMs ?? 30_000;
+            let timeoutSignal;
             try {
-                const timeoutMs = typeof params.timeoutMs === "number"
-                    ? params.timeoutMs
-                    : runtime.config?.timeoutMs ?? 30_000;
                 const deadline = Date.now() + timeoutMs;
-                const timeoutSignal = AbortSignal.timeout(timeoutMs);
+                timeoutSignal = AbortSignal.timeout(timeoutMs);
                 const operationSignal = signal
                     ? AbortSignal.any([signal, timeoutSignal])
                     : timeoutSignal;
                 const options = { signal: operationSignal };
                 ensurePool();
-                const { root, scope, freshness: fresh } = await freshRoot(ctx.cwd, signal);
+                const { root, scope, freshness: fresh } = await freshRoot(ctx.cwd, operationSignal);
                 const { env, binary } = nativeLaunch();
                 // In-process NAPI first; CLI sticky only if addon missing.
                 const sticky = await pool.acquire(root);
@@ -580,14 +573,16 @@ export function registerAstSgrepTools(pi, runtime = new AstSgrepRuntime(pi), fre
                     backend: pool.backend(),
                 });
                 const activationMs = outcome.wallMs;
+                const notes = fresh ? ["index refresh is still running; this answer came from the current index and may be stale"] : [];
                 return {
-                    content: [{ type: "text", text: bounded(rendered) }],
+                    content: [{ type: "text", text: withNotes(rendered, notes) }],
                     details: {
                         ok: true,
                         command: "codemode",
                         result: outcome.result,
                         logs: outcome.logs,
                         rendered,
+                        notes,
                         stats: outcome.stats,
                         trace: bundle.trace(),
                         wallMs: outcome.wallMs,
@@ -598,6 +593,9 @@ export function registerAstSgrepTools(pi, runtime = new AstSgrepRuntime(pi), fre
                 };
             }
             catch (cause) {
+                if (timeoutSignal?.aborted && !signal?.aborted) {
+                    return failure("codemode", new RuntimeError("TIMEOUT", `codemode timed out after ${timeoutMs}ms`));
+                }
                 return failure("codemode", cause, signal);
             }
         },
@@ -623,9 +621,7 @@ export function registerAstSgrepTools(pi, runtime = new AstSgrepRuntime(pi), fre
             report(onUpdate, "search", "started");
             try {
                 ensurePool();
-                const scopedPath = (typeof params.in === "string" ? params.in : undefined)
-                    ?? extractInPath(params.query);
-                const fresh = await freshRoot(ctx.cwd, signal, scopedPath);
+                const fresh = await freshRoot(ctx.cwd, signal);
                 // The checkout owns the index; the caller's scope rides under it.
                 const anchored = withAnchorScope(params, fresh.scope);
                 const [tool, args] = searchToolCall(anchored);
@@ -674,7 +670,7 @@ export function registerAstSgrepTools(pi, runtime = new AstSgrepRuntime(pi), fre
         name: "asgrep_edit",
         label: "asgrep edit",
         promptSnippet: "Exact-string edit",
-        description: "Edit by exact-string replace. edits[] applies many atomically.",
+        description: "Exact-string edits, validated together before writing.",
         parameters: editParameters,
         renderShell: "self",
         renderCall() {
@@ -716,14 +712,13 @@ export function registerAstSgrepTools(pi, runtime = new AstSgrepRuntime(pi), fre
         async execute(_toolCallId, params, signal, onUpdate, ctx) {
             report(onUpdate, "read", "started");
             try {
-                ensurePool();
+                // Reading source must remain available when the binary or index is broken.
                 const options = signal ? { signal } : {};
-                const { root, scope, freshness: fresh } = await freshRoot(ctx.cwd, signal);
-                const sticky = await pool.acquire(root);
-                const bundle = createAsgrepConnector({ run: (a, c, o) => runtime.run(a, c, o), sticky }, rootedAt(root), { ...options, ...(scope ? { scope } : {}) });
+                const { root, scope } = await anchorRoot(ctx.cwd);
+                const bundle = createAsgrepConnector({ run: (a, c, o) => runtime.run(a, c, o) }, rootedAt(root), { ...options, localReads: true, ...(scope ? { scope } : {}) });
                 const response = await bundle.asgrep.read(params);
                 report(onUpdate, "read", "completed");
-                return success("read", response, { backend: pool.backend(), ...(fresh ? { freshness: fresh } : {}) });
+                return success("read", response, { backend: "filesystem" });
             }
             catch (cause) {
                 return failure("read", cause, signal);
@@ -797,5 +792,8 @@ function searchToolCall(params) {
         const prefixed = spec.prefix ? `${spec.prefix}: ${query}` : query;
         return ["search", { query: prefixed, limit, excerpt_lines, format: "capsule", ...(lang ? { lang } : {}) }];
     }
+    if (/(?:^|\s)in:/u.test(query)) {
+        return ["search", { query: queryForMode(query, mode), limit, excerpt_lines, format: "capsule", ...(lang ? { lang } : {}) }];
+    }
     return [spec.tool, { [spec.key]: params.query, limit, excerpt_lines, ...(lang ? { lang } : {}) }];
 }

package/dist/runtime/index-health.d.ts

@@ -1,5 +1,7 @@
 import { type MachineEnvelope } from "./types.js";
 export type IndexHealth = "ready" | "missing" | "incompatible";
+/** Never turn a canonical byte path into another file's replacement-character name. */
+export declare function realpathUtf8(path: string): Promise<string>;
 export declare function pathContained(parent: string, child: string): boolean;
 export declare function record(value: unknown): Record<string, unknown> | undefined;
 export declare function indexHealth(status: MachineEnvelope): IndexHealth;

package/dist/runtime/index-health.js

@@ -3,12 +3,20 @@
  * rebuild-failure reporting, containment helper. Imports types + sqlite.
  */
 import { existsSync, readdirSync } from "node:fs";
-import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { realpath } from "node:fs/promises";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { INDEX_FORMAT_VERSION, RuntimeError } from "./types.js";
 import { openIndexDatabase } from "./sqlite.js";
+/** Never turn a canonical byte path into another file's replacement-character name. */
+export async function realpathUtf8(path) {
+    if (Buffer.from(path, "utf8").toString("utf8") !== path)
+        throw new Error("invalid Unicode path");
+    const bytes = await realpath(path, { encoding: "buffer" });
+    return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+}
 export function pathContained(parent, child) {
     const rel = relative(parent, child);
-    const first = rel.split(/[\\/]/u, 1)[0];
+    const first = rel.split(sep, 1)[0];
     return rel === "" || (!isAbsolute(rel) && first !== "..");
 }
 export function record(value) {

package/dist/runtime/runtime.d.ts

@@ -40,6 +40,9 @@ export declare class AstSgrepRuntime {
     resolveBinaryPath(options?: {
         env?: NodeJS.ProcessEnv;
     }): string;
+    binaryWarning(): string | undefined;
+    /** Report installed layers even if the project's index cannot be opened. */
+    diagnostics(context: RuntimeContext): Promise<Record<string, unknown>>;
     /** Merged process env for native Code Mode workers. */
     nativeEnv(options?: {
         env?: NodeJS.ProcessEnv;

package/dist/runtime/runtime.js

@@ -1,10 +1,10 @@
-import { realpath } from "node:fs/promises";
-import { constants, accessSync } from "node:fs";
-import { isAbsolute, resolve } from "node:path";
+import { constants, accessSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { createRequire } from "node:module";
 import { resolveBinary } from "ast-sgrep";
 import { CONFIG_SCHEMA_VERSION, DEFAULT_MAX_OUTPUT_BYTES, DEFAULT_REFRESH_INTERVAL_MS, DEFAULT_TIMEOUT_MS, INDEX_FORMAT_VERSION, MACHINE_SCHEMA_VERSION, RUNTIME_VERSION, RuntimeError, RESOLVED_ROOT, } from "./types.js";
 import { finitePositive, migrateConfig, resolveConfig, rollbackConfig, } from "./config.js";
-import { indexCompletion, indexPathFor, indexQuarantines, inspectIndexFile, pathContained, record, throwIndexRebuildFailed, } from "./index-health.js";
+import { indexCompletion, indexPathFor, indexQuarantines, inspectIndexFile, pathContained, realpathUtf8 as realpath, record, throwIndexRebuildFailed, } from "./index-health.js";
 // The public surface of ./runtime is a contract (package.json exports +
 // tests): re-export the symbols that moved to their own modules.
 export { CONFIG_SCHEMA_VERSION, DEFAULT_FRESHNESS_WAIT_MS, DEFAULT_MAX_OUTPUT_BYTES, DEFAULT_REFRESH_INTERVAL_MS, DEFAULT_TIMEOUT_MS, INDEX_FORMAT_VERSION, MACHINE_SCHEMA_VERSION, RUNTIME_VERSION, RuntimeError, } from "./types.js";
@@ -25,18 +25,37 @@ export async function resolveRuntimeRoot(projectCwd, requestedRoot, allowOutside
     }
     return candidate;
 }
-function getBinary(config, env, resolver) {
+function getBinary(config, env, resolver, onRecovery) {
     let binary;
+    let warning;
     try {
         const options = config.binaryPath ? { binaryPath: config.binaryPath, env } : { env };
         binary = resolver(options);
     }
     catch (cause) {
         const message = cause instanceof Error ? cause.message : String(cause);
-        if (config.binaryPath) {
-            throw new RuntimeError("BINARY_NOT_FOUND", `Configured ast-sgrep binary is unavailable: ${config.binaryPath}`, { binaryPath: config.binaryPath, cause: message });
+        const failure = cause;
+        // Missing environment-only dev builds may recover, never explicit settings,
+        // permissions, empty artifacts, checksum failures, PATH, or downloads.
+        if (onRecovery && (env.ASGREP_BIN || env.AST_SGREP_BINARY) && failure?.code === "ASGREP_EXECUTABLE_MISSING" &&
+            (failure.cause?.code === "ENOENT" || failure.cause?.code === "ENOTDIR")) {
+            const variable = env.ASGREP_BIN ? "ASGREP_BIN" : "AST_SGREP_BINARY";
+            try {
+                binary = resolver({ env: { ...env, ASGREP_BIN: undefined, AST_SGREP_BINARY: undefined } });
+            }
+            catch (fallbackCause) {
+                const fallback = fallbackCause instanceof Error ? fallbackCause.message : String(fallbackCause);
+                throw new RuntimeError("BINARY_RESOLUTION_FAILED", `Missing ${variable} override (${config.binaryPath ?? env[variable]}); bundled binary unavailable: ${fallback}. Run /asgrep-doctor and reinstall pi-ast-sgrep with optional dependencies enabled.`, { cause: message, fallbackCause: fallback });
+            }
+            warning = `Ignored missing ${variable}=${config.binaryPath ?? env[variable]}; using bundled binary ${binary}. Remove the stale export from your shell configuration.`;
+        }
+        else {
+            const hint = "Correct binaryPath or unset ASGREP_BIN/AST_SGREP_BINARY; run /asgrep-doctor.";
+            if (config.binaryPath) {
+                throw new RuntimeError("BINARY_NOT_FOUND", `Configured ast-sgrep binary is unavailable: ${config.binaryPath}. ${message}. ${hint}`, { binaryPath: config.binaryPath, cause: message, hint });
+            }
+            throw new RuntimeError("BINARY_RESOLUTION_FAILED", `Unable to resolve an ast-sgrep binary for this platform: ${message}. Run /asgrep-doctor.`, { cause: message });
         }
-        throw new RuntimeError("BINARY_RESOLUTION_FAILED", "Unable to resolve an ast-sgrep binary for this platform", { cause: message });
     }
     try {
         accessSync(binary, constants.X_OK);
@@ -44,6 +63,8 @@ function getBinary(config, env, resolver) {
     catch (cause) {
         throw new RuntimeError("BINARY_NOT_EXECUTABLE", `ast-sgrep binary is not executable: ${binary}`, { binaryPath: binary, cause: cause instanceof Error ? cause.message : String(cause) });
     }
+    if (warning)
+        onRecovery?.(warning);
     return binary;
 }
 function byteLength(value) { return Buffer.byteLength(value, "utf8"); }
@@ -153,11 +174,15 @@ export class AstSgrepRuntime {
     config;
     #resolver;
     #environment;
+    #recoverMissingOverride;
+    #binaryWarning;
     constructor(pi, sources = {}, dependencies = {}) {
         this.pi = pi;
         this.#environment = sources.environment ?? process.env;
         this.config = resolveConfig({ ...sources, environment: this.#environment });
         this.#resolver = dependencies.resolveBinary ?? resolveBinary;
+        this.#recoverMissingOverride = ![sources.explicitProjectConfig, sources.projectSettings, sources.globalSettings, sources.defaults]
+            .some(source => source?.binaryPath !== undefined);
     }
     async resolveRoot(context) {
         return context[RESOLVED_ROOT]
@@ -249,7 +274,7 @@ export class AstSgrepRuntime {
         const root = await this.resolveRoot(context);
         const timeout = finitePositive(options.timeoutMs, this.config.timeoutMs, "timeoutMs");
         const env = this.#mergedEnv(options.env);
-        const binary = getBinary(this.config, env, this.#resolver);
+        const binary = this.resolveBinaryPath({ env });
         try {
             const execOptions = { cwd: root, env, timeout };
             if (options.signal)
@@ -267,7 +292,35 @@ export class AstSgrepRuntime {
     }
     /** Absolute path to the native binary (for sticky serve / stdin batch spawn). */
     resolveBinaryPath(options = {}) {
-        return getBinary(this.config, this.#mergedEnv(options.env), this.#resolver);
+        this.#binaryWarning = undefined;
+        return getBinary(this.config, this.#mergedEnv(options.env), this.#resolver, this.#recoverMissingOverride ? warning => { this.#binaryWarning = warning; } : undefined);
+    }
+    binaryWarning() { return this.#binaryWarning; }
+    /** Report installed layers even if the project's index cannot be opened. */
+    async diagnostics(context) {
+        const versionAt = (path) => {
+            try {
+                return JSON.parse(readFileSync(path, "utf8")).version ?? "unknown";
+            }
+            catch {
+                return "unknown";
+            }
+        };
+        const result = {
+            extension: versionAt(new URL("../../package.json", import.meta.url)),
+        };
+        try {
+            const launcher = createRequire(import.meta.url).resolve("ast-sgrep");
+            result.launcher = versionAt(join(dirname(launcher), "..", "package.json"));
+            result.binaryPath = this.resolveBinaryPath();
+            result.native = (await this.checkCompatibility(context)).version;
+        }
+        catch (cause) {
+            result.error = cause instanceof Error ? cause.message : String(cause);
+        }
+        if (this.#binaryWarning)
+            result.warning = this.#binaryWarning;
+        return result;
     }
     /** Merged process env for native Code Mode workers. */
     nativeEnv(options = {}) {

package/dist/runtime/types.d.ts

@@ -2,7 +2,7 @@
  * Shared leaf module: version constants, wire types, RuntimeError.
  * Imports nothing from sibling modules — any file may depend on it.
  */
-export declare const RUNTIME_VERSION = "2.5.2";
+export declare const RUNTIME_VERSION = "2.5.4";
 export declare const MACHINE_SCHEMA_VERSION = "1.0.0";
 export declare const CONFIG_SCHEMA_VERSION: 1;
 /** Index format this release ships. Must equal INDEX_SCHEMA_VERSION in crates/ast-sgrep-core (check-contract gates it). */

package/dist/runtime/types.js

@@ -2,7 +2,7 @@
  * Shared leaf module: version constants, wire types, RuntimeError.
  * Imports nothing from sibling modules — any file may depend on it.
  */
-export const RUNTIME_VERSION = "2.5.2";
+export const RUNTIME_VERSION = "2.5.4";
 export const MACHINE_SCHEMA_VERSION = "1.0.0";
 export const CONFIG_SCHEMA_VERSION = 1;
 /** Index format this release ships. Must equal INDEX_SCHEMA_VERSION in crates/ast-sgrep-core (check-contract gates it). */

package/dist/ui/card.js

@@ -1,7 +1,7 @@
 /** Pi TUI result card — supernova-style: the call slot is empty; one card
  * owns the whole lifecycle (running → ops ledger → result → error). Rows are
  * fixed-column and theme-painted; nothing here writes to the model channel. */
-import { displayWidth, hitLabel, hitLocation, paint, sanitizeContent, summarizeValue, truncateToWidth, visibleWidth, } from "./present.js";
+import { displayWidth, hitLabel, hitLocation, hitsOf, paint, sanitizeContent, summarizeValue, truncateToWidth, visibleWidth, } from "./present.js";
 /** Header text that rides the top border: "asgrep search · 4 hits · 12ms · napi". */
 function frameLabel(model) {
     const bits = ["asgrep", model.command, ...model.title.filter((b) => Boolean(b))];
@@ -250,12 +250,6 @@ function editsOf(value) {
     }
     return undefined;
 }
-function hitsOf(value) {
-    if (value && typeof value === "object" && Array.isArray(value.hits)) {
-        return value.hits;
-    }
-    return undefined;
-}
 function resultPreviewLines(value) {
     if (value === undefined || value === null)
         return undefined;

package/dist/ui/present.d.ts

@@ -39,10 +39,12 @@ export declare const ASGREP_PROMPT_GUIDELINES: readonly ["Any code lookup: call
 export declare const ASGREP_PROMPT_GUIDELINES_HOST_FILES: readonly ["Any code lookup: call asgrep first.", "Compose in Code Mode (search/defs/read, Promise.all, small shaped value); grep only exact strings/filenames. Bound with in:\"path\"; on 0 hits use suggested_next."];
 export declare function paint(theme: PresentTheme | undefined, role: string, text: string, bold?: boolean): string;
 export declare function hitLocation(hit: HitLike): string;
+/** A caller may return arbitrary data named `hits`; only locations are search hits. */
+export declare function hitsOf(value: unknown): HitLike[] | undefined;
 export declare function hitLabel(hit: HitLike): string;
 export declare function formatEditResult(response: EnvelopeLike, theme?: PresentTheme): string;
 /** Model-visible text for a read envelope: the window contents themselves. */
-export declare function formatReadResult(response: EnvelopeLike, theme?: PresentTheme): string;
+export declare function formatReadResult(response: EnvelopeLike, theme?: PresentTheme, maxChars?: number): string;
 /**
  * Model-facing result text is deliberately lean: the tool call already carries
  * the query/mode, the TUI card renders timing and backend for the human, and
@@ -84,6 +86,7 @@ export declare function truncateToWidth(text: string, maxWidth: number, ellipsis
  * value compacted. Transport fields are dropped rather than rendered.
  */
 export declare function summarizeValue(value: unknown, limit?: number): string[];
+export declare function boundedText(text: string, maxChars?: number, notice?: string): string;
 export declare function formatCodemodeResult(value: unknown, meta?: {
     stats?: {
         calls: number;

package/dist/ui/present.js

@@ -30,10 +30,18 @@ export function hitLocation(hit) {
         return sanitizeContent(hit.ref);
     return file || "?";
 }
+/** A caller may return arbitrary data named `hits`; only locations are search hits. */
+export function hitsOf(value) {
+    const hits = value && typeof value === "object" ? value.hits : undefined;
+    return Array.isArray(hits) && hits.every(hit => hit && typeof hit === "object" &&
+        (typeof hit.file === "string" || typeof hit.path === "string" || typeof hit.ref === "string"))
+        ? hits : undefined;
+}
 /** Hard caps for one result: rows shown, excerpt lines per hit, longest preview. */
 const MAX_HIT_ROWS = 24;
 const MAX_EXCERPT_LINES_OUT = 12;
 const MAX_PREVIEW_CHARS = 96;
+const MAX_RESULT_CHARS = 8_000;
 export function hitLabel(hit) {
     const symbol = typeof hit.symbol === "string" ? sanitizeContent(hit.symbol) : "";
     const kind = typeof hit.kind === "string" ? sanitizeContent(hit.kind) : "";
@@ -55,22 +63,38 @@ export function formatEditResult(response, theme) {
     return rows.join("\n");
 }
 /** Model-visible text for a read envelope: the window contents themselves. */
-export function formatReadResult(response, theme) {
+export function formatReadResult(response, theme, maxChars = MAX_RESULT_CHARS) {
     const windows = Array.isArray(response.windows) ? response.windows : [];
     if (windows.length === 0)
         return "read: 0 windows";
     const out = [];
+    let displayed = 0;
+    const moreWindows = (count) => count > 0 ? [`… ${count} more windows`] : [];
     for (const w of windows.slice(0, 8)) {
         const path = sanitizeContent(typeof w.path === "string" ? w.path : "?");
-        // The window's own path+range is the line the model needs to cite back.
-        out.push(path + "#L" + (w.start ?? 1) + "-L" + (w.end ?? ""));
         const text = sanitizeContent(typeof w.text === "string" ? w.text : "");
-        for (const line of text.split("\n").slice(0, 80))
-            out.push(line);
+        const lines = text.split("\n");
+        const start = w.start ?? 1;
+        const render = (count) => {
+            const end = count < lines.length && typeof start === "number" ? start + Math.max(0, count - 1) : (w.end ?? "");
+            return [path + "#L" + start + "-L" + end, ...lines.slice(0, count),
+                ...(count < lines.length || w.truncated === true ? ["… (truncated; read a smaller window)"] : [])].join("\n");
+        };
+        // Reserve the omission notice and fit whole lines before finalizing refs;
+        // a later character clip would otherwise overstate the displayed range.
+        const suffix = moreWindows(windows.length - displayed - 1);
+        let count = Math.min(lines.length, 80);
+        const fits = () => [...out, render(count), ...suffix].join("\n").length <= maxChars;
+        while (count > 0 && !fits())
+            count--;
+        if (!fits())
+            break;
+        out.push(render(count));
+        displayed++;
+        if (count < Math.min(lines.length, 80))
+            break;
     }
-    if (windows.length > 8)
-        out.push("… " + (windows.length - 8) + " more windows");
-    return out.join("\n");
+    return boundedText([...out, ...moreWindows(windows.length - displayed)].join("\n"), maxChars);
 }
 /**
  * Model-facing result text is deliberately lean: the tool call already carries
@@ -324,7 +348,7 @@ export function summarizeValue(value, limit = 4) {
     }
     const recordValue = value;
     const rows = [];
-    const hits = Array.isArray(recordValue.hits) ? recordValue.hits : undefined;
+    const hits = hitsOf(value);
     const windows = Array.isArray(recordValue.windows)
         ? recordValue.windows
         : undefined;
@@ -361,19 +385,34 @@ function compactValue(value) {
     const json = JSON.stringify(value);
     return json.length <= 80 ? json : `${json.slice(0, 79)}…`;
 }
+/** Model output is data, not the TUI's lossy summary. Keep a visible size bound. */
+function codemodePayload(value) {
+    return sanitizeContent(typeof value === "string" ? value : JSON.stringify(value, null, 2) ?? String(value));
+}
+export function boundedText(text, maxChars = MAX_RESULT_CHARS, notice = "\n… (truncated)") {
+    if (text.length <= maxChars)
+        return text;
+    if (maxChars <= notice.length)
+        return notice.slice(0, Math.max(0, maxChars));
+    let end = maxChars - notice.length;
+    const last = text.charCodeAt(end - 1);
+    if (last >= 0xd800 && last <= 0xdbff)
+        end--;
+    return text.slice(0, end) + notice;
+}
+function boundedCodemode(text) {
+    return boundedText(text, MAX_RESULT_CHARS, "\n… (truncated; return fewer items or smaller windows)");
+}
 export function formatCodemodeResult(value, meta = {}, theme) {
-    if (value && typeof value === "object" && Array.isArray(value.hits)) {
-        const searchMeta = { command: "codemode" };
-        if (meta.wallMs !== undefined)
-            searchMeta.activationMs = meta.wallMs;
-        if (meta.backend !== undefined)
-            searchMeta.backend = meta.backend;
-        return formatSearchResult(value, searchMeta, theme);
-    }
+    const result = value && typeof value === "object" ? value : undefined;
+    const hits = hitsOf(value);
+    const envelope = result?.tool === "asgrep" && typeof result.schema_version === "string" && typeof result.ok === "boolean";
     const bits = [];
+    if (hits)
+        bits.push(`${hits.length} hit${hits.length === 1 ? "" : "s"}`);
     if (value && typeof value === "object") {
         const record = value;
-        if (typeof record.hit_count === "number")
+        if (!hits && typeof record.hit_count === "number")
             bits.push(`${record.hit_count} hit${record.hit_count === 1 ? "" : "s"}`);
         else if (typeof record.node_count === "number")
             bits.push(`${record.node_count} node${record.node_count === 1 ? "" : "s"}`);
@@ -390,13 +429,12 @@ export function formatCodemodeResult(value, meta = {}, theme) {
         return `${title}\n${paint(theme, "muted", "  (no return statement; add `return` to send a value to the model)")}`;
     }
     if (value && typeof value === "object" && !Array.isArray(value)) {
-        // The program's own return shape is a deliberate choice: summarize it
-        // wider than a hit preview, or the model has to re-run to see its value.
-        const rows = summarizeValue(value, 12).map((row) => paint(theme, "toolOutput", `  ${row}`));
-        return [title, ...rows].join("\n");
-    }
-    if (Array.isArray(value)) {
-        return [title, paint(theme, "toolOutput", `  ${value.length} value${value.length === 1 ? "" : "s"}`)].join("\n");
+        // The chosen return value is data. Lossy hit summaries belong only to the
+        // TUI or one-shot search, never this explicit model-facing return channel.
+        const rows = Object.entries(value)
+            .filter(([key]) => !envelope || !TRANSPORT_KEYS.has(key))
+            .map(([key, entry]) => paint(theme, "toolOutput", `  ${sanitizeContent(key)}: ${codemodePayload(entry)}`));
+        return boundedCodemode([title, ...rows].join("\n"));
     }
-    return `${title}\n${paint(theme, "toolOutput", `  ${compactValue(value)}`)}`;
+    return boundedCodemode(`${title}\n${paint(theme, "toolOutput", `  ${codemodePayload(value)}`)}`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ast-sgrep",
-  "version": "2.5.2",
+  "version": "2.5.4",
   "description": "Native Code Mode, structural, graph, and semantic code search for Pi",
   "type": "module",
   "license": "MIT",
@@ -63,7 +63,7 @@
     "node": ">=22.19.0"
   },
   "dependencies": {
-    "ast-sgrep": ">=2.0.0 <3",
+    "ast-sgrep": ">=2.5.4 <3",
     "typebox": "^1.0.0"
   },
   "peerDependencies": {