pi-ast-sgrep 1.4.0 → 2.0.0

package/dist/runtime.js

@@ -1,16 +1,16 @@
-import { mkdir, mkdtemp, realpath, rename, rm } from "node:fs/promises";
-import { constants, accessSync, existsSync, realpathSync } from "node:fs";
-import { randomUUID } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import { constants, accessSync, existsSync, readdirSync, realpathSync, statSync, watch } from "node:fs";
 import { DatabaseSync } from "node:sqlite";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { resolveBinary } from "ast-sgrep";
-export const RUNTIME_VERSION = "1.4.0";
+export const RUNTIME_VERSION = "2.0.0";
 export const MACHINE_SCHEMA_VERSION = "1.0.0";
 export const CONFIG_SCHEMA_VERSION = 1;
-export const INDEX_FORMAT_VERSION = 7;
+export const INDEX_FORMAT_VERSION = 12;
 export const DEFAULT_TIMEOUT_MS = 30_000;
 export const DEFAULT_MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
 export const DEFAULT_REFRESH_INTERVAL_MS = 30_000;
+const MAX_TARGETED_INDEX_PATHS = 1_024;
 const RESOLVED_ROOT = Symbol("resolvedRoot");
 export class RuntimeError extends Error {
     code;
@@ -112,7 +112,8 @@ export function resolveConfig(sources = {}) {
 }
 function pathContained(parent, child) {
     const rel = relative(parent, child);
-    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+    const first = rel.split(/[\\/]/u, 1)[0];
+    return rel === "" || (!isAbsolute(rel) && first !== "..");
 }
 export async function resolveRuntimeRoot(projectCwd, requestedRoot, allowOutsideProject = false) {
     let project;
@@ -132,7 +133,7 @@ export async function resolveRuntimeRoot(projectCwd, requestedRoot, allowOutside
 function record(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value) ? value : undefined;
 }
-function indexHealth(status) {
+function indexHealth(status, knownExisting = false) {
     const index = record(status.index);
     const state = typeof index?.status === "string" ? index.status :
         typeof status.index_status === "string" ? status.index_status : undefined;
@@ -143,7 +144,7 @@ function indexHealth(status) {
     if (state === "ready" || state === "current" || index?.exists === true || status.indexed === true)
         return "ready";
     if (typeof status.index_path === "string" && typeof status.file_count === "number") {
-        return status.file_count === 0 ? "missing" : "ready";
+        return knownExisting || status.file_count > 0 ? "ready" : "missing";
     }
     throw new RuntimeError("INDEX_STATUS_UNKNOWN", "ast-sgrep status did not report index freshness", { index: status.index, index_status: status.index_status });
 }
@@ -153,9 +154,63 @@ function incompatibleStatusFailure(cause) {
     const text = `${cause.message} ${JSON.stringify(cause.details)}`;
     return /incompatib|unsupported.{0,24}schema|schema.{0,24}(version|mismatch)/i.test(text);
 }
+/** Probe compatibility hook then status; map incompat operational failures to health. */
+async function probeIndexHealth(runtime, rootContext, options) {
+    const hinted = await runtime.inspectIndexCompatibility?.(rootContext);
+    if (hinted === "missing" || hinted === "incompatible")
+        return hinted;
+    try {
+        const status = runtime.nativeCall
+            ? await runtime.nativeCall("index_status", {}, rootContext, options)
+            : await runtime.run(["status", ".", "--json"], rootContext, options);
+        return indexHealth(status, hinted === "ready");
+    }
+    catch (cause) {
+        if (!incompatibleStatusFailure(cause))
+            throw cause;
+        return "incompatible";
+    }
+}
+function indexCompletion(response, requireWalkErrors) {
+    const stats = record(response.stats) ?? response;
+    const failed = stats.files_failed;
+    const walkErrors = stats.walk_errors;
+    if (!Number.isSafeInteger(failed) || failed < 0
+        || (requireWalkErrors ? typeof walkErrors !== "boolean" : walkErrors !== undefined && typeof walkErrors !== "boolean")) {
+        throw new RuntimeError("INDEX_RESPONSE_INVALID", "ast-sgrep index response omitted valid completion status", { filesFailed: failed, walkErrors, requireWalkErrors });
+    }
+    return {
+        failed: failed,
+        walkErrors: walkErrors === true,
+    };
+}
+/** Run index_repo via native sticky pool or CLI argv. force=true → reindex. */
+async function runIndex(runtime, force, rootContext, options) {
+    const response = runtime.nativeCall
+        ? await runtime.nativeCall("index_repo", { force }, rootContext, options)
+        : await runtime.run([force ? "reindex" : "index", ".", "--json"], rootContext, options);
+    const { failed, walkErrors } = indexCompletion(response, true);
+    if (failed > 0 || walkErrors) {
+        throw new RuntimeError("INDEX_UPDATE_INCOMPLETE", "ast-sgrep did not complete the full index reconciliation", { failed, walkErrors, force });
+    }
+}
+/** Update known changed paths without walking the repository. */
+async function runTargetedIndex(runtime, paths, rootContext, options) {
+    for (let offset = 0; offset < paths.length; offset += MAX_TARGETED_INDEX_PATHS) {
+        const chunk = paths.slice(offset, offset + MAX_TARGETED_INDEX_PATHS);
+        const response = runtime.nativeCall
+            ? await runtime.nativeCall("index_repo", { paths: chunk }, rootContext, options)
+            : await runtime.run(["index", ".", "--json", ...chunk.flatMap((path) => ["--path", path])], rootContext, options);
+        const { failed } = indexCompletion(response, false);
+        if (failed > 0) {
+            throw new RuntimeError("INDEX_UPDATE_INCOMPLETE", `ast-sgrep failed to update ${failed} changed path${failed === 1 ? "" : "s"}`, { failed, pathCount: chunk.length });
+        }
+    }
+}
 function canonicalizeAffectedPath(path) {
-    const unresolved = [];
-    let existing = resolve(path);
+    const absolute = resolve(path);
+    const unresolved = [basename(absolute)];
+    let existing = dirname(absolute);
     for (;;) {
         try {
             return resolve(realpathSync(existing), ...unresolved.reverse());
@@ -170,106 +225,296 @@ function canonicalizeAffectedPath(path) {
         }
     }
 }
+function canonicalizeRootPath(path) {
+    try {
+        return realpathSync(resolve(path));
+    }
+    catch {
+        return canonicalizeAffectedPath(path);
+    }
+}
+function changesIgnoreRules(path) {
+    const name = basename(path);
+    return name === ".gitignore" || name === ".ignore" || name === ".asgrepignore";
+}
+function ignoredIndexWrite(root, path, indexPath) {
+    const defaultIndexDirectory = join(root, ".asgrep");
+    if (pathContained(defaultIndexDirectory, path))
+        return true;
+    const indexDirectory = dirname(indexPath);
+    if (dirname(path) !== indexDirectory)
+        return false;
+    const name = basename(path);
+    const sqliteArtifact = (database) => {
+        const suffix = name.slice(database.length);
+        return name.startsWith(database) && (suffix === ""
+            || suffix === "-wal"
+            || suffix === "-shm"
+            || suffix === "-journal"
+            || suffix === ".reindex.lock"
+            || /^\.corrupt(?:\.\d+)?(?:-(?:wal|shm|journal))?$/u.test(suffix));
+    };
+    return sqliteArtifact(basename(indexPath))
+        || sqliteArtifact("lexical.db")
+        || name === "semantic.ivf"
+        || (name.startsWith(".semantic.ivf.") && name.endsWith(".tmp"));
+}
+function existingDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function markStatePathDirty(state, path) {
+    state.dirtyGeneration += 1;
+    if (changesIgnoreRules(path)) {
+        state.dirtyPaths.clear();
+        state.fullScanRequired = true;
+    }
+    else if (!state.fullScanRequired) {
+        if (!state.dirtyPaths.has(path) && state.dirtyPaths.size >= MAX_TARGETED_INDEX_PATHS) {
+            state.dirtyPaths.clear();
+            state.fullScanRequired = true;
+        }
+        else {
+            state.dirtyPaths.add(path);
+        }
+    }
+}
+function markStateFullScan(state) {
+    state.dirtyGeneration += 1;
+    state.dirtyPaths.clear();
+    state.fullScanRequired = true;
+}
+function cancelledRefreshWait() {
+    return new RuntimeError("CANCELLED", "ast-sgrep freshness wait was cancelled");
+}
+/** Stop one caller waiting without transferring cancellation ownership to shared work. */
+function waitForRefresh(refresh, signal) {
+    if (!signal)
+        return refresh;
+    if (signal.aborted)
+        return Promise.reject(cancelledRefreshWait());
+    return new Promise((resolveWait, rejectWait) => {
+        const onAbort = () => {
+            signal.removeEventListener("abort", onAbort);
+            rejectWait(cancelledRefreshWait());
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        refresh.then(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolveWait();
+        }, (cause) => {
+            signal.removeEventListener("abort", onAbort);
+            rejectWait(cause);
+        });
+    });
+}
 export class FreshnessCoordinator {
     #states = new Map();
-    #pendingPaths = new Set();
+    #pending = new Map();
     #interval;
     #now;
+    #watchFactory;
     constructor(options = {}) {
         this.#interval = finitePositive(options.refreshIntervalMs, DEFAULT_REFRESH_INTERVAL_MS, "refreshIntervalMs");
         this.#now = options.now ?? Date.now;
+        this.#watchFactory = options.watchFactory ?? watch;
     }
     markAffectedPath(path, cwd) {
         const affected = canonicalizeAffectedPath(isAbsolute(path) ? path : resolve(canonicalizeAffectedPath(cwd), path));
-        this.#pendingPaths.add(affected);
+        let matched = false;
         for (const [root, state] of this.#states) {
-            if (pathContained(root, affected))
-                state.dirtyGeneration += 1;
+            if (!pathContained(root, affected))
+                continue;
+            markStatePathDirty(state, affected);
+            matched = true;
+        }
+        if (!matched) {
+            const pendingRoot = canonicalizeRootPath(cwd);
+            // Before root resolution, the caller's cwd is the only trustworthy
+            // confinement boundary. Do not retain unrelated/escaping paths forever.
+            if (!pathContained(pendingRoot, affected))
+                return;
+            let pending = this.#pending.get(pendingRoot);
+            if (!pending) {
+                pending = { paths: new Set(), fullScanRequired: false, consumedFullScanRoots: new Set() };
+                this.#pending.set(pendingRoot, pending);
+            }
+            if (changesIgnoreRules(affected)) {
+                pending.paths.clear();
+                pending.fullScanRequired = true;
+            }
+            else if (!pending.fullScanRequired) {
+                if (!pending.paths.has(affected) && pending.paths.size >= MAX_TARGETED_INDEX_PATHS) {
+                    pending.paths.clear();
+                    pending.fullScanRequired = true;
+                }
+                else {
+                    pending.paths.add(affected);
+                }
+            }
         }
     }
     markRootDirty(root) {
-        const canonical = canonicalizeAffectedPath(root);
+        const canonical = canonicalizeRootPath(root);
         const state = this.#states.get(canonical);
-        if (state)
-            state.dirtyGeneration += 1;
-        else
-            this.#pendingPaths.add(canonical);
+        if (state) {
+            markStateFullScan(state);
+        }
+        else {
+            this.#pending.set(canonical, {
+                paths: new Set(),
+                fullScanRequired: true,
+                consumedFullScanRoots: new Set(),
+            });
+        }
     }
     async ensureFresh(runtime, context, options = {}) {
         const root = await runtime.resolveRoot(context);
         const rootContext = { cwd: root, [RESOLVED_ROOT]: true };
         let state = this.#states.get(root);
         if (!state) {
-            state = { dirtyGeneration: 0, cleanGeneration: 0, initialized: false, lastRefreshAt: 0, inFlight: undefined };
+            state = {
+                dirtyGeneration: 0,
+                cleanGeneration: 0,
+                dirtyPaths: new Set(),
+                fullScanRequired: false,
+                initialized: false,
+                lastRefreshAt: 0,
+                inFlight: undefined,
+                watcher: undefined,
+            };
             this.#states.set(root, state);
         }
-        for (const path of this.#pendingPaths) {
-            if (!pathContained(root, path))
+        if (runtime.watchExternalChanges && state.watcher === undefined) {
+            const indexPath = canonicalizeAffectedPath(runtime.resolveIndexPath?.(root) ?? join(root, ".asgrep", "index.db"));
+            this.#startWatcher(root, state, indexPath);
+        }
+        for (const [pendingRoot, pending] of this.#pending) {
+            if (!pathContained(pendingRoot, root) && !pathContained(root, pendingRoot))
                 continue;
-            state.dirtyGeneration += 1;
-            this.#pendingPaths.delete(path);
+            if (pending.fullScanRequired) {
+                if (!pending.consumedFullScanRoots.has(root)) {
+                    markStateFullScan(state);
+                    pending.consumedFullScanRoots.add(root);
+                }
+                continue;
+            }
+            for (const path of pending.paths) {
+                if (!pathContained(root, path))
+                    continue;
+                markStatePathDirty(state, path);
+                pending.paths.delete(path);
+            }
+            if (pending.paths.size === 0)
+                this.#pending.delete(pendingRoot);
         }
         if (state.inFlight) {
-            await state.inFlight;
+            await waitForRefresh(state.inFlight, options.signal);
             return this.ensureFresh(runtime, rootContext, options);
         }
         const now = this.#now();
         const elapsed = now - state.lastRefreshAt;
+        // Lease expiry: initialized and interval elapsed (or clock went backwards).
         const expired = state.initialized && (elapsed < 0 || elapsed >= this.#interval);
         if (state.initialized && state.cleanGeneration === state.dirtyGeneration && !expired)
             return root;
         const refreshGeneration = state.dirtyGeneration;
-        const wasInitialized = state.initialized;
+        const refreshPaths = [...state.dirtyPaths];
+        const fullScanRequired = state.fullScanRequired;
+        // Correctness work belongs to the root, not to whichever request happened
+        // to start it. Individual callers may stop waiting, but cannot cancel the
+        // shared refresh while other callers depend on it.
+        const sharedOptions = {};
+        if (options.timeoutMs !== undefined)
+            sharedOptions.timeoutMs = options.timeoutMs;
+        if (options.env !== undefined)
+            sharedOptions.env = options.env;
         const refresh = (async () => {
-            let health = await runtime.inspectIndexCompatibility?.(rootContext);
-            if (health !== "incompatible") {
-                try {
-                    const status = runtime.nativeCall
-                        ? await runtime.nativeCall("index_status", {}, rootContext, options)
-                        : await runtime.run(["status", ".", "--json"], rootContext, options);
-                    health = indexHealth(status);
-                }
-                catch (cause) {
-                    if (!incompatibleStatusFailure(cause))
-                        throw cause;
-                    health = "incompatible";
-                }
-            }
+            const health = await probeIndexHealth(runtime, rootContext, sharedOptions);
             const dirty = refreshGeneration > state.cleanGeneration;
             if (health === "incompatible") {
+                // Requisite variety: force rebuild path (hook or reindex).
                 if (runtime.rebuildIncompatibleIndex)
-                    await runtime.rebuildIncompatibleIndex(rootContext, options);
-                else if (runtime.nativeCall)
-                    await runtime.nativeCall("index_repo", { force: true }, rootContext, options);
+                    await runtime.rebuildIncompatibleIndex(rootContext, sharedOptions);
                 else
-                    await runtime.run(["reindex", ".", "--json"], rootContext, options);
+                    await runIndex(runtime, true, rootContext, sharedOptions);
             }
-            else if (health === "missing" || !wasInitialized || dirty) {
-                if (runtime.nativeCall)
-                    await runtime.nativeCall("index_repo", { force: false }, rootContext, options);
-                else
-                    await runtime.run(["index", ".", "--json"], rootContext, options);
+            else if (health === "missing" || !state.initialized || expired || (dirty && (fullScanRequired || refreshPaths.length === 0))) {
+                await runIndex(runtime, false, rootContext, sharedOptions);
             }
-            else if (expired) {
-                // Lease expired without dirty marks: incremental index (not force reindex)
-                // so external create/modify/delete are reconciled without rebuild thrash (5du.9).
-                if (runtime.nativeCall)
-                    await runtime.nativeCall("index_repo", { force: false }, rootContext, options);
-                else
-                    await runtime.run(["index", ".", "--json"], rootContext, options);
+            else if (dirty) {
+                await runTargetedIndex(runtime, refreshPaths, rootContext, sharedOptions);
             }
             state.initialized = true;
             state.cleanGeneration = refreshGeneration;
+            if (state.dirtyGeneration === refreshGeneration) {
+                state.dirtyPaths.clear();
+                state.fullScanRequired = false;
+            }
             state.lastRefreshAt = this.#now();
         })();
-        state.inFlight = refresh;
+        let tracked;
+        tracked = refresh.finally(() => {
+            if (state.inFlight === tracked)
+                state.inFlight = undefined;
+        });
+        state.inFlight = tracked;
+        // If every waiter is cancelled, the root-owned refresh still needs a
+        // rejection handler while it finishes in the background.
+        void tracked.catch(() => undefined);
+        await waitForRefresh(tracked, options.signal);
+        if (state.cleanGeneration !== state.dirtyGeneration) {
+            return this.ensureFresh(runtime, rootContext, options);
+        }
+        return root;
+    }
+    shutdown() {
+        for (const state of this.#states.values())
+            state.watcher?.close();
+        this.#states.clear();
+        this.#pending.clear();
+    }
+    #startWatcher(root, state, indexPath) {
+        if (!existsSync(root)) {
+            state.watcher = null;
+            markStateFullScan(state);
+            return;
+        }
         try {
-            await refresh;
-            return root;
+            const watcher = this.#watchFactory(root, { recursive: true, persistent: false, encoding: "utf8" }, (eventType, filename) => {
+                if (!filename) {
+                    markStateFullScan(state);
+                    return;
+                }
+                const affected = canonicalizeAffectedPath(join(root, filename));
+                if (ignoredIndexWrite(root, affected, indexPath))
+                    return;
+                if (eventType === "rename" || existingDirectory(affected)) {
+                    markStateFullScan(state);
+                    return;
+                }
+                markStatePathDirty(state, affected);
+            });
+            watcher.on("error", () => {
+                watcher.close();
+                // Watcher errors (including backend overflow) make event history
+                // unknowable. Scan once, then rely on the periodic correctness lease;
+                // retrying a permanently broken watcher on every request hot-loops.
+                if (state.watcher === watcher)
+                    state.watcher = null;
+                markStateFullScan(state);
+            });
+            state.watcher = watcher;
         }
-        finally {
-            if (state.inFlight === refresh)
-                state.inFlight = undefined;
+        catch {
+            // Do one correctness scan now, then rely on periodic scans instead of
+            // retrying (and rescanning) on every query on unsupported filesystems.
+            state.watcher = null;
+            markStateFullScan(state);
         }
     }
 }
@@ -297,38 +542,61 @@ function getBinary(config, env, resolver) {
 function byteLength(value) { return Buffer.byteLength(value, "utf8"); }
 /** Present-field version identity checks. Pass `requireIdentity` for version --json. */
 function assertVersionTriple(envelope, requireIdentity = false) {
-    if (requireIdentity || envelope.version !== undefined) {
-        if (envelope.version !== RUNTIME_VERSION) {
-            throw new RuntimeError("VERSION_MISMATCH", "ast-sgrep binary version does not match the extension", { expected: RUNTIME_VERSION, actual: envelope.version });
-        }
+    // Compound guards (same short-circuit as nested if): check only when required or field present.
+    if ((requireIdentity || envelope.version !== undefined) && envelope.version !== RUNTIME_VERSION) {
+        throw new RuntimeError("VERSION_MISMATCH", "ast-sgrep binary version does not match the extension", { expected: RUNTIME_VERSION, actual: envelope.version });
     }
-    if (requireIdentity || envelope.machine_schema_version !== undefined) {
-        if (envelope.machine_schema_version !== MACHINE_SCHEMA_VERSION) {
-            throw new RuntimeError("PROTOCOL_MISMATCH", "ast-sgrep binary reports an incompatible machine protocol", { expected: MACHINE_SCHEMA_VERSION, actual: envelope.machine_schema_version });
+    if ((requireIdentity || envelope.machine_schema_version !== undefined) && envelope.machine_schema_version !== MACHINE_SCHEMA_VERSION) {
+        throw new RuntimeError("PROTOCOL_MISMATCH", "ast-sgrep binary reports an incompatible machine protocol", { expected: MACHINE_SCHEMA_VERSION, actual: envelope.machine_schema_version });
+    }
+}
+/**
+ * Nonzero CLI exit: prefer structured failed envelope (OPERATIONAL_ERROR), else PROCESS_FAILED.
+ * Always throws — error-path extract so parseEnvelope keeps success-path protocol field checks.
+ */
+function throwNonzeroProcessFailure(result, code) {
+    try {
+        const value = record(JSON.parse(result.stdout));
+        // Wire-valid ok:false asgrep envelope → structured operational failure (not PROCESS_FAILED).
+        if (value && value.tool === "asgrep" && value.schema_version === MACHINE_SCHEMA_VERSION && value.ok === false) {
+            const failure = record(value.error);
+            const message = typeof failure?.message === "string" ? failure.message : "ast-sgrep reported an operational failure";
+            throw new RuntimeError("OPERATIONAL_ERROR", message, { command: value.command, error: failure, exitCode: code });
         }
     }
+    catch (cause) {
+        if (cause instanceof RuntimeError)
+            throw cause;
+    }
+    throw new RuntimeError("PROCESS_FAILED", `ast-sgrep exited with code ${code}`, {
+        exitCode: code,
+        signal: result.signal ?? undefined,
+        stderr: result.stderr.slice(0, 1024),
+    });
+}
+/** Map exec failures (abort / timeout / generic) to RuntimeError. Re-throws RuntimeError as-is. */
+function rethrowExecFailure(cause, options, timeout) {
+    if (cause instanceof RuntimeError)
+        throw cause;
+    if (options.signal?.aborted || (cause instanceof Error && cause.name === "AbortError")) {
+        throw new RuntimeError("CANCELLED", "ast-sgrep execution was cancelled");
+    }
+    const message = cause instanceof Error ? cause.message : String(cause);
+    if (/timeout|timed out/i.test(message)) {
+        throw new RuntimeError("TIMEOUT", `ast-sgrep exceeded ${timeout}ms`, { timeoutMs: timeout });
+    }
+    throw new RuntimeError("EXEC_FAILED", "Unable to execute ast-sgrep", { cause: message });
 }
 function parseEnvelope(result, limit) {
     const stdoutBytes = byteLength(result.stdout);
     const stderrBytes = byteLength(result.stderr);
-    if (stdoutBytes > limit || stderrBytes > limit || stdoutBytes + stderrBytes > limit) {
+    // Byte lengths are non-negative: sum > limit covers either-side overflow and combined cap.
+    if (stdoutBytes + stderrBytes > limit) {
         throw new RuntimeError("OUTPUT_LIMIT", "ast-sgrep output exceeded the configured limit", { limit, stdoutBytes, stderrBytes });
     }
     const code = result.exitCode ?? result.code ?? 0;
     if (code !== 0) {
-        try {
-            const value = JSON.parse(result.stdout);
-            if (value && typeof value === "object" && value.tool === "asgrep" && value.schema_version === MACHINE_SCHEMA_VERSION && value.ok === false) {
-                const failure = record(value.error);
-                const message = typeof failure?.message === "string" ? failure.message : "ast-sgrep reported an operational failure";
-                throw new RuntimeError("OPERATIONAL_ERROR", message, { command: value.command, error: failure, exitCode: code });
-            }
-        }
-        catch (cause) {
-            if (cause instanceof RuntimeError)
-                throw cause;
-        }
-        throw new RuntimeError("PROCESS_FAILED", `ast-sgrep exited with code ${code}`, { exitCode: code, signal: result.signal ?? undefined, stderr: result.stderr.slice(0, 1024) });
+        throwNonzeroProcessFailure(result, code);
     }
     let value;
     try {
@@ -337,9 +605,10 @@ function parseEnvelope(result, limit) {
     catch (cause) {
         throw new RuntimeError("MALFORMED_OUTPUT", "ast-sgrep returned malformed JSON", { cause: cause instanceof Error ? cause.message : String(cause) });
     }
-    if (!value || typeof value !== "object" || Array.isArray(value))
+    const envelope = record(value);
+    if (!envelope)
         throw new RuntimeError("MALFORMED_OUTPUT", "ast-sgrep returned a non-object JSON payload");
-    const envelope = value;
+    // Protocol field varieties (Ashby Keep) — sequential wire-contract checks stay here.
     if (envelope.tool !== "asgrep")
         throw new RuntimeError("TOOL_MISMATCH", "Response is not from ast-sgrep", { actual: envelope.tool });
     if (envelope.schema_version !== MACHINE_SCHEMA_VERSION)
@@ -347,6 +616,7 @@ function parseEnvelope(result, limit) {
     if (typeof envelope.ok !== "boolean")
         throw new RuntimeError("MALFORMED_OUTPUT", "ast-sgrep response is missing boolean ok");
     if (!envelope.ok) {
+        // Preserve pre-extract failure shape: plain object check (arrays allowed as error bag).
         const failure = envelope.error && typeof envelope.error === "object" ? envelope.error : undefined;
         const message = typeof failure?.message === "string" ? failure.message : "ast-sgrep reported an operational failure";
         throw new RuntimeError("OPERATIONAL_ERROR", message, { command: envelope.command, error: failure });
@@ -361,6 +631,34 @@ function indexPathFor(root, env) {
     const resolved = resolve(root, configured);
     return extname(resolved) === ".db" ? resolved : join(resolved, "index.db");
 }
+function indexQuarantines(indexPath) {
+    const quarantinePrefix = `${basename(indexPath)}.corrupt`;
+    try {
+        return readdirSync(dirname(indexPath), { withFileTypes: true })
+            .filter((entry) => entry.isFile() && (entry.name === quarantinePrefix || entry.name.startsWith(`${quarantinePrefix}.`)))
+            .map((entry) => join(dirname(indexPath), entry.name))
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/** Classify a rebuild failure and identify recovery copies made by this attempt. */
+function throwIndexRebuildFailed(cause, indexPath, quarantinesBefore) {
+    const newQuarantines = indexQuarantines(indexPath).filter((path) => !quarantinesBefore.has(path));
+    const recoveryPaths = [
+        ...newQuarantines,
+        ...(existsSync(indexPath) ? [indexPath] : []),
+    ];
+    throw new RuntimeError("INDEX_REBUILD_FAILED", "Incompatible index rebuild failed; the prior index remains recoverable", {
+        indexPath,
+        recoveryPath: recoveryPaths[0] ?? indexPath,
+        recoveryPaths,
+        priorIndexPreserved: recoveryPaths.length > 0,
+        expectedIndexFormat: INDEX_FORMAT_VERSION,
+        cause: cause instanceof Error ? cause.message : String(cause),
+    });
+}
 function inspectIndexFile(path) {
     if (!existsSync(path))
         return "missing";
@@ -389,6 +687,7 @@ function inspectIndexFile(path) {
 }
 export class AstSgrepRuntime {
     pi;
+    watchExternalChanges = true;
     config;
     #resolver;
     #environment;
@@ -403,6 +702,9 @@ export class AstSgrepRuntime {
             ? resolveRuntimeRoot(context.cwd)
             : resolveRuntimeRoot(context.cwd, this.config.root, this.config.allowOutsideProject);
     }
+    resolveIndexPath(root) {
+        return indexPathFor(root, { ...this.#environment, ...this.config.env });
+    }
     async inspectIndexCompatibility(context) {
         const root = await this.resolveRoot(context);
         return inspectIndexFile(indexPathFor(root, { ...this.#environment, ...this.config.env }));
@@ -411,50 +713,23 @@ export class AstSgrepRuntime {
         const root = await this.resolveRoot(context);
         const env = { ...this.#environment, ...this.config.env, ...options.env };
         const indexPath = indexPathFor(root, env);
-        const parent = dirname(indexPath);
-        await mkdir(parent, { recursive: true });
-        const temporaryDirectory = await mkdtemp(join(parent, ".rebuild-"));
-        const replacementPath = join(temporaryDirectory, "index.db");
-        const backupPath = `${indexPath}.backup-${randomUUID()}`;
-        let priorMoved = false;
+        const quarantinesBefore = new Set(indexQuarantines(indexPath));
         try {
-            const response = await this.run(["--index-path", replacementPath, "index", ".", "--json"], { cwd: root }, options);
-            if (inspectIndexFile(replacementPath) !== "ready") {
-                throw new RuntimeError("INDEX_REBUILD_INVALID", "Replacement index has an incompatible format", { expected: INDEX_FORMAT_VERSION });
+            // Core reindex prepares files before opening one bulk transaction and
+            // commits rewrites plus stale-row pruning together. Keeping the same DB
+            // inode avoids stale warm NAPI sessions and removes rename crash windows.
+            const response = await this.run(["reindex", ".", "--json"], { cwd: root }, options);
+            const { failed, walkErrors } = indexCompletion(response, true);
+            if (failed > 0 || walkErrors) {
+                throw new RuntimeError("INDEX_UPDATE_INCOMPLETE", "ast-sgrep did not complete the incompatible-index rebuild", { failed, walkErrors, force: true });
             }
-            if (existsSync(indexPath)) {
-                await rename(indexPath, backupPath);
-                priorMoved = true;
+            if (inspectIndexFile(indexPath) !== "ready") {
+                throw new RuntimeError("INDEX_REBUILD_INVALID", "Rebuilt index has an incompatible format", { expected: INDEX_FORMAT_VERSION });
             }
-            try {
-                await rename(replacementPath, indexPath);
-            }
-            catch (cause) {
-                if (priorMoved)
-                    await rename(backupPath, indexPath);
-                throw cause;
-            }
-            if (priorMoved)
-                await rm(backupPath, { force: true });
             return response;
         }
         catch (cause) {
-            let recoveryPath = indexPath;
-            let priorIndexPreserved = existsSync(indexPath);
-            if (priorMoved && !priorIndexPreserved && existsSync(backupPath)) {
-                recoveryPath = backupPath;
-                priorIndexPreserved = true;
-            }
-            throw new RuntimeError("INDEX_REBUILD_FAILED", "Incompatible index rebuild failed; the prior index remains recoverable", {
-                indexPath,
-                recoveryPath,
-                priorIndexPreserved,
-                expectedIndexFormat: INDEX_FORMAT_VERSION,
-                cause: cause instanceof Error ? cause.message : String(cause),
-            });
-        }
-        finally {
-            await rm(temporaryDirectory, { recursive: true, force: true });
+            throwIndexRebuildFailed(cause, indexPath, quarantinesBefore);
         }
     }
     async run(args, context, options = {}) {
@@ -474,14 +749,7 @@ export class AstSgrepRuntime {
             return parseEnvelope(result, this.config.maxOutputBytes);
         }
         catch (cause) {
-            if (cause instanceof RuntimeError)
-                throw cause;
-            if (options.signal?.aborted || (cause instanceof Error && cause.name === "AbortError"))
-                throw new RuntimeError("CANCELLED", "ast-sgrep execution was cancelled");
-            const message = cause instanceof Error ? cause.message : String(cause);
-            if (/timeout|timed out/i.test(message))
-                throw new RuntimeError("TIMEOUT", `ast-sgrep exceeded ${timeout}ms`, { timeoutMs: timeout });
-            throw new RuntimeError("EXEC_FAILED", "Unable to execute ast-sgrep", { cause: message });
+            rethrowExecFailure(cause, options, timeout);
         }
     }
     /** Absolute path to the native binary (for sticky serve / stdin batch spawn). */