@cat-factory/executor-harness 1.31.0

package/src/coding-agent.ts

@@ -0,0 +1,393 @@
+import { mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { HarnessAuthFields, RepoSpec } from './job.js'
+import {
+  branchHasCommitsSince,
+  cloneExistingBranch,
+  cloneRepo,
+  commitTrackedEdits,
+  createBranch,
+  excludeFromGit,
+  headCommit,
+  listUntrackedFiles,
+  prepareExistingCheckout,
+  pushBranch,
+  refreshFromBaseIfClean,
+  remoteBranchExists,
+} from './git.js'
+import { FOLLOW_UPS_FILENAME, FollowUpTailer } from './follow-ups.js'
+import type { PiRunStats } from './pi.js'
+import {
+  acquireRepoCheckout,
+  agentNeverActed,
+  agentOutputTail,
+  runAgentInWorkspace,
+} from './pi-workspace.js'
+import type { ProgressGuardLimits } from './pi.js'
+import type { RunOptions } from './runner.js'
+import { log } from './logger.js'
+
+// The shared skeleton for the container coding agents that clone a repo, run Pi
+// against it and push the result on a branch. The implementation (`/run`) and
+// CI-fixer (`/ci-fix`) agents are conceptually the same job — only what they clone
+// onto and what they do with the outcome differ — so they share this whole flow
+// rather than each re-deriving (and separately bug-fixing) it. Built on the thinner
+// {@link withWorkspace}/{@link runAgentInWorkspace} base shared with the non-pushing
+// agents (bootstrap/blueprint/merger). Mirrors their secret handling: the per-job
+// GitHub + proxy tokens arrive in the spec and live only for the job's duration.
+
+/** What a coding agent run needs: where to clone, what to run, where to push. */
+export interface CodingAgentSpec extends HarnessAuthFields {
+  /** Short label for the temp dir + log lines (e.g. 'impl', 'ci-fix'). */
+  kind: string
+  /** The job id, threaded into every log line for end-to-end tracing. */
+  jobId: string
+  repo: RepoSpec
+  /** Branch to clone and check out as the starting point. */
+  cloneBranch: string
+  /** A fresh branch to create off the clone before running; omit to work directly on `cloneBranch`. */
+  newBranch?: string
+  /** Branch the produced change is pushed to. */
+  pushBranch: string
+  ghToken: string
+  /** Composed role + best-practice fragments; written to Pi's global AGENTS.md context. */
+  systemPrompt: string
+  /** The concrete task prompt handed to Pi. */
+  userPrompt: string
+  model: string
+  /** Commit message for any work the agent left uncommitted. */
+  commitMessage: string
+  /** Per-kind web-search guidance (backend-composed); surfaced only when web search is on. */
+  webToolsGuidance?: string
+  /** Enable proxy-backed web search for this run (see {@link AgentRunSpec.webSearchProxy}). */
+  webSearchProxy?: boolean
+  /** Per-knob progress-guard overrides (loosen-only), set per agent kind by the backend. */
+  guardLimits?: Partial<ProgressGuardLimits>
+  /**
+   * Reuse a stable per-repo checkout (clean-sweep + fetch + switch branch) instead of a
+   * fresh clone into a throwaway temp dir. Set only by the local warm-pool transport
+   * (its containers are reused across runs); absent everywhere else.
+   */
+  persistentCheckout?: boolean
+  /**
+   * Tail the Coder's follow-up sentinel file ({@link FOLLOW_UPS_FILENAME}) and stream the
+   * forward-looking items it surfaces out on the job view (the Follow-up companion). Set
+   * only for the implementer (`coder`) dispatch; absent ⇒ no tailing (e.g. the CI-fixer).
+   */
+  streamFollowUps?: boolean
+}
+
+/** The outcome of a coding agent run, before each caller maps it to its own result shape. */
+export interface CodingAgentOutcome {
+  /** Whether the branch carries work and was therefore pushed (new commits, or resumed prior work). */
+  pushed: boolean
+  /** Whether the run resumed an existing remote branch (prior work already pushed). */
+  resumed: boolean
+  summary: string
+  stats: PiRunStats
+  stderrTail?: string
+  /** Token usage from a subscription harness's CLI stream (absent for Pi). */
+  usage?: { inputTokens: number; outputTokens: number }
+}
+
+/**
+ * How often the harness checkpoints the agent's work mid-run by pushing the branch.
+ * A per-run container can be evicted at any moment; pushing the agent's commits
+ * periodically means an evicted run's work survives on the branch, so a retry
+ * RESUMES on top of it instead of starting over. Overridable via env for tests.
+ */
+function checkpointIntervalMs(): number {
+  const n = Number(process.env.JOB_CHECKPOINT_INTERVAL_MS)
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : 60_000
+}
+
+/**
+ * How often the harness tails the Coder's follow-up sentinel file to surface new items.
+ * Short (a few seconds) so the Follow-up companion lights up promptly while the Coder is
+ * still running. Overridable via env for tests.
+ */
+function followUpPollIntervalMs(): number {
+  const n = Number(process.env.JOB_FOLLOWUP_POLL_INTERVAL_MS)
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : 3_000
+}
+
+/**
+ * Clone (or RESUME an existing branch) → write context → run Pi → push the branch
+ * iff it carries work. The agent commits its OWN work (it alone knows which files
+ * belong vs scratch/artifacts it created), so the harness never blanket-stages:
+ * {@link commitTrackedEdits} is only a safety net for forgotten edits to ALREADY
+ * tracked files, and the run is judged a no-op only when the branch never advanced
+ * past its pre-run tip ({@link branchHasCommitsSince}). The harness owns push + PR;
+ * it checkpoints (pushes) periodically so an evicted run's commits survive and a
+ * retry resumes on them. Returns the run's summary/stats, whether it pushed, and
+ * whether it resumed; callers decide what to do after a push (open a PR, or nothing).
+ */
+export async function runCodingAgent(
+  spec: CodingAgentSpec,
+  opts: RunOptions = {},
+): Promise<CodingAgentOutcome> {
+  const { signal } = opts
+  // The registry already binds jobId/repo/branch; add the coding kind + the push branch
+  // (which differs from the cloned branch the registry bound).
+  const logger = (opts.log ?? log).child({ kind: spec.kind, branch: spec.pushBranch })
+  return acquireRepoCheckout(
+    { persistent: spec.persistentCheckout === true, prefix: spec.kind, repo: spec.repo },
+    async (dir) => {
+      // Resume an evicted earlier run when its work branch already exists on the
+      // remote: clone THAT branch and continue on its commits, rather than branching
+      // off base and redoing everything. Only the impl path (which creates a fresh
+      // `newBranch`) can resume; the ci-fix/conflict paths already clone the PR branch.
+      //
+      // Resume safety relies on two invariants the dispatcher (worker) upholds, since
+      // the harness can't see run/PR state from inside the container:
+      //  - At most ONE active run per block at a time. The work branch is deterministic
+      //    per block (`cat-factory/<blockId>`), so two concurrent runs would target the
+      //    same branch; their pushes race. A plain (non-forced) push fails safely on a
+      //    non-fast-forward rather than clobbering the other run's commits, so the worst
+      //    case is one run failing — never lost work — but the dispatcher should not
+      //    knowingly run two at once.
+      //  - Re-dispatch only NON-terminal runs (failed / evicted / stale-running), whose
+      //    branch is by definition unmerged. Resuming a branch whose PR already merged
+      //    could re-introduce merged work; that is avoided two ways: the platform deletes
+      //    the work branch when its PR merges (GitHubPullRequestMerger), so a re-run finds
+      //    no branch and starts fresh, and a `done` block is never re-dispatched anyway.
+      const resumed =
+        spec.newBranch != null &&
+        (await remoteBranchExists(spec.repo.cloneUrl, spec.newBranch, spec.ghToken, signal))
+      opts.onPhase?.('clone')
+      if (spec.persistentCheckout) {
+        // Reused checkout: clean-sweep + fetch + switch branch in place. A resumed branch
+        // (or a run without `newBranch`, working directly on `cloneBranch`) already exists
+        // on the remote, so check it out directly; otherwise (re)create `newBranch` off the
+        // base tip — the same resume-vs-fresh decision the clone paths below make.
+        const targetBranch = spec.newBranch ?? spec.cloneBranch
+        logger.info('coding-agent: preparing reused checkout', { branch: targetBranch, resumed })
+        await prepareExistingCheckout({
+          dir,
+          repo: spec.repo,
+          ghToken: spec.ghToken,
+          branch: targetBranch,
+          baseBranch: spec.cloneBranch,
+          existing: resumed || spec.newBranch == null,
+          signal,
+        })
+      } else if (resumed) {
+        logger.info('coding-agent: resuming existing branch', { branch: spec.newBranch })
+        await cloneExistingBranch({
+          cloneUrl: spec.repo.cloneUrl,
+          branch: spec.newBranch!,
+          ghToken: spec.ghToken,
+          dir,
+          signal,
+        })
+      } else {
+        logger.info('coding-agent: cloning', { cloneBranch: spec.cloneBranch })
+        await cloneRepo({
+          repo: { ...spec.repo, baseBranch: spec.cloneBranch },
+          ghToken: spec.ghToken,
+          dir,
+          signal,
+        })
+        if (spec.newBranch) await createBranch(dir, spec.newBranch, signal)
+      }
+      // The branch tip before the agent runs this time. A FRESH run produced work iff
+      // the branch advances past it; a RESUMED run already carries prior work, so it is
+      // never a no-op regardless of what this pass adds. Captured BEFORE the resume base
+      // refresh below so that refresh's merge commit counts as advancement and is pushed.
+      const baseSha = await headCommit(dir, signal)
+
+      // A resumed branch was cut from an OLDER base; merge the latest base in when the
+      // two merge cleanly, so the agent works against current base and the PR stays
+      // current. On a conflict this is a no-op (the run continues on the stale base — the
+      // merge gate handles a conflicting PR downstream, as before), so it never blocks a
+      // resume. Best-effort: any error is treated as "continue without refreshing".
+      if (resumed) {
+        const refreshed = await refreshFromBaseIfClean(
+          dir,
+          spec.cloneBranch,
+          spec.ghToken,
+          signal,
+        ).catch(() => false)
+        if (!refreshed) {
+          logger.info('coding-agent: resume base refresh skipped (conflict or error)', {
+            base: spec.cloneBranch,
+          })
+        }
+      }
+
+      // Serialize all pushes to the work branch through a single in-flight promise.
+      // A checkpoint tick and the final push (or two slow checkpoint ticks) must never
+      // run `git push` to the same branch concurrently: overlapping pushes race on the
+      // remote ref and can make a push fail with a ref-lock / non-fast-forward error —
+      // which, on the FINAL push, would fail the whole run even though the work is
+      // committed. `pushWorkOnce` coalesces concurrent callers onto one push and only
+      // pushes once the branch has advanced past `baseSha` (see below).
+      //
+      // Only push once the branch has advanced past its pre-run tip: pushing while it
+      // still sits at `baseSha` would create the work branch at the base commit (a
+      // zero-diff branch), which a later retry would see via `remoteBranchExists` and
+      // treat as resumable work — then fail to open a PR ("no commits between base and
+      // head"). So a run that never commits leaves NO branch behind, preserving the
+      // clean no-op outcome.
+      let pushInFlight: Promise<void> | null = null
+      const pushWorkOnce = (): Promise<void> => {
+        if (pushInFlight) return pushInFlight
+        pushInFlight = (async () => {
+          if (!(await branchHasCommitsSince(dir, baseSha, signal))) return
+          await pushBranch(dir, spec.pushBranch, spec.ghToken, signal)
+        })().finally(() => {
+          pushInFlight = null
+        })
+        return pushInFlight
+      }
+      // Read the in-flight push, if any. A function (with an explicit return type) so the
+      // value isn't subject to the caller's straight-line narrowing — `pushInFlight` is
+      // only ever assigned inside closures, which flow analysis can't observe.
+      const inFlightPush = (): Promise<void> | null => pushInFlight
+
+      // Checkpoint the agent's committed work to the branch periodically so an eviction
+      // mid-run doesn't lose it (a retry then resumes from the pushed commits). The
+      // agent commits its own work; this only PUSHES already-committed commits, so it
+      // never races the agent's staging. Best-effort: a failed checkpoint is skipped.
+      // Surface checkpoint-push failures at warn with a running count: a checkpoint losing
+      // a race is harmless once, but a steadily-climbing count means mid-run work is NOT
+      // being durably checkpointed, so an eviction would lose it — previously invisible at
+      // info level. Still best-effort: a failed checkpoint never fails the run.
+      let checkpointFailures = 0
+      const checkpoint = setInterval(() => {
+        pushWorkOnce().catch((err) => {
+          checkpointFailures++
+          logger.warn('coding-agent: checkpoint push failed', {
+            reason: err instanceof Error ? err.message : String(err),
+            checkpointFailures,
+          })
+        })
+      }, checkpointIntervalMs())
+      checkpoint.unref?.()
+
+      // In a monorepo the service lives in a subdirectory: run Pi with its cwd set to
+      // that subtree (git stays rooted at `dir` so commits/pushes still cover the whole
+      // checkout). Created if missing so a coder scaffolding a brand-new service into an
+      // existing monorepo has a cwd to start in. The agent is also TOLD it's in a
+      // monorepo (and where) via the AGENTS.md context below.
+      const serviceDirectory = spec.repo.serviceDirectory
+      const workDir = serviceDirectory ? join(dir, serviceDirectory) : dir
+      if (serviceDirectory) await mkdir(workDir, { recursive: true })
+
+      // Follow-up companion: tail the Coder's sentinel file and stream new items out on the
+      // job view. Locally exclude it from git first so the agent's own `git add` can never
+      // stage it and it never surfaces as an untracked leftover or in the PR. The sentinel
+      // lives in the agent's working directory (its cwd), where the prompt tells it to write.
+      const followUpTailer =
+        spec.streamFollowUps && opts.onFollowUp
+          ? new FollowUpTailer(join(workDir, FOLLOW_UPS_FILENAME), opts.onFollowUp, logger)
+          : undefined
+      let followUpTick: ReturnType<typeof setInterval> | undefined
+      if (followUpTailer) {
+        await excludeFromGit(dir, FOLLOW_UPS_FILENAME, signal)
+        followUpTick = setInterval(() => {
+          void followUpTailer.poll()
+        }, followUpPollIntervalMs())
+        followUpTick.unref?.()
+      }
+
+      let outcome: CodingAgentOutcome
+      try {
+        opts.onPhase?.('agent')
+        logger.info('coding-agent: running agent', { serviceDirectory })
+        const { summary, stats, stderrTail, usage } = await runAgentInWorkspace(
+          {
+            dir: workDir,
+            systemPrompt: spec.systemPrompt,
+            userPrompt: spec.userPrompt,
+            model: spec.model,
+            harness: spec.harness,
+            subscriptionToken: spec.subscriptionToken,
+            subscriptionBaseUrl: spec.subscriptionBaseUrl,
+            ambientAuth: spec.ambientAuth,
+            proxyBaseUrl: spec.proxyBaseUrl,
+            sessionToken: spec.sessionToken,
+            serviceDirectory,
+            webToolsGuidance: spec.webToolsGuidance,
+            webSearchProxy: spec.webSearchProxy,
+            guardLimits: spec.guardLimits,
+          },
+          opts,
+        )
+
+        // Stop tailing the follow-up sentinel and flush any items written after the last
+        // tick, so a fast final burst still reaches the job view before the run is recorded.
+        if (followUpTick) clearInterval(followUpTick)
+        if (followUpTailer) await followUpTailer.poll().catch(() => {})
+
+        // Safety net for forgotten edits: commit changes to TRACKED files only (never
+        // untracked scratch files/artifacts — the agent owns committing new files).
+        await commitTrackedEdits(dir, spec.commitMessage, signal)
+
+        // Stop periodic checkpoints and let any in-flight one settle BEFORE the final
+        // push, so the two never run a concurrent `git push` to the same branch (the
+        // final push below is then a fresh attempt whose failure is the real signal).
+        clearInterval(checkpoint)
+        const inflight = inFlightPush()
+        if (inflight) await inflight.catch(() => {})
+
+        // Surface (don't fail on) untracked, non-ignored files the agent left behind:
+        // `commitTrackedEdits` only captures edits to ALREADY tracked files, so a NEW
+        // file the agent created but forgot to commit is silently dropped. Logging it
+        // makes that loss observable when a PR turns out to be missing a file.
+        const leftover = await listUntrackedFiles(dir, signal)
+        if (leftover.length > 0) {
+          logger.warn('coding-agent: uncommitted new files left behind (not pushed)', {
+            count: leftover.length,
+            files: leftover.slice(0, 20),
+          })
+        }
+
+        const hasWork = resumed || (await branchHasCommitsSince(dir, baseSha, signal))
+        if (!hasWork) {
+          logger.info('coding-agent: no changes produced', { ...stats })
+          outcome = {
+            pushed: false,
+            resumed,
+            summary,
+            stats,
+            ...(stderrTail ? { stderrTail } : {}),
+            ...(usage ? { usage } : {}),
+          }
+        } else {
+          opts.onPhase?.('push')
+          logger.info('coding-agent: pushing', { resumed, ...stats })
+          await pushWorkOnce()
+          outcome = {
+            pushed: true,
+            resumed,
+            summary,
+            stats,
+            ...(stderrTail ? { stderrTail } : {}),
+            ...(usage ? { usage } : {}),
+          }
+        }
+      } finally {
+        // Safety net for the throw path (the happy path already cleared these above).
+        clearInterval(checkpoint)
+        if (followUpTick) clearInterval(followUpTick)
+      }
+      return outcome
+    },
+  )
+}
+
+/**
+ * The "no changes" reason both coding agents report: a caller-supplied lead phrase
+ * plus the shared "never acted" cause and a credential-scrubbed tail of Pi's stderr.
+ */
+export function noChangesReason(
+  lead: string,
+  stats: PiRunStats,
+  stderrTail: string | undefined,
+): string {
+  const cause = agentNeverActed(stats)
+    ? ' (the agent never acted — it most likely could not reach the model)'
+    : ''
+  return `${lead}${cause}.${agentOutputTail(stderrTail)}`
+}

package/src/embed.ts

@@ -0,0 +1,32 @@
+// Embeddable surface of the executor harness: the Pi-driving and git helpers
+// the container payload uses, re-exported so other packages (e.g. the benchmark
+// harness) can run the *same* coding-agent flow outside the container — clone a
+// repo, write the agent context, point Pi at an OpenAI-compatible endpoint, run
+// it, and inspect what changed. The HTTP server / job lifecycle stays internal;
+// only the reusable primitives are exposed here.
+
+export {
+  PI_MAX_OUTPUT_TOKENS,
+  DEFAULT_PROGRESS_GUARD_LIMITS,
+  writePiModelsConfig,
+  writeAgentsContext,
+  runPi,
+  summarizePiRun,
+  parsePiOutput,
+  parseTodoProgress,
+  progressGuardLimitsFromEnv,
+  terminalRunError,
+  type PiRunOutcome,
+  type PiRunStats,
+  type ProgressGuardLimits,
+  type TodoItem,
+  type TodoProgress,
+} from './pi.js'
+export {
+  cloneRepo,
+  createBranch,
+  changedPathsFromPorcelain,
+  hasAgentChanges,
+  redactSecrets,
+} from './git.js'
+export type { RepoSpec } from './job.js'

package/src/failure.ts

@@ -0,0 +1,73 @@
+// Single source of truth for how a job FAILS: the canonical failure-cause vocabulary plus
+// the watchdog abort-message builders.
+//
+// WHY THIS MODULE EXISTS — the backend classifies a failed job by REGEX-matching the
+// harness's free-text `error` string (it has no other signal today):
+//   - server `ContainerRepoBootstrapper.classifyBootstrapFailure`:
+//       /inactivity|no agent activity|max duration/i → 'timeout', else → 'agent'
+//   - orchestration `job.logic.isContainerEvictionError`: /evicted or crashed/i (FACADE-owned,
+//     NOT emitted here — the harness must keep NOT emitting that phrase for a non-eviction)
+// Because those phrases are matched downstream, their wording MUST stay stable. Centralizing
+// the builders here keeps the emitted text from drifting away from the regex that reads it.
+// Alongside the strings we now also emit a STRUCTURED {@link FailureCause} on the job view so
+// the backend can prefer it and treat the regex as a backward-compatible fallback.
+
+/**
+ * The structured reason a harness job failed, surfaced on the job view's `failureCause`.
+ * Covers only HARNESS-owned failures — container eviction is detected by the runtime facade
+ * (a vanished container → `(container evicted or crashed)`), never set here.
+ *
+ *  - `inactivity-timeout` — the inactivity watchdog fired (no agent output for the window).
+ *  - `max-duration`       — the overall wall-clock cap fired.
+ *  - `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).
+ *  - `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'
+  | 'no-usable-output'
+  | 'no-changes'
+
+/**
+ * A thrown failure that carries a structured {@link FailureCause}, so a `git` / `api`
+ * operation that fails deep in a helper surfaces its real cause instead of being flattened
+ * to the generic `agent` in the registry's catch. The watchdog kills set their cause from
+ * `killReason` and never throw this; anything else thrown without a cause stays `agent`.
+ */
+export class HarnessFailure extends Error {
+  readonly failureCause: FailureCause
+  constructor(failureCause: FailureCause, message: string) {
+    super(message)
+    this.name = 'HarnessFailure'
+    this.failureCause = failureCause
+  }
+}
+
+/** The structured cause a thrown error carries, or undefined for a plain/agent error. */
+export function failureCauseOf(err: unknown): FailureCause | undefined {
+  return err instanceof HarnessFailure ? err.failureCause : undefined
+}
+
+/**
+ * The inactivity-watchdog abort message PREFIX. The `no agent activity` phrase is
+ * regex-matched by the backend's `classifyBootstrapFailure` (→ `timeout`); do not reword it.
+ * The caller appends a `(likely hung ...)` diagnostic clause (phase + last tool) after this,
+ * so the prefix deliberately stops before the parenthetical (see `runner.ts` drive catch).
+ */
+export function inactivityAbortMessage(inactivityMs: number): string {
+  return `Aborted: no agent activity for ${Math.round(inactivityMs / 1000)}s`
+}
+
+/**
+ * The max-duration-watchdog abort message. The `max duration` phrase is regex-matched by the
+ * backend's `classifyBootstrapFailure` (→ `timeout`); do not reword it.
+ */
+export function maxDurationAbortMessage(maxDurationMs: number): string {
+  return `Aborted: exceeded max duration of ${Math.round(maxDurationMs / 1000)}s`
+}

package/src/follow-ups.ts

@@ -0,0 +1,106 @@
+import { readFile } from 'node:fs/promises'
+import { log, type Logger } from './logger.js'
+
+// The Coder's forward-looking side channel. As the implementer works it appends one
+// JSON line per item to a sentinel file in its working directory; the harness tails
+// that file and streams the new items OUT on the job view (drain-on-read), so the
+// backend lifts them onto the run's step and the "Follow-up companion" lights up
+// while the container is still running. This is the OUT-bound half only — there is no
+// in-bound path back into a running container (an answer reaches the Coder via a
+// backend-driven re-run, not by resuming the live process).
+
+/** The sentinel file the Coder appends items to, relative to its working directory. */
+export const FOLLOW_UPS_FILENAME = '.cat-follow-ups.jsonl'
+
+/** One streamed item the Coder surfaced. Mirrors the backend's `streamedFollowUpSchema`. */
+export interface FollowUpLine {
+  kind: 'follow_up' | 'question'
+  title: string
+  detail: string
+  suggestedAction?: string
+}
+
+/** Coerce one parsed JSON line into a {@link FollowUpLine}, or null when unusable. */
+function coerceLine(value: unknown): FollowUpLine | null {
+  if (typeof value !== 'object' || value === null) return null
+  const o = value as Record<string, unknown>
+  const title = typeof o.title === 'string' ? o.title.trim() : ''
+  if (!title) return null
+  const kind = o.kind === 'question' ? 'question' : 'follow_up'
+  const detail = typeof o.detail === 'string' ? o.detail : ''
+  const suggestedAction =
+    typeof o.suggestedAction === 'string' && o.suggestedAction.trim()
+      ? o.suggestedAction.trim()
+      : undefined
+  return {
+    kind,
+    title: title.slice(0, 300),
+    detail,
+    ...(suggestedAction ? { suggestedAction } : {}),
+  }
+}
+
+/**
+ * Tails an append-only JSONL sentinel file, yielding only the NEW complete lines on each
+ * {@link poll}. Tracks how many characters have been consumed so a partially-written
+ * trailing line (no newline yet) is held back until it completes. Tolerant: a malformed
+ * line is skipped, a missing file yields nothing — surfacing follow-ups must never
+ * disturb the coding run.
+ */
+export class FollowUpTailer {
+  private consumed = 0
+  /** Running count of complete-but-unparsable lines, so silent drops become visible. */
+  private skipped = 0
+
+  constructor(
+    private readonly filePath: string,
+    private readonly onItems: (items: FollowUpLine[]) => void,
+    private readonly logger: Logger = log,
+  ) {}
+
+  /** Read any new complete lines and emit the coerced items. Best-effort; never throws. */
+  async poll(): Promise<void> {
+    let content: string
+    try {
+      content = await readFile(this.filePath, 'utf8')
+    } catch {
+      // Not created yet (or vanished): nothing to surface.
+      return
+    }
+    if (content.length <= this.consumed) return
+    const fresh = content.slice(this.consumed)
+    // Only consume up to the last newline; hold any trailing partial line for next poll.
+    const lastNewline = fresh.lastIndexOf('\n')
+    if (lastNewline === -1) return
+    this.consumed += lastNewline + 1
+    const items: FollowUpLine[] = []
+    let skippedThisPoll = 0
+    for (const raw of fresh.slice(0, lastNewline).split('\n')) {
+      const line = raw.trim()
+      if (!line) continue
+      try {
+        const coerced = coerceLine(JSON.parse(line))
+        if (coerced) items.push(coerced)
+        else skippedThisPoll++
+      } catch {
+        // A non-JSON / half-written line — skip it (a later poll re-reads from `consumed`,
+        // which only advanced past complete newline-terminated lines).
+        skippedThisPoll++
+      }
+    }
+    if (skippedThisPoll > 0) {
+      // A complete line that didn't yield an item is dropped for good (consumed past it).
+      // Surface it at warn with a running total rather than swallowing it silently — a
+      // steadily-growing count points at a malformed-emitter bug, not a transient race.
+      this.skipped += skippedThisPoll
+      this.logger.warn('follow-ups: skipped malformed lines', {
+        skipped: skippedThisPoll,
+        skippedTotal: this.skipped,
+      })
+    }
+    if (items.length > 0) {
+      this.logger.info('follow-ups: surfaced items', { count: items.length })
+      this.onItems(items)
+    }
+  }
+}