pi-better-subagents 0.4.2 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-subagents",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "description": "Pi extension for detached, sandboxed subagent runs that keep the foreground session free.",
   "license": "MIT",
   "type": "module",
@@ -36,9 +36,9 @@
     "test": "node --import tsx --test tests/*.test.mjs",
     "test:cross-session": "node --import tsx --test --test-name-pattern \"callback session isolation\" tests/extension_health_lifecycle.test.mjs",
     "pretest:macos-sandbox": "node ../../scripts/sync-shared-sandbox-core.mjs",
-    "test:macos-sandbox": "bash tests/test_sandbox_applied.sh && bash tests/test_sandbox_deny_outside.sh && bash tests/test_sandbox_wrapper_argv.sh && node --import tsx --test tests/sandbox_profile.test.mjs",
+    "test:macos-sandbox": "bash tests/test_sandbox_applied.sh && bash tests/test_sandbox_deny_outside.sh && bash tests/test_sandbox_wrapper_argv.sh && node --import tsx --test tests/sandbox_profile.test.mjs tests/child_incidents.test.mjs",
     "pretest:linux-sandbox": "node ../../scripts/sync-shared-sandbox-core.mjs",
-    "test:linux-sandbox": "node --import tsx --test tests/linux_bubblewrap.integration.mjs",
+    "test:linux-sandbox": "node --import tsx --test tests/linux_bubblewrap.integration.mjs tests/child_incidents.test.mjs",
     "verify": "npm run typecheck && npm test"
   },
   "files": [

package/parse.ts

@@ -97,13 +97,20 @@ export function tailLog(id: string, n: number, maxBytes = maxRawTailBytes()): st
     return out === "" ? "(no output yet)" : out;
 }
 
-/** Join the text blocks of a message into a plain string. */
+/**
+ * Join the text blocks of a message verbatim. Leading indentation and trailing
+ * newlines are part of the answer (Markdown, code); whitespace-only text is
+ * treated as no text.
+ */
 function messageText(msg: Msg | undefined): string {
     if (!msg) return "";
     const c = msg.content;
-    if (typeof c === "string") return c;
-    if (!Array.isArray(c)) return "";
-    return c.filter((b) => b?.type === "text" && typeof b.text === "string").map((b) => b.text).join("").trim();
+    const joined = typeof c === "string"
+        ? c
+        : Array.isArray(c)
+            ? c.filter((b) => b?.type === "text" && typeof b.text === "string").map((b) => b.text).join("")
+            : "";
+    return joined.trim() ? joined : "";
 }
 
 export interface UnmatchedToolCall {
@@ -1359,7 +1366,9 @@ export function formatSubagentOutputBody(
             : `(no parsed output yet)\n\n--- raw log tail ---\n${rawTail}`;
     }
     const diag = diagnostics.length ? `\n[parser: ${diagnostics.join("; ")}]` : "";
-    return `${head}${tools}${diag}\n${body}`;
+    // Ordinary ordered tool histories are omitted from default output (#312).
+    void tools;
+    return `${head}${diag}\n${body}`;
 }
 
 /** Build the human-readable body for subagent_result. Exported for unit testing. */

package/registry.ts

@@ -879,6 +879,89 @@ export function listMetas(): RunMeta[] {
         .sort((a, b) => b.startedAt - a.startedAt);
 }
 
