agent-relay-server 0.121.0 → 0.121.1

package/src/agent-lifecycle-events.ts

@@ -1,6 +1,7 @@
 import { emitRelayEvent } from "./events";
 import { routeNotification } from "./notification-router";
-import { getAgent, markAgentReadyNotified, recordCrashReport, recordTerminalEvent } from "./db";
+import { LIFECYCLE_STATE_WORKING, childSignalKey, stampLifecycleSignal, taskSignalKey } from "./lifecycle-signal-registry";
+import { deliverableTaskIdsBySpawnRequestId, getAgent, markAgentReadyNotified, recordCrashReport, recordTerminalEvent } from "./db";
 import { crashReportFor } from "./agent-death-diagnosis";
 import { renderTemplate } from "./prompt-resolver";
 import type { AgentCard, AgentDeathDiagnosis } from "./types";
@@ -82,6 +83,26 @@ function spawnRequestIdOf(child: AgentCard): string | undefined {
   return typeof s === "string" ? s : undefined;
 }
 
+// #1032b — record that a first-class lifecycle event (ready/exit) told the parent about this child,
+// so a redundant "Task status pulse" for the same child/task is suppressed instead of double-waking.
+// #1038 — agent.ready means the child is coming up to work its task, so it is state-keyed to
+// `working` (same as a report-up): it supersedes a redundant `working` pulse only, never a later
+// distinct-state transition for the same task within the TTL.
+function stampChildLifecycleSignal(parent: string, child: AgentCard): void {
+  stampLifecycleSignal(parent, childSignalKey(child.id));
+  const direct = child.meta?.taskId;
+  const directNum = typeof direct === "string" ? Number(direct) : direct;
+  if (typeof directNum === "number" && Number.isSafeInteger(directNum) && directNum > 0) {
+    stampLifecycleSignal(parent, taskSignalKey(directNum, LIFECYCLE_STATE_WORKING));
+  }
+  const spawnRequestId = spawnRequestIdOf(child);
+  if (spawnRequestId) {
+    for (const taskId of deliverableTaskIdsBySpawnRequestId(spawnRequestId)) {
+      stampLifecycleSignal(parent, taskSignalKey(taskId, LIFECYCLE_STATE_WORKING));
+    }
+  }
+}
+
 /**
  * A spawned child became genuinely ready (registered AND past onboarding — ready+idle, not merely
  * process-started). Emits the durable `agent.ready` event and, unless suppressed, pushes the
@@ -152,6 +173,7 @@ export function notifyAgentReady(childId: string): void {
       replyExpected: false,
     },
   });
+  stampChildLifecycleSignal(parent, child);
 }
 
 /**

package/src/agent-ref.ts

@@ -99,9 +99,19 @@ function idMatchesSegment(id: string, ref: string): boolean {
 export function matchAgents(ref: string, agents: AgentCard[], opts: ResolveOptions = {}): AgentCard[] {
   const trimmed = ref.trim();
   if (!trimmed) return [];
-  const pool = opts.excludeId ? agents.filter((a) => a.id !== opts.excludeId) : agents;
 
   const selector = parseSelector(trimmed);
+  // An exact id reference — a bare full id, or an `id:` selector — names ONE agent unambiguously,
+  // so it is honored even when it targets the excluded (self) agent: addressing your own full id
+  // is a deliberate self/peer send, NOT the #290 bare-ref self-loop that `excludeId` guards
+  // against. Without this exemption an exact self-id is refused by the matcher yet still offered by
+  // the "did you mean" hint — the resolver suggesting the very id it just rejected (#1035).
+  const exactId = selector ? (selector.field === "id" ? selector.value : null) : trimmed;
+  const selfExact = opts.excludeId && exactId
+    ? agents.find((a) => a.id === opts.excludeId && a.id === exactId)
+    : undefined;
+  const pool = opts.excludeId && !selfExact ? agents.filter((a) => a.id !== opts.excludeId) : agents;
+
   if (selector) return selector.value ? pool.filter((a) => matchesSelector(a, selector)) : [];
 
   const exact = pool.filter((a) => matchesExact(a, trimmed));
@@ -207,9 +217,14 @@ function ambiguousMessage(ref: string, candidates: AgentCard[]): string {
   return `agent reference "${ref}" is ambiguous — matches ${candidates.length}: ${list}${more}. Use a full id, label, or a fan-out selector (tag:/cap:/label:/team:).`;
 }
 
-function notFoundMessage(ref: string, agents: AgentCard[]): string {
+function notFoundMessage(ref: string, agents: AgentCard[], opts: ResolveOptions = {}): string {
   const needle = ref.toLowerCase();
   const near = agents
+    // Canonicalize the suggestion pool to the SAME identity the matcher used: never offer the
+    // excluded (self) agent, and never suggest an id/label that EQUALS the ref — if it were an
+    // exact match it would have resolved, so surfacing it means offering the id we just rejected
+    // (#1035, the "Did you mean: <the id you typed>?" self-suggestion).
+    .filter((a) => a.id !== opts.excludeId && a.id !== ref && a.label !== ref)
     .filter((a) => isPseudoAgent(a) && (a.id.toLowerCase().includes(needle) || a.label?.toLowerCase().includes(needle)))
     .slice(0, 3)
     .map(describeAgent);
@@ -261,7 +276,7 @@ export function planSend(to: string, agents: AgentCard[], opts: ResolveOptions =
   if (offline.length > 1) {
     return { kind: "ambiguous", message: ambiguousMessage(target, offline), candidates: offline };
   }
-  return { kind: "not_found", message: notFoundMessage(target, agents) };
+  return { kind: "not_found", message: notFoundMessage(target, agents, opts) };
 }
 
 /**

package/src/bus-outbox.ts

@@ -45,6 +45,24 @@ export function appendEvent(type: string, source: string, data: unknown, subject
 }
 
 export function replayEvents(since: number, limit = 500): BusEvent[] {
+  return replayEventsSlice(since, limit).events;
+}
+
+export interface ReplaySlice {
+  events: BusEvent[];
+  /** The highest real outbox row seq in this slice (or `since` when empty). Resume from here to
+   * continue past the slice — driven by the raw row seq, not the (possibly batch-expanded) payload
+   * seq, so a legacy `message.batch` row can't be half-skipped. */
+  lastSeq: number;
+  /** More retained events exist beyond `lastSeq` — the caller MUST fetch the next slice, or the
+   * backlog tail between this slice and the outbox head is silently dropped (#1022 F1). */
+  truncated: boolean;
+}
+
+/** One page of the resume backlog plus whether more remains. `replayEvents`' 500-row cap used to
+ * be a silent ceiling: a resume returning exactly `limit` rows dropped everything between the last
+ * replayed event and the outbox head. Callers loop on `truncated`, resuming from `lastSeq`. */
+export function replayEventsSlice(since: number, limit = 500): ReplaySlice {
   const rows = getDb().query(`
     SELECT seq, event_type, source, subject, data, timestamp
     FROM bus_outbox
@@ -52,7 +70,10 @@ export function replayEvents(since: number, limit = 500): BusEvent[] {
     ORDER BY seq ASC
     LIMIT ?
   `).all(since, limit) as OutboxRow[];
-  return rows.map(rowToEvent);
+  const events = rows.map(rowToEvent);
+  const lastSeq = rows.length > 0 ? rows[rows.length - 1]!.seq : since;
+  const truncated = rows.length === limit && getOutboxCursor() > lastSeq;
+  return { events, lastSeq, truncated };
 }
 
 export function pruneOutbox(retentionMs = 60 * 60 * 1000): number {
@@ -71,6 +92,28 @@ export function getOldestOutboxCursor(): number {
   return row.cursor ?? 0;
 }
 
+/** The highest seq ever assigned to the outbox — read from `sqlite_sequence`, so it survives the
+ * retention prune that empties the table. Needed for gap detection: once the outbox is fully
+ * pruned `getOldestOutboxCursor()` returns 0, which read as "no gap" and let a reconnecting client
+ * believe it was caught up while its post-cursor events had aged out (#1022 F2). */
+export function getOutboxHighWater(): number {
+  const row = getDb().query("SELECT seq FROM sqlite_sequence WHERE name = 'bus_outbox'").get() as { seq: number } | undefined;
+  return row?.seq ?? 0;
+}
+
+/** Whether a resume from `since` has lost events to the retention prune. Two cases:
+ *   - outbox non-empty: the oldest retained event is newer than `since + 1` → the events between
+ *     were pruned.
+ *   - outbox fully pruned (oldest = 0): a gap exists iff events after `since` were ever assigned
+ *     (`since` is behind the high-water mark) and have since aged out.
+ * A client that hits a gap must reconcile from scratch rather than resume from a stale cursor. */
+export function hasReplayGap(since: number): boolean {
+  if (since <= 0) return false;
+  const oldest = getOldestOutboxCursor();
+  if (oldest > 0) return oldest > since + 1;
+  return since < getOutboxHighWater();
+}
+
 function rowToEvent(row: OutboxRow): BusEvent {
   return {
     seq: row.seq,

package/src/bus.ts

@@ -1,6 +1,6 @@
 import type { Server, ServerWebSocket } from "bun";
 import { ValidationError, getAgent, getDb, heartbeat, markReady, mergeAgentMeta, orphanTasksForAgent, revokeRuntimeTokensForAgent, setStatus, validateAgentSession } from "./db";
-import { getOldestOutboxCursor, getOutboxCursor, replayEvents, type BusEvent } from "./bus-outbox";
+import { getOutboxCursor, hasReplayGap, replayEventsSlice, type BusEvent } from "./bus-outbox";
 import { projectAgentStatusData } from "./agent-card-projection";
 import { emitRelayEvent, subscribeRelayEvents, type RelayEvent } from "./events";
 import { getCommand, updateCommand } from "./commands-db";
@@ -15,6 +15,7 @@ import { agentProviderTimelineEvent, auditRunnerTimelineEvent } from "./provider
 import { ServiceAuthError } from "./services/errors";
 import { ShutdownAuthError, ShutdownTargetError, shutdownAgent, shutdownInputFromBusFrame } from "./services/shutdown-agent";
 import { flushQueuedDirectMessages } from "./services/managed-running";
+import { flushIdleLineageReport } from "./services/send-message";
 import { isAgentUnavailable } from "./db/agent-predicates";
 import { applyCommandToRecipe } from "./recipe-runner";
 import { enqueueContinuationInjectionAfterSelfResume } from "./self-resume";
@@ -105,6 +106,10 @@ export function busHandleClose(ws: BusWebSocket): void {
     if (!conn.transportReconnect) {
       setStatus(conn.agentId, "stale", { instanceId: conn.instanceId, epoch: conn.epoch });
       emitAgentStatusEvent(conn.agentId);
+      // #1040 — a WS close is a busy→exit edge (the runner crashed/dropped before its stop-hook
+      // status frame). Flush any held turn-final report-up so it still reaches the spawner instead
+      // of dying with the socket. No-op when nothing was deferred.
+      flushIdleLineageReport(conn.agentId);
     }
   }
 }
@@ -123,6 +128,9 @@ export function expireStaleBusAgents(graceMs = busStaleGraceMs()): { agentIds: s
     revokeRuntimeTokensForAgent(row.id, Date.now(), "stale");
     setStatus(row.id, "offline");
     emitAgentStatusEvent(row.id);
+    // #1040 — the stale sweep is the terminal busy→offline edge for a runner that dropped without a
+    // clean idle transition. Flush any held turn-final report-up before the agent ages out.
+    flushIdleLineageReport(row.id);
     const tasks = orphanTasksForAgent(row.id);
     for (const task of tasks) {
       orphanedTasks.push(task);
@@ -156,7 +164,14 @@ function handleFrame(ws: BusWebSocket, frame: ReturnType<typeof validateClientFr
             const wasUnavailable = current ? isAgentUnavailable(current) : false;
             const runtime = runtimeFromMeta(frame.payload.meta);
             heartbeat(conn.agentId, { instanceId: conn.instanceId, epoch: conn.epoch }, runtime);
-            if (frame.payload.status) setStatus(conn.agentId, frame.payload.status, { instanceId: conn.instanceId, epoch: conn.epoch });
+            if (frame.payload.status) {
+              setStatus(conn.agentId, frame.payload.status, { instanceId: conn.instanceId, epoch: conn.epoch });
+              // #1040 — a heartbeat frame can carry the busy→idle transition instead of a `status`
+              // frame. Flush the held report-up on THIS edge too, else `before.status` is already
+              // non-busy at the next status frame → the flush never fires → the child deadlocks idle
+              // with its verdict held and the coordinator waits forever.
+              if (current?.status === "busy" && frame.payload.status !== "busy") flushIdleLineageReport(conn.agentId);
+            }
             emitAgentStatusEvent(conn.agentId);
             // #416 — flush queued messages if the agent transitioned from unavailable to available.
             if (wasUnavailable) {
@@ -200,6 +215,9 @@ function handleFrame(ws: BusWebSocket, frame: ReturnType<typeof validateClientFr
         emitAgentStatusEvent(conn.agentId);
         // #237 stop-hook → instant ⚪↔🟡 changes detection on the turn-end edge.
         probeWorkspaceOnTurnEnd(before, after);
+        // #1037 — the same busy→idle turn-end edge flushes a quiet child's deferred turn-final
+        // report-up to its spawner (held back while the child was mid-work).
+        if (before?.status === "busy" && after && after.status !== "busy") flushIdleLineageReport(conn.agentId);
         // #633 — silent clean-exit: a runner that stays alive after its provider terminally exited
         // marks the offline edge with `terminalProviderExit`; the owning service turns that into a
         // terminal event + #636 diagnosis (and clears the hold on a genuine resume).
@@ -466,18 +484,23 @@ function hasRunnerLifecycleCapabilities(capabilities: string[], meta: Record<str
 }
 
 function handleResume(ws: BusWebSocket, frameId: string, since: number): void {
-  const oldest = getOldestOutboxCursor();
-  if (since > 0 && oldest > 0 && oldest > since + 1) {
+  if (hasReplayGap(since)) {
     sendError(ws, frameId, "REPLAY_GAP", "requested cursor is older than retained bus outbox events");
     return;
   }
-  const events = replayEvents(since).flatMap(outboxToPayloads);
+  // One page only. The replay cap silently dropped the backlog tail between item 500 and the head
+  // (#1022 F1); we now report `truncated` + the raw `nextSince` row seq so the client loops resume
+  // until it has drained the whole backlog rather than lurching to the live head on the next event.
+  const slice = replayEventsSlice(since);
+  const events = slice.events.flatMap(outboxToPayloads);
   send(ws, {
     type: "resumed",
     payload: {
       events,
       fromSeq: events[0]?.seq ?? since,
       toSeq: events.at(-1)?.seq ?? since,
+      nextSince: slice.lastSeq,
+      truncated: slice.truncated,
     },
   });
 }

package/src/channel-target.ts

@@ -19,6 +19,10 @@ export function parseChannelRouteTarget(target: string): ChannelRouteTarget {
   if (target.startsWith("label:")) return { type: "label", id: target.slice("label:".length) };
   if (target.startsWith("tag:")) return { type: "tag", id: target.slice("tag:".length) };
   if (target.startsWith("cap:")) return { type: "capability", id: target.slice("cap:".length) };
+  // `capability:` is an accepted alias of `cap:` at send time (planSend/FANOUT_PREFIXES + the SDK
+  // matcher both honor it). Parse it here too so channel routing, broadcast scoping and the
+  // claimable gate don't silently treat a `capability:` message as a bare agent id (#1022 F3).
+  if (target.startsWith("capability:")) return { type: "capability", id: target.slice("capability:".length) };
   if (target === "broadcast") return { type: "broadcast" };
   if (target.startsWith("orchestrator:")) return { type: "orchestrator", id: target.slice("orchestrator:".length) };
   return { type: "agent", id: target };

package/src/cli/steward.ts

@@ -1,6 +1,7 @@
 // Steward commands — auto-split from cli.ts (#294). Briefing rail for the steward
 // (#208): the attention queue, per-workspace diagnostics, and check suggestions.
 import { apiRequest } from "./_shared";
+import { resolveStewardChecks } from "../gate-resolver";
 
 // Steward briefing commands (#208): queue of workspaces needing attention, a
 // per-workspace diagnostics inspection, and a check-command suggestion.
@@ -39,21 +40,21 @@ export async function handleStewardCommand(args: string[]): Promise<void> {
     return;
   }
 
-  // checks: suggest validation commands from the workspace's changed files.
+  // checks: suggest validation commands from the workspace's changed files. Derive
+  // the gate from the repo (#1036) — hardcoding `bun test` produced bogus failures in
+  // non-bun repos. Resolve the worktree to read its package.json / land-gates pin:
+  // an explicit `--repo` wins, else the workspace's own worktreePath/repoRoot.
   const diff = await apiRequest("GET", `/api/workspaces/${encodeURIComponent(id)}/diff?patch=0`) as any;
   const files: string[] = Array.isArray(diff?.files) ? diff.files.map((f: any) => f.path) : [];
-  const checks = suggestStewardChecks(files);
+  let repoRoot = repo;
+  if (!repoRoot) {
+    try {
+      const ws = await apiRequest("GET", `/api/workspaces/${encodeURIComponent(id)}`) as any;
+      repoRoot = ws?.worktreePath ?? ws?.repoRoot;
+    } catch {
+      // Best-effort: without a resolvable path the resolver falls back to its default.
+    }
+  }
+  const checks = resolveStewardChecks(files, repoRoot);
   console.log(JSON.stringify({ workspaceId: id, changedFiles: files.length, checks }, null, 2));
 }
-
-// Heuristic check suggestions from changed file paths. Repo-agnostic defaults a
-// steward can refine; cheaper than re-deriving from project docs every run.
-function suggestStewardChecks(files: string[]): Array<{ command: string; reason: string }> {
-  const checks: Array<{ command: string; reason: string }> = [];
-  const has = (re: RegExp) => files.some((f) => re.test(f));
-  if (has(/\.(ts|tsx|mts|cts)$/)) checks.push({ command: "bun run typecheck", reason: "TypeScript files changed" });
-  if (has(/\.test\.|(^|\/)tests?\//)) checks.push({ command: "bun test", reason: "test files changed" });
-  else if (files.length) checks.push({ command: "bun test", reason: "repo default" });
-  if (has(/(^|\/)dashboard\//)) checks.push({ command: "bun run build:dashboard", reason: "dashboard sources changed" });
-  return checks;
-}

package/src/commands-db.ts

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { STALE_TTL_MS } from "./config";
 import { getAgent, getDb, getTerminalEvent, recordTerminalEvent } from "./db";
 import { stringValue } from "agent-relay-sdk";
 import type { Command, CommandStatus, CreateCommandInput, UpdateCommandInput } from "./types";
@@ -63,6 +64,14 @@ function isTerminalStatus(status: CommandStatus): boolean {
 function isLegitimateTerminalCorrection(type: string, from: CommandStatus, to: CommandStatus): boolean {
   if (type === "agent.spawn" && from === "succeeded" && to === "failed") return true;
   if (type === "orchestrator.upgrade" && from === "failed" && to === "succeeded") return true;
+  // #1025 A7 — a lost merge RESULT: the orchestrator lands the branch (base pushed,
+  // worktree recycled onto `<branch>-N`) but dies before POSTing, so the command ages to
+  // `timed_out`. When it finally reports the real `succeeded` result, that late correction
+  // must be applied — otherwise setWorkspaceBranch never runs, the row keeps the old
+  // (deleted) branch, the worktree sits on `-N`, and every later preview reports `missing`
+  // → the lane degrades into a silent previewUnavailable strand (A5). The merge already
+  // happened, so there is no double-land hazard: applying the result only reconciles state.
+  if (type === "workspace.merge" && from === "timed_out" && to === "succeeded") return true;
   return false;
 }
 
@@ -162,16 +171,34 @@ export function findLatestCommandByCorrelation(type: string, correlationId: stri
   return row ? rowToCommand(row) : null;
 }
 
-export function countInFlightSpawnCommands(parentId: string): number {
+// #1034 — count a parent's still-in-flight spawn commands, EXCLUDING any whose child has
+// already registered as a live agent. Spawn commands settle to a terminal status
+// asynchronously (the orchestrator reports back AFTER the child registers), so between
+// registration and settlement a child is otherwise double-counted: once by
+// `countLiveSpawnedAgents` (ready=1) and once here (command still running). Combined into
+// `occupied = live + inFlight`, that transient over-count could push a parent at its quota
+// boundary over the limit and spuriously reject a concurrent spawn — which then "succeeded
+// seconds later" once the command settled. The `NOT EXISTS` dedup mirrors the live-child
+// liveness predicate in `countLiveSpawnedAgents` (and the display-side dedup already in
+// relay_my_agents) so each child counts exactly once.
+export function countInFlightSpawnCommands(parentId: string, now: number = Date.now()): number {
   const row = getDb()
     .query(
       `SELECT count(*) AS n
-       FROM commands
-       WHERE type = 'agent.spawn'
-         AND status IN (${SPAWN_IN_FLIGHT_STATUSES.map(() => "?").join(",")})
-         AND json_extract(params, '$.spawnedBy') = ?`,
+       FROM commands c
+       WHERE c.type = 'agent.spawn'
+         AND c.status IN (${SPAWN_IN_FLIGHT_STATUSES.map(() => "?").join(",")})
+         AND json_extract(c.params, '$.spawnedBy') = ?
+         AND NOT EXISTS (
+           SELECT 1 FROM agents a
+           WHERE a.spawned_by = ?
+             AND a.status NOT IN ('offline', 'stale')
+             AND a.ready = 1
+             AND a.last_seen > ?
+             AND json_extract(a.meta, '$.spawnRequestId') = coalesce(json_extract(c.params, '$.spawnRequestId'), c.correlation_id)
+         )`,
     )
-    .get(...SPAWN_IN_FLIGHT_STATUSES, parentId) as { n: number };
+    .get(...SPAWN_IN_FLIGHT_STATUSES, parentId, parentId, now - STALE_TTL_MS) as { n: number };
   return row.n;
 }
 
@@ -244,11 +271,38 @@ export function deleteCommand(id: string): boolean {
   return true;
 }
 
-export function expireCommands(now: number = Date.now()): Command[] {
-  const rows = getDb()
+// #1025 A6 — sweep both claimed/active leases past their deadline AND pending commands
+// whose target orchestrator is permanently gone. Pending commands are normally left for a
+// busy host to poll (#930/#953), but a `workspace.merge` (or `agent.spawn`) whose target
+// host was decommissioned / re-registered under a new agent id will NEVER poll again — the
+// command lingers forever, `recoverAgedInFlightWorkspaces` files the workspace under
+// `stillActive` indefinitely, and the parked worker waits on a `landed-success` that can't
+// fire. The `isTargetGone` predicate (supplied by the caller, which knows agent liveness)
+// gates the pending sweep so a merely-busy host is untouched; a gone target's expired
+// pending command is timed out, then settled → the workspace returns to review_requested
+// and re-schedules, and the spawn parent is told. Opt-in: callers without the predicate
+// keep the historical claimed/active-only behavior.
+export function expireCommands(
+  now: number = Date.now(),
+  opts: { isTargetGone?: (command: Command) => boolean } = {},
+): Command[] {
+  const activeRows = getDb()
     .query(`SELECT * FROM commands WHERE expires_at IS NOT NULL AND expires_at <= ? AND status IN (${CLAIMED_ACTIVE_STATUSES.map(() => "?").join(",")})`)
     .all(now, ...CLAIMED_ACTIVE_STATUSES) as CommandRow[];
-  for (const row of rows) updateCommand(row.id, { status: "timed_out", error: "command timed out" });
+  let pendingRows: CommandRow[] = [];
+  if (opts.isTargetGone) {
+    const candidates = getDb()
+      .query(`SELECT * FROM commands WHERE expires_at IS NOT NULL AND expires_at <= ? AND status = 'pending'`)
+      .all(now) as CommandRow[];
+    pendingRows = candidates.filter((row) => opts.isTargetGone!(rowToCommand(row)));
+  }
+  const rows = [...activeRows, ...pendingRows];
+  for (const row of rows) {
+    updateCommand(row.id, {
+      status: "timed_out",
+      error: row.status === "pending" ? "command target gone; expired before dispatch" : "command timed out",
+    });
+  }
   return rows.map((row) => getCommand(row.id)).filter((command): command is Command => Boolean(command));
 }
 

package/src/config.ts

@@ -116,6 +116,56 @@ export function relayAuthHeaders(base: Record<string, string> = {}): Record<stri
   return token ? { ...base, [RELAY_TOKEN_HEADER]: token } : base;
 }
 
+// #1024 — origins the orchestrator proxy may forward the relay MASTER token (relayToken()) to.
+// A dynamically-registered orchestrator can carry an attacker-controlled apiUrl; forwarding the
+// master token there leaks full relay admin. This is the defense-in-depth backstop behind the
+// registration lock: even if some path seeds an orchestrator row, the proxy refuses to talk to an
+// untrusted apiUrl at all (never sending the token OR the caller's query string). Explicit
+// operator overrides — comma-separated origins, e.g. "https://orch.example.com".
+export const TRUSTED_ORCHESTRATOR_ORIGINS = (process.env.AGENT_RELAY_TRUSTED_ORCHESTRATOR_ORIGINS || "")
+  .split(",")
+  .map((origin) => origin.trim())
+  .filter(Boolean);
+
+// A private/LAN/tailnet IP literal — never a public, attacker-reachable address.
+function isPrivateIpLiteral(host: string): boolean {
+  const v4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+  if (v4) {
+    const a = Number(v4[1]), b = Number(v4[2]);
+    if (a === 10 || a === 127) return true;              // 10.0.0.0/8, loopback
+    if (a === 172 && b >= 16 && b <= 31) return true;    // 172.16.0.0/12
+    if (a === 192 && b === 168) return true;             // 192.168.0.0/16
+    if (a === 169 && b === 254) return true;             // 169.254.0.0/16 link-local
+    if (a === 100 && b >= 64 && b <= 127) return true;   // 100.64.0.0/10 CGNAT (tailnet)
+    return false;
+  }
+  if (/^f[cd][0-9a-f]*:/.test(host)) return true;         // IPv6 ULA fc00::/7
+  if (/^fe[89ab][0-9a-f]*:/.test(host)) return true;      // IPv6 link-local fe80::/10
+  return false;
+}
+
+// Whether the relay master token may be forwarded to this orchestrator apiUrl (#1024). Trusts
+// loopback, bare single-label hostnames (LAN/MagicDNS — never a public FQDN), private DNS
+// suffixes, private/CGNAT/ULA IP literals, and any explicit AGENT_RELAY_TRUSTED_ORCHESTRATOR_ORIGINS
+// entry. A public IP or public FQDN (e.g. http://attacker.example) is refused unless allowlisted.
+export function isTrustedOrchestratorApiUrl(apiUrl: string | undefined): boolean {
+  if (!apiUrl) return false;
+  let url: URL;
+  try {
+    url = new URL(apiUrl);
+  } catch {
+    return false;
+  }
+  if (TRUSTED_ORCHESTRATOR_ORIGINS.includes(url.origin)) return true;
+  let host = url.hostname.toLowerCase();
+  if (host.startsWith("[") && host.endsWith("]")) host = host.slice(1, -1); // unwrap IPv6 literal
+  if (host === "localhost" || host === "127.0.0.1" || host === "::1") return true;
+  // A bare single-label host (no dot, not an IPv6 literal) is a LAN/MagicDNS name, never public.
+  if (!host.includes(".") && !host.includes(":")) return true;
+  if (/\.(local|internal|lan|home|ts\.net|tailnet)$/.test(host)) return true;
+  return isPrivateIpLiteral(host);
+}
+
 export function allowUnauthenticated(): boolean {
   return process.env.AGENT_RELAY_ALLOW_UNAUTH === "1";
 }

package/src/db/claim-sql.ts

@@ -26,3 +26,19 @@ type MessageIdRef = "m.id" | "messages.id";
 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}))`;
 }
+
+/**
+ * SQL predicate: a claimable message that has NO linked task has already been handled by its claim
+ * holder. A claimable with a linked task settles via `messageTaskClosed`; one WITHOUT a task had no
+ * completion state at all — after the 30-min lease expired `releaseExpiredClaims` nulled the claim
+ * and the poll re-offered the finished work to every matching agent, forever (#1022 F6). The runner
+ * only marks a claimable read AFTER winning the claim (losers `continue` without reading), so a
+ * read receipt from any non-sender uniquely means "the holder took and processed it" — the missing
+ * settle signal. Gate the expired/unclaimed poll branch with `AND NOT ${claimableHandledNoTask(...)}`.
+ * `messageRef` is a fixed internal column reference, not user input.
+ */
+export function claimableHandledNoTask(messageRef: MessageIdRef): string {
+  const fromAgentRef = messageRef === "m.id" ? "m.from_agent" : "messages.from_agent";
+  return `(NOT EXISTS (SELECT 1 FROM tasks t WHERE t.message_id = ${messageRef}) ` +
+    `AND EXISTS (SELECT 1 FROM message_reads mr WHERE mr.message_id = ${messageRef} AND mr.agent_id <> ${fromAgentRef}))`;
+}

package/src/db/continuations.ts

@@ -55,6 +55,16 @@ export function seedContinuationObjectiveFromSpawnPrompt(agentId: string, spawnR
   return ensureContinuationEnvelope({ agentId, objective: params.prompt, config, now });
 }
 
+// #1023 — the ruledOut ledger was append-only with no cap: cumulative resends
+// duplicated entries verbatim, and nothing bounded total size, so one long-running
+// agent could render a multi-megabyte continuation straight into its own fresh
+// context. MAX_LEDGER_TOTAL_BYTES/MAX_LEDGER_ENTRIES bound what stays in the
+// envelope; dedupe drops literal resends. Entries pushed out by the bound are
+// returned as droppedLedgerEntries so the caller can archive them (still
+// recallable via relay_recall) instead of silently destroying them.
+const MAX_LEDGER_TOTAL_BYTES = 256 * 1024;
+const MAX_LEDGER_ENTRIES = 500;
+
 export function updateContinuationAfterCompact(input: {
   agentId: string;
   generation: number;
@@ -63,7 +73,7 @@ export function updateContinuationAfterCompact(input: {
   archiveRefs?: string[];
   spentTokens: number;
   now?: number;
-}): ContinuationEnvelope {
+}): { envelope: ContinuationEnvelope; droppedLedgerEntries: ContinuationLedgerEntry[] } {
   const existing = getContinuationEnvelope(input.agentId);
   if (!existing) throw new ValidationError("continuation envelope not found");
   const now = input.now ?? Date.now();
@@ -76,20 +86,51 @@ export function updateContinuationAfterCompact(input: {
       tokens: existing.budget.spent.tokens + Math.max(0, input.spentTokens),
     },
   };
+  const { ledger, dropped } = mergeLedger(existing.ledger, input.ledgerEntries);
   getDb().query(`
     UPDATE agent_continuations
     SET generation = ?, ledger = ?, working_state = ?, archive_refs = ?, budget = ?, updated_at = ?
     WHERE agent_id = ?
   `).run(
     input.generation,
-    JSON.stringify([...existing.ledger, ...input.ledgerEntries]),
+    JSON.stringify(ledger),
     input.workingState,
     JSON.stringify([...existing.archiveRefs, ...(input.archiveRefs ?? [])]),
     JSON.stringify(nextBudget),
     now,
     input.agentId,
   );
-  return getContinuationEnvelope(input.agentId)!;
+  return { envelope: getContinuationEnvelope(input.agentId)!, droppedLedgerEntries: dropped };
+}
+
+function ledgerEntryKey(entry: ContinuationLedgerEntry): string {
+  return `${entry.ruledOut.trim().toLowerCase()} ${entry.why.trim().toLowerCase()}`;
+}
+
+function ledgerEntryBytes(entry: ContinuationLedgerEntry): number {
+  return new TextEncoder().encode(entry.ruledOut).byteLength + new TextEncoder().encode(entry.why).byteLength + 48;
+}
+
+function mergeLedger(
+  existing: ContinuationLedgerEntry[],
+  incoming: ContinuationLedgerEntry[],
+): { ledger: ContinuationLedgerEntry[]; dropped: ContinuationLedgerEntry[] } {
+  const seen = new Set(existing.map(ledgerEntryKey));
+  const merged = [...existing];
+  for (const entry of incoming) {
+    const key = ledgerEntryKey(entry);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    merged.push(entry);
+  }
+  let start = merged.length > MAX_LEDGER_ENTRIES ? merged.length - MAX_LEDGER_ENTRIES : 0;
+  let totalBytes = 0;
+  for (let i = merged.length - 1; i >= start; i -= 1) totalBytes += ledgerEntryBytes(merged[i]!);
+  while (totalBytes > MAX_LEDGER_TOTAL_BYTES && start < merged.length - 1) {
+    totalBytes -= ledgerEntryBytes(merged[start]!);
+    start += 1;
+  }
+  return { ledger: merged.slice(start), dropped: merged.slice(0, start) };
 }
 
 export function appendContinuationArchiveRefs(agentId: string, archiveRefs: string[]): ContinuationEnvelope | null {

package/src/db/message-reads.ts

@@ -1,6 +1,6 @@
 import { Database } from "bun:sqlite";
 import { randomUUID } from "node:crypto";
-import { isRecord, stringValue, isMechanicalMessageKind } from "agent-relay-sdk";
+import { isRecord, stringValue, isMechanicalMessageKind, isReportVerbosity, type ReportVerbosity } from "agent-relay-sdk";
 import { ORCHESTRATOR_PROTOCOL_VERSION, VERSION } from "../config.ts";
 import { parseJson } from "../utils";
 import { isLiveIsolatedWorkspace } from "../workspace-phase";
@@ -19,7 +19,7 @@ import { sendMessageWithResult } from "./messages.ts";
 import { deleteArtifactLinksForEntity } from "./artifacts.ts";
 import { getDb, getDbPath, runDbMaintenanceWorker, timedQuery } from "./connection.ts";
 import { legacyChannelTargets, isChannelAgentId } from "./delivery.ts";
-import { messageTaskClosed } from "./claim-sql.ts";
+import { claimableHandledNoTask, messageTaskClosed } from "./claim-sql.ts";
 import { MSG_SELECT, rowToMessage } from "./mappers.ts";
 import type {
   AgentCard,
@@ -306,7 +306,11 @@ export function pollMessages(query: PollQuery): Message[] {
     targetClauses.push(freshFanoutTargetClause(`tag:${tag}`, agent, params));
   }
   for (const cap of agentCaps) {
+    // A capability fan-out is accepted at send time under both `cap:` and its `capability:` alias
+    // (planSend/FANOUT_PREFIXES + the SDK matcher). Poll for BOTH stored forms, or a message sent
+    // to `capability:X` gets a delivered receipt yet is invisible to every poll (#1022 F3).
     targetClauses.push(freshFanoutTargetClause(`cap:${cap}`, agent, params));
+    targetClauses.push(freshFanoutTargetClause(`capability:${cap}`, agent, params));
   }
   if (agentLabel) {
     targetClauses.push(freshFanoutTargetClause(`label:${agentLabel}`, agent, params));
@@ -338,7 +342,9 @@ export function pollMessages(query: PollQuery): Message[] {
   // 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")}))`);
+  // `claimableHandledNoTask` closes the same gap for claimables with NO linked task: once the
+  // holder handled one, its lease expired and it got re-offered to everyone forever (#1022 F6).
+  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")} AND NOT ${claimableHandledNoTask("m.id")}))`);
   params.push(query.for, Date.now());
 
   if (query.sinceId !== undefined) {
@@ -594,6 +600,30 @@ export function seedSpawnPromptMirror(
   }
 }
 
+/**
+ * #1037 — the per-spawn report-up verbosity a spawner chose, read from the persisted `agent.spawn`
+ * command params by spawnRequestId. Mirrors seedSpawnPromptMirror: at first registration the relay
+ * has both the resolved child id and the spawn command, so registration stamps this onto child meta
+ * where the lineage report-up delivery gate reads it. Returns undefined when absent/unparseable
+ * (the gate then defaults to `quiet`).
+ */
+export function readSpawnReportVerbosity(spawnRequestId: string | undefined): ReportVerbosity | undefined {
+  if (!spawnRequestId) return undefined;
+  try {
+    const row = getDb().query(`
+      SELECT params FROM commands
+      WHERE type = 'agent.spawn' AND correlation_id = ?
+      ORDER BY created_at DESC
+      LIMIT 1
+    `).get(spawnRequestId) as { params: string } | undefined;
+    const params = row ? parseJson<unknown>(row.params, {}) : {};
+    if (!isRecord(params)) return undefined;
+    return isReportVerbosity(params.reportVerbosity) ? params.reportVerbosity : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export function markRead(messageId: number, agentId: string): boolean {
   const exists = getDb().query("SELECT 1 FROM messages WHERE id = ?").get(messageId);
   if (!exists) return false;
@@ -607,7 +637,7 @@ export function markRead(messageId: number, agentId: string): boolean {
         delivery_next_retry_at = NULL,
         delivery_poison_reason = NULL,
         delivery_updated_at = ?
-    WHERE id = ? AND (to_target = ? OR resolved_to_agent = ? OR to_target = 'broadcast' OR to_target LIKE 'tag:%' OR to_target LIKE 'cap:%' OR to_target LIKE 'label:%' OR to_target LIKE 'team:%')
+    WHERE id = ? AND (to_target = ? OR resolved_to_agent = ? OR to_target = 'broadcast' OR to_target LIKE 'tag:%' OR to_target LIKE 'cap:%' OR to_target LIKE 'capability:%' OR to_target LIKE 'label:%' OR to_target LIKE 'team:%')
   `).run(Date.now(), messageId, agentId, agentId);
   return true;
 }