@sema-agent/core 5.41.0 → 5.42.0

package/dist/core/types.d.ts

@@ -4669,12 +4669,15 @@ export interface EngineNotice {
      *    value IS in force the prepare refuses with the same code as `TaskResult.errorCode` (one
      *    fact, one code, two loudness dialects); `detail: { raw }`.
      *
-     *  - `"task.user_steer_undrained"` (#259) — user steers/follow-ups whose receipts said "queued"
-     *    were still in the queues at agent_end: the run ended before any turn could drain them. They
-     *    are NOT redelivered (a steer aimed at a finished run must not fire at the next one — unlike
-     *    ENGINE notes, which pend per session); the notice is the loud half of the #257 contract's
-     *    "accepted = enqueued, not consumed" sentence; `detail: { steer, followUp, taskId? }`.
-     *    Per-run, at most once (the terminal sweep is a single site).
+     *  - `"task.user_steer_undrained"` / `"task.user_followup_undrained"` (#259) — user steers /
+     *    follow-ups whose receipts said "queued" were still in their queue at agent_end: the run
+     *    ended before any turn could drain them. One notice PER family (a consumer routing on `code`
+     *    alone must not mistake a stranded follow-up for a stranded steer — same split as the settled
+     *    frame's two count keys). They are NOT redelivered (a steer aimed at a finished run must not
+     *    fire at the next one — unlike ENGINE notes, which pend per session); the loud half of the
+     *    #257 contract's "accepted = enqueued, not consumed" sentence;
+     *    `detail: { steer, taskId? }` / `{ followUp, taskId? }`. Per-run, at most once per family
+     *    (the terminal sweep is a single site).
      *
      *  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
@@ -4709,6 +4712,16 @@ export declare function __resetMalformedNoticeSeatAnnouncement(): void;
  *  · an ABSENT seat prints the historic `console.warn` line verbatim (byte-compat loudness).
  */
 export declare function deliverEngineNotice(onNotice: ((notice: EngineNotice) => void) | undefined, notice: EngineNotice): void;
+/**
+ * #259 loud half, one notice PER FAMILY (`task.user_steer_undrained` / `task.user_followup_undrained`):
+ * a consumer routing on `code` alone must never mistake a stranded follow-up for a stranded steer, so
+ * the code carries exactly the semantics its name claims — the same two-key split the settled frame
+ * uses. Pure (the terminal sweep race window is not constructible deterministically; this seam is).
+ */
+export declare function undrainedUserInputNotices(counts: {
+    steer: number;
+    followUp: number;
+}, taskId?: string): EngineNotice[];
 /** Runtime dependencies shared across tasks. */
 export interface RunnerDeps {
     brain: Brain;

package/dist/core/types.js

@@ -49,3 +49,23 @@ export function deliverEngineNotice(onNotice, notice) {
     }
     console.warn(notice.message);
 }
+export function undrainedUserInputNotices(counts, taskId) {
+    const tid = taskId !== undefined ? { taskId } : {};
+    const tail = `accepted as "queued" were never consumed — the run ended first. They are NOT redelivered; re-send against a live run if still wanted.`;
+    const out = [];
+    if (counts.steer > 0) {
+        out.push({
+            code: "task.user_steer_undrained",
+            message: `${counts.steer} user steer(s) ${tail}`,
+            detail: { steer: counts.steer, ...tid },
+        });
+    }
+    if (counts.followUp > 0) {
+        out.push({
+            code: "task.user_followup_undrained",
+            message: `${counts.followUp} user follow-up(s) ${tail}`,
+            detail: { followUp: counts.followUp, ...tid },
+        });
+    }
+    return out;
+}

package/dist/index.d.ts

@@ -93,7 +93,7 @@ export { READ_FACE_DEFAULT_DENY_ENTRIES, READ_FACE_BUILTIN_DENY_TABLE, READ_DENY
 export { deploymentReadFaceClampNotice, resolveReadFace, type ReadFace, type ReadFaceInputs } from "./tools/fs/index.js";
 export { WRITE_PROTECTED_DEFAULT_TABLE, resolveWriteProtectedTable, compileWriteProtection, type WriteProtectedEntry, type WriteProtectedRow, type WriteProtectedKind, type WriteProtectedHit, type WriteProtectionMatcher, } from "./core/write-protect.js";
 export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, assertSafeToolResultRef, buildToolResultRef, toolResultContentSegment, MAX_MINTED_TOOL_RESULT_REF_CHARS, type ToolResultProvenance, assertToolResultProvenanceMatch, normalizeToolResultProvenance, toolResultProvenanceOf, ToolResultRefConflictError, TOOL_RESULT_REF_CONFLICT_CODE, type ToolResultStore, type ToolResultSlice, type ToolResultDeletionReport, } from "./core/tool-result-store.js";
-export { InMemoryCheckpointStore, CheckpointError, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingTokens, winnerFromOutcome, validatePendingSteer, readPendingSteerQueue, appendPendingSteer, MAX_PENDING_STEER_CHARS, MAX_PENDING_STEER_ENTRIES, PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES, PENDING_STEER_FROZEN_FIELDS, ACTOR_ASSERTION_FROZEN_FIELDS, MAX_ACTOR_FIELD_CHARS, MAX_STEER_INPUT_ID_CHARS, LEGACY_PENDING_STEER_INPUT_ID, type ActorAssertion, type PendingSteerEntry, type PendingSteerInput, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, type RiskDescriptor, type ProbeCause, type ProbeCauseOperands, type CheckpointStore, type CheckpointSummary, type Checkpoint, type CheckpointToken, type CheckpointGate, type CheckpointState, type SerializedCheckpointState, type CheckpointFaultMode, type PendingAction, type ResumeOutcome, type ResolvedOutcome, type ReopenReason, type ResolveExpectation, type SafetyAxis, type RealApprovalGateBit, type ResourceLedger, type ResourceLimitReason, type PlatformLimitReason, } from "./core/checkpoint-store.js";
+export { InMemoryCheckpointStore, CheckpointError, mintCheckpointId, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingTokens, winnerFromOutcome, validatePendingSteer, readPendingSteerQueue, appendPendingSteer, MAX_PENDING_STEER_CHARS, MAX_PENDING_STEER_ENTRIES, PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES, PENDING_STEER_FROZEN_FIELDS, ACTOR_ASSERTION_FROZEN_FIELDS, MAX_ACTOR_FIELD_CHARS, MAX_STEER_INPUT_ID_CHARS, LEGACY_PENDING_STEER_INPUT_ID, type ActorAssertion, type PendingSteerEntry, type PendingSteerInput, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, type RiskDescriptor, type ProbeCause, type ProbeCauseOperands, type CheckpointStore, type CheckpointSummary, type Checkpoint, type CheckpointToken, type CheckpointGate, type CheckpointState, type SerializedCheckpointState, type CheckpointFaultMode, type PendingAction, type ResumeOutcome, type ResolvedOutcome, type ReopenReason, type ResolveExpectation, type SafetyAxis, type RealApprovalGateBit, type ResourceLedger, type ResourceLimitReason, type PlatformLimitReason, } from "./core/checkpoint-store.js";
 export { InMemoryUsageWindowStore, GLOBAL_USAGE_KEY, EMPTY_USAGE_WINDOW_RECORD, chargeUsageRecord, readUsageRecord, usageRetryAfterMs, resolveUsageWindows, type UsageWindow, type UsageWindowStore, type UsageWindowReading, type UsageWindowRecord, type UsageSlot, type UsageBucketRow, } from "./core/usage-window-store.js";
 export { FileUsageWindowStore } from "./stores/file/usage-window-store.js";
 export { ENV_LIFETIME_SUSPEND_MARGIN_MS, USAGE_WINDOW_REAP_MARGIN_MS } from "./core/runner/prepare-task.js";

package/dist/index.js

@@ -73,7 +73,7 @@ export { READ_FACE_DEFAULT_DENY_ENTRIES, READ_FACE_BUILTIN_DENY_TABLE, READ_DENY
 export { deploymentReadFaceClampNotice, resolveReadFace } from "./tools/fs/index.js";
 export { WRITE_PROTECTED_DEFAULT_TABLE, resolveWriteProtectedTable, compileWriteProtection, } from "./core/write-protect.js";
 export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, assertSafeToolResultRef, buildToolResultRef, toolResultContentSegment, MAX_MINTED_TOOL_RESULT_REF_CHARS, assertToolResultProvenanceMatch, normalizeToolResultProvenance, toolResultProvenanceOf, ToolResultRefConflictError, TOOL_RESULT_REF_CONFLICT_CODE, } from "./core/tool-result-store.js";
-export { InMemoryCheckpointStore, CheckpointError, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingTokens, winnerFromOutcome, validatePendingSteer, readPendingSteerQueue, appendPendingSteer, MAX_PENDING_STEER_CHARS, MAX_PENDING_STEER_ENTRIES, PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES, PENDING_STEER_FROZEN_FIELDS, ACTOR_ASSERTION_FROZEN_FIELDS, MAX_ACTOR_FIELD_CHARS, MAX_STEER_INPUT_ID_CHARS, LEGACY_PENDING_STEER_INPUT_ID, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, } from "./core/checkpoint-store.js";
+export { InMemoryCheckpointStore, CheckpointError, mintCheckpointId, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingTokens, winnerFromOutcome, validatePendingSteer, readPendingSteerQueue, appendPendingSteer, MAX_PENDING_STEER_CHARS, MAX_PENDING_STEER_ENTRIES, PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES, PENDING_STEER_FROZEN_FIELDS, ACTOR_ASSERTION_FROZEN_FIELDS, MAX_ACTOR_FIELD_CHARS, MAX_STEER_INPUT_ID_CHARS, LEGACY_PENDING_STEER_INPUT_ID, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, } from "./core/checkpoint-store.js";
 export { InMemoryUsageWindowStore, GLOBAL_USAGE_KEY, EMPTY_USAGE_WINDOW_RECORD, chargeUsageRecord, readUsageRecord, usageRetryAfterMs, resolveUsageWindows, } from "./core/usage-window-store.js";
 export { FileUsageWindowStore } from "./stores/file/usage-window-store.js";
 export { ENV_LIFETIME_SUSPEND_MARGIN_MS, USAGE_WINDOW_REAP_MARGIN_MS } from "./core/runner/prepare-task.js";

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

@@ -2,6 +2,14 @@ import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
 import type { ToolEffect } from "../../core/types.js";
 import type { ReadDenyMatcher } from "./read-deny.js";
 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.
+ */
+export declare function grepDetailFields(text: string, mode: "files_with_matches" | "content" | "count", offset?: number): 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,6 +2,72 @@ 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) {
+    const rows = text.startsWith("No matches.")
+        ? []
+        : text
+            .split("\n")
+            .filter((l) => l.length > 0 &&
+            l !== "No matches." &&
+            !l.startsWith("…[") &&
+            !l.startsWith("[offset") &&
+            !l.startsWith("[note") &&
+            !l.startsWith("[!]") &&
+            !l.startsWith("<<<UNTRUSTED ") &&
+            !l.startsWith("<<<END UNTRUSTED "));
+    const contentPathOf = (l) => {
+        const m = /^(.*?):(\d+):/.exec(l);
+        return m ? m[1] : l;
+    };
+    const byteTruncated = text.includes("…[output truncated at ");
+    const truncatedFlag = byteTruncated ? { truncated: true } : {};
+    const capMarker = /^…\[capped at (\d+) of (\d+)\]$/m.exec(text);
+    const cappedAt = capMarker ? Number(capMarker[1]) : undefined;
+    const capTotal = capMarker ? Number(capMarker[2]) : undefined;
+    const appliedOffset = typeof offset === "number" && offset > 0 ? { appliedOffset: 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 };
+    }
+    else if (mode === "count") {
+        const filenames = [...new Set(rows.map((l) => (l.includes(":") ? l.slice(0, l.lastIndexOf(":")) : l)))];
+        let numMatches = 0;
+        let malformed = false;
+        for (const l of rows) {
+            const m = /:(\d+)$/.exec(l);
+            if (m)
+                numMatches += Number(m[1]);
+            else
+                malformed = true;
+        }
+        detailFields = {
+            filenames,
+            numFiles: filenames.length,
+            content: rows.join("\n"),
+            ...(malformed || byteTruncated ? {} : { numMatches }),
+            ...truncatedFlag,
+            ...appliedLimit,
+            ...appliedOffset,
+        };
+    }
+    else {
+        const filenames = [...new Set(rows.map(contentPathOf))];
+        const joined = rows.join("\n");
+        const GREP_CONTENT_PREVIEW_CHARS = 16_000;
+        detailFields = {
+            filenames,
+            numFiles: filenames.length,
+            content: joined.length > GREP_CONTENT_PREVIEW_CHARS ? `${joined.slice(0, GREP_CONTENT_PREVIEW_CHARS)}\n…[truncated — full text in the tool output]` : joined,
+            numLines: rows.length,
+            ...(byteTruncated ? {} : { totalLines: capTotal ?? rows.length }),
+            ...truncatedFlag,
+            ...appliedLimit,
+            ...appliedOffset,
+        };
+    }
+    return detailFields;
+}
 export function createGrepTool(env, rootCanonical, additionalRoots, readDeny, readFace) {
     return defineTool({
         name: "Grep",
@@ -95,64 +161,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 rows = text.startsWith("No matches.")
-                ? []
-                : text
-                    .split("\n")
-                    .filter((l) => l.length > 0 &&
-                    !l.startsWith("…[") &&
-                    !l.startsWith("[offset") &&
-                    !l.startsWith("[note") &&
-                    !l.startsWith("[!]") &&
-                    !l.startsWith("<<<UNTRUSTED ") &&
-                    !l.startsWith("<<<END UNTRUSTED "));
-            const contentPathOf = (l) => {
-                const m = /^(.*?):(\d+):/.exec(l);
-                return m ? m[1] : l;
-            };
-            const capMarker = /^…\[capped at (\d+) of (\d+)\]$/m.exec(text);
-            const cappedAt = capMarker ? Number(capMarker[1]) : undefined;
-            const capTotal = capMarker ? Number(capMarker[2]) : undefined;
-            const appliedOffset = typeof a.offset === "number" && a.offset > 0 ? { appliedOffset: a.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 };
-            }
-            else if (mode === "count") {
-                const filenames = [...new Set(rows.map((l) => (l.includes(":") ? l.slice(0, l.lastIndexOf(":")) : l)))];
-                let numMatches = 0;
-                let malformed = false;
-                for (const l of rows) {
-                    const m = /:(\d+)$/.exec(l);
-                    if (m)
-                        numMatches += Number(m[1]);
-                    else
-                        malformed = true;
-                }
-                detailFields = {
-                    filenames,
-                    numFiles: filenames.length,
-                    content: rows.join("\n"),
-                    ...(malformed ? {} : { numMatches }),
-                    ...appliedLimit,
-                    ...appliedOffset,
-                };
-            }
-            else {
-                const filenames = [...new Set(rows.map(contentPathOf))];
-                const joined = rows.join("\n");
-                const GREP_CONTENT_PREVIEW_CHARS = 16_000;
-                detailFields = {
-                    filenames,
-                    numFiles: filenames.length,
-                    content: joined.length > GREP_CONTENT_PREVIEW_CHARS ? `${joined.slice(0, GREP_CONTENT_PREVIEW_CHARS)}\n…[truncated — full text in the tool output]` : joined,
-                    numLines: rows.length,
-                    totalLines: capTotal ?? rows.length,
-                    ...appliedLimit,
-                    ...appliedOffset,
-                };
-            }
+            const detailFields = grepDetailFields(text, mode, a.offset);
             return {
                 content: text,
                 details: { type: "grep", mode, ...detailFields, ...(grepRun.degraded ?? {}), ...(grepRun.withheld !== undefined ? { withheld: grepRun.withheld } : {}) },

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

@@ -1,4 +1,9 @@
 import type { ExecutionEnv } from "../../internal/harness-types.js";
+/** backlog #310 — the JS scanner's own output ceiling, in bytes of emitted content rows. Pinned to the
+ *  ripgrep leg's figure ({@link MAX_EXEC_OUTPUT_BYTES}, the exec pipe's rolling-tail bound) so the two
+ *  legs cannot disagree about how much one search may return; see the collection site in {@link jsGrep}
+ *  for why this leg bounds the HEAD where the pipe bounds the tail. */
+export declare const JS_GREP_OUTPUT_MAX_BYTES: number;
 /** Directories never worth crawling (design/64 §10.3) — dependency/build/cache trees, PLUS the VCS
  *  metadata directories CC names explicitly (RB-200 F1, 220 @368402: `Ok_ = [".git",".svn",".hg",
  *  ".bzr",".jj",".sl"]` — git/svn/mercurial/bazaar/jujutsu/sapling). `.bzr`/`.jj`/`.sl` are additive here
@@ -153,6 +158,10 @@ export interface JsGrepGuards {
     budgetMs?: number;
     /** Longest line/content (chars) a gray-zone pattern may be matched against. */
     longLineLimit?: number;
+    /** backlog #310 — bytes of content rows this scan may accumulate before it stops collecting and
+     *  says so (default {@link JS_GREP_OUTPUT_MAX_BYTES}). A seam for the same reason the two above
+     *  are: the boundary is pinnable at a testable size instead of only at an 8MB harness. */
+    outputMaxBytes?: number;
 }
 /** design/199 件B — what a traversal withheld under the sensitive-path read deny list, structured
  *  (the prose note is the model-facing twin). Three shapes (§3.1): `pruned_count` = the JS walker
@@ -208,6 +217,8 @@ export interface GrepRunResult {
      *  withheld / no deny judge in play. */
     withheld?: ReadDenyWithheld;
 }
+/** The output modes the rg leg and {@link jsGrep} share. */
+type GrepOutputMode = "content" | "files_with_matches" | "count";
 /**
  * backlog #303 (rescan-hardened form) — the rg leg's deny TRIPWIRE. rg's exclusion globs are spelled
  * from the pattern text and cannot express the win32 component-alias family (`.aws.` / `.aws ` —
@@ -220,21 +231,31 @@ export interface GrepRunResult {
  * ripgrep prints filenames verbatim, so a path component containing a NEWLINE splits one record
  * across physical lines whose fragments carry no `:line:` boundary — the filter kept them and the
  * deny-listed content passed (a protection hole, not a precision residual); and pruning every line
- * of a partial run fabricated a `No matches.` row inside the structured card. Text-splitting rg
- * records is unsalvageable without structured output (`--json`, backlog #306), so this function no
- * longer edits anything: it JUDGES. Any deny hit — or any line the format cannot account for —
+ * of a partial run fabricated a `No matches.` row inside the structured card. So this function no
+ * longer edits anything: it JUDGES. Any deny hit — or any record the format cannot account for —
  * trips, and the caller abandons the rg run for the JS scanner, whose walk prunes with the
  * authoritative judge and needs no path parsing at all. rg stays the fast path for the common case
  * (no guarded entries in the result); the moment a guarded spelling is involved, the engine that
  * cannot mis-parse it owns the answer.
  *
- * Trip conditions by mode — `files_with_matches`: every line IS a path, judged whole; `count`:
- * `path:N` (a line without the numeric tail is a split record — ambiguous, trip); `content`:
- * judged at EVERY `:digits:` boundary and every `-digits-` boundary (a candidate cut inside match
- * text can over-trip — safe: the fallback re-derives the exact answer), and a non-separator line
- * with NO boundary at all is a split record — trip. `--` separators and empty lines pass.
+ * backlog #306 — what it judges is now ripgrep's OWN path field ({@link parseRgRecords}, `--null`),
+ * not a prefix cut at a guessed separator. Trip conditions, all three modes alike: a record whose
+ * path the deny judge names trips as `deny-hit`; a record with no path field at all (rg's binary-file
+ * notice, a no-filename row, an unterminated tail, output from an env that ignored `--null`) is
+ * unaccountable and trips as `ambiguous-record` — same abandonment, same reason code as before.
+ * `dropIncompleteTail` mirrors {@link parseRgRecords}: on the partial legs the cut tail is dropped
+ * BEFORE judging, because judging a record the caller will never receive can only cost an
+ * unnecessary rescan — every record that does reach the output is still judged, which is what the
+ * rule is for. (A killed stream ending mid-record is an EXPECTED shape with a rule of its own; the
+ * unaccountable arm is for records that survive that rule.)
+ * `--` group separators and empty lines carry no path by construction and pass. The `:digits:` /
+ * `-digits-` boundary family this used to reason about is gone with the guessing: both of #303's
+ * declared residuals (over-tripping on a cluster inside match TEXT, and the dedup key folding two
+ * denied files whose own names carry a cluster) were artifacts of that decision, not of the judge.
  */
-export declare function rgOutputDenyTripwire(stdout: string, mode: "content" | "files_with_matches" | "count", judge: Pick<ReadDenyJudge, "matchPath">): {
+export declare function rgOutputDenyTripwire(stdout: string, mode: GrepOutputMode, judge: Pick<ReadDenyJudge, "matchPath">, opts?: {
+    dropIncompleteTail?: boolean;
+}): {
     trip: false;
 } | {
     trip: true;
@@ -285,3 +306,4 @@ export declare function runGlobDetailed(env: ExecutionEnv, root: string, pattern
     error?: string;
     withheld?: ReadDenyWithheld;
 }>;
+export {};

package/dist/tools/fs/search.js

@@ -1,9 +1,11 @@
 import { delimitUntrusted } from "../../core/untrusted-text.js";
+import { MAX_EXEC_OUTPUT_BYTES } from "../../core/exec-output-tail.js";
 import { hasBinaryExtension, isAbsolutePathForm } from "./safety.js";
 const WALK_MAX_FILES = 5000;
 const WALK_MAX_DEPTH = 32;
 const GREP_DEFAULT_CAP = 250;
 const FILE_MAX_BYTES = 5 * 1024 * 1024;
+export const JS_GREP_OUTPUT_MAX_BYTES = MAX_EXEC_OUTPUT_BYTES;
 export const DEFAULT_IGNORE_DIRS = new Set([
     "node_modules", ".git", ".hg", ".svn", ".bzr", ".jj", ".sl", "build", "dist", "out", "target",
     ".dart_tool", ".pub-cache", ".next", ".nuxt", ".gradle", ".idea", ".vscode", "Pods", ".venv", "venv",
@@ -840,6 +842,27 @@ export async function jsGrep(env, root, p, signal, guards, deny, denyOut) {
     const off = Math.min(100_000, Math.max(0, Math.floor(p.offset ?? 0)));
     const collectCap = cap + off;
     const out = [];
+    const outputMaxBytes = guards?.outputMaxBytes ?? JS_GREP_OUTPUT_MAX_BYTES;
+    let outBytes = 0;
+    let outputTruncated = false;
+    let rowsBeforeWindow = 0;
+    const pushRow = (row) => {
+        if (outputTruncated)
+            return;
+        if (rowsBeforeWindow < off) {
+            rowsBeforeWindow++;
+            return;
+        }
+        if (out.length >= cap)
+            return;
+        const size = Buffer.byteLength(row, "utf8") + 1;
+        if (outBytes + size > outputMaxBytes) {
+            outputTruncated = true;
+            return;
+        }
+        outBytes += size;
+        out.push(row);
+    };
     const fileMatches = [];
     const counts = [];
     let totalContent = 0;
@@ -888,14 +911,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++) {
-                            if (out.length < collectCap)
-                                out.push(`${relOut(f)}:${s + k}:${clipLine(parts[k])}`);
+                            pushRow(`${relOut(f)}:${s + k}:${clipLine(parts[k])}`);
                         }
                         continue;
                     }
                     for (let j = Math.max(0, s - 1 - ctxB); j <= Math.min(lines.length - 1, eL - 1 + ctxA); j++) {
-                        if (out.length < collectCap)
-                            out.push(`${relOut(f)}:${j + 1}:${clipLine(lines[j])}`);
+                        pushRow(`${relOut(f)}:${j + 1}:${clipLine(lines[j])}`);
                     }
                 }
             }
@@ -924,18 +945,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)) {
-                            if (out.length < collectCap)
-                                out.push(`${relOut(f)}:${i + 1}:${clipLine(part)}`);
+                            pushRow(`${relOut(f)}:${i + 1}:${clipLine(part)}`);
                         }
                     }
                     else if (ctx > 0) {
                         for (let j = Math.max(0, i - ctxB); j <= Math.min(lines.length - 1, i + ctxA); j++) {
-                            if (out.length < collectCap)
-                                out.push(`${relOut(f)}:${j + 1}:${clipLine(lines[j])}`);
+                            pushRow(`${relOut(f)}:${j + 1}:${clipLine(lines[j])}`);
                         }
                     }
