agent-relay-runner 0.101.1 → 0.102.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.101.1",
+  "version": "0.102.0",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-relay-runner",
   "description": "Thin Agent Relay runner bridge for Claude Code",
-  "version": "0.101.1",
+  "version": "0.102.0",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/adapter.ts

@@ -174,6 +174,11 @@ export interface ProviderAdapter {
   // turn was interrupted from the web terminal so no Stop hook fired). "unknown"
   // means the provider can't be cheaply probed and the reconciler should defer.
   probeActivity?(process: ManagedProcess): Promise<"busy" | "idle" | "unknown">;
+  // #769 P1-A: an independent "is the provider still visibly busy?" read, consulted
+  // ONLY as a veto at the reconciler's force-clear moment — a probeActivity()=idle
+  // must not clear a live turn while this returns true (defense-in-depth when the
+  // primary probe can momentarily read idle mid-turn, e.g. a connection retry).
+  probePaneBusy?(process: ManagedProcess): Promise<boolean>;
   terminalAttachSpec?(process: ManagedProcess): Promise<TerminalAttachSpec>;
   respondToPermissionDecision?(process: ManagedProcess, input: ProviderPermissionDecisionInput): Promise<Record<string, unknown> | void>;
   // `options.readyTimeoutMs` lets the runner widen the provider-ready wait for the

package/src/adapters/claude-session-probe.ts

@@ -0,0 +1,225 @@
+// #766/#768 — Claude Code's intrinsic, machine-readable session probe.
+//
+// Claude Code ≥2.1.119 writes `$CLAUDE_CONFIG_DIR/sessions/<pid>.json` and rewrites
+// it on every status transition. It carries an authoritative `status` field
+// (busy|shell|idle|waiting, plus `waitingFor` when waiting) — the very
+// "machine-readable ready/busy signal" the old pane-scrape comment claimed didn't
+// exist. The runner manages the claude pid and its CLAUDE_CONFIG_DIR, so this is a
+// direct keyed read — no enumeration, no cwd/solo-multi disambiguation.
+//
+// This is the single home (DRY) for reading + version-gating + mapping that probe.
+// `probeActivity`, the BusyReconciler backstop, and the monitorless turn-watch all
+// delegate here; the legacy pane-scrape stays only as the graceful fallback for
+// pre-2.1.119 / probe-missing sessions (e.g. a claude-rig host whose real config
+// home the runner can't resolve). Schema is reverse-engineered (pbauermeister/
+// claude-busy-monitor), so we gate on `version`/presence and degrade gracefully if
+// Anthropic ever drifts it.
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { isPidAlive } from "agent-relay-sdk/process-utils";
+import { tmuxCommand } from "agent-relay-sdk/tmux-utils";
+
+/** Raw probe status; "unknown" = absent / unparseable / version-gated out. */
+export type ClaudeProbeStatus = "busy" | "shell" | "idle" | "waiting" | "unknown";
+
+/** The 3-valued activity the reconciler + monitorless turn-watch consume. */
+export type ClaudeProbeActivity = "busy" | "idle" | "unknown";
+
+/** First Claude Code version that writes the session probe. Below this → fallback. */
+export const CLAUDE_PROBE_MIN_VERSION = "2.1.119";
+
+export interface ClaudeSessionReading {
+  /** Raw probe status, or "unknown" when the probe is absent/old/unparseable. */
+  status: ClaudeProbeStatus;
+  /** `waitingFor` reason when status==="waiting" (e.g. "approve Bash"), else null. */
+  waitingFor: string | null;
+  /** Probe `version`, or null when unavailable. */
+  version: string | null;
+  /** `procStart` (process start-time token, == `/proc/<pid>/stat` field 22), or null. */
+  procStart: string | null;
+  /** `updatedAt` epoch-ms of the last probe write, or null. */
+  updatedAt: number | null;
+  /** True iff a present, parseable, version-gated probe produced `status`. */
+  available: boolean;
+}
+
+const UNAVAILABLE: ClaudeSessionReading = { status: "unknown", waitingFor: null, version: null, procStart: null, updatedAt: null, available: false };
+
+/**
+ * Process-liveness seam for the staleness guard (#769 P1-B), injectable in tests.
+ *   procStartOf — the start-time token of a LIVE pid (to compare against the probe's
+ *     `procStart`), or null when the pid is dead/unreadable. Catches both a frozen
+ *     probe from a SIGKILLed claude AND a sub-second pid-reuse window (a reused pid
+ *     has a different start time).
+ *   pidAlive — liveness fallback for probes that predate `procStart`.
+ */
+export interface ClaudeProbeLiveness {
+  procStartOf(pid: number): string | null;
+  pidAlive(pid: number): boolean;
+}
+
+// Default (Linux /proc) liveness. `procStart` in the probe is `/proc/<pid>/stat`
+// field 22 (starttime, clock-ticks since boot) — verified equal live on CC 2.1.193.
+// NB: we deliberately do NOT gate on `updatedAt` freshness — Claude only rewrites
+// the probe on a status *transition*, so a legitimately busy turn keeps a frozen
+// `updatedAt` for its whole duration (verified: a 90s+ busy turn never rewrote it).
+// A staleness threshold would force a long busy turn back to the pane-scrape and
+// reintroduce the #766 idle-while-working bug; pid-liveness + procStart cover the
+// SIGKILL-frozen and pid-reuse cases without that hazard.
+const DEFAULT_LIVENESS: ClaudeProbeLiveness = {
+  procStartOf: readProcStartTime,
+  pidAlive: isPidAlive,
+};
+
+function readProcStartTime(pid: number): string | null {
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    // comm (field 2) is parenthesized and may contain spaces — slice past the last
+    // ')' so the remaining whitespace split starts cleanly at field 3 (state).
+    const after = stat.slice(stat.lastIndexOf(")") + 1).trim();
+    const fields = after.split(/\s+/);
+    return fields[19] ?? null; // field 22 (starttime) = index 19 after dropping pid+comm
+  } catch {
+    return null;
+  }
+}
+
+/** The per-session probe path the runner reads directly (keyed by claude's pid). */
+export function claudeSessionProbePath(configHome: string, pid: number): string {
+  return join(configHome, "sessions", `${pid}.json`);
+}
+
+/** Dotted-version compare; true iff `version` >= `min`. Missing/non-numeric → gate closed. */
+export function claudeVersionAtLeast(version: string | null | undefined, min: string): boolean {
+  if (!version) return false;
+  const actual = version.split(".");
+  const wanted = min.split(".");
+  for (let i = 0; i < wanted.length; i++) {
+    const x = Number.parseInt(actual[i] ?? "0", 10);
+    const y = Number.parseInt(wanted[i] ?? "0", 10);
+    if (Number.isNaN(x)) return false; // unparseable build → fall back, don't trust the probe
+    if (x !== y) return x > y;
+  }
+  return true;
+}
+
+function normalizeStatus(value: unknown): ClaudeProbeStatus {
+  switch (value) {
+    case "busy":
+    case "shell":
+    case "idle":
+    case "waiting":
+      return value;
+    default:
+      return "unknown";
+  }
+}
+
+/** Pure: parse a probe JSON body + version-gate it. Malformed / old / unknown status → unavailable. */
+export function parseClaudeSessionProbe(raw: string, minVersion = CLAUDE_PROBE_MIN_VERSION): ClaudeSessionReading {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return UNAVAILABLE;
+  }
+  if (!parsed || typeof parsed !== "object") return UNAVAILABLE;
+  const probe = parsed as Record<string, unknown>;
+  const version = typeof probe.version === "string" ? probe.version : null;
+  const procStart = typeof probe.procStart === "string" ? probe.procStart : null;
+  const updatedAt = typeof probe.updatedAt === "number" ? probe.updatedAt : null;
+  if (!claudeVersionAtLeast(version, minVersion)) return { ...UNAVAILABLE, version, procStart, updatedAt };
+  const status = normalizeStatus(probe.status);
+  if (status === "unknown") return { status: "unknown", waitingFor: null, version, procStart, updatedAt, available: false };
+  const waitingFor = typeof probe.waitingFor === "string" && probe.waitingFor.trim() ? probe.waitingFor : null;
+  return { status, waitingFor, version, procStart, updatedAt, available: true };
+}
+
+/**
+ * Read + parse the probe for `pid` under `configHome`. Missing file (older CC, a
+ * config home the runner can't resolve, or claude not yet started) → unavailable,
+ * so the caller falls back to the pane-scrape. Sync: the file is a few hundred
+ * bytes and both call sites (4s reconcile poll, 1.5s monitorless tick) are timers.
+ */
+export function readClaudeSessionStatus(
+  configHome: string,
+  pid: number,
+  opts: { minVersion?: string; liveness?: ClaudeProbeLiveness } = {},
+): ClaudeSessionReading {
+  let raw: string;
+  try {
+    raw = readFileSync(claudeSessionProbePath(configHome, pid), "utf8");
+  } catch {
+    return UNAVAILABLE;
+  }
+  const reading = parseClaudeSessionProbe(raw, opts.minVersion ?? CLAUDE_PROBE_MIN_VERSION);
+  if (!reading.available) return reading;
+  // #769 P1-B: a frozen probe from a SIGKILLed claude (or a reused pid) would report
+  // a stale busy/shell forever. Verify the pid still belongs to the same process.
+  const live = opts.liveness ?? DEFAULT_LIVENESS;
+  if (reading.procStart) {
+    if (live.procStartOf(pid) !== reading.procStart) return { ...reading, status: "unknown", available: false };
+  } else if (!live.pidAlive(pid)) {
+    return { ...reading, status: "unknown", available: false };
+  }
+  return reading;
+}
+
+/**
+ * Resolve the claude pid for the session probe (#766/#768): a directly-spawned
+ * process exposes it; a tmux-managed (headless) claude is the pane's process —
+ * buildTmuxArgs runs `bash launcher.sh` whose launcher `exec`s claude, so the pane
+ * pid IS the claude pid (verified live: pane_pid → sessions/<pid>.json). undefined
+ * when neither is available, which routes the caller to the pane-scrape fallback.
+ */
+export function resolveClaudePid(directPid: number | undefined, tmuxSession?: string, tmuxSocket?: string): number | undefined {
+  if (typeof directPid === "number" && directPid > 0) return directPid;
+  if (!tmuxSession) return undefined;
+  const result = Bun.spawnSync(tmuxCommand(tmuxSocket, "display-message", "-p", "-t", tmuxSession, "-F", "#{pane_pid}"), {
+    stdin: "ignore", stdout: "pipe", stderr: "ignore",
+  });
+  if (result.exitCode !== 0) return undefined;
+  const pid = Number.parseInt(result.stdout.toString().trim(), 10);
+  return Number.isFinite(pid) && pid > 0 ? pid : undefined;
+}
+
+/**
+ * Resolve the managed claude's config home + pid, then read the probe. The runner
+ * knows the config home (CLAUDE_CONFIG_DIR in the spawn env, or the host default)
+ * and the pid (direct or via the tmux pane). Returns the reading plus the resolved
+ * pid (for #650 liveness wiring), or undefined when the pid can't be resolved.
+ */
+export function readManagedClaudeStatus(args: {
+  pid?: number;
+  tmuxSession?: string;
+  tmuxSocket?: string;
+  configHomeEnv?: string;
+}): { reading: ClaudeSessionReading; pid: number } | undefined {
+  const pid = resolveClaudePid(args.pid, args.tmuxSession, args.tmuxSocket);
+  if (pid === undefined) return undefined;
+  const configHome = args.configHomeEnv || process.env.CLAUDE_CONFIG_DIR || join(homedir(), ".claude");
+  return { reading: readClaudeSessionStatus(configHome, pid), pid };
+}
+
+/**
+ * Map the intrinsic probe status to the 3-valued activity. The whole point of #766:
+ *   busy/shell → busy   — shell is shelled-out/local-bash (a tool/gate is running);
+ *                         the old pane-scrape misread it as idle and force-cleared.
+ *   idle       → idle
+ *   waiting    → unknown — a permission/input dialog is a parked (not done) turn, so
+ *                          we neither assert compute-busy nor let the backstop clear
+ *                          the live turn. `waitingFor` is surfaced separately for
+ *                          permission/asking detection.
+ */
+export function claudeProbeActivity(status: ClaudeProbeStatus): ClaudeProbeActivity {
+  switch (status) {
+    case "busy":
+    case "shell":
+      return "busy";
+    case "idle":
+      return "idle";
+    default:
+      return "unknown";
+  }
+}

