@humwick/server 0.130.2 → 0.130.3

package/src/db/messages.ts

@@ -59,9 +59,9 @@ 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`)
-    .get(from, key) as any;
-  return row ? rowToMessage(row) : null;
+    .query("SELECT m.id FROM messages m WHERE m.from_agent = ? AND m.idempotency_key = ? LIMIT 1")
+    .get(from, key) as { id: number } | null;
+  return row ? getMessage(row.id) : null;
 }
 
 function sessionStepId(payload: Record<string, unknown> | undefined): string | undefined {
@@ -162,7 +162,7 @@ function findRecentDuplicateReply(input: SendMessageInput, threadId: number | nu
   if (!input.replyTo || threadId === null || hasAttachments) return null;
   const kind = inferMessageKind(input);
   const row = getDb().query(`
-    ${MSG_SELECT}
+    SELECT m.id FROM messages m
     WHERE m.from_agent = ?
       AND m.to_target = ?
       AND m.kind = ?
@@ -183,8 +183,8 @@ function findRecentDuplicateReply(input: SendMessageInput, threadId: number | nu
     input.subject ?? null,
     input.channel ?? null,
     now - REPLY_DUPLICATE_WINDOW_MS,
-  ) as any;
-  return row ? rowToMessage(row) : null;
+  ) as { id: number } | null;
+  return row ? getMessage(row.id) : null;
 }
 
 function sessionMeta(input: Message | SendMessageInput): Record<string, unknown> | undefined {
@@ -252,8 +252,8 @@ function findLineageReportByTurn(input: {
     lineageKey,
     `response-report:${input.from}:%:${input.turnId}`,
     input.turnId,
-  ) as any;
-  return row ? rowToMessage(row) : null;
+  ) as { id: number } | null;
+  return row ? getMessage(row.id) : null;
 }
 
 function findRecentLineageReport(input: SendMessageInput, now: number): Message | null {
@@ -275,8 +275,8 @@ function findRecentLineageReport(input: SendMessageInput, now: number): Message
     if (duplicate) return duplicate;
   }
   if (responseCapture) return null;
-  const row = getDb().query(RECENT_LINEAGE_REPORT_SQL).get(from, to, input.body, now - LINEAGE_REPORT_DUPLICATE_WINDOW_MS, `response-report:${from}:%`) as any;
-  return row ? rowToMessage(row) : null;
+  const row = getDb().query(RECENT_LINEAGE_REPORT_SQL).get(from, to, input.body, now - LINEAGE_REPORT_DUPLICATE_WINDOW_MS, `response-report:${from}:%`) as { id: number } | null;
+  return row ? getMessage(row.id) : null;
 }
 
 // T4458 (Edin's rule #2844 1a) — the sender's currently-open provider turn: the newest
@@ -340,10 +340,10 @@ function findSameTurnExplicitReport(input: {
     input.to,
     ...(input.turnId ? [input.from, input.turnId, fallback] : [fallback]),
     input.at + LINEAGE_REPORT_DUPLICATE_WINDOW_MS,
-  ) as any[];
+  ) as Array<{ id: number; body: string | null }>;
   for (const row of rows) {
     const explicit = normBody(String(row?.body ?? ""));
-    if (explicit.length >= SAME_TURN_MIN_CHARS && explicit.includes(body)) return rowToMessage(row);
+    if (explicit.length >= SAME_TURN_MIN_CHARS && explicit.includes(body)) return getMessage(row.id);
   }
   return null;
 }
@@ -361,9 +361,9 @@ function findTurnExplicitReport(input: {
   captureLen: number;
   captureOccurredAt: number;
 }): Message | null {
-  const row = getDb().query(TURN_EXPLICIT_REPORT_SQL).get(input.from, input.to, input.turnId, input.before) as any;
-  if (!row) return null;
-  const message = rowToMessage(row);
+  const row = getDb().query(TURN_EXPLICIT_REPORT_SQL).get(input.from, input.to, input.turnId, input.before) as { id: number } | null;
+  const message = row ? getMessage(row.id) : null;
+  if (!message) return null;
   const explicitLen = normBody(String(message.body ?? "")).length;
   if (explicitLen < SAME_TURN_MIN_CHARS || explicitLen < 0.5 * input.captureLen) return null;
   // MED-1 (r1 review): a stamp is turn inference and can go stale — t1's late final can land
@@ -409,8 +409,8 @@ function findRecentExplicitLineageDuplicate(input: {
     input.to,
     input.body,
     input.since,
-  ) as any;
-  return row ? rowToMessage(row) : null;
+  ) as { id: number } | null;
+  return row ? getMessage(row.id) : null;
 }
 
 // #1084/#3304 — reporting a definitive provider completion does not close its work window.
