agent-relay-runner 0.129.11 → 0.129.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.129.11",
+  "version": "0.129.12",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -22,8 +22,8 @@
     "directory": "runner"
   },
   "dependencies": {
-    "agent-relay-providers": "0.104.5",
-    "agent-relay-sdk": "0.2.129",
+    "agent-relay-providers": "0.104.6",
+    "agent-relay-sdk": "0.2.130",
     "callmux": "0.24.2"
   },
   "devDependencies": {

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.129.11",
+  "version": "0.129.12",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/plugins/claude/monitors/relay-monitor.provisioned.mjs

@@ -47,8 +47,8 @@ var RUNNER_PROMPT_TEMPLATE_DEFAULTS = [
     category: "runner",
     title: "Codex Relay Context",
     description: "Relay context note injected into Codex sessions.",
-    template: "[agent-relay] You are connected to Agent Relay, a real-time message bus between agents and users. When you receive a relay message: read it, do what it asks, and reply through the relay when a text response is needed. Use agent-relay /react <messageId> <emoji> for lightweight acknowledgement or approval. If Relay MCP tools are available, prefer relay_reply, relay_get_message, relay_get_thread, relay_send_message, relay_upload_artifact, relay_attach_artifact, relay_agent_status, relay_find_agents, relay_compact_and_resume, relay_recall, relay_spawn_agent, and relay_shutdown_agent. You never need to know or pass your own agent id \u2014 relay fills it from your token. Your identity is injected at startup as the `## Agent Relay Identity` block; use relay_whoami only for the full verbose identity dump. relay_compact_and_resume is for clean-seam self-resume after a context advisory: pass workingState and optional ruledOut; Relay owns the objective envelope. relay_recall searches your own archived pre-compaction segments by keyword when a discarded detail is needed. relay_spawn_targets / relay_spawn_agent / relay_shutdown_agent only appear if your profile grants spawning (a live-children quota); when present, call relay_spawn_targets FIRST for the live host/provider/model matrix + your quota, then stand up long-living child agents and shut down your own \u2014 find them later with relay_find_agents spawnedBy:me. For replies, prefer relay_reply or relay_send_message; CLI fallback: agent-relay /reply <messageId> \"<your reply>\". If a delivered message says it was truncated, fetch the full body with: agent-relay get-message <messageId>. For command details, run: agent-relay /guide",
-    defaultTemplate: "[agent-relay] You are connected to Agent Relay, a real-time message bus between agents and users. When you receive a relay message: read it, do what it asks, and reply through the relay when a text response is needed. Use agent-relay /react <messageId> <emoji> for lightweight acknowledgement or approval. If Relay MCP tools are available, prefer relay_reply, relay_get_message, relay_get_thread, relay_send_message, relay_upload_artifact, relay_attach_artifact, relay_agent_status, relay_find_agents, relay_compact_and_resume, relay_recall, relay_spawn_agent, and relay_shutdown_agent. You never need to know or pass your own agent id \u2014 relay fills it from your token. Your identity is injected at startup as the `## Agent Relay Identity` block; use relay_whoami only for the full verbose identity dump. relay_compact_and_resume is for clean-seam self-resume after a context advisory: pass workingState and optional ruledOut; Relay owns the objective envelope. relay_recall searches your own archived pre-compaction segments by keyword when a discarded detail is needed. relay_spawn_targets / relay_spawn_agent / relay_shutdown_agent only appear if your profile grants spawning (a live-children quota); when present, call relay_spawn_targets FIRST for the live host/provider/model matrix + your quota, then stand up long-living child agents and shut down your own \u2014 find them later with relay_find_agents spawnedBy:me. For replies, prefer relay_reply or relay_send_message; CLI fallback: agent-relay /reply <messageId> \"<your reply>\". If a delivered message says it was truncated, fetch the full body with: agent-relay get-message <messageId>. For command details, run: agent-relay /guide",
+    template: "[agent-relay] You are connected to Agent Relay, a real-time message bus between agents and users. When you receive a relay message: read it, do what it asks, and reply through the relay when a text response is needed. Use agent-relay /react <messageId> <emoji> for lightweight acknowledgement or approval. Prefer Relay MCP tools for the ops they cover, but WHICH relay_* tools you have depends on your role: a worker loads a lean implementer set (delivery, workspace status, the message round-trip, memory, blackboard, artifacts, timers, agent discovery, self-care), a coordinator loads the full surface \u2014 so use only the tools your session actually exposes and do not assume a specific tool is present. You never need to know or pass your own agent id \u2014 relay fills it from your token. Your identity is injected at startup as the `## Agent Relay Identity` block, so you never need an identity tool. relay_compact_and_resume is for clean-seam self-resume after a context advisory: pass workingState and optional ruledOut; Relay owns the objective envelope. relay_recall searches your own archived pre-compaction segments by keyword when a discarded detail is needed. relay_spawn_targets / relay_spawn_agent / relay_shutdown_agent only appear if your profile grants spawning (a live-children quota); when present, call relay_spawn_targets FIRST for the live host/provider/model matrix + your quota, then stand up long-living child agents and shut down your own \u2014 find them later with relay_find_agents spawnedBy:me. For replies, prefer relay_reply or relay_send_message; CLI fallback: agent-relay /reply <messageId> \"<your reply>\". If a delivered message says it was truncated, fetch the full body with: agent-relay get-message <messageId>. CLI-FIRST for GitHub and code intel (zero always-loaded tool-schema cost): use the `gh` CLI for all GitHub work \u2014 do NOT reach for GitHub MCP tools \u2014 and the `tl` (tokenlean) CLI for code intel (e.g. `tl run`, `tl pack`). The `agent-relay` CLI covers a specific set of relay ops: `agent-relay message`/`reply`/`get-message` and `agent-relay workspace <status|deps|list|claim|release>`; use those instead of the matching MCP tools. Other relay capabilities (memory, blackboard, timers, artifacts, and agent discovery via relay_find_agents) have no equivalent CLI and stay as MCP tools in your set \u2014 call them directly. For non-relay tools routed through callmux (web search, code search, reasoning, etc.): when the callmux meta-tools are present, call callmux_search_tools to find a tool, then callmux_call to invoke it on demand. For command details, run: agent-relay /guide",
+    defaultTemplate: "[agent-relay] You are connected to Agent Relay, a real-time message bus between agents and users. When you receive a relay message: read it, do what it asks, and reply through the relay when a text response is needed. Use agent-relay /react <messageId> <emoji> for lightweight acknowledgement or approval. Prefer Relay MCP tools for the ops they cover, but WHICH relay_* tools you have depends on your role: a worker loads a lean implementer set (delivery, workspace status, the message round-trip, memory, blackboard, artifacts, timers, agent discovery, self-care), a coordinator loads the full surface \u2014 so use only the tools your session actually exposes and do not assume a specific tool is present. You never need to know or pass your own agent id \u2014 relay fills it from your token. Your identity is injected at startup as the `## Agent Relay Identity` block, so you never need an identity tool. relay_compact_and_resume is for clean-seam self-resume after a context advisory: pass workingState and optional ruledOut; Relay owns the objective envelope. relay_recall searches your own archived pre-compaction segments by keyword when a discarded detail is needed. relay_spawn_targets / relay_spawn_agent / relay_shutdown_agent only appear if your profile grants spawning (a live-children quota); when present, call relay_spawn_targets FIRST for the live host/provider/model matrix + your quota, then stand up long-living child agents and shut down your own \u2014 find them later with relay_find_agents spawnedBy:me. For replies, prefer relay_reply or relay_send_message; CLI fallback: agent-relay /reply <messageId> \"<your reply>\". If a delivered message says it was truncated, fetch the full body with: agent-relay get-message <messageId>. CLI-FIRST for GitHub and code intel (zero always-loaded tool-schema cost): use the `gh` CLI for all GitHub work \u2014 do NOT reach for GitHub MCP tools \u2014 and the `tl` (tokenlean) CLI for code intel (e.g. `tl run`, `tl pack`). The `agent-relay` CLI covers a specific set of relay ops: `agent-relay message`/`reply`/`get-message` and `agent-relay workspace <status|deps|list|claim|release>`; use those instead of the matching MCP tools. Other relay capabilities (memory, blackboard, timers, artifacts, and agent discovery via relay_find_agents) have no equivalent CLI and stay as MCP tools in your set \u2014 call them directly. For non-relay tools routed through callmux (web search, code search, reasoning, etc.): when the callmux meta-tools are present, call callmux_search_tools to find a tool, then callmux_call to invoke it on demand. For command details, run: agent-relay /guide",
     variables: []
   },
   {
@@ -56,8 +56,8 @@ var RUNNER_PROMPT_TEMPLATE_DEFAULTS = [
     category: "runner",
     title: "Runner Workspace Lifecycle Note",
     description: "Lifecycle note injected by the runner for isolated workspaces.",
-    template: lines("[agent-relay] Isolated workspace: you are in a git worktree on branch {{branch}}, based on {{baseRef}} \u2014 NOT the main checkout. Other agents may work in parallel and land to {{baseRef}}, so {{baseRef}} will move under you. That is expected; don't fight it.", "While iterating, self-validate by running only the tests affected by your change \u2014 use your project's affected-test command if it has one; the full test gate still runs automatically at delivery, so scoping down while you iterate is safe.", "Do NOT push this branch yourself \u2014 not with `git push`, not with `tl push` or any other push wrapper, and do not manually rebase or merge. A steward may be auto-rebasing this branch in the background; pushing concurrently races it and can leave the worktree mid-rebase. Just commit your work here. When the task is done, call `relay_task_deliver` with disposition `complete`, a summary, commits, and passing `typecheck` + `test` gates when the diff touches code/test/config paths. Relay records the typed delivery on the Task, skips code gates for empty/docs-only diffs, then rebases onto the latest {{baseRef}}, lands your work, and pushes for you.", "After `relay_task_deliver` accepts a complete delivery, the workspace status becomes `ready` \u2014 this is the NORMAL, healthy hand-off state, NOT an escalation or a stall. Relay auto-merges clean rebases roughly every 2 minutes; a steward agent is spawned (after a short delay) ONLY if it can't land deterministically, so seeing no steward means it's working, not stuck. Stop your turn after delivery and go idle; do NOT wait or poll the steward queue. Relay wakes you with `landed-success` when your branch lands and refreshes, or `landed-failure` if landing fatally fails. On success you'll be on a fresh rebased branch whose name gains a `--N` suffix \u2014 expected, keep working there. Never `cd` into the main checkout, and never merge/push/resolve conflicts yourself \u2014 Relay and the steward own all of that. `agent-relay workspace status` anytime shows your current state and the exact next step."),
-    defaultTemplate: lines("[agent-relay] Isolated workspace: you are in a git worktree on branch {{branch}}, based on {{baseRef}} \u2014 NOT the main checkout. Other agents may work in parallel and land to {{baseRef}}, so {{baseRef}} will move under you. That is expected; don't fight it.", "While iterating, self-validate by running only the tests affected by your change \u2014 use your project's affected-test command if it has one; the full test gate still runs automatically at delivery, so scoping down while you iterate is safe.", "Do NOT push this branch yourself \u2014 not with `git push`, not with `tl push` or any other push wrapper, and do not manually rebase or merge. A steward may be auto-rebasing this branch in the background; pushing concurrently races it and can leave the worktree mid-rebase. Just commit your work here. When the task is done, call `relay_task_deliver` with disposition `complete`, a summary, commits, and passing `typecheck` + `test` gates when the diff touches code/test/config paths. Relay records the typed delivery on the Task, skips code gates for empty/docs-only diffs, then rebases onto the latest {{baseRef}}, lands your work, and pushes for you.", "After `relay_task_deliver` accepts a complete delivery, the workspace status becomes `ready` \u2014 this is the NORMAL, healthy hand-off state, NOT an escalation or a stall. Relay auto-merges clean rebases roughly every 2 minutes; a steward agent is spawned (after a short delay) ONLY if it can't land deterministically, so seeing no steward means it's working, not stuck. Stop your turn after delivery and go idle; do NOT wait or poll the steward queue. Relay wakes you with `landed-success` when your branch lands and refreshes, or `landed-failure` if landing fatally fails. On success you'll be on a fresh rebased branch whose name gains a `--N` suffix \u2014 expected, keep working there. Never `cd` into the main checkout, and never merge/push/resolve conflicts yourself \u2014 Relay and the steward own all of that. `agent-relay workspace status` anytime shows your current state and the exact next step."),
+    template: lines("[agent-relay] Isolated workspace: you are in a git worktree on branch {{branch}}, based on {{baseRef}} \u2014 NOT the main checkout. Other agents may work in parallel and land to {{baseRef}}, so {{baseRef}} will move under you. That is expected; don't fight it.", "While iterating, self-validate by running only the tests affected by your change \u2014 use your project's affected-test command if it has one; the full test gate still runs automatically at delivery, so scoping down while you iterate is safe.", "Do NOT push this branch yourself \u2014 not with `git push`, not with `tl push` or any other push wrapper, and do not manually rebase or merge. A steward may be auto-rebasing this branch in the background; pushing concurrently races it and can leave the worktree mid-rebase. Just commit your work here. When the task is done, call `relay_task_deliver` with disposition `complete`, a summary, commits, and passing `typecheck` + `test` gates when the diff touches code/test/config paths. Relay records the typed delivery on the Task, skips code gates for empty/docs-only diffs, then rebases onto the latest {{baseRef}}, lands your work, and pushes for you.", "After `relay_task_deliver` accepts a complete delivery, the workspace status becomes `ready` \u2014 this is the NORMAL, healthy hand-off state, NOT an escalation or a stall. Relay auto-merges clean rebases roughly every 2 minutes; a steward agent is spawned (after a short delay) ONLY if it can't land deterministically, so seeing no steward means it's working, not stuck. Stop your turn after delivery and go idle; do NOT wait or poll the steward queue. Relay wakes you with `landed-success` when your branch lands and refreshes, or `landed-failure` if landing fatally fails. On success Relay keeps this worktree on its current post-land branch; keep working there and the next delivery rebases it against the latest base. Never `cd` into the main checkout, and never merge/push/resolve conflicts yourself \u2014 Relay and the steward own all of that. `agent-relay workspace status` anytime shows your current state and the exact next step."),
+    defaultTemplate: lines("[agent-relay] Isolated workspace: you are in a git worktree on branch {{branch}}, based on {{baseRef}} \u2014 NOT the main checkout. Other agents may work in parallel and land to {{baseRef}}, so {{baseRef}} will move under you. That is expected; don't fight it.", "While iterating, self-validate by running only the tests affected by your change \u2014 use your project's affected-test command if it has one; the full test gate still runs automatically at delivery, so scoping down while you iterate is safe.", "Do NOT push this branch yourself \u2014 not with `git push`, not with `tl push` or any other push wrapper, and do not manually rebase or merge. A steward may be auto-rebasing this branch in the background; pushing concurrently races it and can leave the worktree mid-rebase. Just commit your work here. When the task is done, call `relay_task_deliver` with disposition `complete`, a summary, commits, and passing `typecheck` + `test` gates when the diff touches code/test/config paths. Relay records the typed delivery on the Task, skips code gates for empty/docs-only diffs, then rebases onto the latest {{baseRef}}, lands your work, and pushes for you.", "After `relay_task_deliver` accepts a complete delivery, the workspace status becomes `ready` \u2014 this is the NORMAL, healthy hand-off state, NOT an escalation or a stall. Relay auto-merges clean rebases roughly every 2 minutes; a steward agent is spawned (after a short delay) ONLY if it can't land deterministically, so seeing no steward means it's working, not stuck. Stop your turn after delivery and go idle; do NOT wait or poll the steward queue. Relay wakes you with `landed-success` when your branch lands and refreshes, or `landed-failure` if landing fatally fails. On success Relay keeps this worktree on its current post-land branch; keep working there and the next delivery rebases it against the latest base. Never `cd` into the main checkout, and never merge/push/resolve conflicts yourself \u2014 Relay and the steward own all of that. `agent-relay workspace status` anytime shows your current state and the exact next step."),
     variables: ["branch", "baseRef"]
   },
   {
@@ -118,6 +118,10 @@ function relayReplyActionText(messageId) {
 function relayReplyReminderText(messageId) {
   return `If this batch needs a response, send one useful reply to the latest relevant message with ${relayReplyActionText(messageId)}`;
 }
+var REMINDER_EVERY_DELIVERIES = 5;
+function shouldShowReplyReminder(deliveryCount) {
+  return deliveryCount <= 1 || deliveryCount % REMINDER_EVERY_DELIVERIES === 0;
+}
 function workspaceDepsNote(input) {
   if (input.mode !== "isolated")
     return "";
@@ -277,7 +281,6 @@ function providerAttachmentText(message) {
 }
 
 // runner/src/adapters/claude-delivery.ts
-var REMINDER_EVERY_DELIVERIES = 5;
 var TASK_CLAIM_INSTRUCTION = "Claim this task before working it, then update task status when finished.";
 function stripRelayScaffolding(body) {
   const lines2 = body.split(`
@@ -314,9 +317,6 @@ function providerSenderLabel(message) {
   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) {
-  return deliveryCount <= 1 || deliveryCount % REMINDER_EVERY_DELIVERIES === 0;
-}
 function latestReplyableMessage(messages) {
   return messages.filter((message) => isPersistedRelayMessage2(message) && !isMemoryInjection(message) && !isReactionNotification(message) && !isSpawnObligationMessage(message) && message.replyExpected !== false).at(-1);
 }

package/src/adapter.ts

@@ -1,12 +1,29 @@
-import type { AgentProfile, InteractivePrompt, LivenessSignal, Message, MessageFinalityConfidence, MessageTurnEndReason, ProviderState } from "agent-relay-sdk";
+import type { AgentProfile, InteractivePrompt, LivenessSignal, Message, MessageFinalityConfidence, MessageTurnEndReason, ProviderState, ToolCallCategory } from "agent-relay-sdk";
 import { isRecord } from "agent-relay-sdk/types/guards";
 import type { LivenessInputs } from "./liveness";
 import type { SessionEvent } from "./session-insights";
 import { messageBodyMaxCharsFromEnv } from "./message-body-config";
-import { relayReplyReminderText } from "./relay-instructions";
+import { relayReplyReminderText, shouldShowReplyReminder } from "./relay-instructions";
 import { renderRunnerTemplate } from "./template-resolver";
 
 export type SemanticStatus = "idle" | "busy" | "offline" | "error";
+
+/**
+ * #1656 — the independent pane read is THREE-VALUED on its non-busy side, and collapsing it to a
+ * boolean was the defect. `false` used to mean both "captured the pane, no spinner" (evidence the
+ * turn is over) and "could not read the pane at all" (no evidence of anything), and the busy
+ * backstop's force-clear consumed the second as if it were the first: absence of evidence taken
+ * as consent, on a turn that was still running.
+ *
+ * - `busy`       — captured, the pane visibly reads busy. Vetoes a clear.
+ * - `not-busy`   — captured, no busy chrome. The ONLY positive evidence the turn is over.
+ * - `no-session` — the pane doesn't exist to be read (no tmux session).
+ * - `unreadable` — the capture failed. Says nothing about the provider, only about the read.
+ *
+ * The last two are both `unknown` to the reconciler and behave identically there; they are kept
+ * distinct so the session log names which failure happened. Neither may ever authorize a mutation.
+ */
+export type PaneBusyReading = "busy" | "not-busy" | "no-session" | "unreadable";
 type ProviderWorkKind = "provider-turn" | "subagent" | "background-script";
 
 export interface ProviderStatusEvent {
@@ -33,10 +50,43 @@ export interface ProviderStatusEvent {
   pids?: number[];
   providerState?: ProviderState;
   metadata?: Record<string, unknown>;
+  // #1235 — the live transcript path for a hookless (monitorless) provider turn. When an
+  // adapter that learns turn boundaries WITHOUT Stop/UserPromptSubmit hooks (Claude's tmux
+  // monitorless watch) supplies this on a `provider-turn` busy/idle event, the runner drives
+  // the transcript reasoning tail natively: start on turn-start, capture the final response on
+  // turn-end. Absent for hook-driven agents, whose capture stays hook-triggered (no double-run).
+  transcriptPath?: string;
 }
 
 export type ProviderStatusUpdate = SemanticStatus | ProviderStatusEvent;
 
+/**
+ * #1651 — a pane-derived DIAGNOSTIC, and the ONLY thing a pane observation is allowed to
+ * produce. Deliberately structurally incapable of mutating runner state: it carries no
+ * SemanticStatus, no work-kind `clear`, and no ProviderState, so no amount of pane text can
+ * end a provider turn, clear subagent work, complete a task claim, place a scheduling hold,
+ * decide a restart, or license terminal wording. Those mutations require positively
+ * correlated structured evidence (hooks, StopFailure, process exit) — never a string match
+ * against TUI chrome that agent output can quote verbatim.
+ *
+ * A detector that wants to say something about the pane emits one of these via
+ * {@link ProviderAdapter.onPaneObservation}; the runner records it and nothing else.
+ */
+export interface PaneObservation {
+  /** Stable event id, e.g. "claude.pane_gate_candidate". */
+  eventType: string;
+  /** Always "pane" — names the (untrusted) evidence class this reading came from. */
+  source: "pane";
+  /** Adapter-scoped detector id: a prompt-gate id, "connection-retry", "model-unavailable". */
+  detectorId: string;
+  observedAt: number;
+  sessionName?: string;
+  /** The pane line that triggered the observation, when there is one. Diagnostic only. */
+  message?: string;
+  /** Detector-specific extras. Diagnostic only — never read for a control decision. */
+  detail?: Record<string, unknown>;
+}
+
 /**
  * A session-mirror event surfaced by an adapter that learns about session
  * activity through provider events rather than hooks/transcripts (e.g. the Codex
@@ -58,6 +108,8 @@ export interface ProviderSessionEvent {
   /** Whether this response may clear a direct user obligation; Codex keeps this false. */
   replyToUserObligation?: boolean;
   label?: string;
+  /** Provider-independent tool-call category (#1498), adapter-resolved; only set when type is "tool". */
+  category?: ToolCallCategory;
   status?: "running" | "completed" | "failed";
   streaming?: boolean;
   /** Stable provider-side step id (Codex app-server item id). Carried into
@@ -180,6 +232,11 @@ export interface RunnerSpawnConfig {
   // Stage 2 (#215): the MCP endpoint the agent connects to — the runner-local proxy URL when the
   // proxy is active. Undefined → the adapter targets the relay's MCP endpoint directly (Stage 1).
   relayMcpEndpoint?: string;
+  // #1450: the per-session proxy secret the agent authenticates to the runner-local proxy with (the
+  // same value exported as AGENT_RELAY_SESSION_TOKEN). Set only when the proxy is active; the Codex
+  // per-agent metaOnly callmux uses it to reach the relay endpoint on-demand THROUGH the proxy, so
+  // identity rides the proxy's live-token injection and no relay token is ever written to disk.
+  mcpProxySecret?: string;
   // #672: the shared host-listener URL the per-agent `callmux bridge` connects to, when the
   // profile/spawn opted into `agentProfile.sharedMcp`. Resolved runner-side (env → default);
   // the launch assembler only emits the bridge entry when sharedMcp is on.
@@ -230,6 +287,15 @@ export interface ProviderPermissionDecisionReason {
   message?: string;
 }
 
+// Fresh, per-turn context usage a transcript-backed adapter reads from its
+// session log (#1512). tokensUsed is the context-window token sum for the turn;
+// occurredAt is the wall-clock ms of the turn when the log stamps one.
+export interface ProviderContextUsage {
+  tokensUsed: number;
+  model?: string;
+  occurredAt?: number;
+}
+
 export interface ProviderAdapter {
   provider: string;
   statusSourceId?: string;
@@ -240,6 +306,24 @@ export interface ProviderAdapter {
   compact?(process: ManagedProcess, opts?: { instructions?: string }): Promise<Record<string, unknown> | void>;
   compactSupportsInstructions?: boolean;
   clearContext?(process: ManagedProcess): Promise<Record<string, unknown> | void>;
+  // #1588 — when true, the runner delivers a self-resume clear-inject continuation IN-PROCESS,
+  // coupled to the very same agent.clearContext command (deliverCoupledContinuationAfterClear),
+  // rather than leaving it to the separate reactive agent.injectContext command. Set this ONLY for
+  // providers whose clearContext is a fire-and-forget keystroke with no structured completion
+  // barrier — Claude's tmux `/clear` — where a separate inject would race the still-processing
+  // async clear and get swallowed (the #1588 silent mind-wipe). Providers whose clearContext is an
+  // awaited atomic call leave this unset: Codex's `client.threadStart()` returns the confirmed,
+  // ready new thread id BEFORE clearContext resolves, so the await IS the barrier — there is no
+  // race and the existing separate-inject-to-a-ready-thread flow (backstopped by the server-side
+  // #1023 sweep) stays correct and untouched.
+  couplesClearInjectContinuation?: boolean;
+  // Derive the current context-window token usage from a transcript-backed
+  // provider's session log (#1512). The runner calls this every heartbeat with the
+  // latest transcript so context stats keep advancing per-turn even when a provider's
+  // out-of-band probe (Claude's status-line command) goes silent after a
+  // compact/clear/native-resume. Pure parse — no process state. Event-stream
+  // providers (Codex) report context through `meta.getContext` instead and omit this.
+  contextUsageFromTranscript?(jsonl: string): ProviderContextUsage | undefined;
   // Normalize the session so far into the provider-agnostic SessionEvent stream the
   // Insights context-ratio signal (#183/#184) reduces. Called by the runner's
   // pre-session-destroy seam before any compact/clear/restart/shutdown. The runner owns
@@ -265,11 +349,19 @@ 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>;
+  // #769 P1-A: an independent "is the provider still visibly busy?" read, consulted by the
+  // busy backstop — a probeActivity()=idle must not clear a live turn while this reads `busy`
+  // (defense-in-depth when the primary probe can momentarily read idle mid-turn, e.g. a
+  // connection retry). #1656: three-valued on purpose. Only `not-busy` is evidence the turn
+  // ended; `no-session`/`unreadable` are unknown and must never authorize a clear.
+  probePaneBusy?(process: ManagedProcess): Promise<PaneBusyReading>;
+  // #1138: resolve a real OS pid for a busy provider-turn whose ManagedProcess carries
+  // none directly (e.g. Claude's tmux launch — process.pid is undefined, only a tmux
+  // session/socket). The runner calls this as a fallback when a busy report supplies no
+  // explicit pids, so the #650 liveness reconcile (and the stale-turn backstop) has real
+  // proof-of-life instead of only an elapsed-time heuristic. Returning undefined leaves
+  // the runner's existing process.pid fallback (or no pid at all) unchanged.
+  resolveBusyPid?(process: ManagedProcess): number | undefined;
   terminalAttachSpec?(process: ManagedProcess): Promise<TerminalAttachSpec>;
   respondToPermissionDecision?(process: ManagedProcess, input: ProviderPermissionDecisionInput): Promise<Record<string, unknown> | void>;
   captureSessionTurn?(input: ProviderSessionTurnInput, ctx: ProviderSessionTurnContext): Promise<ProviderSessionTurnResult | void>;
@@ -294,6 +386,11 @@ export interface ProviderAdapter {
   seedsInitialPromptAtLaunch?: boolean;
   deliver(process: ManagedProcess, messages: Message[]): Promise<void>;
   onStatusChange(cb: (status: ProviderStatusUpdate) => void): void;
+  // #1651 — subscribe to pane-derived DIAGNOSTICS. Separate from onStatusChange on purpose:
+  // this channel's payload cannot carry a status, a clear, or a providerState, so wiring a
+  // detector here is a structural guarantee that it cannot mutate runner state. Optional;
+  // adapters with no pane to scrape simply never call it.
+  onPaneObservation?(cb: (observation: PaneObservation) => void): void;
   // Subscribe to session-mirror events from providers. Batch callbacks preserve
   // shared idempotency for multiple trace steps discovered in one provider poll.
   onSessionEvent?(cb: (event: ProviderSessionEvent) => void): void;
@@ -516,7 +613,14 @@ export function providerAttachmentText(message: Message): string | undefined {
   ].join("\n");
 }
 
-export function providerMessageText(messages: Message[]): string {
+export interface ProviderMessageTextOptions {
+  // #1570 SUB-A — how many deliveries this session has sent so far (1 = first). Gates the
+  // reply-reminder block so it lands once up front and then periodically, instead of on every
+  // replyable message. Defaults to 1 (always show) for call sites that don't track a count.
+  deliveryCount?: number;
+}
+
+export function providerMessageText(messages: Message[], options: ProviderMessageTextOptions = {}): string {
   const uniqueMessages = dedupePersistedMessages(messages);
   const replyable = latestReplyableMessage(uniqueMessages);
   const maxChars = providerMessageBodyMaxChars();
@@ -534,20 +638,18 @@ export function providerMessageText(messages: Message[]): string {
       if (isMemoryContext) {
         return [
           `[agent-relay ${isSelfResumeInjection(message) ? "self-resume continuation" : "context"} from ${message.from}]`,
-          "Guide: agent-relay /guide",
           providerAttachmentText(message),
           `${subject}${preview.body}`,
         ].join("\n");
       }
       return [
         `[relay message #${message.id} from ${providerSenderLabel(message)}]`,
-        "Guide: agent-relay /guide",
         truncationGuidance,
         providerAttachmentText(message),
         `${subject}${preview.body}`,
       ].join("\n");
     });
-  if (replyable) {
+  if (replyable && shouldShowReplyReminder(options.deliveryCount ?? 1)) {
     sections.push([
       "[agent-relay reply reminder]",
       relayReplyReminderText(replyable.id),

package/src/adapters/claude-delivery.ts

@@ -1,9 +1,7 @@
 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;
+import { relayReplyReminderText, shouldShowReplyReminder } from "../relay-instructions";
 
 interface ClaudeDeliveryTextOptions {
   deliveryCount: number;
@@ -59,10 +57,6 @@ function providerSenderLabel(message: Message): string {
   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)

package/src/adapters/claude-exit.ts

@@ -0,0 +1,289 @@
+// #1647 — the ONE module allowed to type Claude's exit command, or the Enter that
+// answers its exit-confirmation dialog, into a managed pane.
+//
+// A 13.4h coordinator was destroyed when the runner's graceful-shutdown path typed
+// `/exit` into a pane whose turn was LIVE (a turn had started 18s earlier and never
+// ended), and the shutdown grace loop then pressed Enter on the resulting
+// "Background work is running — 1. Exit anyway" modal. The shutdown request itself
+// was legitimate and audited; what was missing was any correlation between the
+// request and the state of the process it was about to kill.
+//
+// Two structural guarantees live here, and both are enforced at RUNTIME, not by
+// convention:
+//
+//  1. CAPABILITY. Neither writer takes a session name. Both take a ClaudeExitGrant,
+//     and a grant can only come out of `authorizeClaudeGracefulExit`, which in turn
+//     demands a shutdown intent minted by an explicit lifecycle command. Grants are
+//     tracked in a module-private WeakSet, so a forged object literal is rejected —
+//     a detector cannot reach these functions even by fabricating the type.
+//
+//  2. CORRELATION. Authorization requires the observed provider epoch, process
+//     identity, tmux session, provider session id and turn state to match the
+//     intent EXACTLY, with positive evidence the turn has ended. Anything else —
+//     a live turn, an UNKNOWN turn, a stale intent, a re-used intent — is denied.
+//     Fail-closed in every direction: absent evidence is never treated as consent.
+//
+// `claude-exit.guard.test.ts` fails the build if any pane-detector module can reach
+// this file through the import graph.
+import { isClaudeExitConfirmationDialog } from "agent-relay-sdk/claude-exit-dialog";
+import { tmuxCommand } from "agent-relay-sdk/tmux-utils";
+import { captureTmuxPane, submitTextToTmux } from "./claude-tmux";
+
+export const CLAUDE_EXIT_COMMAND = "/exit";
+
+// A shutdown intent describes the process the operator asked to stop. It stops
+// being usable once the request is older than this, so a shutdown that queued
+// behind a slow teardown can never fire against a later turn of the same session.
+export const CLAUDE_SHUTDOWN_INTENT_TTL_MS = 60_000;
+
+// What the pane/probe says about the correlated turn. "unknown" is NOT "probably
+// idle" — it is the absence of evidence, and it denies exactly like "live".
+export type ClaudeTurnState = "ended" | "live" | "unknown";
+
+/**
+ * The audited lifecycle request, pinned to the exact process it was issued for.
+ * Minted only from an explicit shutdown/restart command — never from a detector.
+ */
+export interface ClaudeShutdownIntent {
+  /** Runner provider epoch: bumped on every provider spawn, so a post-restart process never matches. */
+  readonly epoch: number;
+  /** OS pid of the managed process at request time (undefined for tmux-managed panes). */
+  readonly pid?: number;
+  /** Claude's own process-start marker from the intrinsic session probe. */
+  readonly procStart: string | null;
+  readonly sessionName: string;
+  /** Claude's session id from the intrinsic probe; null when the probe is unavailable. */
+  readonly providerSessionId: string | null;
+  /**
+   * Identity of the conversation the request was accepted against. Claude's intrinsic
+   * probe exposes no per-turn id, so this is the finest granularity actually available
+   * (see `claudeTurnKey`) and it catches process/session replacement, not turn rollover.
+   * The "don't type into a live turn" guarantee therefore rests on the `turn` gate
+   * below, NOT on this field — stated plainly so nobody reads more safety into it.
+   */
+  readonly turnKey: string;
+  readonly issuedAt: number;
+}
+
+/** Live facts about the pane, sampled at the moment we consider typing `/exit`. */
+export interface ClaudeExitObservation {
+  readonly epoch: number;
+  readonly pid?: number;
+  readonly procStart: string | null;
+  readonly sessionName: string;
+  readonly providerSessionId: string | null;
+  readonly turn: ClaudeTurnState;
+  readonly turnKey: string;
+  readonly now: number;
+}
+
+export type ClaudeExitDenial =
+  | "intent-consumed"
+  | "intent-stale"
+  | "epoch-mismatch"
+  | "process-identity-mismatch"
+  | "session-mismatch"
+  | "provider-session-mismatch"
+  | "provider-session-unknown"
+  | "turn-changed"
+  | "turn-live"
+  | "turn-unknown";
+
+// Denials that no amount of further polling can clear: the request does not describe
+// the process in front of us, or it has already been spent. The shutdown loop stops
+// waiting on these and goes straight to out-of-band termination. Everything else
+// ("turn-live", "turn-unknown", "provider-session-unknown") is a not-yet, so the loop
+// keeps sampling until the grace window closes.
+const PERMANENT_DENIALS: ReadonlySet<ClaudeExitDenial> = new Set([
+  "intent-consumed", "intent-stale", "epoch-mismatch",
+  "process-identity-mismatch", "session-mismatch", "provider-session-mismatch", "turn-changed",
+]);
+
+export function claudeExitDenialIsPermanent(reason: ClaudeExitDenial): boolean {
+  return PERMANENT_DENIALS.has(reason);
+}
+
+export type ClaudeExitDecision =
+  | { readonly authorized: true; readonly grant: ClaudeExitGrant }
+  | { readonly authorized: false; readonly reason: ClaudeExitDenial };
+
+declare const CLAUDE_EXIT_GRANT: unique symbol;
+
+/**
+ * One-shot capability to type `/exit` into one specific pane, and to answer the
+ * ONE dialog that `/exit` raises. Opaque and unforgeable: the brand blocks it at
+ * compile time and the ISSUED registry blocks it at runtime.
+ */
+export interface ClaudeExitGrant {
+  readonly [CLAUDE_EXIT_GRANT]: true;
+  readonly sessionName: string;
+  readonly socketName?: string;
+  readonly authorizedAt: number;
+}
+
+interface GrantState {
+  /** Set once `/exit` has actually been written through this grant. */
+  exitSubmittedAt?: number;
+  /** True when a dialog was already on screen BEFORE our `/exit` — it is not ours to answer. */
+  dialogPredatesExit: boolean;
+  answeredAt?: number;
+}
+
+// Module-private. Nothing outside this file can add to either, which is what makes
+// a fabricated grant object inert rather than merely type-invalid.
+const ISSUED_GRANTS = new WeakSet<ClaudeExitGrant>();
+const GRANT_STATE = new WeakMap<ClaudeExitGrant, GrantState>();
+const CONSUMED_INTENTS = new WeakSet<ClaudeShutdownIntent>();
+
+/** Record the audited lifecycle request. Minting does not authorize anything by itself. */
+export function mintClaudeShutdownIntent(facts: Omit<ClaudeShutdownIntent, "issuedAt"> & { issuedAt?: number }): ClaudeShutdownIntent {
+  return {
+    epoch: facts.epoch,
+    ...(facts.pid === undefined ? {} : { pid: facts.pid }),
+    procStart: facts.procStart,
+    sessionName: facts.sessionName,
+    providerSessionId: facts.providerSessionId,
+    turnKey: facts.turnKey,
+    issuedAt: facts.issuedAt ?? Date.now(),
+  };
+}
+
+/**
+ * The whole policy, as a pure decision over (intent, observation). Kept separate
+ * from grant minting so the rules are unit-testable without touching tmux.
+ */
+export function decideClaudeGracefulExit(
+  intent: ClaudeShutdownIntent,
+  observed: ClaudeExitObservation,
+  consumed: boolean,
+): ClaudeExitDenial | undefined {
+  if (consumed) return "intent-consumed";
+  if (observed.now - intent.issuedAt > CLAUDE_SHUTDOWN_INTENT_TTL_MS) return "intent-stale";
+  if (observed.epoch !== intent.epoch) return "epoch-mismatch";
+  if (observed.sessionName !== intent.sessionName) return "session-mismatch";
+  // pid/procStart: only compare what BOTH sides know. A pid that changed under us is
+  // decisive; a pid nobody recorded cannot be, so it falls through to the turn gate.
+  if (intent.pid !== undefined && observed.pid !== undefined && intent.pid !== observed.pid) return "process-identity-mismatch";
+  if (intent.procStart !== null && observed.procStart !== null && intent.procStart !== observed.procStart) return "process-identity-mismatch";
+  // The provider session id is the strongest identity we have, so absence of it at
+  // exit time is disqualifying rather than ignorable: without it we cannot tell this
+  // session from its successor.
+  if (observed.providerSessionId === null) return "provider-session-unknown";
+  if (intent.providerSessionId !== null && intent.providerSessionId !== observed.providerSessionId) return "provider-session-mismatch";
+  // #1647's actual failure: the pane was mid-stream. Only POSITIVE end-of-turn
+  // evidence authorizes typing into it.
+  if (observed.turn === "live") return "turn-live";
+  if (observed.turn !== "ended") return "turn-unknown";
+  // An "ended" verdict for a DIFFERENT turn than the one we were asked about means a
+  // new turn started and finished since; the request no longer describes reality.
+  if (observed.turnKey !== intent.turnKey) return "turn-changed";
+  return undefined;
+}
+
+/**
+ * Consume the intent and mint a grant, or explain the denial. One-shot: the intent
+ * is burned on the first authorization, so a retry loop cannot type `/exit` twice.
+ */
+export function authorizeClaudeGracefulExit(
+  intent: ClaudeShutdownIntent,
+  observed: ClaudeExitObservation,
+  socketName?: string,
+): ClaudeExitDecision {
+  const denial = decideClaudeGracefulExit(intent, observed, CONSUMED_INTENTS.has(intent));
+  if (denial) return { authorized: false, reason: denial };
+  CONSUMED_INTENTS.add(intent);
+  const grant = {
+    sessionName: intent.sessionName,
+    ...(socketName === undefined ? {} : { socketName }),
+    authorizedAt: observed.now,
+  } as ClaudeExitGrant;
+  ISSUED_GRANTS.add(grant);
+  GRANT_STATE.set(grant, { dialogPredatesExit: false });
+  return { authorized: true, grant };
+}
+
+export interface ClaudeExitWriterDeps {
+  capture?: (sessionName: string, socketName?: string) => string;
+  submit?: (sessionName: string, text: string, socketName?: string) => Promise<void>;
+  sendEnter?: (sessionName: string, socketName?: string) => void;
+}
+
+function grantStateOrThrow(grant: ClaudeExitGrant): GrantState {
+  // The runtime half of the capability check. A detector that fabricates
+  // `{} as ClaudeExitGrant` to satisfy the compiler still lands here and throws.
+  if (!ISSUED_GRANTS.has(grant)) throw new Error("claude exit: grant was not issued by authorizeClaudeGracefulExit");
+  const state = GRANT_STATE.get(grant);
+  if (!state) throw new Error("claude exit: grant has no state");
+  return state;
+}
+
+export type ClaudeExitSubmitResult = "submitted" | "already-submitted" | "dialog-already-open";
+
+/**
+ * Type `/exit` into the granted pane, once.
+ *
+ * Snapshots the pane first: if an exit dialog is ALREADY on screen we neither type
+ * nor later answer it, because a modal we did not cause is not ours to dismiss —
+ * that is the "causally bound" half of the guard.
+ */
+export async function submitClaudeExitCommand(grant: ClaudeExitGrant, deps: ClaudeExitWriterDeps = {}): Promise<ClaudeExitSubmitResult> {
+  const state = grantStateOrThrow(grant);
+  if (state.exitSubmittedAt !== undefined) return "already-submitted";
+  const capture = deps.capture ?? captureTmuxPane;
+  const submit = deps.submit ?? submitTextToTmux;
+  let pane: string | undefined;
+  try {
+    pane = capture(grant.sessionName, grant.socketName);
+  } catch {
+    // Capture failure is not evidence of a clean pane. Fail closed and let the
+    // caller's out-of-band kill-session backstop terminate the process instead.
+    state.dialogPredatesExit = true;
+    return "dialog-already-open";
+  }
+  if (isClaudeExitConfirmationDialog(pane)) {
+    state.dialogPredatesExit = true;
+    return "dialog-already-open";
+  }
+  await submit(grant.sessionName, CLAUDE_EXIT_COMMAND, grant.socketName);
+  state.exitSubmittedAt = Date.now();
+  return "submitted";
+}
+
+export type ClaudeExitConfirmResult = "confirmed" | "no-dialog" | "exit-not-submitted" | "dialog-predates-exit" | "already-answered";
+
+/**
+ * Answer the exit-confirmation dialog raised by OUR `/exit`, once.
+ *
+ * Every non-"confirmed" result means no key was written. In particular the Enter is
+ * unreachable unless this same grant already submitted `/exit` and no dialog was
+ * open beforehand — so it can only ever dismiss the modal it caused.
+ */
+export function confirmClaudeExitDialogUnderGrant(grant: ClaudeExitGrant, deps: ClaudeExitWriterDeps = {}): ClaudeExitConfirmResult {
+  const state = grantStateOrThrow(grant);
+  if (state.dialogPredatesExit) return "dialog-predates-exit";
+  if (state.exitSubmittedAt === undefined) return "exit-not-submitted";
+  if (state.answeredAt !== undefined) return "already-answered";
+  const capture = deps.capture ?? captureTmuxPane;
+  let pane: string;
+  try {
+    pane = capture(grant.sessionName, grant.socketName);
+  } catch {
+    return "no-dialog";
+  }
+  if (!isClaudeExitConfirmationDialog(pane)) return "no-dialog";
+  const sendEnter = deps.sendEnter ?? defaultSendEnter;
+  try {
+    sendEnter(grant.sessionName, grant.socketName);
+  } catch {
+    // Best-effort: the caller's kill-session backstop still guarantees termination.
+    return "no-dialog";
+  }
+  state.answeredAt = Date.now();
+  return "confirmed";
+}
+
+function defaultSendEnter(sessionName: string, socketName?: string): void {
+  Bun.spawnSync(tmuxCommand(socketName, "send-keys", "-t", sessionName, "Enter"), {
+    stdin: "ignore", stdout: "ignore", stderr: "ignore",
+  });
+}