agent-relay-server 0.23.0 → 0.25.0

package/src/mcp.ts

@@ -515,11 +515,14 @@ function senderIdentity(auth: McpAuthContext): string | undefined {
   return agents?.length === 1 ? agents[0] : undefined;
 }
 
-// Caller's own agent id for spawn/shutdown gating (#221). `senderIdentity` covers
+// THE caller-identity resolver: the agent id behind this token, for `from`-autofill,
+// relay_whoami, and spawn/shutdown gating (#221, #243). `senderIdentity` covers
 // identity-bearing tokens (interactive/mcp, constraints.agents). Managed agents spawned by
 // the orchestrator authenticate with a runner token that carries no `agents` constraint but
-// DOES carry its spawnRequestId/policy — resolve those back to the registered agent card.
-// Returns undefined for server/admin tokens (unrestricted by design).
+// DOES carry its spawnRequestId/policy — resolve those back to the registered agent card so
+// they never need to pass `from`. Returns undefined for server/admin tokens (unrestricted by
+// design) and multi-agent tokens. Keep `resolveSender`/`relayWhoami` on THIS, not the narrower
+// `senderIdentity`, or managed agents silently lose implicit identity again (the #243 drift).
 function callerAgentId(auth: McpAuthContext): string | undefined {
   const direct = senderIdentity(auth);
   if (direct) return direct;
@@ -536,14 +539,15 @@ function callerAgentId(auth: McpAuthContext): string | undefined {
 
 function resolveSender(auth: McpAuthContext, rawFrom: unknown): string {
   // Token identity wins and cannot be spoofed; any provided `from` is ignored when known.
-  const identity = senderIdentity(auth);
+  // Resolves both constraints.agents tokens AND spawn/policy-managed agents (#243).
+  const identity = callerAgentId(auth);
   if (identity) return identity;
   // Server/integration/multi-agent tokens carry no single identity — keep requiring `from`.
   return stringField(rawFrom, "from", { required: true, max: 200 });
 }
 
 function relayWhoami(auth: McpAuthContext): Record<string, unknown> {
-  const agentId = senderIdentity(auth);
+  const agentId = callerAgentId(auth);
   const agent = agentId ? getAgent(agentId) : null;
   return {
     agentId: agentId ?? null,

package/src/memory-broker-base.ts

@@ -0,0 +1,161 @@
+import type {
+  ActiveMemoryClearReason,
+  ContextPackage,
+  ContextPackageRequest,
+  CreateMemoryInput,
+  Memory,
+  MemoryBrokerCapabilities,
+  MemoryBrokerContext,
+  MemoryQuery,
+  MemorySearchResult,
+  MemoryStats,
+  UpdateMemoryInput,
+} from "./types";
+import type { MemoryBroker } from "./memory-broker-contract";
+import {
+  MemoryBrokerContractError,
+  normalizeMemory,
+  normalizeMemoryBrokerCapabilities,
+  normalizeMemorySearchResult,
+} from "./memory-broker-contract";
+import { isRecord } from "agent-relay-sdk";
+
+export const DEFAULT_MEMORY_BROKER_TIMEOUT_MS = 10_000;
+
+/**
+ * Shared scaffolding for transport-backed memory brokers. The command and HTTP
+ * brokers differ only in how a single request is dispatched — everything else
+ * (operation methods, response normalization, error/result unwrapping) is
+ * identical. Subclasses implement {@link call} and supply a {@link label} used
+ * in error messages.
+ */
+export abstract class AbstractMemoryBroker implements MemoryBroker {
+  /** Human-readable transport name, e.g. "command" or "http". */
+  protected abstract readonly label: string;
+
+  /** Dispatch a single broker operation and return its raw (un-unwrapped) result. */
+  protected abstract call(operation: string, payload: Record<string, unknown>): Promise<unknown>;
+
+  async capabilities(): Promise<MemoryBrokerCapabilities> {
+    return normalizeMemoryBrokerCapabilities(await this.call("capabilities", {}));
+  }
+
+  async create(input: CreateMemoryInput, ctx: MemoryBrokerContext): Promise<Memory> {
+    return normalizeMemory(await this.call("create", { input, ctx }), { now: ctx.now });
+  }
+
+  async get(id: string, ctx: MemoryBrokerContext): Promise<Memory | null> {
+    const value = await this.call("get", { id, ctx });
+    return value === null ? null : normalizeMemory(value, { now: ctx.now });
+  }
+
+  async search(query: MemoryQuery, ctx: MemoryBrokerContext): Promise<MemorySearchResult> {
+    return normalizeMemorySearchResult(await this.call("search", { query, ctx }), { now: ctx.now });
+  }
+
+  async update(id: string, patch: UpdateMemoryInput, ctx: MemoryBrokerContext): Promise<Memory> {
+    return normalizeMemory(await this.call("update", { id, patch, ctx }), { now: ctx.now });
+  }
+
+  async delete(id: string, ctx: MemoryBrokerContext): Promise<void> {
+    await this.call("delete", { id, ctx });
+  }
+
+  async stats(ctx: MemoryBrokerContext): Promise<MemoryStats> {
+    return normalizeStats(await this.call("stats", { ctx }));
+  }
+
+  async assemble(request: ContextPackageRequest, ctx: MemoryBrokerContext): Promise<ContextPackage> {
+    return normalizeContextPackage(await this.call("assemble", { request, ctx }), ctx);
+  }
+
+  async markInjected(agentId: string, memoryIds: string[], ctx: MemoryBrokerContext): Promise<void> {
+    await this.call("mark-injected", { agentId, memoryIds, ctx });
+  }
+
+  async clearActive(agentId: string, reason: ActiveMemoryClearReason, ctx: MemoryBrokerContext): Promise<void> {
+    await this.call("clear-active", { agentId, reason, ctx });
+  }
+
+  async listActive(agentId: string, ctx: MemoryBrokerContext): Promise<Memory[]> {
+    return normalizeMemoryList(await this.call("list-active", { agentId, ctx }), ctx);
+  }
+
+  /** Parse a broker response body, treating empty output as null. */
+  protected parseJson(text: string, operation: string): unknown {
+    if (!text.trim()) return null;
+    try {
+      return JSON.parse(text);
+    } catch {
+      throw new MemoryBrokerContractError(`${this.label} memory broker ${operation} returned invalid JSON`);
+    }
+  }
+
+  /**
+   * Resolve a broker payload to its result. A `{ error }` field is treated as a
+   * failure (even on an otherwise-successful transport response), and a
+   * `{ result }` envelope is unwrapped; anything else is returned as-is.
+   */
+  protected unwrapResult(payload: unknown): unknown {
+    if (isRecord(payload) && Object.hasOwn(payload, "error") && typeof payload.error === "string") {
+      throw new MemoryBrokerContractError(`${this.label} memory broker failed: ${payload.error}`);
+    }
+    if (isRecord(payload) && Object.hasOwn(payload, "result")) return payload.result;
+    return payload;
+  }
+}
+
+export function normalizeContextPackage(value: unknown, ctx: MemoryBrokerContext): ContextPackage {
+  const record = requireRecord(value, "context package");
+  const rawMemories = record.memories;
+  if (!Array.isArray(rawMemories)) throw new MemoryBrokerContractError("context package.memories must be an array");
+  return {
+    memories: rawMemories.map((item) => {
+      const packaged = requireRecord(item, "packaged memory");
+      const priority = packaged.priority;
+      if (priority !== 1 && priority !== 2 && priority !== 3) throw new MemoryBrokerContractError("packaged memory.priority must be 1, 2, or 3");
+      return {
+        memory: normalizeMemory(packaged.memory, { now: ctx.now }),
+        reason: typeof packaged.reason === "string" ? packaged.reason : "broker selected",
+        priority,
+        score: typeof packaged.score === "number" && Number.isFinite(packaged.score) ? packaged.score : undefined,
+      };
+    }),
+    estimatedTokens: typeof record.estimatedTokens === "number" && Number.isFinite(record.estimatedTokens) ? record.estimatedTokens : 0,
+    rolePrompt: typeof record.rolePrompt === "string" ? record.rolePrompt : undefined,
+    recentContext: typeof record.recentContext === "string" ? record.recentContext : undefined,
+  };
+}
+
+function normalizeMemoryList(value: unknown, ctx: MemoryBrokerContext): Memory[] {
+  if (Array.isArray(value)) return value.map((item) => normalizeMemory(item, { now: ctx.now }));
+  if (isRecord(value) && Array.isArray(value.memories)) return value.memories.map((item) => normalizeMemory(item, { now: ctx.now }));
+  throw new MemoryBrokerContractError("memory list-active result must be an array or object with memories array");
+}
+
+function normalizeStats(value: unknown): MemoryStats {
+  const record = requireRecord(value, "memory stats");
+  return {
+    total: numberField(record.total, "memory stats.total"),
+    byType: objectField(record.byType, "memory stats.byType"),
+    byScope: objectField(record.byScope, "memory stats.byScope"),
+    bySensitivity: objectField(record.bySensitivity, "memory stats.bySensitivity"),
+  } as MemoryStats;
+}
+
+function objectField(value: unknown, field: string): Record<string, number> {
+  const record = requireRecord(value, field);
+  const out: Record<string, number> = {};
+  for (const [key, count] of Object.entries(record)) out[key] = numberField(count, `${field}.${key}`);
+  return out;
+}
+
+function numberField(value: unknown, field: string): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) throw new MemoryBrokerContractError(`${field} must be a number`);
+  return value;
+}
+
+function requireRecord(value: unknown, field: string): Record<string, unknown> {
+  if (!isRecord(value)) throw new MemoryBrokerContractError(`${field} must be an object`);
+  return value;
+}

package/src/memory-command-broker.ts

@@ -1,82 +1,18 @@
-import type {
-  ActiveMemoryClearReason,
-  CommandMemoryBrokerConfig,
-  ContextPackage,
-  ContextPackageRequest,
-  CreateMemoryInput,
-  Memory,
-  MemoryBrokerCapabilities,
-  MemoryBrokerContext,
-  MemoryQuery,
-  MemorySearchResult,
-  MemoryStats,
-  UpdateMemoryInput,
-} from "./types";
-import type { MemoryBroker } from "./memory-broker-contract";
-import {
-  MemoryBrokerContractError,
-  normalizeMemory,
-  normalizeMemoryBrokerCapabilities,
-  normalizeMemorySearchResult,
-} from "./memory-broker-contract";
-import { normalizeContextPackage } from "./memory-http-broker";
-import { errMessage, isRecord } from "agent-relay-sdk";
+import type { CommandMemoryBrokerConfig } from "./types";
+import { MemoryBrokerContractError } from "./memory-broker-contract";
+import { AbstractMemoryBroker, DEFAULT_MEMORY_BROKER_TIMEOUT_MS } from "./memory-broker-base";
+import { errMessage } from "agent-relay-sdk";
 
-const DEFAULT_TIMEOUT_MS = 10_000;
-
-export class CommandMemoryBroker implements MemoryBroker {
+export class CommandMemoryBroker extends AbstractMemoryBroker {
+  protected readonly label = "command";
   private readonly timeoutMs: number;
 
   constructor(private readonly config: CommandMemoryBrokerConfig) {
-    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  }
-
-  async capabilities(): Promise<MemoryBrokerCapabilities> {
-    return normalizeMemoryBrokerCapabilities(await this.call("capabilities", {}));
-  }
-
-  async create(input: CreateMemoryInput, ctx: MemoryBrokerContext): Promise<Memory> {
-    return normalizeMemory(await this.call("create", { input, ctx }), { now: ctx.now });
-  }
-
-  async get(id: string, ctx: MemoryBrokerContext): Promise<Memory | null> {
-    const value = await this.call("get", { id, ctx });
-    return value === null ? null : normalizeMemory(value, { now: ctx.now });
-  }
-
-  async search(query: MemoryQuery, ctx: MemoryBrokerContext): Promise<MemorySearchResult> {
-    return normalizeMemorySearchResult(await this.call("search", { query, ctx }), { now: ctx.now });
-  }
-
-  async update(id: string, patch: UpdateMemoryInput, ctx: MemoryBrokerContext): Promise<Memory> {
-    return normalizeMemory(await this.call("update", { id, patch, ctx }), { now: ctx.now });
-  }
-
-  async delete(id: string, ctx: MemoryBrokerContext): Promise<void> {
-    await this.call("delete", { id, ctx });
-  }
-
-  async stats(ctx: MemoryBrokerContext): Promise<MemoryStats> {
-    return normalizeStats(await this.call("stats", { ctx }));
-  }
-
-  async assemble(request: ContextPackageRequest, ctx: MemoryBrokerContext): Promise<ContextPackage> {
-    return normalizeContextPackage(await this.call("assemble", { request, ctx }), ctx);
-  }
-
-  async markInjected(agentId: string, memoryIds: string[], ctx: MemoryBrokerContext): Promise<void> {
-    await this.call("mark-injected", { agentId, memoryIds, ctx });
+    super();
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_MEMORY_BROKER_TIMEOUT_MS;
   }
 
-  async clearActive(agentId: string, reason: ActiveMemoryClearReason, ctx: MemoryBrokerContext): Promise<void> {
-    await this.call("clear-active", { agentId, reason, ctx });
-  }
-
-  async listActive(agentId: string, ctx: MemoryBrokerContext): Promise<Memory[]> {
-    return normalizeMemoryList(await this.call("list-active", { agentId, ctx }), ctx);
-  }
-
-  private async call(operation: string, payload: Record<string, unknown>): Promise<unknown> {
+  protected async call(operation: string, payload: Record<string, unknown>): Promise<unknown> {
     const proc = Bun.spawn([this.config.command, ...(this.config.args ?? [])], {
       stdin: "pipe",
       stdout: "pipe",
@@ -102,7 +38,7 @@ export class CommandMemoryBroker implements MemoryBroker {
       if (exitCode !== 0) {
         throw new MemoryBrokerContractError(`command memory broker ${operation} failed: exit ${exitCode}${stderr.trim() ? ` ${stderr.trim()}` : ""}`);
       }
-      return unwrapResult(parseJson(stdout, operation));
+      return this.unwrapResult(this.parseJson(stdout, operation));
     } catch (error) {
       if (error instanceof MemoryBrokerContractError) throw error;
       throw new MemoryBrokerContractError(`command memory broker ${operation} failed: ${errMessage(error)}`);
@@ -111,48 +47,3 @@ export class CommandMemoryBroker implements MemoryBroker {
     }
   }
 }
-
-function parseJson(text: string, operation: string): unknown {
-  if (!text.trim()) return null;
-  try {
-    return JSON.parse(text);
-  } catch {
-    throw new MemoryBrokerContractError(`command memory broker ${operation} returned invalid JSON`);
-  }
-}
-
-function unwrapResult(payload: unknown): unknown {
-  if (isRecord(payload) && Object.hasOwn(payload, "error") && typeof payload.error === "string") {
-    throw new MemoryBrokerContractError(`command memory broker failed: ${payload.error}`);
-  }
-  if (isRecord(payload) && Object.hasOwn(payload, "result")) return payload.result;
-  return payload;
-}
-
-function normalizeMemoryList(value: unknown, ctx: MemoryBrokerContext): Memory[] {
-  if (Array.isArray(value)) return value.map((item) => normalizeMemory(item, { now: ctx.now }));
-  if (isRecord(value) && Array.isArray(value.memories)) return value.memories.map((item) => normalizeMemory(item, { now: ctx.now }));
-  throw new MemoryBrokerContractError("memory list-active result must be an array or object with memories array");
-}
-
-function normalizeStats(value: unknown): MemoryStats {
-  if (!isRecord(value)) throw new MemoryBrokerContractError("memory stats must be an object");
-  return {
-    total: numberField(value.total, "memory stats.total"),
-    byType: objectField(value.byType, "memory stats.byType"),
-    byScope: objectField(value.byScope, "memory stats.byScope"),
-    bySensitivity: objectField(value.bySensitivity, "memory stats.bySensitivity"),
-  } as MemoryStats;
-}
-
-function objectField(value: unknown, field: string): Record<string, number> {
-  if (!isRecord(value)) throw new MemoryBrokerContractError(`${field} must be an object`);
-  const out: Record<string, number> = {};
-  for (const [key, count] of Object.entries(value)) out[key] = numberField(count, `${field}.${key}`);
-  return out;
-}
-
-function numberField(value: unknown, field: string): number {
-  if (typeof value !== "number" || !Number.isFinite(value)) throw new MemoryBrokerContractError(`${field} must be a number`);
-  return value;
-}

package/src/memory-http-broker.ts

@@ -1,83 +1,22 @@
-import type {
-  ActiveMemoryClearReason,
-  ContextPackage,
-  ContextPackageRequest,
-  CreateMemoryInput,
-  HttpMemoryBrokerConfig,
-  Memory,
-  MemoryBrokerCapabilities,
-  MemoryBrokerContext,
-  MemoryQuery,
-  MemorySearchResult,
-  MemoryStats,
-  UpdateMemoryInput,
-} from "./types";
-import type { MemoryBroker } from "./memory-broker-contract";
-import {
-  MemoryBrokerContractError,
-  normalizeMemory,
-  normalizeMemoryBrokerCapabilities,
-  normalizeMemorySearchResult,
-} from "./memory-broker-contract";
+import type { HttpMemoryBrokerConfig } from "./types";
+import { MemoryBrokerContractError } from "./memory-broker-contract";
+import { AbstractMemoryBroker, DEFAULT_MEMORY_BROKER_TIMEOUT_MS } from "./memory-broker-base";
 import { errMessage, isRecord } from "agent-relay-sdk";
 
-const DEFAULT_TIMEOUT_MS = 10_000;
+export { normalizeContextPackage } from "./memory-broker-base";
 
-export class HttpMemoryBroker implements MemoryBroker {
+export class HttpMemoryBroker extends AbstractMemoryBroker {
+  protected readonly label = "http";
   private readonly baseUrl: string;
   private readonly timeoutMs: number;
 
   constructor(private readonly config: HttpMemoryBrokerConfig) {
+    super();
     this.baseUrl = config.url.replace(/\/+$/, "");
-    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.timeoutMs = config.timeoutMs ?? DEFAULT_MEMORY_BROKER_TIMEOUT_MS;
   }
 
-  async capabilities(): Promise<MemoryBrokerCapabilities> {
-    return normalizeMemoryBrokerCapabilities(await this.call("capabilities", {}));
-  }
-
-  async create(input: CreateMemoryInput, ctx: MemoryBrokerContext): Promise<Memory> {
-    return normalizeMemory(await this.call("create", { input, ctx }), { now: ctx.now });
-  }
-
-  async get(id: string, ctx: MemoryBrokerContext): Promise<Memory | null> {
-    const value = await this.call("get", { id, ctx });
-    return value === null ? null : normalizeMemory(value, { now: ctx.now });
-  }
-
-  async search(query: MemoryQuery, ctx: MemoryBrokerContext): Promise<MemorySearchResult> {
-    return normalizeMemorySearchResult(await this.call("search", { query, ctx }), { now: ctx.now });
-  }
-
-  async update(id: string, patch: UpdateMemoryInput, ctx: MemoryBrokerContext): Promise<Memory> {
-    return normalizeMemory(await this.call("update", { id, patch, ctx }), { now: ctx.now });
-  }
-
-  async delete(id: string, ctx: MemoryBrokerContext): Promise<void> {
-    await this.call("delete", { id, ctx });
-  }
-
-  async stats(ctx: MemoryBrokerContext): Promise<MemoryStats> {
-    return normalizeStats(await this.call("stats", { ctx }));
-  }
-
-  async assemble(request: ContextPackageRequest, ctx: MemoryBrokerContext): Promise<ContextPackage> {
-    return normalizeContextPackage(await this.call("assemble", { request, ctx }), ctx);
-  }
-
-  async markInjected(agentId: string, memoryIds: string[], ctx: MemoryBrokerContext): Promise<void> {
-    await this.call("mark-injected", { agentId, memoryIds, ctx });
-  }
-
-  async clearActive(agentId: string, reason: ActiveMemoryClearReason, ctx: MemoryBrokerContext): Promise<void> {
-    await this.call("clear-active", { agentId, reason, ctx });
-  }
-
-  async listActive(agentId: string, ctx: MemoryBrokerContext): Promise<Memory[]> {
-    return normalizeMemoryList(await this.call("list-active", { agentId, ctx }), ctx);
-  }
-
-  private async call(operation: string, body: Record<string, unknown>): Promise<unknown> {
+  protected async call(operation: string, body: Record<string, unknown>): Promise<unknown> {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), this.timeoutMs);
     try {
@@ -88,12 +27,12 @@ export class HttpMemoryBroker implements MemoryBroker {
         signal: controller.signal,
       });
       const text = await res.text();
-      const payload = parseJson(text, operation);
+      const payload = this.parseJson(text, operation);
       if (!res.ok) {
         const detail = isRecord(payload) && typeof payload.error === "string" ? payload.error : text.trim();
         throw new MemoryBrokerContractError(`http memory broker ${operation} failed: ${res.status}${detail ? ` ${detail}` : ""}`);
       }
-      return unwrapResult(payload);
+      return this.unwrapResult(payload);
     } catch (error) {
       if (error instanceof MemoryBrokerContractError) throw error;
       if (error instanceof DOMException && error.name === "AbortError") {
@@ -114,72 +53,3 @@ export class HttpMemoryBroker implements MemoryBroker {
     return headers;
   }
 }
-
-function parseJson(text: string, operation: string): unknown {
-  if (!text.trim()) return null;
-  try {
-    return JSON.parse(text);
-  } catch {
-    throw new MemoryBrokerContractError(`http memory broker ${operation} returned invalid JSON`);
-  }
-}
-
-function unwrapResult(payload: unknown): unknown {
-  if (isRecord(payload) && Object.hasOwn(payload, "result")) return payload.result;
-  return payload;
-}
-
-export function normalizeContextPackage(value: unknown, ctx: MemoryBrokerContext): ContextPackage {
-  const record = requireRecord(value, "context package");
-  const rawMemories = record.memories;
-  if (!Array.isArray(rawMemories)) throw new MemoryBrokerContractError("context package.memories must be an array");
-  return {
-    memories: rawMemories.map((item) => {
-      const packaged = requireRecord(item, "packaged memory");
-      const priority = packaged.priority;
-      if (priority !== 1 && priority !== 2 && priority !== 3) throw new MemoryBrokerContractError("packaged memory.priority must be 1, 2, or 3");
-      return {
-        memory: normalizeMemory(packaged.memory, { now: ctx.now }),
-        reason: typeof packaged.reason === "string" ? packaged.reason : "broker selected",
-        priority,
-        score: typeof packaged.score === "number" && Number.isFinite(packaged.score) ? packaged.score : undefined,
-      };
-    }),
-    estimatedTokens: typeof record.estimatedTokens === "number" && Number.isFinite(record.estimatedTokens) ? record.estimatedTokens : 0,
-    rolePrompt: typeof record.rolePrompt === "string" ? record.rolePrompt : undefined,
-    recentContext: typeof record.recentContext === "string" ? record.recentContext : undefined,
-  };
-}
-
-function normalizeMemoryList(value: unknown, ctx: MemoryBrokerContext): Memory[] {
-  if (Array.isArray(value)) return value.map((item) => normalizeMemory(item, { now: ctx.now }));
-  if (isRecord(value) && Array.isArray(value.memories)) return value.memories.map((item) => normalizeMemory(item, { now: ctx.now }));
-  throw new MemoryBrokerContractError("memory list-active result must be an array or object with memories array");
-}
-
-function normalizeStats(value: unknown): MemoryStats {
-  const record = requireRecord(value, "memory stats");
-  return {
-    total: numberField(record.total, "memory stats.total"),
-    byType: objectField(record.byType, "memory stats.byType"),
-    byScope: objectField(record.byScope, "memory stats.byScope"),
-    bySensitivity: objectField(record.bySensitivity, "memory stats.bySensitivity"),
-  } as MemoryStats;
-}
-
-function objectField(value: unknown, field: string): Record<string, number> {
-  const record = requireRecord(value, field);
-  const out: Record<string, number> = {};
-  for (const [key, count] of Object.entries(record)) out[key] = numberField(count, `${field}.${key}`);
-  return out;
-}
-
-function numberField(value: unknown, field: string): number {
-  if (typeof value !== "number" || !Number.isFinite(value)) throw new MemoryBrokerContractError(`${field} must be a number`);
-  return value;
-}
-
-function requireRecord(value: unknown, field: string): Record<string, unknown> {
-  if (!isRecord(value)) throw new MemoryBrokerContractError(`${field} must be an object`);
-  return value;
-}

package/src/notify.ts

@@ -0,0 +1,31 @@
+import { sendMessage } from "./db";
+import { emitNewMessage } from "./sse";
+import type { Message, MessageKind } from "./types";
+
+export interface SystemNotifyOptions {
+  subject?: string;
+  body: string;
+  payload?: Record<string, unknown>;
+  /** Defaults to "system" — a bypass-targeting kind that wakes the recipient like a prompt. */
+  kind?: MessageKind;
+  /** Sender id; defaults to "system". */
+  from?: string;
+}
+
+/**
+ * Post a system DM to one agent and fan it out over the bus. This is the one home for
+ * "relay tells an agent something happened" — store-ahead delivers it on next poll if the
+ * recipient is offline (#234). Used by the GC sweep (maintenance) and lifecycle events (#239).
+ */
+export function notifySystemMessage(to: string, opts: SystemNotifyOptions): Message {
+  const msg = sendMessage({
+    from: opts.from ?? "system",
+    to,
+    kind: opts.kind ?? "system",
+    subject: opts.subject,
+    body: opts.body,
+    payload: opts.payload,
+  });
+  emitNewMessage(msg);
+  return msg;
+}

package/src/routes.ts

@@ -139,6 +139,7 @@ import { createToken, deleteTokenProfile, getToken, getTokenProfile, listTokenPr
 import {
   getConnector,
   listConnectors,
+  markConnectorUnreachable,
   readConnectorConfig,
   registerConnectorManifest,
   runConnectorAction,
@@ -176,6 +177,7 @@ import {
   WORKSPACE_ACTIONS,
 } from "./workspace-actions";
 import { describeWorkspacePhase, landReceipt, TERMINAL_WORKSPACE_STATUSES } from "./workspace-phase";
+import { notifyBranchLanded } from "./branch-landed";
 import type { WorkspaceDiagnostics, WorkspaceGitState, WorkspaceRecord } from "./types";
 import {
   getComponentAuth,
@@ -2197,7 +2199,7 @@ function restartSpawnParamsForAgent(
   const policy = policyName ? getSpawnPolicy(policyName) : null;
   const requestedBy = opts.resumeId ? "dashboard-resume" : "dashboard-restart";
   if (policy) {
-    const params = { ...managedSpawnParams(policy.value, requestId), agentId: agent.id, requestedBy };
+    const params = { ...buildManagedSpawnParams(policy.value, requestId, { createdBy: "managed-agent" }), agentId: agent.id, requestedBy };
     return opts.resumeId ? withClaudeResumeParams(params, opts.resumeId, agent.id) : params;
   }
 
@@ -4477,6 +4479,9 @@ const patchCommand: Handler = async (req, params) => {
         const workspaceId = cleanString(command.result.workspaceId, "result.workspaceId", { max: 160 });
         const resultStatus = optionalEnum(command.result.status, "result.status", VALID_WORKSPACE_STATUSES) as WorkspaceStatus | undefined;
         if (workspaceId && resultStatus) {
+          // Snapshot the row BEFORE the recycle repoints `branch` (#206) — the landed
+          // branch name + author (#239 branch.landed push) come from this pre-mutation state.
+          const landedWorkspace = getWorkspace(workspaceId);
           updateWorkspaceStatus(workspaceId, resultStatus, {
             mergeResult: command.result,
             mergeCommandId: command.id,
@@ -4490,10 +4495,20 @@ const patchCommand: Handler = async (req, params) => {
           // Land-and-continue (#206): the worktree was recycled onto a fresh branch.
           // Repoint the row so the next merge targets the live branch, not the deleted one.
           const newBranch = cleanString(command.result.newBranch, "result.newBranch", { max: 240 });
+          const mergedSha = cleanString(command.result.mergedSha, "result.mergedSha", { max: 64 });
           if (newBranch) {
-            const mergedSha = cleanString(command.result.mergedSha, "result.mergedSha", { max: 64 });
             setWorkspaceBranch(workspaceId, newBranch, mergedSha);
           }
+          // #239 — push the author a "your branch landed" notice (no polling). Only on a
+          // real land; a no-op resolution (#230) merged nothing, so it earns no notice.
+          if (command.result.merged === true && landedWorkspace) {
+            notifyBranchLanded({
+              workspace: landedWorkspace,
+              mergedSha,
+              subject: cleanString(command.result.subject, "result.subject", { max: 200 }),
+              newBranch,
+            });
+          }
         }
       } else if (command.status === "failed" && command.correlationId) {
         // Merge couldn't complete — don't leave it stuck in merge_planned.
@@ -4811,11 +4826,6 @@ function policyStatusPayload(policy: SpawnPolicy) {
   };
 }
 
-function managedSpawnParams(policy: SpawnPolicy, requestId: string): Record<string, unknown> {
-  return buildManagedSpawnParams(policy, requestId, { createdBy: "managed-agent" });
-}
-
-
 function requirePolicyAndOrchestrator(name: string): { policy: SpawnPolicy; orch: NonNullable<ReturnType<typeof getOrchestrator>> } | Response {
   const entry = getSpawnPolicy(name);
   if (!entry) return error("spawn policy not found", 404);
@@ -4861,7 +4871,7 @@ function enqueuePolicyStart(policy: SpawnPolicy, reason: string): Command | Resp
     target: orch.agentId,
     correlationId: requestId,
     params: {
-      ...managedSpawnParams(policy, requestId),
+      ...buildManagedSpawnParams(policy, requestId, { createdBy: "managed-agent" }),
       reason,
       orchestratorId: orch.id,
     },
@@ -4875,7 +4885,7 @@ function enqueuePolicyStop(policy: SpawnPolicy, action: "shutdown" | "restart",
   if (!orch) return error("orchestrator not found", 404);
   const state = getManagedAgentState(policy.name);
   const restartRequestId = action === "restart" ? spawnRequestId() : undefined;
-  const restartSpawn = restartRequestId ? managedSpawnParams(policy, restartRequestId) : undefined;
+  const restartSpawn = restartRequestId ? buildManagedSpawnParams(policy, restartRequestId, { createdBy: "managed-agent" }) : undefined;
   const nextState = upsertManagedAgentState({
     policyName: policy.name,
     status: "stopping",
@@ -5784,6 +5794,13 @@ const postConnectorCall: Handler = async (req, params) => {
       headers: { "content-type": res.headers.get("content-type") || "application/json" },
     });
   } catch (e) {
+    // A connection error (refused/reset/DNS) means the advertised endpoint is
+    // genuinely down — reconcile the stale running:true so the dashboard stops
+    // claiming the connector is healthy. A timeout (AbortError) may just be a
+    // slow daemon, so leave its state alone.
+    if ((e as Error).name !== "AbortError") {
+      markConnectorUnreachable(params.id!, `endpoint unreachable: ${(e as Error).message}`);
+    }
     return error(`failed to reach connector: ${(e as Error).message}`, 502);
   }
 };