@herbertgao/pi-extensions 2026.8.6 → 2026.8.7

package/node_modules/pi-lens/dist/clients/safe-spawn.js

@@ -763,6 +763,21 @@ function ensureUtf8ConsoleCodePageOnce() {
 export function resetUtf8ConsoleCodePageStateForTests() {
     utf8ConsoleCodePageApplied = false;
 }
+// #1656: post-exit pipe-idle wait constants. Node's "close" event only fires
+// once every stdio fd referencing the child has been released — a
+// daemonized descendant that inherited our stdout/stderr pipe (the Windows
+// no-job-object case) can hold that fd open forever, hanging "close" even
+// though the child we spawned is long dead. A fixed post-exit deadline
+// avoids that hang but truncates a legitimately still-streaming child. The
+// idle-grace construction (adopted from pi's `waitForChildProcess`) does
+// neither: after "exit", wait for the pipes to go quiet — no data for
+// EXIT_PIPE_IDLE_GRACE_MS, re-armed on every chunk — so a quiet inherited
+// handle still releases after one grace window while an actively-writing
+// descendant keeps being read. EXIT_PIPE_IDLE_MAX_WAIT_MS caps the total
+// extra wait so a pathological, never-quiet descendant can't extend the
+// caller's overall budget unboundedly.
+const EXIT_PIPE_IDLE_GRACE_MS = 100;
+const EXIT_PIPE_IDLE_MAX_WAIT_MS = 2000;
 // ============================================================================
 // ASYNC VERSION (Recommended - Non-blocking)
 // ============================================================================
@@ -825,7 +840,18 @@ export async function safeSpawnAsync(command, args, options) {
         let aborted = false;
         let killed = false;
         let outputTruncated = false;
-        let spawnErrored = false;
+        // #1651 review: a single boolean the close/error handlers both check
+        // AND set, so whichever one decides the outcome first wins outright —
+        // the DECISION itself is shape-based (see the `close` handler below),
+        // this flag only stops the loser from resolving a second time.
+        let resolved = false;
+        // The most recent 'error' Error, captured the instant the event fires
+        // regardless of whether that handler goes on to resolve. The `close`
+        // handler's shape-based branch (code === null || code < 0) reads this
+        // when it decides FIRST, so a genuinely informative ENOENT/EACCES/etc.
+        // Error is used when it happens to already be available, instead of
+        // always falling back to a generic synthesized one.
+        let pendingSpawnError;
         // #1109: the non-Windows SIGTERM→SIGKILL escalation timer (armed in
         // killTree below). Stored per-call (never shared) so the close/error
         // handlers can clear it if the child exits before it fires — same
@@ -841,6 +867,11 @@ export async function safeSpawnAsync(command, args, options) {
         // any `await`, so a timer firing during the close handler's `await
         // killPromise` still observes the flag correctly).
         let closed = false;
+        // #1656: set only while the post-exit idle-pipe wait is active (see
+        // waitForPipeIdle below); the stdout/stderr "data" handlers call this to
+        // re-arm the grace timer on every chunk. `undefined` before exit / after
+        // the wait settles, so the calls below are no-ops outside that window.
+        let rearmIdleGrace;
         const maxOutputBytes = options?.maxOutputBytes !== undefined &&
             Number.isFinite(options.maxOutputBytes) &&
             options.maxOutputBytes > 0
@@ -996,7 +1027,7 @@ export async function safeSpawnAsync(command, args, options) {
             lifetimeState.pids.add(child.pid);
         }
         // #620: bracket this spawn's lifetime with a short-interval CPU/RSS poll
-        // (started right here, stopped in the "close" handler below) so transient
+        // (started right here, stopped in finalize() below) so transient
         // analyzer children (jscpd, knip, madge, gitleaks, etc.) — which live too
         // briefly for heartbeat-cadence sampling to reliably catch — still get a
         // peak/average resource reading. `startSpawnUsageSampler` itself is
@@ -1052,7 +1083,7 @@ export async function safeSpawnAsync(command, args, options) {
             }
         };
         abortSignal?.addEventListener("abort", onAbort, { once: true });
-        // Output-cap kills are awaited by the close handler below, just like
+        // Output-cap kills are awaited by finalize() below, just like
         // timeout/abort kills. This keeps a noisy CLI from continuing in the
         // background after its retained output has been bounded.
         let killPromise;
@@ -1068,10 +1099,28 @@ export async function safeSpawnAsync(command, args, options) {
         child.stdout?.on("data", (data) => {
             stdout = appendOutput(stdout, data);
             stopForOutputLimit();
+            rearmIdleGrace?.();
         });
         child.stderr?.on("data", (data) => {
             stderr = appendOutput(stderr, data);
             stopForOutputLimit();
+            rearmIdleGrace?.();
+        });
+        // #1673 review round 3 (F2): registered HERE, at spawn time, alongside
+        // the other handlers above — not inside `waitForPipeIdle`. Real Node
+        // emits `close` a fraction of a millisecond after `exit` (both fire in
+        // the same "process exit" turn, well before any microtask), so a
+        // listener attached inside `waitForPipeIdle` — which `finalize` only
+        // reaches after `await killPromise`, at least one microtask later — is
+        // always attaching to an event that has already happened. That's why
+        // the round-2 `child.on("close", finish)` placed inside
+        // `waitForPipeIdle` never actually caught a real spawn's `close` early:
+        // every real call still paid the full grace window. Capturing the
+        // boolean here, before any await, means `waitForPipeIdle` can check
+        // "did close already happen" synchronously the moment it runs.
+        let closeSeen = false;
+        child.on("close", () => {
+            closeSeen = true;
         });
         // Timeout handling - KILL the process, don't just abandon it
         const timeoutId = setTimeout(() => {
@@ -1105,23 +1154,144 @@ export async function safeSpawnAsync(command, args, options) {
             }
             return summary;
         };
+        // #1656: wait for stdout/stderr to fall idle after exit instead of
+        // waiting for Node's "close" event (see the constants' doc comment
+        // above). Resolves immediately if the child has no pipes to drain.
+        //
+        // These timers stay REF'D, matching `timeoutId`/`escalationTimer`
+        // elsewhere in this function: the caller's own settlement depends on
+        // them firing, so unref'ing would let a short-lived host process (a
+        // one-shot CLI whose only other in-flight work was this spawn) exit
+        // the event loop before `finish` ever runs — silently abandoning this
+        // promise instead of merely leaking a handle. Both paths to `finish`
+        // clear both timers, so nothing outlives settlement either way.
+        const waitForPipeIdle = () => {
+            if (!child.stdout && !child.stderr)
+                return Promise.resolve();
+            // #1673 review round 3 (F2): `close` fires a fraction of a
+            // millisecond after `exit` for a real Node child — well before
+            // `finalize`'s `await killPromise` ever yields, i.e. before this
+            // function is even called. By the time we get here, `closeSeen`
+            // (set by the listener registered at spawn time, above) already
+            // reflects reality for the overwhelming majority of real spawns:
+            // nothing is holding this child's stdio open, so don't pay out the
+            // 100ms grace window for a signal that already arrived.
+            if (closeSeen)
+                return Promise.resolve();
+            return new Promise((finishIdleWait) => {
+                let settled = false;
+                let graceTimer;
+                const capTimer = setTimeout(() => {
+                    finish();
+                }, EXIT_PIPE_IDLE_MAX_WAIT_MS);
+                const finish = () => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    rearmIdleGrace = undefined;
+                    if (graceTimer)
+                        clearTimeout(graceTimer);
+                    clearTimeout(capTimer);
+                    // Optional chaining, not a bare call: `child` is a real Node
+                    // ChildProcess (always an EventEmitter, always has this) in
+                    // production, but several existing test doubles across the
+                    // suite fake stdio-bearing children as plain objects with only
+                    // the handful of methods (`on`, `kill`, ...) their scenario
+                    // needs — no `removeListener`. Skipping cleanup on those is
+                    // harmless (the fake is torn down with the test either way);
+                    // crashing here from inside a timer callback is not: it would
+                    // throw before `finishIdleWait()` runs, hanging every caller's
+                    // `safeSpawnAsync` promise (#1673 review round 2 caught this
+                    // live in tests/clients/installer/version-drift.test.ts).
+                    child.removeListener?.("close", finish);
+                    finishIdleWait();
+                };
+                // The `closeSeen` fast-path above catches the common case (close
+                // already happened by the time we get here). This listener is
+                // the fallback for the rare case where `close` genuinely lands
+                // DURING the wait — e.g. a child whose stdio takes a beat
+                // longer than usual to release, but still well under the grace
+                // window. `close` is a stronger signal than "no data for
+                // EXIT_PIPE_IDLE_GRACE_MS", so finishing on it here still beats
+                // waiting out the timer. The anti-hang property is untouched
+                // either way: a daemonized descendant holding the pipe open is
+                // EXACTLY the case where `close` never fires at all, so the
+                // grace/cap timers still bound that case as before.
+                child.on("close", finish);
+                rearmIdleGrace = () => {
+                    if (graceTimer)
+                        clearTimeout(graceTimer);
+                    graceTimer = setTimeout(finish, EXIT_PIPE_IDLE_GRACE_MS);
+                };
+                rearmIdleGrace();
+            });
+        };
         // Process completion
-        child.on("close", async (code, signal) => {
-            if (spawnErrored)
+        //
+        // #1656 x #1651/#1670: finalize off BOTH `exit` and `close`, not just
+        // one — each covers a shape the other misses.
+        //   - `exit` is what unblocks the #1656 hang: a daemonized descendant
+        //     that inherited our stdout/stderr pipe can hold that fd open
+        //     forever, so `close` (which waits for every fd referencing the
+        //     child to release) never fires even though the child we spawned
+        //     is long dead. `exit` always fires once the child itself exits,
+        //     independent of who still holds its pipes.
+        //   - `close` is still wired because a child that never actually
+        //     launched (bad binary, EACCES, ...) gets NO `exit` event at all —
+        //     Node only emits `error` then `close(code<0, null)` for that
+        //     shape (#1651/#1670's shape guard below decides from exactly
+        //     this). `exit`-only would make that guard unreachable.
+        // Whichever fires first drives `finalize`; `settled` (distinct from
+        // `resolved`, which `finalize` itself owns) stops the second event
+        // from dispatching a redundant, concurrently-racing `finalize` call —
+        // double-invoking it would double-run `waitForPipeIdle` and
+        // `finishResourceUsage` against the same child.
+        let settled = false;
+        const onChildSettle = (code, signal) => {
+            if (settled || resolved)
                 return;
+            settled = true;
             closed = true;
             clearTimeout(timeoutId);
             abortSignal?.removeEventListener("abort", onAbort);
             if (child.pid)
                 lifetimeState.pids.delete(child.pid);
+            void finalize(code, signal);
+        };
+        const finalize = async (code, signal) => {
+            // Belt, not the decision: whichever path settles `resolved` FIRST
+            // wins. A healthy run's outcome must never be discarded by a late,
+            // unrelated 'error' (e.g. a post-exit kill() that itself failed
+            // with EPERM, #1651 review F4) — so this only bails when something
+            // else has ALREADY resolved, never on `error` merely having fired.
             await killPromise;
+            if (resolved)
+                return;
             // #1109: the child has exited — if killTree armed the non-Windows
             // SIGTERM→SIGKILL escalation timer and it hasn't fired yet, clear it
             // so it doesn't linger as a ref'd handle after this promise resolves.
             if (escalationTimer)
                 clearTimeout(escalationTimer);
+            // #1673 review F1: latch the verdict as DECIDED here, before the
+            // idle-pipe wait — not after it. `code`/`signal`/`timedOut`/`aborted`
+            // are already fixed by this point (they don't change during the
+            // wait), so nothing below depends on staying unresolved across it.
+            // Leaving `resolved` false across the wait would reopen the exact
+            // race #1651 review F4 closed: a late, unrelated 'error' (e.g. a
+            // post-exit kill() failing with EPERM) landing inside the
+            // idle-grace window (bounded, but up to EXIT_PIPE_IDLE_MAX_WAIT_MS)
+            // would steal an already-decided healthy verdict. Pre-#1656 that
+            // race window was one microtask — the gap between `close` firing
+            // and `resolve()` being called synchronously in the same handler.
+            // This closes the window back down to that same shape instead of
+            // widening it to the whole wait.
+            resolved = true;
+            await waitForPipeIdle();
             const resourceUsage = finishResourceUsage();
             const outputInfo = outputTruncated ? { outputTruncated: true } : {};
+            // #1816: surface the signal name as a field on every path where one
+            // exists, so callers can NAME it instead of scraping `error.message`.
+            const signalInfo = signal ? { signal } : {};
             if (timedOut) {
                 const cause = new Error(`Process timed out after ${timeout}ms (killed with ${signal || "SIGTERM"})`);
                 resolve({
@@ -1130,6 +1300,7 @@ export async function safeSpawnAsync(command, args, options) {
                     status: null,
                     error: cause,
                     failure: "timeout",
+                    ...signalInfo,
                     spawnFailure: new SpawnFailureError("timeout", cause.message, cause),
                     ...outputInfo,
                     resourceUsage,
@@ -1143,6 +1314,7 @@ export async function safeSpawnAsync(command, args, options) {
                     status: null,
                     error: cause,
                     failure: "aborted",
+                    ...signalInfo,
                     spawnFailure: new SpawnFailureError("killed", cause.message, cause),
                     ...outputInfo,
                     resourceUsage,
@@ -1156,17 +1328,58 @@ export async function safeSpawnAsync(command, args, options) {
                     status: null,
                     error: cause,
                     failure: "signal",
+                    ...signalInfo,
                     spawnFailure: new SpawnFailureError("killed", cause.message, cause),
                     ...outputInfo,
                     resourceUsage,
                 });
             }
+            else if (code === null || code < 0) {
+                // #1651 review F3: a real completed process never exits with a
+                // null or negative code (Node reports the negated libuv/errno for
+                // a child that never launched — e.g. ENOENT: -2 on Linux, -4058
+                // on Windows). This decides from that SHAPE alone, independent of
+                // whether/when 'error' has fired — Node's docs leave the
+                // 'error'/'close' ordering for a failed spawn unspecified, and a
+                // same-microtask re-check (the #1651 first-round fix) still loses
+                // if 'error' lands a tick later via setImmediate/nextTick.
+                // Reuse `pendingSpawnError` when 'error' already landed (a more
+                // informative Error — ENOENT vs EACCES vs other); otherwise
+                // synthesize an ENOENT-shaped one so a genuinely missing tool is
+                // never read as a clean, answered run.
+                const cause = pendingSpawnError ?? synthesizeEnoentError(command);
+                const spawnFailure = await classifySpawnFailure(cause, {
+                    command,
+                    cwd: options?.cwd,
+                });
+                resolve({
+                    stdout,
+                    stderr,
+                    status: code,
+                    error: cause,
+                    failure: "spawn",
+                    spawnFailure,
+                    ...outputInfo,
+                    resourceUsage,
+                });
+            }
             else {
                 resolve({ stdout, stderr, status: code, ...outputInfo, resourceUsage });
             }
-        });
+        };
+        child.on("exit", onChildSettle);
+        child.on("close", onChildSettle);
         child.on("error", (err) => {
-            spawnErrored = true;
+            // Capture unconditionally — even when `close` already resolved, this
+            // keeps the most recent Error available for anyone reading state
+            // mid-flight, and costs nothing (the assignment, not a resolve).
+            pendingSpawnError = err;
+            // A completed run's own verdict must never be downgraded by an
+            // unrelated LATE error (#1651 review F4 — e.g. a post-exit kill()
+            // failing with EPERM after `close(0, null)` already answered).
+            if (resolved)
+                return;
+            resolved = true;
             closed = true;
             clearTimeout(timeoutId);
             abortSignal?.removeEventListener("abort", onAbort);

package/node_modules/pi-lens/dist/clients/scratch-tree-policy.js

@@ -0,0 +1,161 @@
+/**
+ * Single source of truth for "scratch/cache tree" exclusion, shared by every
+ * runner that hands a DIRECTORY to an external binary and lets that binary do
+ * its own tree walk.
+ *
+ * pi-lens's own in-process walkers (`source-filter.ts`/`source-walker.ts`,
+ * `getProjectIgnoreMatcher`) already route every entry through
+ * `isExcludedDirName`/`EXCLUDED_DIRS` (`file-utils.ts`) — that's how knip,
+ * jscpd, and the tree-sitter project scan skip `.pi/`, `node_modules/`, etc.
+ * But a runner that shells out with `cwd`/`--source <dir>` and lets the
+ * EXTERNAL tool walk (gitleaks `detect --source`, `trivy fs`, `opengrep scan
+ * <dir>`) bypasses that walker entirely — the tool sees the raw tree,
+ * including pi-ecosystem scratch/data directories that were never meant to be
+ * scan targets (#1562: `.pi/greedysearch-sources/` — a gitignored web-research
+ * cache — served a `YOUR_API_KEY` doc-example placeholder to the agent as a
+ * "leaked secret").
+ *
+ * This module derives each such runner's native exclude syntax from the SAME
+ * `EXCLUDED_DIRS` list `file-utils.ts` already uses for the in-process walk,
+ * rather than hand-maintaining a parallel per-tool list (the single-source-of-
+ * truth rule that #883 encodes — a hand-copied list is a defect in itself:
+ * `dead-code-client.ts`'s `VULTURE_EXCLUDES` had drifted from `EXCLUDED_DIRS`
+ * before this fix, e.g. missing `.pi`/`.claude`/`.next`).
+ *
+ * Deliberately NOT `.gitignore`-based: a secrets scanner (gitleaks, trivy's
+ * `secret` scanner) must still see an untracked `.env` with a real credential
+ * — `.env` is commonly gitignored, so blanket "respect .gitignore" would hide
+ * exactly the file classes these scanners exist to catch (#1562 design note).
+ * `EXCLUDED_DIRS` is a narrower, deliberate list of scratch/cache/vendor
+ * directory NAMES (`.pi`, `.claude`, `node_modules`, `dist`, …), not a
+ * gitignore pattern set.
+ *
+ * TWO exclusion tiers, not one (#1562 review-round F1) — `EXCLUDED_DIRS`
+ * itself conflates two different questions:
+ *   - "don't bother INDEXING/LINTING/DEDUPING this" (the walker-parity
+ *     exports below, `getScratchTreeGlobPatterns`/`getScratchTreeDirNames`/
+ *     `getScratchTreeFnmatchPatterns`) — correctly broad: build output
+ *     (`dist`, `build`, `out`, `target`, `coverage`), vendored source
+ *     (`vendor`, `third_party`, `vendors`), and editor config (`.vscode`)
+ *     are all noise for knip/jscpd/vulture.
+ *   - "don't bother looking for SECRETS here" — a much narrower question.
+ *     The first cut of this fix reused the walker-parity list for gitleaks's
+ *     secrets-lane exclusion too, and a review probe caught it silently
+ *     dropping real AWS-shaped secrets seeded in `dist/`, `vendor/`,
+ *     `.vscode/`, `build/`, `out/`, `target/`, `third_party/`,
+ *     `third-party/`, `coverage/` (0/9 kept, unlogged) — a bundler can bake
+ *     a real key into `dist/`, `.vscode/launch.json` commonly carries a
+ *     committed debug token, and a vendored tree can carry an upstream
+ *     leak. `SECRETS_LANE_SCRATCH_DIR_NAMES`/`getSecretsLaneAllowlistPaths`/
+ *     `isUnderSecretsLaneScratchTree` are the narrow tier gitleaks (or any
+ *     future gitleaks-shaped secret scanner) must use instead — pi-ecosystem/
+ *     agent data dirs, `node_modules`, `.git`, and generic build/package-
+ *     manager CACHES only; every real-leak-surface directory above stays
+ *     fully in scope.
+ */
+import { EXCLUDED_DIRS, getExcludedDirGlobs } from "./file-utils.js";
+/** Directory-name entries only — drops glob entries (e.g. `*.dSYM`) that a
+ * bare directory-name/regex exclude can't express. */
+function literalExcludedDirNames() {
+    return EXCLUDED_DIRS.filter((name) => !name.includes("*") && !name.includes("?"));
+}
+/**
+ * `**\/name/**` glob patterns for tools that take doublestar globs
+ * (trivy `--skip-dirs`, opengrep/semgrep `--exclude`). Reuses
+ * `file-utils.ts`'s own glob derivation so both walkers and shell-out runners
+ * stay byte-for-byte in sync.
+ */
+export function getScratchTreeGlobPatterns() {
+    return getExcludedDirGlobs();
+}
+function escapeRegExp(literal) {
+    return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** Bare directory names, for tools (opengrep/semgrep `--exclude`) that treat a
+ * slash-free pattern as "this directory name, anywhere in the tree". */
+export function getScratchTreeDirNames() {
+    return literalExcludedDirNames();
+}
+/**
+ * Fnmatch-style glob patterns (`star/name/star`, not doublestar) for
+ * vulture's `--exclude` — the format `dead-code-client.ts` needs.
+ */
+export function getScratchTreeFnmatchPatterns() {
+    return literalExcludedDirNames().map((name) => `*/${name}/*`);
+}
+// --- Secrets-lane tier (#1562 review-round F1) ---
+//
+// Deliberately curated, NOT `EXCLUDED_DIRS`-derived: every name here must be
+// individually justified as "never intentionally holds a first-party
+// credential", not merely "not worth linting". See the module doc above for
+// the walker-parity-vs-secrets-lane distinction and the 9-path probe that
+// caught the original (too-broad) version of this fix.
+export const SECRETS_LANE_SCRATCH_DIR_NAMES = [
+    // pi-ecosystem / coding-agent data + cache directories.
+    ".pi",
+    ".pi-lens",
+    ".claude",
+    ".codex",
+    ".agents",
+    ".worktrees",
+    ".rescue",
+    ".gstack",
+    ".superpowers",
+    ".guardrails",
+    ".playwright-cli",
+    ".playwright-mcp",
+    // git's own internal object storage — binary/compressed, not readable
+    // source; a byte-regex scan of it produces garbage, not real findings.
+    ".git",
+    // Vendored/installed npm packages — third-party noise, not a first-party
+    // leak surface (unlike `vendor`/`third_party`, which are vendored SOURCE
+    // a project can carry an upstream leak in and stays in scope).
+    "node_modules",
+    // Generic build/package-manager CACHES — regenerated from source on every
+    // build/install, never a place a human commits a credential on purpose.
+    // Deliberately excludes build OUTPUT (`dist`/`build`/`out`/`target`/
+    // `coverage`) — a bundler/compiler CAN bake a real secret into output.
+    ".turbo",
+    ".cache",
+    ".parcel-cache",
+    ".svelte-kit",
+    ".nuxt",
+    ".yarn",
+    ".pnpm-store",
+    ".gradle",
+    ".next",
+    ".ruff_cache",
+    ".tox",
+    ".pytest_cache",
+    "venv",
+    ".venv",
+    "__pycache__",
+];
+/**
+ * Regex patterns for gitleaks's `[allowlist] paths` config array, scoped to
+ * the narrow secrets-lane tier above (NOT the walker-parity list — see the
+ * module doc). Matched against the finding's relative path.
+ *
+ * #1562 review-round F4: gitleaks's `File` field preserves the OS-native
+ * separator from Go's directory walk — on Windows that's `\`, not `/` — so
+ * an anchor of only `(?:^|/)` never matches there. Both separators are
+ * accepted in the anchor and in the "rest of path" tail.
+ */
+export function getSecretsLaneAllowlistPaths() {
+    return SECRETS_LANE_SCRATCH_DIR_NAMES.map((name) => {
+        const escaped = escapeRegExp(name);
+        return `(?:^|[/\\\\])${escaped}(?:[/\\\\].*)?$`;
+    });
+}
+/**
+ * True when any path segment of `relPath` (forward- or back-slash separated)
+ * is a secrets-lane scratch dir name. Used for the TS-side post-filter that
+ * backstops the generated gitleaks config — belt-and-suspenders because we
+ * can't exercise gitleaks's own TOML-regex engine in unit tests, only assert
+ * the config we hand it.
+ */
+export function isUnderSecretsLaneScratchTree(relPath) {
+    const names = new Set(SECRETS_LANE_SCRATCH_DIR_NAMES.map((n) => n.toLowerCase()));
+    const segments = relPath.split(/[/\\]/).filter(Boolean);
+    return segments.some((segment) => names.has(segment.toLowerCase()));
+}

package/node_modules/pi-lens/dist/clients/search-read-registration.js

@@ -4,15 +4,31 @@
  *
  * Search → edit is a common flow: the agent finds where something must change
  * (ast_grep_search / lsp_navigation / grep), then edits exactly those lines.
- * Those lines were genuinely shown, so they count as read — but ONLY those lines
- * (plus a small context margin), never the whole file, so editing an unseen
- * region is still guarded.
+ * Those lines were genuinely shown, so they count as read — but ONLY the lines
+ * the search actually DELIVERED, never the whole file and never a blanket
+ * margin, so editing an unseen region is still guarded (#1904).
  */
 import * as nodeFs from "node:fs";
 import * as path from "node:path";
 import { isPathIgnoredByProject } from "./file-utils.js";
 import { isExternalOrVendorFile } from "./path-utils.js";
-const DEFAULT_CONTEXT_MARGIN = 2;
+/** Clamp a delivered-context count to a usable non-negative integer. */
+function normalizeMargin(value) {
+    if (value === undefined || !Number.isFinite(value))
+        return undefined;
+    return Math.max(0, Math.floor(value));
+}
+/**
+ * #1904 item 2: this was 2, which credited every search hit as a 5-line read
+ * even though most searches print ONE line. The guard then let edits pass
+ * against lines the model never saw. Credit only delivered lines; callers that
+ * DID deliver context pass `contextBefore`/`contextAfter` per location.
+ *
+ * Note this is not the only slack in the system: `readCoversRange` in
+ * read-guard.ts still widens every read record by `config.contextLines` when it
+ * tests coverage, so a bare hit remains editable within that configured band.
+ */
+const DEFAULT_CONTEXT_MARGIN = 0;
 /**
  * Record each shown location as a read (± context margin). Resolves project-
  * relative paths, skips external/vendor/ignored/non-existent files, and dedupes
@@ -39,11 +55,18 @@ export function registerSearchReads(readGuard, locations, opts) {
         catch {
             continue;
         }
-        const start = Math.max(1, Math.floor(loc.startLine) - margin);
+        const marginBefore = normalizeMargin(loc.contextBefore) ?? margin;
+        const marginAfter = normalizeMargin(loc.contextAfter) ?? margin;
+        const creditReason = marginBefore === 0 && marginAfter === 0
+            ? "match-lines-only"
+            : loc.contextBefore !== undefined || loc.contextAfter !== undefined
+                ? "delivered-context-flags"
+                : "caller-margin";
+        const start = Math.max(1, Math.floor(loc.startLine) - marginBefore);
         const endLine = Number.isFinite(loc.endLine)
             ? loc.endLine
             : loc.startLine;
-        const end = Math.max(start, Math.floor(endLine) + margin);
+        const end = Math.max(start, Math.floor(endLine) + marginAfter);
         const limit = end - start + 1;
         const key = `${abs}:${start}:${limit}`;
         if (seen.has(key))
@@ -56,6 +79,11 @@ export function registerSearchReads(readGuard, locations, opts) {
             effectiveOffset: start,
             effectiveLimit: limit,
             expandedByLsp: false,
+            searchCredit: {
+                marginBefore,
+                marginAfter,
+                reason: creditReason,
+            },
             turnIndex: opts.turnIndex,
             writeIndex: opts.writeIndex,
             timestamp: Date.now(),