agent-relay-server 0.94.3 → 0.94.5

package/docs/openapi.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.94.3",
+  "version": "0.94.5",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",
@@ -38,12 +38,13 @@
     "ajv": "^8.20.0"
   },
   "scripts": {
-    "prepack": "bun run build:dashboard:bundle >&2",
+    "prepack": "bun run build:claude-monitor >&2 && bun run build:dashboard:bundle >&2",
     "postinstall": "node scripts/install-bin-shim.cjs",
     "start": "bun run src/index.ts",
     "dev": "bun --watch run src/index.ts",
     "dev:dashboard": "cd dashboard && bun run dev",
     "build:sdk": "cd sdk && bun run build",
+    "build:claude-monitor": "bun run scripts/build-claude-monitor.ts",
     "build:dashboard": "bun run build:dashboard:bundle && bun run deploy:dashboard",
     "build:dashboard:bundle": "bun run build:sdk && cd dashboard && bun run build",
     "deploy:dashboard": "bun run scripts/deploy-dashboard.ts",

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

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

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

@@ -0,0 +1,908 @@
+// @bun
+// sdk/src/types/guards.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// sdk/src/types/constants.ts
+var DEFAULT_RELAY_PORT = 4850;
+var DEFAULT_RELAY_URL = `http://127.0.0.1:${DEFAULT_RELAY_PORT}`;
+// sdk/src/provider-catalog.ts
+var CLAUDE_LOW_TO_MAX = ["low", "medium", "high", "max"];
+var CLAUDE_LOW_TO_XHIGH_MAX = ["low", "medium", "high", "xhigh", "max"];
+var CODEX_REASONING = ["low", "medium", "high", "xhigh"];
+var CONTEXT_200K = { value: 200000, source: "catalog", confidence: "declared" };
+var CONTEXT_1M = { value: 1e6, source: "catalog", confidence: "declared" };
+var CODE_MODEL_CAPABILITIES = {
+  modalities: {
+    input: { text: true, image: true },
+    output: { text: true }
+  },
+  tools: {
+    code: true,
+    review: true,
+    debug: true,
+    refactor: true
+  },
+  source: "catalog",
+  confidence: "declared"
+};
+function codeModel(limits) {
+  return {
+    ...limits ? { limits } : {},
+    capabilities: CODE_MODEL_CAPABILITIES
+  };
+}
+var PROVIDER_CATALOG = {
+  claude: {
+    provider: "claude",
+    label: "Claude Code",
+    defaultModel: "sonnet-4.6",
+    models: [
+      { alias: "fable-5", label: "Fable 5", providerModel: "claude-fable-5", efforts: CLAUDE_LOW_TO_XHIGH_MAX, defaultEffort: "medium", unavailable: "suspended by export-control directive, 2026-06-12", ...codeModel({ contextWindowTokens: CONTEXT_1M }) },
+      { alias: "opus-4.8", label: "Opus 4.8", providerModel: "claude-opus-4-8", efforts: CLAUDE_LOW_TO_XHIGH_MAX, defaultEffort: "medium", ...codeModel({ contextWindowTokens: CONTEXT_200K }) },
+      { alias: "opus-4.8[1m]", label: "Opus 4.8 1M", providerModel: "claude-opus-4-8[1m]", efforts: CLAUDE_LOW_TO_XHIGH_MAX, defaultEffort: "medium", ...codeModel({ contextWindowTokens: CONTEXT_1M }) },
+      { alias: "opus-4.7", label: "Opus 4.7", providerModel: "claude-opus-4-7", efforts: CLAUDE_LOW_TO_XHIGH_MAX, defaultEffort: "medium", ...codeModel({ contextWindowTokens: CONTEXT_200K }) },
+      { alias: "opus-4.7[1m]", label: "Opus 4.7 1M", providerModel: "claude-opus-4-7[1m]", efforts: CLAUDE_LOW_TO_XHIGH_MAX, defaultEffort: "medium", ...codeModel({ contextWindowTokens: CONTEXT_1M }) },
+      { alias: "opus-4.6", label: "Opus 4.6", providerModel: "claude-opus-4-6", efforts: CLAUDE_LOW_TO_MAX, defaultEffort: "medium", ...codeModel({ contextWindowTokens: CONTEXT_200K }) },
+      { alias: "opus-4.6[1m]", label: "Opus 4.6 1M", providerModel: "claude-opus-4-6[1m]", efforts: CLAUDE_LOW_TO_MAX, defaultEffort: "medium", ...codeModel({ contextWindowTokens: CONTEXT_1M }) },
+      { alias: "sonnet-4.6", label: "Sonnet 4.6", providerModel: "claude-sonnet-4-6", efforts: CLAUDE_LOW_TO_MAX, defaultEffort: "medium", ...codeModel({ contextWindowTokens: CONTEXT_200K }) },
+      { alias: "sonnet-4.6[1m]", label: "Sonnet 4.6 1M", providerModel: "claude-sonnet-4-6[1m]", efforts: CLAUDE_LOW_TO_MAX, defaultEffort: "medium", ...codeModel({ contextWindowTokens: CONTEXT_1M }) },
+      { alias: "haiku", label: "Haiku", providerModel: "haiku", efforts: [], ...codeModel() }
+    ]
+  },
+  codex: {
+    provider: "codex",
+    label: "Codex",
+    defaultModel: "gpt-5.5",
+    models: [
+      { alias: "gpt-5.5", label: "GPT-5.5", providerModel: "gpt-5.5", efforts: CODEX_REASONING, defaultEffort: "medium", ...codeModel({ contextWindowTokens: CONTEXT_200K }) },
+      { alias: "gpt-5.4", label: "GPT-5.4", providerModel: "gpt-5.4", efforts: CODEX_REASONING, defaultEffort: "medium", ...codeModel({ contextWindowTokens: CONTEXT_200K }) },
+      { alias: "gpt-5.4-mini", label: "GPT-5.4 Mini", providerModel: "gpt-5.4-mini", efforts: CODEX_REASONING, defaultEffort: "medium", ...codeModel({ contextWindowTokens: CONTEXT_200K }) },
+      { alias: "gpt-5.3-codex", label: "GPT-5.3 Codex", providerModel: "gpt-5.3-codex", efforts: CODEX_REASONING, defaultEffort: "medium", ...codeModel({ contextWindowTokens: CONTEXT_200K }) },
+      { alias: "gpt-5.3-codex-spark", label: "GPT-5.3 Codex Spark", providerModel: "gpt-5.3-codex-spark", efforts: CODEX_REASONING, defaultEffort: "high", ...codeModel({ contextWindowTokens: CONTEXT_200K }) },
+      { alias: "gpt-5.2", label: "GPT-5.2", providerModel: "gpt-5.2", efforts: CODEX_REASONING, defaultEffort: "medium", ...codeModel({ contextWindowTokens: CONTEXT_200K }) }
+    ]
+  }
+};
+// sdk/src/reconnect.ts
+import { setTimeout as delay } from "timers/promises";
+var DEFAULTS = {
+  initialMs: 1000,
+  maxMs: 30000,
+  jitterMs: 500
+};
+
+class ReconnectionManager {
+  attempts = 0;
+  abort;
+  options;
+  constructor(options = {}) {
+    this.options = {
+      initialMs: options.initialMs ?? DEFAULTS.initialMs,
+      maxMs: options.maxMs ?? DEFAULTS.maxMs,
+      jitterMs: options.jitterMs ?? DEFAULTS.jitterMs
+    };
+  }
+  get attempt() {
+    return this.attempts;
+  }
+  nextDelay() {
+    const base = Math.min(this.options.maxMs, this.options.initialMs * 2 ** this.attempts);
+    this.attempts += 1;
+    const jitter = this.options.jitterMs > 0 ? Math.floor(Math.random() * (this.options.jitterMs + 1)) : 0;
+    return Math.min(this.options.maxMs, base + jitter);
+  }
+  reset() {
+    this.attempts = 0;
+    this.cancel();
+  }
+  async schedule() {
+    this.cancel();
+    this.abort = new AbortController;
+    const ms = this.nextDelay();
+    await delay(ms, undefined, { signal: this.abort.signal }).catch((error) => {
+      if (error.name !== "AbortError")
+        throw error;
+    });
+  }
+  cancel() {
+    this.abort?.abort();
+    this.abort = undefined;
+  }
+}
+// sdk/src/config.ts
+function relayTokenFromEnv() {
+  return process.env.AGENT_RELAY_TOKEN;
+}
+// sdk/src/bus-client.ts
+import { EventEmitter } from "events";
+class MemoryCursorStore {
+  value = null;
+  async load() {
+    return this.value;
+  }
+  async save(cursor) {
+    this.value = cursor;
+  }
+}
+
+class RelayBusClient extends EventEmitter {
+  options;
+  ws = null;
+  registeredEpoch = 0;
+  lastCursor = 0;
+  serverCursor = 0;
+  closed = false;
+  connecting = null;
+  heartbeat;
+  heartbeatWatchdog;
+  pendingHeartbeatId;
+  pendingHeartbeatSentAt;
+  lastServerFrameAt = 0;
+  lastHeartbeatAckAt = 0;
+  heartbeatAckSupported = false;
+  semanticStatus;
+  transport = { connected: false, reconnecting: false };
+  reconnect;
+  cursorStore;
+  subscriptions = new Set(["message.*", "agent.status", "task.*"]);
+  pending = new Map;
+  constructor(options) {
+    super();
+    this.options = options;
+    this.reconnect = new ReconnectionManager({
+      initialMs: options.reconnect?.initialMs,
+      maxMs: options.reconnect?.maxMs,
+      jitterMs: options.reconnect?.jitterMs
+    });
+    this.cursorStore = options.cursorStore ?? new MemoryCursorStore;
+    this.semanticStatus = options.initialStatus ?? "idle";
+  }
+  get connected() {
+    return this.ws?.readyState === WebSocket.OPEN && this.registeredEpoch > 0;
+  }
+  get epoch() {
+    return this.registeredEpoch;
+  }
+  get cursor() {
+    return this.lastCursor;
+  }
+  get transportState() {
+    return { ...this.transport };
+  }
+  async connect() {
+    if (this.connecting)
+      return this.connecting;
+    this.closed = false;
+    this.connecting = this.connectLoop().finally(() => {
+      this.connecting = null;
+    });
+    return this.connecting;
+  }
+  async close() {
+    this.closed = true;
+    this.stopHeartbeat();
+    this.stopHeartbeatWatchdog();
+    this.reconnect.cancel();
+    for (const pending of this.pending.values())
+      pending.reject(new Error("bus client closed"));
+    this.pending.clear();
+    if (this.ws && this.ws.readyState <= WebSocket.OPEN)
+      this.ws.close();
+    this.ws = null;
+  }
+  setToken(token) {
+    this.options.token = token;
+  }
+  reconnectTransport(reason = "client requested reconnect") {
+    this.forceReconnect(reason, { emitError: false, code: 4001 });
+  }
+  status(update) {
+    if (update.agentStatus === "idle" || update.agentStatus === "busy")
+      this.semanticStatus = update.agentStatus;
+    this.send({
+      type: "status",
+      payload: {
+        agentStatus: update.agentStatus,
+        ready: update.ready,
+        meta: update.meta
+      }
+    });
+  }
+  async statusAsync(update) {
+    this.status(update);
+    await Promise.resolve();
+  }
+  setSemanticStatus(status) {
+    this.semanticStatus = status;
+  }
+  updateCommand(commandId, params) {
+    return this.command("command.update", commandId, params);
+  }
+  command(type, target, params) {
+    const id = crypto.randomUUID();
+    this.send({ type: "command", id, payload: { commandType: type, target, params } });
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+    });
+  }
+  async subscribe(events, scopes) {
+    for (const event of events)
+      this.subscriptions.add(event);
+    const id = crypto.randomUUID();
+    this.send({ type: "subscribe", id, payload: { events, scopes } });
+    await Promise.resolve();
+  }
+  on(event, listener) {
+    return super.on(event, listener);
+  }
+  off(event, listener) {
+    return super.off(event, listener);
+  }
+  once(event, listener) {
+    return super.once(event, listener);
+  }
+  async connectLoop() {
+    while (!this.closed) {
+      try {
+        await this.openOnce();
+        this.reconnect.reset();
+        return;
+      } catch (error) {
+        if (this.closed)
+          throw error;
+        const delayMs = this.reconnect.nextDelay();
+        this.transport = { ...this.transport, connected: false, reconnecting: true };
+        this.emit("reconnecting", this.reconnect.attempt, delayMs);
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+      }
+    }
+  }
+  async openOnce() {
+    const cursor = await this.cursorStore.load();
+    if (cursor !== null)
+      this.lastCursor = cursor;
+    await new Promise((resolve, reject) => {
+      const ws = new WebSocket(this.wsUrl());
+      this.ws = ws;
+      let resolved = false;
+      ws.onopen = () => {
+        if (this.ws !== ws)
+          return;
+        const now = Date.now();
+        this.lastServerFrameAt = now;
+        this.transport = { ...this.transport, connected: true, reconnecting: false, lastConnectedAt: now, lastServerFrameAt: now, reconnectReason: undefined };
+        this.emit("connected");
+        this.sendRegister();
+      };
+      ws.onmessage = (message) => {
+        if (this.ws !== ws)
+          return;
+        this.handleMessage(message.data, () => {
+          if (!resolved) {
+            resolved = true;
+            resolve();
+          }
+        });
+      };
+      ws.onerror = () => {
+        if (this.ws !== ws)
+          return;
+        if (!resolved)
+          reject(new Error("bus connection failed"));
+      };
+      ws.onclose = (event) => {
+        if (this.ws !== ws)
+          return;
+        this.stopHeartbeat();
+        this.stopHeartbeatWatchdog();
+        this.registeredEpoch = 0;
+        this.heartbeatAckSupported = false;
+        this.transport = { ...this.transport, connected: false, reconnecting: !this.closed, lastDisconnectedAt: Date.now() };
+        const reason = event.reason || `closed:${event.code}`;
+        this.emit("disconnected", reason);
+        if (!resolved) {
+          resolved = true;
+          reject(new Error(reason));
+          return;
+        }
+        if (!this.closed)
+          this.connect();
+      };
+    });
+  }
+  sendRegister() {
+    this.send({
+      type: "register",
+      id: crypto.randomUUID(),
+      payload: {
+        role: this.options.role,
+        componentId: this.options.componentId,
+        agentId: this.options.agentId,
+        instanceId: this.options.instanceId,
+        capabilities: this.options.capabilities ?? [],
+        tags: this.options.tags ?? [],
+        machine: this.options.machine ?? "unknown",
+        meta: this.registrationMeta()
+      }
+    });
+  }
+  async handleMessage(data, onRegistered) {
+    this.recordServerFrame();
+    let frame;
+    try {
+      frame = JSON.parse(typeof data === "string" ? data : String(data));
+    } catch {
+      this.emit("error", "INVALID_JSON", "server sent invalid JSON");
+      return;
+    }
+    if (frame.type === "registered") {
+      const payload = frame.payload;
+      const resumeFrom = this.lastCursor;
+      this.registeredEpoch = payload.epoch;
+      this.serverCursor = payload.cursor;
+      this.heartbeatAckSupported = payload.features?.heartbeatAck === true;
+      this.emit("registered", payload.epoch, payload.cursor);
+      this.send({ type: "subscribe", id: crypto.randomUUID(), payload: { events: [...this.subscriptions] } });
+      if (resumeFrom > 0 && resumeFrom < payload.cursor) {
+        this.send({ type: "resume", id: crypto.randomUUID(), payload: { since: resumeFrom } });
+      } else {
+        this.lastCursor = payload.cursor;
+        await this.cursorStore.save(this.lastCursor);
+      }
+      this.startHeartbeat();
+      if (this.heartbeatAckSupported)
+        this.startHeartbeatWatchdog();
+      else
+        this.stopHeartbeatWatchdog();
+      onRegistered();
+      return;
+    }
+    if (frame.type === "ack") {
+      if (frame.payload.frameId === this.pendingHeartbeatId) {
+        this.lastHeartbeatAckAt = Date.now();
+        this.pendingHeartbeatId = undefined;
+        this.pendingHeartbeatSentAt = undefined;
+        this.transport = { ...this.transport, lastHeartbeatAckAt: this.lastHeartbeatAckAt };
+      }
+      return;
+    }
+    if (frame.type === "event") {
+      await this.handleEvent(frame.payload);
+      return;
+    }
+    if (frame.type === "resumed") {
+      for (const event of frame.payload.events)
+        await this.handleEvent(event);
+      return;
+    }
+    if (frame.type === "command.result") {
+      const pending = this.pending.get(frame.payload.commandId);
+      if (!pending)
+        return;
+      this.pending.delete(frame.payload.commandId);
+      if (frame.payload.status === "succeeded")
+        pending.resolve(frame.payload.result ?? null);
+      else
+        pending.reject(new Error(frame.payload.error || frame.payload.status));
+      return;
+    }
+    if (frame.type === "error") {
+      const error = frame;
+      if (error.payload.code === "REPLAY_GAP") {
+        await this.options.reconcile?.();
+        this.lastCursor = this.serverCursor;
+        await this.cursorStore.save(this.lastCursor);
+      }
+      this.emit("error", error.payload.code, error.payload.message);
+      if (error.payload.frameId) {
+        const pending = this.pending.get(error.payload.frameId);
+        if (pending) {
+          this.pending.delete(error.payload.frameId);
+          pending.reject(new Error(error.payload.message));
+        }
+      }
+    }
+  }
+  async handleEvent(event) {
+    this.lastCursor = Math.max(this.lastCursor, event.seq);
+    await this.cursorStore.save(this.lastCursor);
+    this.emit("event", event.eventType, event.data, event.seq);
+    if (event.eventType === "command.requested") {
+      const command = isRecord(event.data.command) ? event.data.command : undefined;
+      if (command) {
+        const commandType = typeof command.type === "string" ? command.type : "";
+        const commandId = typeof command.id === "string" ? command.id : "";
+        const params = isRecord(command.params) ? command.params : {};
+        this.emit("command", commandType, params, commandId, command);
+      }
+    }
+    this.emit(event.eventType, event.data);
+    if (event.eventType.startsWith("task."))
+      this.emit("task.changed", event.data);
+  }
+  startHeartbeat() {
+    this.stopHeartbeat();
+    this.sendHeartbeat();
+    this.heartbeat = setInterval(() => {
+      this.sendHeartbeat();
+    }, this.options.heartbeatIntervalMs ?? 30000);
+  }
+  stopHeartbeat() {
+    if (this.heartbeat)
+      clearInterval(this.heartbeat);
+    this.heartbeat = undefined;
+    this.pendingHeartbeatId = undefined;
+    this.pendingHeartbeatSentAt = undefined;
+  }
+  startHeartbeatWatchdog() {
+    this.stopHeartbeatWatchdog();
+    const intervalMs = Math.max(100, Math.min(5000, this.heartbeatIntervalMs()));
+    this.heartbeatWatchdog = setInterval(() => this.checkHeartbeatAck(), intervalMs);
+  }
+  stopHeartbeatWatchdog() {
+    if (this.heartbeatWatchdog)
+      clearInterval(this.heartbeatWatchdog);
+    this.heartbeatWatchdog = undefined;
+  }
+  sendHeartbeat() {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN || !this.registeredEpoch)
+      return;
+    const now = Date.now();
+    const expectAck = this.heartbeatAckSupported;
+    if (expectAck && this.pendingHeartbeatId && this.pendingHeartbeatSentAt && now - this.pendingHeartbeatSentAt < this.heartbeatIntervalMs())
+      return;
+    const id = expectAck ? crypto.randomUUID() : undefined;
+    const meta = this.heartbeatMeta();
+    if (expectAck && id) {
+      this.pendingHeartbeatId = id;
+      if (!this.pendingHeartbeatSentAt)
+        this.pendingHeartbeatSentAt = now;
+    }
+    this.send({ type: "heartbeat", ...id ? { id } : {}, payload: { status: this.semanticStatus, ...meta ? { meta } : {} } });
+  }
+  checkHeartbeatAck() {
+    if (!this.pendingHeartbeatSentAt || !this.ws || this.ws.readyState !== WebSocket.OPEN)
+      return;
+    const ageMs = Date.now() - this.pendingHeartbeatSentAt;
+    if (ageMs <= this.heartbeatAckTimeoutMs())
+      return;
+    this.forceReconnect(`heartbeat ack timeout after ${ageMs}ms`, { emitError: true, code: 4000 });
+  }
+  forceReconnect(reason, opts) {
+    if (this.closed)
+      return;
+    this.transport = { ...this.transport, connected: false, reconnecting: true, lastDisconnectedAt: Date.now(), reconnectReason: reason };
+    if (opts.emitError)
+      this.emit("error", "HEARTBEAT_TIMEOUT", reason);
+    this.stopHeartbeat();
+    this.stopHeartbeatWatchdog();
+    const ws = this.ws;
+    this.ws = null;
+    this.registeredEpoch = 0;
+    this.heartbeatAckSupported = false;
+    if (ws && ws.readyState <= WebSocket.OPEN)
+      ws.close(opts.code, reason.slice(0, 120));
+    this.connect();
+  }
+  heartbeatIntervalMs() {
+    return this.options.heartbeatIntervalMs ?? 30000;
+  }
+  heartbeatAckTimeoutMs() {
+    return this.options.heartbeatAckTimeoutMs ?? Math.max(1e4, Math.ceil(this.heartbeatIntervalMs() * 1.5));
+  }
+  recordServerFrame() {
+    this.lastServerFrameAt = Date.now();
+    this.transport = { ...this.transport, lastServerFrameAt: this.lastServerFrameAt };
+  }
+  send(frame) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
+      return;
+    this.ws.send(JSON.stringify(frame));
+  }
+  wsUrl() {
+    const url = new URL(this.options.url);
+    const token = this.options.token ?? relayTokenFromEnv();
+    if (token && !url.searchParams.has("token"))
+      url.searchParams.set("token", token);
+    return url.toString();
+  }
+  registrationMeta() {
+    return {
+      ...this.options.meta ?? {},
+      ...this.options.providerCapabilities ? { providerCapabilities: this.options.providerCapabilities } : {},
+      ...this.options.context ? { context: this.options.context } : {}
+    };
+  }
+  heartbeatMeta() {
+    const dynamic = this.options.heartbeatMeta?.();
+    const meta = {
+      ...dynamic ?? {},
+      ...this.options.providerCapabilities ? { providerCapabilities: this.options.providerCapabilities } : {},
+      ...this.options.context ? { context: this.options.context } : {}
+    };
+    return Object.keys(meta).length ? meta : undefined;
+  }
+}
+// sdk/src/provider-base.ts
+class ProviderBase {
+  options;
+  client;
+  running = false;
+  pending = new Map;
+  drain;
+  constructor(options) {
+    this.options = options;
+    this.client = new RelayBusClient({
+      url: options.relayUrl,
+      role: "provider",
+      componentId: `${options.adapter.providerName}:${options.agentId}`,
+      agentId: options.agentId,
+      instanceId: options.instanceId,
+      token: options.token,
+      capabilities: options.adapter.capabilities,
+      tags: options.tags ?? [options.adapter.providerName],
+      machine: options.machine,
+      meta: { provider: options.adapter.providerName, ...options.meta ?? {} }
+    });
+  }
+  async run() {
+    if (this.running)
+      return;
+    this.running = true;
+    this.client.on("message.new", (message) => this.queueMessage(message));
+    await this.client.connect();
+    this.startStatusLoop();
+  }
+  async stop() {
+    this.running = false;
+    if (this.drain)
+      clearInterval(this.drain);
+    this.drain = undefined;
+    await this.client.close();
+  }
+  queueMessage(message) {
+    if (message.to !== this.options.agentId && message.to !== "broadcast" && !message.to.startsWith("tag:") && !message.to.startsWith("cap:") && !message.to.startsWith("label:") && !message.to.startsWith("team:")) {
+      return;
+    }
+    this.pending.set(message.id, message);
+    this.drainMessages();
+  }
+  async drainMessages() {
+    if (!this.running || this.pending.size === 0)
+      return;
+    const messages2 = [...this.pending.values()].sort((a, b) => a.id - b.id);
+    this.pending.clear();
+    await this.options.adapter.deliverMessage(this.options.agentId, messages2);
+  }
+  startStatusLoop() {
+    this.drain = setInterval(async () => {
+      if (!this.running)
+        return;
+      try {
+        const status = await this.options.adapter.getAgentStatus(this.options.agentId);
+        this.client.status({ agentStatus: status, ready: true });
+      } catch {
+        this.client.status({ agentStatus: "online", ready: false });
+      }
+    }, 30000);
+  }
+}
+// sdk/src/claim-tracker.ts
+class WorkClaimTracker {
+  providerActive = false;
+  claims = new Map;
+  setProviderActive(active) {
+    this.providerActive = active;
+  }
+  start(kind, id, expiresAt) {
+    this.claims.set(`${kind}:${id}`, { kind, id, startedAt: Date.now(), expiresAt });
+  }
+  finish(kind, id) {
+    this.claims.delete(`${kind}:${id}`);
+  }
+  expire(now = Date.now()) {
+    for (const [key, claim] of this.claims) {
+      if (claim.expiresAt !== undefined && claim.expiresAt <= now)
+        this.claims.delete(key);
+    }
+  }
+  status() {
+    return this.providerActive || this.claims.size > 0 ? "busy" : "idle";
+  }
+  active() {
+    return [...this.claims.values()];
+  }
+}
+// sdk/src/process-utils.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+// sdk/src/teams-config.ts
+var TEAM_IDLE_THRESHOLD_MINUTES_MAX = 24 * 60;
+// runner/src/config.ts
+function messageBodyMaxCharsFromEnv() {
+  return process.env.AGENT_RELAY_MESSAGE_BODY_MAX_CHARS;
+}
+
+// runner/src/relay-instructions.ts
+var CLAUDE_RELAY_CONTEXT = `[agent-relay] Relay is available. Follow the Agent Relay rules in CLAUDE.md when present, or run agent-relay /guide. Reply through Relay only when a response is needed; do not send status-only follow-ups after the useful Relay response was already delivered.`;
+var CLAUDE_READ_ONLY_RELAY_CONTEXT = `${CLAUDE_RELAY_CONTEXT}
+
+This Claude session is running with restricted read-only Relay permissions. Do not invoke Agent Relay skills. If you need to reply, use this Bash command shape:
+
+agent-relay /reply <messageId> "<your reply>"`;
+function relayReplyActionText(messageId) {
+  return `relay_reply (messageId: ${messageId}, body: "<your reply>"). CLI fallback: agent-relay /reply ${messageId} "<your reply>"`;
+}
+function relayReplyReminderText(messageId) {
+  return `If this batch needs a response, send one useful reply to the latest relevant message with ${relayReplyActionText(messageId)}`;
+}
+function workspaceDepsNote(input) {
+  if (input.mode !== "isolated")
+    return "";
+  switch (input.depsMode) {
+    case "symlink":
+      return "[agent-relay] Isolated workspace: this is a git worktree, and its node_modules are SYMLINKED from the main checkout \u2014 dependencies are already installed and ready to use. Do NOT run a clean dependency install (`bun install` / `npm install` / `pnpm install`): it writes through the symlink and mutates the main checkout's shared node_modules. Build caches written under node_modules are shared too. If typecheck/build fails on a missing module (a dependency added to the base AFTER this worktree was created), run `agent-relay workspace deps` \u2014 it re-provisions only the stale dirs with a real isolated install, safely, without touching the shared node_modules. If you genuinely need to change dependencies in isolation, ask the host to spawn with AGENT_RELAY_WORKSPACE_DEPS=install.";
+    case "none":
+      return "[agent-relay] Isolated workspace: dependencies were not provisioned (AGENT_RELAY_WORKSPACE_DEPS=none). You may need to install node_modules before typecheck/test/build work.";
+    default:
+      return "";
+  }
+}
+function workspaceLifecycleNote(input) {
+  if (input.mode !== "isolated")
+    return "";
+  const branch = input.branch ? `\`${input.branch}\`` : "an isolated agent branch";
+  const base = input.baseRef ? `\`${input.baseRef}\`` : "the base branch";
+  return [
+    `[agent-relay] Isolated workspace: you are in a git worktree on branch ${branch}, based on ${base} \u2014 NOT the main checkout. Other agents may work in parallel and land to ${base}, so ${base} will move under you. That is expected; don't fight it.`,
+    `Do NOT push this branch yourself \u2014 not with \`git push\`, not with \`tl push\` or any other push wrapper, and do not manually rebase or merge. A steward may be auto-rebasing this branch in the background; pushing concurrently races it and can leave the worktree mid-rebase. Just commit your work here. When the task is done, run \`agent-relay workspace ready\` \u2014 Relay rebases onto the latest ${base}, lands your work, and pushes for you. If the installed \`agent-relay\` binary is stale and says the workspace command is unknown, run the repo-local fallback: \`bun src/index.ts workspace ready\`.`,
+    `After \`ready\`, the status becomes \`review_requested\` \u2014 this is the NORMAL, healthy hand-off state, NOT an escalation or a stall. Relay auto-merges clean rebases roughly every 2 minutes; a steward agent is spawned (after a short delay) ONLY if it can't land deterministically, so seeing no steward means it's working, not stuck. Stop your turn after \`ready\` and go idle; do NOT wait or poll the steward queue. Relay wakes you with \`landed-success\` when your branch lands and refreshes, or \`landed-failure\` if landing fatally fails. On success you'll be on a fresh rebased branch whose name gains a \`--N\` suffix \u2014 expected, keep working there. Never \`cd\` into the main checkout, and never merge/push/resolve conflicts yourself \u2014 Relay and the steward own all of that. \`agent-relay workspace status\` anytime shows your current state and the exact next step.`
+  ].join(`
+`);
+}
+function workspaceSymlinksNote(linked) {
+  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 \u2014 treat them as read-only unless you intend to change main.`;
+}
+function workspaceDepsNoteFromEnv(env = process.env) {
+  const json = env.AGENT_RELAY_WORKSPACE_JSON;
+  if (!json)
+    return "";
+  try {
+    const parsed = JSON.parse(json);
+    return [
+      workspaceLifecycleNote({ mode: parsed.mode ?? null, branch: parsed.branch ?? null, baseRef: parsed.baseRef ?? null }),
+      workspaceDepsNote({ mode: parsed.mode ?? null, depsMode: parsed.deps?.mode ?? null }),
+      parsed.mode === "isolated" ? workspaceSymlinksNote(parsed.symlinks?.linked ?? []) : ""
+    ].filter(Boolean).join(`
+
+`);
+  } catch {
+    return "";
+  }
+}
+
+// runner/src/adapter.ts
+var DEFAULT_PROVIDER_MESSAGE_BODY_MAX_CHARS = 24000;
+function providerMessageBodyMaxChars() {
+  const raw = messageBodyMaxCharsFromEnv();
+  if (raw !== undefined) {
+    const parsed = Number.parseInt(raw.trim(), 10);
+    if (Number.isFinite(parsed) && parsed > 0)
+      return parsed;
+  }
+  return DEFAULT_PROVIDER_MESSAGE_BODY_MAX_CHARS;
+}
+function attachmentRefs(message) {
+  const payloadRefs = message.payload?.attachments;
+  const topLevelRefs = message.attachments;
+  const refs = Array.isArray(payloadRefs) ? payloadRefs : Array.isArray(topLevelRefs) ? topLevelRefs : [];
+  return refs.filter(isRecord);
+}
+function attachmentLabel(ref) {
+  const parts = [
+    typeof ref.kind === "string" ? ref.kind : undefined,
+    typeof ref.role === "string" ? ref.role : undefined,
+    typeof ref.title === "string" ? `"${ref.title}"` : undefined
+  ].filter(Boolean);
+  return parts.length ? ` (${parts.join(", ")})` : "";
+}
+function attachmentCacheMetadata(ref) {
+  const metadata = isRecord(ref.metadata) ? ref.metadata : undefined;
+  const agentRelay = metadata && isRecord(metadata.agentRelay) ? metadata.agentRelay : undefined;
+  return agentRelay;
+}
+function isPersistedRelayMessage(message) {
+  return Number.isSafeInteger(message.id) && message.id > 0;
+}
+var NOTIFICATION_NUDGE = "\u21AA Notification \u2014 no reply needed.";
+function isNotificationMessage(message) {
+  return isPersistedRelayMessage(message) && message.replyExpected === false;
+}
+function providerAttachmentText(message) {
+  const refs = attachmentRefs(message);
+  if (!refs.length)
+    return;
+  const lines = refs.flatMap((ref) => {
+    const artifactId = typeof ref.artifactId === "string" ? ref.artifactId : "unknown-artifact";
+    const source = isRecord(ref.ref) ? [
+      typeof ref.ref.provider === "string" ? ref.ref.provider : undefined,
+      typeof ref.ref.id === "string" ? ref.ref.id : undefined
+    ].filter(Boolean).join(":") : "";
+    const cache = attachmentCacheMetadata(ref);
+    const localPath = typeof cache?.localPath === "string" ? cache.localPath : undefined;
+    const cacheError = typeof cache?.cacheError === "string" ? cache.cacheError : undefined;
+    return [
+      `- ${artifactId}${attachmentLabel(ref)}${source ? ` source=${source}` : ""}`,
+      ...localPath ? [`  local: ${localPath}`] : [],
+      ...cacheError ? [`  cache error: ${cacheError}`] : []
+    ];
+  });
+  const hasLocalPaths = refs.some((ref) => typeof attachmentCacheMetadata(ref)?.localPath === "string");
+  const canFetchMessage = isPersistedRelayMessage(message);
+  const guidance = !canFetchMessage ? [] : hasLocalPaths ? [
+    "Use the local path above when inspecting the attachment.",
+    `Read attachment details: agent-relay get-message ${message.id} --json`
+  ] : [
+    `Read attachment details: agent-relay get-message ${message.id} --json`,
+    `Fetch content: curl -fsS -H "X-Agent-Relay-Token: $AGENT_RELAY_TOKEN" "$AGENT_RELAY_URL/api/artifacts/<artifactId>/content" -o <filename>`
+  ];
+  return [
+    "Attachments:",
+    ...lines,
+    ...guidance
+  ].join(`
+`);
+}
+
+// runner/src/adapters/claude-delivery.ts
+var REMINDER_EVERY_DELIVERIES = 5;
+var TASK_CLAIM_INSTRUCTION = "Claim this task before working it, then update task status when finished.";
+function stripRelayScaffolding(body) {
+  const lines = body.split(`
+`);
+  const popTrailingBlanks = () => {
+    while (lines.length && (lines.at(-1) ?? "").trim() === "")
+      lines.pop();
+  };
+  popTrailingBlanks();
+  if (lines.at(-1) === TASK_CLAIM_INSTRUCTION) {
+    lines.pop();
+    popTrailingBlanks();
+  }
+  return lines.join(`
+`);
+}
+function isMemoryInjection(message) {
+  return isRecord(message.payload) && message.payload.memoryInjection === true;
+}
+function isReactionNotification(message) {
+  const event = isRecord(message.payload?.event) ? message.payload.event : undefined;
+  return message.payload?.reactionNotification === true || event?.type === "message.reaction";
+}
+function isSpawnObligationMessage(message) {
+  return isRecord(message.payload) && message.payload.source === "spawn-obligation";
+}
+function isPersistedRelayMessage2(message) {
+  return Number.isSafeInteger(message.id) && message.id > 0;
+}
+function providerSenderLabel(message) {
+  if (message.from === "user")
+    return "human user";
+  const source = isRecord(message.payload?.source) ? message.payload.source : undefined;
+  const isHumanChannel = Boolean(source && (isRecord(source.telegram) || isRecord(source.slack) || isRecord(source.discord)));
+  return isHumanChannel ? `human user via ${message.from}` : message.from;
+}
+function shouldShowReplyReminder(deliveryCount) {
+  return deliveryCount <= 1 || deliveryCount % REMINDER_EVERY_DELIVERIES === 0;
+}
+function latestReplyableMessage(messages2) {
+  return messages2.filter((message) => isPersistedRelayMessage2(message) && !isMemoryInjection(message) && !isReactionNotification(message) && !isSpawnObligationMessage(message) && message.replyExpected !== false).at(-1);
+}
+function formatMessage(message, relaySurface) {
+  const subject = message.subject ? `Subject: ${message.subject}
+` : "";
+  const isMemoryContext = isMemoryInjection(message);
+  const canFetchMessage = isPersistedRelayMessage2(message);
+  const rawBody = relaySurface ? message.body : stripRelayScaffolding(message.body);
+  const maxChars = providerMessageBodyMaxChars();
+  const shouldPreview = canFetchMessage && rawBody.length > maxChars;
+  const preview = shouldPreview ? {
+    body: rawBody.slice(0, maxChars),
+    truncated: true
+  } : {
+    body: rawBody,
+    truncated: false
+  };
+  const truncationGuidance = preview.truncated ? [
+    `[truncated: showing first ${maxChars} of ${rawBody.length} chars]`,
+    `Read full: agent-relay get-message ${message.id}`,
+    `Body only: agent-relay get-message ${message.id} --body`
+  ].join(`
+`) : undefined;
+  if (isMemoryContext) {
+    return [
+      `[agent-relay context from ${message.from}]`,
+      providerAttachmentText(message),
+      `${subject}${preview.body}`,
+      truncationGuidance
+    ].filter(Boolean).join(`
+`);
+  }
+  return [
+    `[relay message #${message.id} from ${providerSenderLabel(message)}]`,
+    providerAttachmentText(message),
+    `${subject}${preview.body}`,
+    truncationGuidance
+  ].filter(Boolean).join(`
+`);
+}
+function replyReminder(message, readOnly) {
+  const command = readOnly ? `agent-relay /reply ${message.id} "<your reply>"` : relayReplyReminderText(message.id);
+  return [
+    "[agent-relay reply reminder]",
+    readOnly ? `If this batch needs a response, send one useful reply to the latest relevant message: ${command}` : command,
+    "If you already delivered the useful response through Relay, do not send a separate status-only confirmation.",
+    "If multiple messages arrived together, cover them in one reply instead of answering each line separately."
+  ].join(`
+`);
+}
+function claudeProviderMessageText(messages2, options) {
+  const relaySurface = options.relaySurface !== false;
+  const sections = messages2.map((message) => formatMessage(message, relaySurface));
+  const replyable = latestReplyableMessage(messages2);
+  if (relaySurface && replyable && shouldShowReplyReminder(options.deliveryCount)) {
+    sections.push(replyReminder(replyable, options.readOnly === true));
+  } else if (relaySurface && !replyable && messages2.some(isNotificationMessage)) {
+    sections.push(NOTIFICATION_NUDGE);
+  }
+  return sections.join(`
+
+`);
+}
+
+// runner/plugins/claude/monitors/relay-monitor.ts
+var port = process.env.AGENT_RELAY_RUNNER_PORT;
+if (!port)
+  process.exit(0);
+var firstDelivery = true;
+var deliveryCount = 0;
+var ws = new WebSocket(`ws://127.0.0.1:${port}/monitor`);
+ws.onmessage = (event) => {
+  const payload = parsePayload(String(event.data));
+  if (!payload || payload.type !== "message.deliver" || !Array.isArray(payload.messages))
+    return;
+  const messages2 = payload.messages;
+  deliveryCount += 1;
+  if (firstDelivery) {
+    console.log(process.env.AGENT_RELAY_APPROVAL === "read-only" ? CLAUDE_READ_ONLY_RELAY_CONTEXT : CLAUDE_RELAY_CONTEXT);
+    const wsNote = workspaceDepsNoteFromEnv();
+    if (wsNote) {
+      console.log("");
+      console.log(wsNote);
+    }
+    console.log("");
+    firstDelivery = false;
+  }
+  console.log(claudeProviderMessageText(messages2, {
+    deliveryCount,
+    readOnly: process.env.AGENT_RELAY_APPROVAL === "read-only"
+  }));
+  ws.send(JSON.stringify({
+    type: "message.delivered",
+    deliveryId: typeof payload.deliveryId === "string" ? payload.deliveryId : "",
+    messageIds: messages2.map((message) => message.id)
+  }));
+};
+ws.onerror = () => process.exit(1);
+function parsePayload(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}

