@cat-factory/executor-harness 1.96.0 → 1.100.0

package/src/agent-runner.ts

@@ -9,17 +9,18 @@ import {
   type TrackedToolCall,
   recordClaudeToolResults,
 } from './tool-trajectory.js'
-import type { Logger } from './logger.js'
+import { log, type Logger } from './logger.js'
+import { NO_TOOL_WINDOW, type ToolProgressWindow } from './tool-silence.js'
 import {
   createCallMetricPublisher,
   publishCallMetric,
   type CallMetricPublisher,
   type HarnessCallMetric,
   type PiRunOutcome,
-  type PiRunStats,
   type TodoProgress,
   type ToolSpan,
 } from './pi.js'
+import type { PiRunStats } from './pi-reduction.js'
 import {
   claudeAllowedToolPatterns,
   codexMcpConfigToml,
@@ -31,6 +32,7 @@ import {
   type SkillSpec,
 } from './agent-capabilities.js'
 import { ProgressGuard, type ProgressGuardLimits } from './progress-guard.js'
+import { BoundedTail, JsonlLineReader } from './jsonl-stream.js'
 import { killChildProcess, spawnDetached } from './process.js'
 import { describeProcessExit } from './process-exit.js'
 import { redact, registerKnownSecrets, secretsToRedact } from './redact.js'
@@ -138,6 +140,18 @@ export interface SubscriptionRunOptions {
    * DID dies with the container.
    */
   onSpan?: (span: ToolSpan) => void
+  /**
+   * Opens this stream's tool-silence window (see `RunOptions.beginToolWindow`), closed when the
+   * CLI exits. Both subscription CLIs report tool activity — claude-code on the `tool_result`
+   * turn that answers each call, codex on its tool/command/exec events — so a window either
+   * opens is one the run can beat. It is deliberately NOT tied to {@link onSpan}: the trajectory
+   * is an observability opt-in, and the codex stream produces none at all while still doing tool
+   * work, which a span-keyed window would have read as a run making no progress.
+   *
+   * A caller with no tool loop (the inline one-shot completion) passes nothing; see the note at
+   * `handleInline`.
+   */
+  beginToolWindow?: () => ToolProgressWindow
   /**
    * Called with the FULL set of per-slice reviews each time one lands, so the backend can persist
    * a parallel review's completed work as it happens instead of only from the terminal result.
@@ -227,9 +241,10 @@ function streamCli(
     child.stdin.on('error', () => {})
     child.stdin.end(prompt)
 
-    let stderr = ''
+    // 8 KB is well over the 700 B tail anyone quotes below, and the CLI's stderr is diagnostic
+    // noise rather than a product, so a bounded tail is all this ever needed to be.
+    const stderr = new BoundedTail(8_000)
     let aborted = false
-    let lineBuffer = ''
 
     const killChild = (): void => killChildProcess(child)
 
@@ -253,16 +268,9 @@ function streamCli(
       }
     }
 
-    const consumeStdout = (text: string): void => {
-      lineBuffer += text
-      let nl = lineBuffer.indexOf('\n')
-      while (nl !== -1) {
-        const line = lineBuffer.slice(0, nl).trim()
-        lineBuffer = lineBuffer.slice(nl + 1)
-        nl = lineBuffer.indexOf('\n')
-        processLine(line)
-      }
-    }
+    // Bounded framing, shared with `runPi`: an unterminated record must not be able to grow
+    // until parsing it stalls the loop the watchdogs and poll handlers run on (audit F6).
+    const reader = new JsonlLineReader(processLine)
 
     const onAbort = (): void => {
       aborted = true
@@ -272,12 +280,11 @@ function streamCli(
 
     child.stdout.on('data', (chunk: Buffer) => {
       opts.onActivity?.()
-      consumeStdout(chunk.toString())
+      reader.push(chunk.toString())
     })
     child.stderr.on('data', (chunk: Buffer) => {
       opts.onActivity?.()
-      stderr += chunk.toString()
-      if (stderr.length > 8_000) stderr = stderr.slice(-8_000)
+      stderr.push(chunk.toString())
     })
 
     child.on('error', (err) => {
@@ -286,8 +293,19 @@ function streamCli(
     })
     child.on('close', (code, signal) => {
       opts.signal?.removeEventListener('abort', onAbort)
-      const stderrTail = redact(stderr, secrets).slice(-700)
-      if (lineBuffer.trim()) processLine(lineBuffer.trim(), true)
+      const stderrTail = redact(stderr.toString(), secrets).slice(-700)
+      reader.flush()
+      // Surface an oversized record the reader refused to buffer ONCE (a count, not per line),
+      // for the same reason `runPi` does: a dropped record costs this run its progress, its
+      // trajectory and its per-call telemetry for that turn, and a silent loss reads exactly
+      // like a CLI that never emitted it. Falls back to the module logger so the report cannot
+      // depend on a caller having wired a per-job one.
+      if (reader.droppedLines > 0) {
+        ;(opts.log ?? log).warn('agent CLI: skipped oversized JSONL records', {
+          command,
+          oversizedLines: reader.droppedLines,
+        })
+      }
       if (aborted) {
         // Carry the tail on the rejection so a caller that REPLACES this generic message with a
         // more specific cause (the no-progress guard's diagnostic) can still append it — the
@@ -659,6 +677,25 @@ function createClaudeToolTrajectory(
   }
 }
 
+/**
+ * Open this run's tool-silence window, or the inert one when the caller wired no watchdog. One
+ * definition so both runners resolve "is there a watchdog?" identically, and so neither carries
+ * the optional-call noise at the point where it should simply have a window.
+ */
+function openToolWindow(opts: SubscriptionRunOptions): ToolProgressWindow {
+  return opts.beginToolWindow ? opts.beginToolWindow() : NO_TOOL_WINDOW
+}
+
+/**
+ * Whether a claude-code `user` turn carries a `tool_result` block, i.e. whether a tool call just
+ * COMPLETED — the progress the tool-silence watchdog measures. Tested explicitly rather than
+ * taken from "the model sent a user turn", which a plain follow-up prompt also is: a watchdog
+ * reset handed out for work that did nothing is the same as no watchdog.
+ */
+function carriesToolResult(content: unknown[]): boolean {
+  return content.some((block) => isObject(block) && block.type === 'tool_result')
+}
+
 export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRunOutcome> {
   const stats: PiRunStats = { toolCalls: 0, assistantChars: 0 }
   let summary = ''
@@ -739,6 +776,9 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
   const progressGuard = createClaudeProgressGuard(opts)
   const { rememberTool, feedGuard, guardAbort } = progressGuard
   const trajectory = createClaudeToolTrajectory(opts, secrets)
+  // This stream's tool-silence window; opened just before the CLI starts and closed in the
+  // `finally` below, so it can only ever be armed while the CLI it watches is running.
+  let toolWindow: ToolProgressWindow = NO_TOOL_WINDOW
 
   const onEvent = (event: Record<string, unknown>, meta?: { final?: boolean }): void => {
     const type = event.type
@@ -776,6 +816,7 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
       // tool_result blocks the harness fed back to the model — part of the next prompt.
       const content = (event.message as Record<string, unknown>).content
       if (Array.isArray(content)) {
+        if (carriesToolResult(content)) toolWindow.toolCompleted()
         sliceTracker.onUser(content)
         planTracker.onUser(content)
         emitProgress()
@@ -824,6 +865,9 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     ? AbortSignal.any([opts.signal, guardAbort.signal])
     : guardAbort.signal
 
+  // Opened around the CLI itself, not around this function: everything above is per-run setup
+  // (the config home, the skills, the MCP config) which completes no tool calls by nature.
+  toolWindow = openToolWindow(opts)
   try {
     const { stderrTail } = await streamCli(
       {
@@ -895,6 +939,7 @@ export async function runClaudeCode(opts: SubscriptionRunOptions): Promise<PiRun
     }
     throw withAgentReport(err, terminalReport, secrets)
   } finally {
+    toolWindow.close()
     await subagents?.stop()
     await home.dispose()
   }
@@ -1097,6 +1142,30 @@ function claudeUsage(raw: unknown): { inputTokens: number; outputTokens: number
 // Codex
 // ---------------------------------------------------------------------------
 
+/**
+ * The assistant text a codex event carries, or `''`. Two shapes because the CLI changed its
+ * stream between versions and the harness serves both: the flat `agent_message*` events and the
+ * newer `item.completed` envelope around a message item.
+ */
+function codexAssistantText(event: Record<string, unknown>, type: string): string {
+  const isMessage =
+    type.includes('agent_message') || (type === 'item.completed' && isCodexMessageItem(event))
+  return (isMessage ? extractText(event) : '') ?? ''
+}
+
+/**
+ * Whether a codex event reports tool activity — a substring test because the CLI names these
+ * events differently across versions (`exec_command_end`, `item.*` around a command execution,
+ * `tool_*`) and the harness cares only that SOMETHING ran.
+ *
+ * This is also the tool-silence watchdog's only signal on this stream. Codex exposes no
+ * structured tool bodies, so `runCodex` produces no `ToolSpan` at all, and a window keyed on the
+ * trajectory would have force-failed every codex pass that outran it while the run was working.
+ */
+function isCodexToolActivity(type: string): boolean {
+  return type.includes('tool') || type.includes('command') || type.includes('exec')
+}
+
 /**
  * Run the Codex CLI headlessly against `opts.cwd`, authenticated with the leased
  * ChatGPT `auth.json` bundle written to an isolated CODEX_HOME, talking direct to
@@ -1158,6 +1227,9 @@ export async function runCodex(opts: SubscriptionRunOptions): Promise<PiRunOutco
   // context into the prompt itself (Claude Code instead rides --append-system-prompt,
   // falling back to this same fold when the prompt overflows argv).
   const prompt = foldSystemPrompt(opts.systemPrompt, opts.userPrompt)
+  // This stream's tool-silence window (see the claude runner for the shape); opened just before
+  // the CLI starts and closed in the `finally` below.
+  let toolWindow: ToolProgressWindow = NO_TOOL_WINDOW
 
   // Codex's `exec --json` is far thinner than Claude Code's stream: it surfaces only
   // flat assistant text and (on `token_count` events) the per-turn `last_token_usage`
@@ -1171,19 +1243,15 @@ export async function runCodex(opts: SubscriptionRunOptions): Promise<PiRunOutco
 
   const onEvent = (event: Record<string, unknown>): void => {
     const type = typeof event.type === 'string' ? event.type : ''
-    if (
-      type.includes('agent_message') ||
-      (type === 'item.completed' && isCodexMessageItem(event))
-    ) {
-      const text = extractText(event)
-      if (text) {
-        stats.assistantChars += text.length
-        summary = text
-        pendingText = text
-      }
+    const text = codexAssistantText(event, type)
+    if (text) {
+      stats.assistantChars += text.length
+      summary = text
+      pendingText = text
     }
-    if (type.includes('tool') || type.includes('command') || type.includes('exec')) {
+    if (isCodexToolActivity(type)) {
       stats.toolCalls += 1
+      toolWindow.toolCompleted()
     }
     const progress = codexPlanProgress(event)
     if (progress && opts.onProgress) opts.onProgress(progress)
@@ -1214,6 +1282,7 @@ export async function runCodex(opts: SubscriptionRunOptions): Promise<PiRunOutco
     }
   }
 
+  toolWindow = openToolWindow(opts)
   try {
     const { stderrTail } = await streamCli(
       {
@@ -1281,6 +1350,7 @@ export async function runCodex(opts: SubscriptionRunOptions): Promise<PiRunOutco
     // stream, not on stderr — so a bad exit carries the last thing the agent said.
     throw withAgentReport(err, summary, secrets)
   } finally {
+    toolWindow.close()
     if (codexHome) {
       // Lift the CLI session transcripts (`sessions/`) out for short-lived retention BEFORE the
       // home is deleted — the credential (`auth.json`) lives at the home root, never in

package/src/agent.ts

@@ -27,7 +27,7 @@ import {
   unmergedPaths,
 } from './git.js'
 import { inferVcsProvider, openPullRequest } from './vcs-api.js'
-import type { PiRunStats, RunDiagnostics } from './pi.js'
+import type { PiRunStats, RunDiagnostics } from './pi-reduction.js'
 import { applyPrDescription } from './pr-description.js'
 import {
   makeDirClaimer,

package/src/bootstrap-mode.ts

@@ -1,7 +1,7 @@
 import { opendir } from 'node:fs/promises'
 import { join } from 'node:path'
 import type { AgentJob, AgentResult } from './job.js'
-import type { PiRunStats } from './pi.js'
+import type { PiRunStats } from './pi-reduction.js'
 import type { RunOptions } from './runner.js'
 import {
   NEVER_ACTED_CAUSE,
@@ -101,6 +101,7 @@ export async function runBootstrap(job: AgentJob, opts: RunOptions): Promise<Age
       dir,
       target: boot.target,
       ghToken: job.ghToken,
+      signal,
       message: fromScratch
         ? 'Bootstrap new repository'
         : `Bootstrap from ${job.repo.owner}/${job.repo.name}`,

package/src/coding-agent.ts

@@ -30,7 +30,8 @@ import {
 } from './git.js'
 import { openPullRequest } from './vcs-api.js'
 import { FOLLOW_UPS_FILENAME, FollowUpTailer } from './follow-ups.js'
-import type { HarnessCallMetric, PiRunStats } from './pi.js'
+import type { HarnessCallMetric } from './pi.js'
+import type { PiRunStats } from './pi-reduction.js'
 import { EFFORT_REPORT_FILE, type EffortReport } from './effort.js'
 import {
   type AgentPrDescription,

package/src/embed.ts

@@ -6,19 +6,22 @@
 // only the reusable primitives are exposed here.
 
 export {
-  PI_MAX_OUTPUT_TOKENS,
   writePiModelsConfig,
   writeAgentsContext,
   runPi,
-  summarizePiRun,
-  parsePiOutput,
   parseTodoProgress,
-  terminalRunError,
   type PiRunOutcome,
-  type PiRunStats,
   type TodoItem,
   type TodoProgress,
 } from './pi.js'
+export {
+  PI_MAX_OUTPUT_TOKENS,
+  parsePiOutput,
+  summarizePiRun,
+  terminalRunError,
+  type PiRunReduction,
+  type PiRunStats,
+} from './pi-reduction.js'
 export {
   DEFAULT_PROGRESS_GUARD_LIMITS,
   progressGuardLimitsFromEnv,

package/src/failure.ts

@@ -20,6 +20,10 @@
  *
  *  - `inactivity-timeout` — the inactivity watchdog fired (no agent output for the window).
  *  - `max-duration`       — the overall wall-clock cap fired.
+ *  - `no-tool-progress`   — the tool-silence watchdog fired: the agent kept TALKING but completed
+ *                           no tool call for the window. Distinct from `inactivity-timeout` on
+ *                           purpose, because the two need different fixes: one says the container
+ *                           went quiet, this one says the model rabbit-holed while streaming.
  *  - `agent`              — the agent ran but produced an unusable/failed result, or threw.
  *  - `git`                — a git operation failed (clone/push/merge/PR).
  *  - `api`                — an upstream API call failed (e.g. the GitHub/GitLab PR/MR REST call).
@@ -28,15 +32,25 @@
  *  - `no-usable-output`   — the agent finished but returned no usable report / structured output.
  *  - `no-changes`         — a coding agent finished without producing any change to push.
  */
-export type FailureCause =
-  | 'inactivity-timeout'
-  | 'max-duration'
-  | 'agent'
-  | 'git'
-  | 'api'
-  | 'llm-upstream'
-  | 'no-usable-output'
-  | 'no-changes'
+export const FAILURE_CAUSES = [
+  'inactivity-timeout',
+  'max-duration',
+  'no-tool-progress',
+  'agent',
+  'git',
+  'api',
+  'llm-upstream',
+  'no-usable-output',
+  'no-changes',
+] as const
+
+/**
+ * See {@link FAILURE_CAUSES}. Derived from the array rather than declared beside it so the two
+ * cannot disagree, and so the list is ENUMERABLE at runtime — which is what lets
+ * `failure-cause.conformity.test.ts` check this image's vocabulary against the kernel union that
+ * has to classify it (the two are kept in step by hand; the image can carry no workspace dep).
+ */
+export type FailureCause = (typeof FAILURE_CAUSES)[number]
 
 /**
  * A thrown failure that carries a structured {@link FailureCause}, so a `git` / `api`
@@ -77,3 +91,16 @@ export function inactivityAbortMessage(inactivityMs: number): string {
 export function maxDurationAbortMessage(maxDurationMs: number): string {
   return `Aborted: exceeded max duration of ${Math.round(maxDurationMs / 1000)}s`
 }
+
+/**
+ * The tool-silence-watchdog abort message. Human-readable only, like its two siblings — the
+ * backend reads the structured `no-tool-progress` {@link FailureCause}. Says what it observed
+ * (output, but no completed tool call) rather than "hung": the run was demonstrably alive, which
+ * is exactly why the inactivity watchdog never fired.
+ */
+export function toolSilenceAbortMessage(toolSilenceMs: number): string {
+  return (
+    `Aborted: the agent produced output but completed no tool call for ` +
+    `${Math.round(toolSilenceMs / 1000)}s`
+  )
+}

package/src/git.ts

@@ -1081,25 +1081,33 @@ export async function pushBranch(
  * .gitignore and/or license picked on the new-repo page), so a fast-forward is
  * impossible. The Worker pre-flights that the target is empty or holds only that
  * boilerplate, so overwriting it is safe and intended.
+ *
+ * `signal` is the job watchdog's, and threading it is load-bearing rather than tidy: without
+ * it the six commands below are bounded only by their own per-command timeouts, so an abort
+ * raised during the push phase cannot interrupt them and the job keeps working for up to
+ * ~6 × `GIT_TIMEOUT_MS` past its max-duration kill. Every other git helper here threads it.
  */
 export async function reinitAndPush(opts: {
   dir: string
   target: BootstrapTargetSpec
   ghToken: string
   message: string
+  signal?: AbortSignal
 }): Promise<void> {
-  await rm(join(opts.dir, '.git'), { recursive: true, force: true })
-  await git(['init'], { cwd: opts.dir })
+  const { dir, signal } = opts
+  await rm(join(dir, '.git'), { recursive: true, force: true })
+  await git(['init'], { cwd: dir, signal })
   // Start the history on the target's default branch (init may default to master).
-  await git(['checkout', '-b', opts.target.defaultBranch], { cwd: opts.dir })
-  await git(['config', 'user.name', GIT_AUTHOR], { cwd: opts.dir })
-  await git(['config', 'user.email', GIT_EMAIL], { cwd: opts.dir })
-  await git(['add', '-A'], { cwd: opts.dir })
-  await git(['commit', '-m', opts.message], { cwd: opts.dir })
+  await git(['checkout', '-b', opts.target.defaultBranch], { cwd: dir, signal })
+  await git(['config', 'user.name', GIT_AUTHOR], { cwd: dir, signal })
+  await git(['config', 'user.email', GIT_EMAIL], { cwd: dir, signal })
+  await git(['add', '-A'], { cwd: dir, signal })
+  await git(['commit', '-m', opts.message], { cwd: dir, signal })
   const url = authenticatedCloneUrl(opts.target.cloneUrl)
-  await git(['remote', 'add', 'origin', url], { cwd: opts.dir })
+  await git(['remote', 'add', 'origin', url], { cwd: dir, signal })
   await git(['push', '--force', '-u', 'origin', opts.target.defaultBranch], {
-    cwd: opts.dir,
+    cwd: dir,
+    signal,
     env: await authEnv(opts.ghToken),
   })
 }

package/src/inline.ts

@@ -35,6 +35,12 @@ function deriveFinishReason(calls: HarnessCallMetric[] | undefined): 'stop' | 'l
  * directory. The job's watchdog (inactivity + max-duration, see {@link JobRegistry}) bounds
  * it through `opts.signal`; `opts.onActivity` keeps the inactivity timer alive while the CLI
  * streams. The temp cwd is always removed.
+ *
+ * `opts.beginToolWindow` is deliberately NOT forwarded. An inline completion is a one-shot
+ * answer with no checkout and no tool loop, so the tool-silence watchdog would arm a window this
+ * run could never beat and could only ever expire — force-failing a healthy completion under a
+ * cause ("kept talking, completed no tool call") that misdescribes what it is. The inactivity and
+ * max-duration watchdogs still bound it, which is the whole bound this work ever had.
  */
 export async function handleInline(job: InlineJob, opts: RunOptions): Promise<InlineResult> {
   opts.onPhase?.('agent')

package/src/job.ts

@@ -1,4 +1,5 @@
-import type { HarnessCallMetric, PiRunStats } from './pi.js'
+import type { HarnessCallMetric } from './pi.js'
+import type { PiRunStats } from './pi-reduction.js'
 import type { HarnessKind } from './pi-workspace.js'
 import type { FailureCause } from './failure.js'
 import type { EffortReport } from './effort.js'

package/src/jsonl-stream.ts

@@ -0,0 +1,149 @@
+// BOUNDED reading of an agent CLI's child streams: LF-framing its JSONL stdout, and holding a
+// capped tail of raw output for diagnostics.
+//
+// WHY THIS MODULE EXISTS — the harness's two watchdog timers and its `/health` + `/jobs` poll
+// endpoints share ONE Node event loop with the stream-parsing hot path, so the advertised "a
+// container can never run forever" guarantee only holds while that loop stays live (stuck-run
+// audit F6). Both CLI readers (`runPi`, `runSubscriptionAgent`) had grown the same unbounded
+// framing loop: a record with no terminating newline accumulated without limit, so a runaway
+// producer could drive the buffer until a single `JSON.parse` (or the allocation behind it)
+// stalled the loop past the abort timers and the poll handlers alike. The container then stops
+// answering polls while its own watchdogs never fire — the exact wedge the timers exist to
+// prevent, with only the engine-side poll-failure tolerance and the reaper left underneath.
+//
+// One definition of "how much of a child's output we are willing to hold" therefore serves both
+// harnesses, for the same reason `ProgressGuard` does: two copies of a bound are two bounds.
+
+/**
+ * Longest single JSONL record either CLI may emit before the reader stops buffering it.
+ *
+ * Deliberately far above the largest LEGITIMATE record — the terminal `agent_end`, which carries
+ * the run's whole message transcript including tool results — because dropping that one costs the
+ * run its summary and stats. The cap is not a size policy, it is the ceiling that keeps a
+ * runaway producer from growing the buffer until parsing it wedges the event loop, so it only
+ * has to be low enough that one parse of it stays well inside the poll cadence.
+ */
+export const MAX_JSONL_LINE_CHARS = 32 * 1024 * 1024
+
+/**
+ * A fixed-size tail of a text stream, for output kept ONLY to quote back on a failure.
+ *
+ * Retaining a whole run's stdout to slice the last 2 KB off it at close is the memory half of
+ * F6: a chatty agent's output is unbounded, and the container OOMing is another way for a job to
+ * stop answering polls with no watchdog having fired. The tail is trimmed lazily — only once it
+ * has grown past twice the bound — so a run that streams thousands of chunks pays an amortized
+ * O(1) copy per chunk rather than an O(maxChars) slice on every one of them.
+ */
+export class BoundedTail {
+  private text = ''
+  private total = 0
+
+  constructor(private readonly maxChars: number) {}
+
+  push(chunk: string): void {
+    this.text += chunk
+    this.total += chunk.length
+    if (this.text.length > this.maxChars * 2) this.text = this.text.slice(-this.maxChars)
+  }
+
+  /** The last `maxChars` characters seen. */
+  toString(): string {
+    return this.text.length > this.maxChars ? this.text.slice(-this.maxChars) : this.text
+  }
+
+  /** Everything ever pushed, whether or not it is still retained. */
+  get totalChars(): number {
+    return this.total
+  }
+
+  /**
+   * Characters dropped off the FRONT because the tail is bounded; 0 while everything still fits.
+   *
+   * A caller that renders the tail to a human owes them this: a bounded tail is the opposite of a
+   * prefix, so a reader who assumes one concludes the producer stopped where the text begins.
+   * Diagnostic quotes (a stderr tail) need no such note — being a tail is what they are for.
+   */
+  get droppedChars(): number {
+    return this.total - this.toString().length
+  }
+}
+
+/**
+ * Frames a child's LF-delimited JSONL stdout into complete records, bounding what it will buffer
+ * for any one of them.
+ *
+ * `onLine` is invoked per complete record with `final: false`, and once more from {@link flush}
+ * with `final: true` for a trailing record that arrived without its newline (a clean exit can
+ * leave the last event unterminated). `final` is what lets a caller deliver the record's
+ * progress/telemetry signal while suppressing any decision that would KILL the run: the process
+ * has already exited, so a guard tripping on that last buffered record would turn a clean exit
+ * into a spurious failure.
+ *
+ * A record that outgrows {@link MAX_JSONL_LINE_CHARS} is DROPPED, not truncated: a partial JSON
+ * document is not a record, and handing the parser half of one would report it as corrupt output
+ * rather than as the bound firing. The reader then resynchronises on the next newline, so the
+ * oversized record costs its own signal and nothing after it. Callers report {@link droppedLines}
+ * at close (never per line) so the loss is diagnosable instead of silent.
+ */
+export class JsonlLineReader {
+  private buffer = ''
+  /** True while discarding the tail of a record that already blew the cap. */
+  private skipping = false
+  private dropped = 0
+
+  constructor(
+    private readonly onLine: (line: string, final: boolean) => void,
+    private readonly maxLineChars: number = MAX_JSONL_LINE_CHARS,
+  ) {}
+
+  /** Feed one stdout chunk, emitting every complete record it finishes. */
+  push(text: string): void {
+    // Framing scans the incoming CHUNK, never the accumulated buffer. `buffer += chunk` is a
+    // cheap rope in V8 and `.length` reads off it in constant time, but ANY search over it
+    // flattens the rope — so scanning the buffer once per chunk costs O(record) per chunk, i.e.
+    // quadratic in a runaway record, paid on the very event loop this class exists to keep
+    // answering polls. Measured, a 32 MB unterminated record cost ~6s of solid blocking that
+    // way: the cap bounded the memory and handed back the stall in its place.
+    let rest = text
+    for (;;) {
+      const nl = rest.indexOf('\n')
+      if (nl === -1) break
+      if (this.skipping) {
+        // The newline that ends an oversized record ends the skip with it: everything buffered
+        // for that record is already gone, and what follows is a fresh one.
+        this.skipping = false
+      } else {
+        // The only place the buffer is materialised, and only for a record that COMPLETED —
+        // which the branch below has already kept under the cap.
+        const raw = this.buffer + rest.slice(0, nl)
+        this.buffer = ''
+        // The cap is on the RECORD, not on the leftover buffer: a record that arrived whole
+        // inside one chunk was never buffered across pushes, and dropping it only when it
+        // straddles a chunk boundary would make the bound depend on how the OS split the reads.
+        if (raw.length > this.maxLineChars) this.dropped++
+        else this.onLine(raw.trim(), false)
+      }
+      rest = rest.slice(nl + 1)
+    }
+    if (this.skipping) return
+    this.buffer += rest
+    if (this.buffer.length > this.maxLineChars) {
+      this.buffer = ''
+      // Count the record once, however many chunks it goes on to spill.
+      this.dropped++
+      this.skipping = true
+    }
+  }
+
+  /** Emit any trailing unterminated record (see the class doc); call once, after the child exits. */
+  flush(): void {
+    const line = this.buffer.trim()
+    this.buffer = ''
+    if (line && !this.skipping) this.onLine(line, true)
+  }
+
+  /** Records dropped for exceeding the line cap; 0 on every ordinary run. */
+  get droppedLines(): number {
+    return this.dropped
+  }
+}