@@ -418,9 +418,14 @@ function findRecentExplicitLineageDuplicate(input: {
 const LINEAGE_FINAL_GROUP_RECENCY_MS = 10 * 60 * 1000;
 export { __resetDeferredLineageReports, restoreDeferredLineageReports, takeDeferredLineageReports } from "./deferred-lineage-reports.ts";
 
+export interface LineageReportResult {
+  message: Message;
+  created: boolean;
+  lifecycleSignals?: Array<{ recipient: string; subjectKey: string }>;
+}
 export interface WorkFinalFlushResult {
   /** The chat report(s) forwarded (or found already-forwarded) to the spawner, oldest first. */
-  forwarded: Array<{ message: Message; created: boolean }>;
+  forwarded: LineageReportResult[];
   /** The original session-mirror captures retroactively tagged `payload.finality` (for the
    * `message.finalized` SSE upgrade of already-rendered bubbles). */
   finalizedOriginals: Message[];
@@ -533,12 +538,11 @@ function edgeFallbackReportScore(body: string): number {
 // redundant "Task status pulse" for the same child/task is suppressed rather than double-waking.
 // #1038 — a report-up conveys "the child is progressing", so it is state-keyed to `working`: it
 // supersedes only a redundant `working` pulse, never a later distinct milestone (committed/landed/done).
-function stampReportUpLifecycleSignal(parent: string, child: AgentCard): void {
-  stampLifecycleSignal(parent, childSignalKey(child.id));
-  for (const taskId of childTaskIds(child)) stampLifecycleSignal(parent, taskSignalKey(taskId, LIFECYCLE_STATE_WORKING));
+export function applyLineageReportEffects(result: LineageReportResult | null): void {
+  for (const signal of result?.lifecycleSignals ?? []) stampLifecycleSignal(signal.recipient, signal.subjectKey);
 }
 
-export function promoteLineageCapturedResponse(message: Message): { message: Message; created: boolean } | null {
+export function promoteLineageCapturedResponse(message: Message, deferred?: Array<{ childId: string; messageId: number }>): LineageReportResult | null {
   if (message.kind !== "session" || isReportSuppressed(message)) return null;
   const session = sessionMeta(message);
   if (!session) return null;
@@ -556,7 +560,8 @@ export function promoteLineageCapturedResponse(message: Message): { message: Mes
   // #3304 — provider completion is enough to report a turn, without declaring the Task done.
   // Keep the ring for later work-final metadata; addressed captures already have a runner reply.
   if (stream === "responses" && verbosity !== "verbose") {
-    deferLineageReport(child.id, message.id);
+    if (deferred) deferred.push({ childId: child.id, messageId: message.id });
+    else deferLineageReport(child.id, message.id);
     if (session.confidence !== "definitive" || session.endedBy !== "completed" || message.replyTo) return null;
     if (lineageDeliveryCoversCapture(message, child, parent, message.createdAt)) return null;
   }
@@ -576,7 +581,7 @@ function forwardLineageStreamCapture(
   child: AgentCard,
   parent: string,
   finality?: MessageWorkFinality,
-): { message: Message; created: boolean } | null {
+): LineageReportResult | null {
   const parentAgentId = parent;
   parent = canonicalLineageReportTarget(child, parent);
   const idempotencyKey = lineageStreamReportKey(message, session, stream);
@@ -679,7 +684,8 @@ function forwardLineageStreamCapture(
     occurredAt: message.occurredAt ?? message.createdAt,
   });
   if (stream === "responses" && result.created) {
-    stampReportUpLifecycleSignal(parentAgentId, child);
+    return { ...result, lifecycleSignals: [childSignalKey(child.id), ...childTaskIds(child).map(id => taskSignalKey(id, LIFECYCLE_STATE_WORKING))]
+      .map(subjectKey => ({ recipient: parentAgentId, subjectKey })) };
   }
   return result;
 }

package/src/db/migrations.ts

@@ -1,3 +1,6 @@
+import { COMMAND_RETENTION_SCHEMA, ensureCommandRetentionReferenceIndexes } from "./command-retention";
+import { migrateCheckoutRefreshHeads } from "./checkout-refresh-schema";
+import { TOKEN_USAGE_RETENTION_SCHEMA } from "./token-usage-retention";
 import { PLAN_DISPATCH_SCHEMA_SQL } from "./plan-dispatch-schema";
 import { PLAN_IMPORT_SCHEMA_SQL } from "./plan-import-schema";
 import { ensureDurablePayloadSchema } from "./durable-payloads"; import { redactProviderConfigHistory } from "./provider-config-history"; import { retireMemoryStorage } from "./memory-retirement";
@@ -66,6 +69,7 @@ import { migrateTeamProjectSeats } from "./team-project.ts";
 import { ensureArtifactCreatorAgentColumn } from "./artifacts.ts";
 import { rewriteEmptyToolGroupsToAbsent } from "./tool-groups-empty-migration.ts";
 import { backfillProjectMemoryToolGroup } from "./project-memory-group-migration.ts";
+import { backfillPlanToolsIntoToolIncludes } from "./plan-tools-include-migration.ts";
 import { removeLegacyProfileProjectInstructions } from "./profile-legacy-project-instructions-migration.ts";
 import { migrateProfileHostSources } from "./profile-host-sources-migration.ts";
 import { migrateProfileProjectAcks } from "./profile-project-ack-migration.ts";
@@ -169,7 +173,15 @@ export function applyMigrations(): void {
     )
   `);
   getDb().run("CREATE INDEX IF NOT EXISTS idx_issue_refs_external ON issue_refs(provider, repo, external_key)");
-  getDb().run("CREATE INDEX IF NOT EXISTS idx_issue_refs_updated ON issue_refs(updated_at DESC)");
+  // #3799 — matches the listing ORDER BY exactly, so a list is a bounded index walk with no sort; supersedes (updated_at DESC).
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_issue_refs_listing ON issue_refs(updated_at DESC, created_at DESC, id DESC)");
+  getDb().run("DROP INDEX IF EXISTS idx_issue_refs_updated");
+  // #3799 — automation_runs list/scan indexes: status+created_at supersedes the plain status index, created_at serves the
+  // unfiltered listing, and the partial index holds exactly the open task-bound runs the reconcile pass walks.
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_automation_runs_status_created ON automation_runs(status, created_at)");
+  getDb().run("DROP INDEX IF EXISTS idx_automation_runs_status");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_automation_runs_created ON automation_runs(created_at DESC)");
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_automation_runs_open ON automation_runs(created_at) WHERE status IN ('scheduled', 'dispatching', 'waiting_agent', 'running') AND task_id IS NOT NULL");
   // #2520 — the GitHub close classification (completed|not_planned) cached beside the status so
   // plan-node terminal propagation can tell a completed close from a not-planned one. The guarded
   // ALTER converges databases created before the column existed with the CREATE above.
@@ -666,6 +678,7 @@ export function applyMigrations(): void {
   ensureIngestedMemoryIndex();
   rewriteEmptyToolGroupsToAbsent(); // #1963 N2 — persisted relay.tools.groups:[] meant ALL; honoring [] as NONE requires rewriting existing [] → absent first
   backfillProjectMemoryToolGroup(); // #2154 follow-up — stored/overridden profiles do not pick up the built-in `project-memory` group on their own
+  backfillPlanToolsIntoToolIncludes(); // #3812 — lean per-tool allowlists (coordinator) never gained relay_plan_start/import
   removeLegacyProfileProjectInstructions(); // #2133 — remove retired profile policy fields before profile override migration reads legacy rows
   backfillCustomProfileArtifacts(); // #3171 — Artifact is off by default now; keep the approved custom brainstorm exception
   migrateAgentProfileOverridesToV2(); // #1963 N10 — back up + migrate persisted override rows to the v2 matrix (D-T=off; G6/G7 leave-untouched-and-report; flag-gated rollback)
@@ -1733,6 +1746,10 @@ export function applyMigrations(): void {
   getDb().run(AGENT_EXIT_REPORT_SCHEMA);
   getDb().run(CONTEXT_RESET_SCHEMA); // #3398
   getDb().run(TASK_TOKEN_TOTALS_SCHEMA);
+  getDb().run(TOKEN_USAGE_RETENTION_SCHEMA);
+  getDb().run(COMMAND_RETENTION_SCHEMA);
+  migrateCheckoutRefreshHeads(getDb());
+  ensureCommandRetentionReferenceIndexes(getDb());
   getDb().run(SHIPPING_STATS_SCHEMA);
   getDb().run(CI_GATE_BACKFILL_SCHEMA); getDb().run(AGENT_GATE_RUNS_SCHEMA); ensureAgentGateCommandSchema(); repairRerunGateTimings(); ensureCiShaObservationsSchema();
   migrateOperatorActionsSchema();

package/src/db/notification-write-ops.ts

@@ -0,0 +1,19 @@
+import { sendMessageWithResultInternal } from "./messages";
+import { insertAgentNoticeSlot, type AgentNoticeSlot } from "./terminal-events";
+import type { SendMessageInput } from "../types";
+import type { WriterOpContext, WriterOpSpec } from "./write-ops";
+
+const send = (inputs: SendMessageInput[], now: number) => inputs.map(input => sendMessageWithResultInternal(input, false, {}, now));
+export const NOTIFICATION_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = Object.freeze({
+  "notifications.route": {
+    offLoop: true, idempotent: false,
+    fn: ({ inputs }: { inputs: SendMessageInput[] }, ctx: WriterOpContext) => send(inputs, ctx.now),
+  },
+  "notifications.agentNotice": {
+    offLoop: true, idempotent: false,
+    fn: ({ slot, inputs }: { slot: AgentNoticeSlot; inputs: SendMessageInput[] }, ctx: WriterOpContext) => {
+      const created = insertAgentNoticeSlot(slot, ctx.now);
+      return { created, results: created ? send(inputs, ctx.now) : [] };
+    },
+  },
+});

package/src/db/operator-answer-write.ts

@@ -0,0 +1,19 @@
+import { answerOpenOperatorDecision, getOperatorDecision, getWorkflowOperatorDecision, insertOperatorDecision, setOperatorDecisionAnswerMessage } from "./operator-decisions";
+import { sendMessageWithResultInternal } from "./messages";
+import type { SendMessageInput } from "../types";
+export interface OperatorAnswerWrite {
+  id: number;
+  answer: Parameters<typeof answerOpenOperatorDecision>[1];
+  message: SendMessageInput;
+}
+export function answerOperatorDecisionBody({ id, answer, message }: OperatorAnswerWrite) {
+  if (!answerOpenOperatorDecision(id, answer)) return null;
+  const result = sendMessageWithResultInternal(message, false, {}, answer.now);
+  setOperatorDecisionAnswerMessage(id, result.message.id);
+  return { decision: getOperatorDecision(id)!, result };
+}
+
+export function fileWorkflowDecisionBody(input: Parameters<typeof insertOperatorDecision>[0]) {
+  const existing = getWorkflowOperatorDecision(input.workflow!.effectId);
+  return existing ? { decision: existing, created: false } : { decision: insertOperatorDecision(input), created: true };
+}

package/src/db/orchestrators.ts

@@ -11,7 +11,7 @@ import {
   type RuntimeContracts,
 } from "../contracts";
 import { STALE_TTL_MS } from "../config";
-import { deleteAgent, heartbeat, upsertAgent, upsertAgentInternal, type UpsertAgentTxResult } from "./agents.ts";
+import { deleteAgentInternal, heartbeat, upsertAgent, upsertAgentInternal, type UpsertAgentTxResult } from "./agents.ts";
 import { evictPendingPresence } from "./presence-buffer.ts";
 import { getDb, writeTransaction } from "./connection.ts";
 import { fencedColumnSql, nextLifecycleSeq } from "./lifecycle-seq.ts";
@@ -386,11 +386,17 @@ export function reportOrchestratorRosterRow(id: string, agents: ManagedAgent[],
 }
 
 export function deleteOrchestrator(id: string): boolean {
+  const result = deleteOrchestratorRow(id, Date.now());
+  if (result.agentId) evictPendingPresence(result.agentId);
+  return result.deleted;
+}
+
+export function deleteOrchestratorRow(id: string, now: number): { deleted: boolean; agentId?: string } {
   const orch = getOrchestrator(id);
-  if (!orch) return false;
+  if (!orch) return { deleted: false };
   getDb().query("DELETE FROM orchestrators WHERE id = ?").run(id);
-  deleteAgent(orch.agentId);
-  return true;
+  deleteAgentInternal(orch.agentId, now);
+  return { deleted: true, agentId: orch.agentId };
 }
 
 export function hasStaleOrchestrator(cutoff: number): boolean {

package/src/db/pairs-async.ts

@@ -1,5 +1,6 @@
+import { randomUUID } from "node:crypto";
+import type { createPair, acceptPair, rejectPair, endPair, sendPairMessage, getPair, listPairs } from "./pairs";
 import { getGateway } from "./gateway";
-import type { getPair, listPairs } from "./pairs";
 
 export function getPairAsync(id: string): Promise<ReturnType<typeof getPair>> {
   return getGateway().write("pairs.getCurrent", { id }) as Promise<ReturnType<typeof getPair>>;
@@ -8,3 +9,23 @@ export function getPairAsync(id: string): Promise<ReturnType<typeof getPair>> {
 export function listPairsAsync(filter?: Parameters<typeof listPairs>[0]): Promise<ReturnType<typeof listPairs>> {
   return getGateway().write("pairs.listCurrent", filter) as unknown as Promise<ReturnType<typeof listPairs>>;
 }
+
+export function createPairAsync(...args: Parameters<typeof createPair>): Promise<ReturnType<typeof createPair>> {
+  return getGateway().write("pairs.createPair", args, { idempotencyKey: randomUUID() }) as unknown as Promise<ReturnType<typeof createPair>>;
+}
+
+export function acceptPairAsync(...args: Parameters<typeof acceptPair>): Promise<ReturnType<typeof acceptPair>> {
+  return getGateway().write("pairs.acceptPair", args, { idempotencyKey: randomUUID() }) as unknown as Promise<ReturnType<typeof acceptPair>>;
+}
+
+export function rejectPairAsync(...args: Parameters<typeof rejectPair>): Promise<ReturnType<typeof rejectPair>> {
+  return getGateway().write("pairs.rejectPair", args, { idempotencyKey: randomUUID() }) as unknown as Promise<ReturnType<typeof rejectPair>>;
+}
+
+export function endPairAsync(...args: Parameters<typeof endPair>): Promise<ReturnType<typeof endPair>> {
+  return getGateway().write("pairs.endPair", args, { idempotencyKey: randomUUID() }) as unknown as Promise<ReturnType<typeof endPair>>;
+}
+
+export function sendPairMessageAsync(...args: Parameters<typeof sendPairMessage>): Promise<ReturnType<typeof sendPairMessage>> {
+  return getGateway().write("pairs.sendPairMessage", args, { idempotencyKey: randomUUID() }) as unknown as Promise<ReturnType<typeof sendPairMessage>>;
+}

package/src/db/pairs-write-ops.ts

@@ -1,8 +1,13 @@
-import { getPair, listPairs } from "./pairs";
+import { createPair, acceptPair, rejectPair, endPair, sendPairMessage, getPair, listPairs } from "./pairs";
 import type { WriterOpSpec } from "./write-ops";
 
 // Pair reads settle expired requests before returning the current view.
 export const PAIRS_WRITE_OPS: Readonly<Record<string, WriterOpSpec>> = {
-  "pairs.getCurrent": { idempotent: true, offLoop: true, fn: (args: { id: string }) => getPair(args.id) },
-  "pairs.listCurrent": { idempotent: true, offLoop: true, fn: (args: Parameters<typeof listPairs>[0]) => listPairs(args) },
+  "pairs.getCurrent": { idempotent: true, offLoop: true, fn: (args: { id: string }, ctx) => getPair(args.id, ctx.now) },
+  "pairs.listCurrent": { idempotent: true, offLoop: true, fn: (args: Parameters<typeof listPairs>[0], ctx) => listPairs(args, ctx.now) },
+  "pairs.createPair": { offLoop: true, idempotent: false, fn: (a: Parameters<typeof createPair>, ctx) => createPair(a[0], a[1] ?? ctx.now) },
+  "pairs.acceptPair": { offLoop: true, idempotent: false, fn: (a: Parameters<typeof acceptPair>, ctx) => acceptPair(a[0], a[1], a[2] ?? ctx.now) },
+  "pairs.rejectPair": { offLoop: true, idempotent: false, fn: (a: Parameters<typeof rejectPair>, ctx) => rejectPair(a[0], a[1], a[2] ?? ctx.now) },
+  "pairs.endPair": { offLoop: true, idempotent: false, fn: (a: Parameters<typeof endPair>, ctx) => endPair(a[0], a[1], a[2] ?? ctx.now) },
+  "pairs.sendPairMessage": { offLoop: true, idempotent: false, fn: (a: Parameters<typeof sendPairMessage>, ctx) => sendPairMessage(a[0], a[1], a[2] ?? ctx.now) },
 };

package/src/db/pairs.ts

@@ -4,7 +4,7 @@ import { matchAgents } from "../agent-ref";
 import { getAgent, listAgents } from "./agents.ts";
 import { getDb } from "./connection.ts";
 import { rowToPair } from "./mappers.ts";
-import { sendMessage } from "./messages.ts";
+import { sendMessageWithResultInternal } from "./messages.ts";
 export { closeOpenPairsForAgent } from "./pair-maintenance.ts";
 import type {
   AgentCard,
@@ -26,8 +26,8 @@ function expirePendingPairs(now: number = Date.now()): void {
     .run(now, now, now);
 }
 
-function getOpenPairForAgent(agentId: string): PairSession | null {
-  expirePendingPairs();
+function getOpenPairForAgent(agentId: string, now: number = Date.now()): PairSession | null {
+  expirePendingPairs(now);
   const row = getDb().query(`
     SELECT * FROM pairs
     WHERE status IN ('pending', 'active') AND (requester_id = ? OR target_id = ?)
@@ -45,7 +45,7 @@ function pairPeer(pair: PairSession, agentId: string): string {
   return pair.requesterId === agentId ? pair.targetId : pair.requesterId;
 }
 
-function resolvePairTarget(target: string, requesterId: string): {
+function resolvePairTarget(target: string, requesterId: string, now: number = Date.now()): {
   ok: true;
   agent: AgentCard;
 } | {
@@ -64,7 +64,7 @@ function resolvePairTarget(target: string, requesterId: string): {
   const busy: Array<{ agent: AgentCard; pair: PairSession }> = [];
   const available: AgentCard[] = [];
   for (const agent of live) {
-    const openPair = getOpenPairForAgent(agent.id);
+    const openPair = getOpenPairForAgent(agent.id, now);
     if (openPair) busy.push({ agent, pair: openPair });
     else available.push(agent);
   }
@@ -81,8 +81,8 @@ function resolvePairTarget(target: string, requesterId: string): {
   return { ok: true, agent: available[0]! };
 }
 
-function pairSystemMessage(pair: PairSession, to: string, event: string, subject: string, body: string): Message {
-  return sendMessage({
+function pairSystemMessage(pair: PairSession, to: string, event: string, subject: string, body: string, now: number = Date.now()): Message {
+  return sendMessageWithResultInternal({
     from: "system",
     to,
     kind: "pair",
@@ -95,17 +95,17 @@ function pairSystemMessage(pair: PairSession, to: string, event: string, subject
       targetId: pair.targetId,
       pairStatus: pair.status,
     },
-  });
+  }, false, {}, now).message;
 }
 
-export function getPair(id: string): PairSession | null {
-  expirePendingPairs();
+export function getPair(id: string, now: number = Date.now()): PairSession | null {
+  expirePendingPairs(now);
   const row = getDb().query("SELECT * FROM pairs WHERE id = ?").get(id) as any;
   return row ? rowToPair(row) : null;
 }
 
-export function listPairs(filter?: { agentId?: string; status?: PairStatus }): PairSession[] {
-  expirePendingPairs();
+export function listPairs(filter?: { agentId?: string; status?: PairStatus }, now: number = Date.now()): PairSession[] {
+  expirePendingPairs(now);
   const conditions: string[] = [];
   const params: any[] = [];
   if (filter?.agentId) {
@@ -120,7 +120,7 @@ export function listPairs(filter?: { agentId?: string; status?: PairStatus }): P
   return (getDb().query(`SELECT * FROM pairs ${where} ORDER BY updated_at DESC LIMIT 100`).all(...params) as any[]).map(rowToPair);
 }
 
-export function createPair(input: CreatePairInput): {
+export function createPair(input: CreatePairInput, now: number = Date.now()): {
   ok: true;
   pair: PairSession;
   invite: Message;
@@ -131,25 +131,23 @@ export function createPair(input: CreatePairInput): {
   matches?: AgentCard[];
   busy?: Array<{ agent: AgentCard; pair: PairSession }>;
 } {
-  expirePendingPairs();
+  expirePendingPairs(now);
   const requester = getAgent(input.from);
   if (!requester) return { ok: false, code: "invalid", error: `requester agent ${input.from} not registered` };
   if (requester.status === "offline" || !requester.ready) return { ok: false, code: "offline", error: `requester agent ${input.from} is not online and ready` };
-  const requesterPair = getOpenPairForAgent(input.from);
+  const requesterPair = getOpenPairForAgent(input.from, now);
   if (requesterPair) return { ok: false, code: "busy", error: `requester is already paired`, busy: [{ agent: requester, pair: requesterPair }] };
 
-  const resolved = resolvePairTarget(input.target, input.from);
+  const resolved = resolvePairTarget(input.target, input.from, now);
   if (!resolved.ok) return resolved;
   if (resolved.agent.id === input.from) return { ok: false, code: "invalid", error: "cannot pair with yourself" };
-
-  const now = Date.now();
   const ttlMs = Math.min(Math.max(input.ttlMs ?? DEFAULT_PAIR_TTL_MS, 10_000), MAX_PAIR_TTL_MS);
   const id = randomUUID();
   getDb().query(`
     INSERT INTO pairs (id, requester_id, target_id, status, objective, meta, created_at, updated_at, expires_at)
     VALUES (?, ?, ?, 'pending', ?, ?, ?, ?, ?)
   `).run(id, input.from, resolved.agent.id, input.objective ?? null, JSON.stringify(input.meta ?? {}), now, now, now + ttlMs);
-  const pair = getPair(id)!;
+  const pair = getPair(id, now)!;
   const objective = pair.objective ? `\n\nObjective:\n${pair.objective}` : "";
   const invite = pairSystemMessage(
     pair,
@@ -163,14 +161,14 @@ export function createPair(input: CreatePairInput): {
       "Accept with POST /api/pairs/{id}/accept using your agentId.",
       "Reject with POST /api/pairs/{id}/reject using your agentId.",
       "Pairing is exclusive: each agent can be in at most one pending or active pair.",
-    ].join("\n"),
+    ].join("\n"), now
   );
   return { ok: true, pair, invite };
 }
 
-export function acceptPair(id: string, input: PairActionInput): { ok: true; pair: PairSession; notices: Message[] } | { ok: false; error: string; code: "not_found" | "forbidden" | "busy" | "invalid" } {
-  expirePendingPairs();
-  const pair = getPair(id);
+export function acceptPair(id: string, input: PairActionInput, now: number = Date.now()): { ok: true; pair: PairSession; notices: Message[] } | { ok: false; error: string; code: "not_found" | "forbidden" | "busy" | "invalid" } {
+  expirePendingPairs(now);
+  const pair = getPair(id, now);
   if (!pair) return { ok: false, code: "not_found", error: "pair not found" };
   if (pair.status !== "pending") return { ok: false, code: "invalid", error: `pair is ${pair.status}` };
   if (pair.targetId !== input.agentId) return { ok: false, code: "forbidden", error: "only the target agent can accept this pair" };
@@ -180,61 +178,56 @@ export function acceptPair(id: string, input: PairActionInput): { ok: true; pair
   if (!requester || requester.status === "offline" || !requester.ready) return { ok: false, code: "invalid", error: "requester agent is no longer online and ready" };
 
   for (const agentId of [pair.requesterId, pair.targetId]) {
-    const open = getOpenPairForAgent(agentId);
+    const open = getOpenPairForAgent(agentId, now);
     if (open && open.id !== pair.id) return { ok: false, code: "busy", error: `${agentId} is already paired` };
   }
-
-  const now = Date.now();
   getDb().query("UPDATE pairs SET status = 'active', accepted_at = ?, updated_at = ? WHERE id = ? AND status = 'pending'")
     .run(now, now, id);
-  const active = getPair(id)!;
+  const active = getPair(id, now)!;
   const notices = [
-    pairSystemMessage(active, active.requesterId, "accepted", `Pair accepted by ${active.targetId}`, `Pair ${active.id} is active. Send pair messages with POST /api/pairs/${active.id}/messages.`),
-    pairSystemMessage(active, active.targetId, "accepted", `Pair active with ${active.requesterId}`, `Pair ${active.id} is active. Send pair messages with POST /api/pairs/${active.id}/messages.`),
+    pairSystemMessage(active, active.requesterId, "accepted", `Pair accepted by ${active.targetId}`, `Pair ${active.id} is active. Send pair messages with POST /api/pairs/${active.id}/messages.`, now),
+    pairSystemMessage(active, active.targetId, "accepted", `Pair active with ${active.requesterId}`, `Pair ${active.id} is active. Send pair messages with POST /api/pairs/${active.id}/messages.`, now),
   ];
   return { ok: true, pair: active, notices };
 }
 
-export function rejectPair(id: string, input: PairActionInput): { ok: true; pair: PairSession; notice: Message } | { ok: false; error: string; code: "not_found" | "forbidden" | "invalid" } {
-  expirePendingPairs();
-  const pair = getPair(id);
+export function rejectPair(id: string, input: PairActionInput, now: number = Date.now()): { ok: true; pair: PairSession; notice: Message } | { ok: false; error: string; code: "not_found" | "forbidden" | "invalid" } {
+  expirePendingPairs(now);
+  const pair = getPair(id, now);
   if (!pair) return { ok: false, code: "not_found", error: "pair not found" };
   if (pair.status !== "pending") return { ok: false, code: "invalid", error: `pair is ${pair.status}` };
   if (pair.targetId !== input.agentId) return { ok: false, code: "forbidden", error: "only the target agent can reject this pair" };
-  const now = Date.now();
   getDb().query("UPDATE pairs SET status = 'rejected', ended_at = ?, ended_by = ?, updated_at = ? WHERE id = ?")
     .run(now, input.agentId, now, id);
-  const rejected = getPair(id)!;
+  const rejected = getPair(id, now)!;
   const reason = input.reason ? `\n\nReason:\n${input.reason}` : "";
-  const notice = pairSystemMessage(rejected, rejected.requesterId, "rejected", `Pair rejected by ${input.agentId}`, `Pair ${rejected.id} was rejected.${reason}`);
+  const notice = pairSystemMessage(rejected, rejected.requesterId, "rejected", `Pair rejected by ${input.agentId}`, `Pair ${rejected.id} was rejected.${reason}`, now);
   return { ok: true, pair: rejected, notice };
 }
 
-export function endPair(id: string, input: PairActionInput): { ok: true; pair: PairSession; notice?: Message } | { ok: false; error: string; code: "not_found" | "forbidden" | "invalid" } {
-  expirePendingPairs();
-  const pair = getPair(id);
+export function endPair(id: string, input: PairActionInput, now: number = Date.now()): { ok: true; pair: PairSession; notice?: Message } | { ok: false; error: string; code: "not_found" | "forbidden" | "invalid" } {
+  expirePendingPairs(now);
+  const pair = getPair(id, now);
   if (!pair) return { ok: false, code: "not_found", error: "pair not found" };
   if (!pairParticipant(pair, input.agentId)) return { ok: false, code: "forbidden", error: "only pair participants can hang up" };
   if (!OPEN_PAIR_STATUSES.includes(pair.status as any)) return { ok: false, code: "invalid", error: `pair is ${pair.status}` };
-  const now = Date.now();
   getDb().query("UPDATE pairs SET status = 'ended', ended_at = ?, ended_by = ?, updated_at = ? WHERE id = ?")
     .run(now, input.agentId, now, id);
-  const ended = getPair(id)!;
+  const ended = getPair(id, now)!;
   const reason = input.reason ? `\n\nReason:\n${input.reason}` : "";
   const peer = pairPeer(ended, input.agentId);
-  const notice = pairSystemMessage(ended, peer, "ended", `Pair ended by ${input.agentId}`, `Pair ${ended.id} ended.${reason}`);
+  const notice = pairSystemMessage(ended, peer, "ended", `Pair ended by ${input.agentId}`, `Pair ${ended.id} ended.${reason}`, now);
   return { ok: true, pair: ended, notice };
 }
 
-export function sendPairMessage(id: string, input: PairMessageInput): { ok: true; pair: PairSession; message: Message } | { ok: false; error: string; code: "not_found" | "forbidden" | "invalid" } {
-  expirePendingPairs();
-  const pair = getPair(id);
+export function sendPairMessage(id: string, input: PairMessageInput, now: number = Date.now()): { ok: true; pair: PairSession; message: Message } | { ok: false; error: string; code: "not_found" | "forbidden" | "invalid" } {
+  expirePendingPairs(now);
+  const pair = getPair(id, now);
   if (!pair) return { ok: false, code: "not_found", error: "pair not found" };
   if (pair.status !== "active") return { ok: false, code: "invalid", error: `pair is ${pair.status}` };
   if (!pairParticipant(pair, input.from)) return { ok: false, code: "forbidden", error: "only pair participants can send pair messages" };
   const to = pairPeer(pair, input.from);
-  const now = Date.now();
-  const message = sendMessage({
+  const message = sendMessageWithResultInternal({
     from: input.from,
     to,
     kind: "pair",
@@ -246,7 +239,7 @@ export function sendPairMessage(id: string, input: PairMessageInput): { ok: true
       requesterId: pair.requesterId,
       targetId: pair.targetId,
     },
-  });
+  }, false, {}, now).message;
   getDb().query("UPDATE pairs SET last_message_at = ?, updated_at = ? WHERE id = ?").run(now, now, id);
-  return { ok: true, pair: getPair(id)!, message };
+  return { ok: true, pair: getPair(id, now)!, message };
 }

package/src/db/plan-dispatch-schema.ts

@@ -1,4 +1,4 @@
-// #3660 — plan autopilot tables (see plan-dispatch-store.ts); dependency-free so the startup catalog can include it.
+// #3660 — plan autopilot tables (see plan-dispatch-store.ts) and ready-node notice state (plan-ready-notices.ts); dependency-free so the startup catalog can include it.
 export const PLAN_DISPATCH_SCHEMA_SQL = `
   CREATE TABLE IF NOT EXISTS task_executions (task_id INTEGER PRIMARY KEY, execution TEXT NOT NULL, updated_at INTEGER NOT NULL);
   CREATE TABLE IF NOT EXISTS plan_dispatch (
@@ -14,4 +14,8 @@ export const PLAN_DISPATCH_SCHEMA_SQL = `
   CREATE TABLE IF NOT EXISTS plan_ci_blocks (
     run_id TEXT PRIMARY KEY, plan_id TEXT NOT NULL, task_id INTEGER NOT NULL, sha TEXT NOT NULL,
     incident_ids TEXT NOT NULL, wait_key TEXT NOT NULL, retry_note TEXT NOT NULL, retried_at INTEGER
+  );
+  CREATE TABLE IF NOT EXISTS plan_ready_notices (
+    plan_id TEXT NOT NULL, node_id TEXT NOT NULL, ready_since INTEGER NOT NULL, notified_at INTEGER,
+    PRIMARY KEY (plan_id, node_id)
   )`;

package/src/db/plan-ready-notices.ts

@@ -0,0 +1,43 @@
+// #3660 — durable "ready since / already told" state per plan node, so a hub restart neither
+// loses the unstarted-ready clock nor repeats a notice. A row exists exactly while the node is
+// ready-and-unstarted; leaving ready deletes it, so re-entering ready starts a fresh clock.
+import { getDb } from "./connection.ts";
+
+export interface ReadyPlanScan { planId: string; nodeIds: string[] }
+export interface DueReadyNodes { planId: string; nodes: Array<{ nodeId: string; readySince: number }> }
+
+/** Reconcile every scanned plan's ready set; plans absent from `scans` (archived, done, deleted,
+ * coordinator-less) lose their rows. Returns the nodes ready for >= `dueMs` and not yet notified. */
+export function syncPlanReadyNotices(args: { scans: ReadyPlanScan[]; now: number; dueMs: number }): DueReadyNodes[] {
+  const db = getDb();
+  const scanned = new Set(args.scans.map(scan => scan.planId));
+  for (const { plan_id } of db.query("SELECT DISTINCT plan_id FROM plan_ready_notices").all() as Array<{ plan_id: string }>) {
+    if (!scanned.has(plan_id)) db.query("DELETE FROM plan_ready_notices WHERE plan_id = ?").run(plan_id);
+  }
+  const due: DueReadyNodes[] = [];
+  for (const scan of args.scans) {
+    const keep = new Set(scan.nodeIds);
+    const rows = db.query("SELECT node_id, ready_since, notified_at FROM plan_ready_notices WHERE plan_id = ?").all(scan.planId) as
+      Array<{ node_id: string; ready_since: number; notified_at: number | null }>;
+    const nodes: DueReadyNodes["nodes"] = [];
+    const known = new Set<string>();
+    for (const row of rows) {
+      if (!keep.has(row.node_id)) { db.query("DELETE FROM plan_ready_notices WHERE plan_id = ? AND node_id = ?").run(scan.planId, row.node_id); continue; }
+      known.add(row.node_id);
+      if (row.notified_at === null && row.ready_since <= args.now - args.dueMs) nodes.push({ nodeId: row.node_id, readySince: row.ready_since });
+    }
+    for (const nodeId of keep) if (!known.has(nodeId)) db.query("INSERT INTO plan_ready_notices(plan_id, node_id, ready_since) VALUES(?, ?, ?)").run(scan.planId, nodeId, args.now);
+    if (nodes.length) due.push({ planId: scan.planId, nodes });
+  }
+  return due;
+}
+
+export function markPlanReadyNoticed(args: { planId: string; nodeIds: string[]; now: number }): void {
+  const stmt = getDb().query("UPDATE plan_ready_notices SET notified_at = ? WHERE plan_id = ? AND node_id = ? AND notified_at IS NULL");
+  for (const nodeId of args.nodeIds) stmt.run(args.now, args.planId, nodeId);
+}
+
+export const PLAN_READY_NOTICE_WRITE_OPS = {
+  "plans.readyNotices.sync": { offLoop: true, idempotent: true, fn: syncPlanReadyNotices },
+  "plans.readyNotices.mark": { offLoop: true, idempotent: true, fn: markPlanReadyNoticed },
+};

package/src/db/plan-tools-include-migration.ts

@@ -0,0 +1,36 @@
+// #3812 — backfill relay_plan_start/import into stored per-tool allowlists (the lean coordinator
+// from #3472 froze before they existed, so tools/list never carried them).
+// Narrow: only an include list already holding relay_plan_get, and not excluding the tool.
+// json_insert, not parse+reserialize (#1456); patches `$.relay.tools` and its `sources` mirror, and
+// the -v1-backup namespace, whose bytes are served while the matrix flag is off.
+import { getDb } from "./connection.ts";
+import { runMigrationOnce } from "./migration-marker.ts";
+
+const PROFILE_NAMESPACES = ["agent-profile", "agent-profile-override", "agent-profile-override-v1-backup"] as const;
+const SELECTION_PATHS = ["$.relay.tools", "$.sources.agentRelay.mcp"] as const;
+const BACKFILLED_TOOLS = ["relay_plan_start", "relay_plan_import"] as const;
+const EVIDENCE_TOOL = "relay_plan_get";
+
+export function backfillPlanToolsIntoToolIncludes(): void {
+  runMigrationOnce("plan-tools-include-backfill-v1", () => {
+    const db = getDb();
+    const namespaces = PROFILE_NAMESPACES.map(() => "?").join(", ");
+    // The outer table is aliased: inside the subqueries a bare `value` binds to json_each.value.
+    const holds = (path: string, field: "include" | "exclude", tool: string) =>
+      `EXISTS (SELECT 1 FROM json_each(c.value, '${path}.${field}') je WHERE je.value = '${tool}')`;
+    db.transaction(() => {
+      for (const path of SELECTION_PATHS) {
+        for (const tool of BACKFILLED_TOOLS) {
+          db.query(
+            `UPDATE config AS c SET value = json_insert(c.value, '${path}.include[#]', ?)
+             WHERE c.namespace IN (${namespaces}) AND json_valid(c.value)
+               AND json_type(c.value, '${path}.include') = 'array'
+               AND ${holds(path, "include", EVIDENCE_TOOL)}
+               AND NOT ${holds(path, "include", tool)}
+               AND NOT ${holds(path, "exclude", tool)}`,
+          ).run(tool, ...PROFILE_NAMESPACES);
+        }
+      }
+    })();
+  });
+}