@humwick/server 0.130.1 → 0.130.3

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";
@@ -21,7 +24,6 @@ import { backfillLegacyMessages } from "./legacy-message-backfill";
 import { installHistoryDeliverySettlement } from "./history-delivery-settle";
 import { installReplyObligations } from "./reply-obligations";
 import { beginStartupPhase, timeStartupPhase } from "../startup-timing";
-import { Database } from "bun:sqlite";
 import { AGENT_EXIT_REPORT_SCHEMA } from "./agent-exit-report";
 import { CONTEXT_RESET_SCHEMA } from "./context-reset-carry";
 import { TASK_TOKEN_TOTALS_SCHEMA } from "./token-usage";
@@ -30,20 +32,8 @@ import { migrateOperatorActionsSchema } from "./operator-actions-schema";
 import { SELF_EFFORT_PERMISSIONS_SCHEMA } from "./self-effort-permissions";
 import { AGENT_EFFORT_STATE_SCHEMA, importLegacyEffortCommands } from "./agent-effort-state";
 import { randomUUID } from "node:crypto";
-import { isRecord, stringValue, isMechanicalMessageKind } from "@humwick/sdk";
-import { ORCHESTRATOR_PROTOCOL_VERSION, VERSION } from "../config.ts";
-import { parseJson } from "../utils";
-import { isLiveIsolatedWorkspace } from "../workspace-phase";
-import {
-  CONTRACT_REQUIREMENTS,
-  contractCompatibility,
-  parseRuntimeCapabilities,
-  parseRuntimeContracts,
-  parseRuntimePackage,
-  type RuntimeContracts,
-} 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 { PROJECT_PROFILE_INSTRUCTIONS_SCHEMA_SQL } from "./project-profile-instructions";
+import { CLAIM_LEASE_MS } from "../config";
 import { COORDINATOR_PROFILE_NAMES } from "../agent-system-tags";
 import { getDb } from "./connection.ts";
 import { normalizeExistingAgentSpawnRequestIds } from "./spawn-request-id-migration.ts";
