agent-relay-runner 0.129.14 → 0.129.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.129.14",
+  "version": "0.129.15",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -23,7 +23,7 @@
   },
   "dependencies": {
     "agent-relay-providers": "0.104.6",
-    "agent-relay-sdk": "0.2.130",
+    "agent-relay-sdk": "0.2.131",
     "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.14",
+  "version": "0.129.15",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/adapter.ts

@@ -260,6 +260,16 @@ export interface ManagedProcess {
   meta?: Record<string, unknown>;
 }
 
+/**
+ * #1746 — the terminal verdict of a provider shutdown. `killed` means the provider
+ * process (tmux pane / pid tree) is POSITIVELY confirmed gone; `failed-to-kill` means it
+ * survived even a SIGKILL of its process group (near-impossible on a same-user Linux host,
+ * so it is the operator-visible safety surface, not the happy path). The runner uses this
+ * to gate deregistration: a roster removal must imply the process is dead (#1746 ask 2), so
+ * a `failed-to-kill` keeps the agent visible rather than turning it into a silent zombie.
+ */
+export type ShutdownOutcome = "killed" | "failed-to-kill";
+
 export interface TerminalAttachSpec {
   mode: "guest";
   provider: string;
@@ -302,7 +312,10 @@ export interface ProviderAdapter {
   stopObligationPath?: string;
   permissionPromptHandler?: ProviderPermissionPromptHandler;
   spawn(config: RunnerSpawnConfig): Promise<ManagedProcess>;
-  shutdown(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<void>;
+  // #1746 — resolves once the provider is terminal. Returns the outcome so the runner can
+  // gate deregistration on confirmed death; `void` from a legacy adapter is treated as
+  // `killed` (best-effort back-compat), but both first-party adapters now report explicitly.
+  shutdown(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<ShutdownOutcome | void>;
   compact?(process: ManagedProcess, opts?: { instructions?: string }): Promise<Record<string, unknown> | void>;
   compactSupportsInstructions?: boolean;
   clearContext?(process: ManagedProcess): Promise<Record<string, unknown> | void>;

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

@@ -14,7 +14,7 @@
 // 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 { readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { isPidAlive } from "agent-relay-sdk/process-utils";
@@ -51,9 +51,18 @@ export function claudeProbeBusyIsStale(
   reading: ClaudeSessionReading,
   nowMs: number = Date.now(),
   thresholdMs: number = claudeProbeBusyStaleMsFromEnv(),
+  lastActivityAt: number | null = null,
 ): boolean {
   if (!reading.available || reading.updatedAt === null) return false;
-  return nowMs - reading.updatedAt >= thresholdMs;
+  // #1642 — age the busy verdict against the most recent OBSERVED activity, not the probe's own
+  // last write alone. Claude appends to its transcript on every turn event (tool_use / thinking /
+  // text) even when no status TRANSITION rewrites the probe, so a fresher transcript append is
+  // direct proof the turn is still producing work. With no activity signal supplied this collapses
+  // to the exact #1621 behavior (age against `updatedAt`).
+  const lastActivity = lastActivityAt !== null && lastActivityAt > reading.updatedAt
+    ? lastActivityAt
+    : reading.updatedAt;
+  return nowMs - lastActivity >= thresholdMs;
 }
 
 /**
@@ -65,19 +74,27 @@ export function claudeProbeBusyIsStale(
 export function claudeProbeVerdict(
   reading: ClaudeSessionReading | undefined,
   nowMs: number = Date.now(),
-  opts: { paneInterruptAt?: number } = {},
+  opts: { paneInterruptAt?: number; lastActivityAt?: number } = {},
 ): { activity: ClaudeProbeActivity | undefined; busyStale: boolean } {
   const activity = reading?.available ? claudeProbeActivity(reading.status) : undefined;
   if (activity !== "busy" || !reading) return { activity, busyStale: false };
+  // #1642 — a transcript append AFTER a candidate cancellation is proof the turn is still live and
+  // defeats BOTH staleness paths below. An actively-streaming turn must never be handed to the pane
+  // for clearing just because the probe file went quiet between transitions. A genuine out-of-band
+  // cancel stops the event stream too, so the transcript also falls silent and the trust decay
+  // below still fires — this narrows the decay to exactly the false-idle case, nothing wider.
+  const activityAt = opts.lastActivityAt ?? null;
   // #1621 — the precise form of the same staleness question, for the case relay CAUSED: relay
   // typed a turn-cancelling keystroke into the pane (the prompt gate's Escape) and the probe has
   // not been rewritten since. That is not a guess about elapsed time — it is a busy assertion that
   // demonstrably predates the cancellation, so it stops being authoritative immediately instead of
-  // after the whole trust window. The pane still has to corroborate the idle read either way.
+  // after the whole trust window. The pane still has to corroborate the idle read either way. A
+  // transcript append after the interrupt (#1642) means the cancel did not take, so it is honored.
   const predatesInterrupt = opts.paneInterruptAt !== undefined
     && reading.updatedAt !== null
-    && reading.updatedAt <= opts.paneInterruptAt;
-  return { activity, busyStale: predatesInterrupt || claudeProbeBusyIsStale(reading, nowMs) };
+    && reading.updatedAt <= opts.paneInterruptAt
+    && !(activityAt !== null && activityAt > opts.paneInterruptAt);
+  return { activity, busyStale: predatesInterrupt || claudeProbeBusyIsStale(reading, nowMs, undefined, activityAt) };
 }
 
 export interface ClaudeSessionReading {
@@ -274,6 +291,27 @@ export function claudeTranscriptPath(configHome: string, cwd: string, sessionId:
   return join(configHome, "projects", cwd.replace(/[^a-zA-Z0-9]/g, "-"), `${sessionId}.jsonl`);
 }
 
+/**
+ * #1642 — the transcript's last-modified time in epoch-ms, or undefined when it can't be read
+ * (absent/old probe with no sessionId+cwd, or the file not yet created). Claude appends to this
+ * JSONL on every turn event, so its mtime is the runner's hookless "events still flowing" heartbeat
+ * — the signal that keeps an actively-streaming turn's frozen busy probe from being aged out to the
+ * pane. A failed stat is silence, never a claim the turn ended: undefined leaves #1621 untouched.
+ */
+export function claudeTranscriptMtimeMs(
+  reading: Pick<ClaudeSessionReading, "sessionId" | "cwd"> | undefined,
+  configHome: string | undefined,
+): number | undefined {
+  const sessionId = reading?.sessionId;
+  const cwd = reading?.cwd;
+  if (!sessionId || !cwd || !configHome) return undefined;
+  try {
+    return statSync(claudeTranscriptPath(configHome, cwd, sessionId)).mtimeMs;
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Resolve the live transcript path for the managed claude via its session probe (#1235):
  * the probe carries `sessionId` + `cwd`, and the runner knows the config home. Returns

package/src/adapters/claude-shutdown.ts

@@ -4,8 +4,9 @@
 //
 // The policy itself lives in ./claude-exit. This module is the caller that samples
 // live state and drives the loop.
-import { tmuxCommand, tmuxHasSession } from "agent-relay-sdk/tmux-utils";
-import type { ManagedProcess } from "../adapter";
+import { tmuxCommand, tmuxHasSession, tmuxPanePid } from "agent-relay-sdk/tmux-utils";
+import { isPidAlive, killProcessGroup } from "agent-relay-sdk/process-utils";
+import type { ManagedProcess, ShutdownOutcome } from "../adapter";
 import { readManagedClaudeStatus } from "./claude-session-probe";
 import { claudePaneIsBusy } from "./claude-status-detectors";
 import { captureTmuxPane } from "./claude-tmux";
@@ -69,6 +70,13 @@ export function observeClaudeExitState(
   };
 }
 
+// #1746 — the graceful window before the force-kill fallback escalates a signal. Two steps
+// (SIGTERM→SIGKILL) of this each; short because by the time we reap, the #1647 graceful
+// `/exit` window has already been given and declined.
+export const CLAUDE_REAP_ESCALATION_STEP_MS = 1_500;
+// Poll cadence while confirming the pane process is gone after a signal.
+const CLAUDE_REAP_CONFIRM_POLL_MS = 100;
+
 // Injectable seams so the shutdown loop (which otherwise only talks to a live tmux
 // server) is unit-testable — same pattern as ClaudeClearCommitDeps.
 export interface ClaudeShutdownDeps {
@@ -76,8 +84,19 @@ export interface ClaudeShutdownDeps {
   observe?: (process: ManagedProcess, sessionName: string, socketName?: string) => ClaudeExitObservation;
   submitExit?: (grant: ClaudeExitGrant) => Promise<unknown>;
   confirmExit?: (grant: ClaudeExitGrant) => unknown;
-  reap?: (sessionName: string, socketName?: string) => void;
+  // #1746 — the reap now returns a terminal outcome (it verifies death, it does not merely
+  // fire a kill-session). Tests that only care that the reap ran may still return void.
+  reap?: (sessionName: string, socketName?: string) => ShutdownOutcome | void | Promise<ShutdownOutcome | void>;
   sleep?: (ms: number) => Promise<unknown>;
+  // #1746 — seams for the force-kill fallback so the escalation is unit-testable without a
+  // real tmux server or live pids.
+  panePid?: (sessionName: string, socketName?: string) => number | undefined;
+  killSession?: (sessionName: string, socketName?: string) => void;
+  isAlive?: (pid: number) => boolean;
+  killGroup?: (pid: number, signal: "SIGTERM" | "SIGKILL") => void;
+  // Per-escalation-step confirm window; defaults to CLAUDE_REAP_ESCALATION_STEP_MS. Tests
+  // shrink it so the SIGTERM→SIGKILL escalation runs in milliseconds, not seconds.
+  reapStepMs?: number;
 }
 
 export async function shutdownClaudeTmux(
@@ -87,7 +106,7 @@ export async function shutdownClaudeTmux(
   socketName: string | undefined,
   fallbackEpoch: number,
   deps: ClaudeShutdownDeps = {},
-): Promise<void> {
+): Promise<ShutdownOutcome> {
   const hasSession = deps.hasSession ?? tmuxHasSession;
   const observe = deps.observe ?? ((p, s, k) => observeClaudeExitState(p, s, k, fallbackEpoch));
   const submitExit = deps.submitExit ?? submitClaudeExitCommand;
@@ -110,7 +129,9 @@ export async function shutdownClaudeTmux(
     let grant: ClaudeExitGrant | undefined;
     const deadline = Date.now() + claudeShutdownGraceMs(opts.timeoutMs);
     while (Date.now() < deadline) {
-      if (!hasSession(sessionName, socketName)) return;
+      // The session vanished on its own — the graceful `/exit` (or the agent's own exit)
+      // took. That IS a confirmed-terminal shutdown; no force-kill needed. (#1746)
+      if (!hasSession(sessionName, socketName)) return "killed";
       if (!grant) {
         // #1647 — the guard that would have saved the coordinator. A turn that is live
         // (or that we cannot positively confirm has ended) authorizes nothing, so we
@@ -138,11 +159,70 @@ export async function shutdownClaudeTmux(
 
   // The out-of-band backstop, and the path #1647 prefers: it terminates the process
   // without typing anything into the pane, so it is always reached when the guard above
-  // declines to authorize a graceful exit.
-  (deps.reap ?? reapTmuxSession)(sessionName, socketName);
+  // declines to authorize a graceful exit. #1746 — this is now a VERIFIED, escalating
+  // force-kill that returns a terminal outcome, not a fire-and-forget kill-session.
+  const outcome = await (deps.reap ?? ((s, k) => terminateClaudeTmux(s, k, deps)))(sessionName, socketName);
+  return outcome ?? "killed";
+}
+
+/**
+ * #1746 — the guaranteed-terminal force-kill fallback for a Claude tmux session. The old
+ * `reapTmuxSession` fired a single `kill-session` and trusted it; a wedged pane (parked at
+ * the "Exit anyway?" dialog) or a hiccuping tmux server would silently no-op and leave the
+ * agent fully alive while shutdown reported success — the #1746 zombie. This resolves the
+ * pane's OS pid up front, then:
+ *   1. asks tmux to kill the session (the clean path) and verifies the pane pid is gone,
+ *   2. on survival, SIGTERM the pane's PROCESS GROUP (covers the pane's foreground tree),
+ *   3. still alive → SIGKILL the group, then kill-session again to drop the empty shell,
+ * confirming death by RE-OBSERVING pid liveness + session presence after each step. Returns
+ * `killed` only on positive proof the process is gone; `failed-to-kill` if it somehow
+ * survives SIGKILL (so the runner keeps it visible rather than deregistering a live zombie).
+ */
+export async function terminateClaudeTmux(
+  sessionName: string,
+  socketName: string | undefined,
+  deps: ClaudeShutdownDeps = {},
+): Promise<ShutdownOutcome> {
+  const hasSession = deps.hasSession ?? tmuxHasSession;
+  const killSession = deps.killSession ?? defaultKillSession;
+  const isAlive = deps.isAlive ?? isPidAlive;
+  const killGroup = deps.killGroup ?? killProcessGroup;
+  const sleep = deps.sleep ?? Bun.sleep;
+  const stepMs = deps.reapStepMs ?? CLAUDE_REAP_ESCALATION_STEP_MS;
+  // Resolve BEFORE the first kill, while the session still exists to report it.
+  const panePid = (deps.panePid ?? tmuxPanePid)(sessionName, socketName);
+
+  // Terminal iff the actual pane PROCESS is gone. When we resolved a pane pid, that pid is the
+  // authority — a lingering empty tmux session shell with a dead pane process is harmless and
+  // must not read as "failed-to-kill". Only when no pid is resolvable do we fall back to the
+  // session's presence as the sole liveness signal.
+  const dead = () => panePid !== undefined ? !isAlive(panePid) : !hasSession(sessionName, socketName);
+  const settle = async (): Promise<boolean> => {
+    const deadline = Date.now() + stepMs;
+    while (Date.now() < deadline) {
+      if (dead()) return true;
+      await sleep(CLAUDE_REAP_CONFIRM_POLL_MS);
+    }
+    return dead();
+  };
+
+  // 1. The clean tear-down.
+  killSession(sessionName, socketName);
+  if (await settle()) return "killed";
+
+  // 2/3. kill-session did not take it down. Escalate on the pane's process group.
+  if (panePid !== undefined) {
+    killGroup(panePid, "SIGTERM");
+    if (await settle()) return "killed";
+    killGroup(panePid, "SIGKILL");
+    killSession(sessionName, socketName); // drop the now-empty session shell
+    if (await settle()) return "killed";
+  }
+
+  return dead() ? "killed" : "failed-to-kill";
 }
 
-function reapTmuxSession(sessionName: string, socketName?: string): void {
+function defaultKillSession(sessionName: string, socketName?: string): void {
   Bun.spawnSync(tmuxCommand(socketName, "kill-session", "-t", sessionName), {
     stdin: "ignore", stdout: "ignore", stderr: "ignore",
   });

package/src/adapters/claude.ts

@@ -4,14 +4,15 @@ import { delimiter, join, resolve } from "node:path";
 import { type Message } from "agent-relay-sdk";
 import { shellEscape as shellQuote } from "agent-relay-sdk/shell-utils";
 import { tmuxCommand, tmuxHasSession } from "agent-relay-sdk/tmux-utils";
+import { isPidAlive } from "agent-relay-sdk/process-utils";
 import { runtimePath } from "agent-relay-sdk/runtime-prefix";
-import { profileAllowsRelayFeature, type ManagedProcess, type PaneBusyReading, type PaneObservation, type ProviderAdapter, type ProviderConfig, type ProviderStatusUpdate, type RunnerSpawnConfig, type SemanticStatus, type SpawnArgs } from "../adapter";
+import { profileAllowsRelayFeature, type ManagedProcess, type PaneBusyReading, type PaneObservation, type ProviderAdapter, type ProviderConfig, type ProviderStatusUpdate, type RunnerSpawnConfig, type SemanticStatus, type ShutdownOutcome, type SpawnArgs } from "../adapter";
 import { computeLivenessSignal, type LivenessInputs } from "../liveness";
 import type { LivenessSignal } from "agent-relay-sdk";
 import { prepareClaudeProfileHome, profileUsesClaudeHostProviderGlobals } from "../profile-home";
 import { assembleLaunch, materializeLaunchAssembly, sessionStatusLineSettingsArgs, stripSettingsArgs } from "../launch-assembly";
 import { claudeProviderMessageText } from "./claude-delivery";
-import { claudeProbeVerdict, readManagedClaudeStatus, resolveClaudePid, resolveManagedClaudeTranscriptPath, type ClaudeProbeActivity } from "./claude-session-probe";
+import { claudeProbeVerdict, claudeTranscriptMtimeMs, readManagedClaudeStatus, resolveClaudePid, resolveManagedClaudeTranscriptPath, type ClaudeProbeActivity } from "./claude-session-probe";
 import { evaluateClaudePromptGatePane, initialClaudePromptGatePaneState, type ClaudePromptGatePaneState } from "./claude-prompt-gates";
 import { claudeActivityFromProbeAndPane, claudePaneLooksReady, claudePaneIsBusy, claudeRateLimitStatus, claudeConnectionRetryObservation, claudeConnectionRetryClearedObservation, claudeModelUnavailableObservation, debounceClaudeModelUnavailableObservation, initialClaudeModelUnavailableObservationState } from "./claude-status-detectors";
 import { ClaudeSessionCapture, collectClaudeTranscriptArchiveSegment, collectClaudeTranscriptSessionEvents } from "./claude-session-capture";
@@ -103,14 +104,13 @@ export class ClaudeAdapter implements ProviderAdapter {
     return { pid: proc.pid, process: proc, meta: { monitor: config.monitor, env: args.env } };
   }
 
-  async shutdown(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<void> {
+  async shutdown(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<ShutdownOutcome> {
     const tmuxSession = process.meta?.tmuxSession as string | undefined;
     const tmuxSocket = process.meta?.tmuxSocket as string | undefined;
     if (tmuxSession) {
-      await this.shutdownTmux(process, tmuxSession, opts, tmuxSocket);
-      return;
+      return this.shutdownTmux(process, tmuxSession, opts, tmuxSocket);
     }
-    await terminateSingleProcess(process, opts);
+    return terminateSingleProcess(process, opts);
   }
 
   async compact(process: ManagedProcess, opts?: { instructions?: string }): Promise<Record<string, unknown>> {
@@ -209,7 +209,12 @@ export class ClaudeAdapter implements ProviderAdapter {
     // #1621: a busy probe that hasn't been rewritten inside its trust window may be describing a
     // turn that was already cancelled out of band (no transition → no rewrite). It keeps the fast
     // path (no pane capture) only while fresh; once stale it has to face the pane.
-    const { activity: probe, busyStale } = claudeProbeVerdict(managed?.reading, Date.now(), { paneInterruptAt: this.paneInterruptAt });
+    // #1642: but a turn that is still appending to its transcript is demonstrably live — the probe
+    // freezes between status transitions while tool_use/thinking/text keep streaming. Feed the
+    // transcript mtime in as the "events still flowing" heartbeat so an actively-streaming turn is
+    // never aged out to the pane (where a missing spinner in the last 10 lines would false-idle it).
+    const lastActivityAt = claudeTranscriptMtimeMs(managed?.reading, managed?.configHome);
+    const { activity: probe, busyStale } = claudeProbeVerdict(managed?.reading, Date.now(), { paneInterruptAt: this.paneInterruptAt, lastActivityAt });
     if (probe === "busy" && !busyStale) return "busy";
     let pane: string | undefined;
     try { pane = captureTmuxPane(session, socket); } catch { return probe ?? "unknown"; }
@@ -570,13 +575,13 @@ export class ClaudeAdapter implements ProviderAdapter {
     opts: { graceful: boolean; timeoutMs: number },
     socketName?: string,
     deps: ClaudeShutdownDeps = {},
-  ): Promise<void> {
+  ): Promise<ShutdownOutcome> {
     this.stopTurnWatch();
     if (this.tmuxWatcher) {
       clearInterval(this.tmuxWatcher);
       this.tmuxWatcher = undefined;
     }
-    await shutdownClaudeTmux(process, sessionName, opts, socketName, this.providerEpoch, deps);
+    return shutdownClaudeTmux(process, sessionName, opts, socketName, this.providerEpoch, deps);
   }
 }
 
@@ -593,7 +598,7 @@ function messagesAreSelfResumeContinuation(messages: Message[]): boolean {
 // #1647 — the exit command and its two writers now live in ./claude-exit, behind the
 // one-shot grant. Re-exported so existing `./claude` consumers + tests keep their path.
 export { CLAUDE_EXIT_COMMAND } from "./claude-exit";
-export { claudeShutdownGraceMs, shutdownClaudeTmux, observeClaudeExitState, type ClaudeShutdownDeps } from "./claude-shutdown";
+export { claudeShutdownGraceMs, shutdownClaudeTmux, terminateClaudeTmux, observeClaudeExitState, CLAUDE_REAP_ESCALATION_STEP_MS, type ClaudeShutdownDeps } from "./claude-shutdown";
 // tmux transport plumbing moved to ./claude-tmux (#300 ratchet); re-exported so
 // existing `./claude` consumers + tests keep their import paths.
 export { CLAUDE_TMUX_SUBMIT_DELAY_MS, CLAUDE_TMUX_SUBMIT_KEY, CLAUDE_TMUX_READY_TIMEOUT_MS, CLAUDE_CLEAR_COMMIT_POLL_MS, tmuxSessionName, tmuxSocketName, tmuxSocketPath, assertTmuxSocketPathFits, tmuxEnvKeys, waitForClaudeInputReady, waitForClaudeClearCommitted, submitTextToTmux } from "./claude-tmux";
@@ -675,13 +680,15 @@ export function findClaudeRigRC(cwd: string): string | null {
   }
 }
 
-async function terminateSingleProcess(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<void> {
+async function terminateSingleProcess(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<ShutdownOutcome> {
   const proc = process.process;
-  if (!proc) return;
+  if (!proc) return "killed"; // nothing to kill — vacuously terminal
+  const pid = proc.pid;
   try {
     proc.kill(opts.graceful ? "SIGTERM" : "SIGKILL");
   } catch {
-    return;
+    // Already gone (ESRCH) or unsignalable — re-observe rather than trust the throw. (#1746)
+    return pid !== undefined && isPidAlive(pid) ? "failed-to-kill" : "killed";
   }
   const timeout = new Promise<"timeout">((resolve) => setTimeout(() => resolve("timeout"), opts.timeoutMs));
   const result = await Promise.race([proc.exited, timeout]);
@@ -691,4 +698,6 @@ async function terminateSingleProcess(process: ManagedProcess, opts: { graceful:
     } catch {}
     await proc.exited.catch(() => {});
   }
+  // Confirm death rather than assume the kill took (#1746).
+  return pid !== undefined && isPidAlive(pid) ? "failed-to-kill" : "killed";
 }

package/src/adapters/codex.ts

@@ -1,7 +1,7 @@
 import type { ContextState, InteractivePrompt, LivenessSignal, Message, MessageTurnEndReason, ProviderState, ToolCallCategory } from "agent-relay-sdk";
 import { isRecord, stringValue } from "agent-relay-sdk";
 import { isPidAlive, killPid, processTreePids, processTreePidsFromTable, waitForPidsExit } from "agent-relay-sdk/process-utils";
-import { profileAllowsRelayFeature, providerMessageText, relayContext, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type ProviderPermissionDecisionInput, type ProviderSessionEvent, type ProviderStatusUpdate, type RunnerSpawnConfig, type SpawnArgs, type TerminalAttachSpec } from "../adapter";
+import { profileAllowsRelayFeature, providerMessageText, relayContext, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type ProviderPermissionDecisionInput, type ProviderSessionEvent, type ProviderStatusUpdate, type RunnerSpawnConfig, type ShutdownOutcome, type SpawnArgs, type TerminalAttachSpec } from "../adapter";
 import { workspaceDepsNoteFromEnv } from "../relay-instructions";
 import { CODEX_TURN_IN_PROGRESS_MESSAGE } from "../runner-helpers";
 import { tomlString } from "../relay-mcp";
@@ -242,10 +242,10 @@ export class CodexAdapter implements ProviderAdapter {
     return process;
   }
 
-  async shutdown(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<void> {
+  async shutdown(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<ShutdownOutcome> {
     const client = process.meta?.client as CodexAppClient | undefined;
     client?.close();
-    await terminateProcessTree(process, opts);
+    return terminateProcessTree(process, opts);
   }
 
   async compact(process: ManagedProcess): Promise<Record<string, unknown>> {
@@ -1170,33 +1170,29 @@ async function connectWithRetry(client: CodexAppClient, attempts = 40): Promise<
   throw lastError instanceof Error ? lastError : new Error(String(lastError));
 }
 
-async function terminateProcessTree(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<void> {
+async function terminateProcessTree(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<ShutdownOutcome> {
   const processes = [
     process.meta?.tui as Bun.Subprocess | undefined,
     process.meta?.appServer as Bun.Subprocess | undefined,
     process.process,
   ].filter(Boolean) as Bun.Subprocess[];
-  if (processes.length === 0) return;
+  if (processes.length === 0) return "killed"; // nothing to kill — vacuously terminal
   const rootPids = processes.map((proc) => proc.pid).filter((pid): pid is number => typeof pid === "number" && pid > 0);
   const pids = await processTreePids(rootPids).catch(() => rootPids);
   const signal = opts.graceful ? "SIGTERM" : "SIGKILL";
-  try {
-    for (const pid of pids) killPid(pid, signal);
-  } catch {
-    return;
-  }
+  for (const pid of pids) killPid(pid, signal);
   const exited = await waitForPidsExit(pids, opts.timeoutMs);
   const alive = pids.filter(isPidAlive);
   if (!exited || alive.length > 0) {
-    try {
-      for (const pid of alive) killPid(pid, "SIGKILL");
-    } catch {}
+    for (const pid of alive) killPid(pid, "SIGKILL");
     await waitForPidsExit(alive, 1_000);
     await Promise.race([
       Promise.all(processes.map((proc) => proc.exited.catch(() => {}))),
       Bun.sleep(1_000),
     ]);
   }
+  // #1746 — report the terminal verdict by RE-OBSERVING, never by trusting the kill calls.
+  return pids.some(isPidAlive) ? "failed-to-kill" : "killed";
 }
 
 function codexRelayContextEnabled(process: ManagedProcess): boolean {

package/src/runner-core.ts

@@ -7,7 +7,7 @@ import { contextStateFromProbeMetrics, quotaStateFromProbeMetrics } from "agent-
 import { isPidAlive } from "agent-relay-sdk/process-utils";
 import { providerAttachmentText, providerMessageText } from "./adapter";
 import { computeLivenessSignal, type LivenessInputs } from "./liveness";
-import type { ManagedProcess, PaneObservation, ProviderAdapter, ProviderConfig, ProviderPermissionDecision, ProviderPermissionDecisionInput, ProviderSessionEvent, ProviderSessionEventBatch, ProviderSessionTurnContext, ProviderSessionTurnInput, ProviderStatusUpdate, ProviderUserPromptInput, RunnerSpawnConfig, SemanticStatus, TerminalAttachSpec } from "./adapter";
+import type { ManagedProcess, PaneObservation, ProviderAdapter, ProviderConfig, ProviderPermissionDecision, ProviderPermissionDecisionInput, ProviderSessionEvent, ProviderSessionEventBatch, ProviderSessionTurnContext, ProviderSessionTurnInput, ProviderStatusUpdate, ProviderUserPromptInput, RunnerSpawnConfig, SemanticStatus, ShutdownOutcome, TerminalAttachSpec } from "./adapter";
 import { messagesWithCachedAttachments } from "./attachment-cache";
 import { ClaimTracker } from "./claim-tracker";
 import { ProviderQuotaHarvest } from "./adapters/provider-quota-harvest";
@@ -871,6 +871,10 @@ export class AgentRunner {
 
     const exitAfterCommand = type === "agent.shutdown" || type === "agent.kill";
     if (exitAfterCommand) this.exitCommandInProgress = true;
+    // #1746 — the confirmed terminal outcome of an exit command's provider teardown. Stays
+    // undefined if shutdownProvider never ran or threw; only a positive `killed` authorizes
+    // deregistration (a roster removal must imply the process is gone).
+    let killOutcome: ShutdownOutcome | undefined;
     const nativeSelfResume = isNativeSelfResumeCompact(type, params)
       ? this.nativeSelfResume.begin(commandId, params)
       : undefined;
@@ -926,7 +930,28 @@ export class AgentRunner {
         providerResult = await this.respondToPermissionDecision(params);
       } else if (type === "prompt.inject") {
         providerResult = await this.injectPrompt(params, ticket);
-      } else await this.shutdownProvider(type === "agent.kill", commandTimeoutMs(params));
+      } else {
+        try {
+          killOutcome = await this.shutdownProvider(type === "agent.kill", commandTimeoutMs(params));
+        } catch (shutdownError) {
+          // #1725 fix-forward — a throw INSIDE shutdownProvider (e.g. tmux missing from PATH ⇒
+          // defaultKillSession's Bun.spawnSync throws ENOENT) previously left killOutcome undefined
+          // and the "kill-failed" pill unset (that pill is set inside shutdownProvider, which never
+          // completed) — so the confirm-dead gate below deleted nothing AND published nothing, wedging
+          // the agent at "shutting-down" forever while the process exited anyway. Treat the throw
+          // exactly like a returned "failed-to-kill": surface the terminal pill and proceed, so the
+          // row reflects reality (a visible, re-targetable kill-failed) instead of an indefinite
+          // in-flight state, and the confirm-dead gate keeps it registered rather than deregistering
+          // a process whose death was never confirmed.
+          killOutcome = "failed-to-kill";
+          this.stopped = true;
+          this.claims.setTerminalStatus("offline");
+          this.lifecycleAction = "kill-failed";
+          this.publishStatus();
+          await this.bus.statusAsync({ agentStatus: "idle", ready: false, meta: { lifecycleAction: this.lifecycleAction, lifecycleActionAt: Date.now() } }).catch(() => {});
+          logger.error("lifecycle", `provider shutdown threw for ${this.agentId}: ${errMessage(shutdownError)}; treating as failed-to-kill and keeping agent registered`);
+        }
+      }
       await this.updateCommand(commandId, "succeeded", {
         action: type,
         agentId: this.agentId,
@@ -944,7 +969,12 @@ export class AgentRunner {
       if (exitAfterCommand) {
         if (params.preserveRegistration === true) {
           await this.http.setStatus(this.agentId, "offline", this.options.instanceId).catch(() => {});
-        } else {
+        } else if (killOutcome === "killed") {
+          // #1746 — CONFIRM-DEAD-BEFORE-DEREGISTER. Only remove the roster row once the
+          // provider is positively confirmed gone. If the force-kill could not confirm death
+          // (killOutcome "failed-to-kill", or undefined because shutdownProvider threw), leave
+          // the agent registered so it stays visible (as "kill-failed") rather than becoming a
+          // silent zombie — a roster removal must imply the process is dead.
           await this.http.deleteAgent(this.agentId).catch(() => {});
         }
         if (this.options.exitProcessOnShutdown !== false) {
@@ -1403,19 +1433,29 @@ export class AgentRunner {
     return undefined;
   }
 
-  private async shutdownProvider(hard: boolean, timeoutMs = this.options.providerConfig.headless.shutdownTimeoutMs): Promise<void> {
+  private async shutdownProvider(hard: boolean, timeoutMs = this.options.providerConfig.headless.shutdownTimeoutMs): Promise<ShutdownOutcome> {
     this.lifecycleAction = hard ? "killing" : "shutting-down";
     this.publishStatus();
     await this.bus.statusAsync({ agentStatus: "idle", ready: false, meta: { lifecycleAction: this.lifecycleAction, lifecycleActionAt: Date.now() } });
+    // #1746 — no process to kill is vacuously terminal. Otherwise the adapter now returns a
+    // VERIFIED terminal outcome (it re-observes liveness, it does not trust the kill call);
+    // a legacy adapter that returns void is treated as `killed` for back-compat.
+    let outcome: ShutdownOutcome = "killed";
     if (this.process) {
-      await this.options.adapter.shutdown(this.process, {
-        graceful: !hard,
-        timeoutMs,
-      });
+      outcome = (await this.options.adapter.shutdown(this.process, { graceful: !hard, timeoutMs })) ?? "killed";
     }
     this.claims.setTerminalStatus("offline");
-    this.publishStatus();
     this.stopped = true;
+    if (outcome === "failed-to-kill") {
+      // Do NOT clear to a normal terminal state: surface the failure so the operator sees a
+      // "kill-failed" pill instead of an indefinite "shutting-down", and so the confirm-dead
+      // gate in handleCommand keeps the agent on the roster rather than deregistering a zombie.
+      this.lifecycleAction = "kill-failed";
+      await this.bus.statusAsync({ agentStatus: "idle", ready: false, meta: { lifecycleAction: this.lifecycleAction, lifecycleActionAt: Date.now() } }).catch(() => {});
+      logger.error("lifecycle", `provider force-kill failed for ${this.agentId}: process survived SIGKILL; keeping agent registered`);
+    }
+    this.publishStatus();
+    return outcome;
   }
 
   private publishRunnerTimelineEvent(event: RunnerTimelineEvent): void {

package/src/session-destroy.ts

@@ -2,6 +2,11 @@ export type SessionDestroyReason = "compact" | "clear" | "restart" | "shutdown"
 
 export type LifecycleAction =
   | "shutting-down" | "killing" | "restarting"
+  // #1746 — a TERMINAL marker: the graceful+force-kill path ran and the provider process
+  // still could not be confirmed dead. The runner deliberately keeps the agent registered
+  // (a roster removal must imply the process is gone), so this pill replaces an indefinite
+  // "shutting-down" with an operator-visible "the kill did not take" state.
+  | "kill-failed"
   | `finalizing-${SessionDestroyReason}`;
 
 export const PRE_DESTROY_TIMEOUT_MS = 4_000;