@sema-agent/core 5.42.0 → 5.43.0

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## 5.43.0 — 2026-08-18
+
+### Added
+- `TaskResult.checkpointId` — the non-secret checkpoint identity now rides the suspended /
+  needs_review terminals beside `checkpointToken` (full chain: mint → publishCommittedSuspend →
+  suspend/review ref → runTask ref copy → assemble-result; the ref copy is an explicit-key
+  whitelist and the new key crosses it). **Erratum for the 5.42.0 entry**: that release minted
+  `checkpointId` on `Checkpoint`/`CheckpointSummary` only — it did NOT yet reach `TaskResult`;
+  the entry omitted that boundary. This release completes the face.
+- `NodeExecutionEnv` constructor seat `onSecretEnvScrub` (#316): the Bash exec site's secret-env
+  scrub decision is observable. Findings name the denylist-matched keys withheld from the child
+  env; a caller-overridden key (constructor `shellEnv` or per-exec `env`) is NOT reported withheld —
+  the child has it by the caller's explicit choice; an async seat's rejection is consumed (an announcement must
+  never become an exec failure); unwired builds print a once-per-process console summary.
+  Companion doc fix (#315, doc half): the scrub matches key NAMES against the denylist — a secret
+  VALUE under an innocent name is not detected; the doc now says so where the denylist lives.
+- Grep structured rows (#313, first stage): the ripgrep legs hand their served rows
+  (`{path?, text}`, post cap/offset) to the tool layer, and `grepDetailFields` prefers row
+  identity when every served row carries it — `details.filenames` on rg legs no longer re-parses
+  paths out of formatted text (a path containing `:digits:` can no longer split wrong). Text
+  parsing remains the honest fallback (JS fallback leg unchanged; its rows stage is a later
+  window).
+
+### Changed
+- Grep's ripgrep legs always pass `-H` (#311): a single explicit file target keeps its path
+  field, so a deny-guarded single-file grep keeps the rg fast path instead of abandoning rg for
+  the JS scanner's explicit-file lane (an engine swap over that one file, losing rg's
+  streaming/large-file handling). Observable flip, both arms: content-mode output for a single
+  explicit file target now carries a path prefix in the TARGET's spelling as passed (the tool
+  layer hands an absolute canonical path, so the prefix is ABSOLUTE); without a deny judge the
+  line previously had no prefix, and WITH one it previously came from the JS lane with a
+  root-relative prefix — both spellings change. Multi-file and directory targets: byte-identical
+  (measured). The two engines still disagree on path shape for the same call (jsGrep emits
+  root-relative) — that alignment is tracked separately (#318), not silently changed here.
+- The deny-withholding note no longer fabricates on single-file scopes (5.43 rescan): `rg --files`
+  lists an explicitly named file argument regardless of glob filters, so the existence probe
+  behind the note would have claimed "entries were excluded" on every deny-wired single-file grep
+  the `-H` change made reachable. A target the stat probe proves is a FILE is judged clean without
+  the probe — the tool layer already judged that one target against the same deny table before
+  the engine ran, and a scope of exactly one served file has nothing else to withhold. Directory
+  scopes keep the probe unchanged.
+- A clean no-match ripgrep run now carries `rows: []` (5.43 rescan): the one rg terminal that
+  omitted the served-rows key, breaking the "rows present ⟺ ripgrep leg" reading.
+- `onSecretEnvScrub` judges its seat by FUNCTION-ness (5.43 rescan): a present non-function seat
+  (null, an untyped host's JSON wiring) no longer silences both channels at once — the findings
+  keep the seatless once-per-process console summary and the seat defect itself is announced once
+  per process (the #170 shape; loud-bad-value law).
+
 ## 5.42.0 — 2026-08-18
 
 ### Added

package/dist/core/runner/assemble-result.d.ts

@@ -170,6 +170,8 @@ export interface ResultFlags {
      *  but does not set `threw`, so it never reaches the `flags.threw` branch. */
     suspendRef?: {
         token: import("../checkpoint-store.js").CheckpointToken;
+        /** The non-secret identity twin ({@link import("../checkpoint-store.js").Checkpoint.checkpointId}). */
+        checkpointId?: string;
         gate: import("../checkpoint-store.js").CheckpointGate;
         /** RB-439-b: how the paused workspace comes back (`"park_only"` = a non-suspendable target that was
          *  never actually paused). Echoed on `TaskResult.workspaceRestoreMode`; absent for a process-local
@@ -190,6 +192,7 @@ export interface ResultFlags {
      *  so it never hits the failure branches above. */
     reviewRef?: {
         token: import("../checkpoint-store.js").CheckpointToken;
+        checkpointId?: string;
         gate: import("../checkpoint-store.js").CheckpointGate;
         /** RB-439-b: the review pause pauses the same workspace the approval pause does — same discriminant. */
         restoreMode?: "snapshot" | "park_only";

package/dist/core/runner/assemble-result.js

@@ -60,6 +60,7 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
     let blockedReason;
     let salvagedOutput;
     let checkpointToken;
+    let checkpointId;
     let checkpointGate;
     let workspaceRestoreMode;
     const isDegenerate = final?.stopReason === "error" && isDegenerateCutMessage(final);
@@ -114,6 +115,7 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
     else if (flags.suspendRef) {
         status = "suspended";
         checkpointToken = flags.suspendRef.token;
+        checkpointId = flags.suspendRef.checkpointId;
         checkpointGate = flags.suspendRef.gate;
         workspaceRestoreMode = flags.suspendRef.restoreMode;
     }
@@ -121,6 +123,7 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
         status = "needs_review";
         errorCode = "review.pending";
         checkpointToken = flags.reviewRef.token;
+        checkpointId = flags.reviewRef.checkpointId;
         checkpointGate = flags.reviewRef.gate;
         workspaceRestoreMode = flags.reviewRef.restoreMode;
     }
@@ -162,5 +165,5 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
     void _internalCompaction;
     if (flags.unpricedSpend)
         delete publicStats.costMicroUsd;
-    return { taskId, sessionId, status, ...(flags.model !== undefined ? { model: flags.model } : {}), result: result.trim(), salvagedOutput, blockedReason, errorMessage, errorCode, ...(retryAfterMs !== undefined ? { retryAfterMs } : {}), checkpointToken, checkpointGate, ...(workspaceRestoreMode !== undefined ? { workspaceRestoreMode } : {}), ...(flags.rewindNotes !== undefined && flags.rewindNotes.length > 0 ? { rewindNotes: flags.rewindNotes } : {}), ...(flags.remoteEnvFailures !== undefined && flags.remoteEnvFailures.length > 0 ? { remoteEnvFailures: flags.remoteEnvFailures } : {}), ...(flags.strandedHumanAnswers !== undefined && flags.strandedHumanAnswers.length > 0 ? { strandedHumanAnswers: flags.strandedHumanAnswers } : {}), ...(flags.effectiveReadFace !== undefined ? { effectiveReadFace: flags.effectiveReadFace } : {}), ...(flags.effectiveReadDenyPatterns !== undefined && flags.effectiveReadDenyPatterns.length > 0 ? { effectiveReadDenyPatterns: flags.effectiveReadDenyPatterns } : {}), ...(flags.effectiveMemoryScopes !== undefined ? { effectiveMemoryScopes: flags.effectiveMemoryScopes } : {}), stats: publicStats };
+    return { taskId, sessionId, status, ...(flags.model !== undefined ? { model: flags.model } : {}), result: result.trim(), salvagedOutput, blockedReason, errorMessage, errorCode, ...(retryAfterMs !== undefined ? { retryAfterMs } : {}), checkpointToken, ...(checkpointId !== undefined ? { checkpointId } : {}), checkpointGate, ...(workspaceRestoreMode !== undefined ? { workspaceRestoreMode } : {}), ...(flags.rewindNotes !== undefined && flags.rewindNotes.length > 0 ? { rewindNotes: flags.rewindNotes } : {}), ...(flags.remoteEnvFailures !== undefined && flags.remoteEnvFailures.length > 0 ? { remoteEnvFailures: flags.remoteEnvFailures } : {}), ...(flags.strandedHumanAnswers !== undefined && flags.strandedHumanAnswers.length > 0 ? { strandedHumanAnswers: flags.strandedHumanAnswers } : {}), ...(flags.effectiveReadFace !== undefined ? { effectiveReadFace: flags.effectiveReadFace } : {}), ...(flags.effectiveReadDenyPatterns !== undefined && flags.effectiveReadDenyPatterns.length > 0 ? { effectiveReadDenyPatterns: flags.effectiveReadDenyPatterns } : {}), ...(flags.effectiveMemoryScopes !== undefined ? { effectiveMemoryScopes: flags.effectiveMemoryScopes } : {}), stats: publicStats };
 }

package/dist/core/runner/prepare-task.d.ts

@@ -433,6 +433,7 @@ export interface Prepared {
      *  fired this run. */
     suspendRef: {
         token?: CheckpointToken;
+        checkpointId?: string;
         gate?: CheckpointGate;
         scope?: string;
         restoreMode?: "snapshot" | "park_only";
@@ -453,6 +454,7 @@ export interface Prepared {
      *  `status:"needs_review"`. Empty unless a review pause fired this run. */
     reviewRef: {
         token?: CheckpointToken;
+        checkpointId?: string;
         gate?: CheckpointGate;
         scope?: string;
         restoreMode?: "snapshot" | "park_only";

package/dist/core/runner/prepare-task.js

@@ -3537,9 +3537,11 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     return { ok: false, reason };
                 }
             };
-            const publishCommittedSuspend = (token, gate, scope, remoteHandle) => {
+            const publishCommittedSuspend = (token, gate, scope, remoteHandle, checkpointId) => {
                 const ref = gate.kind === "needs_review" || gate.kind === "plan_review" ? reviewRef : suspendRef;
                 ref.token = token;
+                if (checkpointId !== undefined)
+                    ref.checkpointId = checkpointId;
                 ref.gate = gate;
                 if (remoteHandle !== undefined)
                     ref.restoreMode = remoteHandle.restoreMode === "park_only" ? "park_only" : "snapshot";
@@ -3625,7 +3627,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 };
                 if (!(await commitSuspendSaga(token, cp, suspendableEnv, remoteHandle)).ok)
                     return false;
-                publishCommittedSuspend(token, gate, scope, remoteHandle);
+                publishCommittedSuspend(token, gate, scope, remoteHandle, cp.checkpointId);
                 try {
                     await sessions.pin?.(sessionId);
                 }
@@ -3711,7 +3713,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     };
                     if (!(await commitSuspendSaga(token, cp, suspendableEnv, remoteHandle)).ok)
                         return false;
-                    publishCommittedSuspend(token, gate, scope, remoteHandle);
+                    publishCommittedSuspend(token, gate, scope, remoteHandle, cp.checkpointId);
                     try {
                         await sessions.pin?.(sessionId);
                     }
@@ -4006,7 +4008,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     if (!committed.ok) {
                         return committed.reason !== undefined ? { parkFailed: committed.reason } : undefined;
                     }
-                    publishCommittedSuspend(token, gate, cp.scope, remoteHandle);
+                    publishCommittedSuspend(token, gate, cp.scope, remoteHandle, cp.checkpointId);
                     try {
                         await sessions.pin?.(sessionId);
                     }

package/dist/core/runner/runtask.js

@@ -3472,6 +3472,7 @@ export class Runner {
                 suspendRef: prepared.suspendRef.token !== undefined && prepared.suspendRef.gate !== undefined
                     ? {
                         token: prepared.suspendRef.token,
+                        ...(prepared.suspendRef.checkpointId !== undefined ? { checkpointId: prepared.suspendRef.checkpointId } : {}),
                         gate: prepared.suspendRef.gate,
                         ...(prepared.suspendRef.restoreMode !== undefined ? { restoreMode: prepared.suspendRef.restoreMode } : {}),
                     }
@@ -3479,6 +3480,7 @@ export class Runner {
                 reviewRef: prepared.reviewRef.token !== undefined && prepared.reviewRef.gate !== undefined
                     ? {
                         token: prepared.reviewRef.token,
+                        ...(prepared.reviewRef.checkpointId !== undefined ? { checkpointId: prepared.reviewRef.checkpointId } : {}),
                         gate: prepared.reviewRef.gate,
                         ...(prepared.reviewRef.restoreMode !== undefined ? { restoreMode: prepared.reviewRef.restoreMode } : {}),
                     }

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;

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

@@ -9,7 +9,7 @@ import type { ReadFace } from "./read-face.js";
  * replace the text parsing with structured rows from runGrep; until then this seam is 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

@@ -210,8 +210,19 @@ 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 (first stage, rg legs) — one SERVED result row with its path read from ripgrep's own
+ *  field ({@link parseRgRecords}), exactly the window `text` shows (post cap/offset). The tool
+ *  layer prefers these over re-parsing `text` (whose `path:line:text` split mis-cuts a path that
+ *  itself contains `:digits:`); absent = a leg that has no structured rows yet (the JS scanner —
+ *  its rows stage is the ticket's remainder) and the text parse is the honest fallback. */
+export interface GrepRow {
+    path?: string;
+    text: string;
+}
 export interface GrepRunResult {
     text: string;
+    /** Served rows (#313): present on the ripgrep legs, absent on the JS-scanner legs. */
+    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

@@ -1096,12 +1096,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)
@@ -1143,7 +1147,7 @@ async function jsGrepFallback(env, root, p, signal, reason, deny) {
 }
 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 +1197,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 +1209,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 +1225,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 +1238,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 +1252,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"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "5.42.0",
+  "version": "5.43.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",