agent-relay-server 0.58.0 → 0.60.0

package/src/db/stats.ts

@@ -135,20 +135,35 @@ export const ANALYTICS_PERIODS = {
 
 export type AnalyticsPeriod = keyof typeof ANALYTICS_PERIODS;
 
-// Message → category, the ONE place this mapping lives (server-side SQL). Order is
-// significant: a claimable/system/pair/channel message is classified as such even
-// when it is also a reply; only an otherwise-plain reply counts as "Replies".
-export const ANALYTICS_CATEGORIES = ["Messages", "Replies", "Work items", "System", "Pair", "Channel"] as const;
-export type AnalyticsCategory = (typeof ANALYTICS_CATEGORIES)[number];
-export const ANALYTICS_CATEGORY_SQL = `
+// ─── Analytics taxonomy ─────────────────────────────────────────────────────
+// The relay carries three distinct streams of activity, and analytics keeps them
+// SEPARATE rather than collapsing into one "messages" count (which is ~94%
+// session-mirror noise on a busy relay — see the work layer below):
+//   1. Conversation — real inter-agent / human messaging (chat, replies, channel, pair, work items)
+//   2. Work — session-mirror cognition: tool calls, reasoning, narration, responses
+//   3. Fleet — agent registrations/spawns + per-agent activity (NOT online/offline:
+//      agents start, work, and shut down constantly — point-in-time status is noise here)
+
+// Conversation categories. Order is significant: a claimable/channel/pair message
+// is classified as such even when it is also a reply; only an otherwise-plain reply
+// counts as "Replies". Session/control/system rows are EXCLUDED (they're streams 2/mechanical).
+export const CONVERSATION_CATEGORIES = ["Chat", "Replies", "Channel", "Pair", "Work items"] as const;
+export type ConversationCategory = (typeof CONVERSATION_CATEGORIES)[number];
+const CONVERSATION_CATEGORY_SQL = `
   CASE
     WHEN claimable = 1 THEN 'Work items'
-    WHEN kind = 'system' OR from_agent = 'system' THEN 'System'
-    WHEN kind = 'pair' THEN 'Pair'
     WHEN kind = 'channel.event' THEN 'Channel'
+    WHEN kind = 'pair' THEN 'Pair'
     WHEN reply_to IS NOT NULL THEN 'Replies'
-    ELSE 'Messages'
+    ELSE 'Chat'
   END`;
+// Only real messaging — excludes the session-mirror lane and mechanical/system rows.
+const CONVERSATION_FILTER = `kind NOT IN ('session','control','system') AND from_agent != 'system'`;
+
+// Session-mirror event sub-types we surface as the "agent work" composition. (prompt
+// is counted in the user-interaction stream; notice is mechanical chatter.)
+export const WORK_TYPES = ["tool", "reasoning", "narration", "response"] as const;
+export type WorkType = (typeof WORK_TYPES)[number];
 
 export interface AnalyticsData {
   period: AnalyticsPeriod;
@@ -156,52 +171,196 @@ export interface AnalyticsData {
   now: number;
   bucketMs: number;
   bucketCount: number;
-  // Per-bucket category counts, oldest → newest, length === bucketCount.
-  buckets: Array<{ start: number; counts: Record<AnalyticsCategory, number> }>;
-  // Category totals over the whole period (powers the breakdown donut).
-  categories: Record<AnalyticsCategory, number>;
-  // Busiest-hours grid: heatmap[dayOfWeek 0=Sun][hour 0-23], in server-local time.
+  // 1. Conversation — real messaging volume, per-bucket (oldest→newest) + totals.
+  conversation: {
+    buckets: Array<{ start: number; counts: Record<ConversationCategory, number> }>;
+    totals: Record<ConversationCategory, number>;
+    total: number;
+  };
+  // 2. Work — session-mirror cognition: per-bucket type counts, totals, tool leaderboard, turn count.
+  work: {
+    buckets: Array<{ start: number; counts: Record<WorkType, number> }>;
+    totals: Record<WorkType, number>;
+    topTools: Array<{ name: string; count: number }>;
+    turns: number;
+    toolCalls: number;
+  };
+  // 3. User interaction — human prompts, reply rate, and agent reply latency (median is
+  // the headline; avg is tail-inflated by agents that were away mid-conversation).
+  user: {
+    prompts: number;
+    replied: number;
+    replyRate: number; // 0..1
+    latencyMs: { median: number; avg: number; p90: number } | null;
+    buckets: Array<{ start: number; prompts: number }>;
+  };
+  // 4. Fleet — activity-based, never online/offline. Registrations (spawns) over time,
+  // how many were agent-spawned, distinct active agents, and a per-agent leaderboard.
+  fleet: {
+    activeAgents: number;
+    registrations: number;
+    spawnedByAgent: number;
+    buckets: Array<{ start: number; registrations: number }>;
+    leaderboard: Array<{ id: string; label: string | null; turns: number; toolCalls: number; messages: number }>;
+  };
+  // Busiest-hours grid: heatmap[dayOfWeek 0=Sun][hour 0-23], server-local time, all activity.
   heatmap: number[][];
-  totalMessages: number;
   totalReactions: number;
 }
 
-export function emptyCategoryCounts(): Record<AnalyticsCategory, number> {
-  return { Messages: 0, Replies: 0, "Work items": 0, System: 0, Pair: 0, Channel: 0 };
+function emptyConversationCounts(): Record<ConversationCategory, number> {
+  return { Chat: 0, Replies: 0, Channel: 0, Pair: 0, "Work items": 0 };
+}
+function emptyWorkCounts(): Record<WorkType, number> {
+  return { tool: 0, reasoning: 0, narration: 0, response: 0 };
+}
+
+// Percentile over an unsorted list of numbers (linear interpolation-free nearest-rank).
+function percentile(sorted: number[], p: number): number {
+  if (sorted.length === 0) return 0;
+  const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil((p / 100) * sorted.length) - 1));
+  return sorted[idx] ?? 0;
 }
 
 export function getAnalytics(period: AnalyticsPeriod, now: number = Date.now()): AnalyticsData {
   const { ms, buckets: bucketCount } = ANALYTICS_PERIODS[period] ?? ANALYTICS_PERIODS["24h"];
   const start = now - ms;
   const bucketMs = ms / bucketCount;
+  const db = getDb();
+  // created_at in (start, now] keeps the floored bucket index in [0, bucketCount).
+  const clampIdx = (bucket: number) => Math.min(Math.max(bucket, 0), bucketCount - 1);
+  const bucketStarts = Array.from({ length: bucketCount }, (_, i) => start + i * bucketMs);
 
-  const buckets = Array.from({ length: bucketCount }, (_, i) => ({
-    start: start + i * bucketMs,
-    counts: emptyCategoryCounts(),
-  }));
-  const categories = emptyCategoryCounts();
-
-  // One pass: bucket index × category counts. CAST floors toward zero; created_at
-  // in (start, now] keeps the index in [0, bucketCount).
-  const volumeRows = getDb()
+  // ── 1. Conversation: real messaging volume ──
+  const conversationBuckets = bucketStarts.map((s) => ({ start: s, counts: emptyConversationCounts() }));
+  const conversationTotals = emptyConversationCounts();
+  const convRows = db
     .query(
-      `SELECT CAST((created_at - ?) / ? AS INTEGER) AS bucket, ${ANALYTICS_CATEGORY_SQL} AS category, COUNT(*) AS c
-       FROM messages WHERE created_at > ? AND created_at <= ? GROUP BY bucket, category`,
+      `SELECT CAST((created_at - ?) / ? AS INTEGER) AS bucket, ${CONVERSATION_CATEGORY_SQL} AS category, COUNT(*) AS c
+       FROM messages WHERE created_at > ? AND created_at <= ? AND ${CONVERSATION_FILTER} GROUP BY bucket, category`,
     )
-    .all(start, bucketMs, start, now) as Array<{ bucket: number; category: AnalyticsCategory; c: number }>;
-  for (const row of volumeRows) {
-    const idx = Math.min(Math.max(row.bucket, 0), bucketCount - 1);
-    const bucket = buckets[idx];
+    .all(start, bucketMs, start, now) as Array<{ bucket: number; category: ConversationCategory; c: number }>;
+  for (const row of convRows) {
+    const bucket = conversationBuckets[clampIdx(row.bucket)];
     if (bucket && row.category in bucket.counts) {
       bucket.counts[row.category] += row.c;
-      categories[row.category] += row.c;
+      conversationTotals[row.category] += row.c;
+    }
+  }
+  const conversationTotal = Object.values(conversationTotals).reduce((sum, v) => sum + v, 0);
+
+  // ── 2. Work: session-mirror cognition ──
+  const workBuckets = bucketStarts.map((s) => ({ start: s, counts: emptyWorkCounts() }));
+  const workTotals = emptyWorkCounts();
+  const workRows = db
+    .query(
+      `SELECT CAST((created_at - ?) / ? AS INTEGER) AS bucket,
+              json_extract(payload, '$.session.type') AS wtype, COUNT(*) AS c
+       FROM messages WHERE created_at > ? AND created_at <= ? AND kind = 'session'
+         AND json_extract(payload, '$.session.type') IN ('tool','reasoning','narration','response')
+       GROUP BY bucket, wtype`,
+    )
+    .all(start, bucketMs, start, now) as Array<{ bucket: number; wtype: WorkType; c: number }>;
+  for (const row of workRows) {
+    const bucket = workBuckets[clampIdx(row.bucket)];
+    if (bucket && row.wtype in bucket.counts) {
+      bucket.counts[row.wtype] += row.c;
+      workTotals[row.wtype] += row.c;
     }
   }
-  const totalMessages = Object.values(categories).reduce((sum, v) => sum + v, 0);
+  const topTools = db
+    .query(
+      `SELECT json_extract(payload, '$.session.label') AS name, COUNT(*) AS count
+       FROM messages WHERE created_at > ? AND created_at <= ? AND kind = 'session'
+         AND json_extract(payload, '$.session.type') = 'tool'
+         AND json_extract(payload, '$.session.label') IS NOT NULL
+       GROUP BY name ORDER BY count DESC LIMIT 12`,
+    )
+    .all(start, now) as Array<{ name: string; count: number }>;
+  const turns = (
+    db
+      .query(
+        `SELECT COUNT(DISTINCT json_extract(payload, '$.session.turnId')) AS c
+         FROM messages WHERE created_at > ? AND created_at <= ? AND kind = 'session'
+           AND json_extract(payload, '$.session.turnId') IS NOT NULL`,
+      )
+      .get(start, now) as { c: number }
+  ).c;
+
+  // ── 3. User interaction: human prompts + agent reply latency ──
+  const userBuckets = bucketStarts.map((s) => ({ start: s, prompts: 0 }));
+  const promptRows = db
+    .query(
+      `SELECT CAST((created_at - ?) / ? AS INTEGER) AS bucket, COUNT(*) AS c
+       FROM messages WHERE created_at > ? AND created_at <= ? AND from_agent = 'user' GROUP BY bucket`,
+    )
+    .all(start, bucketMs, start, now) as Array<{ bucket: number; c: number }>;
+  let prompts = 0;
+  for (const row of promptRows) {
+    const bucket = userBuckets[clampIdx(row.bucket)];
+    if (bucket) bucket.prompts += row.c;
+    prompts += row.c;
+  }
+  // Latency = first threaded reply from a non-user agent, in (start, now] by the prompt's time.
+  const latencyRows = db
+    .query(
+      `SELECT (r.created_at - u.created_at) AS delta
+       FROM messages u JOIN messages r ON r.reply_to = u.id
+       WHERE u.from_agent = 'user' AND r.from_agent != 'user'
+         AND u.created_at > ? AND u.created_at <= ? AND r.created_at >= u.created_at`,
+    )
+    .all(start, now) as Array<{ delta: number }>;
+  const deltas = latencyRows.map((r) => r.delta).sort((a, b) => a - b);
+  const replied = deltas.length;
+  const latencyMs =
+    replied > 0
+      ? {
+          median: percentile(deltas, 50),
+          avg: Math.round(deltas.reduce((sum, d) => sum + d, 0) / replied),
+          p90: percentile(deltas, 90),
+        }
+      : null;
+
+  // ── 4. Fleet: registrations (spawns) over time + per-agent leaderboard ──
+  const fleetBuckets = bucketStarts.map((s) => ({ start: s, registrations: 0 }));
+  const regRows = db
+    .query(
+      `SELECT CAST((created_at - ?) / ? AS INTEGER) AS bucket, COUNT(*) AS c,
+              SUM(CASE WHEN spawned_by IS NOT NULL THEN 1 ELSE 0 END) AS spawned
+       FROM agents WHERE created_at > ? AND created_at <= ? GROUP BY bucket`,
+    )
+    .all(start, bucketMs, start, now) as Array<{ bucket: number; c: number; spawned: number }>;
+  let registrations = 0;
+  let spawnedByAgent = 0;
+  for (const row of regRows) {
+    const bucket = fleetBuckets[clampIdx(row.bucket)];
+    if (bucket) bucket.registrations += row.c;
+    registrations += row.c;
+    spawnedByAgent += row.spawned ?? 0;
+  }
+  const activeAgents = (
+    db
+      .query(
+        `SELECT COUNT(DISTINCT from_agent) AS c FROM messages
+         WHERE created_at > ? AND created_at <= ? AND from_agent NOT IN ('system','user')`,
+      )
+      .get(start, now) as { c: number }
+  ).c;
+  const leaderboard = db
+    .query(
+      `SELECT m.from_agent AS id, a.label AS label,
+              COUNT(DISTINCT CASE WHEN m.kind = 'session' THEN json_extract(m.payload, '$.session.turnId') END) AS turns,
+              SUM(CASE WHEN m.kind = 'session' AND json_extract(m.payload, '$.session.type') = 'tool' THEN 1 ELSE 0 END) AS toolCalls,
+              SUM(CASE WHEN m.kind != 'session' THEN 1 ELSE 0 END) AS messages
+       FROM messages m LEFT JOIN agents a ON a.id = m.from_agent
+       WHERE m.created_at > ? AND m.created_at <= ? AND m.from_agent NOT IN ('system','user')
+       GROUP BY m.from_agent ORDER BY (toolCalls + messages) DESC LIMIT 10`,
+    )
+    .all(start, now) as Array<{ id: string; label: string | null; turns: number; toolCalls: number; messages: number }>;
 
-  // Busiest-hours heatmap (day-of-week × hour), server-local time.
+  // ── Busiest-hours heatmap (all activity, day-of-week × hour, server-local time) ──
   const heatmap: number[][] = Array.from({ length: 7 }, () => new Array(24).fill(0));
-  const heatRows = getDb()
+  const heatRows = db
     .query(
       `SELECT CAST(strftime('%w', created_at / 1000, 'unixepoch', 'localtime') AS INTEGER) AS dow,
               CAST(strftime('%H', created_at / 1000, 'unixepoch', 'localtime') AS INTEGER) AS hour, COUNT(*) AS c
@@ -214,7 +373,7 @@ export function getAnalytics(period: AnalyticsPeriod, now: number = Date.now()):
   }
 
   const totalReactions = (
-    getDb()
+    db
       .query(
         `SELECT COUNT(*) AS c FROM message_reactions r
          JOIN messages m ON m.id = r.message_id WHERE m.created_at > ? AND m.created_at <= ?`,
@@ -222,7 +381,19 @@ export function getAnalytics(period: AnalyticsPeriod, now: number = Date.now()):
       .get(start, now) as { c: number }
   ).c;
 
-  return { period, start, now, bucketMs, bucketCount, buckets, categories, heatmap, totalMessages, totalReactions };
+  return {
+    period,
+    start,
+    now,
+    bucketMs,
+    bucketCount,
+    conversation: { buckets: conversationBuckets, totals: conversationTotals, total: conversationTotal },
+    work: { buckets: workBuckets, totals: workTotals, topTools, turns, toolCalls: workTotals.tool },
+    user: { prompts, replied, replyRate: prompts > 0 ? replied / prompts : 0, latencyMs, buckets: userBuckets },
+    fleet: { activeAgents, registrations, spawnedByAgent, buckets: fleetBuckets, leaderboard },
+    heatmap,
+    totalReactions,
+  };
 }
 
 export function getHealth(now: number = Date.now()): HealthReport {

package/src/index.ts

@@ -10,6 +10,7 @@ import { getLifecycleManager } from "./lifecycle-manager";
 import { getCompactionWatch } from "./compaction-watch";
 import { getConfig, setConfig } from "./config-store";
 import { startConnectorStatusPoller } from "./connectors";
+import { installNotificationSubscriptionRule } from "./db/notification-subscriptions";
 import { startPlanLiveBindings } from "./services/plan-live-bindings";
 import { resolve, sep } from "path";
 import { gzipSync, brotliCompressSync, constants as zlibConstants } from "node:zlib";
@@ -74,6 +75,7 @@ function startServer(): void {
 
   assertSafeNetworkConfig(HOST);
   initDb(DB_PATH);
+  installNotificationSubscriptionRule();
   startPlanLiveBindings();
   getLifecycleManager().start();
   getCompactionWatch().start();

package/src/maintenance.ts

@@ -39,7 +39,7 @@ import type { WorkspaceMergePreview, WorkspaceRecord, WorkspaceStatus } from "./
 import { requestWorkspaceMerge } from "./workspace-merge";
 import { reconcileLandedWorkspace } from "./branch-landed";
 import { isAwaitingReviewerApproval } from "./reviewer-pipeline";
-import { preparePrCompletionScan } from "./workspace-pr-completion";
+import { preparePrCompletionScan, reconcileLandedPr } from "./workspace-pr-completion";
 import { notifyAgentOffline } from "./agent-lifecycle-events";
 import { workspaceActiveClaim } from "./workspace-claim";
 import { reapOrphanedWorktrees } from "./workspace-orphans";
@@ -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 });
@@ -655,6 +661,7 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
   );
   const flagged: string[] = [], cleared: string[] = [], merged: string[] = [], notifiedStewards: string[] = [];
   const reviewerArmed: string[] = [], reviewerChangesRequested: string[] = [], relayPrMerged: string[] = [], relayPrWaiting: string[] = [];
