@edspencer/paddock 0.0.1 → 0.56.0

package/packages/server/dist/recovery.js

@@ -0,0 +1,490 @@
+/**
+ * Keeper-chat recovery ENGINE — Layer 3 (automatic re-drive) for issue #301.
+ *
+ * ── What it does ──────────────────────────────────────────────────────────────
+ * Phase 0 (recovery-config.ts) defined the config surface and Phase 1 (Layer 2)
+ * shipped the manual "Continue" button. This module is Layer 3: it AUTOMATICALLY
+ * unsticks a keeper whose background task was killed at the turn boundary, with no
+ * human in the loop — the same nudge a human sends by hand (or clicks Continue for),
+ * fired on its own.
+ *
+ * ── How it detects a hang (approach A — post-turn transcript tail) ────────────
+ * The one thing we can rely on (see edspencer/herdctl#374) is that herdctl keeps
+ * the session ALIVE at the turn boundary and the transcript is the source of truth.
+ * So after a SESSION-mode keeper turn completes, {@link RecoveryEngine.armWatch}
+ * tails that session's transcript JSONL for a bounded window:
+ *
+ *   1. A COMPLETED background task emits a follow-up that WAKES the keeper — more
+ *      `assistant` entries append. A KILLED/STOPPED task writes a terminated
+ *      `<task-notification>` (a `user` entry) that wakes NOTHING — no assistant
+ *      entry follows it.
+ *   2. So the hung signature is: the tail ends (logically) with a terminated
+ *      task-notification and NO `assistant` activity after it. That's exactly what
+ *      {@link detectHang} computes by reducing the appended entries in order.
+ *   3. The kill lands ~2–8s AFTER the turn ends, so the watch polls for
+ *      `debounceMs + KILL_GRACE_MS`, and only fires once the notification has sat
+ *      un-answered for the full `debounceMs` quiet window — a keeper that wakes
+ *      itself inside that window resets the pending state and is never poked.
+ *
+ * ── Guards (issue #301) ───────────────────────────────────────────────────────
+ *   - Only fires when the resolved `recovery.autoReDrive` (per-project override
+ *     else instance default) is ON — Layer 3 is opt-in.
+ *   - Per-session `{ lastNudgeAt, retryCount }`: a wedged keeper is re-driven at
+ *     most `maxRetries` times, then left alone (no poke-loop).
+ *   - `debounceMs`: never fires until the notification has been quiet that long.
+ *   - A HUMAN message ({@link RecoveryEngine.onHumanMessage}) clears the session's
+ *     entry, so a genuinely-new later hang re-arms fresh.
+ *
+ * The engine is deliberately narrow + injectable (clock, scheduler, transcript
+ * reader) so the timing-sensitive orchestration is unit-testable without real
+ * timers or a real filesystem — same discipline as the sidecar-store modules.
+ */
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { projectChatsDir } from "./transcripts.js";
+import { isTerminatedTaskStatus, resolveRecoveryConfig } from "./recovery-config.js";
+/** Flatten a transcript message `content` (string, or an array of blocks) to text. */
+function contentText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((b) => {
+        const blk = b;
+        return blk?.type === "text" && typeof blk.text === "string" ? blk.text : "";
+    })
+        .join("");
+}
+/** Extract a `<task-notification>` `<status>` value, or undefined. */
+function notificationStatus(text) {
+    return /<status>([\s\S]*?)<\/status>/.exec(text)?.[1];
+}
+/** True when `text` is a `<task-notification>` carrying a terminated (killed/
+ *  stopped) status — the turn-boundary-kill signature this recovers from. */
+function isTerminatedNotificationText(text) {
+    return text.includes("<task-notification>") && isTerminatedTaskStatus(notificationStatus(text));
+}
+/**
+ * Classify one already-parsed transcript entry as the hang detector sees it.
+ *
+ * A terminated `<task-notification>` reaches the transcript in TWO shapes, and we
+ * must catch both (issue #347):
+ *   - As a materialised `type:"user"` entry — but that only appears once a LATER
+ *     turn flushes the SDK's input queue, often tens of seconds after the kill.
+ *   - At the moment of the kill, as a `type:"queue-operation"` `enqueue` whose
+ *     `content` IS the notification. This is the one that lands inside the watch
+ *     window; missing it (the original bug) let every real hang go undetected.
+ *
+ * A keeper reply is `assistant`; a killed/stopped notification in either shape is
+ * `terminated-notification`; everything else (system lines, attachments, a
+ * `dequeue`, a completed/running notification, plain user text) is `other`.
+ */
+export function classifyEntry(entry) {
+    if (entry.type === "assistant")
+        return "assistant";
+    if (entry.type === "user" && isTerminatedNotificationText(contentText(entry.message?.content))) {
+        return "terminated-notification";
+    }
+    // The kill's notification is delivered to the input queue as an `enqueue`
+    // whose `content` is the `<task-notification>`; a `dequeue` carries no payload.
+    if (entry.type === "queue-operation" && entry.operation === "enqueue") {
+        if (isTerminatedNotificationText(contentText(entry.content)))
+            return "terminated-notification";
+    }
+    return "other";
+}
+/** Extract a `<task-notification>` `<summary>` value (trimmed), or undefined. */
+function notificationSummary(text) {
+    return /<summary>([\s\S]*?)<\/summary>/.exec(text)?.[1]?.trim() || undefined;
+}
+/** The notification payload carried by an entry, whichever shape it took: a
+ *  `user` message's content, or a `queue-operation` enqueue's `content`. */
+function notificationText(entry) {
+    if (entry.type === "user")
+        return contentText(entry.message?.content);
+    if (entry.type === "queue-operation")
+        return contentText(entry.content);
+    return "";
+}
+/**
+ * Parse one raw JSONL line into its {@link TailEvent} plus, for a terminated
+ * notification, its human-readable `<summary>` (used by the live surface frame).
+ * Unparseable/blank → `other`.
+ */
+export function parseTailLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return { event: "other" };
+    let entry;
+    try {
+        entry = JSON.parse(trimmed);
+    }
+    catch {
+        return { event: "other" };
+    }
+    const event = classifyEntry(entry);
+    return event === "terminated-notification"
+        ? { event, summary: notificationSummary(notificationText(entry)) }
+        : { event };
+}
+/** Classify one raw JSONL line (unparseable/blank → `other`). */
+export function classifyLine(line) {
+    return parseTailLine(line).event;
+}
+/**
+ * Reduce an ordered stream of tail events to whether the transcript currently ends
+ * (logically) with an un-answered terminated task-notification — the hung
+ * signature. An `assistant` entry clears any pending notification (the keeper
+ * woke); a terminated notification sets it; `other` entries are inert. True iff a
+ * terminated notification is still pending after the last event.
+ */
+export function detectHang(events) {
+    let pending = false;
+    for (const ev of events) {
+        if (ev === "assistant")
+            pending = false;
+        else if (ev === "terminated-notification")
+            pending = true;
+    }
+    return pending;
+}
+/** Default poll cadence — brisk enough to catch the kill+debounce, cheap enough to ignore. */
+export const DEFAULT_POLL_MS = 750;
+/**
+ * How long past `debounceMs` we keep watching for the kill to land. herdctl#374's
+ * teardown fires ~2–8s after the turn boundary, so the notification can appear late;
+ * this grace ensures its full `debounceMs` quiet window still fits inside the watch.
+ */
+export const DEFAULT_KILL_GRACE_MS = 12_000;
+/**
+ * Cadence (ms) at which a deferred fire re-checks whether the session has gone
+ * idle (issue #397). Brisk enough to fire promptly once the reaper releases,
+ * cheap enough to ignore.
+ */
+export const DEFAULT_SETTLE_POLL_MS = 1_000;
+/**
+ * How long (ms) the engine keeps DEFERRING an otherwise-ready fire while the
+ * session is still live (hub or reaper) before standing down (issue #397). Must
+ * comfortably exceed herdctl's `DEFAULT_REINVOCATION_GRACE_MS` (15s) — the reaper
+ * holds a just-killed-task session live for that grace — plus margin, so the
+ * deferred nudge lands once the reaper reaps rather than giving up early. Bounds
+ * the defer so a session the reaper never releases can't retry forever.
+ */
+export const DEFAULT_SETTLE_WINDOW_MS = 30_000;
+/**
+ * Cheap current size (bytes) of the transcript via `stat` — the arm-time baseline,
+ * so we never slurp a multi-MB transcript just to learn where its EOF is. A missing
+ * file (the turn wrote no transcript yet) → 0, so the watch starts from the top.
+ */
+async function defaultFileSize(file) {
+    try {
+        return (await fsp.stat(file)).size;
+    }
+    catch {
+        return 0;
+    }
+}
+/**
+ * Read the transcript bytes appended since `offset` using a single positioned read
+ * (not a whole-file slurp), so tailing a large transcript stays cheap. A missing
+ * file yields no new text at the same offset (the turn simply never wrote one).
+ */
+async function defaultReadTail(file, offset) {
+    let fh = null;
+    try {
+        fh = await fsp.open(file, "r");
+        const { size } = await fh.stat();
+        if (size <= offset)
+            return { text: "", size };
+        const len = size - offset;
+        const buf = Buffer.allocUnsafe(len);
+        await fh.read(buf, 0, len, offset);
+        return { text: buf.toString("utf8"), size };
+    }
+    catch {
+        return { text: "", size: offset };
+    }
+    finally {
+        await fh?.close().catch(() => undefined);
+    }
+}
+/**
+ * Layer 3 automatic-recovery engine (issue #301). Arm a post-turn transcript watch
+ * after each session-mode keeper turn; if a killed-at-turn-boundary notification
+ * appears with no keeper response, auto-inject a recovery nudge — guarded by
+ * debounce + a per-session retry cap, and cleared when a human next messages.
+ */
+export class RecoveryEngine {
+    deps;
+    now;
+    setTimer;
+    clearTimer;
+    readTail;
+    fileSize;
+    pollMs;
+    killGraceMs;
+    settlePollMs;
+    settleWindowMs;
+    log;
+    surface;
+    isBusy;
+    sdkSessionLive;
+    /** Per-session retry/debounce bookkeeping — cleared on a human message. */
+    guards = new Map();
+    /** In-flight watches keyed by session id — re-arming or a human message cancels one. */
+    watches = new Map();
+    constructor(deps) {
+        this.deps = deps;
+        this.now = deps.now ?? Date.now;
+        this.setTimer = deps.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+        this.clearTimer = deps.clearTimer ?? ((h) => clearTimeout(h));
+        this.readTail = deps.readTail ?? defaultReadTail;
+        this.fileSize = deps.fileSize ?? defaultFileSize;
+        this.pollMs = deps.pollMs ?? DEFAULT_POLL_MS;
+        this.killGraceMs = deps.killGraceMs ?? DEFAULT_KILL_GRACE_MS;
+        this.settlePollMs = deps.settlePollMs ?? DEFAULT_SETTLE_POLL_MS;
+        this.settleWindowMs = deps.settleWindowMs ?? DEFAULT_SETTLE_WINDOW_MS;
+        this.log = deps.log ?? (() => undefined);
+        this.surface = deps.surface ?? (() => undefined);
+        this.isBusy = deps.isBusy ?? (() => false);
+        this.sdkSessionLive = deps.sdkSessionLive ?? (() => false);
+    }
+    /**
+     * Arm (or re-arm) a post-turn watch for a just-completed SESSION-mode keeper turn.
+     * No-op unless SOMETHING wants it for this project: Layer 2 `surfaceKilledTask`
+     * (surface the kill live) or Layer 3 `autoReDrive` (auto re-drive, while the
+     * session has retries left). Re-arming cancels any prior watch for the same
+     * session. Safe to call fire-and-forget; never throws (a lookup/IO failure just
+     * declines to watch).
+     */
+    armWatch(input) {
+        void this.armWatchAsync(input).catch((err) => {
+            this.log("recovery: armWatch failed", { err: String(err), ...input });
+        });
+    }
+    async armWatchAsync({ slug, sessionId }) {
+        let project;
+        try {
+            project = await this.deps.getProject(slug);
+        }
+        catch {
+            return; // unknown/deleted project — nothing to recover
+        }
+        const recovery = resolveRecoveryConfig(project.recovery, this.deps.cfg.recovery);
+        // Two independent actions can want this watch: Layer 2 `surfaceKilledTask`
+        // (push the "keeper is idle" affordance live) and Layer 3 `autoReDrive`
+        // (re-drive automatically). Re-drive is additionally bounded by the retry cap
+        // — each armed watch fires at most once, so gating on `retryCount >= maxRetries`
+        // bounds total auto re-drives to exactly maxRetries (and `maxRetries: 0`
+        // disables it). Surfacing has no such cap: a re-drive that hangs again is a new
+        // event worth showing. If neither wants in, don't arm at all.
+        const retryCount = this.guards.get(sessionId)?.retryCount ?? 0;
+        const wantSurface = recovery.surfaceKilledTask;
+        const wantReDrive = recovery.autoReDrive && retryCount < recovery.maxRetries;
+        if (!wantSurface && !wantReDrive) {
+            this.log("recovery: nothing to arm (surface off, re-drive off or capped)", {
+                slug,
+                sessionId,
+                retryCount,
+                maxRetries: recovery.maxRetries,
+            });
+            return;
+        }
+        // Re-arming supersedes any prior watch for this session.
+        this.cancelWatch(sessionId);
+        const file = path.join(projectChatsDir(project.dir), `${sessionId}.jsonl`);
+        // Baseline = the transcript's current EOF via a cheap `stat` (NOT a full read):
+        // this runs on EVERY session-mode turn once autoReDrive is on, and transcripts
+        // here are multi-MB. Start the tail from EOF so we only ever see entries appended
+        // AFTER this turn (the kill's notification), never a stale one from earlier.
+        let offset = await this.fileSize(file);
+        let carry = "";
+        let pending = false;
+        let pendingSummary;
+        let notifiedAt = null;
+        const deadline = this.now() + recovery.debounceMs + this.killGraceMs;
+        const watch = { timer: null, cancelled: false };
+        this.watches.set(sessionId, watch);
+        const tick = async () => {
+            if (watch.cancelled)
+                return;
+            let tail;
+            try {
+                tail = await this.readTail(file, offset);
+            }
+            catch {
+                tail = { text: "", size: offset };
+            }
+            if (watch.cancelled)
+                return;
+            offset = tail.size;
+            const combined = carry + tail.text;
+            const lines = combined.split("\n");
+            // The last element is an incomplete (unterminated) line — hold it for next read.
+            carry = lines.pop() ?? "";
+            for (const line of lines) {
+                const { event, summary } = parseTailLine(line);
+                if (event === "assistant") {
+                    pending = false;
+                    pendingSummary = undefined;
+                    notifiedAt = null;
+                }
+                else if (event === "terminated-notification" && !pending) {
+                    pending = true;
+                    pendingSummary = summary;
+                    notifiedAt = this.now();
+                }
+            }
+            const t = this.now();
+            if (pending && notifiedAt !== null && t - notifiedAt >= recovery.debounceMs) {
+                // Hung: a terminated notification has sat un-answered for the full debounce.
+                this.cancelWatch(sessionId);
+                await this.fire(project, sessionId, recovery, pendingSummary);
+                return;
+            }
+            if (t >= deadline) {
+                // The turn ended cleanly (no kill) or the keeper woke — stop watching.
+                this.cancelWatch(sessionId);
+                return;
+            }
+            if (!watch.cancelled)
+                watch.timer = this.setTimer(() => void tick(), this.pollMs);
+        };
+        watch.timer = this.setTimer(() => void tick(), this.pollMs);
+    }
+    /**
+     * A detected turn-boundary kill is ready to recover — kick off the fire, giving
+     * it a bounded {@link settleWindowMs} budget to wait out any still-live session.
+     * See {@link fireWhenIdle} for the surface/re-drive actions and the defer guard.
+     */
+    async fire(project, sessionId, recovery, summary) {
+        await this.fireWhenIdle(project, sessionId, recovery, summary, this.now() + this.settleWindowMs);
+    }
+    /**
+     * Handle a detected turn-boundary kill. Two independent, resolved-config-gated
+     * actions, in order:
+     *   1. `surfaceKilledTask` — push the kill to attached clients LIVE so the
+     *      "keeper is idle / Continue" affordance appears without a refresh. Never
+     *      throws; a bad sink can't wedge the engine.
+     *   2. `autoReDrive` (under the retry cap) — bump the session's retry bookkeeping
+     *      FIRST (so a re-drive that itself hangs can't exceed the cap), then inject
+     *      the recovery nudge via the shared Layer 2 path. A failed inject is logged.
+     *
+     * Liveness guard + defer (issues #352 / #397). Two busy signals mean the session
+     * is NOT idle and firing would collide with a live `claude` subprocess:
+     *   - {@link isBusy} (hub) — a live turn PADDOCK itself started (a human message,
+     *     a queued-message drain, or a prior recovery nudge).
+     *   - {@link sdkSessionLive} (reaper) — a subprocess herdctl is keeping alive for
+     *     the just-killed background task, or holding through its ~15s re-invocation
+     *     grace. `isBusy` is BLIND to this, which is what let the auto re-drive fire a
+     *     COMPETING resume and get interrupted (`[Request interrupted by user]`, #397).
+     *
+     * When EITHER is set we must NOT fire — but standing down *permanently* leaves
+     * recovery incomplete: the reaper reaps SILENTLY (no turn completes, so nothing
+     * re-arms a watch), and the user stays stuck. So instead we DEFER: re-check after
+     * {@link settlePollMs} and fire exactly once the session is genuinely idle
+     * (reaper reaped, hub not running). The deferral is bounded by
+     * {@link settleWindowMs} so a session that never releases can't retry forever, and
+     * is tracked in {@link watches} so a completing turn ({@link armWatch}) or a human
+     * message ({@link onHumanMessage}) supersedes/cancels it — no double fire.
+     */
+    async fireWhenIdle(project, sessionId, recovery, summary, settleDeadline) {
+        const hubBusy = this.isBusy(sessionId);
+        const reaperLive = this.sdkSessionLive(sessionId);
+        if (hubBusy || reaperLive) {
+            if (this.now() >= settleDeadline) {
+                // The session never went idle within the settle budget — give up rather
+                // than defer forever. A later genuine hang re-arms a fresh watch.
+                this.log("recovery: session still live at settle deadline — standing down", {
+                    slug: project.slug,
+                    sessionId,
+                    hubBusy,
+                    reaperLive,
+                });
+                return;
+            }
+            // Defer: re-check liveness after the settle poll. Register as a watch so a
+            // fresh armWatch (a completing turn) or a human message cancels this retry.
+            const watch = { timer: null, cancelled: false };
+            this.watches.set(sessionId, watch);
+            watch.timer = this.setTimer(() => {
+                if (watch.cancelled)
+                    return;
+                // Drop this settle-watch from the map before re-attempting; fireWhenIdle
+                // re-registers a fresh one if it still needs to defer.
+                this.cancelWatch(sessionId);
+                void this.fireWhenIdle(project, sessionId, recovery, summary, settleDeadline).catch((err) => {
+                    this.log("recovery: deferred fire failed", { sessionId, err: String(err) });
+                });
+            }, this.settlePollMs);
+            this.log("recovery: session still live (hub or reaper) — deferring nudge until idle", {
+                slug: project.slug,
+                sessionId,
+                hubBusy,
+                reaperLive,
+            });
+            return;
+        }
+        if (recovery.surfaceKilledTask) {
+            try {
+                this.surface(project, sessionId, summary);
+                this.log("recovery: surfaced killed task", { slug: project.slug, sessionId });
+            }
+            catch (err) {
+                this.log("recovery: surface failed", { sessionId, err: String(err) });
+            }
+        }
+        const retryCount = this.guards.get(sessionId)?.retryCount ?? 0;
+        if (!recovery.autoReDrive || retryCount >= recovery.maxRetries)
+            return;
+        const guard = this.guards.get(sessionId) ?? { lastNudgeAt: 0, retryCount: 0 };
+        guard.retryCount += 1;
+        guard.lastNudgeAt = this.now();
+        this.guards.set(sessionId, guard);
+        this.log("recovery: auto re-driving hung keeper", {
+            slug: project.slug,
+            sessionId,
+            retryCount: guard.retryCount,
+            maxRetries: recovery.maxRetries,
+        });
+        try {
+            await this.deps.reDrive(project, sessionId);
+        }
+        catch (err) {
+            this.log("recovery: auto re-drive inject failed", { sessionId, err: String(err) });
+        }
+    }
+    /**
+     * A human just messaged this session — clear its retry/debounce bookkeeping and
+     * cancel any in-flight watch, so a genuinely-new later hang is recovered fresh
+     * (the retry cap counts auto re-drives BETWEEN human messages).
+     */
+    onHumanMessage(sessionId) {
+        this.guards.delete(sessionId);
+        this.cancelWatch(sessionId);
+    }
+    /** Cancel the in-flight watch for a session, if any (idempotent). */
+    cancelWatch(sessionId) {
+        const w = this.watches.get(sessionId);
+        if (!w)
+            return;
+        w.cancelled = true;
+        if (w.timer !== null)
+            this.clearTimer(w.timer);
+        this.watches.delete(sessionId);
+    }
+    /** Cancel every in-flight watch (e.g. on shutdown). */
+    stopAll() {
+        for (const id of [...this.watches.keys()])
+            this.cancelWatch(id);
+    }
+    /** Test/inspection helper: the current retry count for a session (0 if untracked). */
+    retryCountFor(sessionId) {
+        return this.guards.get(sessionId)?.retryCount ?? 0;
+    }
+    /** Test/inspection helper: whether a watch is currently armed for a session. */
+    isWatching(sessionId) {
+        return this.watches.has(sessionId);
+    }
+}

