@bitkyc08/opencodex 2.64.0 → 2.65.0

package/src/images/artifacts.ts

@@ -14,6 +14,13 @@ const MAX_DECODED_BYTES_PER_RESPONSE = 100 * 1024 * 1024;
 export const MAX_DOWNLOAD_BYTES = 50 * 1024 * 1024; // 50 MiB
 /** Idle timeout for pinned HTTPS connect/headers/body when no AbortSignal is provided. */
 export const DOWNLOAD_IDLE_TIMEOUT_MS = 60_000;
+/**
+ * Connect deadline for pinned HTTPS downloads: a TCP/TLS setup that never
+ * completes fails with connect_timeout after 10 s instead of holding the
+ * download until the 60 s first-byte timer fires. Callers can still override
+ * per call.
+ */
+export const DOWNLOAD_CONNECT_TIMEOUT_MS = 10_000;
 
 /**
  * Upper bound on the raw base64 string length before it is decoded. Base64
@@ -271,6 +278,7 @@ export function pinnedHttpsGet(
   options?: {
     maxBytes?: number;
     idleTimeoutMs?: number;
+    connectTimeoutMs?: number;
     rejectUnauthorized?: boolean;
   },
 ): Promise<Response> {
@@ -280,9 +288,11 @@ export function pinnedHttpsGet(
   }
   const maxBytes = options?.maxBytes ?? MAX_DOWNLOAD_BYTES;
   const idleTimeoutMs = options?.idleTimeoutMs ?? DOWNLOAD_IDLE_TIMEOUT_MS;
+  const connectTimeoutMs = options?.connectTimeoutMs ?? DOWNLOAD_CONNECT_TIMEOUT_MS;
   return pinnedHttpGet(url, pinned, signal, {
     maxBytes,
     idleTimeoutMs,
+    connectTimeoutMs,
     rejectUnauthorized: options?.rejectUnauthorized,
     context: "image download",
   }).then(response => {
@@ -325,6 +335,10 @@ async function connectPublicHttps(
       // cap entirely instead of inheriting a default. Keep the 50 MiB ceiling when a
       // caller omits a limit, and honour an explicit tighter one.
       maxBytes: options.maxBytes ?? MAX_DOWNLOAD_BYTES,
+      // Bound the TCP/TLS setup phase on its own: without this, a peer that never
+      // completes the handshake holds the download until the 60 s first-byte timer
+      // fires. Covers image and video downloads (both go through here).
+      connectTimeoutMs: DOWNLOAD_CONNECT_TIMEOUT_MS,
       context: `${options.context} download`,
     }));
   return download(url, pinned, options.signal);

package/src/integrations/owned-refresh.ts

@@ -77,7 +77,7 @@ export async function refreshOwnedIntegration(
         client: input.clientId,
         ok: true,
         changed: result.changed,
-        ...(result.state === "absent" ? { reason: result.message } : {}),
+        ...(result.state !== "current" ? { reason: result.message } : {}),
       }
     : { client: input.clientId, ok: false, reason: result.message, refusalReason: result.reason, state: result.state,
         ...(result.snapshotPath ? { snapshotPath: result.snapshotPath } : {}),

package/src/integrations/ownership-policy.ts

@@ -12,7 +12,8 @@ import {
   type ManagedContribution,
   type ManagedFragment,
 } from "../clients/config-export";
-import { canonicalContribution, fingerprint, semanticContribution } from "./ownership";
+import { canonicalContribution, fingerprint, semanticContribution, type OwnershipRecord } from "./ownership";
+import { readPath } from "./merge";
 
 type JsonObject = Record<string, unknown>;
 
@@ -20,6 +21,36 @@ function isObject(value: unknown): value is JsonObject {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
+/**
+ * One-way Hermes upgrade: the old owned block is unchanged, or has only gained
+ * the supported dynamic affinity setting. Once applied, that field is protected
+ * like every other field; this is not a permanent refreshable-path exemption.
+ * Callers must first establish the record's client and config-path ownership.
+ */
+export function isHermesAffinityUpgrade(
+  doc: unknown,
+  record: OwnershipRecord,
+  desired: ManagedContribution,
+): boolean {
+  if (record.clientId !== "hermes" || desired.clientId !== "hermes") return false;
+  const path = ["providers", OPENCODE_PROVIDER_ID];
+  const matchesPath = (candidate: readonly string[]) => (
+    candidate.length === path.length && candidate.every((key, index) => key === path[index])
+  );
+  if (record.fragmentPaths.length !== 1 || !matchesPath(record.fragmentPaths[0]!)) return false;
+  const fragment = desired.fragments.find(item => matchesPath(item.path));
+  if (!isObject(fragment?.value) || fragment.value.session_affinity_header !== "session-id") return false;
+  const observed = readPath(doc, path);
+  if (!isObject(observed)) return false;
+  if (Object.hasOwn(observed, "session_affinity_header") && observed.session_affinity_header !== "session-id") return false;
+  const value = { ...observed };
+  delete value.session_affinity_header;
+  const predecessor: ManagedContribution = { clientId: "hermes", fragments: [{ path, value }] };
+  return fingerprint(canonicalContribution(predecessor)) === record.blockFingerprint
+    || (typeof record.semanticBlockFingerprint === "string"
+      && fingerprint(semanticContribution(predecessor)) === record.semanticBlockFingerprint);
+}
+
 function pathStartsWith(path: readonly string[], prefix: readonly string[]): boolean {
   return prefix.length <= path.length && prefix.every((part, index) => path[index] === part);
 }

