agent-relay-server 0.59.0 → 0.60.0

package/src/maintenance.ts

@@ -59,7 +59,7 @@ import {
   emitPoolBindingChanged,
   emitTaskChanged,
 } from "./sse";
-import { notifySystemMessage } from "./notify";
+import { routeNotification, type NotificationType, type NotificationScope } from "./notification-router";
 import { pruneExpiredTokenRecords } from "./token-db";
 import { dissolveTeamById } from "./services/team";
 import { reapTransientAgents, resetTransientTrackerForTests } from "./services/transient-agent-reaper";
@@ -633,10 +633,16 @@ function wakeRepoSteward(ws: WorkspaceRecord, reason: string): string | null {
   const policyName = ensureRepoSteward(ws.repoRoot);
   if (!policyName) return null;
   try {
-    notifySystemMessage(`policy:${policyName}`, {
-      subject: `Steward: ${ws.status} workspace needs attention`,
-      body: `Workspace \`${ws.branch ?? ws.id}\` (id ${ws.id}) in ${ws.repoRoot} is ${ws.status} and could not auto-land (${reason}). Claim it first so auto-merge yields: \`agent-relay workspace claim --id ${ws.id} --purpose steward\`. Inspect: \`agent-relay steward inspect ${ws.id}\`. Then cd into ${ws.worktreePath}, rebase onto ${ws.baseRef ?? "base"}, resolve, run checks, and land: \`agent-relay workspace land --id ${ws.id} --strategy rebase-ff\` — or \`agent-relay workspace release --id ${ws.id}\` and escalate if you can't.`,
-      payload: { kind: "workspace.steward-task", workspaceId: ws.id, repoRoot: ws.repoRoot, worktreePath: ws.worktreePath, branch: ws.branch, baseRef: ws.baseRef, status: ws.status, reason },
+    // Obligation (ttl null by type default): a steward task must survive until claimed/handled.
+    routeNotification({
+      type: "workspace.steward_task",
+      scope: { workspaceId: ws.id, repoRoot: ws.repoRoot },
+      recipients: [`policy:${policyName}`],
+      message: {
+        subject: `Steward: ${ws.status} workspace needs attention`,
+        body: `Workspace \`${ws.branch ?? ws.id}\` (id ${ws.id}) in ${ws.repoRoot} is ${ws.status} and could not auto-land (${reason}). Claim it first so auto-merge yields: \`agent-relay workspace claim --id ${ws.id} --purpose steward\`. Inspect: \`agent-relay steward inspect ${ws.id}\`. Then cd into ${ws.worktreePath}, rebase onto ${ws.baseRef ?? "base"}, resolve, run checks, and land: \`agent-relay workspace land --id ${ws.id} --strategy rebase-ff\` — or \`agent-relay workspace release --id ${ws.id}\` and escalate if you can't.`,
+        payload: { kind: "workspace.steward-task", workspaceId: ws.id, repoRoot: ws.repoRoot, worktreePath: ws.worktreePath, branch: ws.branch, baseRef: ws.baseRef, status: ws.status, reason },
+      },
     });
     getLifecycleManager().onMessageForPolicy(policyName);
     patchWorkspaceMetadata(ws.id, { stewardWokenAt: Date.now(), stewardPolicy: policyName });
@@ -740,10 +746,16 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
         if (woke) notifiedStewards.push(woke);
       } else if (ws.stewardAgentId) {
         try {
-          notifySystemMessage(ws.stewardAgentId, {
-            subject: "Workspace merge conflict",
-            body: `Workspace \`${ws.branch ?? ws.id}\` in ${ws.repoRoot} can no longer merge cleanly into ${p.baseRef ?? "base"} (${p.ahead ?? "?"} ahead, ${p.behind ?? "?"} behind). As repo steward, please coordinate resolution.`,
-            payload: { kind: "workspace.conflict", workspaceId: ws.id, repoRoot: ws.repoRoot, branch: ws.branch, baseRef: p.baseRef, ahead: p.ahead, behind: p.behind },
+          // Obligation (ttl null by type default): a conflict handoff must reach the steward.
+          routeNotification({
+            type: "workspace.conflict",
+            scope: { workspaceId: ws.id, repoRoot: ws.repoRoot },
+            recipients: [ws.stewardAgentId],
+            message: {
+              subject: "Workspace merge conflict",
+              body: `Workspace \`${ws.branch ?? ws.id}\` in ${ws.repoRoot} can no longer merge cleanly into ${p.baseRef ?? "base"} (${p.ahead ?? "?"} ahead, ${p.behind ?? "?"} behind). As repo steward, please coordinate resolution.`,
+              payload: { kind: "workspace.conflict", workspaceId: ws.id, repoRoot: ws.repoRoot, branch: ws.branch, baseRef: p.baseRef, ahead: p.ahead, behind: p.behind },
+            },
           });
           notifiedStewards.push(ws.stewardAgentId);
         } catch {
@@ -848,12 +860,13 @@ async function autoMergeCleanFastForwards(): Promise<Record<string, unknown>> {
   return { scanned: candidates.length, merged, heldByLease, heldByClaim, heldAwaitingApproval, leftForSteward, wokeStewards };
 }
 
-// Send a system DM, swallowing failures (a stale/missing/misconfigured target
-// must never break the GC sweep). Returns the target on success, null otherwise.
-function notifyTarget(target: string, subject: string, body: string, payload: Record<string, unknown>): string | null {
+// Route a GC notification, swallowing failures (a stale/missing/misconfigured target must never
+// break the GC sweep). Returns the target on success, null otherwise. These are all obligation-style
+// workspace handoffs (null TTL by type default) — they must survive until the recipient acts.
+function notifyTarget(type: NotificationType, scope: NotificationScope, target: string, subject: string, body: string, payload: Record<string, unknown>): string | null {
   if (!target) return null;
   try {
-    notifySystemMessage(target, { subject, body, payload });
+    routeNotification({ type, scope, recipients: [target], message: { subject, body, payload } });
     return target;
   } catch {
     return null;
@@ -905,6 +918,8 @@ async function workspaceGC(): Promise<Record<string, unknown>> {
       // steward hasn't been told, hand it off explicitly, then clear markers.
       if (strandedAt !== undefined && meta.strandedNotifiedSteward !== steward) {
         const sent = notifyTarget(
+          "workspace.steward_reassigned",
+          { workspaceId: fresh.id, repoRoot: fresh.repoRoot },
           steward!,
           "Workspace stewardship reassigned",
           `You are now steward for ${fresh.repoRoot}. Workspace \`${fresh.branch ?? fresh.id}\` is ${fresh.status} and was stranded without an online steward — please coordinate ${fresh.status === "conflict" ? "conflict resolution" : "review/merge"}.`,
@@ -920,6 +935,8 @@ async function workspaceGC(): Promise<Record<string, unknown>> {
     if (strandedAt === undefined) { patchWorkspaceMetadata(fresh.id, { strandedAt: now }); continue; }
     if (now - strandedAt < escalationMs || meta.escalatedAt) continue;
     const sent = notifyTarget(
+      "workspace.stranded_escalation",
+      { workspaceId: fresh.id, repoRoot: fresh.repoRoot },
       fallbackTarget,
       "Stranded workspace needs an owner",
       `Workspace \`${fresh.branch ?? fresh.id}\` in ${fresh.repoRoot} is ${fresh.status} with no online steward (all repo agents offline) for ${Math.round((now - strandedAt) / (60 * 60 * 1000))}h. Please coordinate ${fresh.status === "conflict" ? "conflict resolution" : "review/merge"} or clean up the worktree.`,
@@ -951,6 +968,8 @@ async function workspaceGC(): Promise<Record<string, unknown>> {
       // stranded abandon isn't silent (issue #157).
       const target = ws.stewardAgentId ?? fallbackTarget;
       const sent = notifyTarget(
+        "workspace.auto_abandoned",
+        { workspaceId: ws.id, repoRoot: ws.repoRoot },
         target,
         "Workspace auto-abandoned",
         `Workspace \`${ws.branch ?? ws.id}\` in ${ws.repoRoot} was auto-abandoned after ${Math.round(WORKSPACE_REVIEW_TTL_MS / DAY_MS)}d without steward action. Run workspace cleanup to reclaim the worktree.`,

package/src/mcp-notification-subscription-tools.ts

@@ -0,0 +1,111 @@
+import {
+  addSubscription,
+  cleanSubscriptionMode,
+  cleanSubscriptionType,
+  listSubscriptions,
+  NOTIFICATION_SUBSCRIPTION_MODES,
+  NOTIFICATION_SUBSCRIPTION_TYPES,
+  removeSubscription,
+  type NotificationSubscriptionMode,
+} from "./db/notification-subscriptions";
+import { ValidationError } from "./db";
+import { McpAuthError } from "./mcp-errors";
+import { authContextFromMcp } from "./services/auth-context";
+import { cleanString } from "./validation";
+import type { NotificationScope } from "./notification-router";
+
+export const NOTIFICATION_SUBSCRIPTION_TOOLS = [
+  {
+    name: "relay_subscribe",
+    description: "Subscribe, opt out, or mute this caller agent for a notification type. The caller's token identity is the subscription owner.",
+    requiredScopes: ["notifications:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        type: { type: "string", enum: NOTIFICATION_SUBSCRIPTION_TYPES },
+        mode: { type: "string", enum: NOTIFICATION_SUBSCRIPTION_MODES, description: "Default opt_in. mute and opt_out suppress matching default deliveries." },
+        scope: { type: "object", description: "Optional partial notification scope match, such as { teamId } or { repoRoot }." },
+      },
+      required: ["type"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_unsubscribe",
+    description: "Remove this caller agent's notification subscription by id, or by type/mode/scope. Omitting mode removes all modes for the matched type/scope.",
+    requiredScopes: ["notifications:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string" },
+        type: { type: "string", enum: NOTIFICATION_SUBSCRIPTION_TYPES },
+        mode: { type: "string", enum: NOTIFICATION_SUBSCRIPTION_MODES },
+        scope: { type: "object" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_list_subscriptions",
+    description: "List this caller agent's durable notification subscriptions.",
+    requiredScopes: ["notifications:read"],
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+] satisfies Array<{ name: string; description: string; requiredScopes: string[]; inputSchema: Record<string, unknown> }>;
+
+type McpAuthLike = Parameters<typeof authContextFromMcp>[0];
+
+export function relayNotificationSubscriptionTool(
+  auth: McpAuthLike,
+  name: string,
+  args: Record<string, unknown>,
+): Record<string, unknown> {
+  const agentId = callerAgentId(auth);
+  if (name === "relay_subscribe") {
+    const subscription = addSubscription({
+      agentId,
+      type: cleanSubscriptionType(args.type),
+      mode: cleanModeOrDefault(args.mode),
+      scopeMatch: cleanScope(args.scope),
+    });
+    return { subscription };
+  }
+  if (name === "relay_unsubscribe") {
+    const id = cleanString(args.id, "id", { max: 120 });
+    const type = args.type === undefined || args.type === null ? undefined : cleanSubscriptionType(args.type);
+    if (!id && !type) throw new ValidationError("id or type required");
+    const removed = removeSubscription({
+      agentId,
+      id,
+      type,
+      mode: args.mode === undefined || args.mode === null ? undefined : cleanSubscriptionMode(args.mode),
+      ...(Object.prototype.hasOwnProperty.call(args, "scope") ? { scopeMatch: cleanScope(args.scope) } : {}),
+    });
+    return { removed };
+  }
+  if (name === "relay_list_subscriptions") {
+    return { subscriptions: listSubscriptions(agentId) };
+  }
+  throw new ValidationError(`unknown tool: ${name}`);
+}
+
+function callerAgentId(auth: McpAuthLike): string {
+  const ctx = authContextFromMcp(auth);
+  if (!ctx.callerAgentId) throw new McpAuthError("notification subscriptions require a single caller agent identity");
+  return ctx.callerAgentId;
+}
+
+function cleanModeOrDefault(value: unknown): NotificationSubscriptionMode {
+  if (value === undefined || value === null) return "opt_in";
+  return cleanSubscriptionMode(value);
+}
+
+function cleanScope(value: unknown): Partial<NotificationScope> | null {
+  if (value === undefined || value === null) return null;
+  if (typeof value !== "object" || Array.isArray(value)) throw new ValidationError("scope must be an object");
+  return value as Partial<NotificationScope>;
+}

package/src/mcp.ts

@@ -50,6 +50,7 @@ import { PLAN_TOOLS, relayPlanTool } from "./mcp-plan-tools";
 import { TEAM_TOOLS, relayTeamTool } from "./mcp-team-tools";
 import { BLACKBOARD_TOOLS, relayBlackboardTool } from "./mcp-blackboard-tools";
 import { PROJECT_TOOLS, relayProjectTool } from "./mcp-project-tools";
+import { NOTIFICATION_SUBSCRIPTION_TOOLS, relayNotificationSubscriptionTool } from "./mcp-notification-subscription-tools";
 import { PROJECT_INSTRUCTION_POLICY_NAMES, parseProjectInstructions } from "./project-instructions";
 import { AGENT_ACTION_TOOL, relayAgentAction } from "./mcp-agent-action";
 import type { ActivityKind, AgentLifecycle, ArtifactKind, ArtifactSensitivity, AttachmentRef, Command, SendMessageInput, Message, SpawnApprovalMode, SpawnProvider, WorkspaceAutoMergePolicy, WorkspaceMergeStrategy, WorkspaceMode, WorkspaceRecord } from "./types";
@@ -463,6 +464,7 @@ const TOOLS: ToolDefinition[] = [
   ...PLAN_TOOLS,
   ...BLACKBOARD_TOOLS,
   ...PROJECT_TOOLS,
+  ...NOTIFICATION_SUBSCRIPTION_TOOLS,
 ];
 
 export async function postMcp(req: Request): Promise<Response> {
@@ -579,6 +581,7 @@ async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<s
     else if (name.startsWith("relay_plan_")) result = relayPlanTool(auth, name, args);
     else if (name.startsWith("relay_blackboard_")) result = relayBlackboardTool(auth, name, args);
     else if (name.startsWith("relay_project_")) result = relayProjectTool(auth, name, args);
+    else if (name === "relay_subscribe" || name === "relay_unsubscribe" || name === "relay_list_subscriptions") result = relayNotificationSubscriptionTool(auth, name, args);
     else throw new ValidationError(`unknown tool: ${name}`);
 
     auditToolCall(auth, name, "ok", result);

package/src/notification-router.ts

@@ -0,0 +1,168 @@
+import { notifySystemMessage } from "./notify";
+import type { Message, MessageKind } from "./types";
+
+/**
+ * #440 — the single seam every agent-facing "wake" notification flows through. Before this,
+ * ~10 emitter sites each hand-rolled their own recipient policy and called `notifySystemMessage`
+ * directly, with no central rule, no staleness guard, and no record of *why* an agent was chosen.
+ *
+ * This is the #441 slice: the seam + taxonomy + the #451 TTL guard. It is **behavior-preserving** —
+ * emitters still compute and pass their recipients (`recipients`); the router does not yet derive
+ * them from `scope`. The follow-ups move the *deciding* in:
+ *   - #442 introduces the rule engine that computes recipients FROM `scope`.
+ *   - #444 flips `branch.landed` to be the first rule-driven type (retiring its hand-rolled fan-out).
+ *   - #446 turns the routing decision recorded here into an explainable trace.
+ *
+ * `scope` (the entities a notification is ABOUT) is captured now even though #441 doesn't route on
+ * it, so emitters are converted exactly once and the rule engine has its inputs the day it lands.
+ */
+export type NotificationType =
+  | "branch.landed"
+  | "agent.ready"
+  | "agent.exited"
+  | "agent.spawn_failed"
+  | "agent.context_threshold"
+  | "agent.resume_budget_exhausted"
+  | "agent.transient_land_hold"
+  | "agent.rate_limit_resume"
+  | "plan.bound_agent_exited"
+  | "workspace.steward_task"
+  | "workspace.conflict"
+  | "workspace.steward_reassigned"
+  | "workspace.stranded_escalation"
+  | "workspace.auto_abandoned"
+  | "workspace.review_request"
+  | "workspace.review_changes_requested";
+
+/**
+ * The entities a notification is ABOUT — the future routing inputs (#442) and the explainability
+ * subject (#446). All optional: each emitter fills the fields it has in scope at the call site.
+ */
+export interface NotificationScope {
+  /** The agent whose work the notification concerns (branch author, workspace owner). */
+  author?: string;
+  /** The agent the notification is primarily about (lifecycle subject, advisory target). */
+  agentId?: string;
+  /** The spawn-parent that should hear about a child's lifecycle. */
+  parent?: string;
+  /** Team the notification belongs to (plan/coordination scope). */
+  teamId?: string;
+  /** Plan the notification concerns. */
+  planId?: string;
+  /** Repo checkout the notification concerns. */
+  repoRoot?: string;
+  /** Workspace the notification concerns. */
+  workspaceId?: string;
+  /** Files the notification concerns (path-scoped routing, #442). */
+  paths?: string[];
+}
+
+export interface NotificationMessage {
+  subject?: string;
+  body: string;
+  payload?: Record<string, unknown>;
+  kind?: MessageKind;
+  from?: string;
+  /** Default true. Set false for fire-and-forget pushes (no reply scaffold, no obligation). */
+  replyExpected?: boolean;
+}
+
+export interface RouteNotificationInput {
+  type: NotificationType;
+  scope: NotificationScope;
+  /**
+   * Recipients chosen by the emitter (#441, behavior-preserving). May be concrete agent ids OR
+   * durable targets (`policy:`, `team:`, `label:`, `broadcast`, …) — the delivery layer resolves
+   * durable forms at poll time. #442 will derive this set from `scope` via the rule engine.
+   */
+  recipients: Array<string | undefined | null>;
+  message: NotificationMessage;
+  /**
+   * #451 — time-to-live in ms from `emittedAt`, after which the notification is stale and must not
+   * wake a recipient. `undefined` → the per-type default ({@link DEFAULT_TTL_MS}); `null` → never
+   * expires (store-ahead). Emitters override per-call when the type default isn't right for the
+   * audience (e.g. `branch.landed`'s bystander fan-out is ephemeral while the author copy is durable).
+   */
+  ttlMs?: number | null;
+  /** When the underlying event occurred; defaults to now. Drives the staleness guard. */
+  emittedAt?: number;
+}
+
+const MINUTES = 60 * 1000;
+
+/**
+ * Per-type default TTL (#451). Default-SAFE: anything about the recipient's own work or any
+ * obligation is `null` (never auto-expires — store-ahead #234 must still deliver it). Only the
+ * genuinely now-or-never pings get a short default; a stale one of those is actively misleading:
+ *   - `agent.context_threshold` — the advisory band may have changed; old advice is wrong.
+ *   - `agent.rate_limit_resume`  — "your hold cleared, resume" is pointless once the window moved.
+ * Emitters opt INTO a shorter TTL per-call for the bystander/informational cases.
+ */
+export const DEFAULT_TTL_MS: Record<NotificationType, number | null> = {
+  "branch.landed": null,
+  "agent.ready": null,
+  "agent.exited": null,
+  "agent.spawn_failed": null,
+  "agent.context_threshold": 15 * MINUTES,
+  "agent.resume_budget_exhausted": null,
+  "agent.transient_land_hold": null,
+  "agent.rate_limit_resume": 15 * MINUTES,
+  "plan.bound_agent_exited": null,
+  "workspace.steward_task": null,
+  "workspace.conflict": null,
+  "workspace.steward_reassigned": null,
+  "workspace.stranded_escalation": null,
+  "workspace.auto_abandoned": null,
+  "workspace.review_request": null,
+  "workspace.review_changes_requested": null,
+};
+
+/** Convenience TTL for emitter-supplied overrides on bystander/informational notifications. */
+export const INFORMATIONAL_TTL_MS = 30 * MINUTES;
+
+/**
+ * Resolve the effective TTL: an explicit per-call `ttlMs` wins (including an explicit `null` =
+ * never); `undefined` falls back to the per-type default.
+ */
+function effectiveTtlMs(type: NotificationType, ttlMs: number | null | undefined): number | null {
+  return ttlMs === undefined ? DEFAULT_TTL_MS[type] : ttlMs;
+}
+
+/**
+ * Route a wake-notification to its recipients. Applies the #451 staleness guard, stamps the TTL as
+ * the delivered message's `maxAgeSeconds` (so the poll path drops it once stale), and sends one
+ * system message per unique recipient. Returns the delivered messages (most callers ignore this).
+ *
+ * Recipients are de-duplicated and emptied of falsy entries, so emitters can pass optional ids
+ * without guarding. A notification with zero resolved recipients is a no-op.
+ */
+export function routeNotification(input: RouteNotificationInput): Message[] {
+  const ttl = effectiveTtlMs(input.type, input.ttlMs);
+  const emittedAt = input.emittedAt ?? Date.now();
+
+  // Staleness guard (#451): if the triggering event is already older than its TTL, drop before
+  // sending. On the normal synchronous path emittedAt ≈ now so this rarely fires, but it makes the
+  // router correct for any caller that routes a delayed/replayed event.
+  if (ttl !== null && Date.now() - emittedAt > ttl) return [];
+
+  const recipients = [...new Set(input.recipients.filter((r): r is string => Boolean(r && r.trim())))];
+  if (recipients.length === 0) return [];
+
+  // Stamp the TTL on the message so the delivery/poll path (pollMessages) enforces it for offline
+  // or late-joining recipients too. An explicit `null` (never-expire) is authoritative: it suppresses
+  // sendMessage's fan-out default, so a store-ahead type sent to `team:`/`broadcast` keeps its
+  // never-expire intent instead of inheriting the moderate baseline.
+  const maxAgeSeconds = ttl === null ? null : Math.max(1, Math.ceil(ttl / 1000));
+
+  return recipients.map((to) =>
+    notifySystemMessage(to, {
+      subject: input.message.subject,
+      body: input.message.body,
+      payload: input.message.payload,
+      kind: input.message.kind,
+      from: input.message.from,
+      replyExpected: input.message.replyExpected,
+      maxAgeSeconds,
+    }),
+  );
+}

package/src/notification-rules.ts

@@ -0,0 +1,186 @@
+import type { AgentCard } from "./types";
+import { listAgents } from "./db";
+import { isAgentOnline } from "./agent-ref";
+import type { NotificationType, NotificationScope } from "./notification-router";
+
+/**
+ * #442 — the declarative rule engine that computes a notification's recipients FROM its `scope`,
+ * replacing the hand-rolled recipient policy each emitter used to carry (#441 kept those inline as
+ * the behavior-preserving step). This is the **model + evaluator**: a library of typed predicates,
+ * an ordered evaluator that yields a per-agent decision + the matched rule, and the seam where
+ * #443 subscriptions (opt-in / opt-out / mute) plug in as override rules.
+ *
+ * Core design (from epic #440): **rules-as-CODE, subscriptions/overrides-as-DATA.** The default
+ * audience for each type is a composition of these predicates in versioned, tested code — extending
+ * the engine means adding a typed predicate, never authoring a stored rule DSL. Per-type compositions
+ * are REGISTERED by each type's migration (#444 registers `branch.landed` first and flips its call
+ * site); until a type is registered, {@link resolveAudience} returns `[]` and that type stays on the
+ * #441 explicit-recipients path. Nothing here is wired into production delivery yet — #444 does that.
+ */
+
+export type RuleDecision = "deliver" | "suppress" | "abstain";
+
+export interface NotificationRuleContext {
+  type: NotificationType;
+  scope: NotificationScope;
+  /** Evaluation clock — passed in (never read via Date.now() inside a rule) so eval is testable. */
+  now: number;
+}
+
+export interface NotificationRule {
+  /** Stable identifier recorded as the matched rule — the #446 "why did I get this?" answer. */
+  name: string;
+  evaluate(agent: AgentCard, ctx: NotificationRuleContext): RuleDecision;
+}
+
+export interface AudienceMember {
+  agentId: string;
+  /** The rule whose decision was decisive (last non-abstain wins) — carried for explainability (#446). */
+  matchedRule: string;
+}
+
+/**
+ * Predicate library — the reusable building blocks each type composes its default audience from.
+ * Each factory returns a single-concern rule. `deliver` includes the agent; `abstain` leaves the
+ * running decision unchanged; `suppress` removes an agent a prior rule delivered (the opt-out/mute
+ * shape #443 builds on). Compose them ordered: later rules override earlier (see {@link evaluateAudience}).
+ */
+export const audiencePredicates = {
+  /** The agent whose work the notification is about — delivered even when offline (store-ahead #234). */
+  author: (): NotificationRule => ({
+    name: "author",
+    evaluate: (a, { scope }) => (scope.author && a.id === scope.author ? "deliver" : "abstain"),
+  }),
+  /** The spawn-parent that should hear about a child's lifecycle — online-agnostic (store-ahead). */
+  spawnParent: (): NotificationRule => ({
+    name: "spawn-parent",
+    evaluate: (a, { scope }) => (scope.parent && a.id === scope.parent ? "deliver" : "abstain"),
+  }),
+  /** The notification's primary subject agent (advisory target, lifecycle subject). */
+  subjectAgent: (): NotificationRule => ({
+    name: "subject-agent",
+    evaluate: (a, { scope }) => (scope.agentId && a.id === scope.agentId ? "deliver" : "abstain"),
+  }),
+  /** Every member of the notification's team (coordination/plan scope). Online-agnostic by default. */
+  sameTeam: (): NotificationRule => ({
+    name: "same-team",
+    evaluate: (a, { scope }) => (scope.teamId && a.teamId === scope.teamId ? "deliver" : "abstain"),
+  }),
+  /**
+   * Team-scoping SUPPRESSOR (#444): removes an agent that's on a DIFFERENT team than the
+   * notification's. Compose it AFTER a deliver rule (last-wins) to scope a fan-out to the relevant
+   * team — e.g. a Team-A branch land no longer wakes Team-B agents sharing the main checkout (the
+   * epic #440 dogfooded symptom). Deliberately permissive at the edges: a teamless agent
+   * (`a.teamId` unset) and a teamless notification (`scope.teamId` unset) both ABSTAIN, so solo/
+   * unteamed work and cross-team-by-default notifications keep their prior broadcast reach.
+   */
+  differentTeam: (): NotificationRule => ({
+    name: "different-team",
+    evaluate: (a, { scope }) => (scope.teamId && a.teamId && a.teamId !== scope.teamId ? "suppress" : "abstain"),
+  }),
+  /**
+   * Agents working IN the repo's main checkout (cwd === repoRoot) — the `agentsOnMain` fan-out.
+   * Defaults match the legacy behavior exactly: online-only (a stale main session needs no wake)
+   * and author-excluded (the author gets its own store-ahead copy via the `author` rule).
+   */
+  onRepoRoot: (opts: { onlineOnly?: boolean; excludeAuthor?: boolean } = { onlineOnly: true, excludeAuthor: true }): NotificationRule => ({
+    name: "on-repo-root",
+    evaluate: (a, { scope, now }) => {
+      if (!scope.repoRoot || a.meta?.cwd !== scope.repoRoot) return "abstain";
+      if (opts.excludeAuthor && scope.author && a.id === scope.author) return "abstain";
+      if (opts.onlineOnly && !isAgentOnline(a, now)) return "abstain";
+      return "deliver";
+    },
+  }),
+} as const;
+
+/**
+ * The candidate pool for rule evaluation: every registered agent EXCEPT the pseudo-identities
+ * (`system`/`user`) and channel agents, which are never wake-notification recipients. Offline agents
+ * stay IN the pool deliberately — a store-ahead rule (author/spawn-parent) must be able to select an
+ * offline target; per-rule `onlineOnly` gates the cases that need liveness (e.g. on-repo-root fan-out).
+ */
+export function audienceCandidates(): AgentCard[] {
+  return listAgents().filter(
+    (a) => a.id !== "system" && a.id !== "user" && a.kind !== "channel" && a.meta?.kind !== "channel",
+  );
+}
+
+/**
+ * Evaluate an ordered rule list against each candidate. Decision fold: a later non-abstain decision
+ * overrides an earlier one (last-wins), so subscription overrides — appended after the defaults —
+ * can suppress a default deliver (opt-out/mute) or deliver a default-suppress (opt-in). The matched
+ * rule recorded is whichever rule set the final decision. Only `deliver` agents make the audience.
+ */
+export function evaluateAudience(
+  rules: NotificationRule[],
+  ctx: NotificationRuleContext,
+  candidates: AgentCard[],
+): AudienceMember[] {
+  const audience: AudienceMember[] = [];
+  for (const agent of candidates) {
+    let decision: RuleDecision = "abstain";
+    let matchedRule = "";
+    for (const rule of rules) {
+      const d = rule.evaluate(agent, ctx);
+      if (d !== "abstain") {
+        decision = d;
+        matchedRule = rule.name;
+      }
+    }
+    if (decision === "deliver") audience.push({ agentId: agent.id, matchedRule });
+  }
+  return audience;
+}
+
+// Per-type active rule compositions. Production defaults are mirrored in `defaultAudienceRegistry`
+// so the test reset seam can clear transient overrides without losing import-time registrations.
+const audienceRegistry = new Map<NotificationType, NotificationRule[]>();
+const defaultAudienceRegistry = new Map<NotificationType, NotificationRule[]>();
+
+/** Register (or replace) the active audience rules for a notification type. Tests use this for
+ *  transient compositions; production type modules should use registerDefaultAudienceRules. */
+export function registerAudienceRules(type: NotificationType, rules: NotificationRule[]): void {
+  audienceRegistry.set(type, rules);
+}
+
+/** Register (or replace) the production default audience rules for a notification type. Called at
+ *  module init by each type's migration. Idempotent — re-registering replaces, so hot reload is safe. */
+export function registerDefaultAudienceRules(type: NotificationType, rules: NotificationRule[]): void {
+  defaultAudienceRegistry.set(type, rules);
+  audienceRegistry.set(type, rules);
+}
+
+// #443 subscription seam: opt-in / opt-out / mute become override rules injected here. They run AFTER
+// a type's default rules so they win the last-wins fold. Empty until #443 wires a subscription store.
+let subscriptionRules: NotificationRule[] = [];
+
+/** #443 hook: install the subscription override rules (opt-in/opt-out/mute). Pass [] to clear. */
+export function setSubscriptionRules(rules: NotificationRule[]): void {
+  subscriptionRules = rules;
+}
+
+/** The effective ordered rule list for a type: its registered defaults, then subscription overrides. */
+export function audienceRulesFor(type: NotificationType): NotificationRule[] {
+  const defaults = audienceRegistry.get(type);
+  if (!defaults) return [];
+  return subscriptionRules.length === 0 ? defaults : [...defaults, ...subscriptionRules];
+}
+
+/**
+ * Resolve the concrete recipients for a notification from its scope, via the registered rules. Returns
+ * `[]` for an unregistered (not-yet-rule-driven) type — callers fall back to explicit recipients.
+ * This is what #444 will call in place of the hand-rolled `agentsOnMain` + author selection.
+ */
+export function resolveAudience(type: NotificationType, scope: NotificationScope, now: number = Date.now()): AudienceMember[] {
+  const rules = audienceRulesFor(type);
+  if (rules.length === 0) return [];
+  return evaluateAudience(rules, { type, scope, now }, audienceCandidates());
+}
+
+/** Test seam: clear the per-type registry and subscription rules between tests. */
+export function __resetAudienceRules(): void {
+  audienceRegistry.clear();
+  for (const [type, rules] of defaultAudienceRegistry) audienceRegistry.set(type, rules);
+  subscriptionRules = [];
+}

package/src/notify.ts

@@ -17,6 +17,14 @@ interface SystemNotifyOptions {
    * (steward task assignments, conflict handoffs).
    */
   replyExpected?: boolean;
+  /**
+   * #451 — TTL in seconds after which the message is stale and must not wake a recipient (the poll
+   * path drops it). Omit to use sendMessage's defaults (a moderate TTL for fire-and-forget fan-out,
+   * none for direct DMs / obligations / claimable). routeNotification sets this per notification type:
+   * a number for ephemeral types, explicit `null` for store-ahead types (authoritative never-expire,
+   * suppressing the fan-out default so the router's per-type decision wins).
+   */
+  maxAgeSeconds?: number | null;
 }
 
 /**
@@ -33,6 +41,7 @@ export function notifySystemMessage(to: string, opts: SystemNotifyOptions): Mess
     body: opts.body,
     payload: opts.payload,
     replyExpected: opts.replyExpected,
+    maxAgeSeconds: opts.maxAgeSeconds,
   });
   emitNewMessage(msg);
   return msg;