agent-relay-server 0.62.3 → 0.63.1

package/src/db/channels.ts

@@ -15,10 +15,12 @@ import {
 } from "../contracts";
 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, listAgents, parseStringArray } from "./agents.ts";
+import { isDeliveryAgent } from "./agent-predicates.ts";
+import { channelAccountIdForAgent, channelProviderForAgent, expectedChannelAgentId } from "./channel-identity.ts";
 import { ValidationError, getDb } from "./connection.ts";
-import { isDeliveryAgent } from "./delivery.ts";
-import { runningAgentForPolicy } from "./messages.ts";
+import { rowToAgent } from "./mappers.ts";
+import { runningAgentForPolicy } from "./policy-runtime.ts";
+import { parseStringArray } from "./shared.ts";
 import type {
   AgentCard,
   ActivityEvent,
@@ -82,7 +84,9 @@ import type {
   WorkspaceStatus,
 } from "../types";
 
-export function rowToChannelBinding(row: any): ChannelBinding {
+export { channelProviderForAgent, expectedChannelAgentId } from "./channel-identity.ts";
+
+function rowToChannelBinding(row: any): ChannelBinding {
   const target = row.target_type === "broadcast"
     ? { type: "broadcast" } as ChannelRouteTarget
     : { type: row.target_type, id: row.target_id } as ChannelRouteTarget;
@@ -105,7 +109,7 @@ export function rowToChannelBinding(row: any): ChannelBinding {
   return binding;
 }
 
-export function bindingTargetToLegacyTarget(target: ChannelRouteTarget): string {
+function bindingTargetToLegacyTarget(target: ChannelRouteTarget): string {
   if (target.type === "agent") return target.id;
   if (target.type === "label") return `label:${target.id}`;
   if (target.type === "team") return `team:${target.id}`;
@@ -118,7 +122,7 @@ export function bindingTargetToLegacyTarget(target: ChannelRouteTarget): string
   return "";
 }
 
-export function configuredChannelsForAgent(agent: AgentCard): string[] {
+function configuredChannelsForAgent(agent: AgentCard): string[] {
   const channels = agent.meta?.channels;
   if (!Array.isArray(channels)) return [];
   return channels
@@ -127,7 +131,7 @@ export function configuredChannelsForAgent(agent: AgentCard): string[] {
     .filter((item) => item.length > 0);
 }
 
-export function channelEntryMatches(channelId: string, entry: string): boolean {
+function channelEntryMatches(channelId: string, entry: string): boolean {
   const normalized = entry.trim();
   if (!normalized) return false;
   if (normalized === channelId) return true;
@@ -135,27 +139,36 @@ export function channelEntryMatches(channelId: string, entry: string): boolean {
   return channelId.startsWith(`${normalized}:`);
 }
 
-export function agentCanServeChannel(agent: AgentCard, channelId?: string): boolean {
+function agentCanServeChannel(agent: AgentCard, channelId?: string): boolean {
   if (!channelId) return true;
   const channels = configuredChannelsForAgent(agent);
   if (channels.length === 0) return true;
   return channels.some((entry) => channelEntryMatches(channelId, entry));
 }
 
-export function channelTargetMatches(target: ChannelRouteTarget, channelId?: string): AgentCard[] {
-  const candidates = listAgents().filter((agent) => (
+function getChannelAgent(id: string): AgentCard | null {
+  const row = getDb().query("SELECT * FROM agents WHERE id = ?").get(id) as any;
+  return row ? rowToAgent(row) : null;
+}
+
+function listChannelAgents(): AgentCard[] {
+  return (getDb().query("SELECT * FROM agents ORDER BY last_seen DESC").all() as any[]).map(rowToAgent);
+}
+
+function channelTargetMatches(target: ChannelRouteTarget, channelId?: string): AgentCard[] {
+  const candidates = listChannelAgents().filter((agent) => (
     agent.id !== "user" &&
     agent.id !== "system" &&
     agent.kind !== "channel" &&
     agent.meta?.kind !== "channel"
   ));
   if (target.type === "agent" || target.type === "orchestrator") {
-    const agent = getAgent(target.id);
+    const agent = getChannelAgent(target.id);
     return agent ? [agent] : [];
   }
   if (target.type === "policy") {
     const agentId = runningAgentForPolicy(target.id);
-    const agent = agentId ? getAgent(agentId) : null;
+    const agent = agentId ? getChannelAgent(agentId) : null;
     return agent ? [agent] : [];
   }
   const channelCandidates = candidates.filter((agent) => agentCanServeChannel(agent, channelId));
@@ -168,15 +181,15 @@ export function channelTargetMatches(target: ChannelRouteTarget, channelId?: str
   return [];
 }
 
-export function poolSelectorMatches(selector: string, candidates: AgentCard[]): AgentCard[] {
+function poolSelectorMatches(selector: string, candidates: AgentCard[]): AgentCard[] {
   if (selector.startsWith("label:")) return candidates.filter((a) => a.label === selector.slice("label:".length));
   if (selector.startsWith("tag:")) return candidates.filter((a) => a.tags.includes(selector.slice("tag:".length)));
   if (selector.startsWith("cap:")) return candidates.filter((a) => a.capabilities.includes(selector.slice("cap:".length)));
-  const agent = getAgent(selector);
+  const agent = getChannelAgent(selector);
   return agent ? [agent] : [];
 }
 
-export function channelTargetMatchSnapshot(agent: AgentCard): ChannelTargetHealth["matches"][number] {
+function channelTargetMatchSnapshot(agent: AgentCard): ChannelTargetHealth["matches"][number] {
   return {
     id: agent.id,
     name: agent.name,
@@ -189,15 +202,15 @@ export function channelTargetMatchSnapshot(agent: AgentCard): ChannelTargetHealt
   };
 }
 
-export function isHealthyChannelTarget(agent: AgentCard, now: number): boolean {
+function isHealthyChannelTarget(agent: AgentCard, now: number): boolean {
   return isDeliveryAgent(agent) && agent.ready && agent.lastSeen > now - STALE_TTL_MS;
 }
 
-export function describeTarget(target: ChannelRouteTarget): string {
+function describeTarget(target: ChannelRouteTarget): string {
   return bindingTargetToLegacyTarget(target);
 }
 
-export function channelTargetHealth(binding: ChannelBinding, now: number = Date.now()): ChannelTargetHealth {
+function channelTargetHealth(binding: ChannelBinding, now: number = Date.now()): ChannelTargetHealth {
   const target = binding.target;
   const targetLabel = describeTarget(target);
   const matches = channelTargetMatches(target, binding.channelId);
@@ -209,7 +222,7 @@ export function channelTargetHealth(binding: ChannelBinding, now: number = Date.
       if (matches.length === 0) return { status: "error", detail: `Pool ${targetLabel}: no eligible agents`, target, matches: [] };
       return { status: "error", detail: `Pool ${targetLabel}: ${healthyEligibles.length} eligible but slot unclaimed`, target, matches: snapshots };
     }
-    const holder = getAgent(binding.poolAgentId);
+    const holder = getChannelAgent(binding.poolAgentId);
     if (!holder || holder.status === "offline") {
       return { status: "error", detail: `Pool ${targetLabel}: holder ${binding.poolAgentId} is offline`, target, matches: snapshots };
     }
@@ -271,7 +284,7 @@ export function channelTargetHealth(binding: ChannelBinding, now: number = Date.
   };
 }
 
-export function rowToChannelSummary(row: any): ChannelSummary {
+function rowToChannelSummary(row: any): ChannelSummary {
   const binding = row.binding_id ? rowToChannelBinding({
     id: row.binding_id,
     channel_id: row.id,
@@ -309,44 +322,7 @@ export function rowToChannelSummary(row: any): ChannelSummary {
   };
 }
 
-
-export function channelProviderForAgent(agent: AgentCard): string {
-  return stringValue(agent.meta?.provider) ??
-    stringValue(agent.meta?.channelType) ??
-    stringValue(agent.meta?.transport) ??
-    agent.tags.find((tag) => tag.startsWith("channel:"))?.slice("channel:".length) ??
-    "custom";
-}
-
-export function channelProviderForInput(input: Pick<RegisterAgentInput, "tags" | "meta">): string {
-  return stringValue(input.meta?.provider) ??
-    stringValue(input.meta?.channelType) ??
-    stringValue(input.meta?.transport) ??
-    (input.tags ?? []).find((tag) => tag.startsWith("channel:"))?.slice("channel:".length) ??
-    "custom";
-}
-
-export function channelAccountIdForAgent(agent: AgentCard, provider: string): string {
-  const accountId = stringValue(agent.meta?.accountId);
-  if (accountId) return accountId;
-  const prefix = `${provider}:`;
-  return agent.id.startsWith(prefix) ? agent.id.slice(prefix.length) : agent.id;
-}
-
-export function channelAccountIdForInput(input: Pick<RegisterAgentInput, "id" | "meta">, provider: string): string {
-  const accountId = stringValue(input.meta?.accountId);
-  if (accountId) return accountId;
-  const prefix = `${provider}:`;
-  return input.id.startsWith(prefix) ? input.id.slice(prefix.length) : input.id;
-}
-
-export function expectedChannelAgentId(input: Pick<RegisterAgentInput, "id" | "tags" | "meta">): string {
-  const provider = channelProviderForInput(input);
-  const accountId = channelAccountIdForInput(input, provider);
-  return `${provider}:${accountId}`;
-}
-
-export function channelDirectionForAgent(agent: AgentCard): ChannelSummary["direction"] {
+function channelDirectionForAgent(agent: AgentCard): ChannelSummary["direction"] {
   const direction = stringValue(agent.meta?.direction);
   return direction === "inbound" || direction === "outbound" || direction === "bidirectional" ? direction : "bidirectional";
 }
@@ -497,7 +473,7 @@ export function upsertChannelBinding(input: {
   return rowToChannelBinding(row);
 }
 
-export interface PoolBindingChange {
+interface PoolBindingChange {
   bindingId: string;
   channelId: string;
   previousAgentId: string | null;
@@ -517,7 +493,7 @@ export function evaluatePoolBindings(now: number = Date.now()): PoolBindingChang
 
     let holderValid = false;
     if (currentAgentId) {
-      const holder = getAgent(currentAgentId);
+      const holder = getChannelAgent(currentAgentId);
       if (holder && holder.status !== "offline" && holder.ready && holder.lastSeen > now - STALE_TTL_MS && agentCanServeChannel(holder, channelId)) {
         if (currentEpoch === null || holder.epoch === currentEpoch) {
           getDb().query("UPDATE channel_bindings SET pool_claim_expires_at = ? WHERE id = ?")
@@ -534,7 +510,7 @@ export function evaluatePoolBindings(now: number = Date.now()): PoolBindingChang
     }
 
     if (!holderValid) {
-      const candidates = listAgents().filter((a) =>
+      const candidates = listChannelAgents().filter((a) =>
         a.id !== "user" && a.id !== "system" && a.kind !== "channel" && a.meta?.kind !== "channel"
       );
       const eligible = poolSelectorMatches(selector, candidates)

package/src/db/connection.ts

@@ -1,4 +1,5 @@
 import { Database } from "bun:sqlite";
+import { DB_SLOW_QUERY_MS } from "../config";
 
 // The shared SQLite handle. Set once by initDb() (schema.ts) and read everywhere
 // else through getDb(). Kept module-private so the only mutation path is setDb().
@@ -33,7 +34,7 @@ export function applyConnectionPragmas(conn: Database): void {
 // Slow-query log. Off unless AGENT_RELAY_DB_SLOW_MS is set (>0). Wraps the
 // execution of the heavy dynamic queries so the next slow query surfaces before
 // it wedges something (see issue #197 — the 8.6s reply-obligation query).
-const SLOW_QUERY_MS = Number(process.env.AGENT_RELAY_DB_SLOW_MS) || 0;
+const SLOW_QUERY_MS = DB_SLOW_QUERY_MS;
 export function timedQuery<T>(label: string, run: () => T): T {
   if (SLOW_QUERY_MS <= 0) return run();
   const start = performance.now();

package/src/db/continuation-archives.ts

@@ -1,8 +1,8 @@
-import { MAX_BODY_BYTES } from "../config";
+import { MAX_BODY_BYTES, continuationArchiveFtsEnabled } from "../config";
 import { getContinuationEnvelope } from "./continuations.ts";
 import { getDb, ValidationError } from "./connection.ts";
 
-export interface ContinuationArchive {
+interface ContinuationArchive {
   id: number;
   ref: string;
   agentId: string;
@@ -11,7 +11,7 @@ export interface ContinuationArchive {
   createdAt: number;
 }
 
-export interface ContinuationArchiveSearchResult extends ContinuationArchive {
+interface ContinuationArchiveSearchResult extends ContinuationArchive {
   score: number | null;
   searchMode: "fts5" | "like";
 }
@@ -28,7 +28,7 @@ interface ContinuationArchiveRow {
 const MAX_RECALL_LIMIT = 20;
 
 export function ensureContinuationArchiveSearchSchema(): void {
-  if (process.env.AGENT_RELAY_DISABLE_CONTINUATION_ARCHIVE_FTS === "1") return;
+  if (!continuationArchiveFtsEnabled()) return;
   try {
     getDb().query(`
       CREATE VIRTUAL TABLE IF NOT EXISTS continuation_archive_segments
@@ -80,7 +80,7 @@ export function archiveContinuationSegment(input: {
   return getContinuationArchive(Number(info.lastInsertRowid))!;
 }
 
-export function getContinuationArchive(id: number): ContinuationArchive | null {
+function getContinuationArchive(id: number): ContinuationArchive | null {
   const row = getDb().query("SELECT * FROM continuation_archives WHERE id = ?").get(id) as ContinuationArchiveRow | undefined;
   return row ? rowToArchive(row) : null;
 }
@@ -115,8 +115,8 @@ export function searchContinuationArchives(input: {
   return searchContinuationArchivesLike(agentId, query, limit);
 }
 
-export function continuationArchiveSearchMode(): "fts5" | "like" {
-  if (process.env.AGENT_RELAY_DISABLE_CONTINUATION_ARCHIVE_FTS === "1") return "like";
+function continuationArchiveSearchMode(): "fts5" | "like" {
+  if (!continuationArchiveFtsEnabled()) return "like";
   const row = getDb().query(`
     SELECT 1 FROM sqlite_master
     WHERE type = 'table' AND name = 'continuation_archive_segments'

package/src/db/delivery.ts

@@ -16,10 +16,11 @@ 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, listAgents } from "./agents.ts";
-import { channelProviderForAgent } from "./channels.ts";
+import { isDeliveryAgent } from "./agent-predicates.ts";
+import { channelProviderForAgent } from "./channel-identity.ts";
 import { getDb } from "./connection.ts";
 import { MSG_SELECT, rowToMessage, rowToMessageDeliveryAttempt } from "./mappers.ts";
-import { getMessage } from "./messages.ts";
+import { getMessage } from "./message-queries.ts";
 import type {
   AgentCard,
   ActivityEvent,
@@ -83,7 +84,7 @@ import type {
   WorkspaceStatus,
 } from "../types";
 
-export function queueDepthLimit(target: string): number {
+function queueDepthLimit(target: string): number {
   const row = getDb().query("SELECT value FROM config WHERE namespace = 'system' AND key = 'message-queue'").get() as { value?: string } | undefined;
   const parsed = row?.value ? parseJson<Record<string, unknown>>(row.value, {}) : {};
   const perTarget = parsed?.maxDepthPerTarget;
@@ -124,13 +125,7 @@ export function enforceQueueLimit(target: string): void {
   })();
 }
 
-export function isDeliveryAgent(agent: AgentCard): boolean {
-  return agent.status !== "offline" &&
-    agent.id !== "user" &&
-    agent.id !== "system" &&
-    agent.kind !== "channel" &&
-    agent.meta?.kind !== "channel";
-}
+export { isDeliveryAgent } from "./agent-predicates.ts";
 
 export function isChannelAgentId(agentId: string): boolean {
   const agent = getAgent(agentId);
@@ -242,7 +237,7 @@ export function getMessageDeliveryAttempts(messageId: number, limit = 50): Messa
   `).all(messageId, safeLimit) as any[]).map(rowToMessageDeliveryAttempt);
 }
 
-export function insertMessageDeliveryAttempt(
+function insertMessageDeliveryAttempt(
   messageId: number,
   input: {
     agentId?: string;
@@ -269,7 +264,7 @@ export function insertMessageDeliveryAttempt(
   );
 }
 
-export function setMessageDeliveryState(
+function setMessageDeliveryState(
   messageId: number,
   input: {
     status: MessageDeliveryStatus;

package/src/db/inbox.ts

@@ -212,7 +212,7 @@ export function createChatHistoryImport(input: {
   return getChatHistoryImport(id)!;
 }
 
-export function getChatHistoryImport(id: string): ChatHistoryImport | null {
+function getChatHistoryImport(id: string): ChatHistoryImport | null {
   const row = getDb().query("SELECT * FROM chat_history_imports WHERE id = ?").get(id) as any | undefined;
   if (!row) return null;
   const entries = (getDb().query(

package/src/db/integrations.ts

@@ -212,7 +212,7 @@ export function listIntegrationTaskStats(): IntegrationTaskStats[] {
   }));
 }
 
-export type IntegrationRegistryInput = {
+type IntegrationRegistryInput = {
   name: string;
   displayName?: string;
   description?: string;
@@ -231,7 +231,7 @@ export type IntegrationRegistryInput = {
   source?: "api" | "env" | "observed";
 };
 
-export function rowToIntegrationRegistry(row: any): Omit<IntegrationSummary, "configured" | "observed" | "callbackConfigured" | "rateLimit" | "taskStats"> & {
+function rowToIntegrationRegistry(row: any): Omit<IntegrationSummary, "configured" | "observed" | "callbackConfigured" | "rateLimit" | "taskStats"> & {
   source: "api" | "env" | "observed";
   lastEventAt?: number;
   lastTaskAt?: number;
@@ -312,7 +312,7 @@ export function upsertIntegrationRegistry(input: IntegrationRegistryInput): Retu
   return getIntegrationRegistry(name)!;
 }
 
-export function getIntegrationRegistry(name: string): ReturnType<typeof rowToIntegrationRegistry> | null {
+function getIntegrationRegistry(name: string): ReturnType<typeof rowToIntegrationRegistry> | null {
   const row = getDb().query("SELECT * FROM integration_registry WHERE name = ?").get(name) as any;
   return row ? rowToIntegrationRegistry(row) : null;
 }
@@ -321,7 +321,7 @@ export function listIntegrationRegistry(): ReturnType<typeof rowToIntegrationReg
   return (getDb().query("SELECT * FROM integration_registry ORDER BY display_name COLLATE NOCASE, name COLLATE NOCASE").all() as any[]).map(rowToIntegrationRegistry);
 }
 
-export function updateIntegrationObserved(name: string, eventAt: number): void {
+function updateIntegrationObserved(name: string, eventAt: number): void {
   const now = Date.now();
   getDb().query(`
     INSERT INTO integration_registry (name, enabled, scopes, targets, channels, tags, manifest, source, created_at, updated_at, last_event_at, last_task_at)

package/src/db/issue-lifecycle.ts

@@ -1,11 +1,11 @@
 import { getDb, ValidationError } from "./connection.ts";
 
-export const ISSUE_LIFECYCLE_ACTIONS = ["close", "reopen"] as const;
-export const ISSUE_LIFECYCLE_STATUSES = ["succeeded", "failed"] as const;
-export type IssueLifecycleAction = (typeof ISSUE_LIFECYCLE_ACTIONS)[number];
-export type IssueLifecycleStatus = (typeof ISSUE_LIFECYCLE_STATUSES)[number];
+const ISSUE_LIFECYCLE_ACTIONS = ["close", "reopen"] as const;
+const ISSUE_LIFECYCLE_STATUSES = ["succeeded", "failed"] as const;
+type IssueLifecycleAction = (typeof ISSUE_LIFECYCLE_ACTIONS)[number];
+type IssueLifecycleStatus = (typeof ISSUE_LIFECYCLE_STATUSES)[number];
 
-export interface IssueLifecycleActionRecord {
+interface IssueLifecycleActionRecord {
   id: number;
   issueRefId: string;
   action: IssueLifecycleAction;
@@ -24,7 +24,7 @@ export interface IssueLifecycleActionRecord {
   updatedAt: number;
 }
 
-export interface UpsertIssueLifecycleActionInput {
+interface UpsertIssueLifecycleActionInput {
   issueRefId: string;
   action: IssueLifecycleAction;
   landKey: string;

package/src/db/mappers.ts

@@ -14,8 +14,7 @@ import {
 } from "../contracts";
 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 { parseStringArray } from "./agents.ts";
-import { artifactId } from "./artifacts.ts";
+import { parseStringArray } from "./shared.ts";
 import type {
   AgentCard,
   ActivityEvent,

package/src/db/merge-lease.ts

@@ -80,7 +80,7 @@ import type {
 
 // --- Per-repo merge serialization lease (issue #157) -----------------------
 
-export interface MergeLeaseRecord {
+interface MergeLeaseRecord {
   repoRoot: string;
   workspaceId: string;
   commandId?: string;
@@ -89,7 +89,7 @@ export interface MergeLeaseRecord {
   expiresAt: number;
 }
 
-export function rowToMergeLease(row: any): MergeLeaseRecord {
+function rowToMergeLease(row: any): MergeLeaseRecord {
   return {
     repoRoot: row.repo_root,
     workspaceId: row.workspace_id,
@@ -171,7 +171,7 @@ export interface MergePauseRecord {
   expiresAt: number;
 }
 
-export function rowToMergePause(row: any): MergePauseRecord {
+function rowToMergePause(row: any): MergePauseRecord {
   return {
     id: row.id,
     repoRoot: row.repo_root,

package/src/db/message-claims.ts

@@ -0,0 +1,16 @@
+import { CLAIM_LEASE_MS } from "../config";
+import { getDb } from "./connection.ts";
+
+export function claimMessageRow(messageId: number, agentId: string, now: number): { ok: false; error: string } | { ok: true } {
+  const expiresAt = now + CLAIM_LEASE_MS;
+  // Idempotent: a same-agent re-claim refreshes the lease (preserving the original claimed_at).
+  // Without this, a delivery failure that locally drops the claim strands the message until the
+  // lease expires (#261) — the holder's retry would otherwise 409 against its own claim.
+  const result = getDb().query(
+    "UPDATE messages SET claimed_by = ?, claimed_at = COALESCE(claimed_at, ?), claim_expires_at = ? WHERE id = ? AND (claimed_by IS NULL OR claimed_by = ?)"
+  ).run(agentId, now, expiresAt, messageId, agentId);
+
+  // Atomic: if changes === 0, someone else claimed it between our read and write
+  if (result.changes === 0) return { ok: false, error: "claim race — already claimed" };
+  return { ok: true };
+}

package/src/db/message-queries.ts

@@ -0,0 +1,8 @@
+import { getDb } from "./connection.ts";
+import { MSG_SELECT, rowToMessage } from "./mappers.ts";
+import type { Message } from "../types";
+
+export function getMessage(id: number): Message | null {
+  const row = getDb().query(`${MSG_SELECT} WHERE m.id = ?`).get(id) as any;
+  return row ? rowToMessage(row) : null;
+}

package/src/db/message-reads.ts

@@ -15,7 +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 } from "./agents.ts";
-import { sendMessageWithResult } from "./messages.ts";
+import { getMessage, sendMessageWithResult } from "./messages.ts";
 import { deleteArtifactLinksForEntity } from "./artifacts.ts";
 import { getDb, timedQuery } from "./connection.ts";
 import { legacyChannelTargets, isChannelAgentId } from "./delivery.ts";
@@ -369,7 +369,7 @@ export function pollMessages(query: PollQuery): Message[] {
   return annotateAnsweredMessages(rows.map(rowToMessage), query.for);
 }
 
-export function messageRequiresReply(message: Message): boolean {
+function messageRequiresReply(message: Message): boolean {
   // Server-owned notification flag (#283) wins over every kind/sender heuristic below: an
   // explicit replyExpected:false is a fire-and-forget message that must never become an obligation.
   if (message.replyExpected === false) return false;
@@ -387,13 +387,13 @@ export function recordField(value: unknown): Record<string, unknown> | undefined
   return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
 }
 
-export function relayConversationId(message: Message): string | undefined {
+function relayConversationId(message: Message): string | undefined {
   const conversation = recordField(message.payload?.conversation);
   const replyContext = recordField(message.payload?.replyContext);
   return stringField(replyContext?.conversationId) ?? stringField(conversation?.id);
 }
 
-export function isCoveredByLaterAgentResponse(message: Message, agentId: string): boolean {
+function isCoveredByLaterAgentResponse(message: Message, agentId: string): boolean {
   // Order by id, not created_at: ids are monotonic insertion order, so this is
   // robust when a reply lands in the same millisecond as the message it covers
   // (created_at > … strictly would miss it, leaving the message wrongly pending).
@@ -414,7 +414,7 @@ export function isCoveredByLaterAgentResponse(message: Message, agentId: string)
   });
 }
 
-export function replyObligationFromMessage(message: Message, agentId: string): ReplyObligation {
+function replyObligationFromMessage(message: Message, agentId: string): ReplyObligation {
   return {
     messageId: message.id,
     agentId,
@@ -482,6 +482,25 @@ export function channelObligationAnsweredBy(
   return open.length === 1 ? open[0]!.messageId : null;
 }
 
+/**
+ * Spawn report-back linking (#492): a spawned worker's actual task is delivered as the provider
+ * prompt, while `seedSpawnReplyObligation` creates a short Stop-hook contract message so the worker
+ * cannot go idle without reporting back. Workers commonly send their natural completion report
+ * directly to the spawning coordinator; when there is exactly one open spawn obligation from that
+ * coordinator, that send is the answer. Link it to the obligation at send time so the Stop hook does
+ * not nag the worker into re-sending the same verdict through `/reply`.
+ */
+export function spawnObligationAnsweredBy(
+  agentId: string,
+  spawnerAgentId: string,
+): number | null {
+  const open = listPendingReplyObligations(agentId, 50).filter((obligation) => {
+    if (obligation.from !== spawnerAgentId) return false;
+    return getMessage(obligation.messageId)?.payload?.source === "spawn-obligation";
+  });
+  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
@@ -490,7 +509,7 @@ export function channelObligationAnsweredBy(
  * spawn command by its `spawnRequestId` (same lookup as `seedContinuationObjectiveFromSpawnPrompt`),
  * and — only when the spawn carried `expectReply` — posts a message FROM the spawner TO the worker
  * and marks it read, making it an obligation immediately. The Stop hook then refuses to let the
- * worker idle until it `/reply`s, which auto-routes back to the spawner and wakes it.
+ * worker idle until it reports back; a natural direct send to the spawner is linked at send time.
  *
  * Call only on first registration; idempotent regardless (idempotencyKey dedups a double-fire).
  * Never throws — a failure here must not abort registration. Returns the obligation message id,
@@ -515,15 +534,13 @@ export function seedSpawnReplyObligation(
     const params = row ? parseJson<unknown>(row.params, {}) : {};
     if (!isRecord(params) || params.expectReply !== true) return null;
 
-    const objective = typeof params.prompt === "string" ? params.prompt.trim() : "";
     const contract = `Report-back requested by ${spawnedBy}. When you finish your spawned task, reply here with your result so the coordinator is notified — you should not go idle before delivering it.`;
-    const body = objective ? `${contract}\n\nYour task was:\n${objective}` : contract;
 
     const { message } = sendMessageWithResult({
       from: spawnedBy,
       to: agentId,
       subject: "Report your result when done",
-      body,
+      body: contract,
       replyExpected: true,
       // `payload.source` is the server-owned "this requires a reply" signal (see messageRequiresReply).
       payload: { source: "spawn-obligation", spawnRequestId },