agent-relay-server 0.54.0 → 0.56.0

package/docs/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Relay API",
-    "version": "0.54.0",
+    "version": "0.56.0",
     "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.54.0",
+  "version": "0.56.0",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",

package/src/bus.ts

@@ -22,6 +22,7 @@ import {
   type RegisterFrame,
 } from "agent-relay-sdk/protocol";
 import { errMessage, isRecord, stringValue } from "agent-relay-sdk";
+import { agentProviderState } from "./provider-state";
 import { getComponentAuth, isComponentAuthorizedFor, isAuthorized, isOriginAllowed, unauthorized } from "./security";
 import type { AgentCard, Command, ComponentToken, ContextState, Message, ProviderCapabilities, RegisterAgentInput, Task } from "./types";
 
@@ -532,8 +533,8 @@ function emitAgentStatusEvent(agentId: string): void {
 }
 
 function auditProviderStateTransition(agentId: string, before: AgentCard | null | undefined, after: AgentCard | null | undefined): void {
-  const previous = providerStateFromAgent(before);
-  const next = providerStateFromAgent(after);
+  const previous = agentProviderState(before);
+  const next = agentProviderState(after);
   const previousKey = providerStateKey(previous);
   const nextKey = providerStateKey(next);
   if (previousKey === nextKey) return;
@@ -602,12 +603,6 @@ function auditRunnerTimelineEvent(agentId: string, timelineEvent: unknown): void
   }
 }
 
