agent-relay-runner 0.129.11 → 0.129.13

package/src/adapters/claude-status-detectors.ts

@@ -1,5 +1,5 @@
 import { extractClaudeModelUnavailableMessage } from "agent-relay-sdk";
-import type { ProviderStatusUpdate } from "../adapter";
+import type { PaneObservation, ProviderStatusUpdate } from "../adapter";
 import type { ClaudeProbeActivity } from "./claude-session-probe";
 import { buildRateLimitProviderState, parseClaudeRateLimitPane } from "../rate-limit";
 
@@ -16,12 +16,13 @@ import { buildRateLimitProviderState, parseClaudeRateLimitPane } from "../rate-l
 //   readiness (claudePaneLooksReady) breaks if CC renames/removes ALL of: the
 //     "bypass permissions" / "shift+tab to cycle" / "? for shortcuts" footer hints,
 //     the "/effort" hint, or the "Welcome back" / "Claude Code" banner.
-//   busy (claudePaneIsBusy) breaks if CC drops the live "… (<elapsed>" spinner counter
-//     (the cross-version anchor; the "esc to interrupt" hint was already dropped in 2.1.x).
+//   busy (claudePaneIsBusy) breaks if CC drops BOTH the live "… (<elapsed>" spinner
+//     counter and the 2.1.218 "Thought for <elapsed> (ctrl+o to expand)" activity line
+//     (the "esc to interrupt" hint was already dropped in 2.1.x).
 //   FALSE POSITIVES: agent output that literally QUOTES any of these strings (e.g. a
 //     transcript discussing "esc to interrupt", or this very comment shown in a pane)
