agent-relay-server 0.59.0 → 0.60.1

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/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;
 }

package/src/routes/agent-sessions.ts

@@ -1,6 +1,6 @@
 // Auto-split from routes.ts (#299). Domain: agent-sessions.
 import { RELAY_TOKEN_HEADER, isRecord } from "agent-relay-sdk";
-import { VALID_AGENT_ACTIONS, agentControlActionIcon, auditEvent, authAuditMetadata, authorizeRoute, dashboardAttribution, emitCommand, error, json, metaString, parseBody, spawnRequestId, type AgentControlAction, type Handler } from "./_shared";
+import { VALID_AGENT_ACTIONS, agentControlActionIcon, auditEvent, authAuditMetadata, authorizeRoute, cleanAttachmentRefs, dashboardAttribution, emitCommand, error, json, metaString, parseBody, spawnRequestId, type AgentControlAction, type Handler } from "./_shared";
 import { ValidationError, getAgent, getAgentTimeline, getOrchestrator, markReady, mergeAgentMeta, sendMessage } from "../db";
 import { buildManagedSpawnParams } from "../managed-policy";
 import { buildSpawnCommand, generateSpawnRequestId, resolveSpawnModelParams } from "../spawn-command";
@@ -306,6 +306,7 @@ export const postAgentPrompt: Handler = async (req, params) => {
   try {
     if (!isRecord(parsed.body)) return error("body required");
     const body = cleanString(parsed.body.body, "body", { required: true, max: 100_000 })!;
+    const attachments = cleanAttachmentRefs(parsed.body.attachments ?? parsed.body.artifacts, "attachments");
     const agent = getAgent(params.id!);
     if (!agent) return error("agent not found", 404);
     if (agent.status === "offline") return error("agent is offline", 422);
@@ -319,12 +320,13 @@ export const postAgentPrompt: Handler = async (req, params) => {
       to: agent.id,
       kind: "session",
       body,
+      ...(attachments ? { payload: { attachments } } : {}),
     });
     const command = createCommand({
       type: "prompt.inject",
       source: "dashboard",
       target: agent.id,
-      params: { body, messageId: message.id },
+      params: { body, messageId: message.id, ...(attachments ? { attachments } : {}) },
     });
     emitCommand(command);
     emitNewMessage(message);

package/src/routes/commands.ts

@@ -315,6 +315,26 @@ export const patchCommand: Handler = async (req, params) => {
         });
       }
     }
+    if (command.type === "workspace.pr-refresh") {
+      const resultWorkspaceId = isRecord(command.result) ? cleanString(command.result.workspaceId, "result.workspaceId", { max: 160 }) : undefined;
+      const workspaceId = resultWorkspaceId ?? command.correlationId;
+      if (workspaceId && command.status === "succeeded" && isRecord(command.result) && command.result.prRefreshed === true) {
+        patchWorkspaceMetadata(workspaceId, {
+          prRefreshCommandId: command.id,
+          prRefreshedAt: Date.now(),
+          prRefreshResult: command.result,
+          prRefreshError: undefined,
+          prRefreshFailedAt: undefined,
+        });
+      } else if (workspaceId && (command.status === "failed" || command.status === "timed_out" || command.status === "rejected" || command.status === "canceled")) {
+        patchWorkspaceMetadata(workspaceId, {
+          prRefreshCommandId: command.id,
+          prRefreshError: command.error ?? "PR branch refresh failed",
+          prRefreshFailedAt: Date.now(),
+          prRefreshResult: command.result,
+        });
+      }
+    }
     if (command.type === "workspace.deps-refresh" && command.status === "succeeded" && isRecord(command.result)) {
       // Record the outcome on the row without touching status (#51) — observability
       // for the dashboard; the CLI reads the result straight off the command.

package/src/routes/index.ts

@@ -35,6 +35,7 @@ import { getTaskById, getTaskEvents, getTasks, patchTaskStatus, postClaimTask, p
 import { getMyTeamRoute, getTeamOutcomesRoute, getTeamsRoute, postMyTeamDissolveRoute, putMyTeamBriefRoute } from "./teams";
 import { postTeamDissolveByIdRoute } from "./teams";
 import { deleteTeamTemplateRoute, getTeamTemplateRoute, getTeamTemplatesRoute, postTeamTemplateRoute, putTeamTemplateRoute } from "./team-templates";
+import { getMergePauseById, getMergePauses, postMergePause, postMergePauseRenew, postMergePauseResume } from "./merges";
 import { postMcp } from "../mcp";
 import { postOrchestratorBootstrap, postOrchestratorBootstrapExchange } from "./orchestrator-bootstrap";
 
@@ -139,6 +140,12 @@ const routes: Route[] = [
   route("POST", "/api/workspaces/:id/actions", postWorkspaceAction),
   route("DELETE", "/api/workspaces/:id", deleteWorkspaceById),
 
+  route("GET", "/api/merges/pauses", getMergePauses),
+  route("POST", "/api/merges/pause", postMergePause),
+  route("POST", "/api/merges/resume", postMergePauseResume),
+  route("POST", "/api/merges/renew", postMergePauseRenew),
+  route("GET", "/api/merges/pauses/:id", getMergePauseById),
+
   route("POST", "/api/system/broadcast", postSystemBroadcast),
   route("GET", "/api/teams", getTeamsRoute),
   route("GET", "/api/teams/outcomes", getTeamOutcomesRoute),