-                    else if (out.length < collectCap) {
-                        out.push(`${relOut(f)}:${i + 1}:${clipLine(lines[i])}`);
+                    else {
+                        pushRow(`${relOut(f)}:${i + 1}:${clipLine(lines[i])}`);
                     }
                 }
             }
@@ -990,15 +1009,16 @@ export async function jsGrep(env, root, p, signal, guards, deny, denyOut) {
             ? NO_MATCHES + offNote + typeNote + caveat
             : body.join("\n") + (totalFiles > off + cap ? `\n…[capped at ${cap} of ${totalFiles}]` : "") + offNote + typeNote + caveat;
     }
-    const body = paged(out);
+    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 + offNote + typeNote + caveat;
-    if (out.length < collectCap)
-        return body.join("\n") + offNote + typeNote + caveat;
+        return NO_MATCHES + byteNote + offNote + typeNote + caveat;
+    if (out.length < cap)
+        return body.join("\n") + byteNote + offNote + typeNote + caveat;
     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 + offNote + typeNote + caveat;
+    return body.join("\n") + marker + byteNote + offNote + typeNote + caveat;
 }
 const rgCache = new WeakMap();
 export function detectRipgrep(env) {
@@ -1012,79 +1032,89 @@ export function detectRipgrep(env) {
     }
     return cached;
 }
