agent-relay-server 0.62.3 → 0.63.0

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 },

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);
@@ -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,8 +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);
+}

package/src/db/pairs.ts

@@ -18,6 +18,7 @@ import { getAgent, listAgents } from "./agents.ts";
 import { getDb } from "./connection.ts";
 import { rowToPair } from "./mappers.ts";
 import { sendMessage } from "./messages.ts";
+export { closeOpenPairsForAgent } from "./pair-maintenance.ts";
 import type {
   AgentCard,
   ActivityEvent,
@@ -81,24 +82,16 @@ import type {
   WorkspaceStatus,
 } from "../types";
 
-export const OPEN_PAIR_STATUSES = ["pending", "active"] as const;
-export const DEFAULT_PAIR_TTL_MS = 5 * 60_000;
-export const MAX_PAIR_TTL_MS = DAY_MS;
+const OPEN_PAIR_STATUSES = ["pending", "active"] as const;
+const DEFAULT_PAIR_TTL_MS = 5 * 60_000;
+const MAX_PAIR_TTL_MS = DAY_MS;
 
-export function expirePendingPairs(now: number = Date.now()): void {
+function expirePendingPairs(now: number = Date.now()): void {
   getDb().query("UPDATE pairs SET status = 'expired', updated_at = ?, ended_at = ? WHERE status = 'pending' AND expires_at <= ?")
     .run(now, now, now);
 }
 
-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);
-}
-
-export function getOpenPairForAgent(agentId: string): PairSession | null {
+function getOpenPairForAgent(agentId: string): PairSession | null {
   expirePendingPairs();
   const row = getDb().query(`
     SELECT * FROM pairs
@@ -109,15 +102,15 @@ export function getOpenPairForAgent(agentId: string): PairSession | null {
   return row ? rowToPair(row) : null;
 }
 
-export function pairParticipant(pair: PairSession, agentId: string): boolean {
+function pairParticipant(pair: PairSession, agentId: string): boolean {
   return pair.requesterId === agentId || pair.targetId === agentId;
 }
 
-export function pairPeer(pair: PairSession, agentId: string): string {
+function pairPeer(pair: PairSession, agentId: string): string {
   return pair.requesterId === agentId ? pair.targetId : pair.requesterId;
 }
 
-export function resolvePairTarget(target: string, requesterId: string): {
+function resolvePairTarget(target: string, requesterId: string): {
   ok: true;
   agent: AgentCard;
 } | {
@@ -153,7 +146,7 @@ export function resolvePairTarget(target: string, requesterId: string): {
   return { ok: true, agent: available[0]! };
 }
 
-export function pairSystemMessage(pair: PairSession, to: string, event: string, subject: string, body: string): Message {
+function pairSystemMessage(pair: PairSession, to: string, event: string, subject: string, body: string): Message {
   return sendMessage({
     from: "system",
     to,
@@ -321,4 +314,3 @@ export function sendPairMessage(id: string, input: PairMessageInput): { ok: true
   getDb().query("UPDATE pairs SET last_message_at = ?, updated_at = ? WHERE id = ?").run(now, now, id);
   return { ok: true, pair: getPair(id)!, message };
 }
-

package/src/db/plans.ts

@@ -30,7 +30,7 @@ interface PlanVersionRow {
   changed_at: number;
 }
 
-export interface PlanVersionEntry {
+interface PlanVersionEntry {
   id: number;
   planId: string;
   version: number;

package/src/db/policy-runtime.ts

@@ -0,0 +1,14 @@
+import { getDb } from "./connection.ts";
+
+export function runningAgentForPolicy(policyName: string): string | null {
+  const row = getDb().query(`
+    SELECT s.agent_id
+    FROM managed_agent_state s
+    JOIN agents a ON a.id = s.agent_id
+    WHERE s.policy_name = ?
+      AND s.status = 'running'
+      AND s.agent_id IS NOT NULL
+      AND a.status != 'offline'
+  `).get(policyName) as { agent_id?: string } | undefined;
+  return row?.agent_id ?? null;
+}

package/src/db/project-entries.ts

@@ -203,7 +203,7 @@ const BLACKBOARD_TO_PROJECT_KIND: Record<BlackboardEntryKind, ProjectEntryKind>
   ruled_out: "rule",
 };
 
-export interface PromoteBlackboardEntryInput {
+interface PromoteBlackboardEntryInput {
   blackboardEntryId: string;
   projectId: string;
 }

package/src/db/projects.ts

@@ -76,7 +76,7 @@ export function rootsForProject(id: string): ProjectRoot[] {
   return rows.map(rowToRoot);
 }
 
-export interface EnsureProjectInput {
+interface EnsureProjectInput {
   slug: string;
   title?: string;
   description?: string;
@@ -265,7 +265,7 @@ export function dependencies(projectId: string): string[] {
   return rows.map((row) => row.to_project);
 }
 
-export interface ResolveProjectEntriesOptions {
+interface ResolveProjectEntriesOptions {
   kind?: ProjectEntryKind;
   includeInactive?: boolean;
   /** When true (default), merge in entries from transitive `contains` ancestors,

package/src/db/shared.ts

@@ -0,0 +1,7 @@
+import { parseJson } from "../utils";
+
+export function parseStringArray(raw: string): string[] {
+  const parsed = parseJson<unknown>(raw, []);
+  if (!Array.isArray(parsed)) return [];
+  return parsed.filter((value): value is string => typeof value === "string");
+}

package/src/db/stats.ts

@@ -147,7 +147,7 @@ export type AnalyticsPeriod = keyof typeof ANALYTICS_PERIODS;
 // Conversation categories. Order is significant: a claimable/channel/pair message
 // is classified as such even when it is also a reply; only an otherwise-plain reply
 // counts as "Replies". Session/control/system rows are EXCLUDED (they're streams 2/mechanical).
-export const CONVERSATION_CATEGORIES = ["Chat", "Replies", "Channel", "Pair", "Work items"] as const;
+const CONVERSATION_CATEGORIES = ["Chat", "Replies", "Channel", "Pair", "Work items"] as const;
 export type ConversationCategory = (typeof CONVERSATION_CATEGORIES)[number];
 const CONVERSATION_CATEGORY_SQL = `
   CASE
@@ -162,7 +162,7 @@ const CONVERSATION_FILTER = `kind NOT IN ('session','control','system') AND from
 
 // Session-mirror event sub-types we surface as the "agent work" composition. (prompt
 // is counted in the user-interaction stream; notice is mechanical chatter.)
-export const WORK_TYPES = ["tool", "reasoning", "narration", "response"] as const;
+const WORK_TYPES = ["tool", "reasoning", "narration", "response"] as const;
 export type WorkType = (typeof WORK_TYPES)[number];
 
 export interface AnalyticsData {

package/src/db/task-core.ts

@@ -0,0 +1,18 @@
+import { getDb } from "./connection.ts";
+import { rowToTaskEvent } from "./mappers.ts";
+import type { TaskEvent } from "../types";
+
+export const TASK_SELECT = "SELECT * FROM tasks";
+
+export function insertTaskEvent(taskId: number, event: Required<Omit<TaskEvent, "id" | "taskId" | "createdAt">>, now: number): TaskEvent {
+  const result = getDb().query(`
+    INSERT INTO task_events (task_id, source, type, severity, title, body, metadata, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(taskId, event.source, event.type, event.severity, event.title, event.body, JSON.stringify(event.metadata), now);
+  return getTaskEvent(Number(result.lastInsertRowid))!;
+}
+
+function getTaskEvent(id: number): TaskEvent | null {
+  const row = getDb().query("SELECT * FROM task_events WHERE id = ?").get(id) as any;
+  return row ? rowToTaskEvent(row) : null;
+}

package/src/db/task-maintenance.ts

@@ -0,0 +1,24 @@
+import { getDb } from "./connection.ts";
+import { TASK_SELECT, insertTaskEvent } from "./task-core.ts";
+
+// On-demand automation tasks (targetMode=on_demand_agent) are bound to a single
+// ephemeral agent spawned just for that task. When that agent's claim is released,
+// the task must not return to a claimable pool that can never match it again.
+export function settleSingleTargetOnDemandTasks(condition: string, params: any[], now: number, reason: string): void {
+  const selectSql = `${TASK_SELECT} WHERE (${condition}) AND json_extract(metadata, '$.targetMode') = 'on_demand_agent' AND status IN ('claimed', 'in_progress', 'blocked', 'orphaned')`;
+  const rows = getDb().query(selectSql).all(...params) as any[];
+  if (rows.length === 0) return;
+  getDb().query(
+    `UPDATE tasks SET status = 'done', claim_expires_at = NULL, updated_at = ?, last_seen_at = ? WHERE (${condition}) AND json_extract(metadata, '$.targetMode') = 'on_demand_agent' AND status IN ('claimed', 'in_progress', 'blocked', 'orphaned')`
+  ).run(now, now, ...params);
+  for (const row of rows) {
+    insertTaskEvent(row.id, {
+      source: "agent-relay",
+      type: "task.auto-completed",
+      severity: row.severity,
+      title: "On-demand task auto-resolved",
+      body: `On-demand agent ${row.claimed_by ?? "(unknown)"} exited (${reason}); task resolved so it does not orphan`,
+      metadata: { agentId: row.claimed_by, reason, completedBy: "relay" },
+    }, now);
+  }
+}

package/src/db/tasks.ts

@@ -14,11 +14,13 @@ 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, settleSingleTargetOnDemandTasks, validateAgentSession } from "./agents.ts";
+import { getAgent, validateAgentSession } from "./agents.ts";
 import { messageTaskClosed } from "./claim-sql.ts";
 import { ClaimError, getDb } from "./connection.ts";
 import { rowToTask, rowToTaskEvent } from "./mappers.ts";
-import { claimMessageRow } from "./messages.ts";
+import { claimMessageRow } from "./message-claims.ts";
+import { TASK_SELECT, insertTaskEvent } from "./task-core.ts";
+import { settleSingleTargetOnDemandTasks } from "./task-maintenance.ts";
 import type {
   AgentCard,
   ActivityEvent,
@@ -82,7 +84,7 @@ import type {
   WorkspaceStatus,
 } from "../types";
 
-export const TASK_SELECT = "SELECT * FROM tasks";
+export { TASK_SELECT, insertTaskEvent } from "./task-core.ts";
 
 export function findOpenTaskByDedupe(source: string, dedupeKey: string): Task | null {
   const row = getDb()
@@ -91,19 +93,6 @@ export function findOpenTaskByDedupe(source: string, dedupeKey: string): Task |
   return row ? rowToTask(row) : null;
 }
 
-export function insertTaskEvent(taskId: number, event: Required<Omit<TaskEvent, "id" | "taskId" | "createdAt">>, now: number): TaskEvent {
-  const result = getDb().query(`
-    INSERT INTO task_events (task_id, source, type, severity, title, body, metadata, created_at)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
-  `).run(taskId, event.source, event.type, event.severity, event.title, event.body, JSON.stringify(event.metadata), now);
-  return getTaskEvent(Number(result.lastInsertRowid))!;
-}
-
-export function getTaskEvent(id: number): TaskEvent | null {
-  const row = getDb().query("SELECT * FROM task_events WHERE id = ?").get(id) as any;
-  return row ? rowToTaskEvent(row) : null;
-}
-
 export function taskMessageBody(task: Pick<Task, "id" | "source" | "severity" | "body" | "externalUrl" | "dedupeKey">): string {
   const lines = [
     `[task:${task.id}] ${task.severity.toUpperCase()} from ${task.source}`,
@@ -405,4 +394,3 @@ export function listCallbackDeliveries(taskId: number): Array<{
 }
 
 // --- Pair sessions ---
-

package/src/db/teams.ts

@@ -26,7 +26,7 @@ interface TeamRow {
   dissolved_at: number | null;
 }
 
-export interface TeamDissolveInput {
+interface TeamDissolveInput {
   outcomeStatus?: Team["outcomeStatus"];
   outcomeSummary?: string;
   landsClean?: boolean;
@@ -53,7 +53,7 @@ export interface TeamOutcomeCompositionAggregate {
   avgWallClockMs: number | null;
 }
 
-export interface TeamOutcomeRecent {
+interface TeamOutcomeRecent {
   id: string;
   title?: string;
   outcome: Team["outcomeStatus"] | null;
@@ -274,7 +274,7 @@ export function getTeamOutcomeAggregates(input: { recentLimit?: number } = {}):
   };
 }
 
-export interface TeamDissolveResult {
+interface TeamDissolveResult {
   team: Team;
   /** Active blackboard findings not yet lifted into a project — surfaced (not auto-promoted)
    * so the operator/agent can decide what graduates to durable project knowledge (#404). */

package/src/db/workspaces.ts

@@ -78,7 +78,7 @@ import type {
   WorkspaceStatus,
 } from "../types";
 
-export function rowToWorkspace(row: any): WorkspaceRecord {
+function rowToWorkspace(row: any): WorkspaceRecord {
   return {
     id: row.id,
     repoRoot: row.repo_root,
@@ -266,7 +266,7 @@ export function pruneOrphanedSharedWorkspaces(): string[] {
 // owner's branch-state badge" (#236). A hook, not a direct emit, because getDb().ts is
 // the lowest layer — sse.ts imports db, so db can't import sse without a cycle. sse
 // registers a listener at startup that re-emits the owner agent's status over SSE.
-export type WorkspaceChangeListener = (workspace: WorkspaceRecord) => void;
+type WorkspaceChangeListener = (workspace: WorkspaceRecord) => void;
 export const workspaceChangeListeners = new Set<WorkspaceChangeListener>();
 export function onWorkspaceChange(listener: WorkspaceChangeListener): void {
   workspaceChangeListeners.add(listener);
@@ -322,9 +322,9 @@ export function setWorkspaceBranch(id: string, branch: string, baseSha?: string)
 
 // Workspace statuses that count as "live" for stewardship — an agent owning one
 // of these is a candidate steward; the repo is worth coordinating.
-export const STEWARD_LIVE_STATUSES = "'active', 'ready', 'conflict', 'review_requested', 'merge_planned'";
+const STEWARD_LIVE_STATUSES = "'active', 'ready', 'conflict', 'review_requested', 'merge_planned'";
 
-export interface RepoStewardRecord {
+interface RepoStewardRecord {
   repoRoot: string;
   stewardAgentId?: string;
   lastStewardAgentId?: string;
@@ -332,7 +332,7 @@ export interface RepoStewardRecord {
   updatedAt: number;
 }
 
-export function rowToRepoSteward(row: any): RepoStewardRecord {
+function rowToRepoSteward(row: any): RepoStewardRecord {
   return {
     repoRoot: row.repo_root,
     stewardAgentId: row.steward_agent_id ?? undefined,
@@ -354,7 +354,7 @@ export function listRepoStewards(): RepoStewardRecord[] {
 // Persist the elected steward for a repo. The row is never deleted, so a repo's
 // stewardship survives a full all-agents-offline gap (steward goes NULL/dormant,
 // last_steward_agent_id keeps continuity) and resumes on the next agent join.
-export function upsertRepoSteward(repoRoot: string, steward: string | null, now: number): void {
+function upsertRepoSteward(repoRoot: string, steward: string | null, now: number): void {
   getDb().query(`
     INSERT INTO repo_stewards (repo_root, steward_agent_id, last_steward_agent_id, elected_at, updated_at)
     VALUES ($repoRoot, $steward, $steward, $electedAt, $now)