agent-relay-server 0.62.2 → 0.63.0

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";
@@ -159,6 +159,124 @@ export function listAgentChatHistory(query: {
   return ascending ? messages : messages.reverse();
 }
 
+function agentParticipationClauses(
+  alias: string,
+  agent: AgentCard,
+  legacyTargets: string[],
+  params: any[],
+): string[] {
+  const clauses = [
+    `${alias}.from_agent = ?`,
+    `${alias}.to_target = ?`,
+    `${alias}.resolved_to_agent = ?`,
+  ];
+  params.push(agent.id, agent.id, agent.id);
+  for (const tag of agent.tags) {
+    clauses.push(`${alias}.to_target = ?`);
+    params.push(`tag:${tag}`);
+  }
+  for (const cap of agent.capabilities) {
+    clauses.push(`${alias}.to_target = ?`);
+    params.push(`cap:${cap}`);
+  }
+  if (agent.label) {
+    clauses.push(`${alias}.to_target = ?`);
+    params.push(`label:${agent.label}`);
+  }
+  if (agent.teamId) {
+    clauses.push(`${alias}.to_target = ?`);
+    params.push(`team:${agent.teamId}`);
+  }
+  for (const target of legacyTargets) {
+    clauses.push(`${alias}.to_target = ?`);
+    params.push(target);
+  }
+  return clauses;
+}
+
+function scopedBroadcastClause(agent: AgentCard | null | undefined, legacyTargets: string[], params: any[]): string {
+  const senderGlobal = "NOT EXISTS (SELECT 1 FROM agents sender WHERE sender.id = m.from_agent AND sender.team_id IS NOT NULL)";
+  const noChannel = agent?.teamId
+    ? `(m.channel IS NULL AND (${senderGlobal} OR EXISTS (SELECT 1 FROM agents sender WHERE sender.id = m.from_agent AND sender.team_id = ?)))`
+    : `(m.channel IS NULL AND ${senderGlobal})`;
+  if (agent?.teamId) params.push(agent.teamId);
+  if (!agent) return noChannel;
+
+  const participantParams: any[] = [];
+  const participantClauses = agentParticipationClauses("cp", agent, legacyTargets, participantParams);
+  const channel = `(m.channel IS NOT NULL AND (m.from_agent = ? OR EXISTS (
+    SELECT 1 FROM messages cp
+    WHERE cp.channel = m.channel
+      AND cp.id <> m.id
+      AND (${participantClauses.join(" OR ")})
+  )))`;
+  params.push(agent.id, ...participantParams);
+  return `(${noChannel} OR ${channel})`;
+}
+
+function freshForSessionClause(agent: AgentCard | null | undefined, params: any[]): string {
+  // Same-ms registration+send can happen in tests and on fast local loops; >= preserves genuine
+  // post-registration messages while still excluding historical fan-out backlog for fresh sessions.
+  params.push(agent?.createdAt ?? Date.now());
+  return "(m.claimable = 1 OR m.created_at >= ?)";
+}
+
+function freshFanoutTargetClause(target: string, agent: AgentCard | null | undefined, params: any[]): string {
+  params.push(target);
+  return `(m.to_target = ? AND ${freshForSessionClause(agent, params)})`;
+}
+
+/**
+ * Emojis that count as an explicit acknowledgement of a message thread (#437).
+ * A reaction with one of these suppresses the reply-reminder on subsequent deliveries.
+ * Policy: thumbs-up (👍) and check-mark (✅) classes only — passing reactions like ❤️
+ * or 👀 are not settling and must never cause false suppression.
+ */
+export const ACK_REACTION_EMOJIS: readonly string[] = ["👍", "✅"];
+
+/**
+ * Annotates messages with `replyExpected: false` when this agent has already settled them
+ * via a direct/thread reply OR an ack-class reaction. Used at poll time so the runner's
+ * delivery formatting naturally drops them from the reply-reminder anchor (#437).
+ *
+ * A single batch SQL query covers all replyable messages — no per-message round-trips.
+ */
+function annotateAnsweredMessages(messages: Message[], agentId: string): Message[] {
+  const replyableIds = messages
+    .filter((m) => m.replyExpected !== false && Number.isSafeInteger(m.id) && m.id > 0)
+    .map((m) => m.id);
+  if (replyableIds.length === 0) return messages;
+
+  const idPlaceholders = replyableIds.map(() => "?").join(", ");
+  const ackPlaceholders = ACK_REACTION_EMOJIS.map(() => "?").join(", ");
+
+  const answeredRows = getDb().query(`
+    SELECT m.id FROM messages m
+    WHERE m.id IN (${idPlaceholders})
+      AND (
+        EXISTS (
+          SELECT 1 FROM messages r
+          WHERE r.from_agent = ?
+            AND (
+              r.reply_to = m.id
+              OR (m.thread_id IS NOT NULL AND r.thread_id = m.thread_id AND r.id > m.id)
+            )
+        )
+        OR EXISTS (
+          SELECT 1 FROM message_reactions mr
+          WHERE mr.message_id = m.id
+            AND mr.actor_id = ?
+            AND mr.emoji IN (${ackPlaceholders})
+            AND mr.created_at >= m.created_at
+        )
+      )
+  `).all(...replyableIds, agentId, agentId, ...ACK_REACTION_EMOJIS) as Array<{ id: number }>;
+
+  if (answeredRows.length === 0) return messages;
+  const answeredIds = new Set(answeredRows.map((r) => r.id));
+  return messages.map((m) => (answeredIds.has(m.id) ? { ...m, replyExpected: false as const } : m));
+}
+
 export function pollMessages(query: PollQuery): Message[] {
   const agent = getAgent(query.for);
   const agentTags = agent?.tags ?? [];
@@ -170,24 +288,28 @@ export function pollMessages(query: PollQuery): Message[] {
   const conditions: string[] = [];
   const params: any[] = [];
 
-  // Build target matching: direct + broadcast + tag + capability + label.
+  // Build target matching: direct + scoped broadcast + tag + capability + label.
   // Channel agents also accept legacy bare provider targets (for example
   // "telegram") so older clients keep working after canonical IDs became
   // provider:account ("telegram:default").
-  const targetClauses = ["to_target = ?", "resolved_to_agent = ?", "to_target = 'broadcast'"];
+  const targetClauses = ["to_target = ?", "resolved_to_agent = ?"];
   params.push(query.for, query.for);
+  {
+    const broadcastParams: any[] = [];
+    const broadcastScope = scopedBroadcastClause(agent, agentLegacyChannelTargets, broadcastParams);
+    const fresh = freshForSessionClause(agent, broadcastParams);
+    targetClauses.push(`(m.to_target = 'broadcast' AND ${broadcastScope} AND ${fresh})`);
+    params.push(...broadcastParams);
+  }
 
   for (const tag of agentTags) {
-    targetClauses.push("to_target = ?");
-    params.push(`tag:${tag}`);
+    targetClauses.push(freshFanoutTargetClause(`tag:${tag}`, agent, params));
   }
   for (const cap of agentCaps) {
-    targetClauses.push("to_target = ?");
-    params.push(`cap:${cap}`);
+    targetClauses.push(freshFanoutTargetClause(`cap:${cap}`, agent, params));
   }
   if (agentLabel) {
-    targetClauses.push("to_target = ?");
-    params.push(`label:${agentLabel}`);
+    targetClauses.push(freshFanoutTargetClause(`label:${agentLabel}`, agent, params));
   }
   if (agentTeamId) {
     targetClauses.push("to_target = ?");
@@ -244,10 +366,10 @@ export function pollMessages(query: PollQuery): Message[] {
   params.push(limit);
 
   const rows = timedQuery("pollMessages", () => getDb().query(sql).all(...params) as any[]);
-  return rows.map(rowToMessage);
+  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;
@@ -265,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).
@@ -292,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,
@@ -360,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
@@ -368,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,
@@ -393,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 },

package/src/db/messages.ts

@@ -20,7 +20,11 @@ import { cleanAttachmentRefs, linkAttachmentRefs, validateAttachmentRefs } from
 import { ClaimError, ValidationError, getDb } from "./connection.ts";
 import { enforceQueueLimit, isChannelAgentId, matchingDeliveryAgents } from "./delivery.ts";
 import { MSG_SELECT, normalizeReactionEmoji, rowToMessage } from "./mappers.ts";
-import { getTask, insertTaskEvent, releaseExpiredClaims } from "./tasks.ts";
+import { claimMessageRow } from "./message-claims.ts";
+import { getMessage } from "./message-queries.ts";
+import { runningAgentForPolicy } from "./policy-runtime.ts";
+import { getTask, releaseExpiredClaims } from "./tasks.ts";
+import { insertTaskEvent } from "./task-core.ts";
 import type {
   AgentCard,
   ActivityEvent,
@@ -84,6 +88,10 @@ import type {
   WorkspaceStatus,
 } from "../types";
 
+export { claimMessageRow } from "./message-claims.ts";
+export { getMessage } from "./message-queries.ts";
+export { runningAgentForPolicy } from "./policy-runtime.ts";
+
 export function findMessageByIdempotencyKey(from: string, key: string): Message | null {
   const row = getDb()
     .query(`${MSG_SELECT} WHERE m.from_agent = ? AND m.idempotency_key = ? LIMIT 1`)
@@ -119,51 +127,38 @@ function upsertSessionStepInPlace(existing: Message, input: SendMessageInput, no
   return getMessage(existing.id);
 }
 
-export function policyNameFromTarget(target: string): string | null {
+function policyNameFromTarget(target: string): string | null {
   if (!target.startsWith("policy:")) return null;
   const name = target.slice("policy:".length).trim();
   return name || null;
 }
 
-export function spawnPolicyExists(policyName: string): boolean {
+function spawnPolicyExists(policyName: string): boolean {
   const row = getDb().query("SELECT 1 FROM config WHERE namespace = 'spawn-policy' AND key = ?").get(policyName);
   return Boolean(row);
 }
 
-export function runningAgentForPolicy(policyName: string): string | null {
-  const row = getDb().query(`
-    SELECT agent_id
-    FROM managed_agent_state
-    WHERE policy_name = ? AND status = 'running' AND agent_id IS NOT NULL
-  `).get(policyName) as { agent_id?: string } | undefined;
-  if (!row?.agent_id) return null;
-  const agent = getAgent(row.agent_id);
-  if (!agent || agent.status === "offline") return null;
-  return row.agent_id;
-}
-
-
-export function claimableAllowedForTarget(target: string): boolean {
+function claimableAllowedForTarget(target: string): boolean {
   return matchingDeliveryAgents(target).length > 1;
 }
 
-export function shouldStoreClaimable(input: SendMessageInput): boolean {
+function shouldStoreClaimable(input: SendMessageInput): boolean {
   if (!input.claimable) return false;
   if (input.kind === "task" || input.kind === "system") return true;
   if (input.kind === "channel.event") return true;
   return claimableAllowedForTarget(input.to);
 }
 
-export function inferMessageKind(input: SendMessageInput): Message["kind"] {
+function inferMessageKind(input: SendMessageInput): Message["kind"] {
   if (input.kind) return input.kind;
   if (input.claimable) return "task";
   if (isChannelAgentId(input.from) || isChannelAgentId(input.to)) return "channel.event";
   return "chat";
 }
 
-export const REPLY_DUPLICATE_WINDOW_MS = 2 * 60 * 1000;
+const REPLY_DUPLICATE_WINDOW_MS = 2 * 60 * 1000;
 
-export function findRecentDuplicateReply(input: SendMessageInput, threadId: number | null, now: number, hasAttachments: boolean): Message | null {
+function findRecentDuplicateReply(input: SendMessageInput, threadId: number | null, now: number, hasAttachments: boolean): Message | null {
   if (!input.replyTo || threadId === null || hasAttachments) return null;
   const row = getDb().query(`
     ${MSG_SELECT}
@@ -192,7 +187,7 @@ export function findRecentDuplicateReply(input: SendMessageInput, threadId: numb
 // receive time — but it must be a sane epoch-ms value. Returns null (column stays NULL, so
 // readers fall back to created_at) for absent/invalid values or anything more than a minute
 // in the future (clock-skew guard). Only a real backfilled time is stored.
-export function sanitizeOccurredAt(occurredAt: number | undefined, receivedAt: number): number | null {
+function sanitizeOccurredAt(occurredAt: number | undefined, receivedAt: number): number | null {
   if (typeof occurredAt !== "number" || !Number.isFinite(occurredAt)) return null;
   if (occurredAt <= 0 || occurredAt > receivedAt + 60_000) return null;
   return Math.floor(occurredAt);
@@ -265,13 +260,13 @@ export function sendMessageWithResult(input: SendMessageInput): { message: Messa
     }
   }
 
-  // #451 — moderate default TTL for fire-and-forget FAN-OUT messages the sender didn't bound, so a
-  // stale broadcast/tag/cap/label/team push can't wake a late-joining agent hours later. Exempt
+  // #451/#461 — moderate default TTL for non-claimable FAN-OUT messages the sender didn't bound,
+  // so stale broadcast/tag/cap/label/team chat cannot wake a late-joining agent hours later. Exempt
   // (never auto-expire, preserving store-ahead #234): direct DMs and policy targets (single
-  // recipient), reply-obligations (replyExpected !== false), claimable work, and any message that
-  // already carried an explicit TTL — including an explicit `null` from routeNotification, whose
-  // per-type decision (e.g. a store-ahead `plan.bound_agent_exited` to `team:`) must win here.
-  if (ttlUnspecified && input.replyExpected === false && !claimable && isFanoutTarget(input.to)) {
+  // recipient), claimable work, and any message that already carried an explicit TTL — including an
+  // explicit `null` from routeNotification, whose per-type decision (e.g. a store-ahead
+  // `plan.bound_agent_exited` to `team:`) must win here.
+  if (ttlUnspecified && !claimable && isFanoutTarget(input.to)) {
     maxAgeSeconds = DEFAULT_FANOUT_TTL_SECONDS;
   }
 
@@ -369,20 +364,6 @@ export function findMessageByTelegramSource(input: {
   return row ? rowToMessage(row) : null;
 }
 
-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 };
-}
-
 export function claimMessage(messageId: number, agentId: string, guard?: AgentSessionGuard): { ok: boolean; error?: string; task?: Task } {
   releaseExpiredClaims();
   const session = validateAgentSession(agentId, guard);
@@ -475,9 +456,3 @@ export function renewMessageClaim(messageId: number, agentId: string, guard?: Ag
   })();
   return { ok: true, task };
 }
-
-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/notification-subscriptions.ts

@@ -9,10 +9,10 @@ import { getDb, ValidationError } from "./connection";
 export const NOTIFICATION_SUBSCRIPTION_TYPES = ["*", ...Object.keys(DEFAULT_TTL_MS)] as Array<NotificationType | "*">;
 export const NOTIFICATION_SUBSCRIPTION_MODES = ["opt_in", "opt_out", "mute"] as const;
 
-export type NotificationSubscriptionType = NotificationType | "*";
+type NotificationSubscriptionType = NotificationType | "*";
 export type NotificationSubscriptionMode = (typeof NOTIFICATION_SUBSCRIPTION_MODES)[number];
 
-export interface NotificationSubscription {
+interface NotificationSubscription {
   id: string;
   agentId: string;
   type: NotificationSubscriptionType;

package/src/db/orchestrators.ts

@@ -82,7 +82,7 @@ import type {
 
 // --- Orchestrators ---
 
-export function rowToOrchestrator(row: any): Orchestrator {
+function rowToOrchestrator(row: any): Orchestrator {
   const meta = parseJson<Record<string, unknown>>(row.meta, {});
   const runtimePackage = parseRuntimePackage(meta.package);
   const version = stringValue(meta.version);
@@ -133,7 +133,7 @@ export function rowToOrchestrator(row: any): Orchestrator {
   };
 }
 
-export function parseOrchestratorUpgrade(value: unknown): OrchestratorUpgradeState | undefined {
+function parseOrchestratorUpgrade(value: unknown): OrchestratorUpgradeState | undefined {
   if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
   const v = value as Record<string, unknown>;
   const desiredVersion = stringValue(v.desiredVersion);
@@ -167,7 +167,7 @@ export function setOrchestratorUpgradeState(id: string, state: OrchestratorUpgra
 }
 
 
-export function orchestratorHealth(version: string | undefined, compatibility: ReturnType<typeof contractCompatibility>): OrchestratorHealth {
+function orchestratorHealth(version: string | undefined, compatibility: ReturnType<typeof contractCompatibility>): OrchestratorHealth {
   const issues: OrchestratorHealth["issues"] = [];
   if (!version) {
     issues.push({ code: "missing-version", detail: "Orchestrator did not report a package version." });
@@ -204,7 +204,7 @@ export function orchestratorHealth(version: string | undefined, compatibility: R
   };
 }
 
-export function mergeOrchestratorRuntimeMeta(meta: Record<string, unknown>, input: OrchestratorRuntimeInput): Record<string, unknown> {
+function mergeOrchestratorRuntimeMeta(meta: Record<string, unknown>, input: OrchestratorRuntimeInput): Record<string, unknown> {
   const contracts = parseRuntimeContracts(input.contracts, input.protocolVersion !== undefined ? { orchestratorProtocol: input.protocolVersion } : {});
   const capabilities = parseRuntimeCapabilities(input.capabilities);
   return {

package/src/db/pair-maintenance.ts

@@ -0,0 +1,9 @@
+import { getDb } from "./connection.ts";
+
+export function closeOpenPairsForAgent(agentId: string, now: number = Date.now()): void {
+  getDb().query(`
+    UPDATE pairs
+    SET status = 'ended', ended_at = ?, ended_by = ?, updated_at = ?
+    WHERE status IN ('pending', 'active') AND (requester_id = ? OR target_id = ?)
+  `).run(now, agentId, now, agentId, agentId);
+}