-async function sortRgFilesByMtime(env, root, stdout, signal) {
-    const paths = stdout.split("\n").filter((l) => l.length > 0);
-    if (paths.length === 0)
-        return stdout;
+async function sortRgFilesByMtime(env, root, records, signal) {
+    if (records.length === 0)
+        return [...records];
     const rootPrefix = root.replace(/[\\/]+$/, "") + (root.includes("\\") ? "\\" : "/");
     const toAbs = (p) => {
         const stripped = p.startsWith("./") ? p.slice(2) : p;
         return isAbsolutePathForm(stripped) ? stripped : `${rootPrefix}${stripped}`;
     };
+    const paths = records.map((r) => r.path ?? r.text);
     const infos = await Promise.all(paths.map((p) => env.fileInfo(toAbs(p), signal)));
-    const withMtime = paths.map((p, i) => {
-        const r = infos[i];
-        return { p, m: r.ok && typeof r.value.mtimeMs === "number" ? r.value.mtimeMs : undefined };
+    const withMtime = records.map((r, i) => {
+        const info = infos[i];
+        return { r, p: paths[i], m: info.ok && typeof info.value.mtimeMs === "number" ? info.value.mtimeMs : undefined };
     });
     const sorted = withMtime.every((x) => x.m !== undefined)
         ? [...withMtime].sort((a, b) => b.m - a.m || (a.p < b.p ? -1 : a.p > b.p ? 1 : 0))
         : [...withMtime].sort((a, b) => (a.p < b.p ? -1 : a.p > b.p ? 1 : 0));
-    return sorted.map((x) => x.p).join("\n");
+    return sorted.map((x) => x.r);
+}
+function rgRecordSeparator(mode, rest) {
+    if (mode === "count")
+        return /^\d+$/.test(rest) ? ":" : null;
+    const m = /^\d+([:\-])/.exec(rest);
+    return m === null ? null : m[1];
+}
+function parseRgRecords(stdout, mode, dropIncompleteTail = false) {
+    if (stdout.length === 0)
+        return [];
+    if (mode === "files_with_matches") {
+        if (!stdout.includes("\0")) {
+            if (dropIncompleteTail)
+                return [];
+            return stdout.split("\n").filter((l) => l.length > 0).map((l) => ({ path: l, text: l }));
+        }
+        const parts = stdout.split("\0");
+        const tail = parts.pop() ?? "";
+        const records = parts.filter((p) => p.length > 0).map((p) => ({ path: p, text: p }));
+        if (tail.length > 0 && !dropIncompleteTail)
+            records.push({ text: tail });
+        return records;
+    }
+    const lines = stdout.split("\n");
+    if (!stdout.endsWith("\n") && dropIncompleteTail)
+        lines.pop();
+    const records = [];
+    for (const line of lines) {
+        if (line.length === 0)
+            continue;
+        const nul = line.indexOf("\0");
+        const rest = nul < 0 ? "" : line.slice(nul + 1);
+        const sep = nul < 0 ? null : rgRecordSeparator(mode, rest);
+        if (nul < 0 || sep === null) {
+            records.push({ text: line });
+            continue;
+        }
+        const path = line.slice(0, nul);
+        records.push({ path, text: `${path}${sep}${rest}` });
+    }
+    return records;
 }
-function formatRgStdout(stdout, p, caveat = "") {
+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 lines = stdout.split("\n").filter((l) => l.length > 0);
-    const capped = lines.slice(off, off + cap);
+    const capped = records.slice(off, off + cap);
     if (capped.length === 0)
         return NO_MATCHES + (off > 0 ? `\n[offset ${off}]` : "") + caveat;
-    return (capped.join("\n") +
-        (lines.length > off + cap ? `\n…[capped at ${cap} of ${lines.length}]` : "") +
+    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);
 }
-export function rgOutputDenyTripwire(stdout, mode, judge) {
+export function rgOutputDenyTripwire(stdout, mode, judge, opts = {}) {
     if (stdout.length === 0)
         return { trip: false };
-    const judgeBoundaries = (line, boundary) => {
-        let sawBoundary = false;
-        for (let m = boundary.exec(line); m !== null; m = boundary.exec(line)) {
-            sawBoundary = true;
-            const prefix = line.slice(0, m.index);
-            if (prefix.length === 0)
+    for (const record of parseRgRecords(stdout, mode, opts.dropIncompleteTail === true)) {
+        if (record.path === undefined) {
+            if (record.text === "--")
                 continue;
-            const hit = judge.matchPath(prefix);
-            if (hit !== null)
-                return hit.pattern;
-        }
-        return sawBoundary ? null : "";
-    };
-    for (const line of stdout.split("\n")) {
-        if (line.length === 0 || line === "--")
-            continue;
-        if (mode === "files_with_matches") {
-            const h = judge.matchPath(line);
-            if (h !== null)
-                return { trip: true, reason: "deny-hit", pattern: h.pattern };
-        }
-        else if (mode === "count") {
-            const m = /^(.*):\d+$/.exec(line);
-            if (m === null)
-                return { trip: true, reason: "ambiguous-record" };
-            const h = judge.matchPath(m[1]);
-            if (h !== null)
-                return { trip: true, reason: "deny-hit", pattern: h.pattern };
-        }
-        else {
-            const colon = judgeBoundaries(line, /:\d+:/g);
-            if (colon !== null && colon !== "")
-                return { trip: true, reason: "deny-hit", pattern: colon };
-            const dash = judgeBoundaries(line, /-\d+-/g);
-            if (dash !== null && dash !== "")
-                return { trip: true, reason: "deny-hit", pattern: dash };
-            if (colon === "" && dash === "")
-                return { trip: true, reason: "ambiguous-record" };
+            return { trip: true, reason: "ambiguous-record" };
         }
+        const hit = judge.matchPath(record.path);
+        if (hit !== null)
+            return { trip: true, reason: "deny-hit", pattern: hit.pattern };
     }
     return { trip: false };
 }
@@ -1113,7 +1143,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 = ["--no-messages", "--no-require-git", "--hidden"];
+    const flags = ["--null", "--no-messages", "--no-require-git", "--hidden"];
     for (const d of VCS_DIRS)
         flags.push("--glob", `!${d}`);
     flags.push("--max-columns", "500", "--max-columns-preview");
@@ -1155,12 +1185,15 @@ export async function rgGrepDetailed(env, root, p, signal, deny) {
             const partial = err.partialStdout ?? "";
             if (partial.trim().length > 0) {
                 if (deny !== undefined) {
-                    const trip = rgOutputDenyTripwire(partial, mode, deny);
+                    const trip = rgOutputDenyTripwire(partial, mode, deny, { dropIncompleteTail: true });
                     if (trip.trip)
                         return jsGrepDenyTripFallback(env, root, p, signal, trip, deny);
                 }
+                const records = parseRgRecords(partial, mode, true);
+                if (records.length === 0)
+                    return jsGrepFallback(env, root, p, signal, "timed out before completing a result", deny);
                 return {
-                    text: `${delimitUntrusted("ripgrep partial output", formatRgStdout(partial, p))}\n…[ripgrep timed out after producing partial output — results may be incomplete]`,
+                    text: `${delimitUntrusted("ripgrep partial output", formatRgRecords(records, p))}\n…[ripgrep timed out after producing partial output — results may be incomplete]`,
                     degraded: { partial: true, reason: "ripgrep timed out" },
                 };
             }
@@ -1187,12 +1220,15 @@ export async function rgGrepDetailed(env, root, p, signal, deny) {
     if (exitCode >= 2) {
         if (stdout.trim().length > 0) {
             if (deny !== undefined) {
-                const trip = rgOutputDenyTripwire(stdout, mode, deny);
+                const trip = rgOutputDenyTripwire(stdout, mode, deny, { dropIncompleteTail: true });
                 if (trip.trip)
                     return jsGrepDenyTripFallback(env, root, p, signal, trip, deny);
             }
+            const records = parseRgRecords(stdout, mode, true);
+            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", formatRgStdout(stdout, p))}\n…[ripgrep exited with an error after producing partial output — results may be incomplete]`,
+                text: `${delimitUntrusted("ripgrep partial output", formatRgRecords(records, p))}\n…[ripgrep exited with an error after producing partial output — results may be incomplete]`,
                 degraded: { partial: true, reason: `ripgrep exited with code ${exitCode}` },
             };
         }
@@ -1203,9 +1239,10 @@ export async function rgGrepDetailed(env, root, p, signal, deny) {
         if (trip.trip)
             return jsGrepDenyTripFallback(env, root, p, signal, trip, deny);
     }
-    const orderedStdout = mode === "files_with_matches" ? await sortRgFilesByMtime(env, root, stdout, signal) : stdout;
+    const parsed = parseRgRecords(stdout, mode);
+    const ordered = mode === "files_with_matches" ? await sortRgFilesByMtime(env, root, parsed, signal) : parsed;
     const d = await denyDisclosure();
-    return { text: formatRgStdout(orderedStdout, p) + d.note, ...(d.withheld !== undefined ? { withheld: d.withheld } : {}) };
+    return { text: formatRgRecords(ordered, p) + d.note, ...(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.41.0",
+  "version": "5.42.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",