-function providerStateFromAgent(agent: AgentCard | null | undefined): Record<string, unknown> | null {
-  const value = agent?.meta?.providerState;
-  if (!isRecord(value) || typeof value.state !== "string") return null;
-  return value;
-}
-
 function providerStateKey(state: Record<string, unknown> | null): string | null {
   if (!state) return null;
   return [state.state, typeof state.reason === "string" ? state.reason : ""].join(":");

package/src/db/agents.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 { evaluatePoolBindings, expectedChannelAgentId, upsertChannelForAgent } from "./channels.ts";
 import { seedContinuationObjectiveFromSpawnPrompt } from "./continuations.ts";
+import { messageTaskClosed } from "./claim-sql.ts";
 import { ValidationError, getDb } from "./connection.ts";
 import { rowToAgent, rowToContextSnapshot } from "./mappers.ts";
 import { closeOpenPairsForAgent } from "./pairs.ts";
@@ -498,10 +499,12 @@ export function pruneOfflineAgents(maxOfflineMs: number = DAY_MS): string[] {
     if (rows.length === 0) return [];
     const now = Date.now();
 
-    // Release claims held by pruned agents so work becomes claimable again.
+    // Release claims held by pruned agents so unfinished work becomes claimable again — but
+    // never for a message whose task is already closed: nulling that claim resurrects completed
+    // work on the next restart (the task release below is already guarded the same way).
     getDb()
       .query(
-        "UPDATE messages SET claimed_by = NULL, claimed_at = NULL, claim_expires_at = NULL WHERE claimed_by IN (SELECT id FROM agents WHERE status = 'offline' AND last_seen < ? AND id NOT IN ('user', 'system'))"
+        `UPDATE messages SET claimed_by = NULL, claimed_at = NULL, claim_expires_at = NULL WHERE claimed_by IN (SELECT id FROM agents WHERE status = 'offline' AND last_seen < ? AND id NOT IN ('user', 'system')) AND NOT ${messageTaskClosed("messages.id")}`
       )
       .run(cutoff);
 
@@ -534,10 +537,11 @@ export function deleteAgent(id: string): { ok: boolean; error?: string } {
     return { ok: false, error: "built-in agent cannot be deleted" };
   }
   const deleted = getDb().transaction(() => {
-    // Release any claims held by this agent so the tasks become claimable again.
+    // Release any claims held by this agent so the tasks become claimable again — except for
+    // messages whose task is already closed (releasing those resurrects finished work).
     // from_agent is left intact as historical record.
     const now = Date.now();
-    getDb().query("UPDATE messages SET claimed_by = NULL, claimed_at = NULL, claim_expires_at = NULL WHERE claimed_by = ?").run(id);
+    getDb().query(`UPDATE messages SET claimed_by = NULL, claimed_at = NULL, claim_expires_at = NULL WHERE claimed_by = ? AND NOT ${messageTaskClosed("messages.id")}`).run(id);
     settleSingleTargetOnDemandTasks("claimed_by = ?", [id], now, "agent-removed");
     getDb().query("UPDATE tasks SET status = 'open', claimed_by = NULL, claimed_at = NULL, claim_expires_at = NULL, updated_at = ? WHERE claimed_by = ? AND status IN ('claimed', 'in_progress', 'blocked')").run(now, id);
     revokeRuntimeTokensForAgent(id, now);

package/src/db/claim-sql.ts

@@ -0,0 +1,28 @@
+// Single home for the "is this message's task already finished?" SQL guard.
+//
+// A claimable message backed by a task must stop being treated as available work the moment
+// the task is closed. This predicate had drifted: `releaseExpiredClaims` and the
+// `expired-message-claims` health check carried it, but `pruneOfflineAgents`/`deleteAgent`
+// (which release a pruned agent's message claims to NULL) and the poll's null-claim branch did
+// NOT — so a completed automation briefing's message would get its claim nulled on agent prune
+// and then re-deliver as fresh work to the next managed-agent restart (which always mints a new
+// agent id, defeating the per-agent `message_reads` dedup). Route every site through here so the
+// closed-task statuses live in exactly one place.
+
+/** Task statuses that mean "finished — no more work to hand out for this message." */
+const CLOSED_TASK_STATUSES = ["done", "failed", "canceled"] as const;
+
+const CLOSED_TASK_STATUS_SQL = CLOSED_TASK_STATUSES.map((status) => `'${status}'`).join(", ");
+
+/** SQL columns that reference a `messages.id` in the queries below. Internal, never user input. */
+type MessageIdRef = "m.id" | "messages.id";
+
+/**
+ * SQL predicate: the message identified by `messageRef` has a linked task that is already closed.
+ * Negate it (`NOT ${messageTaskClosed(...)}`) to gate "available work" queries — claim release
+ * and inbox polling — so a finished task's claimable message is never released-to-NULL or
+ * re-polled as fresh work. `messageRef` is a fixed internal column reference, not user input.
+ */
+export function messageTaskClosed(messageRef: MessageIdRef): string {
+  return `EXISTS (SELECT 1 FROM tasks t WHERE t.message_id = ${messageRef} AND t.status IN (${CLOSED_TASK_STATUS_SQL}))`;
+}

package/src/db/message-reads.ts

@@ -18,7 +18,8 @@ import { getAgent } from "./agents.ts";
 import { sendMessageWithResult } from "./messages.ts";
 import { deleteArtifactLinksForEntity } from "./artifacts.ts";
 import { getDb, timedQuery } from "./connection.ts";
-import { legacyChannelTargets } from "./delivery.ts";
+import { legacyChannelTargets, isChannelAgentId } from "./delivery.ts";
+import { messageTaskClosed } from "./claim-sql.ts";
 import { MSG_SELECT, rowToMessage } from "./mappers.ts";
 import type {
   AgentCard,
@@ -203,9 +204,13 @@ export function pollMessages(query: PollQuery): Message[] {
   }
   conditions.push("delivery_status != 'queued' AND delivery_status NOT IN ('failed', 'dead')");
 
-  // Hide active claims held by someone else, but let expired claims surface so
-  // another matching agent can recover stuck work.
-  conditions.push(`(claimable = 0 OR claimed_by IS NULL OR claimed_by = ? OR ((claim_expires_at IS NULL OR claim_expires_at <= ?) AND NOT EXISTS (SELECT 1 FROM tasks t WHERE t.message_id = m.id AND t.status IN ('done', 'failed', 'canceled'))))`);
+  // A claimable message is available to this agent when it is non-claimable, currently held by
+  // THIS agent, or unclaimed/expired AND its task is not already closed. The closed-task guard
+  // must cover BOTH the null-claim and the expired-claim branch: when a managed agent is
+  // pruned/deleted its message claims are released to NULL (see pruneOfflineAgents/deleteAgent),
+  // so without it a finished task's message resurrects as fresh work on the next restart (which
+  // mints a new agent id, so message_reads no longer dedups it) — the automation re-delivery bug.
+  conditions.push(`(claimable = 0 OR claimed_by = ? OR ((claimed_by IS NULL OR claim_expires_at IS NULL OR claim_expires_at <= ?) AND NOT ${messageTaskClosed("m.id")}))`);
   params.push(query.for, Date.now());
 
   if (query.sinceId !== undefined) {
@@ -320,6 +325,35 @@ export function listPendingReplyObligations(agentId: string, limit = 20): ReplyO
     .map((message) => replyObligationFromMessage(message, agentId));
 }
 
+/**
+ * Channel-answer linking: a channel agent answers the human OUT-OF-BAND through its bridge — e.g.
+ * `agent-relay /message telegram '{"action":"reply",...}'` — which stores an outbound to the channel
+ * agent with NO reply_to / thread / conversation linkage (the bridge protocol body is opaque to the
+ * relay, so the inbound's channel + conversation never make it onto the answer). Without linkage the
+ * obligation never clears, and the Stop hook nags the agent into a redundant `/reply` that routes back
+ * through the channel as a second message to the human (the Telegram double-message friction).
+ *
+ * When the agent posts an unlinked message into a channel agent and has EXACTLY ONE open obligation on
+ * that channel AT THAT MOMENT, the conversation is unambiguous: this send is the answer. We snapshot
+ * that here, at send time, by returning the obligation id to link the outbound to — a decision a later
+ * sibling conversation can never retroactively confuse (the reason query-time coverage is unsafe). When
+ * two conversations are open the send is unattributable; we leave it unlinked for an explicit `/reply`,
+ * which carries the conversation precisely. Provider-agnostic: keys only on the channel agent target,
+ * never on the body.
+ *
+ * Returns the inbound message id this outbound answers, or null when nothing should be auto-linked.
+ */
+export function channelObligationAnsweredBy(
+  agentId: string,
+  channelAgentId: string,
+): number | null {
+  if (!isChannelAgentId(channelAgentId)) return null;
+  const open = listPendingReplyObligations(agentId, 50).filter(
+    (obligation) => obligation.kind === "channel.event" && obligation.from === channelAgentId,
+  );
+  return open.length === 1 ? open[0]!.messageId : null;
+}
+
 /**
  * #413 / vent #121 — seed a pending reply obligation for a freshly-registered spawned worker so
  * it cannot strand its verdict. A spawned agent gets its task as the positional spawn prompt, NOT

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 { messageTaskClosed } from "./claim-sql.ts";
 import { getDb } from "./connection.ts";
 import type {
   AgentCard,
@@ -245,7 +246,7 @@ export function getHealth(now: number = Date.now()): HealthReport {
   });
 
   const expiredMessageClaims = (getDb()
-    .query("SELECT COUNT(*) as c FROM messages WHERE claimed_by IS NOT NULL AND (claim_expires_at IS NULL OR claim_expires_at <= ?) AND NOT EXISTS (SELECT 1 FROM tasks t WHERE t.message_id = messages.id AND t.status IN ('done', 'failed', 'canceled'))")
+    .query(`SELECT COUNT(*) as c FROM messages WHERE claimed_by IS NOT NULL AND (claim_expires_at IS NULL OR claim_expires_at <= ?) AND NOT ${messageTaskClosed("messages.id")}`)
     .get(now) as any).c as number;
   checks.push({
     name: "expired-message-claims",

package/src/db/tasks.ts

@@ -15,6 +15,7 @@ import {
 import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_MERGE_LEASE_MS } from "../config";
 import { matchAgents } from "../agent-ref";
 import { getAgent, settleSingleTargetOnDemandTasks, validateAgentSession } from "./agents.ts";
+import { messageTaskClosed } from "./claim-sql.ts";
 import { ClaimError, getDb } from "./connection.ts";
 import { rowToTask, rowToTaskEvent } from "./mappers.ts";
 import { claimMessageRow } from "./messages.ts";
@@ -169,7 +170,7 @@ export function recordTaskEvent(taskId: number, input: {
 export function releaseExpiredClaims(now: number = Date.now()): { messageIds: number[]; tasks: Task[] } {
   return getDb().transaction(() => {
     settleSingleTargetOnDemandTasks("claimed_by IS NOT NULL AND (claim_expires_at IS NULL OR claim_expires_at <= ?)", [now], now, "claim-lease-expired");
-    const releasableMessageClaim = "claimed_by IS NOT NULL AND (claim_expires_at IS NULL OR claim_expires_at <= ?) AND NOT EXISTS (SELECT 1 FROM tasks t WHERE t.message_id = messages.id AND t.status IN ('done', 'failed', 'canceled'))";
+    const releasableMessageClaim = `claimed_by IS NOT NULL AND (claim_expires_at IS NULL OR claim_expires_at <= ?) AND NOT ${messageTaskClosed("messages.id")}`;
     const messageRows = getDb()
       .query(`SELECT id FROM messages WHERE ${releasableMessageClaim}`)
       .all(now) as any[];

package/src/maintenance.ts

@@ -63,6 +63,7 @@ import { notifySystemMessage } from "./notify";
 import { pruneExpiredTokenRecords } from "./token-db";
 import { dissolveTeamById } from "./services/team";
 import { reapTransientAgents, resetTransientTrackerForTests } from "./services/transient-agent-reaper";
+import { resumeRateLimitedAgents, resetRateLimitResumeTrackerForTests } from "./services/rate-limit-resume";
 import type { Command, MaintenanceJob, MaintenanceJobRun } from "./types";
 
 const DEFAULT_TIMEOUT_MS = 30_000;
@@ -135,7 +136,7 @@ const orphanReapEnabled = () => process.env.AGENT_RELAY_ORPHAN_REAP !== "0";
 // orchestratorId + session identity -> when we first saw it orphaned (and last reaped).
 const orphanTracker = new Map<string, { firstOrphanedAt: number; lastReapAt?: number }>();
 
-export function resetOrphanTrackerForTests(): void { orphanTracker.clear(); resetTransientTrackerForTests(); }
+export function resetOrphanTrackerForTests(): void { orphanTracker.clear(); resetTransientTrackerForTests(); resetRateLimitResumeTrackerForTests(); }
 
 interface MaintenanceJobDefinition {
   id: string;
@@ -300,6 +301,7 @@ const definitions: MaintenanceJobDefinition[] = [
     handler: reapOrphanedSessions,
   },
   { id: "transient-agent-reaper", title: "Transient agent reaper", description: "Cleanly shut down transient spawned agents once they are idle and any isolated branch work has landed.", intervalMs: REAP_INTERVAL_MS, runOnStart: false, handler: reapTransientAgents },
+  { id: "rate-limit-resume", title: "Rate-limit resume", description: "Auto-resume agents held on a provider usage/rate-limit stall once their reset window has passed (#286).", intervalMs: REAP_INTERVAL_MS, runOnStart: false, handler: resumeRateLimitedAgents },
   {
     id: "team-reap",
     title: "Team lifecycle close-out",

package/src/provider-state.ts

@@ -0,0 +1,66 @@
+import { isRecord } from "agent-relay-sdk";
+
+// One server-side home for reading an agent's provider runtime state (the
+// `meta.providerState` that both Claude and Codex ride for blocked/approval
+// states — see runner setProviderStatus). Imported by the bus transition audit,
+// the transient-agent reaper (don't reap a held agent), and the rate-limit
+// resume sweep. The dashboard has its own client-side copy in display.ts.
+
+export interface ProviderStateView {
+  state: string;
+  reason?: string;
+  label?: string;
+  /** Unix ms the provider's limit window resets (rate-limit holds). */
+  resetAt?: number;
+  /** Unix ms the hold was entered (used for the resume fallback when resetAt is absent). */
+  enteredAt?: number;
+  /** Raw provider error_type, kept for empirical observation of which type a real limit fires. */
+  errorType?: string;
+  [key: string]: unknown;
+}
+
+interface HasMeta {
+  meta?: Record<string, unknown> | null;
+}
+
+/** The agent's provider runtime state, or null when none is set / malformed. */
+export function agentProviderState(agent: HasMeta | null | undefined): ProviderStateView | null {
+  const value = agent?.meta?.providerState;
+  if (!isRecord(value) || typeof value.state !== "string") return null;
+  return value as ProviderStateView;
+}
+
+/** True when the agent is in any blocked provider state (rate-limit, approval, model-unavailable). */
+export function isProviderBlocked(agent: HasMeta | null | undefined): boolean {
+  return agentProviderState(agent)?.state === "blocked";
+}
+
+/** The `reason` value a rate-limit hold carries (matches the runner's control-server seam). */
+export const RATE_LIMIT_BLOCK_REASON = "rate_limit";
+
+/** True when the agent is specifically held on a provider usage/rate limit. */
+export function isRateLimitHold(agent: HasMeta | null | undefined): boolean {
+  const state = agentProviderState(agent);
+  return state?.state === "blocked" && state.reason === RATE_LIMIT_BLOCK_REASON;
+}
+
+// Fallback window when the provider gave no reset time: retry after this long
+// rather than waiting the full (unknown) limit window. Re-entering the hold on a
+// still-limited retry is cheap, and a subscription limit almost always carries a
+// reset time. Read at call-time so operators/tests can tune it.
+const rateLimitFallbackMs = (): number =>
+  Number(process.env.AGENT_RELAY_RATE_LIMIT_FALLBACK_MS) || 60 * 60 * 1000;
+
+/**
+ * When a rate-limit hold should be lifted. The provider's `resetAt` is
+ * authoritative; otherwise fall back to `enteredAt + fallback window`. Null only
+ * when neither is known (shouldn't happen — the runner always stamps enteredAt).
+ */
+export function rateLimitResumeAt(state: ProviderStateView | null): number | null {
+  if (!state) return null;
+  if (typeof state.resetAt === "number" && Number.isFinite(state.resetAt)) return state.resetAt;
+  if (typeof state.enteredAt === "number" && Number.isFinite(state.enteredAt)) {
+    return state.enteredAt + rateLimitFallbackMs();
+  }
+  return null;
+}

package/src/services/rate-limit-resume.ts

@@ -0,0 +1,96 @@
+import { createActivityEvent, listAgents } from "../db";
+import { notifySystemMessage } from "../notify";
+import { agentProviderState, isRateLimitHold, rateLimitResumeAt } from "../provider-state";
+
+// #286 Phase 2: auto-resume agents held on a usage/rate-limit stall once their
+// window resets. The runner reports the hold as `providerState: blocked` (reason
+// rate_limit) with a resetAt; this sweep finds holds whose reset has passed and
+// delivers a waking `continue` message. The agent's next turn clears the hold
+// (the runner drops rateLimitHold on busy), so the blocked badge lifts on its own.
+//
+// Fan-out safe by construction: it resumes EVERY held agent past its reset, not
+// one. Durable across restarts: resetAt lives in the agent's persisted meta, and
+// the runner keeps re-asserting the hold while connected, so a relay restart just
+// re-reads it. The cooldown tracker only debounces the brief window between
+// sending the resume and the agent actually going busy.
+
+const envMsOrDefault = (name: string, fallback: number): number => {
+  const v = Number(process.env[name]);
+  return Number.isFinite(v) && v >= 0 ? v : fallback;
+};
+// Don't re-send a resume to the same agent within this window — covers the gap
+// between delivery and the agent flipping to busy (which clears the hold).
+const resumeCooldownMs = () => envMsOrDefault("AGENT_RELAY_RATE_LIMIT_RESUME_COOLDOWN_MS", 5 * 60 * 1000);
+
+const resumeTracker = new Map<string, number>();
+
+export function resetRateLimitResumeTrackerForTests(): void {
+  resumeTracker.clear();
+}
+
+const RESUME_BODY =
+  "▶️ Your usage/rate limit has reset — resuming. Continue the task you were working on when the limit interrupted you. If you had already finished, no action is needed.";
+
+export function resumeRateLimitedAgents(): Record<string, unknown> {
+  const now = Date.now();
+  const cooldown = resumeCooldownMs();
+  const seen = new Set<string>();
+  const resumed: string[] = [];
+  const waiting: string[] = [];
+  const cooling: string[] = [];
+
+  for (const agent of listAgents()) {
+    if (!isRateLimitHold(agent)) continue;
+    seen.add(agent.id);
+
+    const state = agentProviderState(agent);
+    const resumeAt = rateLimitResumeAt(state);
+    if (resumeAt !== null && now < resumeAt) { waiting.push(agent.id); continue; }
+
+    const lastResume = resumeTracker.get(agent.id);
+    if (lastResume !== undefined && now - lastResume < cooldown) { cooling.push(agent.id); continue; }
+    resumeTracker.set(agent.id, now);
+
+    try {
+      notifySystemMessage(agent.id, {
+        subject: "Usage limit reset — resume",
+        body: RESUME_BODY,
+        payload: {
+          kind: "agent.rate_limit_resume",
+          agentId: agent.id,
+          resetAt: state?.resetAt,
+          errorType: state?.errorType,
+        },
+        replyExpected: false,
+      });
+    } catch {
+      // A stale/unreachable target must never break the sweep; it store-aheads
+      // and retries next pass once the cooldown lapses.
+      resumeTracker.delete(agent.id);
+      continue;
+    }
+
+    resumed.push(agent.id);
+    createActivityEvent({
+      clientId: `rate-limit-resume-${agent.id}-${now}`,
+      kind: "state",
+      title: "Rate-limit hold resumed",
+      body: `Usage window reset — sent resume to ${agent.label ?? agent.id}`,
+      meta: agent.id,
+      icon: "ti-player-play",
+      view: "agents",
+      agentId: agent.id,
+      metadata: {
+        source: "server",
+        maintenanceJobId: "rate-limit-resume",
+        resetAt: state?.resetAt,
+        errorType: state?.errorType,
+      },
+    });
+  }
+
+  // Forget agents no longer held so a future hold resumes immediately.
+  for (const id of resumeTracker.keys()) if (!seen.has(id)) resumeTracker.delete(id);
+
+  return { held: seen.size, resumed, waiting, cooling, tracked: resumeTracker.size };
+}

package/src/services/send-message.ts

@@ -22,7 +22,7 @@
 // OUT OF SCOPE (transport-edge, excluded from the parity facet): automatic memory injection
 // (needs request-derived context) and per-transport audit (HTTP domain row vs MCP tool-call row).
 import { isMechanicalMessageKind, isRecord, isReservedAgentId } from "agent-relay-sdk";
-import { ValidationError, getMessage, listAgents, sendMessageWithResult } from "../db";
+import { ValidationError, getMessage, listAgents, sendMessageWithResult, channelObligationAnsweredBy } from "../db";
 import { planSend, type DeliveryReceipt } from "../agent-ref";
 import { emitMessageQueued, emitNewMessage } from "../sse";
 import { getLifecycleManager } from "../lifecycle-manager";
@@ -159,6 +159,18 @@ export function sendMessageService(
   // Resolve BEFORE authorize so both run against the canonical id (kills the HTTP-authorizes-raw
   // vs MCP-authorizes-resolved drift).
   const receipt = resolveSendTarget(input, input.from);
+  // Channel-answer linking: an agent answering the human through a channel bridge posts a body-less
+  // message to the channel agent (e.g. `agent-relay /message telegram '{"action":"reply",...}'`) that
+  // carries no reply/conversation linkage, so its reply obligation never clears and the Stop hook nags
+  // it into a redundant `/reply` that leaks back to the human as a second message. When the agent has
+  // exactly ONE open obligation on that channel this send is unambiguously the answer — link it here,
+  // at send time, so the obligation clears with no extra message. (`channelObligationAnsweredBy` is a
+  // no-op unless `to` resolved to a channel agent with a single open obligation; deciding at send time
+  // — not query time — keeps a later sibling conversation from retroactively mis-attributing it.)
+  if (!input.replyTo && !isMechanicalMessageKind(input.kind)) {
+    const answered = channelObligationAnsweredBy(input.from, input.to);
+    if (answered !== null) input.replyTo = answered;
+  }
   authorizeSend(input, ctx, opts, reservedSink);
 
   const result = sendMessageWithResult(input);

package/src/services/transient-agent-reaper.ts

@@ -2,6 +2,7 @@ import { createCommand } from "../commands-db";
 import { emitRelayEvent } from "../events";
 import { createActivityEvent, getAgent, listAgents, listWorkspaces } from "../db";
 import { notifySystemMessage } from "../notify";
+import { isProviderBlocked } from "../provider-state";
 import { TERMINAL_WORKSPACE_STATUSES } from "../workspace-phase";
 
 const envMsOrDefault = (name: string, fallback: number): number => {
@@ -64,7 +65,10 @@ export function reapTransientAgents(): Record<string, unknown> {
   for (const agent of listAgents()) {
     if (agent.lifecycle !== "transient") continue;
     seen.add(agent.id);
-    if (agent.status !== "idle" || !agent.ready) { transientTracker.delete(agent.id); continue; }
+    // A held agent (rate-limit hold #286, or any provider-blocked state) reads as
+    // idle+ready but is NOT done — reaping it would kill work that's just waiting
+    // for the limit to reset. Treat it as not-idle; the clock restarts on resume.
+    if (agent.status !== "idle" || !agent.ready || isProviderBlocked(agent)) { transientTracker.delete(agent.id); continue; }
     const entry = transientTracker.get(agent.id) ?? { firstIdleAt: now };
     transientTracker.set(agent.id, entry);
     const idleForMs = now - entry.firstIdleAt;