@sema-agent/core 5.40.0 → 5.42.0

package/dist/core/types.d.ts

@@ -4669,6 +4669,16 @@ 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"` / `"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
      *  frequency semantics and ride the wire `status` channel ({@link BrainStatus}), whose sink the
@@ -4702,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/engine/harness/agent-harness.d.ts

@@ -80,6 +80,16 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
     private thinkingLevel;
     /** RB-30 terminal fix — runner-set sink for engine-note payloads left undrained at agent_end. */
     onUndrainedEngineNotes?: (payloads: unknown[]) => void;
+    /** backlog #259 — USER-authored queue remnants at agent_end: steers/follow-ups whose receipts said
+     *  "queued" but that no turn will ever drain (the run ended first). The engine-note sweep above
+     *  hands ENGINE payloads back for redelivery; user inputs have no redelivery semantics (a steer
+     *  aimed at a finished run must not silently fire at the next one), so their loss is ANNOUNCED
+     *  instead — the runner surfaces it as an operator notice, closing the "accepted then silently
+     *  dropped" window the #257 contract could only document. */
+    onUndrainedUserInputs?: (counts: {
+        steer: number;
+        followUp: number;
+    }) => void;
     /** design/176 — runner-set sink fired at the CONSUMPTION boundary, once per engine-note payload,
      *  in consumption order (steer/followUp drain and the turn-open nextTurn splice — the two points
      *  where a queued frame actually enters the model's input). The runner uses it to record the
@@ -99,6 +109,13 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
      *  so a double call is a no-op. */
     recoverUndrainedEngineNotes(): void;
     private sweepUndrainedEngineNotes;
+    /** backlog #259 — what remains in the steer/follow-up queues AFTER the engine-note sweep is USER
+     *  input that was accepted ("queued") and will never be consumed: the run reached agent_end first.
+     *  User inputs have no redelivery semantics (unlike engine notes — a steer aimed at a finished run
+     *  must not fire at the next one), so the loss is ANNOUNCED, never silent. The window is a narrow
+     *  race (an injection landing after the loop's final queue check), which is exactly why it needs a
+     *  loud terminal account rather than an e2e reproduction. Returns the counts for the settled frame. */
+    private announceUndrainedUserInputs;
     private systemPrompt;
     /** S4: physical system blocks (static per leg, additive — see AgentHarnessOptions.systemBlocks). */
     private systemBlocks;

package/dist/engine/harness/agent-harness.js

@@ -158,6 +158,7 @@ export class AgentHarness {
     model;
     thinkingLevel;
     onUndrainedEngineNotes;
+    onUndrainedUserInputs;
     onEngineNoteConsumed;
     recoverUndrainedEngineNotes() {
         this.sweepUndrainedEngineNotes([this.nextTurnQueue, this.steerQueue, this.followUpQueue]);
@@ -182,6 +183,17 @@ export class AgentHarness {
             }
         }
     }
+    announceUndrainedUserInputs() {
+        const counts = { steer: this.steerQueue.length, followUp: this.followUpQueue.length };
+        if ((counts.steer > 0 || counts.followUp > 0) && this.onUndrainedUserInputs) {
+            try {
+                this.onUndrainedUserInputs(counts);
+            }
+            catch {
+            }
+        }
+        return counts;
+    }
     systemPrompt;
     systemBlocks;
     streamOptions;
@@ -620,9 +632,15 @@ export class AgentHarness {
         if (event.type === "agent_end") {
             await this.flushPendingSessionWrites();
             this.sweepUndrainedEngineNotes([this.nextTurnQueue, this.steerQueue, this.followUpQueue]);
+            const undrainedUser = this.announceUndrainedUserInputs();
             this.phase = "idle";
             await this.emitAny(event, signal);
-            await this.emitOwn({ type: "settled", nextTurnCount: this.nextTurnQueue.length }, signal);
+            await this.emitOwn({
+                type: "settled",
+                nextTurnCount: this.nextTurnQueue.length,
+                ...(undrainedUser.steer > 0 ? { undrainedSteerCount: undrainedUser.steer } : {}),
+                ...(undrainedUser.followUp > 0 ? { undrainedFollowUpCount: undrainedUser.followUp } : {}),
+            }, signal);
             return;
         }
         await this.emitAny(event, signal);

package/dist/engine/harness/types.d.ts

@@ -815,6 +815,11 @@ export interface AbortEvent {
 export interface SettledEvent {
     type: "settled";
     nextTurnCount: number;
+    /** backlog #259 (additive) — USER steers accepted ("queued") but never drained before agent_end.
+     *  Present only when > 0; their loss is announced through `onUndrainedUserInputs` too. */
+    undrainedSteerCount?: number;
+    /** backlog #259 (additive) — same for the follow-up queue. */
+    undrainedFollowUpCount?: number;
 }
 export interface BeforeAgentStartEvent<TSkill extends Skill = Skill, TPromptTemplate extends PromptTemplate = PromptTemplate> {
     type: "before_agent_start";

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 {};