agent-relay-server 0.122.0 → 0.122.1

package/docs/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Relay API",
-    "version": "0.122.0",
+    "version": "0.122.1",
     "description": "Real-time message bus for inter-agent communication. Agent-first: this spec is designed for machine consumption — agents can self-discover the full API surface via GET /api/spec.",
     "license": {
       "name": "MIT",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.122.0",
+  "version": "0.122.1",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",
@@ -26,8 +26,7 @@
     "recipes/**",
     "scripts/install-bin-shim.cjs",
     "scripts/orchestrator-spawn-smoke.ts",
-    "runner/src/config.ts",
-    "runner/src/adapter.ts",
+    "runner/src/**/*.ts",
     "runner/plugins/**",
     "!runner/**/*.test.ts",
     "public/**",
@@ -37,7 +36,7 @@
     "CONTRIBUTING.md"
   ],
   "dependencies": {
-    "agent-relay-channels-host": "0.122.0",
+    "agent-relay-channels-host": "0.122.1",
     "agent-relay-providers": "0.104.3",
     "agent-relay-sdk": "0.2.114",
     "ajv": "^8.20.0"
@@ -54,8 +53,8 @@
     "build:dashboard": "bun run build:dashboard:bundle && bun run deploy:dashboard",
     "build:dashboard:bundle": "bun run build:sdk && cd dashboard && bun run build",
     "deploy:dashboard": "bun run scripts/deploy-dashboard.ts",
-    "ci:land": "bun run lint:import-boundaries && bun run lint:provider-contract && bun run typecheck && bun run docs:api:check && bun test",
-    "ci": "bun run build:dashboard:bundle && bun run build:claude-monitor:check && bun run ci:land",
+    "ci:land": "bun run build:dashboard:bundle && bun run build:claude-monitor:check && bun run lint:import-boundaries && bun run lint:provider-contract && bun run typecheck && bun run docs:api:check && bun test",
+    "ci": "bun run ci:land",
     "test": "bun test",
     "smoke:spawn": "bun run scripts/orchestrator-spawn-smoke.ts",
     "publish:smoke": "bun run scripts/publish-smoke.ts",

package/runner/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.122.0",
+  "version": "0.122.1",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/runner/src/adapters/claude-delivery.ts

@@ -0,0 +1,127 @@
+import type { Message } from "agent-relay-sdk";
+import { isRecord } from "agent-relay-sdk/types/guards";
+import { dedupePersistedMessages, isNotificationMessage, NOTIFICATION_NUDGE, previewDeliveredBody, providerAttachmentText, providerMessageBodyMaxChars } from "../adapter";
+import { relayReplyReminderText } from "../relay-instructions";
+
+const REMINDER_EVERY_DELIVERIES = 5;
+
+interface ClaudeDeliveryTextOptions {
+  deliveryCount: number;
+  readOnly?: boolean;
+  // false = isolated profile with no relay plugin/CLI surface. The agent cannot /reply or
+  // /claim, so strip the reply-reminder block and the server-baked claim-task instruction —
+  // it's just confusing noise in a clean-room run. Defaults to true (relay-aware agents).
+  relaySurface?: boolean;
+}
+
+// Server-baked trailing line from taskMessageBody() in src/db.ts. Meaningless to an isolated
+// agent (sole claimant, no relay CLI), so drop it from delivered text when there's no surface.
+const TASK_CLAIM_INSTRUCTION = "Claim this task before working it, then update task status when finished.";
+
+function stripRelayScaffolding(body: string): string {
+  const lines = body.split("\n");
+  const popTrailingBlanks = () => {
+    while (lines.length && (lines.at(-1) ?? "").trim() === "") lines.pop();
+  };
+  popTrailingBlanks();
+  if (lines.at(-1) === TASK_CLAIM_INSTRUCTION) {
+    lines.pop();
+    popTrailingBlanks();
+  }
+  return lines.join("\n");
+}
+
+function isMemoryInjection(message: Message): boolean {
+  return isRecord(message.payload) && message.payload.memoryInjection === true;
+}
+
+function isReactionNotification(message: Message): boolean {
+  const event = isRecord(message.payload?.event) ? message.payload.event : undefined;
+  return message.payload?.reactionNotification === true || event?.type === "message.reaction";
+}
+
+function isSpawnObligationMessage(message: Message): boolean {
+  return isRecord(message.payload) && message.payload.source === "spawn-obligation";
+}
+
+function isPersistedRelayMessage(message: Message): boolean {
+  return Number.isSafeInteger(message.id) && message.id > 0;
+}
+
+function providerSenderLabel(message: Message): string {
+  if (message.from === "user") return "human user";
+  const source = isRecord(message.payload?.source) ? message.payload.source : undefined;
+  const isHumanChannel = Boolean(source && (
+    isRecord(source.telegram) ||
+    isRecord(source.slack) ||
+    isRecord(source.discord)
+  ));
+  return isHumanChannel ? `human user via ${message.from}` : message.from;
+}
+
+function shouldShowReplyReminder(deliveryCount: number): boolean {
+  return deliveryCount <= 1 || deliveryCount % REMINDER_EVERY_DELIVERIES === 0;
+}
+
+function latestReplyableMessage(messages: Message[]): Message | undefined {
+  return messages
+    .filter((message) => isPersistedRelayMessage(message) && !isMemoryInjection(message) && !isReactionNotification(message) && !isSpawnObligationMessage(message) && message.replyExpected !== false)
+    .at(-1);
+}
+
+function formatMessage(message: Message, relaySurface: boolean): string {
+  const subject = message.subject ? `Subject: ${message.subject}\n` : "";
+  const isMemoryContext = isMemoryInjection(message);
+  const canFetchMessage = isPersistedRelayMessage(message);
+  const rawBody = relaySurface ? message.body : stripRelayScaffolding(message.body);
+  const preview = canFetchMessage
+    ? previewDeliveredBody(rawBody, message.id, providerMessageBodyMaxChars())
+    : { body: rawBody, truncated: false, guidance: [] };
+  const truncationGuidance = preview.truncated ? preview.guidance.join("\n") : undefined;
+
+  if (isMemoryContext) {
+    return [
+      `[agent-relay context from ${message.from}]`,
+      providerAttachmentText(message),
+      `${subject}${preview.body}`,
+      truncationGuidance,
+    ].filter(Boolean).join("\n");
+  }
+
+  return [
+    `[relay message #${message.id} from ${providerSenderLabel(message)}]`,
+    providerAttachmentText(message),
+    `${subject}${preview.body}`,
+    truncationGuidance,
+  ].filter(Boolean).join("\n");
+}
+
+function replyReminder(message: Message, readOnly: boolean): string {
+  const command = readOnly
+    ? `agent-relay /reply ${message.id} "<your reply>"`
+    : relayReplyReminderText(message.id);
+  return [
+    "[agent-relay reply reminder]",
+    readOnly
+      ? `If this batch needs a response, send one useful reply to the latest relevant message: ${command}`
+      : command,
+    "If you already delivered the useful response through Relay, do not send a separate status-only confirmation.",
+    "If multiple messages arrived together, cover them in one reply instead of answering each line separately.",
+  ].join("\n");
+}
+
+export function claudeProviderMessageText(messages: Message[], options: ClaudeDeliveryTextOptions): string {
+  const relaySurface = options.relaySurface !== false;
+  const uniqueMessages = dedupePersistedMessages(messages);
+  const sections = uniqueMessages.map((message) => formatMessage(message, relaySurface));
+  const replyable = latestReplyableMessage(uniqueMessages);
+  // Isolated agents have no way to reply through Relay — never append the reminder/nudge.
+  if (relaySurface && replyable && shouldShowReplyReminder(options.deliveryCount)) {
+    sections.push(replyReminder(replyable, options.readOnly === true));
+  } else if (relaySurface && !replyable && uniqueMessages.some(isNotificationMessage)) {
+    // #283 — pure notification batch (no message wants a reply): drop the scaffold, append the
+    // one-line nudge so a long context can't make the agent forget the session-start no-reply rule.
+    sections.push(NOTIFICATION_NUDGE);
+  }
+  return sections.join("\n\n");
+}

package/runner/src/adapters/claude-quota-harvest.ts

@@ -0,0 +1,92 @@
+import type { QuotaState, RelayHttpClient } from "agent-relay-sdk";
+import { quotaStateFromProbeMetrics } from "agent-relay-sdk/context-probe";
+import { readRunnerContextProbeState } from "../context-probe-state";
+import { DEFAULT_PROVIDER_QUOTA_CONFIG, normalizeProviderQuotaConfig, resolveClaudeStatuslineQuotaIdentity } from "../quota";
+
+const PASSIVE_QUOTA_CONFIG_REFRESH_MS = 60_000;
+const PASSIVE_QUOTA_SAMPLE_STALE_MS = 10 * 60_000;
+const PASSIVE_QUOTA_LEASE_MAX_TTL_MS = 10 * 60_000;
+const PASSIVE_QUOTA_LEASE_PADDING_MS = 60_000;
+
+interface ClaudeQuotaHarvestOptions {
+  agentId: string;
+  provider: string;
+  http: () => Pick<RelayHttpClient, "acquireProviderQuotaPublisherLease" | "getProviderQuotaConfig" | "upsertProviderQuota">;
+}
+
+export class ClaudeQuotaHarvest {
+  private config = { ...DEFAULT_PROVIDER_QUOTA_CONFIG };
+  private configRefreshAt = 0;
+  private lastReportAt?: number;
+  private lease?: { accountKey: string; leaseToken: string; expiresAt: number };
+  private nextLeaseAttemptAt?: number;
+
+  constructor(private readonly options: ClaudeQuotaHarvestOptions) {}
+
+  async publish(): Promise<void> {
+    if (this.options.provider !== "claude") return;
+    const probeMetrics = readRunnerContextProbeState(this.options.agentId);
+    const now = Date.now();
+    const quota = probeMetrics ? freshQuotaFromProbeMetrics(probeMetrics, now) : undefined;
+    if (!quota) return;
+    const config = await this.refreshConfig();
+    if (!config.enabled) return;
+    if (this.lastReportAt !== undefined && now - this.lastReportAt < config.pollIntervalMs) return;
+    const identity = await resolveClaudeStatuslineQuotaIdentity({ env: process.env });
+    if (!identity) return;
+    if (!await this.ensurePublisherLease(identity.accountKey, config.pollIntervalMs, now)) return;
+    await this.options.http().upsertProviderQuota({
+      provider: "claude",
+      accountKey: identity.accountKey,
+      quota,
+      lastAttemptAt: quota.updatedAt,
+      sourceAgentId: this.options.agentId,
+    });
+    this.lastReportAt = now;
+  }
+
+  private async refreshConfig() {
+    const now = Date.now();
+    if (now < this.configRefreshAt) return this.config;
+    this.configRefreshAt = now + PASSIVE_QUOTA_CONFIG_REFRESH_MS;
+    try {
+      const map = await this.options.http().getProviderQuotaConfig();
+      this.config = map.claude
+        ? normalizeProviderQuotaConfig(map.claude)
+        : { ...DEFAULT_PROVIDER_QUOTA_CONFIG };
+    } catch {
+      // Keep the previous config; defaults preserve collection if the relay is older
+      // or temporarily unreachable during a liveness tick.
+    }
+    return this.config;
+  }
+
+  private async ensurePublisherLease(accountKey: string, pollIntervalMs: number, now: number): Promise<boolean> {
+    if (this.lease?.accountKey === accountKey && this.lease.expiresAt > now) return true;
+    if (this.nextLeaseAttemptAt !== undefined && now < this.nextLeaseAttemptAt) return false;
+    const leaseToken = this.lease?.accountKey === accountKey ? this.lease.leaseToken : undefined;
+    const result = await this.options.http().acquireProviderQuotaPublisherLease({
+      provider: "claude",
+      accountKey,
+      sourceAgentId: this.options.agentId,
+      ...(leaseToken ? { leaseToken } : {}),
+      ttlMs: Math.min(PASSIVE_QUOTA_LEASE_MAX_TTL_MS, pollIntervalMs + PASSIVE_QUOTA_LEASE_PADDING_MS),
+    });
+    if (!result.acquired || !result.lease) {
+      this.lease = undefined;
+      this.nextLeaseAttemptAt = now + Math.min(result.retryAfterMs ?? pollIntervalMs, pollIntervalMs);
+      return false;
+    }
+    this.lease = { accountKey, leaseToken: result.lease.leaseToken, expiresAt: result.lease.expiresAt };
+    this.nextLeaseAttemptAt = undefined;
+    return true;
+  }
+}
+
+function freshQuotaFromProbeMetrics(metrics: NonNullable<ReturnType<typeof readRunnerContextProbeState>>, now: number): QuotaState | undefined {
+  if (now - metrics.timestamp > PASSIVE_QUOTA_SAMPLE_STALE_MS) return undefined;
+  const quota = quotaStateFromProbeMetrics(metrics);
+  if (!quota) return undefined;
+  const windows = quota.windows.filter((window) => window.resetsAt === undefined || window.resetsAt > now);
+  return windows.length > 0 ? { ...quota, windows, updatedAt: now } : undefined;
+}

package/runner/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/runner/src/adapters/claude-status-detectors.ts

@@ -0,0 +1,147 @@
+import { extractClaudeModelUnavailableMessage } from "agent-relay-sdk";
+import type { ProviderStatusUpdate } from "../adapter";
+import { buildRateLimitProviderState, parseClaudeRateLimitPane } from "../rate-limit";
+
+// 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.
+//   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).
+//   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. Tolerated because the markers are CC-specific enough to be
+//     rare in real output; if it bites, gate on the LAST N lines only (the live footer).
+// 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
+  // conversation fills it, so a mid-session delivery (e.g. the budget warning, minutes into
+  // a run) must detect readiness from the PERSISTENT input-box footer that Claude always
+  // renders at the prompt. Requiring the banner made every delivery after the first screen
+  // of output time out as "input not ready". Any one of these strong, Claude-specific
+  // markers means the TUI is up and the input box exists.
+  return text.includes("bypass permissions")   // footer in --dangerously-skip-permissions mode
+    || text.includes("shift+tab to cycle")       // mode-cycle footer hint (persistent)
+    || text.includes("? for shortcuts")          // default footer hint (persistent)
+    || text.includes("/effort")
+    || text.includes("Welcome back")
+    || text.includes("Claude Code");
+}
+
+// The working-spinner footer carries a live elapsed-time counter while a turn is in
+// flight, e.g. "✶ Perambulating… (2m 17s · ↓ 8.7k tokens)" — gerund, "… (", then
+// "[Nh ][Nm ]Ns". Anchored on the gerund ellipsis so it can't match the "… +N lines
+// (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/;
+
+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");
+}
+
+// #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).
+export function claudeRateLimitStatus(text: string, sessionName?: string): ProviderStatusUpdate | null {
+  const parsed = parseClaudeRateLimitPane(text);
+  if (!parsed) return null;
+  return {
+    status: "idle",
+    clear: ["subagent"],
+    providerState: buildRateLimitProviderState({
+      errorType: parsed.errorType ?? "session_limit", kind: parsed.kind ?? "usage_limit",
+      ...(parsed.resetAt ? { resetAt: parsed.resetAt } : {}),
+      message: parsed.message,
+      source: sessionName ? `claude-pane:${sessionName}` : "claude-pane",
+    }),
+  };
+}
+
+// #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.
+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 {
+  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,
+    },
+  };
+}
+
+export function claudeModelUnavailableStatus(text: string, sessionName?: string): ProviderStatusUpdate | null {
+  const message = extractClaudeModelUnavailableMessage(text);
+  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,
+      },
+    },
+  };
+}