agent-relay-server 0.91.4 → 0.93.0

package/src/notification-router.ts

@@ -1,7 +1,11 @@
 import { notifySystemMessage } from "./notify";
-import type { Message, MessageKind } from "./types";
+import { createActivityEvent, getAgent, getMessage } from "./db";
+import { subscriptionDecisionFor } from "./db/notification-subscriptions";
+import { notificationEnabledFor } from "./notification-settings-store";
+import type { Message, MessageKind, NotificationRoutingExplanation, NotificationRoutingPreview, NotificationRoutingRecipientInput } from "./types";
 import { DEFAULT_TTL_MS } from "./notification-types";
 import type { NotificationScope, NotificationType } from "./notification-types";
+import { resolveAudience } from "./notification-rules";
 
 export {
   DEFAULT_TTL_MS,
@@ -44,7 +48,7 @@ interface RouteNotificationInput {
    * 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>;
+  recipients?: Array<string | NotificationRoutingRecipientInput | undefined | null>;
   message: NotificationMessage;
   /**
    * #451 — time-to-live in ms from `emittedAt`, after which the notification is stale and must not
@@ -82,8 +86,8 @@ export function routeNotification(input: RouteNotificationInput): Message[] {
   // 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 [];
+  const preview = previewNotificationRouting(input);
+  if (preview.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
@@ -91,16 +95,166 @@ export function routeNotification(input: RouteNotificationInput): Message[] {
   // 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, {
+  return preview.recipients.map((routing) => {
+    const message = notifySystemMessage(routing.recipient, {
       subject: input.message.subject,
       body: input.message.body,
-      payload: input.message.payload,
+      payload: { ...(input.message.payload ?? {}), routing: compactRoutingExplanation(routing) },
       idempotencyKey: input.message.idempotencyKey,
       kind: input.message.kind,
       from: input.message.from,
       replyExpected: input.message.replyExpected,
       maxAgeSeconds,
-    }),
-  );
+    });
+    auditRoutingTrace(message, preview, maxAgeSeconds);
+    return message;
+  });
+}
+
+export function previewNotificationRouting(input: Pick<RouteNotificationInput, "type" | "scope" | "recipients">): NotificationRoutingPreview {
+  const candidates = normalizeRoutingRecipients(input);
+  const recipients: NotificationRoutingExplanation[] = [];
+  const suppressed: NotificationRoutingExplanation[] = [];
+  for (const candidate of candidates) {
+    const settingsEnabled = notificationRecipientEnabled(input.type, candidate.agentId, input.scope);
+    const subscriptionState = subscriptionStateFor(input.type, candidate.agentId, input.scope);
+    const matchedRule = candidate.matchedRule || inferMatchedRule(candidate.agentId, input.scope);
+    const explanation: NotificationRoutingExplanation = {
+      type: input.type,
+      recipient: candidate.agentId,
+      matchedRule,
+      reason: candidate.reason || routingReason(matchedRule, candidate.agentId, input.scope, subscriptionState, settingsEnabled),
+      scope: input.scope as Record<string, unknown>,
+      subscriptionState,
+      settingsEnabled,
+    };
+    if (settingsEnabled) recipients.push(explanation);
+    else suppressed.push({ ...explanation, matchedRule: "settings:notifications" });
+  }
+  return { type: input.type, scope: input.scope as Record<string, unknown>, recipients, suppressed };
+}
+
+export function whyNotified(messageId: number, agentId: string): (NotificationRoutingExplanation & { messageId: number; agentId: string }) | null {
+  const message = getMessage(messageId);
+  if (!message) return null;
+  const routing = routingExplanationFromPayload(message.payload?.routing);
+  if (!routing) return null;
+  if (routing.recipient !== agentId && message.to !== agentId && message.resolvedToAgent !== agentId) return null;
+  return { ...routing, messageId, agentId };
+}
+
+function notificationRecipientEnabled(type: NotificationType, recipient: string, scope: NotificationScope): boolean {
+  const agent = getAgent(recipient);
+  return notificationEnabledFor(type, {
+    agentId: agent?.id ?? recipient,
+    teamId: agent?.teamId ?? scope.teamId,
+  });
+}
+
+function normalizeRoutingRecipients(input: Pick<RouteNotificationInput, "type" | "scope" | "recipients">): NotificationRoutingRecipientInput[] {
+  const raw = input.recipients === undefined
+    ? resolveAudience(input.type, input.scope).map((member) => ({ agentId: member.agentId, matchedRule: member.matchedRule }))
+    : input.recipients;
+  const byAgent = new Map<string, NotificationRoutingRecipientInput>();
+  for (const item of raw) {
+    const candidate = normalizeRoutingRecipient(item);
+    if (!candidate || byAgent.has(candidate.agentId)) continue;
+    byAgent.set(candidate.agentId, candidate);
+  }
+  return [...byAgent.values()];
+}
+
+function normalizeRoutingRecipient(value: string | NotificationRoutingRecipientInput | null | undefined): NotificationRoutingRecipientInput | null {
+  if (typeof value === "string") {
+    const agentId = value.trim();
+    return agentId ? { agentId } : null;
+  }
+  if (!value) return null;
+  const agentId = typeof value.agentId === "string" ? value.agentId.trim() : "";
+  if (!agentId) return null;
+  return {
+    agentId,
+    matchedRule: typeof value.matchedRule === "string" && value.matchedRule.trim() ? value.matchedRule.trim() : undefined,
+    reason: typeof value.reason === "string" && value.reason.trim() ? value.reason.trim() : undefined,
+  };
+}
+
+function inferMatchedRule(recipient: string, scope: NotificationScope): string {
+  if (scope.author && recipient === scope.author) return "author";
+  if (scope.parent && recipient === scope.parent) return "spawn-parent";
+  if (scope.agentId && recipient === scope.agentId) return "subject-agent";
+  const agent = getAgent(recipient);
+  if (scope.teamId && agent?.teamId === scope.teamId) return "same-team";
+  return "explicit-recipient";
+}
+
+function subscriptionStateFor(type: NotificationType, recipient: string, scope: NotificationScope): NotificationRoutingExplanation["subscriptionState"] {
+  const agent = getAgent(recipient);
+  if (!agent) return "unknown";
+  return subscriptionDecisionFor(agent, { type, scope, now: Date.now() });
+}
+
+function routingReason(
+  matchedRule: string,
+  recipient: string,
+  scope: NotificationScope,
+  subscriptionState: NotificationRoutingExplanation["subscriptionState"],
+  settingsEnabled: boolean,
+): string {
+  if (!settingsEnabled) return "notifications are disabled for this recipient by settings";
+  if (matchedRule === "author") return "you are the author";
+  if (matchedRule === "spawn-parent") return "you are the spawn parent";
+  if (matchedRule === "subject-agent") return "you are the notification subject";
+  if (matchedRule === "same-team") return scope.teamId ? `same team ${scope.teamId}` : "same team";
+  if (matchedRule === "on-repo-root") return scope.repoRoot ? `online in repo root ${scope.repoRoot}` : "online in the repo root";
+  if (matchedRule === "subscription:store" || subscriptionState === "deliver") return "explicit subscription matched";
+  if (matchedRule === "settings:notifications") return "notifications are disabled for this recipient by settings";
+  return `explicit recipient ${recipient}`;
+}
+
+function compactRoutingExplanation(routing: NotificationRoutingExplanation): NotificationRoutingExplanation {
+  return routing;
+}
+
+function routingExplanationFromPayload(value: unknown): NotificationRoutingExplanation | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const record = value as Record<string, unknown>;
+  if (typeof record.type !== "string" || typeof record.recipient !== "string" || typeof record.matchedRule !== "string") return null;
+  return {
+    type: record.type as NotificationType,
+    recipient: record.recipient,
+    matchedRule: record.matchedRule,
+    reason: typeof record.reason === "string" ? record.reason : "",
+    scope: record.scope && typeof record.scope === "object" && !Array.isArray(record.scope) ? record.scope as Record<string, unknown> : {},
+    subscriptionState: record.subscriptionState === "deliver" || record.subscriptionState === "suppress" || record.subscriptionState === "abstain"
+      ? record.subscriptionState
+      : "unknown",
+    settingsEnabled: record.settingsEnabled !== false,
+  };
+}
+
+function auditRoutingTrace(message: Message, preview: NotificationRoutingPreview, maxAgeSeconds: number | null): void {
+  try {
+    createActivityEvent({
+      kind: "state",
+      title: "Notification routed",
+      body: preview.recipients.find((item) => item.recipient === message.to)?.reason,
+      icon: "ti-route",
+      view: "messages",
+      messageId: message.id,
+      agentId: message.to,
+      metadata: {
+        source: "notification-router",
+        notificationType: preview.type,
+        scope: preview.scope as Record<string, unknown>,
+        routing: {
+          delivered: preview.recipients,
+          suppressed: preview.suppressed,
+          maxAgeSeconds,
+        },
+      },
+    });
+  } catch {
+    // Routing audit must never block notification delivery.
+  }
 }

package/src/notification-rules.ts

@@ -1,6 +1,7 @@
 import type { AgentCard } from "./types";
 import { listAgents } from "./db";
 import { isAgentOnline } from "./agent-ref";
+import { notificationEnabledFor } from "./notification-settings-store";
 import type { NotificationType, NotificationScope } from "./notification-types";
 
 /**
@@ -154,6 +155,11 @@ export function registerDefaultAudienceRules(type: NotificationType, rules: Noti
 // #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[] = [];
+const settingsRule: NotificationRule = {
+  name: "settings:notifications",
+  evaluate: (agent, { type, scope }) =>
+    notificationEnabledFor(type, { agentId: agent.id, teamId: agent.teamId ?? scope.teamId }) ? "abstain" : "suppress",
+};
 
 /** #443 hook: install the subscription override rules (opt-in/opt-out/mute). Pass [] to clear. */
 export function setSubscriptionRules(rules: NotificationRule[]): void {
@@ -164,7 +170,7 @@ export function setSubscriptionRules(rules: NotificationRule[]): void {
 function audienceRulesFor(type: NotificationType): NotificationRule[] {
   const defaults = audienceRegistry.get(type);
   if (!defaults) return [];
-  return subscriptionRules.length === 0 ? defaults : [...defaults, ...subscriptionRules];
+  return [...defaults, ...subscriptionRules, settingsRule];
 }
 
 /**

package/src/notification-settings-store.ts

@@ -0,0 +1,47 @@
+import { getConfig, getNotificationsConfig, listConfig } from "./config-store";
+import {
+  NOTIFICATIONS_DEFAULT_KEY,
+  NOTIFICATIONS_NAMESPACE,
+  mergeNotificationSettings,
+  notificationAgentKey,
+  notificationTeamKey,
+  notificationTypeEnabled,
+  parseNotificationSettingsKey,
+  validateNotificationSettingsLayer,
+  type NotificationSettingsTarget,
+  type NotificationSettingLayer,
+} from "./notification-settings";
+import { registerNotificationSettingDescriptor } from "./settings/registry";
+import type { NotificationsConfig } from "./types";
+import type { NotificationType } from "./notification-types";
+
+export function ensureNotificationSettingDescriptors(extraKeys: string[] = []): void {
+  const keys = new Set<string>([NOTIFICATIONS_DEFAULT_KEY]);
+  for (const entry of listConfig(NOTIFICATIONS_NAMESPACE)) keys.add(entry.key);
+  for (const key of extraKeys) keys.add(key);
+
+  for (const key of keys) {
+    if (!parseNotificationSettingsKey(key)) continue;
+    registerNotificationSettingDescriptor(key);
+  }
+}
+
+export function getResolvedNotificationsConfig(target: NotificationSettingsTarget = {}): NotificationsConfig {
+  let config = getNotificationsConfig();
+  if (target.teamId) {
+    config = mergeNotificationSettings(config, notificationSettingsLayer(notificationTeamKey(target.teamId)));
+  }
+  if (target.agentId) {
+    config = mergeNotificationSettings(config, notificationSettingsLayer(notificationAgentKey(target.agentId)));
+  }
+  return config;
+}
+
+export function notificationEnabledFor(type: NotificationType, target: NotificationSettingsTarget = {}): boolean {
+  return notificationTypeEnabled(getResolvedNotificationsConfig(target), type);
+}
+
+function notificationSettingsLayer(key: string): NotificationSettingLayer | null {
+  const entry = getConfig<NotificationSettingLayer>(NOTIFICATIONS_NAMESPACE, key);
+  return entry ? validateNotificationSettingsLayer(entry.value) : null;
+}

package/src/notification-settings.ts

@@ -0,0 +1,155 @@
+import { isRecord } from "agent-relay-sdk";
+import type { JSONSchema } from "agent-relay-sdk";
+import { ValidationError } from "./db/connection.ts";
+import { DEFAULT_CONTEXT_THRESHOLD_CONFIG, validateContextThresholdConfig } from "./context-threshold-config";
+import { DEFAULT_QUOTA_THRESHOLD_CONFIG, validateQuotaThresholdConfig } from "./quota-threshold-config";
+import type { NotificationsConfig } from "./types";
+import type { NotificationType } from "./notification-types";
+
+export const NOTIFICATIONS_NAMESPACE = "notifications";
+export const NOTIFICATIONS_DEFAULT_KEY = "default";
+const TEAM_KEY_PREFIX = "team:";
+const AGENT_KEY_PREFIX = "agent:";
+
+type NotificationToggleKey = "branchLanded" | "agentReady" | "agentExited" | "agentSpawnFailed";
+export type NotificationSettingLayer = Partial<NotificationsConfig>;
+
+export interface NotificationSettingsTarget {
+  agentId?: string;
+  teamId?: string;
+}
+
+export const NOTIFICATIONS_CONFIG_DEFAULTS: NotificationsConfig = {
+  enabled: true,
+  branchLanded: true,
+  agentReady: true,
+  agentExited: true,
+  agentSpawnFailed: true,
+  contextThreshold: DEFAULT_CONTEXT_THRESHOLD_CONFIG,
+  quotaThreshold: DEFAULT_QUOTA_THRESHOLD_CONFIG,
+};
+
+export const CONTEXT_THRESHOLD_SETTINGS_SCHEMA: JSONSchema = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    enabled: { type: "boolean" },
+    advisoryUtilization: { type: "number", minimum: 0, maximum: 1 },
+    selfCompactUtilization: { type: "number", minimum: 0, maximum: 1 },
+    warnUtilization: { type: "number", minimum: 0, maximum: 1 },
+    hardBackstopUtilization: { type: "number", minimum: 0, maximum: 1 },
+    bandSize: { type: "number", exclusiveMinimum: 0, maximum: 1 },
+  },
+};
+
+export const QUOTA_THRESHOLD_SETTINGS_SCHEMA: JSONSchema = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    enabled: { type: "boolean" },
+    warnRemaining: { type: "number", minimum: 0, maximum: 1 },
+    criticalRemaining: { type: "number", minimum: 0, maximum: 1 },
+    resetRemaining: { type: "number", minimum: 0, maximum: 1 },
+    bandSize: { type: "number", exclusiveMinimum: 0, maximum: 1 },
+  },
+};
+
+export const NOTIFICATIONS_SETTINGS_SCHEMA: JSONSchema = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    enabled: { type: "boolean" },
+    branchLanded: { type: "boolean" },
+    agentReady: { type: "boolean" },
+    agentExited: { type: "boolean" },
+    agentSpawnFailed: { type: "boolean" },
+    contextThreshold: CONTEXT_THRESHOLD_SETTINGS_SCHEMA,
+    quotaThreshold: QUOTA_THRESHOLD_SETTINGS_SCHEMA,
+  },
+};
+
+export function notificationTeamKey(teamId: string): string {
+  return `${TEAM_KEY_PREFIX}${cleanLayerId(teamId, "teamId")}`;
+}
+
+export function notificationAgentKey(agentId: string): string {
+  return `${AGENT_KEY_PREFIX}${cleanLayerId(agentId, "agentId")}`;
+}
+
+export function parseNotificationSettingsKey(key: string): { kind: "default" | "team" | "agent"; id?: string } | null {
+  if (key === NOTIFICATIONS_DEFAULT_KEY) return { kind: "default" };
+  if (key.startsWith(TEAM_KEY_PREFIX)) {
+    const id = key.slice(TEAM_KEY_PREFIX.length).trim();
+    return id ? { kind: "team", id } : null;
+  }
+  if (key.startsWith(AGENT_KEY_PREFIX)) {
+    const id = key.slice(AGENT_KEY_PREFIX.length).trim();
+    return id ? { kind: "agent", id } : null;
+  }
+  return null;
+}
+
+export function validateNotificationsConfig(value: unknown): NotificationsConfig {
+  return mergeNotificationSettings(NOTIFICATIONS_CONFIG_DEFAULTS, validateNotificationSettingsLayer(value));
+}
+
+export function validateNotificationSettingsLayer(value: unknown): NotificationSettingLayer {
+  if (!isRecord(value)) throw new ValidationError("notifications config value must be an object");
+  const bool = (key: "enabled" | NotificationToggleKey): boolean | undefined =>
+    value[key] === undefined ? undefined : cleanBoolean(value[key], key);
+  return {
+    ...(bool("enabled") !== undefined ? { enabled: bool("enabled")! } : {}),
+    ...(bool("branchLanded") !== undefined ? { branchLanded: bool("branchLanded")! } : {}),
+    ...(bool("agentReady") !== undefined ? { agentReady: bool("agentReady")! } : {}),
+    ...(bool("agentExited") !== undefined ? { agentExited: bool("agentExited")! } : {}),
+    ...(bool("agentSpawnFailed") !== undefined ? { agentSpawnFailed: bool("agentSpawnFailed")! } : {}),
+    ...(value.contextThreshold === undefined ? {} : { contextThreshold: validateContextThresholdConfig(value.contextThreshold) }),
+    ...(value.quotaThreshold === undefined ? {} : { quotaThreshold: validateQuotaThresholdConfig(value.quotaThreshold) }),
+  };
+}
+
+export function mergeNotificationSettings(base: NotificationsConfig, layer: NotificationSettingLayer | null | undefined): NotificationsConfig {
+  if (!layer) return base;
+  return {
+    ...base,
+    ...withoutNestedThresholds(layer),
+    contextThreshold: layer.contextThreshold ? { ...base.contextThreshold, ...layer.contextThreshold } : base.contextThreshold,
+    quotaThreshold: layer.quotaThreshold ? { ...base.quotaThreshold, ...layer.quotaThreshold } : base.quotaThreshold,
+  };
+}
+
+export function notificationTypeEnabled(config: NotificationsConfig, type: NotificationType): boolean {
+  if (!config.enabled) return false;
+  if (type === "agent.context_threshold") return config.contextThreshold.enabled;
+  if (type === "agent.quota_threshold") return config.quotaThreshold.enabled;
+  const key = notificationToggleForType(type);
+  return key ? config[key] : true;
+}
+
+function notificationToggleForType(type: NotificationType): NotificationToggleKey | null {
+  if (type === "branch.landed" || type === "landed-failure") return "branchLanded";
+  if (type === "agent.ready") return "agentReady";
+  if (type === "agent.exited") return "agentExited";
+  if (type === "agent.spawn_failed") return "agentSpawnFailed";
+  return null;
+}
+
+function withoutNestedThresholds(layer: NotificationSettingLayer): Omit<NotificationSettingLayer, "contextThreshold" | "quotaThreshold"> {
+  const { contextThreshold: _contextThreshold, quotaThreshold: _quotaThreshold, ...rest } = layer;
+  return rest;
+}
+
+function cleanBoolean(value: unknown, field: string): boolean {
+  if (typeof value !== "boolean") throw new ValidationError(`${field} must be a boolean`);
+  return value;
+}
+
+function cleanLayerId(value: string, field: string): string {
+  const clean = value.trim();
+  if (!clean) throw new ValidationError(`${field} required`);
+  if (clean.length > 200) throw new ValidationError(`${field} must be at most 200 characters`);
+  if (clean.includes("/") || clean.includes("\n") || clean.includes("\r")) {
+    throw new ValidationError(`${field} must not contain slashes or newlines`);
+  }
+  return clean;
+}

package/src/notification-types.ts

@@ -84,5 +84,7 @@ export const DEFAULT_TTL_MS: Record<NotificationType, number | null> = {
   "workspace.review_changes_requested": null,
 };
 
+export const NOTIFICATION_TYPES = Object.keys(DEFAULT_TTL_MS) as NotificationType[];
+
 /** Convenience TTL for emitter-supplied overrides on bystander/informational notifications. */
 export const INFORMATIONAL_TTL_MS = 30 * MINUTES;

package/src/quota-advisory.ts

@@ -165,9 +165,6 @@ function notifyQuotaAdvisory(input: {
     data: payload,
   });
 
-  const notifications = effectiveQuotaNotificationConfig();
-  if (!notifications.enabled || !notifications.quotaThreshold.enabled) return;
-
   routeNotification({
     type: "agent.quota_threshold",
     scope: {},

package/src/routes/agents-spawn.ts

@@ -1,5 +1,5 @@
 // Auto-split from routes.ts (#299). Domain: agents-spawn.
-import { APPROVAL_MODES, SPAWN_PROVIDERS, VALID_WORKSPACE_MODES, isRecord } from "agent-relay-sdk";
+import { APPROVAL_MODES, AUTO_MERGE_POLICIES, SPAWN_PROVIDERS, VALID_WORKSPACE_MODES, isRecord } from "agent-relay-sdk";
 import { McpAuthError, McpNotFoundError } from "../mcp-errors";
 import { VALID_AGENT_STATUSES, error, json, parseBody, type Handler } from "./_shared";
 import { ValidationError, listAgents } from "../db";
@@ -15,10 +15,19 @@ import { authContextFromRequest } from "../services/auth-context";
 import { listHostDirectories } from "../agent-spawn";
 import { rankRouteCandidates, type RouteAdvisorInput } from "../context-router";
 import { quotaStateFromUnknown } from "../quota";
-import { type AgentKind, type RegisterAgentInput, type SpawnApprovalMode, type SpawnProvider, type WorkspaceMode } from "../types";
+import { type AgentKind, type RegisterAgentInput, type SpawnApprovalMode, type SpawnProvider, type WorkspaceAutoMergePolicy, type WorkspaceLandingPolicy, type WorkspaceMode } from "../types";
 import { type ProviderEffort } from "agent-relay-sdk/provider-catalog";
 
 const VALID_AGENT_KINDS = ["provider", "channel", "orchestrator", "system", "user"] as const;
+const SPAWN_LAND_STRATEGIES = ["direct", "pr"] as const;
+
+function parseResumeWorkspaceHttp(value: unknown): { branch: string; mode: "attach" | "branch-from" } | undefined {
+  if (!value || !isRecord(value)) return undefined;
+  const branch = cleanString(value.branch, "resumeWorkspace.branch", { max: 500 });
+  const mode = value.mode === "attach" || value.mode === "branch-from" ? value.mode : undefined;
+  if (!branch || !mode) return undefined;
+  return { branch, mode };
+}
 
 function normalizeAgentInput(body: unknown): RegisterAgentInput {
   if (!isRecord(body)) throw new ValidationError("JSON object body required");
@@ -129,12 +138,16 @@ export const postAgentSpawn: Handler = async (req) => {
       projectSkills: parseProjectSkills(parsed.body.projectSkills, (m) => new ValidationError(m)),
       projectSettings: parseProjectSettings(parsed.body.projectSettings, (m) => new ValidationError(m)),
       sharedMcp: parseSharedMcp(parsed.body.sharedMcp, (m) => new ValidationError(m)),
+      landStrategy: optionalEnum(parsed.body.landStrategy, "landStrategy", SPAWN_LAND_STRATEGIES) as WorkspaceLandingPolicy | undefined,
+      autoMerge: optionalEnum(parsed.body.autoMerge, "autoMerge", AUTO_MERGE_POLICIES) as WorkspaceAutoMergePolicy | undefined,
+      reviewer: cleanString(parsed.body.reviewer, "reviewer", { max: 240 }),
       tags: cleanStringArray(parsed.body.tags, "tags", { itemMax: 80, maxItems: 50 }),
       capabilities: cleanStringArray(parsed.body.capabilities, "capabilities", { itemMax: 80, maxItems: 50 }),
       providerArgs: cleanStringArray(parsed.body.providerArgs, "providerArgs", { itemMax: 80, maxItems: 50 }),
       spawnRequestId: cleanString(parsed.body.spawnRequestId, "spawnRequestId", { max: 160 }),
       requestedVia: "dashboard",
       requestedBy: "dashboard",
+      resumeWorkspace: parseResumeWorkspaceHttp(parsed.body.resumeWorkspace),
       // HTTP is fire-and-forget (202): the dashboard polls registration separately via the
       // returned spawnRequestId.
       waitForRegistrationMs: 0,

package/src/routes/agents.ts

@@ -7,6 +7,8 @@ import { cleanStringArray } from "../validation";
 import { clearActiveMemories, memoryBroker } from "../memory-service";
 import { emitAgentRemoved, emitAgentStatus } from "../sse";
 import { notifyAgentReady } from "../agent-lifecycle-events";
+import { flushQueuedDirectMessages } from "../services/managed-running";
+import { isAgentUnavailable } from "../db/agent-predicates";
 import { getCompactionWatch } from "../compaction-watch";
 import { isRecord } from "agent-relay-sdk";
 import { type AgentCard } from "../types";
@@ -210,7 +212,15 @@ export const postHeartbeat: Handler = async (req, params) => {
     const guard = normalizeAgentSessionGuard(req, parsed.body);
     const session = validateAgentSession(params.id!, guard);
     if (!session.ok) return error(session.error!, agentSessionStatus(session.error));
-    return heartbeat(params.id!, guard) ? json({ ok: true }) : error("agent not found", 404);
+    // #416 — capture unavailability before heartbeat to detect the transition.
+    const beforeHeartbeat = getAgent(params.id!);
+    const wasUnavailable = beforeHeartbeat ? isAgentUnavailable(beforeHeartbeat) : false;
+    if (!heartbeat(params.id!, guard)) return error("agent not found", 404);
+    if (wasUnavailable) {
+      const after = getAgent(params.id!);
+      if (after && !isAgentUnavailable(after)) flushQueuedDirectMessages(params.id!);
+    }
+    return json({ ok: true });
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
     throw e;
@@ -287,7 +297,12 @@ export const patchAgentReady: Handler = async (req, params) => {
     // #308 — a spawned child flipping false→true ready is "genuinely ready" (past onboarding):
     // wake its parent so it can stop block-polling. notifyAgentReady no-ops for non-spawned
     // agents and dedups repeat readies.
-    if (body.ready && !before?.ready) notifyAgentReady(params.id!);
+    if (body.ready && !before?.ready) {
+      notifyAgentReady(params.id!);
+      // #416 — also flush queued direct messages: a not-ready agent that becomes ready
+      // may have queued messages waiting (e.g. starting up, clearing context).
+      flushQueuedDirectMessages(params.id!);
+    }
   } catch (e) {
     if (e instanceof ValidationError) return error(e.message, 400);
     throw e;

package/src/routes/commands.ts

@@ -13,6 +13,7 @@ import { authContextFromRequest } from "../services/auth-context";
 import { commandAuthorizationResource as dispatchCommandAuthorizationResource, dispatchCommand } from "../services/dispatch-command";
 import { ServiceAuthError } from "../services/errors";
 import { notifyBranchLandFailed, notifyBranchLanded } from "../branch-landed";
+import { applyIdleRefreshResult } from "../maintenance/workspaces";
 import { seedProviderConfigs } from "../provider-config-store";
 import { notifyAgentSpawnFailed } from "../agent-lifecycle-events";
 import { handleReviewerMergeResult } from "../reviewer-pipeline";
@@ -186,6 +187,10 @@ export const patchCommand: Handler = async (req, params) => {
         });
       }
     }
+    if (command.type === "workspace.idle-refresh" && command.status === "succeeded" && isRecord(command.result)) {
+      const workspaceId = cleanString(command.result.workspaceId, "result.workspaceId", { max: 160 });
+      if (workspaceId) applyIdleRefreshResult(workspaceId, command.result);
+    }
     if (command.type === "workspace.merge") {
       // Merge settled (either way) — free the per-repo merge lease so the next
       // base merge can proceed (issue #157).

package/src/routes/index.ts

@@ -40,6 +40,7 @@ import { deleteIssueRefRoute, getIssueRefRoute, listIssueRefsRoute, patchIssueRe
 import { getProjectEntriesRoute, getProjectEntryRoute, getProjectResolveRoute, getProjectRoute, getProjectsRoute } from "./projects";
 import { getRecipeByName, getRecipeInstanceArtifacts, getRecipeInstanceById, getRecipeInstances, getRecipes, postRecipeInstanceArtifacts, postRecipeStart, postRecipeStop } from "./recipes";
 import { getSettingRoute, getSettingsNamespaceRoute, getSettingsRoute, putSettingRoute, putSettingsDefaultRoute } from "./settings";
+import { postNotificationPreviewRoute } from "./notifications";
 import { getStewardConfigRoute, getWorkspaceConfigRoute, putStewardConfigRoute, putWorkspaceConfigRoute } from "./steward";
 import { getTaskById, getTaskEvents, getTasks, patchTaskStatus, postClaimTask, postRenewTaskClaim } from "./tasks";
 import { getMyTeamRoute, getTeamOutcomesRoute, getTeamsRoute, postMyTeamDissolveRoute, putMyTeamBriefRoute } from "./teams";
@@ -246,6 +247,7 @@ const routes: Route[] = [
   route("GET", "/api/settings/:namespace/:key", getSettingRoute),
   route("PUT", "/api/settings/:namespace", putSettingsDefaultRoute),
   route("PUT", "/api/settings/:namespace/:key", putSettingRoute),
+  route("POST", "/api/notifications/preview", postNotificationPreviewRoute),
   route("GET", "/api/config/:namespace", getConfigNamespace),
   route("GET", "/api/config/:namespace/:key/history", getConfigKeyHistory),
   route("GET", "/api/config/:namespace/:key", getConfigKey),

package/src/routes/notifications.ts

@@ -0,0 +1,36 @@
+// Domain: notification routing preview/explainability (#446).
+import { isRecord } from "agent-relay-sdk";
+import { ValidationError } from "../db";
+import { NOTIFICATION_TYPES, type NotificationScope, type NotificationType } from "../notification-types";
+import { previewNotificationRouting } from "../notification-router";
+import { error, json, parseBody, type Handler } from "./_shared";
+
+export const postNotificationPreviewRoute: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) return error("JSON object body required");
+    return json({
+      preview: previewNotificationRouting({
+        type: cleanNotificationType(parsed.body.type),
+        scope: cleanScope(parsed.body.scope),
+      }),
+    });
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+function cleanNotificationType(value: unknown): NotificationType {
+  if (typeof value !== "string" || !NOTIFICATION_TYPES.includes(value as NotificationType)) {
+    throw new ValidationError(`type must be one of: ${NOTIFICATION_TYPES.join(", ")}`);
+  }
+  return value as NotificationType;
+}
+
+function cleanScope(value: unknown): NotificationScope {
+  if (value === undefined || value === null) return {};
+  if (!isRecord(value)) throw new ValidationError("scope must be an object");
+  return value as NotificationScope;
+}

package/src/routes/settings.ts

@@ -3,6 +3,8 @@ import { ValidationError } from "../db";
 import { getConfig, setConfig } from "../config-store";
 import { getUserSetting, setUserSetting } from "../user-settings-store";
 import { ensureProviderConfigDescriptors, migrateLocalProviderConfigs } from "../provider-config-store";
+import { ensureNotificationSettingDescriptors } from "../notification-settings-store";
+import { NOTIFICATIONS_NAMESPACE } from "../notification-settings";
 import { getSettingDescriptor, listSettingDescriptors, validateSettingValue, PROVIDER_CONFIG_NAMESPACE } from "../settings/registry";
 import { isRequestAuthorizedFor } from "../security";
 import { cleanString } from "../validation";
@@ -21,6 +23,7 @@ type SettingEnvelope = SettingEntry;
 export const getSettingsRoute: Handler = (req) => {
   migrateLocalProviderConfigs();
   ensureProviderConfigDescriptors();
+  ensureNotificationSettingDescriptors();
   return json({ settings: listVisibleSettings(req) });
 };
 
@@ -28,6 +31,7 @@ export const getSettingsNamespaceRoute: Handler = (req, params) => {
   const namespace = normalizeConfigPathParam(params.namespace, "namespace");
   migrateLocalProviderConfigs();
   ensureProviderConfigDescriptors();
+  if (namespace === NOTIFICATIONS_NAMESPACE) ensureNotificationSettingDescriptors();
   return json({ settings: listVisibleSettings(req).filter((setting) => setting.namespace === namespace) });
 };
 
@@ -36,6 +40,7 @@ export const getSettingRoute: Handler = (req, params) => {
   const key = normalizeConfigPathParam(params.key, "key");
   migrateLocalProviderConfigs();
   ensureProviderConfigDescriptors(namespace === PROVIDER_CONFIG_NAMESPACE ? [key] : []);
+  if (namespace === NOTIFICATIONS_NAMESPACE) ensureNotificationSettingDescriptors([key]);
   const descriptor = getSettingDescriptor(namespace, key);
   if (!descriptor) return error("setting not found", 404);
   const readable = canAccessSetting(req, descriptor.scope.read);
@@ -76,6 +81,7 @@ async function putSetting(req: Request, namespaceRaw: string | undefined, keyRaw
   try {
     migrateLocalProviderConfigs();
     ensureProviderConfigDescriptors(namespace === PROVIDER_CONFIG_NAMESPACE ? [key] : []);
+    if (namespace === NOTIFICATIONS_NAMESPACE) ensureNotificationSettingDescriptors([key]);
     const descriptor = getSettingDescriptor(namespace, key);
     if (!descriptor) return error("setting not found", 404);
     if (descriptor.tier !== "server-runtime" && descriptor.tier !== "user") return error("setting is read-only", 403);