-//     reads as ready/busy. The activity reconciler gates on the LAST N lines only (the
-//     live footer); direct raw predicates are still used by readiness/wait gates.
+//     reads as ready. Busy checks gate themselves on the LAST N lines (the live
+//     footer), including direct callers such as the prompt-gate guard.
 // History: 18067b5 (busy counter), and the readiness footer-vs-banner fix below.
 export function claudePaneLooksReady(text: string): boolean {
   // Claude's startup banner ("Claude Code" / "Welcome back") scrolls off the pane once the
@@ -44,30 +45,117 @@ export function claudePaneLooksReady(text: string): boolean {
 // (ctrl+o to expand)" truncation marker, the idle input box, or the persistent
 // "/btw … without interrupting Claude's current work" queue hint.
 const CLAUDE_BUSY_SPINNER_RE = /…\s*\((?:\d+h\s+)?(?:\d+m\s+)?\d+s\b/;
+// Claude Code 2.1.218 replaced the gerund spinner during its thinking phase with
+// "Thought for 13s (ctrl+o to expand)" (and, after a tool call starts,
+// "Thought for 12s, called callmux (ctrl+o to expand)"). The intrinsic session
+// probe remains the primary, version-robust activity source, but 2.1.218 can leave
+// that probe idle during this phase. Treat this live footer as a busy veto so a
+// monitorless worker cannot false-idle before its first assistant output.
+const CLAUDE_BUSY_THOUGHT_RE = /^\s*Thought for (?:\d+h\s+)?(?:\d+m\s+)?\d+s(?:,\s*called [^(\n]+)?\s*\(ctrl\+o to expand\)\s*$/im;
 const CLAUDE_ACTIVITY_FOOTER_LINES = 10;
 
 export function claudePaneIsBusy(text: string): boolean {
   // Claude Code <2.1.x rendered "(esc to interrupt)" in the spinner footer; 2.1.x
-  // dropped that hint but kept the "(<elapsed>" counter, which is the stable busy
-  // signal across versions. Match either so the busy probe (and the reconciler
-  // backstop that depends on it) keep working as the footer wording changes.
-  return CLAUDE_BUSY_SPINNER_RE.test(text) || text.includes("esc to interrupt");
+  // dropped that hint. Keep both older signals and the 2.1.218 thinking line so
+  // the pane veto works across those formats. Only inspect the live footer:
+  // completed "Thought for …" rows remain in scrollback after a turn.
+  const footer = claudeActivityFooter(text);
+  return CLAUDE_BUSY_SPINNER_RE.test(footer)
+    || CLAUDE_BUSY_THOUGHT_RE.test(footer)
+    || footer.includes("esc to interrupt");
 }
 
 function claudeActivityFooter(text: string): string {
   return text.split("\n").slice(-CLAUDE_ACTIVITY_FOOTER_LINES).join("\n");
 }
 
-export function claudeActivityFromProbeAndPane(probe: ClaudeProbeActivity | undefined, pane: string): ClaudeProbeActivity {
+// #1588 — persistent TUI chrome that is present at the prompt regardless of whether a
+// conversation is loaded, so it must NEVER be picked as a pre-clear conversation anchor.
+// (Includes the claudePaneLooksReady footer markers plus the box/hint chrome around them.)
+const CLAUDE_CHROME_MARKERS = [
+  "bypass permissions",
+  "shift+tab to cycle",
+  "? for shortcuts",
+  "/effort",
+  "Welcome back",
+  "Claude Code",
+  "esc to interrupt",
+  "ctrl+o to expand",
+  "/btw",
+  "Tip:",
+  "Tips for getting started",
+];
+
+// #1588 — pick a distinctive line from the PRE-clear pane that belongs to the loaded
+// conversation body (not the persistent chrome/footer), so its DISAPPEARANCE after `/clear`
+// is positive evidence the conversation was actually wiped. claudePaneLooksReady alone can't
+// tell "before clear" from "after clear" — its footer markers are present in both — so the
+// self-resume barrier (waitForClaudeClearCommitted) keys off this anchor instead. Returns the
+// longest content-rich, chrome-free line, or undefined when the pane has no such line (e.g. an
+// already-empty conversation) — in which case the clear can't be positively confirmed and the
+// caller falls to continuationDelivered:false so the #1023 backstop covers it.
+export function claudeConversationAnchor(pane: string): string | undefined {
+  let best: string | undefined;
+  for (const raw of pane.split("\n")) {
+    const line = raw.trim();
+    if (line.length < 20) continue;
+    if (CLAUDE_CHROME_MARKERS.some((marker) => line.includes(marker))) continue;
+    // Require substantial alphanumeric content so a box-border / ASCII-art / punctuation
+    // line can never serve as the anchor (those can reappear on the fresh cleared screen).
+    const alnum = (line.match(/[A-Za-z0-9]/g) ?? []).length;
+    if (alnum < 12) continue;
+    if (!best || line.length > best.length) best = line;
+  }
+  return best;
+}
+
+// #1588 — CLEAR-AWARE completion check for the self-resume barrier. The `/clear` keystroke is
+// async in the Claude TUI: submitTextToTmux returns as soon as the keys are typed, and the
+// persistent footer (claudePaneLooksReady) matches the STILL-UNCLEARED pane, so accepting the
+// first ready match let the continuation race the async clear and get wiped (the #1588 window).
+// A clear is treated as COMMITTED only with positive evidence: the pane is (a) not busy (the
+// clear/redraw finished processing), (b) back at the input-ready footer, and (c) no longer shows
+// the pre-clear conversation anchor (the loaded conversation is gone). Any of these missing →
+// NOT committed → keep waiting (and, on timeout, the caller reports continuationDelivered:false
+// so the backstop re-injects — uncertainty resolves toward the backstop, never toward a wipe).
+export function claudeClearCommitted(preClearAnchor: string | undefined, currentPane: string): boolean {
+  if (claudePaneIsBusy(currentPane)) return false;
+  if (!claudePaneLooksReady(currentPane)) return false;
+  if (!preClearAnchor) return false;
+  return !currentPane.includes(preClearAnchor);
+}
+
+export interface ClaudeActivityReadOptions {
+  /** #1621: the probe's busy assertion has not been rewritten inside its trust window
+   *  (claudeProbeBusyIsStale), so it may describe a turn that was cancelled out of band. */
+  probeBusyStale?: boolean;
+}
+
+export function claudeActivityFromProbeAndPane(
+  probe: ClaudeProbeActivity | undefined,
+  pane: string,
+  opts: ClaudeActivityReadOptions = {},
+): ClaudeProbeActivity {
   const footer = claudeActivityFooter(pane);
-  if (probe === "busy" || claudePaneIsBusy(footer)) return "busy";
-  if (claudePaneLooksReady(footer)) return "idle";
+  // The pane's activity footer is the strongest busy evidence there is and always wins.
+  if (claudePaneIsBusy(footer)) return "busy";
+  const ready = claudePaneLooksReady(footer);
+  if (probe === "busy") {
+    // A FRESH probe-busy stays authoritative: shell→busy is exactly the idle-while-working
+    // read the pane-scrape gets wrong (#766). A STALE one cannot be falsified by the probe
+    // itself — Claude Code writes the file only on a transition, and an out-of-band cancel
+    // makes no transition (#1621) — so the pane must corroborate it. Only a positively
+    // input-ready footer (the prompt box, no activity marker) may overrule it; a
+    // shelled-out full-screen pane or an unreadable capture keeps the turn busy.
+    return opts.probeBusyStale && ready ? "idle" : "busy";
+  }
+  if (ready) return "idle";
   return probe === "idle" ? "unknown" : probe ?? "unknown";
 }
 
 // #286: detect the subscription usage-limit modal in the pane and turn it into the
 // provider-neutral rate-limit hold (idle + blocked) that the relay's resume sweep lifts
-// at reset. Mirrors claudeModelUnavailableStatus, but non-terminal (idle, not error).
+// at reset. Unlike the pane model-rejection observation below, it remains a legacy status path.
 export function claudeRateLimitStatus(text: string, sessionName?: string): ProviderStatusUpdate | null {
   const parsed = parseClaudeRateLimitPane(text);
   if (!parsed) return null;
@@ -83,78 +171,122 @@ export function claudeRateLimitStatus(text: string, sessionName?: string): Provi
   };
 }
 
-// #769 — detect the API connection-retry banner in the live terminal footer and surface a
-// transient blocked hold (non-terminal, clears on recovery). Three stable anchors from the
-// banner text: "Unable to connect to API", "Retrying in <N>s", "attempt <N>/<M>".
-// Gated on the LAST N lines so agent output that merely QUOTES these strings (e.g. quoting
-// this comment, or a discussion of retry logic) doesn't false-positive — the live banner
-// always lives in the footer; quoted strings appear in the scrollback body.
-// Break condition: if CC renames/removes any anchor substring the detector stops firing and
-// sessions return to idle/available — a fast fix once the new footer wording is known.
+// #769 — detect the API connection-retry banner in the live terminal footer. Three stable
+// anchors from the banner text: "Unable to connect to API", "Retrying in <N>s",
+// "attempt <N>/<M>". Gated on the LAST N lines so agent output that merely QUOTES these
+// strings (e.g. quoting this comment, or a discussion of retry logic) doesn't false-positive —
+// the live banner always lives in the footer; quoted strings appear in the scrollback body.
+// Break condition: if CC renames/removes any anchor substring the detector stops firing — a
+// fast fix once the new footer wording is known, and one with no correctness consequence now
+// that this is advisory.
+//
+// #1651 — this returns a DIAGNOSTIC, not a status. It used to return
+// `status: "idle"` + `clear: ["subagent"]` + a blocked `conn_retry` providerState. The runner
+// treats an idle provider-turn as the turn ENDING (runner-core setProviderStatus), which
+// clears the work record and calls completeObservedTaskClaims(): retry chrome rendered in a
+// pane could therefore COMPLETE THE TASK CLAIMS OF A TURN THAT WAS STILL RUNNING. The footer
+// gate did not prevent this — the banner is genuinely in the footer during a live turn, which
+// is exactly when the detector fired.
+//
+// The turn stays live/unknown throughout the retries. Claude's own retry ladder is long
+// (measured at 179s for a refused connection), but lateness is not permission to infer failure
+// from pane text: only a correlated StopFailure may end the turn, after the native ladder
+// exhausts. Disappearance likewise proves nothing — it only clears the diagnostic flag.
 const CLAUDE_CONN_RETRY_FOOTER_LINES = 10;
 const CLAUDE_CONN_RETRY_ANCHOR_RE = /Unable to connect to API/;
 const CLAUDE_CONN_RETRY_RATE_RE = /Retrying in \d+s/;
 const CLAUDE_CONN_RETRY_ATTEMPT_RE = /attempt \d+\/\d+/;
 
-export function claudeConnectionRetryStatus(text: string, sessionName?: string): ProviderStatusUpdate | null {
+export function claudeConnectionRetryObservation(text: string, sessionName?: string, nowMs?: number): PaneObservation | null {
   const footer = text.split("\n").slice(-CLAUDE_CONN_RETRY_FOOTER_LINES).join("\n");
   if (
     !CLAUDE_CONN_RETRY_ANCHOR_RE.test(footer) ||
     !CLAUDE_CONN_RETRY_RATE_RE.test(footer) ||
     !CLAUDE_CONN_RETRY_ATTEMPT_RE.test(footer)
   ) return null;
-  const now = Date.now();
   return {
-    status: "idle",
-    clear: ["subagent"],
-    providerState: {
-      state: "blocked",
-      reason: "conn_retry",
-      kind: "conn_retry",
-      label: "connection degraded · retrying",
-      message: "Claude cannot reach the Anthropic API and is retrying the connection.",
-      source: sessionName ? `claude-pane:${sessionName}` : "claude-pane",
-      terminal: false,
-      recommendedAction: "Holding; agent-relay will clear this state once the session reconnects.",
-      enteredAt: now,
-      updatedAt: now,
-    },
+    eventType: "claude.pane_connection_retry_candidate",
+    source: "pane",
+    detectorId: "connection-retry",
+    observedAt: nowMs ?? Date.now(),
+    ...(sessionName ? { sessionName } : {}),
+    message: "Pane shows Claude's API connection-retry banner. Advisory only: the turn is unchanged.",
+  };
+}
+
+/** The falling edge. It used to publish a bare `idle` — an unconditional turn-end with no
+ *  evidence behind it at all. A banner leaving the footer proves nothing about the turn, so
+ *  this is a diagnostic too: it clears the caller's flag and says so. */
+export function claudeConnectionRetryClearedObservation(sessionName?: string, nowMs?: number): PaneObservation {
+  return {
+    eventType: "claude.pane_connection_retry_cleared",
+    source: "pane",
+    detectorId: "connection-retry",
+    observedAt: nowMs ?? Date.now(),
+    ...(sessionName ? { sessionName } : {}),
+    message: "Pane no longer shows the connection-retry banner. Advisory only: proves nothing about the turn.",
   };
 }
 
-export function claudeModelUnavailableStatus(text: string, sessionName?: string): ProviderStatusUpdate | null {
-  const message = extractClaudeModelUnavailableMessage(text);
+// #1651 — this returns a DIAGNOSTIC, not a status. It used to return `status: "error"` +
+// `clear: ["provider-turn", "subagent"]` + a TERMINAL failed provider state + suppressed
+// restart from a single pane match — reproduced live: the harmless sentence "The test fixture
+// says: not an available model" triggered every one of those, from a pane, where the matched
+// text may simply be an agent quoting a fixture, a code comment, or this very file.
+//
+// A pane match is never terminal. Only a correlated StopFailure whose native error type
+// explicitly denotes model-not-found/unavailable (not yet wired — see #1651's Direction
+// section) may end a turn this way. This detector only notices.
+//
+// Scoped to the trailing modal/composer structural block: the same positional technique
+// rate-limit.ts's livePaneBlock uses (Claude Code pins its composer to the bottom of the
+// screen, separated from the conversation by a blank row, and draws blocking dialogs in that
+// same spot), reimplemented locally rather than importing that module's private helper. An
+// agent's own scrollback quoting/discussing the rejection text sits above the blank row and
+// so can never reach this scan.
+//
+// Repetition is the caller's job, not this function's: claude.ts requires the SAME message on
+// two consecutive polls before it will even publish the diagnostic — this stays pure so it can
+// be unit tested without threading adapter state through it.
+export function claudeModelUnavailableObservation(text: string, sessionName?: string, nowMs?: number): PaneObservation | null {
+  const block = trailingStructuralBlock(text);
+  const message = extractClaudeModelUnavailableMessage(block);
   if (!message) return null;
   return {
-    status: "error",
-    clear: ["provider-turn", "subagent"],
-    providerState: {
-      state: "failed",
-      reason: "model-unavailable",
-      message,
-      source: "claude-pane",
-      terminal: true,
-      ...(sessionName ? { sessionName } : {}),
-      recommendedAction: "Choose a different Claude model before restarting this agent.",
-    },
-    metadata: {
-      terminalFailureReason: "model-unavailable",
-      terminalFailureMessage: message,
-    },
-    timeline: {
-      status: "provider.restart_decision",
-      id: `provider-model-unavailable-${Date.now()}`,
-      timestamp: Date.now(),
-      title: "Provider restart skipped",
-      body: message,
-      icon: "ti-player-stop",
-      metadata: {
-        eventType: "provider.restart_decision",
-        decision: "stop-surface",
-        reason: "model-unavailable",
-        modelUnavailable: true,
-        modelUnavailableMessage: message,
-      },
-    },
+    eventType: "claude.pane_model_unavailable_candidate",
+    source: "pane",
+    detectorId: "model-unavailable",
+    observedAt: nowMs ?? Date.now(),
+    ...(sessionName ? { sessionName } : {}),
+    message,
   };
 }
+
+export interface ClaudeModelUnavailableObservationState {
+  message?: string;
+  reported: boolean;
+}
+
+export function initialClaudeModelUnavailableObservationState(): ClaudeModelUnavailableObservationState {
+  return { reported: false };
+}
+
+/** Require two identical reads before a pane candidate reaches diagnostic telemetry. */
+export function debounceClaudeModelUnavailableObservation(
+  observation: PaneObservation | null,
+  state: ClaudeModelUnavailableObservationState,
+): { state: ClaudeModelUnavailableObservationState; observation?: PaneObservation } {
+  if (!observation?.message) return { state: initialClaudeModelUnavailableObservationState() };
+  if (state.message !== observation.message) return { state: { message: observation.message, reported: false } };
+  if (state.reported) return { state };
+  return { state: { ...state, reported: true }, observation };
+}
+
+function trailingStructuralBlock(text: string): string {
+  const lines = text.split(/\r?\n/);
+  let end = lines.length;
+  while (end > 0 && lines[end - 1]!.trim() === "") end--;
+  let start = end;
+  while (start > 0 && lines[start - 1]!.trim() !== "") start--;
+  return lines.slice(start, end).join("\n");
+}

package/src/adapters/claude-tmux.ts

@@ -9,8 +9,9 @@ import { chmodSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { sanitizeFsName } from "agent-relay-sdk/fs-name";
 import { shellEscape as shellQuote } from "agent-relay-sdk/shell-utils";
-import { tmuxCommand, tmuxHasSession } from "agent-relay-sdk/tmux-utils";
-import { claudePaneLooksReady } from "./claude-status-detectors";
+import { TMUX_SESSION_OWNER_OPTION, tmuxCommand, tmuxHasSession } from "agent-relay-sdk/tmux-utils";
+import { claudeClearCommitted, claudeConversationAnchor, claudePaneLooksReady } from "./claude-status-detectors";
+import { tmuxOwnerIdFromEnv } from "../config";
 import { launcherGatePathForSession, launcherScriptPathForSession } from "../session-scratch";
 
 export const CLAUDE_TMUX_SUBMIT_DELAY_MS = 250;
@@ -24,6 +25,13 @@ export function tmuxSessionName(prefix: string, instanceId: string, label?: stri
   return `${prefix}-${instanceId.slice(0, 8)}`;
 }
 
+// tmux silently rewrites `.` and `:` in new session names to `_` (a colon also
+// separates the session/window/pane portions of a target). All later `-t` lookups
+// must use the rendered name or `has-session` misses the session tmux just created.
+export function tmuxSessionTargetName(sessionName: string): string {
+  return sessionName.replace(/[.:]/g, "_");
+}
+
 export function tmuxSocketName(sessionName: string): string {
   // `tmux -L` puts this value at <TMUX_TMPDIR>/tmux-<uid>/<socket>. Unix
   // socket paths are limited to roughly 104-108 bytes, so a display-oriented
@@ -44,13 +52,14 @@ export function legacyTmuxSocketName(sessionName: string): string {
 }
 
 export function createOrReuseTmuxSession(sessionName: string, socketName: string, tmuxArgs: string[]): void {
-  Bun.spawnSync(tmuxCommand(socketName, "kill-session", "-t", sessionName), {
+  const targetSessionName = tmuxSessionTargetName(sessionName);
+  Bun.spawnSync(tmuxCommand(socketName, "kill-session", "-t", targetSessionName), {
     stdin: "ignore", stdout: "ignore", stderr: "ignore",
   });
   // Upgrade cleanup: a pre-#1353 runner used the readable session name as its
   // selector. Best-effort removal prevents a legacy pane surviving beside its
   // replacement; an overlong legacy selector can fail here harmlessly.
-  Bun.spawnSync(tmuxCommand(legacyTmuxSocketName(sessionName), "kill-session", "-t", sessionName), {
+  Bun.spawnSync(tmuxCommand(legacyTmuxSocketName(sessionName), "kill-session", "-t", targetSessionName), {
     stdin: "ignore", stdout: "ignore", stderr: "ignore",
   });
   const result = Bun.spawnSync(tmuxCommand(socketName, ...tmuxArgs), {
@@ -59,10 +68,37 @@ export function createOrReuseTmuxSession(sessionName: string, socketName: string
   const stderr = result.stderr.toString().trim();
   // A restart can race a still-live predecessor. Reuse the uniquely named,
   // confirmed session rather than failing the healthy agent on "duplicate".
-  const reusable = /duplicate session/i.test(stderr) && tmuxHasSession(sessionName, socketName);
+  const reusable = tmuxSessionCreationFailureIsReusable(stderr, targetSessionName, socketName);
   if (result.exitCode !== 0 && !reusable) {
     throw new Error(`tmux session creation failed: ${stderr || `exit code ${result.exitCode}`}`);
   }
+  // #1514 — stamp the owning orchestrator's state-home id (passed to this runner via
+  // env) onto the session so the orchestrator's wedged-session reaper reaps ONLY the
+  // sessions it positively owns, never a co-tenant orchestrator's on the same host.
+  setTmuxSessionOwner(targetSessionName, tmuxOwnerIdFromEnv(), socketName);
+}
+
+export function tmuxSessionCreationFailureIsReusable(
+  stderr: string,
+  sessionName: string,
+  socketName: string,
+  hasSession: (session: string, socket?: string) => boolean = tmuxHasSession,
+): boolean {
+  return /duplicate session/i.test(stderr)
+    && hasSession(tmuxSessionTargetName(sessionName), socketName);
+}
+
+// #1514 — stamp the owning orchestrator's state-home id onto the tmux session as a
+// user-option. The orchestrator's wedged-session reaper reads it back and reaps ONLY
+// sessions whose owner id matches its own, so it can never reap a session belonging
+// to a different orchestrator that happens to share the UID + tmux prefix on this
+// host. Best-effort: a failure just leaves the session untagged, which the reaper
+// treats as "not positively owned" and skips (fail-safe).
+export function setTmuxSessionOwner(sessionName: string, ownerId: string | undefined, socketName?: string): void {
+  if (!ownerId) return;
+  Bun.spawnSync(tmuxCommand(socketName, "set-option", "-t", sessionName, TMUX_SESSION_OWNER_OPTION, ownerId), {
+    stdin: "ignore", stdout: "ignore", stderr: "ignore",
+  });
 }
 
 export function tmuxSocketPath(socketName: string, socketDir = defaultTmuxSocketDir()): string {
@@ -107,6 +143,14 @@ export function captureTmuxPane(sessionName: string, socketName?: string): strin
   return result.stdout.toString();
 }
 
+// #1514's exit-dialog confirmation used to live here as
+// `confirmClaudeExitDialogIfPresent(sessionName, socketName)` — an Enter writer that
+// any caller holding a session name could invoke. #1647 removed it: taking a session
+// name meant nothing in the type system stopped a pane detector from calling it, and
+// the production kill was exactly that Enter answering an "Exit anyway" modal on a
+// live pane. It now lives in ./claude-exit, where both it and the `/exit` writer take
+// an unforgeable one-shot ClaudeExitGrant instead.
+
 export async function waitForClaudeInputReady(sessionName: string, timeoutMs = CLAUDE_TMUX_READY_TIMEOUT_MS, socketName?: string): Promise<void> {
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
@@ -117,6 +161,51 @@ export async function waitForClaudeInputReady(sessionName: string, timeoutMs = C
   throw new Error(`Claude input was not ready within ${timeoutMs}ms`);
 }
 
+export const CLAUDE_CLEAR_COMMIT_POLL_MS = 200;
+
+// Injectable seams so the polling loop (which otherwise only talks to a live tmux server) is
+// unit-testable — same pattern as confirmTmuxSessionGone's `hasSession` override.
+export interface ClaudeClearCommitDeps {
+  capture?: (sessionName: string, socketName?: string) => string;
+  hasSession?: (sessionName: string, socketName?: string) => boolean;
+  sleep?: (ms: number) => Promise<unknown>;
+}
+
+// #1588 — CLEAR-AWARE settle barrier for the self-resume clear+inject coupling. Unlike
+// waitForClaudeInputReady (which returns on the first persistent-footer match — present BOTH
+// before and after `/clear`, the F2 race), this requires POSITIVE evidence the `/clear` actually
+// committed: it snapshots a distinctive pre-clear conversation anchor and only reports success
+// once the pane is idle, input-ready, AND that anchor is gone (the loaded conversation was wiped).
+// Returns a BOOLEAN rather than throwing: `true` = clear positively confirmed committed; `false` =
+// timed out / session vanished / capture failed / no anchor derivable (uncertain). The caller MUST
+// treat `false` as "not confirmed" and report continuationDelivered:false so the #1023 backstop
+// re-injects — never as a wipe. A settle timeout is therefore surfaced, not swallowed.
+export async function waitForClaudeClearCommitted(
+  sessionName: string,
+  preClearPane: string,
+  timeoutMs = CLAUDE_TMUX_READY_TIMEOUT_MS,
+  socketName?: string,
+  deps: ClaudeClearCommitDeps = {},
+): Promise<boolean> {
+  const capture = deps.capture ?? captureTmuxPane;
+  const hasSession = deps.hasSession ?? tmuxHasSession;
+  const sleep = deps.sleep ?? Bun.sleep;
+  const anchor = claudeConversationAnchor(preClearPane);
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!hasSession(sessionName, socketName)) return false;
+    let pane: string;
+    try {
+      pane = capture(sessionName, socketName);
+    } catch {
+      return false;
+    }
+    if (claudeClearCommitted(anchor, pane)) return true;
+    await sleep(CLAUDE_CLEAR_COMMIT_POLL_MS);
+  }
+  return false;
+}
+
 function pasteTextIntoTmux(sessionName: string, text: string, socketName?: string): void {
   const bufferName = `agent-relay-${crypto.randomUUID()}`;
   const setResult = Bun.spawnSync(tmuxCommand(socketName, "set-buffer", "-b", bufferName, text), {

package/src/adapters/claude-transcript-tail.ts

@@ -14,6 +14,11 @@ interface TailFingerprint {
   bytes: Buffer;
 }
 
+interface TranscriptTailFs {
+  stat: typeof stat;
+  open: typeof open;
+}
+
 export interface IncrementalTranscriptPollResult {
   available: boolean;
   changed: boolean;
@@ -29,10 +34,12 @@ export class IncrementalClaudeTranscriptTail {
   private fingerprint: TailFingerprint | undefined;
   private readonly accumulator = new LatestTurnStepAccumulator();
 
+  constructor(private readonly fs: TranscriptTailFs = { stat, open }) {}
+
   async poll(path: string): Promise<IncrementalTranscriptPollResult> {
     let fileStat: Awaited<ReturnType<typeof stat>>;
     try {
-      fileStat = await stat(path);
+      fileStat = await this.fs.stat(path);
     } catch {
       return this.result({ available: false, changed: false, reset: false });
     }
@@ -54,7 +61,14 @@ export class IncrementalClaudeTranscriptTail {
     const length = fileStat.size - this.offset;
     const buffer = Buffer.alloc(length);
     let bytesRead = 0;
-    const handle = await open(path, "r");
+    // A transcript can be rotated after stat() but before open(). That is ordinary lifecycle
+    // churn, not a runner-fatal error: report this poll as unavailable and retry next interval.
+    let handle: Awaited<ReturnType<typeof open>>;
+    try {
+      handle = await this.fs.open(path, "r");
+    } catch {
+      return this.result({ available: false, changed: false, reset });
+    }
     try {
       const read = await handle.read(buffer, 0, length, this.offset);
       bytesRead = read.bytesRead;
@@ -80,7 +94,12 @@ export class IncrementalClaudeTranscriptTail {
   private async fingerprintMatches(path: string): Promise<boolean> {
     if (!this.fingerprint) return true;
     const buffer = Buffer.alloc(this.fingerprint.bytes.length);
-    const handle = await open(path, "r");
+    let handle: Awaited<ReturnType<typeof open>>;
+    try {
+      handle = await this.fs.open(path, "r");
+    } catch {
+      return false;
+    }
     try {
       const read = await handle.read(buffer, 0, buffer.length, this.fingerprint.offset);
       return read.bytesRead === buffer.length && buffer.equals(this.fingerprint.bytes);