agent-relay-runner 0.15.1 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.15.1",
+  "version": "0.17.0",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "directory": "runner"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.7"
+    "agent-relay-sdk": "0.2.8"
   },
   "devDependencies": {
     "@types/bun": "latest",

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

package/plugins/claude/hooks/permission-request.sh

@@ -1,5 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
+source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks/relay-status.sh"
+relay_install_hook_guard permission-request
 
 port="${AGENT_RELAY_RUNNER_PORT:-}"
 if [[ -z "$port" ]]; then

package/plugins/claude/hooks/post-compact.sh

@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
 source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks/relay-status.sh"
+relay_install_hook_guard post-compact
 
 relay_post_timeline_status idle provider-turn "" compacted

package/plugins/claude/hooks/pre-compact.sh

@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
 source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks/relay-status.sh"
+relay_install_hook_guard pre-compact
 
 relay_post_timeline_status busy provider-turn "" compacting

package/plugins/claude/hooks/relay-status.sh

@@ -92,6 +92,30 @@ relay_post_session_end() {
     -d "$body" >/dev/null 2>&1 || true
 }
 
+# --- Hook FATAL surfacing (#198) -------------------------------------------
+# A hook that dies unexpectedly must never be silent. relay_install_hook_guard
+# arms an ERR trap that reports the failure FATAL to the runner control port,
+# which logs it to the dashboard-surfaced per-agent log. Best-effort and bounded
+# (--max-time 2) so the report itself can never blow the hook's timeout budget.
+relay_hook_fatal_report() {
+  local hook="${1:-unknown}" detail="${2:-}"
+  local port="${AGENT_RELAY_RUNNER_PORT:-}"
+  [ -z "$port" ] && return 0
+  local body="{\"hook\":\"$(relay_json_escape "$hook")\",\"error\":\"$(relay_json_escape "$detail")\"}"
+  curl -fsS --max-time 2 -X POST "http://127.0.0.1:${port}/hook-fatal" \
+    -H 'Content-Type: application/json' \
+    -d "$body" >/dev/null 2>&1 || true
+}
+
+relay_install_hook_guard() {
+  RELAY_HOOK_NAME="${1:-unknown}"
+  # Fires on any unhandled failure under `set -e`/`set -u`/pipefail in the hook's
+  # main body, just before the shell exits. Reports, then lets the exit proceed.
+  # (ERR is not inherited into functions without `set -E`; this covers the top-level
+  # flow, which is where a silent death actually wedges a turn.)
+  trap 'relay_hook_err_rc=$?; relay_hook_fatal_report "${RELAY_HOOK_NAME:-unknown}" "exit ${relay_hook_err_rc}: ${BASH_COMMAND}"' ERR
+}
+
 relay_pending_reply_stop_decision() {
   local port="${AGENT_RELAY_RUNNER_PORT:-}"
   [ -z "$port" ] && return 0

package/plugins/claude/hooks/session-end.sh

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks/relay-status.sh"
+relay_install_hook_guard session-end
 
 payload="$(cat || true)"
 reason="$(relay_json_string_field reason "$payload")"

package/plugins/claude/hooks/session-start.sh

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks/relay-status.sh"
+relay_install_hook_guard session-start
 
 payload="$(cat || true)"
 source_kind="$(relay_json_string_field source "$payload")"

package/plugins/claude/hooks/stop-failure.sh

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks/relay-status.sh"
+relay_install_hook_guard stop-failure
 
 payload="$(cat || true)"
 error="$(relay_json_string_field error "$payload")"

package/plugins/claude/hooks/stop.sh

@@ -1,6 +1,14 @@
 #!/usr/bin/env bash
 set -euo pipefail
 source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks/relay-status.sh"
+relay_install_hook_guard stop
+
+# Clearing the turn's busy state is the critical path (#199). Register it on EXIT
+# so it runs even if a side-call below fails or times out under `set -e`. The one
+# exception is the reply-obligation block path, which deliberately keeps the agent
+# busy to answer — it opts out via the flag before exiting.
+_relay_clear_idle_on_exit=1
+trap '[ "${_relay_clear_idle_on_exit:-0}" = "1" ] && relay_post_status_clearing_subagents idle' EXIT
 
 payload="$(cat || true)"
 stop_hook_active="$(relay_json_bool_field stop_hook_active "$payload")"
@@ -8,12 +16,14 @@ if [ "$stop_hook_active" != "true" ]; then
   last_assistant_msg="$(echo "$payload" | jq -c '.last_assistant_message // empty' 2>/dev/null || true)"
   relay_post_session_turn "$(relay_json_string_field transcript_path "$payload")" "$last_assistant_msg"
   # `|| true`: under `set -e`, a non-zero from the obligation check must never abort
-  # the hook before the idle-clear below — clearing the turn is the critical path (#199).
+  # the hook before the idle-clear — clearing the turn is the critical path (#199).
   stop_decision="$(relay_pending_reply_stop_decision || true)"
   if [ -n "$stop_decision" ]; then
+    _relay_clear_idle_on_exit=0
     printf '%s\n' "$stop_decision"
     exit 0
   fi
 fi
 
-relay_post_status_clearing_subagents idle
+# Normal turn end → the EXIT trap posts idle (always, even on an unexpected abort above).
+exit 0

package/plugins/claude/hooks/subagent-start.sh

@@ -4,6 +4,7 @@ set -euo pipefail
 PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
 # shellcheck source=/dev/null
 source "${PLUGIN_ROOT}/hooks/relay-status.sh"
+relay_install_hook_guard subagent-start
 
 payload="$(cat || true)"
 agent_id="$(relay_json_string_field agent_id "$payload")"

package/plugins/claude/hooks/subagent-stop.sh

@@ -4,6 +4,7 @@ set -euo pipefail
 PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
 # shellcheck source=/dev/null
 source "${PLUGIN_ROOT}/hooks/relay-status.sh"
+relay_install_hook_guard subagent-stop
 
 payload="$(cat || true)"
 agent_id="$(relay_json_string_field agent_id "$payload")"

package/plugins/claude/hooks/user-prompt-submit.sh

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 source "${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks/relay-status.sh"
+relay_install_hook_guard user-prompt-submit
 payload="$(cat || true)"
 relay_post_status busy
 # Mirror a terminal/TUI-typed prompt into the dashboard chat and start reasoning

package/src/adapters/codex.ts

@@ -4,6 +4,7 @@ import { basename, join, resolve } from "node:path";
 import type { ContextState, Message } from "agent-relay-sdk";
 import { profileAllowsRelayFeature, providerMessageText, RELAY_CONTEXT, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type ProviderPermissionDecisionInput, type ProviderSessionEvent, type ProviderStatusUpdate, type RunnerSpawnConfig, type SpawnArgs, type TerminalAttachSpec } from "../adapter";
 import { workspaceDepsNoteFromEnv } from "../relay-instructions";
+import { logger } from "../logger";
 
 /** Relay context prepended to a Codex agent's first turn: the standard relay
  * blurb plus, when running in an isolated workspace, the deps caveat (#159). */
@@ -199,7 +200,7 @@ export class CodexAdapter implements ProviderAdapter {
       input = codexRelayContextBlock() + "\n\n" + input;
       process.meta = { ...(process.meta ?? {}), relayContextSent: true };
     }
-    console.error(`[agent-relay] starting Codex initial prompt in thread ${threadId}`);
+    logger.info("codex", `starting Codex initial prompt in thread ${threadId}`);
     const client = process.meta?.client as CodexAppClient;
     await client.turnStart(threadId, input);
   }
@@ -211,7 +212,7 @@ export class CodexAdapter implements ProviderAdapter {
       text = codexRelayContextBlock() + "\n\n" + text;
       process.meta = { ...(process.meta ?? {}), relayContextSent: true };
     }
-    console.error(codexDeliveryNotice(messages, threadId));
+    logger.info("codex", codexDeliveryNotice(messages, threadId));
     const client = process.meta?.client as CodexAppClient;
     await client.turnStart(threadId, text);
   }