@@ -79,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";
@@ -154,6 +145,7 @@ function backfillProjectRootRemoteUrls(): void {
 // shape, so they must run in historical order. Built-in agent seeding and the
 // read_by backfill live here too — both run unconditionally and idempotently.
 export function applyMigrations(): void {
+  getDb().run(PROJECT_PROFILE_INSTRUCTIONS_SCHEMA_SQL);
   getDb().run(PLAN_IMPORT_SCHEMA_SQL);
   ensureVaultTokensSchema();
   ensureVaultHealthSchema();
@@ -181,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.
@@ -678,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)
@@ -1281,6 +1282,7 @@ export function applyMigrations(): void {
   // addTaskCol guard as the rest of the #834 batch: existing rows read back as absent.
   addTaskCol("tags", "tags TEXT");
   addTaskCol("priority", "priority TEXT");
+  addTaskCol("paths", "paths TEXT"); // #3736
   // #1535 WS1 — parent/epic tree edge. Self-referential FK via ALTER TABLE ADD COLUMN is
   // proven safe in this codebase already (messages.reply_to above); cycle-guarding lives
   // in application code (task-entity.ts), not a DB constraint.
@@ -1294,10 +1296,13 @@ export function applyMigrations(): void {
   addTaskCol("review_hold", "review_hold INTEGER NOT NULL DEFAULT 0 CHECK (review_hold IN (0, 1))");
   addTaskCol("validation_items", "validation_items TEXT");
   addTaskCol("terminal_stage", "terminal_stage TEXT");
+  addTaskCol("on_deploy", "on_deploy TEXT");
   addTaskCol("completed_at", "completed_at INTEGER");
   addTaskCol("owner", "owner TEXT"); // #2862 — backfilled by backfillTaskOwners below
   migratePlanBlurbsOnStartup(); // #2082 S5 — fold legacy bound-node blurbs before stripping them
   getDb().run("CREATE INDEX IF NOT EXISTS idx_tasks_message_status ON tasks(message_id, status) WHERE message_id IS NOT NULL");
+  // #3740: existing databases need the same covering expression index as fresh schemas.
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_tasks_integration_stats ON tasks(coalesce(json_extract(metadata, '$.relayIntegrationName'), source), status, claimed_by, last_seen_at, updated_at, source)");
   getDb().run("CREATE INDEX IF NOT EXISTS idx_tasks_kind ON tasks(kind, status, updated_at)");
   getDb().run("CREATE INDEX IF NOT EXISTS idx_tasks_branch ON tasks(branch) WHERE branch IS NOT NULL");
   getDb().run("CREATE INDEX IF NOT EXISTS idx_tasks_team ON tasks(team_id) WHERE team_id IS NOT NULL");
@@ -1741,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

@@ -1,9 +1,7 @@
 import { isDeepStrictEqual } from "node:util";
-import { randomUUID } from "node:crypto";
-import { isRecord, stringValue, isMechanicalMessageKind, orchestratorAgentId } from "@humwick/sdk";
-import { ORCHESTRATOR_PROTOCOL_VERSION, VERSION } from "../config.ts";
+import { stringValue, orchestratorAgentId } from "@humwick/sdk";
+import { VERSION } from "../config.ts";
 import { parseJson } from "../utils";
-import { isLiveIsolatedWorkspace } from "../workspace-phase";
 import {
   CONTRACT_REQUIREMENTS,
   contractCompatibility,
@@ -12,77 +10,13 @@ import {
   parseRuntimePackage,
   type RuntimeContracts,
 } 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 { deleteAgent, heartbeat, upsertAgent, upsertAgentInternal, type UpsertAgentTxResult } from "./agents.ts";
+import { STALE_TTL_MS } from "../config";
+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";
 import { electWorkspaceStewards, emitWorkspaceUpsert, getWorkspace, upsertWorkspaceFromManagedAgentRow, type WorkspaceUpsertResult } from "./workspaces.ts";
-import type {
-  AgentCard,
-  ActivityEvent,
-  ActivityEventInput,
-  AgentKind,
-  AgentSessionGuard,
-  Artifact,
-  ArtifactBlob,
-  ArtifactKind,
-  ArtifactLink,
-  ArtifactSensitivity,
-  ArtifactVisibility,
-  AttachmentRef,
-  ChannelBinding,
-  ChannelBindingMode,
-  ChannelRouteTarget,
-  ChatHistoryImport,
-  ChatHistoryImportEntry,
-  ChannelSummary,
-  ChannelTargetHealth,
-  CreatePairInput,
-  HealthCheck,
-  HealthReport,
-  ManagedAgent,
-  ManagedSessionExitDiagnostics,
-  Message,
-  MessageDeliveryAttempt,
-  MessageDeliveryStatus,
-  HostDaemonSample,
-  Orchestrator,
-  OrchestratorHealth,
-  OrchestratorRuntimeInput,
-  OrchestratorStatus,
-  OrchestratorUpgradeState,
-  PairActionInput,
-  PairMessageInput,
-  PairSession,
-  PairStatus,
-  RegisterAgentInput,
-  ReplyObligation,
-  RegisterOrchestratorInput,
-  SendMessageInput,
-  PollQuery,
-  SpawnApprovalMode,
-  SpawnProvider,
-  Task,
-  TaskEvent,
-  TaskSeverity,
-  TaskStatus,
-  IntegrationEventInput,
-  IntegrationSummary,
-  IntegrationTaskStats,
-  InboxDraft,
-  InboxState,
-  InboxThreadState,
-  ContextSnapshot,
-  ContextState,
-  ProviderCapabilities,
-  QueuedSpawn,
-  TaskStatusInput,
-  WorkspaceMetadata,
-  WorkspaceRecord,
-  WorkspaceStatus,
-} from "../types";
+import type { ManagedAgent, HostDaemonSample, Orchestrator, OrchestratorHealth, OrchestratorRuntimeInput, OrchestratorStatus, OrchestratorUpgradeState, RegisterAgentInput, RegisterOrchestratorInput, SpawnProvider, QueuedSpawn } from "../types";
 
 // --- Orchestrators ---
 
@@ -185,7 +119,6 @@ export function setOrchestratorUpgradeState(id: string, state: OrchestratorUpgra
   return getOrchestrator(id);
 }
 
-
 function orchestratorHealth(version: string | undefined, compatibility: ReturnType<typeof contractCompatibility>): OrchestratorHealth {
   const issues: OrchestratorHealth["issues"] = [];
   if (!version) {
@@ -452,13 +385,18 @@ export function reportOrchestratorRosterRow(id: string, agents: ManagedAgent[],
   return { orchestrator: getOrchestrator(id), rosterChanged: true, workspaces };
 }
 
-
 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

@@ -1,22 +1,10 @@
 import { randomUUID } from "node:crypto";
-import { isRecord, stringValue, isMechanicalMessageKind } from "@humwick/sdk";
-import { ORCHESTRATOR_PROTOCOL_VERSION, VERSION } from "../config.ts";
-import { parseJson } from "../utils";
-import { isLiveIsolatedWorkspace } from "../workspace-phase";
-import {
-  CONTRACT_REQUIREMENTS,
-  contractCompatibility,
-  parseRuntimeCapabilities,
-  parseRuntimeContracts,
-  parseRuntimePackage,
-  type RuntimeContracts,
-} from "../contracts";
-import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_MERGE_LEASE_MS } from "../config";
+import { DAY_MS } from "../config";
 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,
@@ -38,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 = ?)
@@ -57,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;
 } | {
@@ -76,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);
   }
@@ -93,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",
@@ -107,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) {
@@ -132,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;
@@ -143,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,
@@ -175,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" };
@@ -192,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",
@@ -258,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 },
+};