agent-relay-server 0.59.0 → 0.60.1

package/src/branch-landed.ts

@@ -1,9 +1,16 @@
 import { emitRelayEvent } from "./events";
 import { getNotificationsConfig } from "./config-store";
-import { notifySystemMessage } from "./notify";
-import { createActivityEvent, listAgents, updateWorkspaceStatus } from "./db";
-import { isAgentOnline } from "./agent-ref";
-import type { AgentCard, WorkspaceMergePreview, WorkspaceRecord } from "./types";
+import { routeNotification, INFORMATIONAL_TTL_MS } from "./notification-router";
+import { registerDefaultAudienceRules, resolveAudience, audiencePredicates } from "./notification-rules";
+import { createActivityEvent, getAgent, updateWorkspaceStatus } from "./db";
+import type { WorkspaceMergePreview, WorkspaceRecord } from "./types";
+
+// #444 — branch.landed is the first rule-driven type: the on-main "merged" fan-out audience comes
+// from the #442 engine, not a hand-rolled agentsOnMain scan. onRepoRoot delivers online agents in
+// the main checkout (author excluded — they get the direct store-ahead copy below); differentTeam
+// then scopes the fan-out to the land's team, so a Team-A land no longer wakes Team-B agents sharing
+// the main checkout (epic #440's dogfooded symptom). A teamless author/agent keeps prior reach.
+registerDefaultAudienceRules("branch.landed", [audiencePredicates.onRepoRoot(), audiencePredicates.differentTeam()]);
 
 export interface BranchLandedInput {
   /**
@@ -88,27 +95,44 @@ export function notifyBranchLanded(input: BranchLandedInput): void {
     const continueLabel = input.newBranch
       ? ` You're now on \`${input.newBranch}\` — keep working there.`
       : " Worktree reclaimed.";
-    notifySystemMessage(author, {
-      subject: "Your branch landed",
-      body: `✅ ${branchLabel} landed on \`${base}\`${shaLabel}${subjectLabel}.${publishLabel}${continueLabel}`,
-      payload,
-      replyExpected: false,
+    // Durable (ttl null): the author's own branch landing must reach them even after they go
+    // offline (store-ahead #234) — not a bystander notice that goes stale.
+    routeNotification({
+      type: "branch.landed",
+      scope: { author, repoRoot: workspace.repoRoot, workspaceId: workspace.id },
+      recipients: [author],
+      ttlMs: null,
+      message: {
+        subject: "Your branch landed",
+        body: `✅ ${branchLabel} landed on \`${base}\`${shaLabel}${subjectLabel}.${publishLabel}${continueLabel}`,
+        payload,
+        replyExpected: false,
+      },
     });
   }
 
-  // Agents on `main` — those whose cwd IS the main checkout (not an isolated worktree) —
-  // get a live "merged" notice so a long-lived main agent's context stays current as work
-  // lands under it (#239). Online-only: a stale/exited main session needs no wake, and
-  // store-ahead to it would just pile up noise. The author is in a worktree (cwd ≠ repoRoot)
-  // so it's naturally excluded; guard anyway for shared-mode owners.
-  const branchLabel = landedBranch ? `\`${landedBranch}\`` : "A branch";
-  const authorLabel = author ? ` by \`${author}\`` : "";
-  for (const agent of agentsOnMain(workspace.repoRoot, author)) {
-    notifySystemMessage(agent.id, {
-      subject: `Merged to ${base}`,
-      body: `🔀 ${branchLabel}${authorLabel} merged to \`${base}\`${shaLabel}${subjectLabel}.${publishLabel}`,
-      payload,
-      replyExpected: false,
+  // On-main "merged" fan-out — a live notice so a long-lived main agent's context stays current as
+  // work lands under it (#239). Recipients now come from the #442 rule engine (registered above):
+  // online agents whose cwd is the main checkout, author-excluded, team-scoped. Empty for a solo
+  // land with no other main agents → no-op.
+  const mainScope = { author, repoRoot: workspace.repoRoot, workspaceId: workspace.id, teamId: author ? getAgent(author)?.teamId : undefined };
+  const mainRecipients = resolveAudience("branch.landed", mainScope).map((member) => member.agentId);
+  if (mainRecipients.length > 0) {
+    const branchLabel = landedBranch ? `\`${landedBranch}\`` : "A branch";
+    const authorLabel = author ? ` by \`${author}\`` : "";
+    // Bystander fan-out (ttl informational): a "merged" notice is only useful while fresh — a
+    // late-joining main agent shouldn't be woken by an hours-old land.
+    routeNotification({
+      type: "branch.landed",
+      scope: mainScope,
+      recipients: mainRecipients,
+      ttlMs: INFORMATIONAL_TTL_MS,
+      message: {
+        subject: `Merged to ${base}`,
+        body: `🔀 ${branchLabel}${authorLabel} merged to \`${base}\`${shaLabel}${subjectLabel}.${publishLabel}`,
+        payload,
+        replyExpected: false,
+      },
     });
   }
 }
@@ -148,16 +172,3 @@ export function reconcileLandedWorkspace(ws: WorkspaceRecord, preview: Workspace
     // Notification is best-effort; the merged status + activity event still stand.
   }
 }
-
-// An agent is "on `main`" when its registered cwd equals the repo's main checkout — i.e. it
-// works in the base, not an isolated worktree. Excludes the author, pseudo agents (system/
-// user), channels, and offline sessions.
-function agentsOnMain(repoRoot: string, author: string | undefined): AgentCard[] {
-  return listAgents().filter((a) => {
-    if (a.id === author || a.id === "system" || a.id === "user") return false;
-    if (a.kind === "channel" || a.meta?.kind === "channel") return false;
-    const cwd = a.meta?.cwd;
-    if (typeof cwd !== "string" || cwd !== repoRoot) return false;
-    return isAgentOnline(a);
-  });
-}

package/src/channel-target.ts

@@ -23,3 +23,13 @@ export function parseChannelRouteTarget(target: string): ChannelRouteTarget {
   if (target.startsWith("orchestrator:")) return { type: "orchestrator", id: target.slice("orchestrator:".length) };
   return { type: "agent", id: target };
 }
+
+// A fan-out target addresses MANY agents (broadcast / tag / cap / label / team / pool) rather than
+// one. #451 uses this to scope the default message TTL: a stale fan-out message must not wake a
+// late-joining agent, whereas a direct DM (and `policy:`, which resolves to one running agent or
+// queues with its own expiry) is store-ahead and never auto-expires. Built on the one parser above
+// so the prefix set can't drift from route resolution.
+export function isFanoutTarget(target: string): boolean {
+  const { type } = parseChannelRouteTarget(target);
+  return type === "broadcast" || type === "tag" || type === "capability" || type === "label" || type === "team" || type === "pool";
+}

package/src/cli/index.ts

@@ -14,6 +14,7 @@ import { handleDevCommand } from "./dev";
 import { handleMemoryCommand } from "./memory";
 import { handleSlashOrPairCommand } from "./pair";
 import { handleWorkspaceCommand } from "./workspace";
+import { handleMergesCommand } from "./merges";
 import { handleStewardCommand } from "./steward";
 import { handleMessageCommand, handleGetMessageCommand, handleReactCommand } from "./message";
 import { handleReplyCommand } from "./reply";
@@ -44,6 +45,7 @@ Usage:
   agent-relay context-probe [print-status-line] [--wrap COMMAND] [--agent-id ID] [--state-dir DIR] [--standalone]
   agent-relay token <create|list|revoke|verify> [options]
   agent-relay pair <target|create|status|accept|reject|hangup|send> [options]
+  agent-relay merges <pause|resume|renew|list> [--repo PATH] [--base BRANCH] [--ttl 3m|--ttl-ms N] [--reason TEXT] [--holder TEXT] [--id ID] [--json]
   agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale|deps> [--id ID] [--strategy ...] [--auto-merge on-green|on-approval|manual] [--reviewer HANDLE] [--purpose TEXT] [--repo PATH] [--wait] [--timeout SECONDS] [--check] [--execute] [--json]
   agent-relay steward <queue|inspect|checks> [WORKSPACE_ID] [--repo PATH] [--json]
   agent-relay message <target> <body> [options]
@@ -141,6 +143,11 @@ Token examples:
   agent-relay token list
   agent-relay token revoke JTI
 
+Merge pause examples:
+  agent-relay merges pause --repo /repo --reason release --ttl 5m
+  agent-relay merges renew --id PAUSE_ID --ttl 5m
+  agent-relay merges resume --id PAUSE_ID
+
 Context probe examples:
   agent-relay context-probe print-status-line --wrap 'ccstatusline'
   agent-relay context-probe --wrap 'ccstatusline'
@@ -345,6 +352,10 @@ export async function handleCli(args: string[]): Promise<"start" | "handled"> {
     await handleTagsCommand(args.slice(1));
     return "handled";
   }
+  if (command === "merges" || command === "merge") {
+    await handleMergesCommand(args.slice(1));
+    return "handled";
+  }
   if (command === "workspace" || command === "workspaces") {
     await handleWorkspaceCommand(args.slice(1));
     return "handled";

package/src/cli/merges.ts

@@ -0,0 +1,89 @@
+// Merge coordination CLI. Generic pause/resume lease for relay-owned auto-merge
+// sweeps; useful for release/build critical sections (#448).
+import { spawnSync } from "node:child_process";
+import { apiRequest } from "./_shared";
+
+const MERGES_USAGE = "Usage: agent-relay merges <pause|resume|renew|list> [--repo PATH] [--base BRANCH] [--ttl 3m|--ttl-ms N] [--reason TEXT] [--holder TEXT] [--id ID] [--json]";
+
+function gitRoot(): string | undefined {
+  const r = spawnSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf8", stdio: "pipe" });
+  return r.status === 0 ? r.stdout.trim() : undefined;
+}
+
+function parseDurationMs(raw: string): number {
+  const match = raw.trim().match(/^(\d+)(ms|s|m|h)?$/);
+  if (!match) throw new Error("--ttl must be a positive duration like 180s, 3m, 1h, or use --ttl-ms");
+  const value = Number(match[1]);
+  const unit = match[2] ?? "ms";
+  const multiplier = unit === "h" ? 60 * 60_000 : unit === "m" ? 60_000 : unit === "s" ? 1000 : 1;
+  const ms = value * multiplier;
+  if (!Number.isSafeInteger(ms) || ms <= 0) throw new Error("--ttl is out of range");
+  return ms;
+}
+
+function formatPause(pause: any): string {
+  const until = new Date(pause.expiresAt).toISOString();
+  return `Merge pause ${pause.id}: ${pause.repoRoot}#${pause.baseRef} held by ${pause.holder} until ${until}${pause.reason ? ` (${pause.reason})` : ""}`;
+}
+
+export async function handleMergesCommand(args: string[]): Promise<void> {
+  const action = args[0];
+  if (action === "--help" || action === "-h" || action === "help") {
+    console.log(MERGES_USAGE);
+    return;
+  }
+  if (!action || !["pause", "resume", "renew", "list"].includes(action)) throw new Error(MERGES_USAGE);
+
+  let repoRoot: string | undefined;
+  let baseRef = "main";
+  let ttlMs: number | undefined;
+  let reason: string | undefined;
+  let holder: string | undefined;
+  let id: string | undefined;
+  let json = false;
+
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--repo" && i + 1 < args.length) repoRoot = args[++i];
+    else if (arg === "--base" && i + 1 < args.length) baseRef = args[++i]!;
+    else if (arg === "--ttl" && i + 1 < args.length) ttlMs = parseDurationMs(args[++i]!);
+    else if (arg === "--ttl-ms" && i + 1 < args.length) {
+      ttlMs = Number.parseInt(args[++i]!, 10);
+      if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0) throw new Error("--ttl-ms must be a positive integer");
+    }
+    else if (arg === "--reason" && i + 1 < args.length) reason = args[++i];
+    else if (arg === "--holder" && i + 1 < args.length) holder = args[++i];
+    else if (arg === "--id" && i + 1 < args.length) id = args[++i];
+    else if (arg === "--json") json = true;
+    else throw new Error(`Unknown merges option "${arg}".`);
+  }
+
+  if (action === "list") {
+    const result = await apiRequest("GET", "/api/merges/pauses");
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  if (action === "renew") {
+    if (!id) throw new Error("merges renew requires --id");
+    const result = await apiRequest("POST", "/api/merges/renew", { id, ttlMs });
+    if (json) console.log(JSON.stringify(result, null, 2));
+    else console.log(formatPause((result as any).pause));
+    return;
+  }
+
+  repoRoot = repoRoot ?? gitRoot();
+  if (action === "pause" && !repoRoot) throw new Error("No git repo detected. Pass --repo PATH.");
+  if (action === "resume" && !id && !repoRoot) throw new Error("No git repo detected. Pass --id ID or --repo PATH.");
+
+  if (action === "pause") {
+    const result = await apiRequest("POST", "/api/merges/pause", { repoRoot, baseRef, ttlMs, reason, holder });
+    if (json) console.log(JSON.stringify(result, null, 2));
+    else console.log(formatPause((result as any).pause));
+    return;
+  }
+
+  const result = await apiRequest("POST", "/api/merges/resume", id ? { id } : { repoRoot, baseRef });
+  if (json) console.log(JSON.stringify(result, null, 2));
+  else console.log((result as any).released ? "Merge pause released." : "No matching merge pause was active.");
+}

package/src/config.ts

@@ -20,6 +20,11 @@ function envPositiveInt(name: string, fallback: number): number {
 }
 
 export const STALE_TTL_MS = envPositiveInt("STALE_TTL_MS", 120_000); // 2min without heartbeat → offline
+// #451 — default TTL for fire-and-forget FAN-OUT messages (broadcast/tag/cap/label/team) that the
+// sender didn't bound. A stale fan-out push must not wake an agent that matches the target hours
+// later (the cold-session-woken-by-old-coordination-thread bug). Direct DMs, reply-obligations, and
+// claimable work are exempt (never auto-expire) so store-ahead (#234) still delivers them.
+export const DEFAULT_FANOUT_TTL_SECONDS = envPositiveInt("AGENT_RELAY_FANOUT_TTL_SECONDS", 2 * 60 * 60); // 2h
 export const OFFLINE_PRUNE_MS = envPositiveInt("OFFLINE_PRUNE_MS", DAY_MS); // 24h offline → delete
 export const REAP_INTERVAL_MS = envPositiveInt("REAP_INTERVAL_MS", 60_000); // reaper cadence
 export const CLAIM_LEASE_MS = envPositiveInt("AGENT_RELAY_CLAIM_LEASE_MS", 1_800_000); // 30min claim lease
@@ -28,6 +33,10 @@ export const POOL_CLAIM_LEASE_MS = envPositiveInt("AGENT_RELAY_POOL_CLAIM_LEASE_
 // repo. Held from when a workspace.merge command is dispatched until it settles
 // (or this TTL expires, in case the orchestrator never reports back).
 export const WORKSPACE_MERGE_LEASE_MS = envPositiveInt("AGENT_RELAY_WORKSPACE_MERGE_LEASE_MS", 900_000); // 15min
+// Opt-in release/build critical-section pause for relay-owned auto-merge sweeps.
+// This narrows the race window while the release script creates and pushes a tag;
+// expiry is the safety net so a killed holder cannot wedge the repo.
+export const MAIN_MERGE_PAUSE_TTL_MS = envPositiveInt("AGENT_RELAY_MAIN_MERGE_PAUSE_TTL_MS", 5 * 60_000); // 5min
 
 // Max body size for any POST/PATCH request (64 KiB).
 export const MAX_BODY_BYTES = 64 * 1024;

package/src/context-advisory.ts

@@ -1,7 +1,7 @@
 import { getNotificationsConfig } from "./config-store";
 import { getDb } from "./db/connection.ts";
 import { emitRelayEvent } from "./events";
-import { notifySystemMessage } from "./notify";
+import { routeNotification } from "./notification-router";
 import type { AgentCard, Command, ContextState } from "./types";
 
 interface ContextAdvisoryInput {
@@ -38,11 +38,18 @@ function notifyContextAdvisory(input: ContextAdvisoryInput): void {
   const config = getNotificationsConfig();
   if (!config.enabled || !config.contextThreshold.enabled) return;
 
-  notifySystemMessage(input.agentId, {
-    subject: "Context threshold reached",
-    body: `Context advisory: ${formatTokens(input.tokens)} / ${formatTokens(input.windowTokens)} tokens used (${input.percent}% of window, ${input.band}% band). Compact at a clean seam before the ${input.hardBackstopPercent}% hard backstop may request compaction.`,
-    payload,
-    replyExpected: false,
+  // Short default TTL (per-type): a stale context advisory is misleading — the band may have moved
+  // by the time the agent next polls, so old advice shouldn't wake it.
+  routeNotification({
+    type: "agent.context_threshold",
+    scope: { agentId: input.agentId },
+    recipients: [input.agentId],
+    message: {
+      subject: "Context threshold reached",
+      body: `Context advisory: ${formatTokens(input.tokens)} / ${formatTokens(input.windowTokens)} tokens used (${input.percent}% of window, ${input.band}% band). Compact at a clean seam before the ${input.hardBackstopPercent}% hard backstop may request compaction.`,
+      payload,
+      replyExpected: false,
+    },
   });
 }
 

package/src/db/merge-lease.ts

@@ -12,7 +12,7 @@ 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 { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_MERGE_LEASE_MS, MAIN_MERGE_PAUSE_TTL_MS } from "../config";
 import { matchAgents } from "../agent-ref";
 import { getDb } from "./connection.ts";
 import type {
@@ -158,3 +158,97 @@ export function releaseMergeLease(opts: { repoRoot?: string; commandId?: string;
   return getDb().query(`DELETE FROM workspace_merge_leases WHERE ${where.join(" AND ")}`).run(...params).changes > 0;
 }
 
+// --- Per-target merge pause lease (issue #448) -----------------------------
+
+export interface MergePauseRecord {
+  id: string;
+  repoRoot: string;
+  baseRef: string;
+  holder: string;
+  reason?: string;
+  createdAt: number;
+  updatedAt: number;
+  expiresAt: number;
+}
+
+export function rowToMergePause(row: any): MergePauseRecord {
+  return {
+    id: row.id,
+    repoRoot: row.repo_root,
+    baseRef: row.base_ref,
+    holder: row.holder,
+    reason: row.reason ?? undefined,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+    expiresAt: row.expires_at,
+  };
+}
+
+export function getMergePause(id: string): MergePauseRecord | null {
+  const row = getDb().query("SELECT * FROM workspace_merge_pauses WHERE id = ?").get(id) as any;
+  return row ? rowToMergePause(row) : null;
+}
+
+export function getActiveMergePause(repoRoot: string, baseRef = "main", now: number = Date.now()): MergePauseRecord | null {
+  const row = getDb().query("SELECT * FROM workspace_merge_pauses WHERE repo_root = ? AND base_ref = ? AND expires_at > ?")
+    .get(repoRoot, baseRef, now) as any;
+  return row ? rowToMergePause(row) : null;
+}
+
+export function listMergePauses(): MergePauseRecord[] {
+  return (getDb().query("SELECT * FROM workspace_merge_pauses ORDER BY updated_at DESC").all() as any[]).map(rowToMergePause);
+}
+
+export function acquireMergePause(input: {
+  repoRoot: string;
+  baseRef?: string;
+  holder: string;
+  reason?: string;
+  ttlMs?: number;
+  now?: number;
+}): { ok: true; pause: MergePauseRecord } | { ok: false; pause: MergePauseRecord } {
+  return getDb().transaction(() => {
+    const now = input.now ?? Date.now();
+    const baseRef = input.baseRef || "main";
+    const existing = getActiveMergePause(input.repoRoot, baseRef, now);
+    if (existing) return { ok: false as const, pause: existing };
+    const id = randomUUID();
+    const expiresAt = now + (input.ttlMs ?? MAIN_MERGE_PAUSE_TTL_MS);
+    getDb().query(`
+      INSERT INTO workspace_merge_pauses (id, repo_root, base_ref, holder, reason, created_at, updated_at, expires_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(repo_root, base_ref) DO UPDATE SET
+        id = excluded.id,
+        holder = excluded.holder,
+        reason = excluded.reason,
+        created_at = excluded.created_at,
+        updated_at = excluded.updated_at,
+        expires_at = excluded.expires_at
+    `).run(id, input.repoRoot, baseRef, input.holder, input.reason ?? null, now, now, expiresAt);
+    return { ok: true as const, pause: getMergePause(id)! };
+  })();
+}
+
+export function renewMergePause(id: string, ttlMs: number = MAIN_MERGE_PAUSE_TTL_MS, now: number = Date.now()): MergePauseRecord | null {
+  const current = getMergePause(id);
+  if (!current || current.expiresAt <= now) return null;
+  getDb().query("UPDATE workspace_merge_pauses SET updated_at = ?, expires_at = ? WHERE id = ?").run(now, now + ttlMs, id);
+  return getMergePause(id);
+}
+
+export function releaseMergePause(opts: { id?: string; repoRoot?: string; baseRef?: string }): boolean {
+  const where: string[] = [];
+  const params: string[] = [];
+  if (opts.id) { where.push("id = ?"); params.push(opts.id); }
+  if (opts.repoRoot) { where.push("repo_root = ?"); params.push(opts.repoRoot); }
+  if (opts.baseRef) { where.push("base_ref = ?"); params.push(opts.baseRef); }
+  if (!where.length) return false;
+  return getDb().query(`DELETE FROM workspace_merge_pauses WHERE ${where.join(" AND ")}`).run(...params).changes > 0;
+}
+
+export function releaseExpiredMergePauses(now: number = Date.now()): string[] {
+  const expired = getDb().query("SELECT id FROM workspace_merge_pauses WHERE expires_at <= ?").all(now) as Array<{ id: string }>;
+  if (!expired.length) return [];
+  getDb().query("DELETE FROM workspace_merge_pauses WHERE expires_at <= ?").run(now);
+  return expired.map((r) => r.id);
+}

package/src/db/message-reads.ts

@@ -204,6 +204,12 @@ export function pollMessages(query: PollQuery): Message[] {
   }
   conditions.push("delivery_status != 'queued' AND delivery_status NOT IN ('failed', 'dead')");
 
+  // #451 — never surface a message past its TTL: a stale fan-out notification must not wake an
+  // agent that matches its target long after it was sent. NULL max_age_seconds never expires
+  // (direct DMs, reply-obligations, claimable work — store-ahead #234 still delivers those).
+  conditions.push("(max_age_seconds IS NULL OR created_at + max_age_seconds * 1000 > ?)");
+  params.push(Date.now());
+
   // A claimable message is available to this agent when it is non-claimable, currently held by
   // THIS agent, or unclaimed/expired AND its task is not already closed. The closed-task guard
   // must cover BOTH the null-claim and the expired-claim branch: when a managed agent is

package/src/db/messages.ts

@@ -12,8 +12,9 @@ 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 { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_MERGE_LEASE_MS, DEFAULT_FANOUT_TTL_SECONDS } from "../config";
 import { matchAgents } from "../agent-ref";
+import { isFanoutTarget } from "../channel-target";
 import { getAgent, validateAgentSession } from "./agents.ts";
 import { cleanAttachmentRefs, linkAttachmentRefs, validateAttachmentRefs } from "./artifacts.ts";
 import { ClaimError, ValidationError, getDb } from "./connection.ts";
@@ -247,6 +248,10 @@ export function sendMessageWithResult(input: SendMessageInput): { message: Messa
   const policyName = policyNameFromTarget(input.to);
   let deliveryStatus: Message["deliveryStatus"] = "pending";
   let queuedAt: number | null = null;
+  // Distinguish "unspecified" (apply the #451 fan-out default below) from an explicit `null`
+  // (authoritative never-expire — routeNotification sets this for store-ahead notification types,
+  // and the baseline must not override it). Both store as NULL, but only unspecified gets a default.
+  const ttlUnspecified = input.maxAgeSeconds === undefined;
   let maxAgeSeconds = input.maxAgeSeconds ?? null;
   let resolvedToAgent: string | null = null;
 
@@ -260,6 +265,16 @@ export function sendMessageWithResult(input: SendMessageInput): { message: Messa
     }
   }
 
+  // #451 — moderate default TTL for fire-and-forget FAN-OUT messages the sender didn't bound, so a
+  // stale broadcast/tag/cap/label/team push can't wake a late-joining agent hours later. Exempt
+  // (never auto-expire, preserving store-ahead #234): direct DMs and policy targets (single
+  // recipient), reply-obligations (replyExpected !== false), claimable work, and any message that
+  // already carried an explicit TTL — including an explicit `null` from routeNotification, whose
+  // per-type decision (e.g. a store-ahead `plan.bound_agent_exited` to `team:`) must win here.
+  if (ttlUnspecified && input.replyExpected === false && !claimable && isFanoutTarget(input.to)) {
+    maxAgeSeconds = DEFAULT_FANOUT_TTL_SECONDS;
+  }
+
   const id = getDb().transaction(() => {
     const result = insert.run({
       $from: input.from,

package/src/db/migrations.ts

@@ -117,6 +117,21 @@ export function applyMigrations(): void {
   normalizeExistingMessageReactions();
 
   // Migrations
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS workspace_merge_pauses (
+      id TEXT PRIMARY KEY,
+      repo_root TEXT NOT NULL,
+      base_ref TEXT NOT NULL,
+      holder TEXT NOT NULL,
+      reason TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      expires_at INTEGER NOT NULL,
+      UNIQUE(repo_root, base_ref)
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_workspace_merge_pauses_expires ON workspace_merge_pauses(expires_at)");
+
   const cols = getDb().query("PRAGMA table_info(messages)").all() as any[];
   const colNames = cols.map((c: any) => c.name);
   if (!colNames.includes("thread_id")) {
@@ -449,6 +464,21 @@ export function applyMigrations(): void {
     getDb().run("ALTER TABLE agents ADD COLUMN team_id TEXT");
   }
   getDb().run("CREATE INDEX IF NOT EXISTS idx_agents_team ON agents(team_id)");
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS notification_subscriptions (
+      id TEXT PRIMARY KEY,
+      agent_id TEXT NOT NULL REFERENCES agents(id) ON DELETE CASCADE,
+      type TEXT NOT NULL,
+      mode TEXT NOT NULL CHECK (mode IN ('opt_in', 'opt_out', 'mute')),
+      scope_match TEXT,
+      created_at INTEGER NOT NULL
+    )
+  `);
+  getDb().run("CREATE INDEX IF NOT EXISTS idx_notification_subscriptions_agent ON notification_subscriptions(agent_id, type)");
+  getDb().run(`
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_notification_subscriptions_unique
+    ON notification_subscriptions(agent_id, type, mode, coalesce(scope_match, ''))
+  `);
   getDb().run(`
     CREATE TABLE IF NOT EXISTS context_snapshots (
       id INTEGER PRIMARY KEY AUTOINCREMENT,