package/packages/server/dist/resume-drain.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Resume self-interrupt fix — drain a stale async-input backlog before the real turn.
+ *
+ * ## The bug this fixes
+ *
+ * When a keeper session is resumed and the `claude` CLI still holds a stale
+ * async-input backlog (leftover `killed`/orphaned `<task-notification>` messages
+ * from background shells/subagents a previous process left running), the CLI's
+ * drain loop replays that backlog as its **own turn**, emitting that turn's
+ * `result` FIRST — ahead of the human/wake/command turn.
+ *
+ * Every resume consumer used to `break` its `for await (const m of session.messages)`
+ * loop on the FIRST `result`. Breaking a `for await` invokes the async generator's
+ * `.return()`, which tears the SDK query / `claude` subprocess down (with only a
+ * ~2s SIGTERM grace). So the backlog turn's result closed the subprocess out from
+ * under the still-running real turn — killing it (`[Request interrupted by user]` /
+ * `interruptedByShutdown:true`, the human message lost). It is intermittent because
+ * it races the real turn against the ~2s teardown grace: a fast reply survives; a
+ * slow (heavy-keeper) reply is killed.
+ *
+ * ## The fix
+ *
+ * {@link consumeResumedTurn} consumes the resumed stream and breaks on a `result`
+ * only once the on-disk async-input queue has DRAINED (depth 0) — i.e. after the
+ * LAST (real) turn, never after a backlog turn. So a backlog turn's result can no
+ * longer tear the real turn down.
+ *
+ * The gate is **dynamic** (the queue depth is probed after each turn's result), not
+ * a one-shot pre-probe. This is deliberate: a backlog can materialize DURING the
+ * resume — a crashed process that left background work running writes no `killed`
+ * notification, so the CLI reconciles those orphans into the queue at resume time,
+ * *after* any pre-open probe would have read 0. Dynamic probing catches both the
+ * already-on-disk residue and the reconciled-at-resume residue.
+ *
+ * Zero added latency when there is no backlog: the real prompt is not enqueued into
+ * the async queue when the CLI is idle, so the queue depth is 0 the moment the first
+ * (and only) turn completes → we break after the first result exactly like before.
+ *
+ * Robustness:
+ * - The per-turn wait is bounded only for the wait for a turn's FIRST message (so a
+ *   not-yet-flushed dequeue can't hang us forever waiting on a backlog turn that
+ *   never arrives). Once a turn starts producing, it is consumed to its `result`
+ *   UNBOUNDED — a slow real turn is never cut off mid-flight.
+ * - An overall deadline is the ultimate safety net.
+ * - A single in-flight `next()` is threaded throughout, so the iterator is never
+ *   advanced twice concurrently.
+ */
+import type { SDKMessage } from "@herdctl/core";
+import type { RuntimeSession } from "@herdctl/core";
+export interface ConsumeResumedTurnOptions {
+    /** Current on-disk async-input-queue depth for this session (0 = drained). */
+    residueProbe: () => Promise<number>;
+    /** Surface a message to the client (translate/emit). */
+    onMessage?: (m: SDKMessage) => void | Promise<void>;
+    /** Called with the session id the moment it first appears in the stream. */
+    onSessionId?: (id: string) => void;
+    /** Overall deadline (ms). Default {@link DEFAULT_DEADLINE_MS}. */
+    deadlineMs?: number;
+    /** Optional trace hook — invoked only when a backlog was actually drained. */
+    log?: (msg: string) => void;
+}
+export interface ConsumeResumedTurnResult {
+    /** True unless the real turn's terminal `result` was an error/`success:false`. */
+    success: boolean;
+    /** The session id seen on the stream, if any. */
+    sessionId: string | null;
+    /**
+     * The live iterator this consume drove, handed back so the caller can KEEP
+     * consuming the SAME stream after the primary turn — without opening a second
+     * iterator over the SDK query (which would split messages unpredictably). Used
+     * by the Gap B background-turn delivery ({@link consumeBackgroundTurns}): the
+     * session is left open by the reaper for in-flight background work, and the
+     * autonomous re-invocation turns it later produces arrive on this iterator.
+     */
+    iterator: AsyncIterator<SDKMessage>;
+    /**
+     * The single in-flight `iterator.next()` left outstanding when we stopped
+     * consuming (awaiting the message AFTER the primary turn's terminal `result`).
+     * Handing it back — rather than dropping it and re-pulling — means no message
+     * between the primary result and the first background re-invocation is lost.
+     */
+    pending: Promise<Step>;
+}
+type Step = IteratorResult<SDKMessage>;
+/**
+ * Consume a resumed session's stream to the caller's real turn, first draining any
+ * stale async-input backlog that replays ahead of it. See the module doc.
+ *
+ * The session must already have the caller's prompt seeded (chatSession opens with
+ * the prompt; runCommand `send`s the command; the wake path is opened with its
+ * prompt by herdctl) — this only governs WHEN we stop consuming, never what runs.
+ */
+export declare function consumeResumedTurn(session: RuntimeSession, opts: ConsumeResumedTurnOptions): Promise<ConsumeResumedTurnResult>;
+/**
+ * Gap B — deliver autonomous background-completion turns.
+ *
+ * After {@link consumeResumedTurn} returns, the primary turn is done but the
+ * session may be held OPEN by the reaper because the turn launched continuous
+ * background work (`decideReap` keepAlives while `backgroundTasks.length > 0`).
+ * The `claude` subprocess keeps running and, when a background task completes,
+ * the SDK hands the parent the result as a fresh autonomous re-invocation turn —
+ * emitted on the SAME message stream. Paddock used to stop consuming at the
+ * primary `result`, so those messages buffered undelivered: the CLI still
+ * PERSISTED the re-invocation to the transcript (the subprocess writes JSONL
+ * directly), but the live UI never saw it until a refresh replayed history.
+ *
+ * This keeps consuming the handed-back {@link ConsumeResumedTurnResult.iterator}
+ * (never a second iterator — that would split the stream), forwarding every
+ * subsequent message to `onMessage`. The caller's `onMessage` renders each
+ * autonomous turn to the hub exactly like the scheduler-wake path does, so it
+ * appears live. Consumption ALSO keeps `tapLifecycleStream` advancing, so the
+ * reaper keeps receiving its mid-turn `activity` / `background_tasks_changed`
+ * signals (they fire as a side effect of the consumer pulling messages) — the
+ * behaviour the reaper was designed around.
+ *
+ * The loop ends cleanly when the reaper reaps the idle session: `close()` ends
+ * the SDK query, the iterator yields `done`, and we return. A stream error is
+ * swallowed (the turn is already over). Detached by the caller (`void`), it
+ * never throws to the event loop.
+ */
+export declare function consumeBackgroundTurns(iterator: AsyncIterator<SDKMessage>, pending: Promise<Step>, onMessage: (m: SDKMessage) => void | Promise<void>, onDone?: () => void | Promise<void>): Promise<void>;
+export {};