agent-relay-server 0.62.3 → 0.63.1

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)

package/src/index.ts

@@ -15,7 +15,11 @@ import { startPlanLiveBindings } from "./services/plan-live-bindings";
 import { resolve, sep } from "path";
 import { gzipSync, brotliCompressSync, constants as zlibConstants } from "node:zlib";
 import {
+  AUTOMATION_INTERVAL_MS,
+  IDLE_TIMEOUT_SECONDS,
+  LOG_REQUESTS,
   VERSION,
+  relayToken,
 } from "./config";
 import { CONTRACT_VERSIONS } from "./contracts";
 import {
@@ -69,9 +73,6 @@ function startServer(): void {
   const PORT = Number(process.env.PORT) || 4850;
   const HOST = process.env.HOST || "127.0.0.1";
   const DB_PATH = process.env.DB_PATH || "agent-relay.db";
-  const AUTOMATION_INTERVAL_MS = Number(process.env.AGENT_RELAY_AUTOMATION_INTERVAL_MS) || 30 * 1000;
-  const IDLE_TIMEOUT_SECONDS = Number(process.env.AGENT_RELAY_IDLE_TIMEOUT_SECONDS) || 255;
-  const LOG_REQUESTS = process.env.AGENT_RELAY_LOG_REQUESTS === "1";
 
   assertSafeNetworkConfig(HOST);
   initDb(DB_PATH);
@@ -246,9 +247,9 @@ export function createFetchHandler(
       upstream.protocol = upstream.protocol === "https:" ? "wss:" : "ws:";
       // Pass the relay token as a header (not a query param) so it never lands in
       // access/proxy logs (#149). The orchestrator accepts both, but headers are safer.
-      const relayToken = process.env.AGENT_RELAY_TOKEN;
+      const token = relayToken();
       const upgraded = server.upgrade(req, {
-        data: { kind: "terminal-proxy", upstreamUrl: upstream.toString(), upstreamToken: relayToken, pending: [] },
+        data: { kind: "terminal-proxy", upstreamUrl: upstream.toString(), upstreamToken: token, pending: [] },
       });
       if (!upgraded) return new Response("WebSocket upgrade failed", { status: 400 });
       return undefined;

package/src/issue-tracker/github.ts

@@ -2,7 +2,7 @@ import type { IssueRef, IssueRefStatus } from "../types";
 import type { IssueTrackerAdapter, IssueTrackerCloseOptions, IssueTrackerReopenOptions, IssueTrackerStatus } from "./adapter";
 
 export const GITHUB_FIXED_LABEL = "fixed";
-export const GITHUB_CREDENTIAL_REQUIREMENT = "GitHub issue tracker adapter requires gh authenticated with a token that has issues:write scope";
+const GITHUB_CREDENTIAL_REQUIREMENT = "GitHub issue tracker adapter requires gh authenticated with a token that has issues:write scope";
 
 type GitHubApiMethod = "GET" | "PATCH" | "POST";
 
@@ -12,7 +12,7 @@ export interface GitHubApiRequest {
   body?: Record<string, unknown>;
 }
 
-export type GitHubApi = (request: GitHubApiRequest) => Promise<unknown>;
+type GitHubApi = (request: GitHubApiRequest) => Promise<unknown>;
 
 interface GitHubIssuePayload {
   state?: unknown;
@@ -92,7 +92,7 @@ function uniqueLabels(labels: string[]): string[] {
   return [...new Set(labels.map((label) => label.trim()).filter(Boolean))];
 }
 
-export class GitHubIssueTrackerAdapter implements IssueTrackerAdapter {
+class GitHubIssueTrackerAdapter implements IssueTrackerAdapter {
   constructor(private readonly api: GitHubApi = ghApi) {}
 
   resolveLink(ref: IssueRef): string {

package/src/maintenance/constants.ts

@@ -0,0 +1,52 @@
+import {
+  CONFLICT_SCAN_INTERVAL_MS,
+  DAY_MS,
+  DB_MAINTENANCE_INTERVAL_MS,
+  DB_VACUUM_EVERY,
+  ORPHAN_REAPER_INTERVAL_MS,
+  OUTBOX_RETENTION_MS,
+  REAP_INTERVAL_MS,
+  TOKEN_RECORD_RETENTION_SECONDS,
+  WORKSPACE_AUTO_MERGE_INTERVAL_MS,
+  WORKSPACE_GC_INTERVAL_MS,
+  WORKSPACE_ORPHAN_REAPER_INTERVAL_MS,
+  WORKSPACE_RETENTION_MS,
+  WORKSPACE_REVIEW_TTL_MS,
+  envMsOrDefault,
+  orphanReapCooldownMs,
+  orphanReapEnabled,
+  orphanGraceMs,
+  stewardEscalationMs,
+  stewardFallbackTarget,
+} from "../config";
+import { READY_TO_LAND_STATUSES, TERMINAL_WORKSPACE_STATUSES } from "../workspace-phase";
+import type { WorkspaceStatus } from "../types";
+
+export { DAY_MS, REAP_INTERVAL_MS, TERMINAL_WORKSPACE_STATUSES };
+
+export const DEFAULT_TIMEOUT_MS = 30_000;
+export const SCHEDULER_TICK_MS = 10_000;
+export const STRANDABLE_STATUSES = new Set<WorkspaceStatus>([...READY_TO_LAND_STATUSES, "conflict"]);
+export const CONFLICT_SCAN_STATUSES = new Set<WorkspaceStatus>(["active", "ready", "review_requested", "merge_planned", "conflict"]);
+export const LANDED_RECONCILE_STATUSES = new Set<WorkspaceStatus>(["merge_planned", "review_requested", "conflict"]);
+
+export const teamReapGraceMs = () => envMsOrDefault("TEAM_REAP_GRACE_MS", 30 * 60 * 1000);
+export const teamReapIntervalMs = () => envMsOrDefault("TEAM_REAP_INTERVAL_MS", 5 * 60 * 1000);
+export {
+  CONFLICT_SCAN_INTERVAL_MS,
+  DB_MAINTENANCE_INTERVAL_MS,
+  DB_VACUUM_EVERY,
+  ORPHAN_REAPER_INTERVAL_MS,
+  OUTBOX_RETENTION_MS,
+  TOKEN_RECORD_RETENTION_SECONDS,
+  WORKSPACE_AUTO_MERGE_INTERVAL_MS,
+  WORKSPACE_GC_INTERVAL_MS,
+  WORKSPACE_ORPHAN_REAPER_INTERVAL_MS,
+  WORKSPACE_RETENTION_MS,
+  WORKSPACE_REVIEW_TTL_MS,
+  orphanGraceMs,
+  orphanReapCooldownMs,
+  orphanReapEnabled,
+  stewardEscalationMs,
+  stewardFallbackTarget,
+};

package/src/maintenance/events.ts

@@ -0,0 +1,32 @@
+import { emitRelayEvent } from "../events";
+import { routeNotification, type NotificationScope, type NotificationType } from "../notification-router";
+import type { Command } from "../types";
+
+export function emitCommand(command: Command): void {
+  const suffix = command.status === "timed_out" ? "timed_out" : command.status;
+  emitRelayEvent({
+    type: `command.${suffix}`,
+    source: command.source,
+    subject: command.id,
+    data: { command },
+  });
+}
+
+// Route a maintenance notification, swallowing failures (a stale/missing/misconfigured
+// target must never break the sweep). Returns the target on success, null otherwise.
+export function notifyTarget(
+  type: NotificationType,
+  scope: NotificationScope,
+  target: string,
+  subject: string,
+  body: string,
+  payload: Record<string, unknown>,
+): string | null {
+  if (!target) return null;
+  try {
+    routeNotification({ type, scope, recipients: [target], message: { subject, body, payload } });
+    return target;
+  } catch {
+    return null;
+  }
+}