/** * Turn-level stall detection (2026-11). * * ── WHY THIS EXISTS: THE AGA AUTOS CHAT INCIDENT ───────────────────────────── * * A chat mention spawned an opencode run. It created the first batch of tasks * and then stopped dead: * * 12:00:37.940 --- step --- <- step_start, the model call begins * ...19 minutes of NOTHING... * 13:19:23 session.stop <- a human pressed Stop * * The child was alive, the daemon was healthy, no tool was running, no shell * was running, no subagent existed. The provider call had simply never * returned a token. The ONLY thing that noticed was the 60-minute idle kill, * and that kill cannot tell this apart from a legitimately long tool call - * which is why it is deliberately patient. * * The idle clock measures "is anything happening anywhere". This module * measures something narrower and much more diagnostic: **is a model turn * open with no output**. OpenCode emits `step_start` when a turn begins and * `step_finish` when it ends; a step that stays open past its budget is a hung * turn, not work. That is the exact signature above. * * ── THE LADDER (cheap fix first, destructive last) ────────────────────────── * * warn log + diagnostic. Names the stall instead of leaving a mystery. * interrupt POST /api/session//interrupt on the shared service. The CLI * usually continues in the SAME session, so the common case costs * nothing and loses no work. * kill the full stop path (interrupt -> revoke relay token -> kill the * tree -> force-end the session -> remove the run scope). Exit 124 * is reused on purpose: `spawn.ts` already treats 124 as OUR * decision and keeps the conversation for a retry. * * ── HARD GUARDS (a watchdog that kills real work is worse than a stall) ───── * * Never act while: * - a relayed MCP call is IN FLIGHT (`inFlight > 0` from the daemon probe), * - a background shell is RUNNING (the agent is waiting on a real command), * - a SUBAGENT produced output recently (child work is real work even when * the parent pipe says nothing). * * The first version of the activity clock learned this the expensive way; the * same discipline applies here, and both guards are inputs rather than * something this module guesses. * * Everything below the class is PURE so the regression can be pinned by a test * with no child process, no service and no clock. */ /** What one stream line says about the turn. */ export type TurnEventKind = 'step_start' | 'step_finish' | 'output'; export interface TurnEvent { kind: TurnEventKind; at: number; /** The opencode step/part id, when the event carries one. */ stepId?: string; } export interface TurnSnapshot { /** When the harness was spawned (the grace window is measured from here). */ spawnedAt: number; /** The step currently open, or null when the model is not in a turn. */ stepId: string | null; /** When that step opened, or null. */ stepOpenedAt: number | null; /** Newest turn event of ANY kind (a streaming token keeps this fresh). */ lastEventAt: number; /** True once the open step has produced a token or a tool call. */ sawFirstToken: boolean; /** Completed steps, for logs and tests. */ steps: number; } /** * One clock per harness invocation, fed by the stream. * * Only opencode emits `step_start`/`step_finish`; on every other harness the * snapshot never opens a step and this watchdog stays inert (the idle kill * remains the backstop there). */ export declare class TurnWatch { private readonly spawnedAt; private stepId; private stepOpenedAt; private lastEventAt; private sawFirstToken; private steps; constructor(now?: number); note(event: TurnEvent): void; snapshot(): TurnSnapshot; } /** * Read one raw harness line (before `formatHarnessEvent`) for a turn signal. * * Deliberately tolerant: an unparseable line, a huge NDJSON fragment split * across pipe chunks, or a harness that emits no step events all answer null * and change nothing. */ export declare function extractTurnEvent(line: string, at?: number): TurnEvent | null; export interface TurnBudgets { /** Log the stall (no action). */ warnMs: number; /** Interrupt the service session (cheap, recoverable). */ interruptMs: number; /** Full stop. Reuses exit 124 so the conversation is kept for a retry. */ killMs: number; /** Never act this soon after spawn (startup and queueing are slow). */ graceMs: number; /** How long a subagent's output counts as "a subagent is active". */ subagentGraceMs: number; /** How long to wait for a session to recover after an interrupt. */ recoverMs: number; } /** * Budgets per mode. * * Conversational turns are short by nature, so a six-minute silence is already * pathological. A build/tool turn can legitimately spend a long time inside * one step, so it gets roughly double - and the kill is always capped by the * run's own idle budget, so this can never outlive the existing backstop. */ export declare function turnBudgets(mode: string | undefined, timeoutMin: number, env?: NodeJS.ProcessEnv): TurnBudgets; export type TurnAction = 'none' | 'warn' | 'interrupt' | 'kill'; export interface TurnVerdict { action: TurnAction; /** Human sentence for the console line - never empty. */ reason: string; /** How long the open step has existed. */ openForMs: number; /** How long since the newest turn event (the streaming signal). */ silentMs: number; } export interface TurnDecisionInput { snapshot: TurnSnapshot; now: number; budgets: TurnBudgets; /** Relayed MCP calls that have not answered yet (daemon probe). */ inFlightMcp: number; /** A background shell in this run's folder is still RUNNING. */ shellRunning: boolean; /** A subagent produced output within `budgets.subagentGraceMs`. */ subagentActive: boolean; /** When this step was interrupted, or null when it never was. */ interruptedAt: number | null; } /** * The turn decision. Pure on purpose: every guard is an input, so a test can * pin "never kill with an active shell" without a machine that has one. */ export declare function decideTurnAction(input: TurnDecisionInput): TurnVerdict;