package/src/control-server.ts

@@ -1,6 +1,16 @@
 import type { Server, ServerWebSocket } from "bun";
 import type { Message, ReplyObligation } from "agent-relay-sdk";
 import type { ProviderPermissionDecisionInput, ProviderStatusEvent, SemanticStatus, TerminalAttachSpec } from "./adapter";
+import { logger, parseLogLevel, LOG_LEVELS } from "./logger";
+
+// A hook that failed in a way it could not handle itself reports here so the
+// failure is never silent (#198 item 5). Phase 1 logs it FATAL to the per-agent
+// log; Phase 2 (#196) will additionally route it through the runner outbox to the
+// server.
+export interface HookFatalReport {
+  hook: string;
+  error: string;
+}
 
 interface MonitorSocketData {
   kind: "monitor";
@@ -33,6 +43,10 @@ interface ControlServerOptions {
   // transcript. transcriptPath is optional — the runner falls back to the last
   // path it saw during the session.
   onSessionEnd?(input: { reason?: string; transcriptPath?: string }): Promise<void>;
+  // Phase 1 observability (#198): a hook reporting an unhandled failure. The
+  // control server already logs it FATAL; this is the seam for Phase 2 to also
+  // surface it to the server via the runner outbox.
+  onHookFatal?(report: HookFatalReport): void;
 }
 
 export function startControlServer(options: ControlServerOptions): ControlServer {
@@ -81,6 +95,15 @@ export function startControlServer(options: ControlServerOptions): ControlServer
       if (url.pathname === "/session-end" && req.method === "POST") {
         return handleSessionEnd(req, options);
       }
+      if (url.pathname === "/log-level" && req.method === "GET") {
+        return Response.json({ level: logger.getLevel(), levels: LOG_LEVELS });
+      }
+      if (url.pathname === "/log-level" && req.method === "POST") {
+        return handleLogLevel(req);
+      }
+      if (url.pathname === "/hook-fatal" && req.method === "POST") {
+        return handleHookFatal(req, options);
+      }
       if (url.pathname === "/monitor") {
         const upgraded = srv.upgrade(req, { data: { kind: "monitor" } });
         return upgraded ? undefined : new Response("WebSocket upgrade failed", { status: 400 });
@@ -361,6 +384,26 @@ async function handleSessionEnd(req: Request, options: ControlServerOptions): Pr
   return Response.json({ ok: true });
 }
 
+async function handleLogLevel(req: Request): Promise<Response> {
+  const body = await req.json().catch(() => null);
+  const level = parseLogLevel(isRecord(body) && typeof body.level === "string" ? body.level : undefined);
+  if (!level) return Response.json({ error: `level must be one of: ${LOG_LEVELS.join(", ")}` }, { status: 400 });
+  const previous = logger.getLevel();
+  logger.setLevel(level);
+  logger.info("logger", `log level set to ${level} (was ${previous}) via control port`);
+  return Response.json({ ok: true, level, previous });
+}
+
+async function handleHookFatal(req: Request, options: ControlServerOptions): Promise<Response> {
+  const body = await req.json().catch(() => null);
+  const hook = isRecord(body) && typeof body.hook === "string" && body.hook.trim() ? body.hook.trim() : "unknown";
+  const error = isRecord(body) && typeof body.error === "string" ? body.error : "(no detail)";
+  // Never silent: a hook that couldn't handle its own failure lands here as FATAL.
+  logger.fatal(`hook:${hook}`, error);
+  try { options.onHookFatal?.({ hook, error }); } catch { /* reporting must never throw back at the hook */ }
+  return Response.json({ ok: true });
+}
+
 async function handleStatus(req: Request, options: ControlServerOptions): Promise<Response> {
   const body = await req.json().catch(() => null) as Partial<ProviderStatusEvent> | null;
   const status = body?.status;

package/src/logger.ts

@@ -0,0 +1,97 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+// Phase 1 observability (#198): one leveled, runtime-togglable logger for the
+// Runner and the provider adapters below it. Replaces the ad-hoc scatter of
+// `console.error`, `logRunnerDiagnostic` (-> runner-<agent>.log) and
+// `sessionLog`/`sessionDebug` (-> session-mirror-<agent>.log) with a single
+// switch and a single greppable, ANSI-free sink.
+//
+// Sink: the per-agent `session-mirror-<agent>.log` — the file the orchestrator
+// already surfaces to the dashboard log-viewer (captureSessionMirror). One place
+// to look when anything in the Runner misbehaves.
+//
+// Level is read once from AGENT_RELAY_LOG_LEVEL (default "info") and can be
+// flipped at runtime via the control port (no restart) — so a phase refactor can
+// be watched at debug without bouncing the agent.
+
+export type LogLevel = "debug" | "info" | "warn" | "error" | "fatal";
+
+const ORDER: Record<LogLevel, number> = { debug: 10, info: 20, warn: 30, error: 40, fatal: 50 };
+export const LOG_LEVELS = Object.keys(ORDER) as LogLevel[];
+
+export function parseLogLevel(value: string | undefined | null): LogLevel | undefined {
+  if (!value) return undefined;
+  const v = value.trim().toLowerCase();
+  return (LOG_LEVELS as string[]).includes(v) ? (v as LogLevel) : undefined;
+}
+
+// Matches the runner's safeLogName and the orchestrator's safeMirrorLogName so all
+// three resolve the identical filename for a given agent id.
+function safeLogName(value: string): string {
+  return value.replace(/[^a-zA-Z0-9_.-]+/g, "_").slice(0, 180);
+}
+
+export interface LoggerConfig {
+  agentId?: string;
+  level?: LogLevel;
+  headless?: boolean;
+  logDir?: string;
+}
+
+export class Logger {
+  private level: LogLevel;
+  private agentId: string;
+  private headless: boolean;
+  private logDir: string;
+
+  constructor(config: LoggerConfig = {}) {
+    this.level = config.level ?? parseLogLevel(process.env.AGENT_RELAY_LOG_LEVEL) ?? "info";
+    this.agentId = config.agentId ?? "runner";
+    this.headless = config.headless ?? false;
+    this.logDir = config.logDir ?? join(process.env.HOME || ".", ".agent-relay", "logs");
+  }
+
+  // Bind the logger to a concrete agent once the runner knows its id. Preserves a
+  // level already set via env/runtime unless an explicit level is passed.
+  configure(config: LoggerConfig): void {
+    if (config.agentId !== undefined) this.agentId = config.agentId;
+    if (config.headless !== undefined) this.headless = config.headless;
+    if (config.logDir !== undefined) this.logDir = config.logDir;
+    if (config.level !== undefined) this.level = config.level;
+  }
+
+  setLevel(level: LogLevel): void { this.level = level; }
+  getLevel(): LogLevel { return this.level; }
+  isEnabled(level: LogLevel): boolean { return ORDER[level] >= ORDER[this.level]; }
+
+  debug(component: string, message: string): void { this.log("debug", component, message); }
+  info(component: string, message: string): void { this.log("info", component, message); }
+  warn(component: string, message: string): void { this.log("warn", component, message); }
+  error(component: string, message: string): void { this.log("error", component, message); }
+  fatal(component: string, message: string): void { this.log("fatal", component, message); }
+
+  log(level: LogLevel, component: string, message: string): void {
+    if (!this.isEnabled(level)) return;
+    const line = `[${new Date().toISOString()}] ${level.toUpperCase().padEnd(5)} [${component}] ${oneLine(message)}\n`;
+    try {
+      mkdirSync(this.logDir, { recursive: true });
+      appendFileSync(join(this.logDir, `session-mirror-${safeLogName(this.agentId)}.log`), line);
+    } catch {
+      // Best-effort. If the per-agent file can't be written, surface error/fatal to
+      // stderr so it is not lost entirely (headless: lands in the orchestrator log).
+      if (ORDER[level] >= ORDER.error) { try { console.error(line.trimEnd()); } catch { /* give up */ } }
+    }
+  }
+}
+
+// Newlines would split one record across several log lines and break greppability;
+// collapse them so a multi-line message stays one line.
+function oneLine(message: string): string {
+  return message.replace(/\r?\n/g, " ⏎ ");
+}
+
+// Process-global logger. A runner process serves exactly one agent, so a singleton
+// is the right scope; the runner calls configure() once it knows its id, and
+// adapters import this instance directly (no constructor threading).
+export const logger = new Logger();

package/src/outbox.ts

@@ -0,0 +1,303 @@
+import { Database } from "bun:sqlite";
+import { mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+import { logger } from "./logger";
+
+// Phase 2 (#196) — the "nothing is ever lost" half. Runner→server events that used to be
+// fire-and-forget over HTTP (session turns, reasoning/tool traces, prompt echoes, insights,
+// hook-fatal reports) were silently dropped whenever the server was momentarily down. This
+// is a durable, FIFO, disk-backed queue that:
+//   - survives Runner/server restart (bun:sqlite file in the runtime dir),
+//   - stamps true event time (`occurredAt`) once at enqueue and preserves it through retries,
+//   - retries with capped exponential backoff, strictly in order (an append log must not
+//     reorder turns),
+//   - poisons a permanently-failing head after maxAttempts so it can't block the queue,
+//   - is bounded with a logged drop policy (never silently truncates).
+//
+// Status deliberately does NOT go through here: it rides the WebSocket bus, which is
+// last-wins and self-heals on reconnect (so it already satisfies "coalesce, don't replay
+// stale busyes"). The coalesce mode below exists so a future state event could migrate here.
+
+export type OutboxMode = "append" | "coalesce";
+
+export interface OutboxEventInput {
+  kind: string;
+  payload: unknown;
+  mode?: OutboxMode;
+  // Required for coalesce mode: prior un-poisoned rows with the same dedupeKey are replaced.
+  dedupeKey?: string;
+  // Defaults to now. Set explicitly only to backdate (e.g. replaying a captured timestamp).
+  occurredAt?: number;
+  // Defaults to a stable derived key so server-side dedup makes retries exactly-once.
+  idempotencyKey?: string;
+}
+
+export interface OutboxRecord {
+  seq: number;
+  kind: string;
+  mode: OutboxMode;
+  occurredAt: number;
+  idempotencyKey: string;
+  payload: unknown;
+  attempts: number;
+}
+
+// The transport. Resolve = delivered (row deleted). Reject = failed (retried with backoff).
+export type OutboxSend = (record: OutboxRecord) => Promise<void>;
+
+export interface OutboxOptions {
+  agentId: string;
+  send: OutboxSend;
+  // Storage directory. Defaults to AGENT_RELAY_RUNNER_OUTBOX_DIR, else a per-host temp dir.
+  dir?: string;
+  maxRows?: number;
+  maxAttempts?: number;
+  baseBackoffMs?: number;
+  maxBackoffMs?: number;
+  pollMs?: number;
+}
+
+const DEFAULTS = {
+  maxRows: 5000,
+  maxAttempts: 12,
+  baseBackoffMs: 1_000,
+  maxBackoffMs: 60_000,
+  pollMs: 5_000,
+};
+
+interface Row {
+  seq: number;
+  kind: string;
+  mode: string;
+  occurred_at: number;
+  idempotency_key: string;
+  payload: string;
+  attempts: number;
+  next_attempt_at: number;
+  poisoned: number;
+}
+
+export class Outbox {
+  private readonly db: Database;
+  private readonly agentId: string;
+  private readonly send: OutboxSend;
+  private readonly maxRows: number;
+  private readonly maxAttempts: number;
+  private readonly baseBackoffMs: number;
+  private readonly maxBackoffMs: number;
+  private readonly pollMs: number;
+  readonly path: string;
+
+  private draining = false;
+  private rerun = false;
+  private pollTimer?: ReturnType<typeof setInterval>;
+  private dueTimer?: ReturnType<typeof setTimeout>;
+  private stopped = false;
+
+  constructor(options: OutboxOptions) {
+    this.agentId = options.agentId;
+    this.send = options.send;
+    this.maxRows = options.maxRows ?? DEFAULTS.maxRows;
+    this.maxAttempts = options.maxAttempts ?? DEFAULTS.maxAttempts;
+    this.baseBackoffMs = options.baseBackoffMs ?? DEFAULTS.baseBackoffMs;
+    this.maxBackoffMs = options.maxBackoffMs ?? DEFAULTS.maxBackoffMs;
+    this.pollMs = options.pollMs ?? DEFAULTS.pollMs;
+
+    const dir = options.dir ?? process.env.AGENT_RELAY_RUNNER_OUTBOX_DIR ?? join(tmpdir(), "agent-relay-outbox");
+    this.path = options.dir === ":memory:" ? ":memory:" : join(dir, `outbox-${safeName(this.agentId)}.sqlite`);
+    if (this.path !== ":memory:") mkdirSync(dirname(this.path), { recursive: true });
+
+    this.db = new Database(this.path, { create: true });
+    this.db.exec("PRAGMA journal_mode = WAL");
+    this.db.exec("PRAGMA busy_timeout = 2000");
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS outbox (
+        seq INTEGER PRIMARY KEY AUTOINCREMENT,
+        kind TEXT NOT NULL,
+        mode TEXT NOT NULL DEFAULT 'append',
+        dedupe_key TEXT,
+        occurred_at INTEGER NOT NULL,
+        idempotency_key TEXT NOT NULL,
+        payload TEXT NOT NULL,
+        attempts INTEGER NOT NULL DEFAULT 0,
+        next_attempt_at INTEGER NOT NULL DEFAULT 0,
+        poisoned INTEGER NOT NULL DEFAULT 0,
+        created_at INTEGER NOT NULL
+      )
+    `);
+    // A restart is a fresh start: clear any backoff timers left by the prior process so
+    // pending events get an immediate retry (the down server may now be back). `attempts`
+    // is kept so the poison threshold still counts cumulative failures.
+    this.db.exec("UPDATE outbox SET next_attempt_at = 0 WHERE next_attempt_at > 0");
+  }
+
+  // Persist an event. Returns the assigned seq. Triggers a drain.
+  enqueue(input: OutboxEventInput): number {
+    if (this.stopped) throw new Error("outbox is stopped");
+    const mode: OutboxMode = input.mode ?? "append";
+    const occurredAt = input.occurredAt ?? Date.now();
+    const payloadJson = JSON.stringify(input.payload ?? null);
+    const idempotencyKey = input.idempotencyKey ?? `${this.agentId}:${input.kind}:${occurredAt}:${shortHash(payloadJson)}`;
+
+    if (mode === "coalesce") {
+      if (!input.dedupeKey) throw new Error("coalesce mode requires a dedupeKey");
+      this.db.query("DELETE FROM outbox WHERE dedupe_key = ? AND poisoned = 0").run(input.dedupeKey);
+    }
+
+    const info = this.db
+      .query(`INSERT INTO outbox (kind, mode, dedupe_key, occurred_at, idempotency_key, payload, created_at)
+              VALUES (?, ?, ?, ?, ?, ?, ?)`)
+      .run(input.kind, mode, input.dedupeKey ?? null, occurredAt, idempotencyKey, payloadJson, Date.now());
+    const seq = Number(info.lastInsertRowid);
+
+    this.enforceBound();
+    // Defer the drain to a microtask so a synchronous burst of enqueues (e.g. several
+    // coalesce updates) all land — and coalesce — before the pump pulls the head.
+    queueMicrotask(() => { void this.drain(); });
+    return seq;
+  }
+
+  // Bounded ring buffer: if over capacity, drop the oldest rows (defined overflow policy).
+  // Logged, never silent. Prefers dropping already-poisoned rows first, then oldest by seq.
+  private enforceBound(): void {
+    const { n } = this.db.query("SELECT count(*) AS n FROM outbox").get() as { n: number };
+    if (n <= this.maxRows) return;
+    const overflow = n - this.maxRows;
+    // Oldest poisoned first, then oldest live — both by seq.
+    const victims = this.db
+      .query("SELECT seq FROM outbox ORDER BY poisoned DESC, seq ASC LIMIT ?")
+      .all(overflow) as Array<{ seq: number }>;
+    const ids = victims.map((v) => v.seq);
+    if (ids.length === 0) return;
+    const placeholders = ids.map(() => "?").join(",");
+    this.db.query(`DELETE FROM outbox WHERE seq IN (${placeholders})`).run(...ids);
+    logger.warn("outbox", `bound exceeded (${n}/${this.maxRows}) — dropped ${ids.length} oldest event(s)`);
+  }
+
+  // Begin the background pump: an initial drain plus a poll timer as a backstop.
+  start(): void {
+    if (this.pollTimer || this.stopped) return;
+    void this.drain();
+    this.pollTimer = setInterval(() => { void this.drain(); }, this.pollMs);
+    this.pollTimer.unref?.();
+  }
+
+  // Process the queue strictly oldest-first. Coalesces concurrent calls; if a drain is
+  // requested while one is running, it re-runs once at the end (so an enqueue during a
+  // send isn't missed).
+  async drain(): Promise<void> {
+    if (this.stopped) return;
+    if (this.draining) { this.rerun = true; return; }
+    this.draining = true;
+    try {
+      do {
+        this.rerun = false;
+        await this.drainOnce();
+      } while (this.rerun && !this.stopped);
+    } finally {
+      this.draining = false;
+    }
+  }
+
+  private async drainOnce(): Promise<void> {
+    for (;;) {
+      if (this.stopped) return;
+      const row = this.db
+        .query("SELECT * FROM outbox WHERE poisoned = 0 ORDER BY seq ASC LIMIT 1")
+        .get() as Row | null;
+      if (!row) return;
+
+      const now = Date.now();
+      if (row.next_attempt_at > now) {
+        // Head isn't due yet. Don't reorder past it (FIFO) — schedule a wake-up and stop.
+        this.scheduleDue(row.next_attempt_at - now);
+        return;
+      }
+
+      const record: OutboxRecord = {
+        seq: row.seq,
+        kind: row.kind,
+        mode: row.mode as OutboxMode,
+        occurredAt: row.occurred_at,
+        idempotencyKey: row.idempotency_key,
+        payload: safeParse(row.payload),
+        attempts: row.attempts,
+      };
+
+      try {
+        await this.send(record);
+        this.db.query("DELETE FROM outbox WHERE seq = ?").run(row.seq);
+      } catch (error) {
+        const attempts = row.attempts + 1;
+        const reason = error instanceof Error ? error.message : String(error);
+        if (attempts >= this.maxAttempts) {
+          this.db.query("UPDATE outbox SET attempts = ?, poisoned = 1 WHERE seq = ?").run(attempts, row.seq);
+          logger.fatal("outbox", `event seq=${row.seq} kind=${row.kind} poisoned after ${attempts} attempts: ${reason}`);
+          // Move on — the next iteration picks the new head (poison no longer blocks).
+          continue;
+        }
+        const delay = this.backoff(attempts);
+        this.db.query("UPDATE outbox SET attempts = ?, next_attempt_at = ? WHERE seq = ?").run(attempts, now + delay, row.seq);
+        logger.debug("outbox", `event seq=${row.seq} kind=${row.kind} retry ${attempts}/${this.maxAttempts} in ${delay}ms: ${reason}`);
+        this.scheduleDue(delay);
+        return; // head is now scheduled; stop until it's due (preserve order)
+      }
+    }
+  }
+
+  private backoff(attempts: number): number {
+    const exp = Math.min(this.maxBackoffMs, this.baseBackoffMs * 2 ** (attempts - 1));
+    return Math.round(exp / 2 + Math.random() * (exp / 2)); // full-ish jitter, never below half
+  }
+
+  private scheduleDue(delayMs: number): void {
+    if (this.stopped || this.dueTimer) return;
+    this.dueTimer = setTimeout(() => {
+      this.dueTimer = undefined;
+      void this.drain();
+    }, Math.max(0, delayMs));
+    this.dueTimer.unref?.();
+  }
+
+  // Observability / tests.
+  pendingCount(): number {
+    return (this.db.query("SELECT count(*) AS n FROM outbox WHERE poisoned = 0").get() as { n: number }).n;
+  }
+
+  poisonedCount(): number {
+    return (this.db.query("SELECT count(*) AS n FROM outbox WHERE poisoned = 1").get() as { n: number }).n;
+  }
+
+  stop(): void {
+    this.stopped = true;
+    if (this.pollTimer) clearInterval(this.pollTimer);
+    this.pollTimer = undefined;
+    if (this.dueTimer) clearTimeout(this.dueTimer);
+    this.dueTimer = undefined;
+  }
+
+  close(): void {
+    this.stop();
+    try { this.db.close(); } catch { /* already closed */ }
+  }
+}
+
+function safeName(value: string): string {
+  return value.replace(/[^a-zA-Z0-9_.-]+/g, "_").slice(0, 180) || "agent";
+}
+
+function safeParse(json: string): unknown {
+  try { return JSON.parse(json); } catch { return null; }
+}
+
+// Small, fast, stable string hash (FNV-1a, 32-bit) — enough to disambiguate identical
+// kind+timestamp payloads in the idempotency key. Not security-sensitive.
+function shortHash(value: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < value.length; i++) {
+    h ^= value.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return (h >>> 0).toString(36);
+}

package/src/relay-instructions.ts

@@ -45,15 +45,29 @@ export function workspaceDepsNote(input: { mode?: string | null; depsMode?: stri
   }
 }
 
-/** Resolve the workspace deps caveat from the runner/monitor environment.
+/**
+ * Caveat for untracked paths symlinked from main into an isolated worktree
+ * (WorkspaceConfig.symlinkPaths, e.g. AGENTS.md, .claude-rig). Edits to these
+ * write THROUGH to the main checkout — the agent must know so it doesn't mutate
+ * shared config thinking it's worktree-local. Returns "" when nothing was linked.
+ */
+export function workspaceSymlinksNote(linked: string[]): string {
+  if (!linked.length) return "";
+  return `[agent-relay] Isolated workspace: these untracked paths are SYMLINKED from the main checkout: ${linked.join(", ")}. They resolve to the real files in main, so editing or deleting them writes THROUGH to main — treat them as read-only unless you intend to change main.`;
+}
+
+/** Resolve the workspace caveats from the runner/monitor environment.
  * AGENT_RELAY_WORKSPACE_JSON carries the resolved workspace metadata (mode +
- * deps) and is the authoritative source. Best-effort: never throws. */
+ * deps + symlinks) and is the authoritative source. Best-effort: never throws. */
 export function workspaceDepsNoteFromEnv(env: Record<string, string | undefined> = process.env): string {
   const json = env.AGENT_RELAY_WORKSPACE_JSON;
   if (!json) return "";
   try {
-    const parsed = JSON.parse(json) as { mode?: string; deps?: { mode?: string } };
-    return workspaceDepsNote({ mode: parsed.mode ?? null, depsMode: parsed.deps?.mode ?? null });
+    const parsed = JSON.parse(json) as { mode?: string; deps?: { mode?: string }; symlinks?: { linked?: string[] } };
+    return [
+      workspaceDepsNote({ mode: parsed.mode ?? null, depsMode: parsed.deps?.mode ?? null }),
+      parsed.mode === "isolated" ? workspaceSymlinksNote(parsed.symlinks?.linked ?? []) : "",
+    ].filter(Boolean).join("\n\n");
   } catch {
     return "";
   }

package/src/reply-obligation-cache.ts

@@ -0,0 +1,109 @@
+import type { ReplyObligation } from "agent-relay-sdk";
+import { logger } from "./logger";
+
+// Phase 2 (#196) — the crux. The Claude Stop hook used to ask the server, synchronously
+// and in the hot path, "does this agent owe a reply?" before clearing the turn. A slow
+// server answer (the unindexed reply_to scan, #199) blew the hook's timeout and wedged the
+// agent in `busy` forever. The fix: the hook asks the Runner, the Runner answers instantly
+// from this local snapshot, and the snapshot is refreshed from the server only in the
+// background — never on the path that ends a turn.
+//
+// Design rules:
+// - `get()` is synchronous, never throws, never touches the network.
+// - `refresh()` is the only thing that talks to the server; it coalesces concurrent calls
+//   and, on failure, keeps the last-known snapshot (stale-but-serving beats blocking).
+// - A background interval keeps the snapshot warm; `markDirty()` requests an extra,
+//   debounced refresh when state likely just changed (a message arrived, a turn ended).
+
+export type ReplyObligationFetch = () => Promise<ReplyObligation[]>;
+
+export interface ReplyObligationCacheOptions {
+  fetch: ReplyObligationFetch;
+  // Background freshness backstop. Default 10s — well under any turn cadence, cheap.
+  intervalMs?: number;
+  // Debounce window for markDirty()-triggered refreshes so a burst of events
+  // (e.g. a fan-out of messages) collapses into one server round-trip.
+  dirtyDebounceMs?: number;
+}
+
+const DEFAULT_INTERVAL_MS = 10_000;
+const DEFAULT_DIRTY_DEBOUNCE_MS = 400;
+
+export class ReplyObligationCache {
+  private readonly fetch: ReplyObligationFetch;
+  private readonly intervalMs: number;
+  private readonly dirtyDebounceMs: number;
+
+  private snapshot: ReplyObligation[] = [];
+  private lastRefreshedAt = 0;
+  private inFlight: Promise<void> | null = null;
+  private intervalTimer?: ReturnType<typeof setInterval>;
+  private dirtyTimer?: ReturnType<typeof setTimeout>;
+  private stopped = false;
+
+  constructor(options: ReplyObligationCacheOptions) {
+    this.fetch = options.fetch;
+    this.intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
+    this.dirtyDebounceMs = options.dirtyDebounceMs ?? DEFAULT_DIRTY_DEBOUNCE_MS;
+  }
+
+  // Synchronous, hot-path-safe read. Returns a copy so callers can't mutate the snapshot.
+  get(): ReplyObligation[] {
+    return this.snapshot.slice();
+  }
+
+  getLastRefreshedAt(): number {
+    return this.lastRefreshedAt;
+  }
+
+  // Begin the background freshness loop and prime the first snapshot immediately.
+  start(): void {
+    if (this.intervalTimer || this.stopped) return;
+    void this.refresh();
+    this.intervalTimer = setInterval(() => { void this.refresh(); }, this.intervalMs);
+    // Don't keep the process alive solely for cache refreshes.
+    this.intervalTimer.unref?.();
+  }
+
+  stop(): void {
+    this.stopped = true;
+    if (this.intervalTimer) clearInterval(this.intervalTimer);
+    this.intervalTimer = undefined;
+    if (this.dirtyTimer) clearTimeout(this.dirtyTimer);
+    this.dirtyTimer = undefined;
+  }
+
+  // Request a refresh because state likely changed (message arrived / turn ended).
+  // Debounced so a burst collapses into a single server round-trip.
+  markDirty(): void {
+    if (this.stopped || this.dirtyTimer) return;
+    this.dirtyTimer = setTimeout(() => {
+      this.dirtyTimer = undefined;
+      void this.refresh();
+    }, this.dirtyDebounceMs);
+    this.dirtyTimer.unref?.();
+  }
+
+  // Fetch from the server and replace the snapshot. Coalesces concurrent callers onto a
+  // single in-flight request. Never rejects — a failed fetch leaves the prior snapshot in
+  // place (the hook keeps getting an answer even while the server is down).
+  refresh(): Promise<void> {
+    if (this.stopped) return Promise.resolve();
+    if (this.inFlight) return this.inFlight;
+    this.inFlight = this.doRefresh().finally(() => { this.inFlight = null; });
+    return this.inFlight;
+  }
+
+  private async doRefresh(): Promise<void> {
+    try {
+      const obligations = await this.fetch();
+      if (this.stopped) return;
+      this.snapshot = Array.isArray(obligations) ? obligations : [];
+      this.lastRefreshedAt = Date.now();
+    } catch (error) {
+      // Server-down is a non-event: keep serving the last snapshot. Debug, not error —
+      // this is expected during outages and must not spam the log.
+      logger.debug("obligation-cache", `refresh failed, serving cached snapshot (${this.snapshot.length}): ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+}

package/src/runner.ts

@@ -1,18 +1,21 @@
 import { hostname } from "node:os";
-import { appendFileSync, closeSync, mkdirSync, openSync, readSync, statSync, writeFileSync } from "node:fs";
+import { closeSync, mkdirSync, openSync, readSync, statSync, writeFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import type { AgentProfile, ContextState, Message, MessageSessionMeta, ProviderCapabilities, TaskStatusInput, WorkspaceMetadata } from "agent-relay-sdk";
+import type { AgentProfile, ContextState, Message, MessageSessionMeta, ProviderCapabilities, SendMessageInput, TaskStatusInput, WorkspaceMetadata } from "agent-relay-sdk";
 import { RelayBusClient, RelayHttpClient } from "agent-relay-sdk";
 import { contextStateFromProbeMetrics, readContextProbeState } from "agent-relay-sdk/context-probe";
 import type { ManagedProcess, ProviderAdapter, ProviderConfig, ProviderPermissionDecision, ProviderPermissionDecisionInput, ProviderSessionEvent, ProviderStatusUpdate, RunnerSpawnConfig, SemanticStatus, TerminalAttachSpec } from "./adapter";
 import { messagesWithCachedAttachments } from "./attachment-cache";
 import { ClaimTracker } from "./claim-tracker";
 import { startControlServer, type ControlServer } from "./control-server";
+import { ReplyObligationCache } from "./reply-obligation-cache";
+import { Outbox, type OutboxRecord } from "./outbox";
 import { extractLastAssistantTurn, extractFinalAssistantMessage, extractHookAssistantMessage, extractLatestTurnSteps, transcriptLooksComplete, analyzeSession } from "./adapters/claude-transcript";
 import { agentProfileProjectionReport } from "./profile-projection";
 import { profileUsesHostProviderGlobals } from "./profile-home";
 import { runtimeMetadata } from "./version";
+import { logger, parseLogLevel } from "./logger";
 import { ensureSessionScratch, reapSessionScratch, sweepStaleSessions, type SessionScratchLayout } from "./session-scratch";
 
 interface RunnerOptions {
@@ -115,6 +118,13 @@ export class AgentRunner {
   private readonly claims = new ClaimTracker();
   private readonly http: RelayHttpClient;
   private readonly bus: RelayBusClient;
+  // Phase 2 (#196): the Stop hook reads reply obligations from this local snapshot, never
+  // from the server — so a slow server can no longer wedge a turn (the crux fix).
+  private readonly obligationCache: ReplyObligationCache;
+  // Phase 2 (#196): Runner→server append-log events (session turns, reasoning, prompts,
+  // insights, hook-fatal) go through this durable, disk-backed, timestamped queue instead of
+  // direct fire-and-forget HTTP — so nothing is lost across a server/Runner restart.
+  private readonly outbox: Outbox;
   private currentToken?: string;
   private currentTokenJti?: string;
   private currentTokenProfileId?: string;
@@ -177,12 +187,26 @@ export class AgentRunner {
 
   constructor(private readonly options: RunnerOptions) {
     this.agentId = options.agentId ?? options.runnerId;
+    // Bind the process-global logger to this agent. AGENT_RELAY_SESSION_DEBUG=1 is
+    // kept as a back-compat alias for the verbose probe/emit lines, now expressed
+    // as log level "debug" (AGENT_RELAY_LOG_LEVEL still wins when both are set).
+    logger.configure({
+      agentId: this.agentId,
+      headless: options.headless,
+      ...(this.sessionDebugVerbose && !parseLogLevel(process.env.AGENT_RELAY_LOG_LEVEL) ? { level: "debug" as const } : {}),
+    });
     this.currentToken = options.token;
     this.currentTokenJti = options.tokenJti;
     this.currentTokenProfileId = options.tokenProfileId;
     this.currentTokenExpiresAt = options.tokenExpiresAt;
     const runtime = runtimeMetadata(options.provider);
     this.http = new RelayHttpClient({ baseUrl: options.relayUrl, token: this.currentToken });
+    this.obligationCache = new ReplyObligationCache({ fetch: () => this.http.listReplyObligations(this.agentId) });
+    // Co-locate the durable outbox with the runner's runtime state (survives reboot) when the
+    // orchestrator told us where that is; otherwise the Outbox falls back to a temp dir.
+    const outboxDir = process.env.AGENT_RELAY_RUNNER_OUTBOX_DIR
+      ?? (process.env.AGENT_RELAY_RUNNER_INFO_FILE ? join(dirname(process.env.AGENT_RELAY_RUNNER_INFO_FILE), "outbox") : undefined);
+    this.outbox = new Outbox({ agentId: this.agentId, dir: outboxDir, send: (record) => this.deliverOutboxEvent(record) });
     this.bus = new RelayBusClient({
       url: relayBusUrl(options.relayUrl),
       role: "provider",
@@ -251,10 +275,13 @@ export class AgentRunner {
     this.control = startControlServer({
       onStatus: (status) => this.setProviderStatus(status),
       onTerminalAttachSpec: () => this.terminalAttachSpec(),
-      onReplyObligations: () => this.http.listReplyObligations(this.agentId),
+      // Hot-path-safe: answered instantly from the local snapshot, never a server
+      // round-trip. The snapshot is kept warm by the background refresh below (#196).
+      onReplyObligations: () => Promise.resolve(this.obligationCache.get()),
       onSessionTurn: (input) => this.publishSessionTurn(input),
       onUserPrompt: (input) => this.handleUserPrompt(input),
       onSessionEnd: (input) => this.handleSessionEnd(input),
+      onHookFatal: (report) => this.reportHookFatal(report),
     });
     this.writeRunnerInfoFile();
     this.options.adapter.onStatusChange((status) => {
@@ -268,12 +295,19 @@ export class AgentRunner {
       if (runnerShouldResolveProviderExit(semanticStatus, this.exitCommandInProgress)) this.options.onProviderExit?.(semanticStatus === "offline" ? 0 : 1);
     });
     this.options.adapter.onSessionEvent?.((event) => { void this.publishProviderSessionEvent(event); });
-    this.bus.on("message.new", (message) => this.enqueueMessage(message as Message));
+    this.bus.on("message.new", (message) => {
+      // A delivered message may create a new reply obligation — warm the snapshot so the
+      // next turn-end sees it without a hot-path server read.
+      this.obligationCache.markDirty();
+      this.enqueueMessage(message as Message);
+    });
     this.bus.on("command", (type, params, commandId, command) => {
       void this.handleCommand(type, params, commandId, command);
     });
     this.bus.on("error", (code, message) => this.handleBusError(String(code), String(message)));
     await this.bus.connect();
+    this.obligationCache.start();
+    this.outbox.start();
     this.ensureScratch();
     void this.sweepStaleScratch();
     this.process = await this.spawnProvider();
@@ -313,6 +347,8 @@ export class AgentRunner {
     this.tokenRenewTimer = undefined;
     this.disarmBusyReconciler();
     this.stopReasoningTail();
+    this.obligationCache.stop();
+    this.outbox.close();
     this.control?.stop();
     await this.bus.close();
   }
@@ -387,7 +423,7 @@ export class AgentRunner {
         startedAt: this.options.startedAt,
       }, null, 2) + "\n", { mode: 0o600 });
     } catch (error) {
-      console.error(`[runner] failed to write runner info file: ${error}`);
+      logger.error("runner", `failed to write runner info file: ${error}`);
     }
   }
 
@@ -403,7 +439,7 @@ export class AgentRunner {
       const messages = await this.http.pollMessages({ for: this.agentId, unread: true, limit: 100 });
       for (const message of messages) this.enqueueMessage(message);
     } catch (error) {
-      console.error(`[runner] inbox bootstrap failed: ${error}`);
+      logger.error("runner", `inbox bootstrap failed: ${error}`);
     }
   }
 
@@ -413,7 +449,7 @@ export class AgentRunner {
     try {
       await this.options.adapter.deliverInitialPrompt(this.process, prompt);
     } catch (error) {
-      console.error(`[runner] initial prompt delivery failed: ${error}`);
+      logger.error("runner", `initial prompt delivery failed: ${error}`);
     }
   }
 
@@ -450,7 +486,7 @@ export class AgentRunner {
             status: "in_progress",
             agentId: this.agentId,
             metadata: { messageId: message.id, completedBy: "runner" },
-          }).catch((error) => console.error(`[runner] task ${taskId} in_progress update failed: ${error}`));
+          }).catch((error) => logger.error("task", `task ${taskId} in_progress update failed: ${error}`));
           // Runner owns claim + status here; drop the server's self-claim instruction
           // so the agent doesn't improvise a stray claim send (see stripRunnerClaimedGuidance).
           toDeliver = { ...message, body: stripRunnerClaimedGuidance(message.body) };
@@ -468,7 +504,7 @@ export class AgentRunner {
     try {
       const prepared = await messagesWithCachedAttachments(deliverable, this.http, {
         agentId: this.agentId,
-        onError: (message) => console.error(`[runner] ${message}`),
+        onError: (message) => logger.error("runner", message),
       });
       await this.options.adapter.deliver(this.process, prepared);
       for (const message of deliverable) {
@@ -477,7 +513,7 @@ export class AgentRunner {
       }
     } catch (error) {
       failed = true;
-      if (shouldLogDeliveryFailure(error)) console.error(`[runner] message delivery failed: ${error}`);
+      if (shouldLogDeliveryFailure(error)) logger.warn("delivery", `message delivery failed: ${error}`);
       for (const message of deliverable) {
         this.clearActiveClaim(message);
         this.pendingMessages.set(message.id, message);
@@ -545,7 +581,7 @@ export class AgentRunner {
         await this.http.deleteAgent(this.agentId).catch(() => {});
         if (this.options.exitProcessOnShutdown !== false) {
           setTimeout(() => void this.stop().catch((error) => {
-            console.error(`[runner] stop after command failed: ${error}`);
+            logger.error("lifecycle", `stop after command failed: ${error}`);
           }).finally(() => process.exit(0)), 10);
         }
       } else if (!this.stopped) {
@@ -680,7 +716,7 @@ export class AgentRunner {
 
       if (this.shouldStopUnexpectedProviderExit(diagnostics)) {
         const hasResumeId = typeof diagnostics.claudeResumeId === "string" && diagnostics.claudeResumeId.length > 0;
-        console.warn(`[runner] ${this.options.provider} exited; leaving agent offline for manual recovery`);
+        logger.warn("lifecycle", `${this.options.provider} exited; leaving agent offline for manual recovery`);
         this.publishRunnerTimelineEvent({
           status: "provider.restart_decision",
           id: `provider-restart-decision-${this.providerSessionId}-${now}`,
@@ -708,7 +744,7 @@ export class AgentRunner {
       }
 
       if (runtimeMs < RAPID_EXIT_MS && recent.length > MAX_RAPID_UNEXPECTED_EXITS) {
-        console.error(`[runner] provider session exited ${recent.length} times within ${Math.round(UNEXPECTED_EXIT_WINDOW_MS / 1000)}s; giving up`);
+        logger.error("lifecycle", `provider session exited ${recent.length} times within ${Math.round(UNEXPECTED_EXIT_WINDOW_MS / 1000)}s; giving up`);
         this.publishRunnerTimelineEvent({
           status: "provider.restart_decision",
           id: `provider-restart-decision-${this.providerSessionId}-${now}`,
@@ -732,7 +768,7 @@ export class AgentRunner {
       }
 
       const delayMs = Math.min(10_000, Math.max(500, 500 * recent.length));
-      console.warn(`[runner] provider session exited unexpectedly after ${Math.round(runtimeMs / 1000)}s; restarting in ${delayMs}ms`);
+      logger.warn("lifecycle", `provider session exited unexpectedly after ${Math.round(runtimeMs / 1000)}s; restarting in ${delayMs}ms`);
       this.publishRunnerTimelineEvent({
         status: "provider.restart_decision",
         id: `provider-restart-decision-${this.providerSessionId}-${now}`,
@@ -757,7 +793,7 @@ export class AgentRunner {
         this.publishStatus();
         this.scheduleDrain();
       } catch (error) {
-        console.error(`[runner] provider restart after unexpected exit failed: ${error}`);
+        logger.error("lifecycle", `provider restart after unexpected exit failed: ${error}`);
         this.setProviderStatus("error");
         this.options.onProviderExit?.(1);
       }
@@ -832,10 +868,10 @@ export class AgentRunner {
   private handleBusError(code: string, message: string): void {
     const action = runnerBusErrorAction(code, this.stopped);
     if (action === "ignore") return;
-    console.error(`[runner] bus error ${code}: ${message}`);
+    logger.error("bus", `bus error ${code}: ${message}`);
     if (action === "stop") {
       void this.stop().catch((error) => {
-        console.error(`[runner] stop after bus error failed: ${error}`);
+        logger.error("bus", `stop after bus error failed: ${error}`);
       }).finally(() => process.exit(0));
     }
   }
@@ -918,13 +954,10 @@ export class AgentRunner {
       replyToMessageId = pendingPrompt;
       this.pendingPromptMessageId = undefined;
     } else {
-      try {
-        const obligations = await this.http.listReplyObligations(this.agentId);
-        const obligation = [...obligations].reverse().find((o) => o.from === "user");
-        replyToMessageId = obligation?.messageId;
-      } catch {
-        // fall through and capture without correlation
-      }
+      // Correlation-only (threading + obligation clearing) — the local snapshot is fresh
+      // enough and never blocks the response-capture path (#196).
+      const obligation = [...this.obligationCache.get()].reverse().find((o) => o.from === "user");
+      replyToMessageId = obligation?.messageId;
     }
 
     // The Stop hook can fire before the final assistant entry is flushed to disk.
@@ -966,31 +999,86 @@ export class AgentRunner {
       ...(replyToMessageId ? { replyTo: replyToMessageId } : {}),
       session: { type: "response", origin: "provider", ...(turnId ? { turnId } : {}) },
     });
+    // The agent's reply may have cleared an obligation — refresh the snapshot so the next
+    // turn-end doesn't re-prompt for a message already answered (#196).
+    if (replyToMessageId) this.obligationCache.markDirty();
   }
 
   // Post one session-mirror event (prompt echo, assistant response, reasoning or
   // tool step) as a `kind: "session"` relay message tagged with payload.session so
   // the dashboard can render the live provider session faithfully. Display-only:
   // session messages are never delivered back into a provider.
-  private async publishSessionEvent(input: {
+  private publishSessionEvent(input: {
     from: string;
     to: string;
     body: string;
     session: MessageSessionMeta;
     replyTo?: number;
-  }): Promise<void> {
-    try {
-      await this.http.sendMessage({
+  }): void {
+    // Durable, ordered, timestamped (#196): the actual POST happens in deliverOutboxEvent,
+    // retried until it lands. occurredAt is stamped now so a queued event reports when it
+    // truly happened, not when the server finally accepted it.
+    this.outbox.enqueue({
+      kind: "session-message",
+      payload: {
         from: input.from,
         to: input.to,
         ...(input.replyTo ? { replyTo: input.replyTo } : {}),
         kind: "session",
         body: input.body,
         payload: { session: { provider: this.options.provider, ...input.session } },
+      } satisfies SendMessageInput,
+    });
+  }
+
+  // The outbox transport: map a queued record to its HTTP call. Throw to retry, return to
+  // ack (delete). occurredAt + idempotencyKey are injected from the record so retries are
+  // exactly-once server-side and carry true event time.
+  private async deliverOutboxEvent(record: OutboxRecord): Promise<void> {
+    try {
+      if (record.kind === "session-message") {
+        await this.http.sendMessage({
+          ...(record.payload as SendMessageInput),
+          occurredAt: record.occurredAt,
+          idempotencyKey: record.idempotencyKey,
+        });
+        return;
+      }
+      if (record.kind === "insight") {
+        await this.http.recordInsightObservation({
+          ...(record.payload as Parameters<RelayHttpClient["recordInsightObservation"]>[0]),
+          occurredAt: record.occurredAt,
+        });
+        return;
+      }
+      logger.warn("outbox", `dropping event with unknown kind: ${record.kind}`);
+    } catch (error) {
+      // 409 = the server intentionally rejected it (e.g. Insights/feature toggled off). That
+      // is a permanent "don't want this", not a transient failure — ack so it doesn't retry.
+      if (isHttpStatusError(error, 409)) return;
+      if (isHttpAuthError(error)) this.recoverRuntimeTokenAfterAuthFailure("outbox");
+      throw error; // transient (or auth, post-recovery) → let the outbox retry with backoff
+    }
+  }
+
+  // A hook reported an unhandled failure (#198 seam). Already logged FATAL by the control
+  // server; here we additionally surface it durably to the server as a generic insight so
+  // it shows up in observability rather than only in the per-agent log (#196).
+  private reportHookFatal(report: { hook: string; error: string }): void {
+    try {
+      this.outbox.enqueue({
+        kind: "insight",
+        payload: {
+          sessionId: this.providerSessionId,
+          project: this.options.cwd,
+          agentId: this.agentId,
+          signal: "hook_fatal",
+          value: { hook: report.hook, error: report.error },
+          source: "server",
+        },
       });
     } catch (error) {
-      this.logRunnerDiagnostic(`session ${input.session.type} capture failed: ${error instanceof Error ? error.message : String(error)}`);
-      if (isHttpAuthError(error)) this.recoverRuntimeTokenAfterAuthFailure("session-capture");
+      logger.error("outbox", `failed to queue hook-fatal report: ${error instanceof Error ? error.message : String(error)}`);
     }
   }
 
@@ -1034,8 +1122,11 @@ export class AgentRunner {
     }
     const analysis = analyzeSession(jsonl);
     if (!analysis) return; // no tool calls = nothing substantive to measure
-    try {
-      await this.http.recordInsightObservation({
+    // Durable + non-blocking (#196): queue it. SessionEnd can race provider shutdown, so a
+    // direct POST risked being dropped if the server hiccuped; the outbox survives that.
+    this.outbox.enqueue({
+      kind: "insight",
+      payload: {
         sessionId: this.providerSessionId,
         project: this.options.cwd,
         agentId: this.agentId,
@@ -1043,13 +1134,9 @@ export class AgentRunner {
         value: { ...analysis.metric, ...(input.reason ? { endReason: input.reason } : {}) },
         outcome: { ...analysis.outcome },
         source: "server",
-      });
-      this.sessionLog(`insights: context_ratio ${analysis.metric.ratio.toFixed(2)} (${analysis.metric.gatheringCalls}/${analysis.metric.totalToolCalls} gathering)`);
-    } catch (error) {
-      // 409 = Insights/feature toggled off; anything else is best-effort too.
-      this.sessionDebug(`insights context_ratio skipped: ${error instanceof Error ? error.message : String(error)}`);
-      if (isHttpAuthError(error)) this.recoverRuntimeTokenAfterAuthFailure("insights");
-    }
+      },
+    });
+    this.sessionLog(`insights: context_ratio ${analysis.metric.ratio.toFixed(2)} (${analysis.metric.gatheringCalls}/${analysis.metric.totalToolCalls} gathering) queued`);
   }
 
   // Route a provider-emitted session event (Codex app-server) into the chat mirror.
@@ -1078,13 +1165,9 @@ export class AgentRunner {
       if (pendingPrompt) {
         replyToMessageId = pendingPrompt;
         this.pendingPromptMessageId = undefined;
-      } else {
-        try {
-          const obligations = await this.http.listReplyObligations(this.agentId);
-          if (obligations.some((o) => o.from === "user")) return;
-        } catch {
-          // capture anyway on lookup failure
-        }
+      } else if (this.obligationCache.get().some((o) => o.from === "user")) {
+        // The agent will answer the relay obligation itself — don't double-post (#196).
+        return;
       }
       await this.publishSessionEvent({
         from: this.agentId,
@@ -1363,36 +1446,24 @@ export class AgentRunner {
     this.logRunnerDiagnostic(`[runner] HTTP liveness update failed: ${suffix}`);
   }
 
+  // Runner operational diagnostics (HTTP liveness, token renewal failures). Routed
+  // through the leveled logger at warn — see logger.ts. Kept as a thin wrapper so
+  // the existing call sites and their `[runner]` framing stay put.
   private logRunnerDiagnostic(message: string): void {
-    if (this.options.headless) {
-      console.error(message);
-      return;
-    }
-    try {
-      const logDir = join(process.env.HOME || ".", ".agent-relay", "logs");
-      mkdirSync(logDir, { recursive: true });
-      appendFileSync(join(logDir, `runner-${safeLogName(this.agentId)}.log`), `[${new Date().toISOString()}] ${message}\n`);
-    } catch {
-      // Do not write runner diagnostics into an interactive provider TUI.
-    }
+    logger.warn("runner", message.replace(/^\[runner\]\s*/, ""));
   }
 
-  // Session-mirror diagnostics → a dedicated, ANSI-free, greppable log per agent
-  // (NOT the provider's TUI stdout, which is unreadable). This is the single place
-  // to look when chat/terminal sync misbehaves. Key transitions always log here.
+  // Session-mirror diagnostics → the leveled logger (component "mirror"), written
+  // to the dashboard-surfaced session-mirror-<agent>.log. Key transitions log at
+  // info; the single place to look when chat/terminal sync misbehaves.
   private sessionLog(message: string): void {
-    try {
-      const logDir = join(process.env.HOME || ".", ".agent-relay", "logs");
-      mkdirSync(logDir, { recursive: true });
-      appendFileSync(join(logDir, `session-mirror-${safeLogName(this.agentId)}.log`), `[${new Date().toISOString()}] ${message}\n`);
-    } catch {
-      // best-effort
-    }
+    logger.info("mirror", message);
   }
 
-  // Verbose, high-frequency lines (per-probe, per-emit) — only when AGENT_RELAY_SESSION_DEBUG=1.
+  // Verbose, high-frequency lines (per-probe, per-emit) — surfaced only at log
+  // level "debug" (AGENT_RELAY_LOG_LEVEL=debug, or flip live via /log-level).
   private sessionDebug(message: string): void {
-    if (this.sessionDebugVerbose) this.sessionLog(message);
+    logger.debug("mirror", message);
   }
 
   private ensureScratch(): void {
@@ -1657,7 +1728,7 @@ export class AgentRunner {
       })
         .then(() => true)
         .catch((error) => {
-          console.error(`[runner] task ${claim.taskId} completion update failed: ${error}`);
+          logger.error("task", `task ${claim.taskId} completion update failed: ${error}`);
           return false;
         });
       if (!ok) continue;
@@ -1956,16 +2027,17 @@ function isHttpAuthError(error: unknown): boolean {
   return status === 401 || status === 403;
 }
 
+function isHttpStatusError(error: unknown, code: number): boolean {
+  const status = typeof error === "object" && error !== null ? (error as { status?: unknown }).status : undefined;
+  return status === code;
+}
+
 function httpErrorKey(error: unknown): string {
   const status = typeof error === "object" && error !== null ? (error as { status?: unknown }).status : undefined;
   if (typeof status === "number") return `status:${status}`;
   return String(error);
 }
 
-function safeLogName(value: string): string {
-  return value.replace(/[^a-zA-Z0-9_.-]+/g, "_").slice(0, 180);
-}
-
 function isContextState(value: unknown): value is ContextState {
   if (!value || typeof value !== "object" || Array.isArray(value)) return false;
   const state = value as Record<string, unknown>;