package/src/adapters/claude.ts

@@ -14,6 +14,7 @@ import type { SessionEvent } from "../session-insights";
 import { prepareClaudeProfileHome, profileUsesClaudeHostProviderGlobals } from "../profile-home";
 import { assembleLaunch, materializeLaunchAssembly, sessionStatusLineSettingsArgs } from "../launch-assembly";
 import { claudeProviderMessageText } from "./claude-delivery";
+import { claudeProbeActivity, readManagedClaudeStatus, resolveClaudePid, type ClaudeProbeActivity } from "./claude-session-probe";
 import { buildRateLimitProviderState, parseClaudeRateLimitPane } from "../rate-limit";
 import { evaluateClaudePromptGatePane, initialClaudePromptGatePaneState, type ClaudePromptGatePaneState } from "../claude-prompt-gates";
 
@@ -130,6 +131,22 @@ export class ClaudeAdapter implements ProviderAdapter {
     const session = process.meta?.tmuxSession as string | undefined;
     const socket = process.meta?.tmuxSocket as string | undefined;
     if (!session || !tmuxHasSession(session, socket)) return "unknown";
+    return this.activityFromProbeOrPane(process, session, socket);
+  }
+
+  // Shared probe-primary / pane-fallback activity read (#766/#768), used by both the
+  // reconciler-facing probeActivity and the monitorless turn-watch. Primary: Claude
+  // Code's intrinsic session probe (busy/shell→busy — the idle-while-working gap the
+  // pane-scrape misread; idle→idle; waiting→unknown, a parked turn the backstop must
+  // not force-clear). Legacy fallback: scrape the tmux pane (pre-2.1.119 / probe missing).
+  private activityFromProbeOrPane(process: ManagedProcess, session: string, socket?: string): ClaudeProbeActivity {
+    const managed = readManagedClaudeStatus({
+      pid: process.pid,
+      tmuxSession: session,
+      tmuxSocket: socket,
+      configHomeEnv: (process.meta?.env as Record<string, string | undefined> | undefined)?.CLAUDE_CONFIG_DIR,
+    });
+    if (managed?.reading.available) return claudeProbeActivity(managed.reading.status);
     let pane: string;
     try { pane = captureTmuxPane(session, socket); } catch { return "unknown"; }
     if (claudePaneIsBusy(pane)) return "busy";
@@ -137,6 +154,23 @@ export class ClaudeAdapter implements ProviderAdapter {
     return "unknown";
   }
 
+  // #769 P1-A: an independent pane-busy read, consumed ONLY as a veto on the busy
+  // backstop's force-clear (BusyReconciler) — a probe-`idle` must never clear a live
+  // turn while the pane spinner still reads busy (a connection-retry/529 can write
+  // status:idle mid-turn without tripping the rate-limit pane detector — the #769
+  // gap). probeActivity stays probe-primary; this is a clear-time veto-toward-busy
+  // only. false on no session / capture failure (no veto).
+  async probePaneBusy(process: ManagedProcess): Promise<boolean> {
+    const session = process.meta?.tmuxSession as string | undefined;
+    const socket = process.meta?.tmuxSocket as string | undefined;
+    if (!session || !tmuxHasSession(session, socket)) return false;
+    try {
+      return claudePaneIsBusy(captureTmuxPane(session, socket));
+    } catch {
+      return false;
+    }
+  }
+
   async deliver(process: ManagedProcess, messages: Message[]): Promise<void> {
     const monitor = process.meta?.monitor as { deliver?(messages: Message[]): Promise<number[]> } | undefined;
     // A monitor object always exists for headless claude (it proxies to the runner
@@ -171,15 +205,20 @@ export class ClaudeAdapter implements ProviderAdapter {
     // status does) — the task lingers until the runtime budget cancels it. Scrape
     // the tmux pane for the busy→idle transition to synthesize a provider-turn
     // signal so isolated automation agents reach task "done" like Codex.
-    if (monitorless) this.beginMonitorlessTurnWatch(session, socket);
+    if (monitorless) this.beginMonitorlessTurnWatch(process, session, socket);
   }
 
-  private beginMonitorlessTurnWatch(sessionName: string, socketName?: string): void {
+  private beginMonitorlessTurnWatch(process: ManagedProcess, sessionName: string, socketName?: string): void {
     this.stopTurnWatch();
+    // #769 P2-C: feed the resolved claude pid into the provider-turn liveness pids
+    // so #650's pid-liveness reconcile arms for headless/monitorless turns too (the
+    // process itself isn't tracked here — pid is undefined for tmux-managed claude).
+    // A dead pid means the turn is definitively over, so this can't falsely clear.
+    const livenessPid = resolveClaudePid(process.pid, sessionName, socketName);
     // We just submitted a prompt, so a turn is starting. Emit a synthetic
     // provider-turn busy now so the runner arms task-claim completion; the claim
     // for this delivery is already registered before deliver() runs.
-    this.statusCb({ status: "busy", reason: "provider-turn", id: CLAUDE_TURN_WATCH_ID });
+    this.statusCb({ status: "busy", reason: "provider-turn", id: CLAUDE_TURN_WATCH_ID, ...(livenessPid ? { pids: [livenessPid] } : {}) });
     let ticks = 0;
     let idleStreak = 0;
     let sawBusy = false;
@@ -191,18 +230,16 @@ export class ClaudeAdapter implements ProviderAdapter {
         this.stopTurnWatch();
         return;
       }
-      let pane: string;
-      try {
-        pane = captureTmuxPane(sessionName, socketName);
-      } catch {
-        return; // transient capture failure — retry next tick
-      }
-      if (claudePaneIsBusy(pane)) {
+      // #768: drive turn boundaries off the intrinsic probe (busy/shell→busy,
+      // idle→idle), falling back to the pane-scrape when the probe is unavailable.
+      // shell→busy means a Bash gate no longer reads as a finished turn.
+      const activity = this.activityFromProbeOrPane(process, sessionName, socketName);
+      if (activity === "busy") {
         sawBusy = true;
         idleStreak = 0;
         return;
       }
-      idleStreak = claudePaneLooksReady(pane) ? idleStreak + 1 : 0;
+      idleStreak = activity === "idle" ? idleStreak + 1 : 0;
       const confirmedIdle = idleStreak >= CLAUDE_TURN_IDLE_CONFIRM_TICKS;
       // Require either an observed busy spinner or a grace window, so we never
       // declare idle in the brief gap before Claude starts rendering the turn.
@@ -503,11 +540,16 @@ function captureTmuxPane(sessionName: string, socketName?: string): string {
   return result.stdout.toString();
 }
 
-// ⚠ FRAGILE PANE HEURISTICS — both functions below string-match Claude Code's TUI
-// chrome against captured tmux scrollback (~80 lines), so they break whenever CC
-// restyles its footer/banner. They are deliberately substring/regex based because
-// there's no machine-readable ready/busy signal from the TUI. Known break conditions,
-// so the next CC restyle is a fast fix rather than a hunt:
+// LEGACY PANE-SCRAPE FALLBACK (#766/#768) — busy/idle is now driven primarily by
+// Claude Code's intrinsic session probe (readClaudeSessionStatus, ./claude-session-probe):
+// `$CLAUDE_CONFIG_DIR/sessions/<pid>.json` carries a machine-readable `status` field
+// on CC ≥2.1.119. These two pane heuristics are the SOLE fallback for pre-2.1.119 /
+// probe-missing sessions, and claudePaneLooksReady still backs the input-readiness gate
+// (waitForClaudeInputReady) + the prompt-gate busy guard — so they stay. They string-match
+// CC's TUI chrome against captured tmux scrollback (~80 lines), so they break whenever CC
+// restyles its footer/banner. Deliberately substring/regex based (no machine-readable
+// signal existed when these were written). Known break conditions, so the next CC restyle
+// is a fast fix rather than a hunt:
 //   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.

package/src/busy-reconciler.ts

@@ -13,6 +13,9 @@ interface BusyReconcilerDeps {
   hasProviderTurn(): boolean;
   canProbeActivity(): boolean;
   probeActivity(): Promise<ProviderActivity> | undefined;
+  // #769 P1-A: optional independent pane-busy read consulted ONLY at the force-clear
+  // moment. When it resolves true, a probe-`idle` must not clear the live turn.
+  probePaneBusy?(): Promise<boolean> | undefined;
   clearProviderTurn(reason: string): void;
   sessionDebug(message: string): void;
 }
@@ -78,6 +81,21 @@ export class BusyReconciler {
     const confirm = this.sawBusy ? BUSY_RECONCILE_IDLE_CONFIRM : BUSY_RECONCILE_IDLE_CONFIRM_NO_BUSY;
     this.deps.sessionDebug(`reconcile probe=idle sawBusy=${this.sawBusy} streak=${this.idleStreak}/${confirm}`);
     if (this.idleStreak < confirm) return;
+    // #769 P1-A: before force-clearing, give an independent pane-busy read a veto.
+    // If the pane spinner still says busy, the probe-`idle` is untrustworthy (e.g. a
+    // connection retry wrote status:idle mid-turn) — hold the turn instead of clearing.
+    // Symmetric defense-in-depth: only clear when BOTH sources agree the turn is done.
+    const paneBusy = this.deps.probePaneBusy?.();
+    if (paneBusy) {
+      let stillBusy = false;
+      try { stillBusy = (await paneBusy) === true; } catch { stillBusy = false; }
+      if (stillBusy) {
+        this.idleStreak = 0;
+        this.sawBusy = true;
+        this.deps.sessionDebug("reconcile clear vetoed: pane still reads busy");
+        return;
+      }
+    }
     this.disarm();
     this.deps.clearProviderTurn(this.sawBusy ? "backstop reconciler" : "backstop reconciler (no-busy-observed)");
   }

package/src/runner-core.ts

@@ -333,6 +333,9 @@ export class AgentRunner {
       probeActivity: () => this.process && this.options.adapter.probeActivity
         ? this.options.adapter.probeActivity(this.process)
         : undefined,
+      probePaneBusy: () => this.process && this.options.adapter.probePaneBusy
+        ? this.options.adapter.probePaneBusy(this.process)
+        : undefined,
       clearProviderTurn: (reason) => this.forceClearProviderTurn(reason),
       sessionDebug: (message) => this.sessionDebug(message),
     });