agent-relay-server 0.58.0 → 0.60.0

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;

package/src/project-instructions.ts

@@ -0,0 +1,176 @@
+// Project instruction projection (#409) — the relay-owned replacement for host
+// CLAUDE.md bleed-in. Given a resolved project, render its `rule`/`fact` entries
+// (own + inherited `contains`-ancestor entries from #406's cascade) into a compact,
+// DETERMINISTIC, size-bounded instruction block that can be prepended to a spawned
+// agent's systemPromptAppend.
+//
+// ADDITIVE-FROM-EMPTY (#403 decision 4): this composer builds the instruction world
+// from NOTHING and ADDS project knowledge. It NEVER reads host CLAUDE.md or subtracts
+// from it. Going fully vanilla later = simply not including host-derived (`ingested`)
+// content — a policy switch here, zero schema/composer change. `project_entries.source`
+// is that lever: the included-source set is a policy PARAMETER, and the `vanilla`
+// policy includes `manual`+`promoted` while excluding `ingested`.
+import { resolveProjectEntries } from "./db";
+import { PROJECT_ENTRY_SOURCES, type Project, type ProjectEntryKind, type ProjectEntrySource, type ResolvedProjectEntry } from "./types";
+
+/** Named source policies — THE additive-from-empty lever (#403 decision 4).
+ *   `all`     — every source (manual + promoted + ingested host-CLAUDE.md content).
+ *   `vanilla` — manual + promoted only; EXCLUDES `ingested`, so a vanilla agent gets
+ *               zero host-CLAUDE.md bleed-in while still receiving relay-native knowledge. */
+export const PROJECT_INSTRUCTION_SOURCE_SETS = {
+  all: PROJECT_ENTRY_SOURCES,
+  vanilla: ["manual", "promoted"],
+} as const satisfies Record<string, readonly ProjectEntrySource[]>;
+
+export const PROJECT_INSTRUCTION_POLICY_NAMES = ["all", "vanilla"] as const;
+export type ProjectInstructionPolicyName = (typeof PROJECT_INSTRUCTION_POLICY_NAMES)[number];
+
+/** Per-spawn projection request. Presence (a non-undefined value on the spawn input)
+ * means "project the preamble"; absence means OFF. `policy` selects the source set. */
+export interface ProjectInstructionPolicy {
+  policy?: ProjectInstructionPolicyName;
+}
+
+export interface ComposeProjectInstructionsOptions {
+  /** Named policy selecting the included source set. Default `all`. */
+  policy?: ProjectInstructionPolicyName;
+  /** Explicit source set; overrides `policy` when given (the low-level lever). */
+  includeSources?: readonly ProjectEntrySource[];
+  /** Entry kinds rendered, in this order. Default `["rule", "fact"]` (the directive +
+   * truth kinds; `decision`/`memory` are log/scratch, not preamble material). */
+  includeKinds?: readonly ProjectEntryKind[];
+  /** Merge transitive `contains`-ancestor entries (#406 cascade). Default true. */
+  includeInherited?: boolean;
+  /** Hard byte cap on the rendered block (UTF-8). Default 8192. The block is truncated
+   * deterministically (lowest-priority entries dropped first) to stay within it. */
+  maxBytes?: number;
+}
+
+const DEFAULT_KINDS: readonly ProjectEntryKind[] = ["rule", "fact"];
+const DEFAULT_MAX_BYTES = 8192;
+const TRUNCATION_NOTICE = "_(… additional project entries omitted to fit the instruction budget.)_";
+
+const KIND_HEADINGS: Record<ProjectEntryKind, string> = {
+  rule: "Rules",
+  fact: "Facts",
+  decision: "Decisions",
+  memory: "Memory",
+};
+
+function byteLen(value: string): number {
+  return Buffer.byteLength(value, "utf8");
+}
+
+/** Stable dedup key — same kind + same (trimmed) title + body collapses to one entry.
+ * Uses NUL separators so distinct fields can't collide by concatenation. */
+function dedupKey(entry: ResolvedProjectEntry): string {
+  return `${entry.kind}\u0000${entry.title.trim()}\u0000${(entry.body ?? "").trim()}`;
+}
+
+function entryLine(entry: ResolvedProjectEntry): string {
+  const body = entry.body?.trim();
+  const tag = entry.inherited ? " _(inherited)_" : "";
+  return body ? `- ${entry.title.trim()}: ${body}${tag}` : `- ${entry.title.trim()}${tag}`;
+}
+
+/**
+ * Render a project's instruction block. Deterministic: ordering is by kind (in
+ * `includeKinds` order), then own-before-inherited, then title (code-point), then id —
+ * fully independent of DB row timestamps. Output is deduped and hard-bounded to
+ * `maxBytes`. Returns "" when no entry survives the source/kind filter (the caller then
+ * leaves systemPromptAppend untouched, so the spawn stays byte-identical).
+ */
+export function composeProjectInstructions(
+  project: Pick<Project, "id" | "slug" | "title">,
+  opts: ComposeProjectInstructionsOptions = {},
+): string {
+  const kinds = opts.includeKinds ?? DEFAULT_KINDS;
+  const kindRank = new Map<ProjectEntryKind, number>(kinds.map((kind, index) => [kind, index]));
+  const sources = new Set<ProjectEntrySource>(
+    opts.includeSources ?? PROJECT_INSTRUCTION_SOURCE_SETS[opts.policy ?? "all"],
+  );
+  const includeInherited = opts.includeInherited !== false;
+  const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+
+  const resolved = resolveProjectEntries(project.id, { includeInherited });
+  const filtered = resolved.filter((entry) => kindRank.has(entry.kind) && sources.has(entry.source));
+
+  // Deterministic ordering, independent of DB row order/timestamps.
+  filtered.sort((a, b) => {
+    const byKind = (kindRank.get(a.kind) ?? 0) - (kindRank.get(b.kind) ?? 0);
+    if (byKind !== 0) return byKind;
+    const byInherited = Number(a.inherited) - Number(b.inherited); // own (false) first
+    if (byInherited !== 0) return byInherited;
+    const ta = a.title.trim();
+    const tb = b.title.trim();
+    if (ta !== tb) return ta < tb ? -1 : 1;
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+  });
+
+  // Dedup, own-wins (own sorts before inherited above).
+  const seen = new Set<string>();
+  const deduped: ResolvedProjectEntry[] = [];
+  for (const entry of filtered) {
+    const key = dedupKey(entry);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    deduped.push(entry);
+  }
+  if (deduped.length === 0) return "";
+
+  // Greedy size-bounded render. Entries are contiguous by kind (primary sort key), so a
+  // per-kind `## heading` is emitted once when the first entry of that kind is included.
+  const header = `# Project knowledge: ${project.title?.trim() || project.slug}`;
+  const budget = maxBytes - byteLen(`\n\n${TRUNCATION_NOTICE}`);
+  const lines: string[] = [header];
+  let bytes = byteLen(header);
+  let lastKind: ProjectEntryKind | null = null;
+  let truncated = false;
+
+  for (const entry of deduped) {
+    const segments: string[] = [];
+    if (entry.kind !== lastKind) segments.push("", `## ${KIND_HEADINGS[entry.kind]}`);
+    segments.push(entryLine(entry));
+    const addition = `\n${segments.join("\n")}`;
+    if (bytes + byteLen(addition) > budget) {
+      truncated = true;
+      break;
+    }
+    lines.push(...segments);
+    bytes += byteLen(addition);
+    lastKind = entry.kind;
+  }
+
+  if (truncated) lines.push("", TRUNCATION_NOTICE);
+  let out = lines.join("\n");
+  // Safety net: guarantee the hard byte cap even if the header + first entry overshoot.
+  if (byteLen(out) > maxBytes) {
+    out = Buffer.from(out, "utf8").subarray(0, maxBytes).toString("utf8");
+  }
+  return out;
+}
+
+/**
+ * Parse a spawn-transport's `projectInstructions` wire value into the normalized policy
+ * (or undefined = OFF). Shared by the MCP and HTTP spawn paths so they cannot drift.
+ *   - undefined / null / false → undefined (OFF)
+ *   - true                     → {} (ON, default policy)
+ *   - { policy }               → validated policy
+ * Throws `onInvalid(message)` for a malformed shape or unknown policy name.
+ */
+export function parseProjectInstructions(
+  value: unknown,
+  onInvalid: (message: string) => Error,
+): ProjectInstructionPolicy | undefined {
+  if (value === undefined || value === null || value === false) return undefined;
+  if (value === true) return {};
+  if (typeof value !== "object") {
+    throw onInvalid("projectInstructions must be a boolean or { policy } object");
+  }
+  const policy = (value as Record<string, unknown>).policy;
+  if (policy === undefined) return {};
+  if (typeof policy !== "string" || !PROJECT_INSTRUCTION_POLICY_NAMES.includes(policy as ProjectInstructionPolicyName)) {
+    throw onInvalid(`projectInstructions.policy must be one of: ${PROJECT_INSTRUCTION_POLICY_NAMES.join(", ")}`);
+  }
+  return { policy: policy as ProjectInstructionPolicyName };
+}

