@humwick/server 0.0.0-stage → 0.130.1

package/runner/src/empty-turn.ts

@@ -0,0 +1,816 @@
+// #2389 — an empty provider turn is a failure, not a clean idle.
+//
+// Observed live (blackbox, OpenCode via OpenRouter): the spawn prompt was delivered and
+// persisted, the model was dispatched a real turn, and the assistant message came back
+// `finish=stop` with NO text part, NO tool part and ZERO tokens. Twice in a row. The runner logged
+// `turn ended via provider idle` and left the agent reporting healthy and idle, so the spawning
+// coordinator read `ready` as "working" while the agent sat dead for hours. Nothing anywhere
+// distinguished "idle having finished the work" from "idle having produced literally nothing".
+//
+// This ledger is that distinction, and it is deliberately provider-agnostic: every adapter funnels
+// its turn edges through the same `onStatus` seam and its output through the same session-event
+// seam, so the detection belongs there rather than in any one adapter.
+//
+// It does NOT re-send the prompt. The prompt is already in session history — re-sending would
+// duplicate it. The one recovery action is a NUDGE (see `EMPTY_TURN_NUDGE`), which is what a plain
+// "hello" did when a human finally poked the stranded agent: it provokes a fresh turn over history
+// the model has held all along, carrying no copy of the original instruction.
+
+import { PROVIDER_TURN_EMPTY_TIMELINE_STATUS, type ProviderState } from "@humwick/sdk";
+import type { RunnerTimelineEvent } from "./turn-reconcile-event";
+import type { ProviderInputObserver } from "./adapter";
+
+/** How many consecutive empty turns before the spawn parent is woken. One empty turn is nudged and
+ *  logged; the SECOND is the observed signature of a genuinely stranded agent (the incident had
+ *  exactly two before a human intervened) and means the nudge did not take. */
+export const EMPTY_TURN_ESCALATE_AFTER = 2;
+
+/** Handle for rolling an arm back if the delivery it was taken for never completed. */
+/**
+ * Whether an armed input subjects its turns to the strike ladder, or only to the timed backstop —
+ * and whether it opens a FRESH strike budget.
+ *
+ * - `ladder`     — new user-originated input. Strikes, and a budget of its own.
+ * - `watch-only` — a memory block or a self-resume continuation. Its own turns take no strike
+ *                  (they legitimately produce nothing), and it never resets a budget it may be
+ *                  landing in the middle of. It cannot DOWNGRADE an outstanding ladder obligation.
+ * - `retry`      — a re-delivery of input already armed once (the obligation re-injection, which
+ *                  fires up to three times per message). Strikes like a ladder arm, but re-opening
+ *                  the budget each time would let one message earn four nudges and hold
+ *                  `consecutiveEmpty` below the escalation threshold indefinitely.
+ */
+export type EmptyTurnArmMode = "ladder" | "watch-only" | "retry";
+
+/** Everything an arm overwrites, so a rollback restores rather than erases. */
+interface EmptyTurnBudget {
+  undischargedInputAt?: number;
+  evidence?: InputEvidence;
+  ladderExempt: boolean;
+  nudged: boolean;
+  nudgedInStrand: boolean;
+  escalated: boolean;
+  consecutiveEmpty: number;
+}
+
+export interface EmptyTurnArm {
+  readonly token: number;
+  readonly evidence?: InputEvidence;
+  /** Turns started as of the arm, so a rollback can tell "nothing happened" from "the model ran". */
+  readonly turnsStarted: number;
+  /** State this arm displaced. A failed delivery must put back what was there, not clear it — a
+   *  nested arm (a memory block landing on an unanswered message) otherwise takes the message's
+   *  whole obligation down with it when its own deliver throws. */
+  readonly prev: EmptyTurnBudget;
+}
+
+export interface EmptyTurnVerdict {
+  /** The turn ended having produced nothing, against input it was supposed to answer. */
+  empty: boolean;
+  /** How many empty turns in a row, counting this one. */
+  consecutiveEmpty: number;
+  turnAgeMs: number;
+  /** Deliver the nudge now. At most once per user-originated input. */
+  nudge: boolean;
+  /** Wake the spawn parent now. At most once per user-originated input. */
+  escalate: boolean;
+}
+
+/** What an output event did: nothing (no live turn), counted, counted against a turn whose work
+ *  predates the current input, or discarded because it belongs to a turn already let go. */
+export type EmptyTurnOutput = "no-turn" | "counted" | "predates-input" | "stale-turn";
+
+/** How many turn ids the ledger keeps so it can RECOGNISE a late event as stale. Only ids it has
+ *  actually held count: OpenCode stamps its SESSION id on every event, and that id must stay
+ *  "unknown" so its output is still counted. */
+const RECENT_TURN_IDS = 16;
+
+interface TurnRecord {
+  id: string;
+  startedAt: number;
+  endedAt?: number;
+  outputs: number;
+  lastWorkAt?: number;
+}
+
+interface InputEvidence {
+  offeredAt?: number;
+  hasConsumptionSignal: boolean;
+  consumed: boolean;
+  turn?: TurnRecord;
+  outputsAtOffer: number;
+}
+
+/**
+ * Per-agent bookkeeping for "did this turn actually do anything".
+ *
+ * Pure and clock-injected so the whole decision table is unit-testable without standing up an
+ * AgentRunner — same reason `turn-reconcile-event.ts` keeps its builders pure.
+ */
+export class EmptyTurnLedger {
+  private turn?: TurnRecord;
+  /** Set when user-originated input reaches the provider; cleared by a turn that produces output. */
+  private undischargedInputAt?: number;
+  private evidence?: InputEvidence;
+  private nudged = false;
+  /** Whether a nudge was spent anywhere in the CURRENT strand, as opposed to for the current input.
+   *  The two diverge once a new message lands on an unanswered strand: that message earns its own
+   *  nudge, but the operator-facing copy must still say a nudge was already tried and did not take. */
+  private nudgedInStrand = false;
+  private escalated = false;
+  private consecutiveEmpty = 0;
+  private armToken = 0;
+  private turnsStarted = 0;
+  /** Turn ids this ledger has actually held — see RECENT_TURN_IDS. */
+  private readonly recentTurnIds: string[] = [];
+  /** Timed backstop only: an output-free turn takes no strike and provokes no nudge. */
+  private ladderExempt = false;
+
+  /**
+   * Work-provoking input is being handed to the provider. Called BEFORE the delivery is awaited,
+   * never after it resolves: OpenCode's `/session/{id}/message` is the SYNCHRONOUS endpoint and
+   * returns only once the assistant message is complete, so an arm on resolution lands at or after
+   * the turn's own end — 18 ms apart from two independent async sources in the retained incident
+   * logs, i.e. a coin flip on whether the offending turn is judged at all.
+   *
+   * Arming is an explicit decision at each call site rather than a hook on the payload-agnostic
+   * input queue: the queue also carries memory blocks and self-resume continuations, whose turns
+   * legitimately produce nothing (a compaction, a silent acknowledgment), and arming on those would
+   * strike perfectly healthy agents.
+   */
+  armInput(at: number, mode: EmptyTurnArmMode = "ladder", pendingOffer = false): EmptyTurnArm {
+    // A watch-only arm must never DOWNGRADE a ladder obligation that is still outstanding: a
+    // continuation injected while a delivered message is still unanswered would otherwise silently
+    // disable the strikes for that message.
+    const keepsLadder = mode !== "watch-only" || (this.undischargedInputAt !== undefined && !this.ladderExempt);
+    const prev: EmptyTurnBudget = {
+      undischargedInputAt: this.undischargedInputAt,
+      evidence: this.evidence,
+      ladderExempt: this.ladderExempt,
+      nudged: this.nudged,
+      nudgedInStrand: this.nudgedInStrand,
+      escalated: this.escalated,
+      consecutiveEmpty: this.consecutiveEmpty,
+    };
+    this.ladderExempt = !keepsLadder;
+    // Non-ladder arms inherit the outstanding obligation's barrier. Moving it would stop
+    // work already answering the older input from discharging that obligation.
+    this.undischargedInputAt = mode !== "ladder" && prev.undischargedInputAt !== undefined
+      ? Math.min(prev.undischargedInputAt, at)
+      : at;
+    const inherits = mode !== "ladder" && prev.undischargedInputAt !== undefined;
+    const evidence: InputEvidence | undefined = inherits ? undefined : {
+      offeredAt: pendingOffer ? undefined : at,
+      hasConsumptionSignal: false,
+      consumed: false,
+      turn: pendingOffer ? undefined : this.turn,
+      outputsAtOffer: this.turn?.outputs ?? 0,
+    };
+    if (evidence) this.evidence = evidence;
+    // Only a LADDER arm opens a fresh strike budget — see EmptyTurnArmMode. Both other modes land
+    // on an agent that may already be mid-strand, and resetting there re-opened the nudge budget:
+    // a routine memory injection bought the provider a SECOND nudge and pushed the parent's wake
+    // out by a full turn; the obligation re-injection could do it three times over.
+    //
+    // And a ladder arm only opens one when the previous obligation was actually DISCHARGED. A
+    // stranded provider answers each delivered message with exactly one empty turn, so a fresh
+    // budget per message meant `consecutiveEmpty` was zeroed before it could ever reach the
+    // escalation threshold: six messages, six empty turns, six nudges and no page at all. Any
+    // inbound traffic more often than the escalation deadline permanently suppressed the
+    // coordinator wake — which is the entire point of this feature. A NEW message still earns its
+    // own nudge (it is new work, and the strand may be message-specific); only the count and the
+    // one-shot page survive.
+    if (mode === "ladder") {
+      this.nudged = false;
+      if (prev.undischargedInputAt === undefined) {
+        this.nudgedInStrand = false;
+        this.escalated = false;
+        this.consecutiveEmpty = 0;
+      }
+    }
+    this.armToken += 1;
+    return { token: this.armToken, evidence, turnsStarted: this.turnsStarted, prev };
+  }
+
+  noteInputOffered(arm: EmptyTurnArm, at: number, hasConsumptionSignal: boolean): void {
+    const evidence = arm.evidence;
+    if (!evidence || evidence !== this.evidence || evidence.offeredAt !== undefined) return;
+    evidence.offeredAt = at;
+    evidence.hasConsumptionSignal = hasConsumptionSignal;
+    evidence.turn = this.turn;
+    evidence.outputsAtOffer = this.turn?.outputs ?? 0;
+  }
+
+  noteInputConsumed(arm: EmptyTurnArm): boolean {
+    const evidence = arm.evidence;
+    if (!evidence || evidence !== this.evidence || evidence.offeredAt === undefined) return false;
+    evidence.consumed = true;
+    const turn = evidence.turn;
+    const answered = Boolean(turn && turn.outputs > 0 && this.answers(turn));
+    // A synchronous delivery can confirm after its turn's delayed verdict already ran.
+    if (answered && turn?.endedAt !== undefined && !this.turn) this.dischargeOutput();
+    return answered;
+  }
+
+  /**
+   * The delivery this arm was taken for threw, so nothing is owed — unless a turn started in the
+   * meantime, in which case something clearly DID reach the provider (a sync-endpoint transport can
+   * throw after the model already ran) and the obligation stands. Fenced on the token so a later
+   * arm is never rolled back by an earlier failure.
+   *
+   * RESTORES rather than clears: this arm may be nested inside an older one that is still owed
+   * (a memory block injected while a delivered message sits unanswered), and clearing outright
+   * discarded the message's ladder AND its backstop the moment the injection's own deliver threw.
+   */
+  disarmInput(arm: EmptyTurnArm): void {
+    if (arm.token !== this.armToken || this.turnsStarted !== arm.turnsStarted) return;
+    this.undischargedInputAt = arm.prev.undischargedInputAt;
+    this.evidence = arm.prev.evidence;
+    this.ladderExempt = arm.prev.ladderExempt;
+    this.nudged = arm.prev.nudged;
+    this.nudgedInStrand = arm.prev.nudgedInStrand;
+    this.escalated = arm.prev.escalated;
+    this.consecutiveEmpty = arm.prev.consecutiveEmpty;
+  }
+
+  /**
+   * Forget everything. Used where a turn's outcome stops being the model's own doing: an operator
+   * interrupt or abort (which `agent.turn_interrupted` already owns and which always ends a turn
+   * with no output), and any provider restart — after which a pre-restart obligation must not be
+   * charged against an unrelated post-restart turn.
+   *
+   * KNOWN RESIDUAL, argued not fixed: this drops an obligation armed by input that arrived DURING
+   * the interrupted/restarted turn, which is a discharge by something other than the input's own
+   * turn — the shape every blocking finding on #2389 has had. It is kept because a post-restart
+   * ledger cannot honestly judge a pre-restart obligation, and because the outcome is not silent:
+   * the interrupt command and forceClearProviderTurn both route `agent.turn_interrupted` to the
+   * spawn parent. The auto-restart path is weaker — `restartProvider` emits a
+   * `provider.exit_detected` TIMELINE event, so it is visible on the activity feed but NOT reported
+   * to the parent (agent.exited is terminal-only, agent.provider_flapping needs repeats). The
+   * window is narrow, because a normal restart re-delivers the prompt and re-arms; the real loss is
+   * an already-read relay message, or a suppressPrompt restart. Revisit if that is ever observed.
+   */
+  reset(): void {
+    this.turn = undefined;
+    this.recentTurnIds.length = 0;
+    this.undischargedInputAt = undefined;
+    this.evidence = undefined;
+    this.nudged = false;
+    this.nudgedInStrand = false;
+    this.escalated = false;
+    this.consecutiveEmpty = 0;
+    this.ladderExempt = false;
+    this.armToken += 1;
+  }
+
+  noteTurnStarted(turnId: string, at: number): void {
+    this.turn = { id: turnId, startedAt: at, outputs: 0 };
+    this.recentTurnIds.push(turnId);
+    if (this.recentTurnIds.length > RECENT_TURN_IDS) this.recentTurnIds.shift();
+    this.turnsStarted += 1;
+  }
+
+  /**
+   * Drop a turn without judging it. For turn edges that are relay/provider bookkeeping rather than
+   * the model working: a compaction or a context clear mints a provider-turn busy and ends it with
+   * an idle, producing a genuinely output-free turn that means nothing is wrong. The undischarged
+   * marker is deliberately LEFT in place, so the real turn that follows is still judged.
+   *
+   * EXCEPT for a watch-only obligation, which this DISCHARGES on the same rule `settle` uses: a
+   * turn that ran is proof the agent is alive and consuming its input. A compaction is the very
+   * turn a memory block most often provokes, and a discarded turn never reaches `settle` — so
+   * leaving the marker set here paged the spawn parent (durably; this notice has no TTL) about a
+   * completely healthy agent ten minutes later. That is exactly the false page the watch-only
+   * discharge exists to prevent, arriving through the one door it did not cover.
+   */
+  noteTurnDiscarded(turnId: string): void {
+    const turn = this.turn;
+    if (turn?.id !== turnId) return;
+    this.turn = undefined;
+    if (this.ladderExempt && this.answers(turn)) this.dischargeWatchOnly();
+  }
+
+  /**
+   * Evidence the model produced SOMETHING this turn — an assistant response, streamed narration, a
+   * reasoning step, a tool call, background work it kicked off. Counted from several independent
+   * seams on purpose: a turn that only ran tools, or one whose narration is suppressed by
+   * `reasoningCapture: false`, must never be misread as empty.
+   *
+   * Claude's transcript tail runs whatever `reasoningCapture` says (#3411), so its tool and
+   * narration steps count here even when the mirror keeps them out of chat.
+   */
+  noteOutput(turnId?: string, occurredAt?: number, isWork = false): EmptyTurnOutput {
+    if (!this.turn) return "no-turn";
+    // Provenance. `answers` decides which turn may DISCHARGE an obligation; this decides which turn
+    // an output BELONGS to, and without it the two disagree. A turn's closing response is published
+    // asynchronously AFTER its idle edge (that is why the settle waits on turnCapturesInFlight),
+    // and a reasoning-tail poll can still be in flight when the tail is stopped — so late output
+    // from turn N landed on turn N+1, discharged an input armed between them, and let a genuinely
+    // empty turn go completely undetected. The emitter already carries the right id.
+    //
+    // Only a KNOWN id can be stale: OpenCode stamps its session id on every event, which never
+    // equals a runner-minted turn id, so an unrecognised id must still count.
+    if (turnId !== undefined && turnId !== this.turn.id && this.recentTurnIds.includes(turnId)) return "stale-turn";
+    this.turn.outputs += 1;
+    if (isWork && occurredAt !== undefined && Number.isFinite(occurredAt)) {
+      this.turn.lastWorkAt = Math.max(this.turn.lastWorkAt ?? -Infinity, occurredAt);
+    }
+    // Output counts against the turn; only work since delivery can cancel the input's backstop.
+    return this.answers(this.turn) || this.undischargedInputAt === undefined ? "counted" : "predates-input";
+  }
+
+  /** The provider reported idle for this turn. The verdict is taken later — see `settle`. */
+  noteTurnEnded(turnId: string, at: number): void {
+    if (this.turn?.id !== turnId) return;
+    this.turn.endedAt = at;
+  }
+
+  /**
+   * KNOWN RESIDUAL (accepted): two turns that both start and end inside one settle window collapse.
+   * `noteTurnStarted` overwrites the turn record and `noteTurnEnded` reschedules the single settle
+   * timer, so turn N's verdict is dropped and the ladder undercounts (two empty turns read as one).
+   * The timed backstop still catches the strand — it is armed on the input, not on any turn — so
+   * the parent is woken either way; only the count and the nudge timing are affected. Fixing it
+   * means a settle timer per turn, which is a larger change than the residual is worth.
+   */
+  /** True while an ended turn is still awaiting its verdict, so a caller can defer settling. */
+  awaitingVerdict(turnId: string): boolean {
+    return this.turn?.id === turnId && this.turn.endedAt !== undefined;
+  }
+
+  /**
+   * Take the verdict for an ended turn, after a settle delay that lets late output land (several
+   * providers publish the closing assistant response asynchronously, AFTER the idle edge — judging
+   * synchronously would call every one of those turns empty).
+   *
+   * `canNudge` is false when the adapter has no prompt-injection seam. Then no recovery is possible
+   * at all, so the very first empty turn escalates rather than waiting for a second.
+   */
+  settle(turnId: string, input: { now: number; canNudge: boolean }): EmptyTurnVerdict | undefined {
+    const turn = this.turn;
+    if (!turn || turn.id !== turnId || turn.endedAt === undefined) return undefined;
+    this.turn = undefined;
+    const turnAgeMs = Math.max(0, turn.endedAt - turn.startedAt);
+    if (turn.outputs > 0) {
+      // A turn already in flight can consume coalesced input without starting a new turn (#2691).
+      if (this.answers(turn)) {
+        this.dischargeOutput();
+      }
+      return { empty: false, consecutiveEmpty: this.consecutiveEmpty, turnAgeMs, nudge: false, escalate: false };
+    }
+    // A turn nobody asked for (an autonomous wake, a provider-side artifact) producing nothing is
+    // not a failure — there was no obligation to discharge. Nor is the turn that follows a memory
+    // block or a self-resume continuation: those legitimately produce nothing (a compaction, a
+    // silent acknowledgment), which is why they arm watch-only.
+    //
+    // A watch-only obligation is DISCHARGED here, by any turn that ran to completion — empty or
+    // not. A turn that started and ended is proof the agent is alive and consuming its input, so it
+    // is not stranded, and leaving the marker set meant every silently-absorbed memory block paged
+    // the spawn parent ten minutes later with a durable "steer it or re-spawn it" notice it could
+    // do nothing with. The backstop keeps the case it actually protects: input delivered and NO
+    // turn ever started — see escalateOnTimeout.
+    if (this.undischargedInputAt === undefined || this.evidence?.offeredAt === undefined || turn.endedAt < this.evidence.offeredAt || this.ladderExempt) {
+      if (this.ladderExempt && this.answers(turn)) this.dischargeWatchOnly();
+      return { empty: false, consecutiveEmpty: this.consecutiveEmpty, turnAgeMs, nudge: false, escalate: false };
+    }
+    this.consecutiveEmpty += 1;
+    const nudge = input.canNudge && !this.nudged;
+    const escalate = !this.escalated && (this.consecutiveEmpty >= EMPTY_TURN_ESCALATE_AFTER || !nudge);
+    if (nudge) this.nudged = this.nudgedInStrand = true;
+    if (escalate) this.escalated = true;
+    return { empty: true, consecutiveEmpty: this.consecutiveEmpty, turnAgeMs, nudge, escalate };
+  }
+
+  /**
+   * The timed backstop, and the ONLY net under two strands the turn ladder structurally cannot see:
+   * an armed input that never provokes a turn at all (so no idle edge ever arrives to judge), and a
+   * watch-only continuation, whose turns take no strikes by design. It also covers a provider that
+   * ignores the nudge outright — it never starts the second turn the ladder needs.
+   *
+   * `retry` means "not now, ask again": a turn is running this instant, so the model IS doing
+   * something (a long silent tool run mirrors nothing, and that is exactly the shape that would
+   * otherwise escalate falsely). The caller re-arms rather than dropping the watch, so declining
+   * once can never disable the backstop for good.
+   *
+   * Deliberately NOT gated on `answers` the way discharging is. A turn that predates the input is
+   * still the reason the input has not been picked up — provider input is buffered behind the live
+   * turn — so escalating on it would page the parent about an agent that is visibly working. This
+   * defers; it never discharges. A turn that is wedged forever is the provider-turn watchdog's
+   * (#1980) to report, not this one's.
+   */
+  escalateOnTimeout(): "escalate" | "retry" | "done" {
+    if (this.undischargedInputAt === undefined || this.escalated) return "done";
+    if (this.turn && this.turn.endedAt === undefined) return "retry";
+    this.escalated = true;
+    return "escalate";
+  }
+
+  /** In-flight work needs correlated consumption, or stamped tool/response evidence (#2691). */
+  private answers(turn: TurnRecord): boolean {
+    const evidence = this.evidence;
+    const inputAt = evidence?.offeredAt;
+    if (!evidence || this.undischargedInputAt === undefined || inputAt === undefined) return false;
+    if (turn.startedAt >= inputAt && evidence.turn !== turn) return true;
+    if (this.ladderExempt && turn.startedAt >= this.undischargedInputAt) return true;
+    if (evidence.turn !== turn || (turn.endedAt !== undefined && turn.endedAt < inputAt)) return false;
+    return evidence.hasConsumptionSignal
+      ? evidence.consumed && turn.outputs > evidence.outputsAtOffer
+      : turn.lastWorkAt !== undefined && turn.lastWorkAt > inputAt;
+  }
+
+  private dischargeOutput(): void {
+    this.dischargeWatchOnly();
+    this.nudged = false;
+    this.nudgedInStrand = false;
+    this.escalated = false;
+    this.consecutiveEmpty = 0;
+  }
+
+  private dischargeWatchOnly(): void {
+    this.undischargedInputAt = undefined;
+    this.evidence = undefined;
+    this.ladderExempt = false;
+  }
+
+  /** Whether input is still outstanding — nothing has produced output since it was delivered. */
+  hasUndischargedInput(): boolean {
+    return this.undischargedInputAt !== undefined;
+  }
+
+  /** Whether a nudge was spent anywhere in the current strand — what the operator-facing copy
+   *  reports, as distinct from the per-input budget the ladder spends. */
+  nudgedInCurrentStrand(): boolean {
+    return this.nudgedInStrand;
+  }
+
+  /** Consecutive empty turns as of the last settled verdict (0 once anything lands). */
+  consecutiveEmptyTurns(): number {
+    return this.consecutiveEmpty;
+  }
+}
+
+/**
+ * The nudge. NOT a re-send: it carries no copy of the instruction, because the instruction is
+ * already in the provider's session history — that is precisely why the stranded agent executed its
+ * original spawn prompt the moment a human typed "hello" at it hours later. This says only "your
+ * last turn produced nothing, go look at what you already have".
+ *
+ * Prefixed with `[agent-relay` so `isRunnerInjectedPrompt` suppresses its prompt echo and it is
+ * never mirrored into chat as if a human had typed it.
+ */
+export const EMPTY_TURN_NUDGE =
+  "[agent-relay] Your previous turn ended without producing any output — no text, no tool calls. " +
+  "That was a provider-side empty completion, not an instruction to stop. Nothing was lost: the " +
+  "work you were given is already in this session's history above. Re-read it and carry on now; do " +
+  "not wait for it to be re-sent.";
+
+/**
+ * #2389 — the announcement for a turn that ended clean and produced nothing.
+ *
+ * Emitted (not silently logged) for the same reason #1621 emits its reconcile: `idle` is exactly
+ * the signal a coordinator uses to decide the agent is fine, so an empty turn that only ever
+ * reached a log file leaves the coordinator reading health it does not have. Pure builder so the
+ * payload the parent's notice derives from is unit-testable in isolation.
+ */
+export function emptyTurnTimelineEvent(input: {
+  turnId: string;
+  consecutiveEmpty: number;
+  turnAgeMs: number;
+  nudged: boolean;
+  escalated: boolean;
+  /** `timeout` distinguishes the timed backstop's event from the ladder's, so the activity feed's
+   *  per-(agent, event id) dedup does not swallow the escalation under the first event's key. */
+  kind?: "turn" | "timeout";
+  now: number;
+}): RunnerTimelineEvent {
+  // The timed backstop can fire having never judged a turn at all: input was delivered and the
+  // provider never started one. The turn-ladder copy is wrong on every field an operator reads
+  // there — it claims a turn ended cleanly, says the nudge did not take when none was sent, and
+  // renders "0 provider turns in a row" — so that case gets its own wording, and its own
+  // `emptyKind` for the server's notification copy.
+  const stalled = input.kind === "timeout" && input.consecutiveEmpty === 0 && !input.nudged;
+  const repeated = input.consecutiveEmpty > 1 ? ` (${input.consecutiveEmpty} in a row)` : "";
+  const action = input.nudged
+    ? " The agent has been nudged to continue from the instruction already in its history; the prompt was NOT re-sent."
+    : input.escalated
+      ? " The nudge did not take — this needs a look."
+      : "";
+  return {
+    status: PROVIDER_TURN_EMPTY_TIMELINE_STATUS,
+    // Keyed per turn so a latched event re-published on later status frames cannot re-notify.
+    id: `provider-turn-empty-${input.turnId}${input.kind === "timeout" ? "-timeout" : ""}`,
+    timestamp: input.now,
+    title: stalled ? "Provider never started work on delivered input" : "Provider turn produced no output",
+    body: stalled
+      ? "Input was delivered to the provider and nothing has come back since — no turn was started " +
+        "at all, or every turn that did start was provider bookkeeping. The agent reports healthy " +
+        "and idle while the work it was given sits untouched."
+      : `The provider ended a turn cleanly${repeated} without emitting any text, tool call or ` +
+        `reasoning against input that had already been delivered — an empty completion, not finished work.${action}`,
+    icon: "ti-message-off",
+    metadata: {
+      eventType: PROVIDER_TURN_EMPTY_TIMELINE_STATUS,
+      emptyKind: stalled ? "input-stalled" : "empty-turn",
+      turnId: input.turnId,
+      consecutiveEmptyTurns: input.consecutiveEmpty,
+      turnAgeMs: input.turnAgeMs,
+      nudged: input.nudged,
+      // The server notifies the spawn parent ONLY on this flag, so a first, nudged empty turn stays
+      // a timeline event and does not wake anyone.
+      escalated: input.escalated,
+    },
+  };
+}
+
+/** How long after a provider reports its turn idle before the verdict is taken.
+ *
+ *  Several capture paths publish the closing assistant response ASYNCHRONOUSLY, after the idle edge:
+ *  Claude's hookless native capture reads and parses the transcript, and the Stop-hook path awaits a
+ *  settle poll. For a lean worker with `reasoningCapture: false` that late response is the turn's
+ *  ONLY output signal, so a synchronous verdict would call every such turn empty. A false positive
+ *  costs a needless nudge, so this errs long — and the watch re-defers while a capture is still in
+ *  flight, bounded by {@link SETTLE_MAX_DEFERRALS} so a wedged capture cannot disable detection. */
+export const EMPTY_TURN_SETTLE_MS = 5_000;
+const SETTLE_MAX_DEFERRALS = 6;
+
+/** How long after a nudge before the spawn parent is told anyway. A nudge that takes produces a turn
+ *  within seconds; this covers the provider that ignores it and never starts one — which the
+ *  consecutive-turn ladder can never observe, because it needs a second turn to count. */
+export const EMPTY_TURN_ESCALATION_MS = 3 * 60_000;
+
+/** How long an armed input may sit with NOTHING happening — no turn, no output — before the spawn
+ *  parent is told. Longer than the post-nudge deadline because this covers the case where the
+ *  provider never even starts a turn, and a message delivered mid-turn legitimately waits for the
+ *  running one to finish (which re-arms rather than escalating; see escalateOnTimeout). */
+export const EMPTY_TURN_INPUT_ESCALATION_MS = 10 * 60_000;
+
+export interface EmptyTurnWatchPorts {
+  /** Read lazily — AgentRunner wires this in a field initializer, before its own options exist. */
+  provider(): string;
+  /** False when the adapter has no prompt-injection seam, so no recovery is possible at all. */
+  canNudge(): boolean;
+  /** Deliver the nudge. Never awaited by the watch — on OpenCode the idle edge runs inside the SSE
+   *  reader's callback and the nudge is a blocking POST that lasts the whole next turn. */
+  nudge(): void;
+  /** True while an asynchronous turn capture might still publish this turn's only output. */
+  capturesInFlight(): boolean;
+  log(message: string): void;
+  publishTimeline(event: RunnerTimelineEvent): void;
+  /** Called when the "produced nothing" marker clears and the card should be re-published. */
+  onMarkerCleared(): void;
+  /** Test seam only; production uses the EMPTY_TURN_* constants above. */
+  settleMs?: number;
+  escalationMs?: number;
+  inputEscalationMs?: number;
+}
+
+/**
+ * The ledger plus its timers and its verdict→action ladder, kept out of AgentRunner so the whole
+ * decision is drivable from a test with injected ports and a fake clock, and so the runner keeps
+ * only the wiring it alone can own (the adapter, the process handle, the input queue).
+ *
+ * The ladder: an empty turn is logged, marked on the card and nudged; a SECOND consecutive empty
+ * turn (or a first that could not be nudged) wakes the spawn parent; and a nudge that provokes no
+ * turn at all escalates on a timer, because the ladder alone would wait forever.
+ */
+export class EmptyTurnWatch {
+  private readonly ledger = new EmptyTurnLedger();
+  private settleTimer?: ReturnType<typeof setTimeout>;
+  private escalationTimer?: ReturnType<typeof setTimeout>;
+  private deferrals = 0;
+  private state?: ProviderState;
+  private stopped = false;
+
+  private readonly settleMs: number;
+  private readonly escalationMs: number;
+  private readonly inputEscalationMs: number;
+  /** What the last escalation was armed with, so a timer cleared by output on a turn that is then
+   *  DISCARDED can be put back exactly as it was. `deadlineAt` is ABSOLUTE: re-arming with the full
+   *  duration each time meant a provider compacting more often than the deadline pushed the
+   *  escalation out forever. */
+  private lastEscalationArm?: { subject: string; deadlineMs: number; deadlineAt: number };
+
+  constructor(private readonly ports: EmptyTurnWatchPorts) {
+    this.settleMs = ports.settleMs ?? EMPTY_TURN_SETTLE_MS;
+    this.escalationMs = ports.escalationMs ?? EMPTY_TURN_ESCALATION_MS;
+    this.inputEscalationMs = ports.inputEscalationMs ?? EMPTY_TURN_INPUT_ESCALATION_MS;
+  }
+
+  /**
+   * #2389 — arming ALSO starts the timed backstop, not just the strike ladder. Without this the
+   * ladder is the only detector, and it can only ever fire on a turn that actually ran: an input
+   * that provokes no turn at all, and every watch-only continuation, would go undetected forever.
+   */
+  armInput(at: number, mode: EmptyTurnArmMode = "ladder", pendingOffer = false): EmptyTurnArm {
+    // Sampled BEFORE the arm: an arm landing on an obligation that is still outstanding continues
+    // the strand it found rather than starting one.
+    const inherits = this.ledger.hasUndischargedInput();
+    const arm = this.ledger.armInput(at, mode, pendingOffer);
+    // A ladder arm that opens a FRESH budget also invalidates the card marker it was published
+    // against — "last provider turn produced no output" no longer describes anything outstanding.
+    // Gated on `inherits` because clearing it mid-strand erased the coordinator-facing signal for a
+    // strand that was still running.
+    if (mode === "ladder" && !inherits && this.state) {
+      this.state = undefined;
+      this.ports.onMarkerCleared();
+    }
+    // The subject must be UNIQUE per arm. It becomes the timeline event id (which the activity feed
+    // dedups per (agent, id)) and the parent notification's idempotency key — and that key has no
+    // time window, so a constant here made the dedup permanent: the first strand on an agent was
+    // reported and every later one was silently swallowed, forever. Which is this issue's own
+    // failure mode. The clock disambiguates across runner restarts (the token restarts at 0 with a
+    // fresh ledger); the token disambiguates two arms inside the same millisecond.
+    // An arm that inherits the obligation must not restart its clock either — the ledger already
+    // refuses to move the barrier for one (see armInput), and moving the TIMER anyway is the same
+    // unbounded-postponement bug noteTurnDiscarded had: a memory block injected more often than the
+    // deadline pushed the escalation out forever. It keeps the running strand's subject too, so one
+    // strand stays one notification key.
+    const previous = inherits && mode !== "ladder" ? this.lastEscalationArm : undefined;
+    this.armEscalation(
+      previous?.subject ?? `input-${at}-${arm.token}`,
+      this.inputEscalationMs,
+      previous ? Math.max(0, previous.deadlineAt - Date.now()) : this.inputEscalationMs,
+    );
+    return arm;
+  }
+
+  inputObserver(arm: EmptyTurnArm): ProviderInputObserver {
+    return {
+      offered: (at, hasConsumptionSignal) => this.ledger.noteInputOffered(arm, at, hasConsumptionSignal),
+      consumed: () => { if (this.ledger.noteInputConsumed(arm)) this.clearEscalation(); },
+    };
+  }
+
+  disarmInput(arm: EmptyTurnArm): void {
+    this.ledger.disarmInput(arm);
+    // The rollback may have restored an OLDER obligation (nested arm) — in which case the backstop
+    // stays up, now under this arm's subject. Only a rollback that leaves nothing owed disarms it.
+    if (!this.ledger.hasUndischargedInput()) this.clearEscalation();
+  }
+
+  noteTurnStarted(turnId: string, at: number): void {
+    this.ledger.noteTurnStarted(turnId, at);
+  }
+
+  /**
+   * Evidence the model produced something. A `prompt` event is the user's own text echoing back.
+   * `diagnostic: true` (#2397 round 3) is an adapter narrating its OWN retry/failure mechanics —
+   * e.g. OpenCode's "retrying in Ns…" hold — never the model's own output; crediting it would let a
+   * retry storm that ends in terminal failure cancel the #2389 escalation that wakes the spawn
+   * parent for a turn that never actually produced anything.
+   */
+  noteOutput(event?: { type?: string; body?: string; turnId?: string; occurredAt?: number; diagnostic?: boolean }): void {
+    if (event && (event.type === "prompt" || event.diagnostic === true || !event.body?.trim())) return;
+    // Output must belong to a turn that can answer this input; stray or stale events keep the watch.
+    if (this.ledger.noteOutput(event?.turnId, event?.occurredAt, event?.type === "tool" || event?.type === "response") === "counted") this.clearEscalation();
+  }
+
+  /** A turn edge that is bookkeeping rather than the model working (a compaction, a context clear). */
+  noteTurnDiscarded(turnId: string): void {
+    this.ledger.noteTurnDiscarded(turnId);
+    // The discarded turn may have RECORDED output (a compaction emits session events of its own),
+    // which cleared the backstop — and the discard then drops the turn without settling, so nothing
+    // else ever re-arms. That left the obligation outstanding with no timer at all: a compaction
+    // landing on an undischarged input made the strand permanently undetectable, which is precisely
+    // the case the input-armed backstop was added for. Put the timer back exactly as it was.
+    if (this.escalationTimer || !this.ledger.hasUndischargedInput()) return;
+    const previous = this.lastEscalationArm;
+    // Re-armed to the ORIGINAL absolute deadline, not for a fresh full duration: a provider
+    // compacting more often than the deadline would otherwise postpone the escalation indefinitely.
+    if (previous) this.armEscalation(previous.subject, previous.deadlineMs, Math.max(0, previous.deadlineAt - Date.now()));
+  }
+
+  noteTurnEnded(turnId: string, at: number): void {
+    this.ledger.noteTurnEnded(turnId, at);
+    this.scheduleSettle(turnId, 0);
+  }
+
+  /** Forget everything: an interrupt (already covered by `agent.turn_interrupted`) or a restart. */
+  reset(): void {
+    this.ledger.reset();
+    this.clearSettle();
+    this.clearEscalation();
+    this.lastEscalationArm = undefined;
+    this.state = undefined;
+  }
+
+  dispose(): void {
+    this.stopped = true;
+    this.clearSettle();
+    this.clearEscalation();
+  }
+
+  /** The card marker: "idle having produced nothing" must not read as a plain healthy idle. */
+  providerState(): ProviderState | undefined {
+    return this.state;
+  }
+
+  /** Read straight off the ledger. A watch-level mirror went stale the moment a new ladder arm
+   *  reset the ledger's own budget, and the escalation copy derived from it then described the
+   *  PREVIOUS strand — claiming a turn had ended and a nudge had been sent when neither was true. */
+  consecutiveEmptyTurns(): number {
+    return this.ledger.consecutiveEmptyTurns();
+  }
+
+  private scheduleSettle(turnId: string, deferrals: number): void {
+    if (this.stopped) return;
+    this.clearSettle();
+    this.deferrals = deferrals;
+    this.settleTimer = setTimeout(() => {
+      this.settleTimer = undefined;
+      this.settle(turnId);
+    }, this.settleMs);
+    this.settleTimer.unref?.();
+  }
+
+  private settle(turnId: string): void {
+    if (this.stopped) return;
+    if (this.ports.capturesInFlight() && this.deferrals < SETTLE_MAX_DEFERRALS) {
+      this.scheduleSettle(turnId, this.deferrals + 1);
+      return;
+    }
+    const verdict = this.ledger.settle(turnId, { now: Date.now(), canNudge: this.ports.canNudge() });
+    if (!verdict) return;
+    if (!verdict.empty) {
+      // Covers forward progress AND a discharged watch-only obligation: no obligation, no backstop.
+      if (!this.ledger.hasUndischargedInput()) this.clearEscalation();
+      if (this.state) {
+        this.state = undefined;
+        this.ports.onMarkerCleared();
+      }
+      return;
+    }
+    this.ports.log(`turn ${turnId} ended having produced NO output against delivered input (${verdict.consecutiveEmpty} consecutive empty turn(s))${verdict.nudge ? "; nudging" : ""}${verdict.escalate ? "; escalating to spawn parent" : ""}`);
+    this.state = {
+      state: "idle",
+      reason: "empty-turn",
+      label: verdict.consecutiveEmpty > 1
+        ? `Last ${verdict.consecutiveEmpty} provider turns produced no output`
+        : "Last provider turn produced no output",
+      message: "The provider ended the turn cleanly without emitting any text, tool call or reasoning against input that had already been delivered.",
+      source: this.ports.provider(),
+      consecutiveEmptyTurns: verdict.consecutiveEmpty,
+      updatedAt: Date.now(),
+    };
+    // publishTimeline publishes the status too, so the marker and its explanation travel together.
+    this.ports.publishTimeline(emptyTurnTimelineEvent({
+      turnId,
+      consecutiveEmpty: verdict.consecutiveEmpty,
+      turnAgeMs: verdict.turnAgeMs,
+      nudged: verdict.nudge,
+      escalated: verdict.escalate,
+      now: Date.now(),
+    }));
+    if (!verdict.nudge) return;
+    this.ports.nudge();
+    this.armEscalation(turnId, this.escalationMs);
+  }
+
+  /** `fireInMs` differs from `deadlineMs` only on a re-arm that must honour the original absolute
+   *  deadline; `deadlineMs` stays the nominal budget the log line quotes. */
+  private armEscalation(turnId: string, deadlineMs: number, fireInMs = deadlineMs): void {
+    this.clearEscalation();
+    if (this.stopped) return;
+    this.lastEscalationArm = { subject: turnId, deadlineMs, deadlineAt: Date.now() + fireInMs };
+    this.escalationTimer = setTimeout(() => {
+      this.escalationTimer = undefined;
+      if (this.stopped) return;
+      const verdict = this.ledger.escalateOnTimeout();
+      // A turn is running right now — ask again rather than dropping the watch.
+      if (verdict === "retry") {
+        this.armEscalation(turnId, deadlineMs);
+        return;
+      }
+      if (verdict === "done") return;
+      // Read off the LEDGER, which a new ladder arm resets. A watch-level mirror stayed at the
+      // previous strand's count, so a coordinator's steer that then stalled reported itself as an
+      // ended turn whose nudge did not take — neither of which had happened for that message.
+      const nudged = this.ledger.nudgedInCurrentStrand();
+      this.ports.log(`no output ${Math.round(deadlineMs / 1000)}s after ${nudged ? "the empty-turn nudge" : "input was delivered"} — escalating to spawn parent`);
+      this.ports.publishTimeline(emptyTurnTimelineEvent({
+        turnId,
+        consecutiveEmpty: this.ledger.consecutiveEmptyTurns(),
+        turnAgeMs: 0,
+        nudged,
+        escalated: true,
+        // A distinct id: the activity feed dedups timeline rows per (agent, event id), so reusing
+        // the ladder's key made the escalation invisible on the dashboard even though the parent
+        // notification landed.
+        kind: "timeout",
+        now: Date.now(),
+      }));
+    }, fireInMs);
+    this.escalationTimer.unref?.();
+  }
+
+  private clearSettle(): void {
+    if (!this.settleTimer) return;
+    clearTimeout(this.settleTimer);
+    this.settleTimer = undefined;
+  }
+
+  private clearEscalation(): void {
+    if (!this.escalationTimer) return;
+    clearTimeout(this.escalationTimer);
+    this.escalationTimer = undefined;
+  }
+}