pi-ast-sgrep 1.4.0 → 2.0.1

package/README.md

@@ -4,7 +4,23 @@ Native Code Mode, structural, graph, and semantic code search for [Pi](https://g
 
 [![pi-ast-sgrep: native code search inside Pi](https://cdn.jsdelivr.net/npm/pi-ast-sgrep/assets/preview.png)](https://pi.dev/packages/pi-ast-sgrep?name=pi-ast-sgrep)
 
-`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, and searches local semantic embeddings. The primary `asgrep_codemode` tool lets Pi compose several searches in one JavaScript program instead of spending one model round trip per lookup.
+`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)
+
+**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`.
+
+### What's new for Pi in 2.0
+
+| Change | What you get |
+|--------|----------------|
+| Local-first embeddings | No `ASGREP_EMBED_API_KEY` / Ollama URL. Hashed semantic is default; optional ONNX stays in-process. |
+| Results on the model path | `asgrep_search` and Code Mode serialize hits into `content`. |
+| Two-channel queries | `asgrep.search({ query: 'callers:process_request AND pattern:fn $NAME($$$)' })` joins by span; `AND NOT` subtracts. Plain English `and` stays hybrid. |
+| Critic + follow-ups | Agent envelopes include `why` (`critic:` notes) and causal `follow_up_queries` from the actual top hit. |
+| Native work off the event loop | Index/search run as N-API worker tasks so Pi JS is not blocked on SQLite. |
+| Auto-registered tools | `asgrep` lands without requiring a skill file. |
+| Schema 12 | Older indexes rebuild through the normal compatibility path; `/asgrep-reindex` is the explicit full rebuild. |
 
 ## Install
 
@@ -24,11 +40,10 @@ No Rust toolchain or separate MCP server is required. The npm package selects th
 
 | Resource | Purpose |
 |---|---|
-| `asgrep_codemode` | Primary tool. Run a bounded JavaScript program that composes typed `asgrep.*` calls. |
+| `asgrep` | Primary tool. Run a bounded JavaScript program that composes typed `asgrep.*` calls. Auto-registered with Pi (no skill file). |
 | `asgrep_search` | Run one natural, structural, symbol, graph, semantic, word, literal, or regex lookup. |
 | `asgrep_index` | Create, refresh, or explicitly rebuild the current project index. |
 | `asgrep_status` | Inspect the selected root, index, backend, counts, and capabilities. |
-| `ast-sgrep` skill | Teach Pi when and how to use Code Mode, direct search, or exact-text search. |
 
 The package also registers `/asgrep-doctor`, `/asgrep-status`, `/asgrep-index`, and `/asgrep-reindex`.
 
@@ -38,7 +53,7 @@ Ask Pi:
 
 > Use ast-sgrep Code Mode to find where access tokens are refreshed, trace the top result's callers, and return only the relevant files, symbols, and lines.
 
-Pi can make one `asgrep_codemode` call like this:
+Pi can make one `asgrep` call like this:
 
 ```json
 {
@@ -50,7 +65,7 @@ This workflow narrows the first result, runs independent follow-up searches toge
 
 ### Code Mode API
 
-The sandbox exposes these asynchronous methods:
+The Code Mode program receives these asynchronous methods on `asgrep`:
 
 | Method | Use |
 |---|---|
@@ -67,7 +82,15 @@ The sandbox exposes these asynchronous methods:
 
 Use `Promise.all` for independent calls. Filter, map, sort, and slice intermediate values in JavaScript. Return only the evidence needed for the next reasoning step.
 
-Code Mode includes `Promise`, `JSON`, arrays, objects, `Map`, `Set`, and `Math`. It does not expose `require`, `process`, `fetch`, or filesystem APIs. This is a capability boundary for generated code, not an OS sandbox for the installed Pi package.
+Code Mode runs in a disposable worker with a restricted `node:vm` context that exposes only a serialized `asgrep.*` bridge and console. String and WebAssembly code generation are disabled, ambient Node globals such as `process` and `require` are not exposed, and terminating the worker contains synchronous and microtask CPU loops. Node does not consider `vm` an adversarial-code security boundary, however, and the installed Pi package has full OS-user access; do not treat Code Mode as an OS jail. Prefer Code Mode **or** MCP for a client, never both.
+
+The bridge rejects oversized call arguments and serialized results, allows at
+most 256 host calls per program, and caps collected console output before it
+reaches the extension host. Raw-memory and WebAssembly globals are unavailable;
+worker heap/stack limits contain the remaining accidental memory growth. Native
+tool values are capped at 1 MiB each and complete batch responses at 4 MiB before
+Node-API converts them into extension-host objects. These bounds do not turn `node:vm` into an OS
+sandbox.
 
 ## Direct one-shot search
 
@@ -78,13 +101,15 @@ Use `asgrep_search` when one lookup is enough:
 {"query":"auth_refresh","mode":"callers","limit":8}
 {"query":"where are credentials renewed?","mode":"semantic","limit":8}
 {"query":"$CLIENT.post($URL)","mode":"pattern","limit":8}
+{"query":"callers:process_request AND pattern:fn $NAME($$$)", "mode":"natural","limit":8}
+{"query":"defs:handle AND NOT callers:test_","mode":"natural","limit":8}
 ```
 
 Available modes:
 
 | Mode | Best for |
 |---|---|
-| `natural` | Intent or mixed code-language queries when exact spelling is unknown. |
+| `natural` | Intent or mixed code-language queries when exact spelling is unknown. Also the mode for two-channel `AND` / `AND NOT` query strings. |
 | `pattern` | Syntax-aware ast-sgrep patterns with metavariables. |
 | `defs`, `callers`, `imports` | Symbol and module navigation. |
 | `chain` | Multi-hop relationship tracing. |
@@ -97,6 +122,8 @@ Available modes:
 
 Official platform packages include `ast-sgrep-codemode.node`. The extension loads an in-process native `CodeModeSession` and keeps one warm Searcher per project root for Code Mode, direct tools, and freshness checks. Normal searches do not spawn a CLI process.
 
+Native index and search calls run as Promise-returning N-API worker tasks rather than on Node's event-loop thread. Calls for one warm session are serialized before entering libuv so concurrent Pi work does not occupy worker threads waiting on the same SQLite session.
+
 Independent calls created in the same JavaScript turn are coalesced into a batch. `Promise.all` can therefore fan out several lookups while the model makes one tool call. If the native addon is unavailable, the bundled CLI service is a degraded fallback; `/asgrep-doctor` reports the active backend.
 
 Code Mode and `ast-sgrep-mcp` are separate front ends over the same Rust search core. Pi uses Code Mode directly and does not use an MCP adapter.
@@ -105,7 +132,9 @@ Code Mode and `ast-sgrep-mcp` are separate front ends over the same Rust search
 
 Start Pi in the repository you want to search. The first search validates the index and lazily creates `<project-root>/.asgrep/` when needed. Run `/asgrep-index` if you want to build it before searching.
 
-After a successful Pi `write` or `edit`, the extension marks the affected path dirty and refreshes it before the next search. Concurrent searches for the same root share one in-flight refresh. Use `/asgrep-reindex` only for an incompatible or corrupt index, or when you explicitly need a full rebuild.
+After a successful Pi `write` or `edit`, the extension marks the affected path dirty and updates only known changed paths before the next search. It also watches the project for external filesystem changes: known file changes receive the same targeted update, while renames, directory changes, ignore-file edits, watcher errors, and ambiguous events trigger a correctness scan. `.asgrep` writes are excluded so indexing cannot dirty itself. If recursive watching is unavailable, an immediate scan plus the periodic full scan preserve correctness. Concurrent searches for the same root share one in-flight refresh.
+
+The periodic interval forces a full incremental reconciliation even when the watcher reports nothing, covering dropped or coalesced filesystem events. Run `/asgrep-index` when you need freshness immediately after a large external operation; use `/asgrep-reindex` only for an incompatible or corrupt index, or when you explicitly need a strict full rebuild.
 
 The package never edits `.gitignore`. Add this entry yourself if index data must stay untracked:
 
@@ -120,7 +149,7 @@ The package never edits `.gitignore`. Add this entry yourself if index data must
 | `/asgrep-doctor` | Check package versions, native runtime, protocol, index, and project settings. |
 | `/asgrep-status` | Show the current root and index state. |
 | `/asgrep-index` | Create or incrementally refresh the index. |
-| `/asgrep-reindex` | Build and atomically replace the index from scratch. |
+| `/asgrep-reindex` | Strictly rebuild the index in one transaction while preserving the prior usable rows on failure. |
 
 These commands take no arguments.
 
@@ -166,7 +195,7 @@ The agent chooses the retrieval granularity; these methods never auto-fuse chann
 
 The default semantic backend works offline. It needs no credential, sends no telemetry, and downloads no model on first use. Search data stays under the project's `.asgrep/` directory.
 
-External cloud, Ollama, and neural embedding providers are optional. If you enable one, source text and queries needed for embeddings can be sent to that provider. Its credential, retention, and privacy rules then apply.
+In-process neural embeddings are optional (`--features neural-embed`). They never send source text to a remote embedding API. Hashed local search remains the default.
 
 Pi packages are trusted code. Installation grants this JavaScript extension and its native code the permissions of the OS user running Pi. Project-root confinement is a package policy, not an operating-system security boundary.
 
@@ -200,13 +229,14 @@ pi remove npm:pi-ast-sgrep
 pi install npm:pi-ast-sgrep@<previous-version>
 ```
 
-Then run `/asgrep-doctor`. Compatible updates reuse validated data. Incompatible formats rebuild atomically and preserve recoverable prior data when a rebuild fails.
+Then run `/asgrep-doctor`. Compatible updates reuse validated data. Incompatible formats rebuild transactionally in place and preserve recoverable prior rows when a rebuild fails.
 
 ## More documentation
 
 - [Complete Pi package guide](https://github.com/AdityaVG13/ast-sgrep/blob/main/docs/pi-package.md)
 - [Code Mode architecture and performance](https://github.com/AdityaVG13/ast-sgrep/blob/main/docs/codemode.md)
-- [Query grammar](https://github.com/AdityaVG13/ast-sgrep/blob/main/docs/QUERY_GRAMMAR.md)
+- [Query grammar](https://github.com/AdityaVG13/ast-sgrep/blob/main/docs/QUERY_GRAMMAR.md) (prefixes and two-channel `AND`)
+- [Fusion ranking and critic](https://github.com/AdityaVG13/ast-sgrep/blob/main/docs/fusion-ranking.md)
 - [Release provenance](https://github.com/AdityaVG13/ast-sgrep/blob/main/docs/RELEASING.md)
 
 MIT

package/dist/code-mode.d.ts

@@ -2,17 +2,16 @@ import { type AstSgrepRuntime, type MachineEnvelope, type RunOptions, type Runti
 export type SgrepKind = "asgrep" | "def" | "caller" | "graph" | "anchor" | "import" | "pattern" | "embed";
 export type SgrepSignal = "exact" | "structural" | "semantic";
 export type SgrepRef = `${string}#L${number}-L${number}`;
+/**
+ * Trusted search hit. Location is solely `ref` (parsed once at the CLI/JSON boundary).
+ * Wire may still dual-encode file/lines; those are not live fields on this type.
+ */
 export interface SgrepHit {
     kind: SgrepKind;
     signal: SgrepSignal;
     contributors: SgrepKind[];
     score: number;
     margin: number;
-    file: string;
-    lines: {
-        start: number;
-        end: number;
-    };
     ref: SgrepRef;
     preview: string;
     symbol?: string | null;
@@ -36,15 +35,18 @@ export interface SgrepReadOptions {
     maxChars?: number;
     signal?: AbortSignal;
 }
+/**
+ * Trusted read window. Location is solely `ref` (actual lines returned; may expand the
+ * request via contextLines). Derive file/lines with `parseSgrepRef` -- no live twins.
+ */
 export interface SgrepReadResult {
     ref: SgrepRef;
-    file: string;
-    lines: {
-        start: number;
-        end: number;
-    };
     content: string;
     truncated: boolean;
+    /** Present when truncated: 1-indexed line to resume from (on the last shown line). */
+    resumeOffset?: number;
+    /** Named recovery hint for the model (empty/past-EOF/truncation). */
+    note?: string;
 }
 export interface SgrepApi {
     keywordSearch(query: string, options?: SgrepSearchOptions): Promise<SgrepSearchResponse>;
@@ -62,6 +64,12 @@ export interface SgrepApi {
 }
 export type SgrepPlan<T> = (sgrep: Readonly<SgrepApi>) => T | Promise<T>;
 type RuntimeLike = Pick<AstSgrepRuntime, "run" | "resolveRoot">;
+/** Derive file/lines from a branded ref (sole location encoding on SgrepHit). */
+export declare function parseSgrepRef(ref: SgrepRef): {
+    file: string;
+    start: number;
+    end: number;
+};
 export declare class SgrepCodeMode implements SgrepApi {
     #private;
     private readonly runtime;

package/dist/code-mode.js

@@ -9,6 +9,17 @@ const DEFAULT_MAX_READ_CHARS = 100_000;
 const MAX_READ_CHARS = 1_000_000;
 const MAX_READ_REFS = 20;
 const MAX_SCAN_BYTES = 64 * 1024 * 1024;
+const MAX_LINE_CHARS = 2_000;
+const DEVICE_PATHS = new Set([
+    "/dev/zero", "/dev/urandom", "/dev/random", "/dev/stdin",
+    "/dev/stdout", "/dev/stderr", "/dev/null", "/dev/fd/0", "/dev/fd/1", "/dev/fd/2",
+]);
+function assertSafeReadPath(absolutePath) {
+    const normalized = absolutePath.replace(/\\/g, "/");
+    if (DEVICE_PATHS.has(normalized) || /^\/proc\/\d+\/fd\//.test(normalized)) {
+        throw new RuntimeError("READ_FORBIDDEN_PATH", `${absolutePath} is a device or process fd path and cannot be read`, { path: absolutePath });
+    }
+}
 const MAX_LINE_NUMBER = 0xffff_ffff;
 const REF_PATTERN = /^(.+?)#L([1-9]\d*)-L([1-9]\d*)$/;
 const KINDS = new Set(["asgrep", "def", "caller", "graph", "anchor", "import", "pattern", "embed"]);
@@ -38,6 +49,71 @@ function outputArgs(options) {
         String(boundedInteger(options.excerptLines, 0, 0, MAX_EXCERPT_LINES, "excerptLines")),
     ];
 }
+function optionalTextField(field) {
+    return field === undefined || field === null || typeof field === "string";
+}
+function wireLinesValid(lines) {
+    return !!lines && typeof lines === "object"
+        && Number.isSafeInteger(lines.start)
+        && Number.isSafeInteger(lines.end)
+        && Number(lines.start) > 0
+        && Number(lines.end) >= Number(lines.start);
+}
+/** Parse wire location once: prefer branded `ref`; else derive from structured file/lines. */
+function parseWireHitRef(hit) {
+    if (typeof hit.ref === "string") {
+        parseRef(hit.ref);
+        return hit.ref;
+    }
+    if (typeof hit.file === "string" && hit.file.length > 0 && !isAbsolute(hit.file) && wireLinesValid(hit.lines)) {
+        const start = Number(hit.lines.start);
+        const end = Number(hit.lines.end);
+        if (start > MAX_LINE_NUMBER || end > MAX_LINE_NUMBER) {
+            throw new RuntimeError("PROTOCOL_MISMATCH", "ast-sgrep returned an invalid search hit");
+        }
+        const ref = `${hit.file}#L${start}-L${end}`;
+        parseRef(ref);
+        return ref;
+    }
+    throw new RuntimeError("PROTOCOL_MISMATCH", "ast-sgrep returned an invalid search hit");
+}
+/** Wire hit shape gate: required protocol fields + optional text fields. Domain checks kept intact. */
+function isValidHitShape(hit) {
+    return typeof hit.kind === "string" && KINDS.has(hit.kind)
+        && typeof hit.signal === "string" && SIGNALS.has(hit.signal)
+        && Array.isArray(hit.contributors) && hit.contributors.length > 0
+        && hit.contributors.every((kind) => typeof kind === "string" && KINDS.has(kind))
+        && typeof hit.score === "number" && Number.isFinite(hit.score)
+        && typeof hit.margin === "number" && Number.isFinite(hit.margin) && hit.margin >= 0
+        && typeof hit.preview === "string"
+        && optionalTextField(hit.symbol) && optionalTextField(hit.caller) && optionalTextField(hit.callee)
+        && optionalTextField(hit.language) && optionalTextField(hit.excerpt);
+}
+function parseSearchHit(candidate) {
+    if (!candidate || typeof candidate !== "object") {
+        throw new RuntimeError("PROTOCOL_MISMATCH", "ast-sgrep returned an invalid search hit");
+    }
+    const hit = candidate;
+    if (!isValidHitShape(hit)) {
+        throw new RuntimeError("PROTOCOL_MISMATCH", "ast-sgrep returned an invalid search hit");
+    }
+    const ref = parseWireHitRef(hit);
+    const parsed = {
+        kind: hit.kind,
+        signal: hit.signal,
+        contributors: hit.contributors,
+        score: hit.score,
+        margin: hit.margin,
+        ref,
+        preview: hit.preview,
+        ...(hit.symbol === undefined ? {} : { symbol: hit.symbol }),
+        ...(hit.caller === undefined ? {} : { caller: hit.caller }),
+        ...(hit.callee === undefined ? {} : { callee: hit.callee }),
+        ...(hit.language === undefined ? {} : { language: hit.language }),
+        ...(hit.excerpt === undefined ? {} : { excerpt: hit.excerpt }),
+    };
+    return parsed;
+}
 function asSearchResponse(value) {
     if (value.ok !== true || !Array.isArray(value.hits)) {
         throw new RuntimeError("PROTOCOL_MISMATCH", "ast-sgrep search response is missing hits");
@@ -45,48 +121,23 @@ function asSearchResponse(value) {
     if (value.query !== undefined && typeof value.query !== "string") {
         throw new RuntimeError("PROTOCOL_MISMATCH", "ast-sgrep search response has an invalid query");
     }
-    if (value.hit_count !== undefined
-        && (typeof value.hit_count !== "number" || !Number.isSafeInteger(value.hit_count)
-            || value.hit_count < 0 || value.hit_count !== value.hits.length)) {
-        throw new RuntimeError("PROTOCOL_MISMATCH", "ast-sgrep search response has an invalid hit_count");
-    }
-    const optionalText = (field) => field === undefined || field === null || typeof field === "string";
-    for (const candidate of value.hits) {
-        if (!candidate || typeof candidate !== "object") {
-            throw new RuntimeError("PROTOCOL_MISMATCH", "ast-sgrep returned an invalid search hit");
-        }
-        const hit = candidate;
-        const lines = hit.lines;
-        const validLines = !!lines && typeof lines === "object"
-            && Number.isSafeInteger(lines.start)
-            && Number.isSafeInteger(lines.end)
-            && Number(lines.start) > 0
-            && Number(lines.end) >= Number(lines.start);
-        const valid = typeof hit.kind === "string" && KINDS.has(hit.kind)
-            && typeof hit.signal === "string" && SIGNALS.has(hit.signal)
-            && Array.isArray(hit.contributors) && hit.contributors.length > 0
-            && hit.contributors.every((kind) => typeof kind === "string" && KINDS.has(kind))
-            && typeof hit.score === "number" && Number.isFinite(hit.score)
-            && typeof hit.margin === "number" && Number.isFinite(hit.margin) && hit.margin >= 0
-            && typeof hit.file === "string" && hit.file.length > 0 && !isAbsolute(hit.file)
-            && validLines
-            && typeof hit.ref === "string"
-            && typeof hit.preview === "string"
-            && optionalText(hit.symbol) && optionalText(hit.caller) && optionalText(hit.callee)
-            && optionalText(hit.language) && optionalText(hit.excerpt);
-        if (!valid)
-            throw new RuntimeError("PROTOCOL_MISMATCH", "ast-sgrep returned an invalid search hit");
-        const parsed = parseRef(hit.ref);
-        const hitLines = lines;
-        if (parsed.file !== hit.file || parsed.start !== hitLines.start || parsed.end !== hitLines.end) {
-            throw new RuntimeError("PROTOCOL_MISMATCH", "ast-sgrep hit ref does not match its file and lines");
+    // Guard form of compound hit_count validity (same checks, less && nesting).
+    if (value.hit_count !== undefined) {
+        if (typeof value.hit_count !== "number" || !Number.isSafeInteger(value.hit_count)
+            || value.hit_count < 0 || value.hit_count !== value.hits.length) {
+            throw new RuntimeError("PROTOCOL_MISMATCH", "ast-sgrep search response has an invalid hit_count");
         }
     }
-    return value;
+    const hits = value.hits.map(parseSearchHit);
+    return { ...value, hits };
 }
 function refValue(value) {
     return typeof value === "string" ? value : value.ref;
 }
+/** Derive file/lines from a branded ref (sole location encoding on SgrepHit). */
+export function parseSgrepRef(ref) {
+    return parseRef(ref);
+}
 function parseRef(ref) {
     const match = REF_PATTERN.exec(ref);
     if (!match)
@@ -119,6 +170,9 @@ function boundedPrefix(value, maxChars) {
     }
     return { text: value, chars, truncated: false };
 }
+function formatReadRef(file, start, end) {
+    return `${file}#L${start}-L${end}`;
+}
 async function readLineWindow(handle, parsed, contextLines, maxChars, signal) {
     const stat = await handle.stat();
     if (!stat.isFile())
@@ -146,7 +200,9 @@ async function readLineWindow(handle, parsed, contextLines, maxChars, signal) {
             selectedStart ??= lineNumber;
             selectedEnd = lineNumber;
             if (!truncated) {
-                const addition = `${selectedLines > 0 ? "\n" : ""}${line.endsWith("\r") ? line.slice(0, -1) : line}`;
+                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);
                 content += bounded.text;
                 contentChars += bounded.chars;
@@ -209,14 +265,31 @@ async function readLineWindow(handle, parsed, contextLines, maxChars, signal) {
         stream.destroy();
     }
     checkAbort(signal);
-    if (parsed.start >= lineNumber || parsed.end >= lineNumber) {
-        throw new RuntimeError("RANGE_OUT_OF_BOUNDS", `${parsed.file} has fewer than ${parsed.end} lines`);
+    const totalLines = Math.max(0, lineNumber - 1);
+    if (totalLines === 0) {
+        return {
+            window: null,
+            content: "",
+            truncated: false,
+            note: `${parsed.file} is empty`,
+        };
     }
+    if (parsed.start > totalLines || parsed.end > totalLines) {
+        const resume = Math.max(1, totalLines);
+        throw new RuntimeError("RANGE_OUT_OF_BOUNDS", `Note: offset ${parsed.start} is beyond the end of ${parsed.file} (${totalLines} lines scanned). Retry with a smaller offset (e.g. start=${resume})`, { file: parsed.file, start: parsed.start, end: parsed.end, totalLines, resumeOffset: resume });
+    }
+    const endLine = selectedEnd ?? Math.max(wantedStart, totalLines);
+    const startLine = selectedStart ?? wantedStart;
     return {
-        file: parsed.file,
-        lines: { start: selectedStart ?? wantedStart, end: selectedEnd ?? Math.max(wantedStart, lineNumber - 1) },
+        window: { file: parsed.file, start: startLine, end: endLine },
         content,
         truncated,
+        ...(truncated
+            ? {
+                resumeOffset: endLine,
+                note: `truncated at line ${endLine}; resume with start=${endLine}`,
+            }
+            : {}),
     };
 }
 async function runSearch(runtime, context, command, query, options) {
@@ -225,6 +298,7 @@ async function runSearch(runtime, context, command, query, options) {
 }
 async function resolveReadableFile(root, ref, parsed) {
     const unresolved = resolve(root, parsed.file);
+    assertSafeReadPath(unresolved);
     if (!inside(root, unresolved))
         throw new RuntimeError("PATH_OUTSIDE_ROOT", `Ref escapes the project root: ${ref}`);
     let filePath;
@@ -331,7 +405,17 @@ export class SgrepCodeMode {
             const handle = await openStableHandle(root, ref, parsed.file, unresolved, filePath, expectedStat);
             try {
                 const budget = perRefChars + (index < remainder ? 1 : 0);
-                results.push({ ref, ...await readLineWindow(handle, parsed, contextLines, budget, options.signal) });
+                const payload = await readLineWindow(handle, parsed, contextLines, budget, options.signal);
+                const windowRef = payload.window
+                    ? formatReadRef(payload.window.file, payload.window.start, payload.window.end)
+                    : ref;
+                results.push({
+                    ref: windowRef,
+                    content: payload.content,
+                    truncated: payload.truncated,
+                    ...(payload.resumeOffset === undefined ? {} : { resumeOffset: payload.resumeOffset }),
+                    ...(payload.note === undefined ? {} : { note: payload.note }),
+                });
             }
             finally {
                 await handle.close();

package/dist/codemode/connector.d.ts

@@ -1,49 +1,77 @@
 import type { MachineEnvelope } from "../runtime.js";
 import type { ChainArgs, SearchArgs } from "./types.js";
 import { type BatchCapableHost, type DispatchStats } from "./dispatch.js";
+/**
+ * Spawn/CLI transport. Hosts provide argv `run` only — never a typed twin.
+ * Typed entry lives solely on {@link DispatchSurface} (dispatcher output).
+ */
 export type ConnectorHost = {
-    /** Typed tool call (preferred — no argv archaeology). */
-    call?(tool: string, args: Record<string, unknown>, context: {
+    run(args: readonly string[], context: {
         cwd: string;
     }, options?: {
         signal?: AbortSignal;
     }): Promise<MachineEnvelope>;
-    /** Legacy CLI argv (spawn fallback / direct tools). */
-    run(args: readonly string[], context: {
+};
+/**
+ * Trusted typed dispatch after coalescing. `call` is required; no argv peer
+ * that can disagree with tool+args.
+ */
+export type DispatchSurface = {
+    call(tool: string, args: Record<string, unknown>, context: {
         cwd: string;
     }, options?: {
         signal?: AbortSignal;
     }): Promise<MachineEnvelope>;
 };
 export type AsgrepConnector = {
-    search(input: SearchArgs): Promise<MachineEnvelope>;
-    semantic(input: SearchArgs): Promise<MachineEnvelope>;
-    chain(input: ChainArgs): Promise<MachineEnvelope>;
+    search(input: SearchArgs, options?: {
+        signal?: AbortSignal;
+    }): Promise<MachineEnvelope>;
+    semantic(input: SearchArgs, options?: {
+        signal?: AbortSignal;
+    }): Promise<MachineEnvelope>;
+    chain(input: ChainArgs, options?: {
+        signal?: AbortSignal;
+    }): Promise<MachineEnvelope>;
     defs(input: {
         symbol: string;
         limit?: number;
         excerptLines?: number;
+    }, options?: {
+        signal?: AbortSignal;
     }): Promise<MachineEnvelope>;
     callers(input: {
         symbol: string;
         limit?: number;
         excerptLines?: number;
+    }, options?: {
+        signal?: AbortSignal;
     }): Promise<MachineEnvelope>;
     imports(input: {
         module: string;
         limit?: number;
         excerptLines?: number;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<MachineEnvelope>;
+    indexStatus(options?: {
+        signal?: AbortSignal;
     }): Promise<MachineEnvelope>;
-    indexStatus(): Promise<MachineEnvelope>;
     indexRepo(input?: {
         force?: boolean;
+    }, options?: {
+        signal?: AbortSignal;
     }): Promise<MachineEnvelope>;
     /** Progressive discovery (like deferred tools) — list/filter available asgrep tools. */
     catalogSearch(input: {
         query: string;
+    }, options?: {
+        signal?: AbortSignal;
     }): Promise<MachineEnvelope>;
     catalogDescribe(input: {
         name: string;
+    }, options?: {
+        signal?: AbortSignal;
     }): Promise<MachineEnvelope>;
 };
 export type ConnectorBundle = {
@@ -52,7 +80,7 @@ export type ConnectorBundle = {
     resetStats: () => void;
 };
 /**
- * Host-side connector: typed methods the sandbox calls.
+ * Host-side connector: typed methods the Code Mode program calls.
  *
  * Same-tick calls (Promise.all) are coalesced by CodemodeDispatcher so N
  * lookups share sticky serve / one warm batch process when available.

package/dist/codemode/connector.js

@@ -11,59 +11,65 @@ function clampExcerpt(excerptLines) {
     return Math.min(100, Math.max(0, Math.trunc(excerptLines)));
 }
 /**
- * Host-side connector: typed methods the sandbox calls.
+ * Host-side connector: typed methods the Code Mode program calls.
  *
  * Same-tick calls (Promise.all) are coalesced by CodemodeDispatcher so N
  * lookups share sticky serve / one warm batch process when available.
  */
 export function createAsgrepConnector(host, context, options = {}) {
     const dispatcher = createCodemodeDispatcher(host);
-    const runOptions = options.signal ? { signal: options.signal } : {};
-    const call = (tool, args) => {
-        if (dispatcher.host.call) {
-            return dispatcher.host.call(tool, args, context, runOptions);
+    const combinedSignals = new WeakMap();
+    const callOptions = (signal) => {
+        if (!options.signal)
+            return signal ? { signal } : {};
+        if (!signal || signal === options.signal)
+            return { signal: options.signal };
+        let combined = combinedSignals.get(signal);
+        if (!combined) {
+            combined = AbortSignal.any([options.signal, signal]);
+            combinedSignals.set(signal, combined);
         }
-        // Should not happen — dispatcher always exposes call.
-        return dispatcher.host.run([], context, runOptions);
+        return { signal: combined };
     };
+    const call = (tool, args, signal) => dispatcher.host.call(tool, args, context, callOptions(signal));
     // Bound function properties (not methods) so vm call sites cannot lose `this`.
     const asgrep = {
-        search: (input) => call("search", {
+        search: (input, callOptions) => call("search", {
             query: input.query,
             limit: clampLimit(input.limit),
             excerpt_lines: clampExcerpt(input.excerptLines),
             format: input.format === "agent" ? "agent" : "capsule",
-        }),
-        semantic: (input) => call("semantic", {
+        }, callOptions?.signal),
+        semantic: (input, callOptions) => call("semantic", {
             query: input.query,
             limit: clampLimit(input.limit),
             excerpt_lines: clampExcerpt(input.excerptLines),
             format: input.format === "agent" ? "agent" : "capsule",
-        }),
-        chain: (input) => call("chain", {
+        }, callOptions?.signal),
+        chain: (input, callOptions) => call("chain", {
             query: input.query,
             limit: clampLimit(input.limit),
             top_n: 20,
-        }),
-        defs: (input) => call("defs", {
+        }, callOptions?.signal),
+        defs: (input, callOptions) => call("defs", {
             symbol: input.symbol,
             limit: clampLimit(input.limit),
             excerpt_lines: clampExcerpt(input.excerptLines),
-        }),
-        callers: (input) => call("callers", {
+        }, callOptions?.signal),
+        callers: (input, callOptions) => call("callers", {
             symbol: input.symbol,
             limit: clampLimit(input.limit),
             excerpt_lines: clampExcerpt(input.excerptLines),
-        }),
-        imports: (input) => call("imports", {
+        }, callOptions?.signal),
+        imports: (input, callOptions) => call("imports", {
             module: input.module,
             limit: clampLimit(input.limit),
             excerpt_lines: clampExcerpt(input.excerptLines),
-        }),
-        indexStatus: () => call("index_status", {}),
-        indexRepo: (input = {}) => call("index_repo", { force: input.force === true }),
-        catalogSearch: (input) => call("catalog_search", { query: input.query }),
-        catalogDescribe: (input) => call("catalog_describe", { name: input.name }),
+        }, 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),
     };
     return {
         asgrep,

package/dist/codemode/dispatch.d.ts

@@ -5,7 +5,7 @@
  * for the whole Code Mode program; batch coalescing kills it per Promise.all wave.
  */
 import type { MachineEnvelope } from "../runtime.js";
-import type { ConnectorHost } from "./connector.js";
+import type { ConnectorHost, DispatchSurface } from "./connector.js";
 export type CodemodeToolCall = {
     tool: string;
     args: Record<string, unknown>;
@@ -61,11 +61,10 @@ export type BatchCapableHost = ConnectorHost & {
  * one microtask wave. Prefers sticky serve → one-shot batch → overlapped spawn.
  */
 export declare function createCodemodeDispatcher(host: BatchCapableHost): {
-    host: ConnectorHost;
+    host: DispatchSurface;
     stats: () => DispatchStats;
     resetStats: () => void;
 };
-/** Build CLI argv for spawn fallback (typed path preferred). */
 export declare function argvFor(tool: string, args: Record<string, unknown>): string[];
 export declare function asEnvelope(value: unknown, command?: string): MachineEnvelope;
 /** One-shot batch via stdin (no tempfile) when spawn-with-stdin is available. */