package/src/reviewer-pipeline.ts

@@ -3,7 +3,7 @@ import { planSend } from "./agent-ref";
 import { createCommand } from "./commands-db";
 import { getSpawnPolicy } from "./config-store";
 import { getLifecycleManager } from "./lifecycle-manager";
-import { notifySystemMessage } from "./notify";
+import { routeNotification } from "./notification-router";
 import { getWorkspace, listAgents, patchWorkspaceMetadata, updateWorkspaceStatus } from "./db";
 import type { Command, WorkspaceMergePreview, WorkspaceRecord } from "./types";
 
@@ -60,26 +60,33 @@ export function handleReviewerMergeResult(command: Command, result: Record<strin
   });
   if (!updated) return false;
 
-  notifySystemMessage(target, {
-    subject: `Review requested: ${workspace.branch ?? workspace.id}`,
-    body: [
-      `Review PR ${prUrl ?? `#${prNumber ?? "unknown"}`} for workspace \`${workspace.id}\`.`,
-      `Repo: ${workspace.repoRoot}`,
-      workspace.branch ? `Branch: ${workspace.branch}` : undefined,
-      workspace.baseRef ? `Base: ${workspace.baseRef}` : undefined,
-      compareRef ? `Compare: ${compareRef}` : undefined,
-      "Approve the PR to let Relay arm GitHub auto-merge, or request changes to send it back to the workspace owner.",
-    ].filter(Boolean).join("\n"),
-    payload: {
-      kind: "workspace.review-request",
-      workspaceId: workspace.id,
-      repoRoot: workspace.repoRoot,
-      worktreePath: workspace.worktreePath,
-      branch: workspace.branch,
-      baseRef: workspace.baseRef,
-      prUrl,
-      prNumber,
-      compareRef,
+  // Obligation (ttl null by type default): a review request must reach the reviewer even if they're
+  // offline a while — it's not a bystander notice.
+  routeNotification({
+    type: "workspace.review_request",
+    scope: { workspaceId: workspace.id, repoRoot: workspace.repoRoot },
+    recipients: [target],
+    message: {
+      subject: `Review requested: ${workspace.branch ?? workspace.id}`,
+      body: [
+        `Review PR ${prUrl ?? `#${prNumber ?? "unknown"}`} for workspace \`${workspace.id}\`.`,
+        `Repo: ${workspace.repoRoot}`,
+        workspace.branch ? `Branch: ${workspace.branch}` : undefined,
+        workspace.baseRef ? `Base: ${workspace.baseRef}` : undefined,
+        compareRef ? `Compare: ${compareRef}` : undefined,
+        "Approve the PR to let Relay arm GitHub auto-merge, or request changes to send it back to the workspace owner.",
+      ].filter(Boolean).join("\n"),
+      payload: {
+        kind: "workspace.review-request",
+        workspaceId: workspace.id,
+        repoRoot: workspace.repoRoot,
+        worktreePath: workspace.worktreePath,
+        branch: workspace.branch,
+        baseRef: workspace.baseRef,
+        prUrl,
+        prNumber,
+        compareRef,
+      },
     },
   });
   if (policyName) getLifecycleManager().onMessageForPolicy(policyName);
@@ -172,26 +179,33 @@ function notifyReviewChangesRequested(
 ): string | undefined {
   const target = workspace.ownerAgentId;
   if (!target) return undefined;
-  notifySystemMessage(target, {
-    subject: `Changes requested: ${workspace.branch ?? workspace.id}`,
-    body: [
-      `The reviewer requested changes on ${prUrl ?? `PR #${prNumber ?? "unknown"}`}.`,
-      `Workspace \`${workspace.id}\` remains in review_requested.`,
-      preview.baseRef ? `Base: ${preview.baseRef}` : undefined,
-    ].filter(Boolean).join("\n"),
-    payload: {
-      kind: "workspace.review-changes-requested",
-      workspaceId: workspace.id,
-      repoRoot: workspace.repoRoot,
-      worktreePath: workspace.worktreePath,
-      branch: workspace.branch,
-      baseRef: workspace.baseRef,
-      prUrl,
-      prNumber,
-      reviewDecision: preview.reviewDecision,
-      statusCheckRollup: preview.statusCheckRollup,
+  // Durable (ttl null): the owner must learn changes were requested on THEIR workspace even after
+  // being offline — store-ahead, not a freshness-gated bystander notice.
+  routeNotification({
+    type: "workspace.review_changes_requested",
+    scope: { workspaceId: workspace.id, repoRoot: workspace.repoRoot, author: target },
+    recipients: [target],
+    message: {
+      subject: `Changes requested: ${workspace.branch ?? workspace.id}`,
+      body: [
+        `The reviewer requested changes on ${prUrl ?? `PR #${prNumber ?? "unknown"}`}.`,
+        `Workspace \`${workspace.id}\` remains in review_requested.`,
+        preview.baseRef ? `Base: ${preview.baseRef}` : undefined,
+      ].filter(Boolean).join("\n"),
+      payload: {
+        kind: "workspace.review-changes-requested",
+        workspaceId: workspace.id,
+        repoRoot: workspace.repoRoot,
+        worktreePath: workspace.worktreePath,
+        branch: workspace.branch,
+        baseRef: workspace.baseRef,
+        prUrl,
+        prNumber,
+        reviewDecision: preview.reviewDecision,
+        statusCheckRollup: preview.statusCheckRollup,
+      },
+      replyExpected: false,
     },
-    replyExpected: false,
   });
   return target;
 }