+export interface RunRecordIndex {
+    metas: RunMeta[];
+    /** Run directories whose metadata is missing, unreadable, or corrupt. */
+    unreadable: Array<{ id: string; detail: string }>;
+    /** The runs directory itself could not be read (not "no runs"). */
+    indexError?: string;
+}
+
+/** Why parsed metadata is not a usable run record, or undefined when it is. */
+export function runMetaShapeProblem(meta: unknown, id: string): string | undefined {
+    if (!meta || typeof meta !== "object" || Array.isArray(meta)) return "not an object";
+    const value = meta as Partial<RunMeta>;
+    if (value.id !== id) return `id ${JSON.stringify(value.id ?? null)} does not match ${JSON.stringify(id)}`;
+    if (typeof value.status !== "string" || !value.status) return "missing status";
+    if (typeof value.startedAt !== "number" || !Number.isFinite(value.startedAt)) return "missing startedAt";
+    return undefined;
+}
+
+/**
+ * Inspect one run's metadata without collapsing "missing" and "corrupt":
+ * `missing` only when neither metadata nor the run directory exists.
+ */
+export function inspectRunMeta(id: string): { kind: "ok"; meta: RunMeta } | { kind: "missing" } | { kind: "unreadable"; detail: string } {
+    let raw: string;
+    try {
+        registryIo.metadataFileReads += 1;
+        raw = readFileSync(metaPathFor(id), "utf-8");
+    } catch (error) {
+        metaCache.delete(id);
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code === "ENOENT") {
+            try {
+                statSync(runDir(id));
+                return { kind: "unreadable", detail: "metadata file is missing; the run directory and its evidence are retained" };
+            } catch {
+                return { kind: "missing" };
+            }
+        }
+        return { kind: "unreadable", detail: error instanceof Error ? error.message : String(error) };
+    }
+    let meta: RunMeta;
+    try {
+        meta = JSON.parse(raw) as RunMeta;
+    } catch (error) {
+        metaCache.delete(id);
+        return { kind: "unreadable", detail: `invalid JSON: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    const invalid = runMetaShapeProblem(meta, id);
+    if (invalid) {
+        metaCache.delete(id);
+        return { kind: "unreadable", detail: `invalid metadata: ${invalid}` };
+    }
+    metaCache.set(id, meta);
+    return { kind: "ok", meta };
+}
+
+/** Every run directory, counting unreadable records instead of dropping them. */
+export function listRunRecords(): RunRecordIndex {
+    let ids: string[];
+    try {
+        registryIo.fullDirectoryReads += 1;
+        ids = readdirSync(join(baseDir(), "runs"));
+    } catch (error) {
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code === "ENOENT") return { metas: [], unreadable: [] };
+        return { metas: [], unreadable: [], indexError: error instanceof Error ? error.message : String(error) };
+    }
+    const metas: RunMeta[] = [];
+    const unreadable: Array<{ id: string; detail: string }> = [];
+    for (const id of ids) {
+        const cached = metaCache.get(id);
+        if (cached && cached.status !== "running" && cached.status !== "orphaned") {
+            metas.push(cached);
+            continue;
+        }
+        const inspected = inspectRunMeta(id);
+        if (inspected.kind === "ok") metas.push(inspected.meta);
+        else if (inspected.kind === "unreadable") unreadable.push({ id, detail: inspected.detail });
+    }
+    metas.sort((a, b) => b.startedAt - a.startedAt);
+    return { metas, unreadable };
+}
+
 export function listMetasForParent(parentPid: number): RunMeta[] {
     const directory = join(baseDir(), "by-parent", String(parentPid));
     ensureIndex(directory, (meta) => meta.spawnPid === parentPid);
@@ -1015,18 +1098,18 @@ function ensureActiveParentIndex(directory: string, parentPid: number): void {
     initializedIndexes.add(directory);
 }
 
-function originOf(meta: RunMeta): RunCallbackOrigin {
+export function originOf(meta: RunMeta): RunCallbackOrigin {
     return meta.callbackOrigin ?? { cwd: meta.cwd };
 }
 
-function belongsToOrigin(meta: RunMeta, origin: RunCallbackOrigin): boolean {
+export function belongsToOrigin(meta: RunMeta, origin: RunCallbackOrigin): boolean {
     const candidate = originOf(meta);
     if (candidate.cwd !== origin.cwd) return false;
     if (candidate.sessionId || origin.sessionId) return candidate.sessionId === origin.sessionId;
     return true;
 }
 
-function originKey(origin: RunCallbackOrigin): string {
+export function originKey(origin: RunCallbackOrigin): string {
     return createHash("sha256")
         .update(origin.cwd)
         .update("\0")

package/shared-callback-batcher.ts

@@ -16,6 +16,24 @@ export interface CallbackBatchEvent {
   status: string;
   detailTool: CallbackDetailTool;
   callback?: boolean;
+  /** Lifecycle/work outcome; independent of semantic task correctness. */
+  outcome?: string;
+  /**
+   * Legacy single-string failure summary already reduced by the observation
+   * owner. Prefer `failureRows` so shown/omitted incidents are counted exactly.
+   */
+  failure?: string;
+  /** One row per active incident, priority order (failure-observations formatFailureLines). */
+  failureRows?: string[];
+  /** Matched-condition, stop-error, or observation-gap facts. */
+  decision?: string;
+  /** Active incidents for this row. Defaults to `failureRows.length`. */
+  incidentCount?: number;
+  /**
+   * Legacy: incidents the caller already knows are not in `failure`. Ignored
+   * when `failureRows` is given, because the batch then counts rows it shows.
+   */
+  omittedIncidents?: number;
   isDelivered?: () => boolean;
   getSuppressionReason?: () => string | undefined;
   onDelivered?: (at: number) => void;
@@ -24,11 +42,21 @@ export interface CallbackBatchEvent {
 
 export interface UrgentCallbackEvent {
   source: CallbackSource;
+  /** Notification identity (dedupe/receipts). */
   id: string;
+  /** Retrieval identity for the inspect tool when it differs from `id`. */
+  inspectId?: string;
   label: string;
   status: "orphaned" | "lost" | string;
   customType: string;
+  /** Explanation text (health transition, attention reason). */
   content: string;
+  detailTool?: CallbackDetailTool;
+  /** One row per active incident, priority order. */
+  failureRows?: string[];
+  incidentCount?: number;
+  /** Legacy: ignored when `failureRows` is given. */
+  omittedIncidents?: number;
   isDelivered?: () => boolean;
   getSuppressionReason?: () => string | undefined;
   onDelivered?: (at: number) => void;
@@ -38,6 +66,8 @@ export interface UrgentCallbackEvent {
 export interface CallbackBatcherOptions {
   windowMs?: number;
   retryMs?: number;
+  /** UTF-8 byte cap for one sendMessage payload. Defaults to 2 KiB. */
+  maxBytes?: number;
 }
 
 export interface CallbackBatcher {
@@ -48,6 +78,16 @@ export interface CallbackBatcher {
   pendingCount(): number;
 }
 
+export interface CallbackBatchFormatOptions {
+  maxBytes?: number;
+}
+
+export interface FormattedCallbackBatch {
+  text: string;
+  represented: CallbackBatchEvent[];
+  omitted: number;
+}
+
 interface PendingEvent {
   event: CallbackBatchEvent;
   sequence: number;
@@ -60,9 +100,21 @@ interface SharedCallbackBatcherState {
 const GLOBAL_STATE_KEY = Symbol.for("@1aboveio/pi-better-harness/callback-batcher");
 const DEFAULT_WINDOW_MS = 100;
 const DEFAULT_RETRY_MS = 1_000;
-const MAX_LABEL_CHARS = 160;
-const MAX_ID_CHARS = 200;
-const MAX_STATUS_CHARS = 80;
+const MAX_LABEL_BYTES = 160;
+const MAX_ID_BYTES = 200;
+const MAX_STATUS_BYTES = 80;
+const MAX_FAILURE_BYTES = 400;
+const MAX_DECISION_BYTES = 400;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder("utf-8");
+
+/** OUTPUT-POLICY default: UTF-8 bytes of one model-facing callback batch. */
+export const CALLBACK_BATCH_BUDGET_BYTES = 2 * 1024;
+/** Documented hard cap. Explicit larger pages clamp here. */
+export const CALLBACK_BATCH_MAX_BYTES = 8 * 1024;
+
+const RETRIEVAL_FOOTER =
+  "Retrieve durable results/status with the listed tools using cursor/limit. Full results and logs are intentionally omitted.";
 
 export const CALLBACK_BATCH_WINDOW_ENV = "PI_BETTER_CALLBACK_BATCH_MS";
 export const DEFAULT_CALLBACK_BATCH_WINDOW_MS = DEFAULT_WINDOW_MS;
@@ -76,24 +128,266 @@ export function resolveCallbackBatchWindowMs(
   return Math.max(0, Math.min(5_000, Math.floor(parsed)));
 }
 
-export function formatCallbackBatch(events: readonly CallbackBatchEvent[]): string {
-  const count = events.length;
+export function utf8ByteLength(text: string): number {
+  return encoder.encode(text).byteLength;
+}
+
+export function callbackBatchBudget(requested?: unknown): number {
+  const parsed = typeof requested === "number" ? requested
+    : typeof requested === "string" && requested.trim() !== "" ? Number(requested)
+    : Number.NaN;
+  if (!Number.isFinite(parsed) || parsed <= 0) return CALLBACK_BATCH_BUDGET_BYTES;
+  return Math.min(Math.max(1, Math.floor(parsed)), CALLBACK_BATCH_MAX_BYTES);
+}
+
+function completeUtf8End(bytes: Uint8Array, to: number): number {
+  if (to <= 0) return 0;
+  if (to >= bytes.length) return bytes.length;
+  let seqStart = to - 1;
+  while (seqStart > 0 && (bytes[seqStart]! & 0xc0) === 0x80) seqStart -= 1;
+  if ((bytes[seqStart]! & 0xc0) === 0x80) return to;
+  const lead = bytes[seqStart]!;
+  const needed = lead <= 0x7f ? 1
+    : (lead & 0xe0) === 0xc0 ? 2
+    : (lead & 0xf0) === 0xe0 ? 3
+    : (lead & 0xf8) === 0xf0 ? 4
+    : 1;
+  return seqStart + needed > to ? seqStart : to;
+}
+
+function clipUtf8Prefix(text: string, maxBytes: number): string {
+  if (maxBytes <= 0) return "";
+  const bytes = encoder.encode(text);
+  if (bytes.byteLength <= maxBytes) return text;
+  return decoder.decode(bytes.subarray(0, completeUtf8End(bytes, Math.min(maxBytes, bytes.byteLength))));
+}
+
+function boundedField(value: unknown, maxBytes: number): string {
+  const oneLine = String(value ?? "").replace(/\s+/g, " ").trim();
+  if (utf8ByteLength(oneLine) <= maxBytes) return oneLine;
+  const ellipsis = "...";
+  return `${clipUtf8Prefix(oneLine, Math.max(0, maxBytes - utf8ByteLength(ellipsis)))}${ellipsis}`;
+}
+
+function inspectFor(event: Pick<CallbackBatchEvent, "id" | "detailTool">): string {
+  const id = boundedField(event.id, MAX_ID_BYTES);
+  return event.detailTool === "bg_task_status"
+    ? `bg_task_status id=${id}`
+    : `subagent_result id=${JSON.stringify(id)}`;
+}
+
+interface IncidentLines {
+  lines: string[];
+  shown: number;
+  total: number;
+}
+
+/**
+ * Whole incident rows that fit `maxBytes`, one per line. A first row that does
+ * not fit is shown as a clipped prefix and is NOT counted as shown.
+ */
+function incidentLines(rows: readonly string[], total: number, maxBytes: number, indent: string): IncidentLines {
+  const lines: string[] = [];
+  let used = 0;
+  let shown = 0;
+  for (const row of rows) {
+    const line = `${indent}${String(row).replace(/\s+/g, " ").trim()}`;
+    const size = utf8ByteLength(line) + 1;
+    if (used + size <= maxBytes) {
+      lines.push(line);
+      used += size;
+      shown += 1;
+      continue;
+    }
+    if (lines.length === 0 && maxBytes - indent.length > 48) {
+      lines.push(`${indent}${boundedField(row, maxBytes - utf8ByteLength(indent) - 1)} (clipped)`);
+    }
+    break;
+  }
+  return { lines, shown, total: Math.max(total, rows.length) };
+}
+
+function countsLine(incidents: IncidentLines, inspect: string): string | undefined {
+  if (incidents.total <= 0) return undefined;
+  const omitted = Math.max(0, incidents.total - incidents.shown);
+  return `  incidents=${incidents.total} shown=${incidents.shown}` +
+    (omitted > 0 ? ` omittedIncidents=${omitted} retrieve: ${inspect} (incident pages via cursor)` : "");
+}
+
+function eventIncidents(event: CallbackBatchEvent, failureBytes: number): IncidentLines {
+  if (event.failureRows && event.failureRows.length) {
+    return incidentLines(event.failureRows, event.incidentCount ?? event.failureRows.length, failureBytes, "  failure: ");
+  }
+  if (event.failure) {
+    const total = event.incidentCount ?? 1;
+    const whole = incidentLines([event.failure], 1, failureBytes, "  failure: ");
+    const legacyShown = whole.shown ? Math.max(0, total - (event.omittedIncidents ?? 0)) : 0;
+    return { lines: whole.lines, shown: legacyShown, total };
+  }
+  const total = event.incidentCount ?? 0;
+  return { lines: [], shown: 0, total };
+}
+
+function formatRow(event: CallbackBatchEvent, detailBytes = MAX_FAILURE_BYTES + MAX_DECISION_BYTES): string {
+  const source = boundedField(event.source, 40);
+  const id = boundedField(event.id, MAX_ID_BYTES);
+  const label = boundedField(event.label, MAX_LABEL_BYTES);
+  const status = boundedField(event.status, MAX_STATUS_BYTES);
+  const inspect = inspectFor(event);
+  const lines = [
+    `- source=${source} | id=${id} | label=${JSON.stringify(label)} | status=${status} | inspect: ${inspect}`,
+  ];
+  if (event.outcome) {
+    const outcome = boundedField(event.outcome, 80);
+    if (outcome && outcome !== status) lines.push(`  outcome=${outcome}`);
+  }
+  const decisionBytes = Math.min(MAX_DECISION_BYTES, Math.floor(detailBytes / 2));
+  if (event.decision && decisionBytes > 24) lines.push(`  decision: ${boundedField(event.decision, decisionBytes)}`);
+  const incidents = eventIncidents(event, Math.max(0, Math.min(MAX_FAILURE_BYTES * 2, detailBytes - decisionBytes)));
+  lines.push(...incidents.lines);
+  const counts = countsLine(incidents, inspect);
+  if (counts) lines.push(counts);
+  return lines.join("\n");
+}
+
+function renderBatch(represented: readonly CallbackBatchEvent[], omitted: number, detailBytes?: number): string {
+  const count = represented.length;
   const heading = `${count} background completion${count === 1 ? " is" : "s are"} ready:`;
-  const rows = events.map((event) => {
-    const source = boundedField(event.source, 40);
-    const id = boundedField(event.id, MAX_ID_CHARS);
-    const label = boundedField(event.label, MAX_LABEL_CHARS);
-    const status = boundedField(event.status, MAX_STATUS_CHARS);
-    const detail = event.detailTool === "bg_task_status"
-      ? `bg_task_status id=${id}`
-      : `subagent_result id=${JSON.stringify(id)}`;
-    return `- source=${source} | id=${id} | label=${JSON.stringify(label)} | status=${status} | inspect: ${detail}`;
-  });
-  return [
-    heading,
-    ...rows,
-    "Retrieve durable results/status with the listed tools. Full results and logs are intentionally omitted.",
-  ].join("\n");
+  const omittedLine = omitted > 0
+    ? `${omitted} more completion${omitted === 1 ? "" : "s"} omitted from this batch (not receipted; still queued).`
+    : undefined;
+  return [heading, ...represented.map((event) => formatRow(event, detailBytes)), omittedLine, RETRIEVAL_FOOTER]
+    .filter((line): line is string => Boolean(line))
+    .join("\n");
+}
+
+function clipRendered(text: string, maxBytes: number): string {
+  if (utf8ByteLength(text) <= maxBytes) return text;
+  const suffix = "\n[clipped to callback budget]";
+  const budget = maxBytes - utf8ByteLength(suffix);
+  if (budget < 24) return clipUtf8Prefix(text, maxBytes);
+  return `${clipUtf8Prefix(text, budget)}${suffix}`;
+}
+
+function eventPriority(event: CallbackBatchEvent): number {
+  if (event.failure || event.failureRows?.length || (event.omittedIncidents ?? 0) > 0 || (event.incidentCount ?? 0) > 0) return 0;
+  if (event.decision) return 1;
+  const status = String(event.status ?? "").toLowerCase();
+  if (/(?:fail|orphan|lost|timed_out|timeout|unresolved|incomplete|observation incomplete)/.test(status)) return 0;
+  return 2;
+}
+
+/**
+ * Urgent health/failure callback under the total budget. Order: header,
+ * explanation, whole incident rows that fit, the incident count line (total,
+ * shown, omitted, retrieval), and the inspect line. The count and inspect
+ * lines are never dropped; unshown explanation bytes are counted.
+ */
+export function formatUrgentCallback(
+  event: UrgentCallbackEvent,
+  options: CallbackBatchFormatOptions = {},
+): string {
+  const maxBytes = callbackBatchBudget(options.maxBytes);
+  const target = event.inspectId ?? event.id;
+  const id = boundedField(target, MAX_ID_BYTES);
+  const label = boundedField(event.label, MAX_LABEL_BYTES);
+  const status = boundedField(event.status, MAX_STATUS_BYTES);
+  const tool = event.detailTool
+    ?? (event.source === "background-task" ? "bg_task_status" : "subagent_result");
+  const inspectTarget = tool === "bg_task_status" ? `bg_task_status id=${id}` : `subagent_result id=${JSON.stringify(id)}`;
+  const inspect = `Inspect: ${inspectTarget}`;
+  const header = `${boundedField(event.source, 40)} id=${id} label=${JSON.stringify(label)} status=${status}`;
+  const source = String(event.content ?? "").trim();
+  const rows = event.failureRows ?? [];
+  const total = rows.length ? Math.max(rows.length, event.incidentCount ?? 0) : event.incidentCount ?? 0;
+  const legacyOmitted = rows.length ? 0 : event.omittedIncidents ?? 0;
+  const counts = (shown: number): string | undefined => {
+    if (total <= 0) return undefined;
+    const omitted = rows.length ? total - shown : legacyOmitted;
+    const shownPart = rows.length ? ` shown=${shown}` : "";
+    return `incidents=${total}${shownPart}` +
+      (omitted > 0 ? ` omittedIncidents=${omitted} retrieve: ${inspectTarget} (incident pages via cursor)` : "");
+  };
+  const render = (body: string, note: string | undefined, shownRows: string[]): string =>
+    [header, body, note, ...shownRows, counts(shownRows.length), inspect]
+      .filter((part): part is string => Boolean(part && part.length > 0))
+      .join("\n");
+  const fixed = utf8ByteLength(render("", undefined, [])) + 16;
+  const room = Math.max(0, maxBytes - fixed);
+  // The explanation keeps at least half the room when incident rows compete.
+  const contentShare = rows.length ? Math.floor(room / 2) : room;
+  let body = source;
+  let note: string | undefined;
+  if (utf8ByteLength(source) > contentShare) {
+    const noteFor = (omitted: number) => `omittedBytes=${omitted} retrieve: ${inspectTarget}`;
+    const clipped = clipUtf8Prefix(source, Math.max(0, contentShare - utf8ByteLength(noteFor(utf8ByteLength(source))) - 1));
+    body = clipped;
+    note = noteFor(utf8ByteLength(source) - utf8ByteLength(clipped));
+  }
+  const shown: string[] = [];
+  for (const row of rows) {
+    const line = String(row).replace(/\s+/g, " ").trim();
+    if (utf8ByteLength(render(body, note, [...shown, line])) + 8 > maxBytes) break;
+    shown.push(line);
+  }
+  const rendered = render(body, note, shown);
+  if (utf8ByteLength(rendered) <= maxBytes) return rendered;
+  const minimal = render("", source ? `omittedBytes=${utf8ByteLength(source)} retrieve: ${inspectTarget}` : undefined, []);
+  return clipRendered(minimal, maxBytes);
+}
+
+export function packCallbackBatch(
+  events: readonly CallbackBatchEvent[],
+  options: CallbackBatchFormatOptions = {},
+): FormattedCallbackBatch {
+  const maxBytes = callbackBatchBudget(options.maxBytes);
+  if (events.length === 0) {
+    return { text: renderBatch([], 0), represented: [], omitted: 0 };
+  }
+
+  const ranked = events.map((event, index) => ({ event, index }))
+    .sort((a, b) => eventPriority(a.event) - eventPriority(b.event) || a.index - b.index);
+
+  const selected = new Set<number>();
+  const renderSelected = (): string => {
+    const represented = events.filter((_, index) => selected.has(index));
+    return renderBatch(represented, events.length - selected.size);
+  };
+
+  for (const { index } of ranked) {
+    selected.add(index);
+    if (utf8ByteLength(renderSelected()) <= maxBytes) continue;
+    selected.delete(index);
+    if (selected.size === 0) {
+      // One row alone exceeds the budget: shrink its detail, never its counts.
+      const event = events[index]!;
+      for (const detail of [MAX_FAILURE_BYTES, 200, 0]) {
+        const text = renderBatch([event], events.length - 1, detail);
+        if (utf8ByteLength(text) <= maxBytes) {
+          return { text, represented: [event], omitted: events.length - 1 };
+        }
+      }
+      return {
+        text: clipRendered(renderBatch([event], events.length - 1, 0), maxBytes),
+        represented: [event],
+        omitted: events.length - 1,
+      };
+    }
+  }
+
+  const represented = events.filter((_, index) => selected.has(index));
+  return {
+    text: renderSelected(),
+    represented,
+    omitted: events.length - represented.length,
+  };
+}
+
+export function formatCallbackBatch(
+  events: readonly CallbackBatchEvent[],
+  options: CallbackBatchFormatOptions = {},
+): string {
+  return packCallbackBatch(events, options).text;
 }
 
 export function createCallbackBatcher(
@@ -102,6 +396,7 @@ export function createCallbackBatcher(
 ): CallbackBatcher {
   const windowMs = options.windowMs ?? resolveCallbackBatchWindowMs();
   const retryMs = Math.max(0, options.retryMs ?? DEFAULT_RETRY_MS);
+  const maxBytes = callbackBatchBudget(options.maxBytes);
   const pending = new Map<string, PendingEvent>();
   const inFlight = new Set<string>();
   const urgentInFlight = new Set<string>();
@@ -177,11 +472,16 @@ export function createCallbackBatcher(
       return !deferred;
     }
 
+    const packed = packCallbackBatch(deliverable.map(([, item]) => item.event), { maxBytes });
+    const representedSet = new Set(packed.represented);
+    const representedItems = deliverable.filter(([, item]) => representedSet.has(item.event));
+    const overflowItems = deliverable.filter(([, item]) => !representedSet.has(item.event));
+
     try {
       await host.sendMessage(
         {
           customType: "background-completion-batch",
-          content: formatCallbackBatch(deliverable.map(([, item]) => item.event)),
+          content: packed.text,
           display: true,
         },
         { deliverAs: "followUp", triggerTurn: true },
@@ -199,7 +499,7 @@ export function createCallbackBatcher(
     }
 
     const deliveredAt = Date.now();
-    for (const [key, item] of deliverable) {
+    for (const [key, item] of representedItems) {
       handedOff.set(key, deliveredAt);
       if (!invokeDelivered(item.event, deliveredAt)) {
         deferred = true;
@@ -207,6 +507,10 @@ export function createCallbackBatcher(
       }
       inFlight.delete(key);
     }
+    for (const [key, item] of overflowItems) {
+      pending.set(key, item);
+      inFlight.delete(key);
+    }
     if (pending.size > 0) schedule(deferred ? retryMs : windowMs);
     return !deferred;
   };
@@ -240,7 +544,7 @@ export function createCallbackBatcher(
     urgentInFlight.add(key);
     try {
       const handoff = host.sendMessage(
-        { customType: event.customType, content: event.content, display: true },
+        { customType: event.customType, content: formatUrgentCallback(event, { maxBytes }), display: true },
         { deliverAs: "followUp", triggerTurn: true },
       );
       if (isPromiseLike(handoff)) {
@@ -333,12 +637,6 @@ function invokeSuppressed(
   try { event.onSuppressed?.(reason, at); } catch { /* best effort durable suppression */ }
 }
 
-function boundedField(value: unknown, maxChars: number): string {
-  const oneLine = String(value ?? "").replace(/\s+/g, " ").trim();
-  if (oneLine.length <= maxChars) return oneLine;
-  return `${oneLine.slice(0, Math.max(0, maxChars - 3))}...`;
-}
-
 function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
   return (typeof value === "object" || typeof value === "function")
     && value !== null