+  const prRecycled: string[] = [];
 
   for (const ws of candidates) {
     const orch = orchestrators.find((candidate) => workspacePathWithinBase(ws.sourceCwd, candidate.baseDir));
@@ -687,6 +694,12 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
     // branch-landed.ts (#304).
     const landed = p.landed === true || p.prMerged === true;
     if (landed && LANDED_RECONCILE_STATUSES.has(ws.status)) {
+      // A PR-land merges asynchronously on the remote, outside the relay's land path. For a
+      // LIVE owner that means recycle (land-and-continue, #423); for a gone owner, finalize
+      // terminal `merged` (#304). `reconcileLandedPr` owns that split — see workspace-pr-completion.
+      const outcome = reconcileLandedPr(ws, p);
+      if (outcome.kind === "recycle") { emitCommand(outcome.command); prRecycled.push(ws.id); continue; }
+      if (outcome.kind === "wait") { relayPrWaiting.push(`${ws.id}:${outcome.reason}`); continue; }
       reconcileLandedWorkspace(ws, p);
       merged.push(ws.id);
       continue;
@@ -733,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 {
@@ -752,7 +771,7 @@ async function scanWorkspaceConflicts(): Promise<Record<string, unknown>> {
     }
   }
 
-  return { scanned: candidates.length, flagged, cleared, merged, notifiedStewards, reviewerArmed, reviewerChangesRequested, relayPrMerged, relayPrWaiting };
+  return { scanned: candidates.length, flagged, cleared, merged, prRecycled, notifiedStewards, reviewerArmed, reviewerChangesRequested, relayPrMerged, relayPrWaiting };
 }
 
 // Deterministic auto-land (Layer 0, #167/#207/#242): land conflict-free ready
@@ -841,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;
@@ -898,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"}.`,
@@ -913,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.`,
@@ -944,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,8 @@ 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";
 import { LAND_STRATEGIES, applyWorkspaceAction, waitForWorkspaceStatus, type WorkspaceAction } from "./workspace-actions";
@@ -310,6 +312,7 @@ const TOOLS: ToolDefinition[] = [
         prompt: { type: "string", description: "Initial task/message delivered to the agent on launch — spawn and hand it its first instruction in one call (no separate follow-up message needed)." },
         expectReply: { type: "boolean", description: "Require the worker to report back: it gets a pending reply obligation to you and CANNOT go idle until it delivers its result (which routes to your inbox and wakes you). Defaults true when you pass a prompt — set false for a true fire-and-forget worker that needn't report (e.g. one that only lands a branch)." },
         systemPromptAppend: { type: "string" },
+        projectInstructions: { type: "object", description: "#409 — project instruction projection (default OFF). When set, relay composes a knowledge preamble from the spawn cwd's resolved project (own + inherited entries) and prepends it to systemPromptAppend, instead of relying on host CLAUDE.md. `policy: \"all\"` includes ingested host content; `\"vanilla\"` excludes it (manual+promoted only). Omit to keep current behavior.", properties: { policy: { type: "string", enum: PROJECT_INSTRUCTION_POLICY_NAMES } }, additionalProperties: false },
         profile: { type: "string", description: "Agent profile name to apply (env, instructions, permissions, MCP/skills, spawn quota)." },
         tags: { type: "array", items: { type: "string" } },
         capabilities: { type: "array", items: { type: "string" } },
@@ -461,6 +464,7 @@ const TOOLS: ToolDefinition[] = [
   ...PLAN_TOOLS,
   ...BLACKBOARD_TOOLS,
   ...PROJECT_TOOLS,
+  ...NOTIFICATION_SUBSCRIPTION_TOOLS,
 ];
 
 export async function postMcp(req: Request): Promise<Response> {
@@ -577,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);
@@ -874,6 +879,7 @@ async function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknow
     prompt: optionalString(args.prompt, "prompt", 16_000),
     expectReply: typeof args.expectReply === "boolean" ? args.expectReply : undefined,
     systemPromptAppend: optionalString(args.systemPromptAppend, "systemPromptAppend", 64_000),
+    projectInstructions: parseProjectInstructions(args.projectInstructions, (m) => new ValidationError(m)),
     tags: optionalStringArray(args.tags, "tags"),
     capabilities: optionalStringArray(args.capabilities, "capabilities"),
     providerArgs: optionalStringArray(args.providerArgs, "providerArgs"),