@sema-agent/core 5.42.0 → 5.44.0

package/dist/core/types.d.ts

@@ -2881,6 +2881,10 @@ export interface TaskResult {
      * the resume capability, §6). Undefined for every other status.
      */
     checkpointToken?: import("./checkpoint-store.js").CheckpointToken;
+    /** The suspend's NON-SECRET stable identity ({@link import("./checkpoint-store.js").Checkpoint.checkpointId}),
+     *  set beside `checkpointToken` on the suspended/needs_review terminals — the display/correlation key a
+     *  consumer may log or render where the token must not travel. Absent on pre-identity checkpoints. */
+    checkpointId?: string;
     /** Set with `checkpointToken`: who/what must resume (e.g. `{kind:"human", reason, toolName}`), so the
      *  caller knows what decision the suspension is awaiting. */
     checkpointGate?: import("./checkpoint-store.js").CheckpointGate;
@@ -4679,6 +4683,34 @@ export interface EngineNotice {
      *    `detail: { steer, taskId? }` / `{ followUp, taskId? }`. Per-run, at most once per family
      *    (the terminal sweep is a single site).
      *
+     *  - `"memory.session_polluted"` (design/178 §3, #324a) — this session's memory crossed into the
+     *    one-way POLLUTED state (a tool classified as an external content source was invoked, directly
+     *    or through a delegated child): its memory writes are no longer eligible for the long-term
+     *    library. The notice states that VERDICT plus what a harvest does when it collects — it does
+     *    not promise quarantine, because a `writeScope`-null layering and a declared-unavailable
+     *    session both reach the zero-admission harvest arm (nothing collected ⇒ nothing captured), and
+     *    a mark landing after the pre-commit pollution read leaves already-committed rows to the
+     *    challenge sweep; what a harvest actually contained is the other code below. The challenge
+     *    clause is a policy statement, not a receipt — a sweep that cannot run announces
+     *    `"memory.challenge_sweep_failed"` on the engine's incident seat. Announced ONCE PER
+     *    SESSION, at the mark seat: a repeat mark inside the process and a resumed session whose
+     *    durable marker already exists stay quiet (the state is one-way, so a second line would carry
+     *    no new fact); a pollution state that cannot be read announces rather than assuming it was
+     *    already said. `detail: { reason, sessionId? }` — `reason` names the invoked tool and is
+     *    neutralized/length-bounded (the name comes from the host/protocol roster).
+     *  - `"memory.harvest_quarantined"` (design/178 §3, #324a) — a polluted session's harvest ran its
+     *    containment: `count` ENTRY files written or changed in the session were withheld from the
+     *    library, `moved` of them were physically moved into the control-plane quarantine directory,
+     *    and `escalated` of them carry a `HarvestReport.quarantineFailures` row (a failed capture, a
+     *    failed removal, or a file tombstoned in place — which counts as moved AND escalated, so the
+     *    two numbers are read off the report's rows, never subtracted from each other). One notice PER
+     *    HARVEST that withheld at least one entry file (a checkpoint harvest and the terminal harvest
+     *    are distinct facts), never minted for a clean session; `detail: { count, moved, escalated,
+     *    reason?, sessionId? }` (`reason` absent ⇔ the pollution marker could not be re-read at report
+     *    time — the withheld count stays true either way). Registered gap: the derived index (`MEMORY.md`) is
+     *    contained on a path that mints no rejection row, so an index-ONLY containment produces no
+     *    notice and is disclosed by the harvest report's warnings alone.
+     *
      *  Deliberately NOT a notice family: brain retry/reconnect liveness (a rate limit, a 5xx, a
      *  transient network failure being retried). Those are per-attempt liveness frames with their own
      *  frequency semantics and ride the wire `status` channel ({@link BrainStatus}), whose sink the

package/dist/engine/execution-env/node-execution-env.d.ts

@@ -1,4 +1,5 @@
 import { type ExecResult, type ExecutionEnv, ExecutionError, type ExecutionEnvExecOptions, FileError, type FileInfo, type Result } from "../harness/types.js";
+import { type SecretEnvFinding } from "../../core/secret-env.js";
 import type { BackgroundShellCapability, BackgroundShellId, BackgroundPoll, BackgroundSpawnOptions } from "../../core/background-shell.js";
 import { BackgroundShellError } from "../../core/background-shell.js";
 import type { SchedulerCapability, ScheduledIntent, SchedulerContext, ScheduledTaskId, ScheduledTaskSummary } from "../../core/scheduler.js";
@@ -18,6 +19,8 @@ export declare function getShellConfig(customShellPath?: string): Promise<Result
     shell: string;
     args: string[];
 }, ExecutionError>>;
+/** test seam (mirrors the notice-seat announce reset): the once-per-process fallback latches. */
+export declare function __resetSecretScrubAnnouncement(): void;
 /** RB-235 ([1937] BB2): the spool-reclaim decision, extracted PURE so every rule is unit-pinnable.
  *  Both reclaim sites (foreground `reclaimSpool`, background `syncSpool`) route through this one
  *  function so they cannot drift apart.
@@ -83,6 +86,7 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
     private readonly bgShells;
     private bgCounter;
     private readonly retainBackgroundProcesses;
+    private readonly onSecretEnvScrub?;
     /** design/128 T1-1: lazily-created env-owned spool dir (mkdtemp under os tmp — unpredictable, never the cwd). */
     private bgSpoolDir?;
     readonly backgroundCapabilities: BackgroundShellCapability["backgroundCapabilities"];
@@ -108,6 +112,10 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
          * deployments (their pre-suspend dispose becomes a no-op too — do not combine).
          */
         retainBackgroundProcesses?: boolean;
+        /** The D1 scrub decision's observation seat: called with every NON-EMPTY finding set the default
+         *  "scrub" leg withholds from a shell child. Absent ⇒ a once-per-process console summary (loud
+         *  enough to notice, quiet enough not to spam). Never called on the "all"/allowlist legs. */
+        onSecretEnvScrub?: (findings: readonly SecretEnvFinding[]) => void;
     });
     get schedulerCapabilities(): SchedulerCapability["schedulerCapabilities"];
     schedule(intent: ScheduledIntent, ctx: SchedulerContext): Promise<Result<{

package/dist/engine/execution-env/node-execution-env.js

@@ -188,7 +188,13 @@ export async function getShellConfig(customShellPath) {
     return ok({ shell: "sh", args: ["-c"] });
 }
 const EXEC_FORCE_SETTLE_GRACE_MS = 3000;
-function getShellEnv(inheritEnv, baseEnv, extraEnv) {
+let secretScrubConsoleAnnounced = false;
+let secretScrubSeatDefectAnnounced = false;
+export function __resetSecretScrubAnnouncement() {
+    secretScrubConsoleAnnounced = false;
+    secretScrubSeatDefectAnnounced = false;
+}
+function getShellEnv(inheritEnv, baseEnv, extraEnv, onScrub) {
     let inherited;
     if (inheritEnv === "all") {
         inherited = process.env;
@@ -200,7 +206,36 @@ function getShellEnv(inheritEnv, baseEnv, extraEnv) {
                 inherited[k] = process.env[k];
     }
     else {
-        inherited = scrubSecretEnv(process.env);
+        const scrubbed = [];
+        inherited = scrubSecretEnv(process.env, scrubbed);
+        const findings = scrubbed.filter((f) => baseEnv?.[f.key] === undefined && extraEnv?.[f.key] === undefined);
+        if (findings.length > 0) {
+            if (typeof onScrub === "function") {
+                try {
+                    const r = onScrub(findings);
+                    if (typeof r?.then === "function") {
+                        r.then(undefined, () => {
+                        });
+                    }
+                }
+                catch {
+                }
+            }
+            else {
+                if (onScrub !== undefined && !secretScrubSeatDefectAnnounced) {
+                    secretScrubSeatDefectAnnounced = true;
+                    try {
+                        console.warn(`onSecretEnvScrub seat holds ${onScrub === null ? "null" : typeof onScrub} — not a function; scrub findings fall back to the console summary (once per process)`);
+                    }
+                    catch {
+                    }
+                }
+                if (!secretScrubConsoleAnnounced) {
+                    secretScrubConsoleAnnounced = true;
+                    console.warn(`secret_env_scrubbed: ${findings.length} env key(s) withheld from the shell child (${findings.map((f) => f.key).join(", ")}) — once per process; wire onSecretEnvScrub for per-exec telemetry`);
+                }
+            }
+        }
     }
     return {
         ...inherited,
@@ -254,6 +289,7 @@ export class NodeExecutionEnv {
     bgShells = new Map();
     bgCounter = 0;
     retainBackgroundProcesses;
+    onSecretEnvScrub;
     bgSpoolDir;
     backgroundCapabilities;
     constructor(options) {
@@ -263,6 +299,7 @@ export class NodeExecutionEnv {
         this.inheritEnv = options.inheritEnv ?? "scrub";
         this.scheduler = options.scheduler;
         this.retainBackgroundProcesses = options.retainBackgroundProcesses ?? false;
+        this.onSecretEnvScrub = options.onSecretEnvScrub;
         this.backgroundCapabilities = {
             supported: true,
             maxConcurrent: 8,
@@ -420,7 +457,7 @@ export class NodeExecutionEnv {
                 child = spawn(shellConfig.value.shell, [...shellConfig.value.args, command], {
                     cwd,
                     detached: process.platform !== "win32",
-                    env: getShellEnv(this.inheritEnv, this.shellEnv, options?.env),
+                    env: getShellEnv(this.inheritEnv, this.shellEnv, options?.env, this.onSecretEnvScrub),
                     stdio: execSpoolFds ? ["ignore", execSpoolFds[0], execSpoolFds[1]] : ["ignore", "pipe", "pipe"],
                     windowsHide: true,
                 });
@@ -1114,7 +1151,7 @@ export class NodeExecutionEnv {
             child = spawn(shellConfig.value.shell, [...shellConfig.value.args, command], {
                 cwd: options?.cwd ? resolvePath(this.cwd, options.cwd) : this.cwd,
                 detached: process.platform !== "win32",
-                env: getShellEnv(this.inheritEnv, this.shellEnv, options?.env),
+                env: getShellEnv(this.inheritEnv, this.shellEnv, options?.env, this.onSecretEnvScrub),
                 stdio: spoolFds ? ["ignore", spoolFds[0], spoolFds[1]] : ["ignore", "pipe", "pipe"],
                 windowsHide: true,
             });

package/dist/tools/fs/fs-search-tools.d.ts

@@ -5,11 +5,12 @@ import type { ReadFace } from "./read-face.js";
 /**
  * The Grep card's details assembly, PURE over the engine text ({mode, offset} from the request) —
  * exported so the text→structured mapping is pinnable with synthetic texts (the byte-truncation and
- * fenced-partial shapes are impractical to construct through a live tool call). Follow-up #313 will
- * replace the text parsing with structured rows from runGrep; until then this seam is the honesty
- * boundary.
+ * fenced-partial shapes are impractical to construct through a live tool call). #313 moved PATH
+ * IDENTITY off the text and onto the engines' served rows (both legs supply them now); the counts
+ * and totals below still read the engine's own honesty markers out of the text, which is what keeps
+ * this seam the honesty boundary.
  */
-export declare function grepDetailFields(text: string, mode: "files_with_matches" | "content" | "count", offset?: number): Record<string, unknown>;
+export declare function grepDetailFields(text: string, mode: "files_with_matches" | "content" | "count", offset?: number, structuredRows?: readonly import("./search.js").GrepRow[]): Record<string, unknown>;
 export declare function createGrepTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[], readDeny?: ReadDenyMatcher, readFace?: ReadFace): AgentTool;
 export declare function createGlobTool(env: ExecutionEnv, rootCanonical: string, additionalRoots?: readonly string[], readDeny?: ReadDenyMatcher, readFace?: ReadFace): AgentTool;
 /** Static side-effect class of every hand tool, by name (design/44 §3). Used by prepare-task to (a) feed

package/dist/tools/fs/fs-search-tools.js

@@ -2,7 +2,9 @@ import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
 import { resolveKey, violationText, violationDetails } from "./safety.js";
 import { runGrepDetailed, runGlobDetailed, splitAbsoluteGlobPattern, invalidGlobTokens } from "./search.js";
-export function grepDetailFields(text, mode, offset) {
+export function grepDetailFields(text, mode, offset, structuredRows) {
+    const structuredIdentityComplete = structuredRows !== undefined && structuredRows.every((r) => r.path !== undefined || r.text === "--");
+    const structuredPaths = structuredIdentityComplete && structuredRows !== undefined ? [...new Set(structuredRows.filter((r) => r.path !== undefined).map((r) => r.path))] : undefined;
     const rows = text.startsWith("No matches.")
         ? []
         : text
@@ -28,10 +30,11 @@ export function grepDetailFields(text, mode, offset) {
     const appliedLimit = cappedAt !== undefined ? { appliedLimit: cappedAt } : {};
     let detailFields;
     if (mode === "files_with_matches") {
-        detailFields = { filenames: rows, numFiles: rows.length, totalFiles: capTotal ?? rows.length, ...appliedLimit, ...appliedOffset };
+        const fileNames = structuredPaths ?? rows;
+        detailFields = { filenames: fileNames, numFiles: fileNames.length, totalFiles: capTotal ?? fileNames.length, ...appliedLimit, ...appliedOffset };
     }
     else if (mode === "count") {
-        const filenames = [...new Set(rows.map((l) => (l.includes(":") ? l.slice(0, l.lastIndexOf(":")) : l)))];
+        const filenames = structuredPaths ?? [...new Set(rows.map((l) => (l.includes(":") ? l.slice(0, l.lastIndexOf(":")) : l)))];
         let numMatches = 0;
         let malformed = false;
         for (const l of rows) {
@@ -52,7 +55,7 @@ export function grepDetailFields(text, mode, offset) {
         };
     }
     else {
-        const filenames = [...new Set(rows.map(contentPathOf))];
+        const filenames = structuredPaths ?? [...new Set(rows.map(contentPathOf))];
         const joined = rows.join("\n");
         const GREP_CONTENT_PREVIEW_CHARS = 16_000;
         detailFields = {
@@ -161,7 +164,7 @@ export function createGrepTool(env, rootCanonical, additionalRoots, readDeny, re
             if (text.startsWith("Error (grep)") || text.startsWith("Error (Grep)"))
                 return errorResult(text);
             const mode = a.output_mode ?? "files_with_matches";
-            const detailFields = grepDetailFields(text, mode, a.offset);
+            const detailFields = grepDetailFields(text, mode, a.offset, grepRun.rows);
             return {
                 content: text,
                 details: { type: "grep", mode, ...detailFields, ...(grepRun.degraded ?? {}), ...(grepRun.withheld !== undefined ? { withheld: grepRun.withheld } : {}) },

package/dist/tools/fs/search.d.ts

@@ -190,7 +190,27 @@ export interface ReadDenyJudge {
 /** JS-fallback grep: ignore-aware walk + per-line scan, honoring output_mode / context / head_limit.
  *  design/199 件B: `deny` prunes the walk (note appended to every output shape); `denyOut` is the
  *  structured twin — a sink because this function's dozen error returns predate the facts (the sink
- *  is written the moment the walk lands, whatever the scan then returns). */
+ *  is written the moment the walk lands, whatever the scan then returns).
+ *
+ *  backlog #313 — the SERVED rows ride back next to the text. This scanner knows every result's
+ *  identity natively (the walk hands it whole paths), so a row's `path` is that walked identity,
+ *  never a cut of the rendered line — the mis-split family the text re-parse carries cannot exist
+ *  here. The rows ARE the window `text` shows: post offset, post row cap, post byte ceiling, in the
+ *  same order. The unit is the RECORD, which is the unit the cap has always counted: one record is
+ *  one rendered line EXCEPT where the file's own name carries a newline, and then the one record
+ *  spans two physical lines — the same relation {@link formatRgRecords} states for the rg leg, and
+ *  precisely the case where a row's identity beats anything the text can be split into.
+ *  Every row carries a path (this leg emits no group-separator row — the one pathless shape
+ *  ripgrep's output can carry), and a no-match run's row set is `[]`, not absent. A typed
+ *  `Error (grep): …` return carries no rows at all: a refusal is not a row set. */
+export declare function jsGrepDetailed(env: ExecutionEnv, root: string, p: GrepParams, signal?: AbortSignal, guards?: JsGrepGuards, deny?: ReadDenyJudge, denyOut?: {
+    withheld?: ReadDenyWithheld;
+}): Promise<{
+    text: string;
+    rows?: readonly GrepRow[];
+}>;
+/** Text-only wrapper of {@link jsGrepDetailed} (the shape callers that never look at the served rows
+ *  want — the same relation {@link runGrep} has to {@link runGrepDetailed}). */
 export declare function jsGrep(env: ExecutionEnv, root: string, p: GrepParams, signal?: AbortSignal, guards?: JsGrepGuards, deny?: ReadDenyJudge, denyOut?: {
     withheld?: ReadDenyWithheld;
 }): Promise<string>;
@@ -210,8 +230,35 @@ export type GrepDegradation = {
 };
 /** Structured grep result: the model-facing text plus the degradation facts, so the tool layer can
  *  ship them on the structured frame instead of leaving them prose-only. */
+/** #313 — one SERVED result RECORD with its path taken from the engine's own knowledge, exactly the
+ *  window `text` shows (post cap/offset): ripgrep's `--null` path field ({@link parseRgRecords}) on
+ *  the rg legs, the walked file identity ({@link jsGrepDetailed}) on the JS-scanner legs. A record is
+ *  one rendered line except where a path carries a newline (see {@link formatRgRecords}), which is
+ *  also the case the text can no longer be split into records at all. The tool layer prefers these
+ *  over re-parsing `text` (whose `path:line:text` split mis-cuts a path that
+ *  itself contains `:digits:`).
+ *
+ *  KNOWN EXCEPTION to "exactly the window `text` shows", stated because it is measurable: on the two
+ *  ripgrep PARTIAL legs (timeout / error-exit with output) the delivered text is fenced by
+ *  `delimitUntrusted`, which NEUTRALIZES fence markers inside the body, while the rows carry the
+ *  record bytes as ripgrep emitted them. A row's `text` there is therefore the un-neutralized form —
+ *  identity (`path`) is unaffected. Consume `text` for anything rendered; the rows' contract is
+ *  identity. Reconciling the two (defuse per record, or withhold rows where the text is fenced) is a
+ *  contract choice recorded for the backlog, not settled here.
+ *
+ *  `path` is absent only where the record genuinely carries none —
+ *  ripgrep's `--` group separator and the unaccountable shapes listed on {@link RgRecord} — and a
+ *  row set carrying such a row sends the tool layer back to the text parse for identity. */
+export interface GrepRow {
+    path?: string;
+    text: string;
+}
 export interface GrepRunResult {
     text: string;
+    /** Served rows (#313): present on BOTH engine legs — ripgrep's and the JS scanner's, including the
+     *  rescan legs. Absent only when the JS scanner refused the search outright (a typed
+     *  `Error (grep): …` text): a refusal has no row set, truthfully, rather than an empty one. */
+    rows?: readonly GrepRow[];
     degraded?: GrepDegradation;
     /** design/199 件B — deny-list withholding facts (see {@link ReadDenyWithheld}); absent = nothing
      *  withheld / no deny judge in play. */

package/dist/tools/fs/search.js

@@ -1,6 +1,6 @@
 import { delimitUntrusted } from "../../core/untrusted-text.js";
 import { MAX_EXEC_OUTPUT_BYTES } from "../../core/exec-output-tail.js";
-import { hasBinaryExtension, isAbsolutePathForm } from "./safety.js";
+import { hasBinaryExtension, isAbsolutePathForm, isWinFormPath } from "./safety.js";
 const WALK_MAX_FILES = 5000;
 const WALK_MAX_DEPTH = 32;
 const GREP_DEFAULT_CAP = 250;
@@ -35,6 +35,25 @@ const TYPE_GLOBS = {
     css: "*.{css,scss,less}",
 };
 const basename = (p) => p.slice(Math.max(p.lastIndexOf("/"), p.lastIndexOf("\\")) + 1);
+function collapseDotSegments(p) {
+    const win = isWinFormPath(p);
+    const lead = (win ? /^[\\/]*/ : /^\/*/).exec(p)?.[0] ?? "";
+    const sep = win ? "\\" : "/";
+    const parts = p.slice(lead.length).split(win ? /[\\/]+/ : /\/+/);
+    const floor = !win ? 0 : lead.length >= 2 ? 2 : /^[A-Za-z]:$/.test(parts[0] ?? "") ? 1 : 0;
+    const kept = [];
+    for (const part of parts) {
+        if (part === "" || part === ".")
+            continue;
+        if (part === "..") {
+            if (kept.length > floor)
+                kept.pop();
+            continue;
+        }
+        kept.push(part);
+    }
+    return kept.length === 0 ? "" : lead + kept.join(sep);
+}
 const NO_MATCHES = "No matches.";
 const GREP_LINE_CLIP = 500;
 function clipLine(line) {
@@ -759,10 +778,10 @@ function multilineSpans(content, p, captureText = false, deadline = Infinity) {
     }
     return spans;
 }
-export async function jsGrep(env, root, p, signal, guards, deny, denyOut) {
+export async function jsGrepDetailed(env, root, p, signal, guards, deny, denyOut) {
     const analysis = analyzeRedos(p.pattern, p.ignore_case === true);
     if (analysis.risk)
-        return redosRejection(analysis.risk);
+        return { text: redosRejection(analysis.risk) };
     const budgetMs = guards?.budgetMs ?? GREP_FILE_BUDGET_MS;
     const longLineLimit = guards?.longLineLimit ?? GREP_GRAY_LINE_MAX;
     const grayPattern = analysis.quantifiedGroup || analysis.unboundedCount >= 2;
@@ -776,7 +795,7 @@ export async function jsGrep(env, root, p, signal, guards, deny, denyOut) {
         test = compilePattern(p);
     }
     catch (e) {
-        return `Error (grep): invalid regex: ${e instanceof Error ? e.message : String(e)}`;
+        return { text: `Error (grep): invalid regex: ${e instanceof Error ? e.message : String(e)}` };
     }
     const ignore = await buildIgnore(env, root, signal);
     const rootPrefix = root.replace(/[\\/]+$/, "") + (root.includes("\\") ? "\\" : "/");
@@ -816,9 +835,20 @@ export async function jsGrep(env, root, p, signal, guards, deny, denyOut) {
     const cap = p.head_limit === 0 ? Infinity : Math.max(1, Math.floor(p.head_limit ?? GREP_DEFAULT_CAP));
     const mode = p.output_mode ?? "files_with_matches";
     const rel = (abs) => (abs.startsWith(rootPrefix) ? abs.slice(rootPrefix.length) : abs);
+    const startWin = isWinFormPath(start);
+    const startNorm = collapseDotSegments(start);
+    const targetSpell = p.path ? p.path.replace(startWin ? /[\\/]+$/ : /\/+$/, "") : "";
+    const isBoundary = (c) => c === "/" || (startWin && c === "\\");
     const relOut = (abs) => {
-        const r = rel(abs);
-        return p.path || r === abs ? r : `./${r}`;
+        if (!p.path) {
+            const r = rel(abs);
+            return r === abs ? r : `./${r}`;
+        }
+        if (abs === startNorm || abs === start)
+            return targetSpell;
+        if (abs.startsWith(startNorm) && isBoundary(abs[startNorm.length]))
+            return targetSpell + abs.slice(startNorm.length);
+        return rel(abs);
     };
     if (p.glob) {
         const globRes = splitGlobParam(p.glob).map((g) => globTokenToRegExp(normalizeGlobToken(g), globIsAnchored(g), true));
@@ -846,7 +876,7 @@ export async function jsGrep(env, root, p, signal, guards, deny, denyOut) {
     let outBytes = 0;
     let outputTruncated = false;
     let rowsBeforeWindow = 0;
-    const pushRow = (row) => {
+    const pushRow = (row, path) => {
         if (outputTruncated)
             return;
         if (rowsBeforeWindow < off) {
@@ -861,7 +891,7 @@ export async function jsGrep(env, root, p, signal, guards, deny, denyOut) {
             return;
         }
         outBytes += size;
-        out.push(row);
+        out.push({ path, text: row });
     };
     const fileMatches = [];
     const counts = [];
@@ -889,6 +919,7 @@ export async function jsGrep(env, root, p, signal, guards, deny, denyOut) {
         const lines = read.value.split("\n");
         if (lines.length > 1 && lines.at(-1) === "")
             lines.pop();
+        const shownPath = relOut(f);
         let fileCount = 0;
         const fileMatchStart = monotonicNow();
         if (p.multiline) {
@@ -902,8 +933,8 @@ export async function jsGrep(env, root, p, signal, guards, deny, denyOut) {
             }
             catch (e) {
                 if (e instanceof GrepBudgetExceeded)
-                    return budgetError(relOut(f), monotonicNow() - fileMatchStart);
-                return `Error (grep): invalid regex: ${e instanceof Error ? e.message : String(e)}`;
+                    return { text: budgetError(shownPath, monotonicNow() - fileMatchStart) };
+                return { text: `Error (grep): invalid regex: ${e instanceof Error ? e.message : String(e)}` };
             }
             fileCount = spans.length;
             if (mode === "content") {
@@ -911,12 +942,12 @@ export async function jsGrep(env, root, p, signal, guards, deny, denyOut) {
                     if (p.only_matching && text !== undefined) {
                         const parts = text.split("\n");
                         for (let k = 0; k < parts.length; k++) {
-                            pushRow(`${relOut(f)}:${s + k}:${clipLine(parts[k])}`);
+                            pushRow(`${shownPath}:${s + k}:${clipLine(parts[k])}`, shownPath);
                         }
                         continue;
                     }
                     for (let j = Math.max(0, s - 1 - ctxB); j <= Math.min(lines.length - 1, eL - 1 + ctxA); j++) {
-                        pushRow(`${relOut(f)}:${j + 1}:${clipLine(lines[j])}`);
+                        pushRow(`${shownPath}:${j + 1}:${clipLine(lines[j])}`, shownPath);
                     }
                 }
             }
@@ -926,7 +957,7 @@ export async function jsGrep(env, root, p, signal, guards, deny, denyOut) {
                 if (grayPattern || (i > 0 && i % GREP_LINE_CHECK_EVERY === 0)) {
                     const elapsed = monotonicNow() - fileMatchStart;
                     if (elapsed >= budgetMs)
-                        return budgetError(relOut(f), elapsed);
+                        return { text: budgetError(shownPath, elapsed) };
                 }
                 if (i > 0 && i % GREP_LINE_CHECK_EVERY === 0) {
                     await yieldEventLoop();
@@ -945,16 +976,16 @@ export async function jsGrep(env, root, p, signal, guards, deny, denyOut) {
                 if (mode === "content") {
                     if (p.only_matching) {
                         for (const part of matchedParts(lines[i], p)) {
-                            pushRow(`${relOut(f)}:${i + 1}:${clipLine(part)}`);
+                            pushRow(`${shownPath}:${i + 1}:${clipLine(part)}`, shownPath);
                         }
                     }
                     else if (ctx > 0) {
                         for (let j = Math.max(0, i - ctxB); j <= Math.min(lines.length - 1, i + ctxA); j++) {
-                            pushRow(`${relOut(f)}:${j + 1}:${clipLine(lines[j])}`);
+                            pushRow(`${shownPath}:${j + 1}:${clipLine(lines[j])}`, shownPath);
                         }
                     }
                     else {
-                        pushRow(`${relOut(f)}:${i + 1}:${clipLine(lines[i])}`);
+                        pushRow(`${shownPath}:${i + 1}:${clipLine(lines[i])}`, shownPath);
                     }
                 }
             }
@@ -968,7 +999,7 @@ export async function jsGrep(env, root, p, signal, guards, deny, denyOut) {
             if (mode === "files_with_matches")
                 fileMatches.push(f);
             else if (mode === "count" && counts.length < collectCap)
-                counts.push(`${relOut(f)}:${fileCount}`);
+                counts.push({ path: shownPath, text: `${shownPath}:${fileCount}` });
         }
     }
     if (scanAborted || skippedUnreadableFiles > 0 || skippedLongLines > 0 || multilineSkippedFiles > 0) {
@@ -988,7 +1019,7 @@ export async function jsGrep(env, root, p, signal, guards, deny, denyOut) {
         }
     }
     const caveat = honestyCaveat + denyNote;
-    const paged = (arr) => (off > 0 ? arr.slice(off, off + cap) : arr);
+    const paged = (arr) => (off > 0 ? arr.slice(off, off + cap) : [...arr]);
     const offNote = off > 0 ? `\n[offset ${off}]` : "";
     if (mode === "files_with_matches") {
         const haveMtimes = fileMatches.length > 0 && fileMatches.every((f) => walked.mtimes.has(f));
@@ -999,26 +1030,37 @@ export async function jsGrep(env, root, p, signal, guards, deny, denyOut) {
                 .map((x) => x.r)
             : fileMatches.map(relOut).sort();
         const body = sortedFileMatches.slice(off, off + cap);
-        return body.length === 0
-            ? NO_MATCHES + offNote + typeNote + caveat
-            : body.join("\n") + (totalFiles > off + cap ? `\n…[capped at ${cap} of ${totalFiles}]` : "") + offNote + typeNote + caveat;
+        const rows = body.map((r) => ({ path: r, text: r }));
+        return {
+            text: body.length === 0
+                ? NO_MATCHES + offNote + typeNote + caveat
+                : body.join("\n") + (totalFiles > off + cap ? `\n…[capped at ${cap} of ${totalFiles}]` : "") + offNote + typeNote + caveat,
+            rows,
+        };
     }
     if (mode === "count") {
         const body = paged(counts);
-        return body.length === 0
-            ? NO_MATCHES + offNote + typeNote + caveat
-            : body.join("\n") + (totalFiles > off + cap ? `\n…[capped at ${cap} of ${totalFiles}]` : "") + offNote + typeNote + caveat;
+        return {
+            text: body.length === 0
+                ? NO_MATCHES + offNote + typeNote + caveat
+                : body.map((r) => r.text).join("\n") + (totalFiles > off + cap ? `\n…[capped at ${cap} of ${totalFiles}]` : "") + offNote + typeNote + caveat,
+            rows: body,
+        };
     }
     const body = out;
     const byteNote = outputTruncated ? `\n…[output truncated at ${outputMaxBytes} bytes — narrow the pattern or set a smaller head_limit]` : "";
     if (body.length === 0)
-        return NO_MATCHES + byteNote + offNote + typeNote + caveat;
+        return { text: NO_MATCHES + byteNote + offNote + typeNote + caveat, rows: [] };
+    const bodyText = body.map((r) => r.text).join("\n");
     if (out.length < cap)
-        return body.join("\n") + byteNote + offNote + typeNote + caveat;
+        return { text: bodyText + byteNote + offNote + typeNote + caveat, rows: body };
     const marker = ctx > 0 || p.multiline || p.only_matching
         ? `\n…[capped at ${cap}; ${totalContent}+ match(es) found, more output omitted]`
         : `\n…[capped at ${cap} of ${totalContent}]`;
-    return body.join("\n") + marker + byteNote + offNote + typeNote + caveat;
+    return { text: bodyText + marker + byteNote + offNote + typeNote + caveat, rows: body };
+}
+export async function jsGrep(env, root, p, signal, guards, deny, denyOut) {
+    return (await jsGrepDetailed(env, root, p, signal, guards, deny, denyOut)).text;
 }
 const rgCache = new WeakMap();
 export function detectRipgrep(env) {
@@ -1096,12 +1138,16 @@ function formatRgRecords(records, p, caveat = "") {
     const cap = p.head_limit === 0 ? Infinity : Math.max(1, Math.floor(p.head_limit ?? GREP_DEFAULT_CAP));
     const off = Math.max(0, Math.floor(p.offset ?? 0));
     const capped = records.slice(off, off + cap);
+    const served = capped.map((r) => (r.path !== undefined ? { path: r.path, text: r.text } : { text: r.text }));
     if (capped.length === 0)
-        return NO_MATCHES + (off > 0 ? `\n[offset ${off}]` : "") + caveat;
-    return (capped.map((r) => r.text).join("\n") +
-        (records.length > off + cap ? `\n…[capped at ${cap} of ${records.length}]` : "") +
-        (off > 0 ? `\n[offset ${off}]` : "") +
-        caveat);
+        return { text: NO_MATCHES + (off > 0 ? `\n[offset ${off}]` : "") + caveat, served };
+    return {
+        text: capped.map((r) => r.text).join("\n") +
+            (records.length > off + cap ? `\n…[capped at ${cap} of ${records.length}]` : "") +
+            (off > 0 ? `\n[offset ${off}]` : "") +
+            caveat,
+        served,
+    };
 }
 export function rgOutputDenyTripwire(stdout, mode, judge, opts = {}) {
     if (stdout.length === 0)
@@ -1120,30 +1166,32 @@ export function rgOutputDenyTripwire(stdout, mode, judge, opts = {}) {
 }
 async function jsGrepDenyTripFallback(env, root, p, signal, trip, deny) {
     const denyOut = {};
-    const text = await jsGrep(env, root, p, signal, undefined, deny, denyOut);
+    const { text, rows } = await jsGrepDetailed(env, root, p, signal, undefined, deny, denyOut);
     const why = trip.reason === "deny-hit" ? "its output involved sensitive-path deny-listed entries the exclusion globs cannot express" : "its output contained a record the line format cannot account for";
     return {
         text: text.startsWith("Error (grep)")
             ? text
             : `${text}\n[note: the ripgrep pass was abandoned (${why}); results are from the fallback scanner, which prunes with the authoritative deny judge]`,
+        ...(rows !== undefined ? { rows } : {}),
         degraded: { fallback: "js-scan", reason: `ripgrep output tripped the deny tripwire (${trip.reason})` },
         ...(denyOut.withheld !== undefined ? { withheld: denyOut.withheld } : {}),
     };
 }
 async function jsGrepFallback(env, root, p, signal, reason, deny) {
     const denyOut = {};
-    const text = await jsGrep(env, root, p, signal, undefined, deny, denyOut);
+    const { text, rows } = await jsGrepDetailed(env, root, p, signal, undefined, deny, denyOut);
     return {
         text: text.startsWith("Error (grep)")
             ? text
             : `${text}\n[note: ripgrep failed (${reason}); results are from a fallback scanner]`,
+        ...(rows !== undefined ? { rows } : {}),
         degraded: { fallback: "js-scan", reason: `ripgrep failed (${reason})` },
         ...(denyOut.withheld !== undefined ? { withheld: denyOut.withheld } : {}),
     };
 }
 export async function rgGrepDetailed(env, root, p, signal, deny) {
     const mode = p.output_mode ?? "files_with_matches";
-    const flags = ["--null", "--no-messages", "--no-require-git", "--hidden"];
+    const flags = ["--null", "-H", "--no-messages", "--no-require-git", "--hidden"];
     for (const d of VCS_DIRS)
         flags.push("--glob", `!${d}`);
     flags.push("--max-columns", "500", "--max-columns-preview");
@@ -1193,7 +1241,7 @@ export async function rgGrepDetailed(env, root, p, signal, deny) {
                 if (records.length === 0)
                     return jsGrepFallback(env, root, p, signal, "timed out before completing a result", deny);
                 return {
-                    text: `${delimitUntrusted("ripgrep partial output", formatRgRecords(records, p))}\n…[ripgrep timed out after producing partial output — results may be incomplete]`,
+                    ...(() => { const f = formatRgRecords(records, p); return { text: `${delimitUntrusted("ripgrep partial output", f.text)}\n…[ripgrep timed out after producing partial output — results may be incomplete]`, rows: f.served }; })(),
                     degraded: { partial: true, reason: "ripgrep timed out" },
                 };
             }
@@ -1205,6 +1253,12 @@ export async function rgGrepDetailed(env, root, p, signal, deny) {
     const denyDisclosure = async () => {
         if (deny === undefined || deny.rgExclusionGlobs.length === 0)
             return { note: "" };
+        if (p.path) {
+            const startPath = isAbsolutePathForm(p.path) ? p.path : `${root.replace(/[\\/]+$/, "")}${root.includes("\\") ? "\\" : "/"}${p.path}`;
+            const info = await env.fileInfo(startPath, signal);
+            if (info.ok && info.value.kind === "file")
+                return { note: "" };
+        }
         const withheld = await rgDenyExistenceProbe(env, root, deny, target, signal);
         if (withheld === undefined)
             return { note: "" };
@@ -1215,7 +1269,7 @@ export async function rgGrepDetailed(env, root, p, signal, deny) {
     };
     if (exitCode === 1) {
         const d = await denyDisclosure();
-        return { text: NO_MATCHES + d.note, ...(d.withheld !== undefined ? { withheld: d.withheld } : {}) };
+        return { text: NO_MATCHES + d.note, rows: [], ...(d.withheld !== undefined ? { withheld: d.withheld } : {}) };
     }
     if (exitCode >= 2) {
         if (stdout.trim().length > 0) {
@@ -1228,7 +1282,7 @@ export async function rgGrepDetailed(env, root, p, signal, deny) {
             if (records.length === 0)
                 return jsGrepFallback(env, root, p, signal, `exited with code ${exitCode} and produced no complete result`, deny);
             return {
-                text: `${delimitUntrusted("ripgrep partial output", formatRgRecords(records, p))}\n…[ripgrep exited with an error after producing partial output — results may be incomplete]`,
+                ...(() => { const f = formatRgRecords(records, p); return { text: `${delimitUntrusted("ripgrep partial output", f.text)}\n…[ripgrep exited with an error after producing partial output — results may be incomplete]`, rows: f.served }; })(),
                 degraded: { partial: true, reason: `ripgrep exited with code ${exitCode}` },
             };
         }
@@ -1242,7 +1296,8 @@ export async function rgGrepDetailed(env, root, p, signal, deny) {
     const parsed = parseRgRecords(stdout, mode);
     const ordered = mode === "files_with_matches" ? await sortRgFilesByMtime(env, root, parsed, signal) : parsed;
     const d = await denyDisclosure();
-    return { text: formatRgRecords(ordered, p) + d.note, ...(d.withheld !== undefined ? { withheld: d.withheld } : {}) };
+    const formatted = formatRgRecords(ordered, p);
+    return { text: formatted.text + d.note, rows: formatted.served, ...(d.withheld !== undefined ? { withheld: d.withheld } : {}) };
 }
 async function rgDenyExistenceProbe(env, root, deny, target, signal) {
     const probeFlags = ["--files", "--hidden", "--no-require-git", "--no-messages"];
@@ -1277,8 +1332,8 @@ export async function runGrepDetailed(env, root, p, signal, deny) {
     if (await detectRipgrep(env))
         return rgGrepDetailed(env, root, p, signal, deny);
     const denyOut = {};
-    const text = await jsGrep(env, root, p, signal, undefined, deny, denyOut);
-    return { text, ...(denyOut.withheld !== undefined ? { withheld: denyOut.withheld } : {}) };
+    const { text, rows } = await jsGrepDetailed(env, root, p, signal, undefined, deny, denyOut);
+    return { text, ...(rows !== undefined ? { rows } : {}), ...(denyOut.withheld !== undefined ? { withheld: denyOut.withheld } : {}) };
 }
 export async function runGrep(env, root, p, signal) {
     return (await runGrepDetailed(env, root, p, signal)).text;