package/src/db/delivery.ts

@@ -422,6 +422,23 @@ export function resolveQueuedPolicyMessages(policyName: string, agentId: string)
  * Returns the flushed messages so callers can emit `message.available` / `message.new` /
  * `message.delivery_updated` events.
  */
+/**
+ * Distinct direct (agent) targets that have messages still parked at
+ * `queued` older than `minAgeMs`. Backstop for #706: the primary recovery is
+ * flush-on-availability, but if that event is ever missed a queued message is
+ * invisible (pollMessages excludes `queued`) until it expires. The periodic
+ * resweep uses this to re-resolve such messages once the target is available.
+ */
+export function listStaleQueuedDirectTargets(now: number = Date.now(), minAgeMs = 60_000): string[] {
+  const rows = getDb().query(`
+    SELECT DISTINCT to_target FROM messages
+    WHERE delivery_status = 'queued'
+      AND to_target IS NOT NULL
+      AND COALESCE(queued_at, created_at) <= ?
+  `).all(now - minAgeMs) as Array<{ to_target: string }>;
+  return rows.map((row) => row.to_target);
+}
+
 export function resolveQueuedDirectMessages(agentId: string): Message[] {
   const rows = getDb().query(`
     SELECT m.id
@@ -451,6 +468,21 @@ export function resolveQueuedDirectMessages(agentId: string): Message[] {
   return ids.map((id) => getMessage(id)).filter((message): message is Message => Boolean(message));
 }
 
+/**
+ * Count messages that expired undelivered at max_age within the trailing
+ * `windowMs` (default 24h). Surfaces silent channel data loss (#706) — a queued
+ * message that died without ever reaching its recipient — as a health signal.
+ */
+export function countExpiredUndeliveredMessages(now: number = Date.now(), windowMs = 86_400_000): number {
+  return (getDb().query(`
+    SELECT COUNT(*) as c FROM messages
+    WHERE delivery_status = 'dead'
+      AND delivery_poison_reason = 'queued message expired'
+      AND delivery_updated_at IS NOT NULL
+      AND delivery_updated_at >= ?
+  `).get(now - windowMs) as { c: number }).c;
+}
+
 export function expireQueuedMessages(now: number = Date.now()): Message[] {
   const rows = getDb().query(`
     SELECT id FROM messages

package/src/db/provisioning-registry.ts

@@ -462,14 +462,16 @@ function readBundledFiles(root: string): BundledFile[] {
     const entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
     for (const entry of entries) {
       const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      const cleanRel = cleanRelativePath(rel, "file path");
+      if (root === BUNDLED_CLAUDE_PLUGIN_DIR && cleanRel === "monitors/relay-monitor.provisioned.mjs") continue;
       const abs = join(dir, entry.name);
       if (entry.isDirectory()) {
         visit(abs, rel);
         continue;
       }
       if (!entry.isFile()) continue;
-      const content = readFileSync(abs, "utf8");
-      files.push({ path: cleanRelativePath(rel, "file path"), content, size: Buffer.byteLength(content, "utf8") });
+      const content = root === BUNDLED_CLAUDE_PLUGIN_DIR && cleanRel === "monitors/relay-monitor.ts" ? readFileSync(join(root, "monitors/relay-monitor.provisioned.mjs"), "utf8") : readFileSync(abs, "utf8");
+      files.push({ path: cleanRel, content, size: Buffer.byteLength(content, "utf8") });
     }
   };
   visit(root);

package/src/db/stats.ts

@@ -16,6 +16,7 @@ import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_ME
 import { matchAgents } from "../agent-ref";
 import { listAgents } from "./agents.ts";
 import { listChannels } from "./channels.ts";
+import { countExpiredUndeliveredMessages } from "./delivery.ts";
 import { messageTaskClosed } from "./claim-sql.ts";
 import { getDb } from "./connection.ts";
 import type {
@@ -466,6 +467,37 @@ export function getHealth(now: number = Date.now()): HealthReport {
       : undefined,
   });
 
+  // A channel bridge (e.g. Telegram) that is registered but stale or not-ready
+  // is silently NOT delivering — channel messages queue against it (#706). The
+  // binding-target health above can read "ok" while the bridge itself is wedged,
+  // so check the bridge agent's own liveness to avoid green-washing a down bridge.
+  const channelBridges = listAgents().filter((agent) =>
+    agent.id !== "user" && agent.id !== "system" &&
+    (agent.kind === "channel" || agent.meta?.kind === "channel"));
+  const staleChannelBridges = channelBridges.filter((agent) =>
+    agent.status !== "offline" && agent.lastSeen <= now - STALE_TTL_MS);
+  const notReadyChannelBridges = channelBridges.filter((agent) =>
+    agent.status !== "offline" && !agent.ready && agent.lastSeen > now - STALE_TTL_MS);
+  const unhealthyChannelBridges = [...staleChannelBridges, ...notReadyChannelBridges];
+  checks.push({
+    name: "channel-bridge-liveness",
+    status: staleChannelBridges.length > 0 ? "error" : notReadyChannelBridges.length > 0 ? "warn" : "ok",
+    count: unhealthyChannelBridges.length,
+    detail: unhealthyChannelBridges.length > 0
+      ? `${unhealthyChannelBridges.length} channel bridge(s) not delivering: ${unhealthyChannelBridges.slice(0, 3).map((a) => `${a.id} (status=${a.status}, ready=${a.ready})`).join("; ")}`
+      : undefined,
+  });
+
+  const expiredUndelivered = countExpiredUndeliveredMessages(now);
+  checks.push({
+    name: "expired-undelivered-messages",
+    status: expiredUndelivered > 0 ? "warn" : "ok",
+    count: expiredUndelivered,
+    detail: expiredUndelivered > 0
+      ? `${expiredUndelivered} queued message(s) expired undelivered at max_age in the last 24h (silent data loss)`
+      : undefined,
+  });
+
   const rootTokenRuntimeAgents = listAgents().filter((agent) => {
     if (agent.status === "offline") return false;
     if (agent.id === "user" || agent.id === "system") return false;

package/src/maintenance/jobs.ts

@@ -10,6 +10,7 @@ import {
   expireQueuedMessages,
   getAgent,
   listAgents,
+  listStaleQueuedDirectTargets,
   pruneOrphanedSharedWorkspaces,
   pruneOfflineAgents,
   pruneOldMessages,
@@ -22,6 +23,8 @@ import {
   runDbMaintenance,
   sweepArtifacts,
 } from "../db";
+import { isAgentUnavailable } from "../db/agent-predicates";
+import { flushQueuedDirectMessages } from "../services/managed-running";
 import { notifyAgentOffline } from "../agent-lifecycle-events";
 import { diagnoseAgentDeath } from "../agent-death-diagnosis";
 import { autoMergeCleanFastForwards } from "../workspace-auto-merge";
@@ -193,10 +196,35 @@ export const definitions: MaintenanceJobDefinition[] = [
     runOnStart: true,
     handler() {
       const messages = expireQueuedMessages();
-      for (const message of messages) emitMessageExpired(message);
+      for (const message of messages) {
+        // Silent data loss is the worst failure mode here (#706): a queued
+        // message died without ever reaching its recipient. Surface it loudly.
+        console.warn(`[delivery] message ${message.id} to ${message.to} (kind=${message.kind}) expired undelivered after max_age — silent data loss`);
+        emitMessageExpired(message);
+      }
       return { expiredQueuedMessageIds: messages.map((message) => message.id) };
     },
   },
+  {
+    id: "queued-message-resweep",
+    title: "Queued message re-sweep",
+    description: "Re-resolve long-queued direct messages whose target agent is available again — safety net for a missed flush-on-recovery event (#706).",
+    intervalMs: REAP_INTERVAL_MS,
+    runOnStart: true,
+    handler() {
+      const reswept: Record<string, number> = {};
+      for (const target of listStaleQueuedDirectTargets()) {
+        const agent = getAgent(target);
+        // Only flush to a target that is actually available now; otherwise the
+        // message belongs in the queue (this is hooked to agent availability,
+        // not pool-slot reclaim).
+        if (!agent || isAgentUnavailable(agent)) continue;
+        const flushed = flushQueuedDirectMessages(target);
+        if (flushed.length > 0) reswept[target] = flushed.length;
+      }
+      return { resweptTargets: reswept };
+    },
+  },
   {
     id: "command-expiration",
     title: "Command expiration",

package/src/services/managed-running.ts

@@ -17,7 +17,7 @@ import { getManagedAgentState, updateManagedAgentState } from "../config-store";
 import { emitRelayEvent } from "../events";
 import { emitMessageAvailable, emitMessageDeliveryUpdated, emitNewMessage } from "../sse";
 import type { AuthContext } from "./auth-context";
-import type { ManagedAgentState } from "../types";
+import type { ManagedAgentState, Message } from "../types";
 
 interface ManagedRunningInput {
   policyName?: string;
@@ -135,14 +135,16 @@ function recordManagedTransition(
  * transitions back to available: heartbeat stale→idle, re-registration after restart/compact, or
  * rate-limit resume. Emits the same `message.available` / `message.new` / `message.delivery_updated`
  * events that the policy flush emits so SSE subscribers and the dashboard react identically.
- * No-op when there are no queued direct messages.
+ * No-op when there are no queued direct messages. Returns the flushed messages so
+ * callers (e.g. the resweep safety net, #706) can report how many were recovered.
  */
-export function flushQueuedDirectMessages(agentId: string): void {
+export function flushQueuedDirectMessages(agentId: string): Message[] {
   const available = resolveQueuedDirectMessages(agentId);
-  if (!available.length) return;
+  if (!available.length) return [];
   emitMessageAvailable("direct", agentId, available);
   for (const message of available) {
     emitNewMessage(message);
     emitMessageDeliveryUpdated(message);
   }
+  return available;
 }