package/src/integrations/state.ts

@@ -25,6 +25,7 @@ import {
 } from "./merge";
 import { canonicalContribution, fingerprint, semanticContribution, type OwnershipRecord } from "./ownership";
 import {
+  isHermesAffinityUpgrade,
   protectedContributionFingerprint,
   refreshablePathsOf,
   semanticProtectedContributionFingerprint,
@@ -385,7 +386,8 @@ export function classifyIntegration(input: {
    * conflict no matter what the rest of the file looks like, so the sibling-
    * edit exemption below can never mask it.
    */
-  if (!recordedBlockIsOwned(input.parsed, input.record, input.contribution)) {
+  if (!recordedBlockIsOwned(input.parsed, input.record, input.contribution)
+    && !isHermesAffinityUpgrade(input.parsed, input.record, input.contribution)) {
     return { state: "conflict", reason: "foreign-edit" };
   }
   if (!INTEGRATION_CLIENTS[clientId].sourcePreservingYaml

package/src/integrations/writer.ts

@@ -27,6 +27,7 @@ import {
   type OwnershipRecord,
 } from "./ownership";
 import {
+  isHermesAffinityUpgrade,
   protectedContributionFingerprint,
   refreshablePathsOf,
   semanticProtectedContributionFingerprint,
@@ -341,6 +342,14 @@ function applyOrRefreshIntegration(
   if (classified.state === "current") {
     return { ok: true, changed: false, state: "current", clientId, message: "already applied" };
   }
+  // Catalog refresh must not opt an existing Hermes integration into affinity.
+  // Explicit Apply (or Replace) records the new contract before refresh resumes.
+  if (!allowAbsent && record && isHermesAffinityUpgrade(parsed, record, contribution)) {
+    return {
+      ok: true, changed: false, state: "stale", clientId,
+      message: "Hermes session affinity requires Apply in Integrations; refresh left the configuration unchanged",
+    };
+  }
 
   // A stale refresh drops what the PREVIOUS record owned before merging: a
   // model that left the catalog would otherwise stay behind as an orphan the

package/src/lib/config-ownership.ts

@@ -61,8 +61,11 @@ const INITIAL_OWNED_PATHS = [
   "opencodex-service-task.xml",
   "opencodex-service.cmd",
   "opencodex-tray-offline.ico",
+  "opencodex-tray-offline-update.ico",
   "opencodex-tray-online.ico",
+  "opencodex-tray-online-update.ico",
   "opencodex-tray-warning.ico",
+  "opencodex-tray-warning-update.ico",
   "opencodex-tray.ps1",
   "responses-state.json",
   "runtime-port.json",

package/src/lib/errors.ts

@@ -156,6 +156,93 @@ function isSubscriptionGateMessage(text: string): boolean {
   );
 }
 
+/**
+ * xAI (and similar Chat Completions gateways) sometimes refuse a turn with HTTP 403
+ * and a model-refusal sentence instead of 200 + finish_reason=content_filter.
+ * Codex treats that 403 as a transport failure, so the user message is never
+ * recorded as a completed turn and retries loop. Keep this allowlist narrow:
+ * entitlement / plan / model-access 403s must stay errors.
+ */
+const POLICY_REFUSAL_PHRASES = [
+  "i can't help with that request",
+  "i cannot help with that request",
+  "i'm unable to help with that request",
+  "i am unable to help with that request",
+] as const;
+
+function hasModelAccessCue(text: string): boolean {
+  return (
+    text.includes("not allowed to use this model")
+    || text.includes("not allowed to use this operation")
+  );
+}
+
+/**
+ * xAI plan and credit 403 wording. Checked only by the refusal matcher below: adding these to
+ * the global subscription classifier would also change status and error-code inference for
+ * every message-only error that happens to mention credits.
+ */
+function hasEntitlementCue(text: string): boolean {
+  return (
+    isSubscriptionGateMessage(text)
+    || text.includes("need a grok subscription")
+    || text.includes("run out of credits")
+  );
+}
+
+/** Lowercase, collapse whitespace, and strip trailing .!? so an exact phrase match is stable. */
+function normalizePolicyRefusalSentence(text: string): string {
+  return text
+    .trim()
+    .toLowerCase()
+    .replace(/\s+/g, " ")
+    .replace(/[.!?]+$/g, "")
+    .trim();
+}
+
+/**
+ * True only when the extracted error sentence is exactly a known model-refusal
+ * phrase. JSON / "Provider error 403:" wrappers are unwrapped first. Extra
+ * plan, credit, entitlement, or model-access wording keeps the error path.
+ */
+export function isUpstreamPolicyRefusalMessage(text: string): boolean {
+  const extracted = extractPolicyRefusalText(text);
+  const originalLower = text.toLowerCase();
+  const extractedLower = extracted.toLowerCase();
+  if (hasEntitlementCue(originalLower) || hasEntitlementCue(extractedLower)) return false;
+  if (hasModelAccessCue(originalLower) || hasModelAccessCue(extractedLower)) return false;
+  const normalized = normalizePolicyRefusalSentence(extracted);
+  return (POLICY_REFUSAL_PHRASES as readonly string[]).includes(normalized);
+}
+
+/** HTTP 403 plus {@link isUpstreamPolicyRefusalMessage}; other statuses never rewrite. */
+export function isUpstreamPolicyRefusal(status: number, text: string): boolean {
+  return status === 403 && isUpstreamPolicyRefusalMessage(text);
+}
+
+/** Pull the human-readable refusal sentence out of a JSON or prefixed error body. */
+export function extractPolicyRefusalText(raw: string): string {
+  const trimmed = raw.trim();
+  try {
+    const parsed = JSON.parse(trimmed) as { error?: unknown; message?: unknown };
+    const nested = parsed.error;
+    if (typeof nested === "string" && nested.trim()) return nested.trim();
+    if (nested && typeof nested === "object") {
+      const msg = (nested as { message?: unknown; error?: unknown }).message
+        ?? (nested as { error?: unknown }).error;
+      if (typeof msg === "string" && msg.trim()) return msg.trim();
+    }
+    if (typeof parsed.message === "string" && parsed.message.trim()) return parsed.message.trim();
+  } catch {
+    /* not JSON */
+  }
+  // The proxy's own error text wraps the upstream JSON (`Provider error 403: {"error": ...}`),
+  // so the remainder after the prefix gets the same unwrapping.
+  const prefixed = trimmed.match(/^Provider error 403:\s*([\s\S]+)$/i);
+  if (prefixed?.[1]?.trim()) return extractPolicyRefusalText(prefixed[1]);
+  return trimmed;
+}
+
 function isLocalAclHardeningMessage(text: string): boolean {
   const secretPathHardening = text.includes("secret path") && (
     text.includes("acl") ||

package/src/lib/package-tree-integrity.ts

@@ -57,7 +57,7 @@ export interface PackageTreeIntegrityOptions {
 }
 
 export type ObservePackageTree = () => PackageTreeObservation | null;
-export type PackageTreeRuntimeInstall = "bun" | "npm" | "pnpm" | "source";
+export type PackageTreeRuntimeInstall = "bun" | "mise" | "npm" | "pnpm" | "source";
 
 const packageManifestUrl = new URL("../../package.json", import.meta.url);
 

package/src/lib/request-execution-budget.ts

@@ -187,6 +187,8 @@ export interface RequestExecutionBudget extends TransientSendBudget {
    * that cannot reach it has no operator override, which is the fail-closed answer.
    */
   claimAmbiguousResend?(limit: number): boolean;
+  /** True once any scope has claimed a replacement for this logical request. */
+  readonly ambiguousResendSpent?: boolean;
 }
 
 const RESERVE_FUNDED_CLASSES: ReadonlySet<SendClass> = new Set<SendClass>([
@@ -224,6 +226,7 @@ interface SharedSendLedger {
    * it in -- it has to ask whoever holds the request's grant.
    */
   claimAmbiguousResend(limit: number): boolean;
+  readonly ambiguousResendSpent: boolean;
   readonly observer?: RequestSendObserver;
 }
 
@@ -240,20 +243,23 @@ const sharedSendLedgers = new WeakMap<RequestExecutionBudget, SharedSendLedger>(
  * already spent the one replacement a strict row granted buy another as soon as a more
  * permissive row asked, which is a second duplicate inference of one turn.
  */
-function createAmbiguousResendGrant(): (limit: number) => boolean {
+function createAmbiguousResendGrant(): Pick<SharedSendLedger, "claimAmbiguousResend" | "ambiguousResendSpent"> {
   let claimed = 0;
   let ceiling: number | undefined;
-  return (limit: number): boolean => {
-    const presented = Number.isFinite(limit) ? Math.trunc(limit) : 0;
-    // A zero or nonsense ceiling refuses on its own and leaves the request's alone. It is a
-    // caller that cannot state a grant, not an operator narrowing this request: a leg with no
-    // policy is refused before it ever claims, so binding the request to a malformed number
-    // would only let such a caller cancel a grant an opted-in row really made.
-    if (presented <= 0) return false;
-    ceiling = ceiling === undefined ? presented : Math.min(ceiling, presented);
-    if (claimed >= ceiling) return false;
-    claimed += 1;
-    return true;
+  return {
+    get ambiguousResendSpent(): boolean { return claimed > 0; },
+    claimAmbiguousResend(limit: number): boolean {
+      const presented = Number.isFinite(limit) ? Math.trunc(limit) : 0;
+      // A zero or nonsense ceiling refuses on its own and leaves the request's alone. It is a
+      // caller that cannot state a grant, not an operator narrowing this request: a leg with no
+      // policy is refused before it ever claims, so binding the request to a malformed number
+      // would only let such a caller cancel a grant an opted-in row really made.
+      if (presented <= 0) return false;
+      ceiling = ceiling === undefined ? presented : Math.min(ceiling, presented);
+      if (claimed >= ceiling) return false;
+      claimed += 1;
+      return true;
+    },
   };
 }
 
@@ -302,6 +308,7 @@ function createRequestExecutionBudgetWithLedger(
     claimAmbiguousResend(limit: number): boolean {
       return counter.claimAmbiguousResend(limit);
     },
+    get ambiguousResendSpent(): boolean { return counter.ambiguousResendSpent; },
     reserveDispatch(intent: DispatchIntent): DispatchDecision {
       if (intent.replaySafe === false) return { allowed: false, reason: "not-replay-safe" };
       if (counter.spent >= policy.maxTotalModelSends) return { allowed: false, reason: "total-exhausted" };
@@ -396,10 +403,12 @@ export function createRequestExecutionBudget(
   logicalRequestId?: string,
   observer?: RequestSendObserver,
 ): RequestExecutionBudget {
+  const grant = createAmbiguousResendGrant();
   return createRequestExecutionBudgetWithLedger(policy, logicalRequestId, {
     spent: 0,
     pendingExternalSends: 0,
-    claimAmbiguousResend: createAmbiguousResendGrant(),
+    claimAmbiguousResend: grant.claimAmbiguousResend,
+    get ambiguousResendSpent(): boolean { return grant.ambiguousResendSpent; },
     ...(observer ? { observer } : {}),
   });
 }
@@ -430,10 +439,24 @@ export function deriveRequestExecutionBudget(
  * share pending external bookings and a durable-spend observer, which are private by
  * construction; a bridged scope keeps the parent's spend accurate and books nothing of its own.
  */
+/**
+ * Grant claims made THROUGH a bridge, keyed by the bridged parent so every scope derived from it
+ * sees them. A parent that predates `ambiguousResendSpent` can still grant through
+ * `claimAmbiguousResend`; reading only its missing flag would report "not spent" after a derived
+ * scope spent the grant, and a combo would then hop on a zero-output 200 from the replacement.
+ */
+const bridgedGrantClaims = new WeakMap<RequestExecutionBudget, { claimed: boolean }>();
+
 function ledgerFor(parent: RequestExecutionBudget): SharedSendLedger {
   const existing = sharedSendLedgers.get(parent);
   if (existing) return existing;
   let pendingExternalSends = 0;
+  let bridged = bridgedGrantClaims.get(parent);
+  if (!bridged) {
+    bridged = { claimed: false };
+    bridgedGrantClaims.set(parent, bridged);
+  }
+  const claims = bridged;
   return {
     get spent(): number { return parent.used; },
     set spent(next: number) { parent.used = next; },
@@ -446,7 +469,12 @@ function ledgerFor(parent: RequestExecutionBudget): SharedSendLedger {
     // but the grant can -- `claimAmbiguousResend` is public on the parent. A parent that does
     // not implement it grants nothing, which is the fail-closed answer for a send whose
     // upstream state is unknown.
-    claimAmbiguousResend: (limit: number): boolean => parent.claimAmbiguousResend?.(limit) === true,
+    claimAmbiguousResend: (limit: number): boolean => {
+      const granted = parent.claimAmbiguousResend?.(limit) === true;
+      if (granted) claims.claimed = true;
+      return granted;
+    },
+    get ambiguousResendSpent(): boolean { return claims.claimed || parent.ambiguousResendSpent === true; },
   };
 }
 

package/src/lib/request-resend-gate.ts

@@ -5,9 +5,10 @@
  * asked it for a connection that died before any head; #4989 asked it for an SSE body that
  * died after the head while carrying only control events. Both are the same row of the stage
  * table: a stage the caller observed nothing at, with a cause that cannot prove the origin did
- * not run the turn. `resendPermission` answers `refused-ambiguous` for both, and
- * request-failure-model.ts already names the only thing that may override that answer -- a
- * narrowly scoped recovery a maintainer opted into and bounded.
+ * not run the turn. A Codex WebSocket that dies under its create frame before any Responses
+ * event (#4191) is that row a third time. `resendPermission` answers `refused-ambiguous` for all
+ * of them, and request-failure-model.ts already names the only thing that may override that
+ * answer -- a narrowly scoped recovery a maintainer opted into and bounded.
  *
  * One override, not two. The reason this module exists rather than a boolean in each caller is
  * that a request which resets before the head and again after it would otherwise buy a

package/src/lib/retry-delay.ts

@@ -19,6 +19,7 @@ const MAX_COMPONENTS = 16;
 
 function durationSeconds(tail: string, allowBareSeconds: boolean): number | undefined {
   let rest = tail.trimStart();
+  if (allowBareSeconds && rest.startsWith("~")) rest = rest.slice(1).trimStart();
   let seconds = 0;
   let components = 0;
   while (true) {
@@ -39,6 +40,10 @@ function durationSeconds(tail: string, allowBareSeconds: boolean): number | unde
     rest = rest.slice(component[0].length);
     const separator = SEPARATOR.exec(rest)![0];
     const next = rest.slice(separator.length);
+    // The approximation marker belongs to the whole hint, once, before the
+    // first component. A second one ("~1 minute ~30 seconds") is malformed and
+    // must reject the hint rather than shorten it to the first component.
+    if (next.startsWith("~")) return undefined;
     if (!/^[+-]?(?:\d|\.\d)/.test(next)) break;
     // A numeric continuation is part of this duration; a malformed second
     // component must reject the hint, not silently shorten it to the first.
@@ -50,7 +55,8 @@ function durationSeconds(tail: string, allowBareSeconds: boolean): number | unde
 
 /**
  * Supports reset(s) in, try again in and Retry-After/retry after hints; accepts
- * compound durations and rounds UP once after summing all components.
+ * compound durations, the generated Retry-After approximation marker, and
+ * rounds UP once after summing all components.
  * A bare number is permitted only for header-style Retry-After hints, never
  * for "reset in 2026". When a message declares several usable lower bounds,
  * honour the longest one rather than re-entering a still-live quota window.

package/src/lib/tool-envelope-echo-filter.ts

@@ -0,0 +1,236 @@
+/** Line-aware filter for echoed tool envelopes in incremental assistant text. */
+const MARKERS = ["[Tool Result]", "[Tool Error]", "[tool_result]", "[Tool Call]", "[Tool call:"] as const;
+const UNTERMINATED_MARKERS = ["[Tool Result", "[Tool Error", "[tool_result", "[Tool Call"] as const;
+/** Lines that are an echoed envelope marker on their own (after trimming trailing whitespace). */
+const WHOLE_LINE_MARKERS: readonly string[] = [...MARKERS, ...UNTERMINATED_MARKERS];
+/**
+ * The coding-agent call line "[Tool call: name (call_id: ...) with args: ...]" can wrap across lines
+ * when its arguments do, so it is recognised by its prefix, as before; prose rarely opens that way.
+ */
+const TOOL_CALL_LINE = "[Tool call:";
+const MAX_INDENT = 128;
+// Markdown fenced code (CommonMark): an opener is a run of at least three backticks or tildes
+// indented at most three spaces; only a run of the same character, at least as long and followed
+// by nothing but whitespace, closes it. A backtick opener's info string may not contain a backtick.
+const MAX_FENCE_INDENT = 3;
+const MAX_FENCE_LINE = 1024;
+const FENCE_LINE = /^(\x60{3,}|~{3,})(.*)$/s;
+const FENCE_PREFIX = /^(\x60{1,2}|~{1,2})$/;
+const FENCE_RUN = /^(\x60{3,}|~{3,})/;
+
+/**
+ * The envelope OpenCodex replays is a marker alone on its line ("[Tool Result]\n<payload>"). Only a
+ * line that is exactly such a marker is an echo; prose that merely starts with one ("[Tool Result]
+ * shows the build passed.") is an answer. The call line keeps its prefix rule (TOOL_CALL_LINE).
+ */
+export function isWholeLineEchoMarker(line: string): boolean {
+  const trimmed = line.replace(/^[ \t]*/, "").trimEnd();
+  return WHOLE_LINE_MARKERS.includes(trimmed) || trimmed.startsWith(TOOL_CALL_LINE);
+}
+
+interface FenceLine {
+  char: string;
+  length: number;
+  rest: string;
+}
+
+/** A complete line (no newline) parsed as a CommonMark fence line, or null. */
+function parseFenceLine(line: string): FenceLine | null {
+  const probe = line.replace(/^[ \t]*/, "");
+  if (line.length - probe.length > MAX_FENCE_INDENT) return null;
+  const match = FENCE_LINE.exec(probe.replace(/\r?\n?$/, ""));
+  if (!match) return null;
+  return { char: match[1]![0]!, length: match[1]!.length, rest: match[2] ?? "" };
+}
+
+function opensFence(line: FenceLine): boolean {
+  return !(line.char === "\x60" && line.rest.includes("\x60"));
+}
+
+function closesFence(line: FenceLine, open: { char: string; length: number }): boolean {
+  return line.char === open.char && line.length >= open.length && line.rest.trim() === "";
+}
+
+/**
+ * For complete text (assistant history): true for each line that is a fence line of, or sits
+ * inside, a fenced block that is closed later in the same text. A block that never closes shields
+ * nothing, matching the live filter, which drops a held tail when the turn ends inside a fence.
+ */
+export function closedFenceLines(lines: readonly string[]): boolean[] {
+  const shielded = lines.map(() => false);
+  let open: { char: string; length: number; start: number } | null = null;
+  lines.forEach((text, index) => {
+    const fence = parseFenceLine(text);
+    if (!open) {
+      if (fence && opensFence(fence)) open = { char: fence.char, length: fence.length, start: index };
+      return;
+    }
+    if (fence && closesFence(fence, open)) {
+      for (let line = open.start; line <= index; line++) shielded[line] = true;
+      open = null;
+    }
+  });
+  return shielded;
+}
+
+// A marker line inside a fence may be a quoted example or an echo pasted into a block that never
+// closes. Output from that line is held: a matching closer releases it as code, the end of the turn
+// drops it as an echo. The hold is bounded, so a long block cannot stall the stream.
+const MAX_HELD_CHARS = 64 * 1024;
+
+interface Fence {
+  char: string;
+  length: number;
+  holdDisabled: boolean;
+  /** Its hold overflowed, so its marker is unverified until the block closes. */
+  overflowed?: boolean;
+}
+
+export class ToolEnvelopeEchoFilter {
+  private pending = "";
+  private safeLine = false;
+  private fence: Fence | null = null;
+  private held: string | null = null;
+  matched = false;
+  /** A fenced marker whose hold overflowed was released without proof that the block closes. */
+  unverifiedMarker = false;
+
+  feed(delta: string): string {
+    if (this.matched) return "";
+    let output = "";
+    for (const char of delta) {
+      if (this.matched) break;
+      if (this.safeLine) {
+        output += this.emit(char);
+        if (char === "\n") this.safeLine = false;
+        continue;
+      }
+      this.pending += char;
+      if (char === "\n") {
+        output += this.completeLine();
+        continue;
+      }
+      const probe = this.pending.replace(/^[ \t]*/, "");
+      const indent = this.pending.length - probe.length;
+      if (indent <= MAX_INDENT && probe === TOOL_CALL_LINE) {
+        if (!this.fence) {
+          this.pending = "";
+          this.matched = true;
+          break;
+        }
+        this.startHold();
+        this.flushLineStart();
+        output += this.emit(this.takePending());
+        continue;
+      }
+      // A marker is decided when its line completes (completeLine): until then a line that is a
+      // marker so far or a marker plus trailing whitespace stays pending. Anything else on the
+      // line makes it prose and releases it.
+      const fenceCandidate = indent <= MAX_FENCE_INDENT
+        && this.pending.length <= MAX_FENCE_LINE
+        && (FENCE_PREFIX.test(probe) || FENCE_RUN.test(probe));
+      const markerCandidate = indent <= MAX_INDENT
+        && (probe === ""
+          || MARKERS.some(marker => marker.startsWith(probe))
+          || WHOLE_LINE_MARKERS.includes(probe.trimEnd()));
+      if (fenceCandidate || markerCandidate) continue;
+      this.flushLineStart();
+      output += this.emit(this.takePending());
+    }
+    return output;
+  }
+
+  /**
+   * At normal end, a held fence tail, a last line that is a whole marker (or a bare unterminated
+   * marker such as "[Tool Result") or a "[Tool call:" line is an echo; other text, including a
+   * line that merely starts with a result or error marker, is prose.
+   */
+  finish(): string {
+    if (this.matched) return "";
+    // A closing fence may end the stream without a trailing newline; settle it before the hold.
+    const settled = this.pending !== "" && parseFenceLine(this.pending) ? this.completeLine() : "";
+    const pending = this.takePending();
+    if (this.held !== null) {
+      this.held = null;
+      this.matched = true;
+      return "";
+    }
+    const probe = pending.replace(/^[ \t]*/, "");
+    if (isWholeLineEchoMarker(probe)) {
+      this.matched = true;
+      return settled;
+    }
+    return settled + pending;
+  }
+
+  private completeLine(): string {
+    const raw = this.takePending();
+    const probe = raw.replace(/^[ \t]*/, "");
+    const indent = raw.length - probe.length;
+    const line = probe.replace(/\r?\n$/, "");
+    const fenceLine = parseFenceLine(raw);
+    if (fenceLine) {
+      if (!this.fence) {
+        if (opensFence(fenceLine)) {
+          this.fence = { char: fenceLine.char, length: fenceLine.length, holdDisabled: false };
+        }
+        return this.emit(raw);
+      }
+      if (closesFence(fenceLine, this.fence)) {
+        const out = this.emit(raw);
+        // Only one block is open at a time, so closing the overflowed one settles the doubt. This
+        // runs after the closer is emitted, because the closer itself can be what overflows the hold.
+        if (this.fence.overflowed) this.unverifiedMarker = false;
+        const released = this.held ?? "";
+        this.held = null;
+        this.fence = null;
+        return out + released;
+      }
+      return this.emit(raw);
+    }
+    const trimmed = line.trimEnd();
+    const markerLine = indent <= MAX_INDENT && isWholeLineEchoMarker(trimmed);
+    if (markerLine) {
+      if (!this.fence) {
+        this.matched = true;
+        return "";
+      }
+      this.startHold();
+    }
+    return this.emit(raw);
+  }
+
+  private startHold(): void {
+    if (this.fence && !this.fence.holdDisabled && this.held === null) this.held = "";
+  }
+
+  private flushLineStart(): void {
+    this.safeLine = true;
+  }
+
+  private takePending(): string {
+    const pending = this.pending;
+    this.pending = "";
+    return pending;
+  }
+
+  /** Route text to the client, or into the fence hold while one is open. */
+  private emit(text: string): string {
+    if (this.held === null) return text;
+    this.held += text;
+    if (this.held.length <= MAX_HELD_CHARS) return "";
+    const released = this.held;
+    this.held = null;
+    this.unverifiedMarker = true;
+    if (this.fence) {
+      this.fence.holdDisabled = true;
+      this.fence.overflowed = true;
+    }
+    return released;
+  }
+}
+
+export function stripToolEnvelopeEcho(text: string): string {
+  const filter = new ToolEnvelopeEchoFilter();
+  return filter.feed(text) + filter.finish();
+}