agent-relay-server 0.27.2 → 0.28.0

package/docs/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Relay API",
-    "version": "0.21.0",
+    "version": "0.27.2",
     "description": "Real-time message bus for inter-agent communication. Agent-first: this spec is designed for machine consumption — agents can self-discover the full API surface via GET /api/spec.",
     "license": {
       "name": "MIT",
@@ -7399,6 +7399,9 @@
                   "claimable": {
                     "type": "string"
                   },
+                  "replyExpected": {
+                    "type": "string"
+                  },
                   "from": {
                     "type": "string"
                   },
@@ -7460,6 +7463,16 @@
               }
             }
           },
+          "409": {
+            "description": "Conflict",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Error"
+                }
+              }
+            }
+          },
           "422": {
             "description": "Unprocessable entity",
             "content": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-server",
-  "version": "0.27.2",
+  "version": "0.28.0",
   "description": "Lightweight HTTP message relay for inter-agent communication across machines",
   "module": "src/index.ts",
   "type": "module",
@@ -33,7 +33,7 @@
     "CONTRIBUTING.md"
   ],
   "dependencies": {
-    "agent-relay-sdk": "0.2.16"
+    "agent-relay-sdk": "0.2.17"
   },
   "scripts": {
     "prepack": "bun run build:dashboard:bundle >&2",

package/public/index.html

@@ -10454,12 +10454,28 @@ function spaceDigits(frac) {
 	return frac.split("").join(" ");
 }
 /**
+* Spell a token one character at a time so the engine reads each symbol on its
+* own: digits stay as digits, letters are upper-cased so they're heard as the
+* letter name ("e" → "E" = "ee") rather than a syllable. Used for commit hashes
+* ("834543e" → "8 3 4 5 4 3 E") and acronyms ("id" → "I D").
+*/
+function spellOut(token) {
+	return token.split("").map((c) => /[0-9]/.test(c) ? c : c.toUpperCase()).join(" ");
+}
+/**
 * Ordered normalization rules. ORDER IS LOAD-BEARING:
 *  - URLs/paths first, before anything mangles their slashes/dots.
 *  - `~` → "approximately" before number rules consume the digits after it.
 *  - number ranges ("5-7") before unit expansion, so the unit attaches once: "5 to 7 seconds".
+*  - versions ("0.27.0") before decimals, so all dots become "dot" uniformly
+*    instead of the decimal rule eating only the first pair and stranding ".0".
 *  - decimals before unit expansion and before the sentence splitter sees the dot.
-*  - unit expansion last among the number rules.
+*  - commit-hash spelling before nothing in particular, but after decimals so a
+*    real number is never mistaken for a hash.
+*  - "id" acronym expansion (camelCase suffix before the standalone word).
+*  - unit expansion among the number rules.
+*  - interior-dot LAST, so it only mops up dots the structured rules left behind
+*    (identifiers like "branch.landed", "router.ts") — never a decimal or version.
 */
 var SPEECH_RULES = [
 	{
@@ -10472,6 +10488,11 @@ var SPEECH_RULES = [
 		pattern: /(?:\/[A-Za-z0-9._-]+){2,}\/?/g,
 		replace: (m) => " " + m.replace(/[/._-]+/g, " ").trim() + " "
 	},
+	{
+		name: "slash",
+		pattern: /(?<=[A-Za-z0-9])\/(?=[A-Za-z0-9])/g,
+		replace: " "
+	},
 	{
 		name: "func-call",
 		pattern: /\b([A-Za-z_$][\w$]*)\(\)/g,
@@ -10487,11 +10508,31 @@ var SPEECH_RULES = [
 		pattern: /(\d)\s*[-–—]\s*(?=\d)/g,
 		replace: "$1 to "
 	},
+	{
+		name: "version",
+		pattern: /\b(v?)(\d+(?:\.\d+){2,})\b/gi,
+		replace: (_m, v, nums) => `${v ? "version " : ""}${nums.replace(/\./g, " dot ")}`
+	},
 	{
 		name: "decimal",
 		pattern: /\b(\d+)\.(\d+)\b/g,
 		replace: (_m, i, f) => `${i} point ${spaceDigits(f)}`
 	},
+	{
+		name: "hash",
+		pattern: /\b(?=[0-9a-f]{7,40}\b)(?=[0-9a-f]*[a-f])(?=[0-9a-f]*\d)[0-9a-f]{7,40}\b/gi,
+		replace: (m) => spellOut(m)
+	},
+	{
+		name: "id-camel",
+		pattern: /([a-z])(Id|ID)(s)?\b/g,
+		replace: (_m, pre, _acr, plural) => `${pre} I D${plural ? "s" : ""}`
+	},
+	{
+		name: "id-word",
+		pattern: /\b(?:id|Id|ID)(s)?\b/g,
+		replace: (_m, plural) => `I D${plural ? "s" : ""}`
+	},
 	{
 		name: "byte-unit",
 		pattern: /\b(\d+)\s?(kb|mb|gb|tb)\b/gi,
@@ -10506,6 +10547,16 @@ var SPEECH_RULES = [
 		name: "s-unit",
 		pattern: /\b(\d{1,3})\s?s\b/g,
 		replace: (_m, n) => `${n} ${UNIT_WORDS.s}`
+	},
+	{
+		name: "live-adjective",
+		pattern: /\b(is|are|was|were|be|been|being|now|and|stays?|staying|went|go|goes|going|deployed|it's|that's|here's|there's|we're|you're|they're)\s+live\b/gi,
+		replace: (_m, cue) => `${cue} lyve`
+	},
+	{
+		name: "interior-dot",
+		pattern: /\.(?=[A-Za-z0-9])/g,
+		replace: " dot "
 	}
 ];
 /**
@@ -12255,6 +12306,7 @@ var useRelayStore = create$1()(persist((set, get) => ({
 	view: "overview",
 	showOffline: false,
 	showBuiltIns: false,
+	showReasoning: false,
 	autoRefresh: true,
 	voiceTtsEnabled: false,
 	voiceTtsLang: "en-US",
@@ -14610,6 +14662,7 @@ var useRelayStore = create$1()(persist((set, get) => ({
 		view: state.view,
 		showOffline: state.showOffline,
 		showBuiltIns: state.showBuiltIns,
+		showReasoning: state.showReasoning,
 		autoRefresh: state.autoRefresh,
 		voiceTtsEnabled: state.voiceTtsEnabled,
 		voiceTtsLang: state.voiceTtsLang,
@@ -128013,15 +128066,20 @@ function BusyIndicator({ blockedLabel, onInterrupt }) {
 		})
 	});
 }
-function ActivityTrace({ steps }) {
+function ActivityTrace({ steps, showReasoning }) {
 	const [hideTools, setHideTools] = (0, import_react.useState)(false);
-	if (!steps.length) return null;
-	const toolCount = steps.filter((s) => s.kind === "tool").length;
+	const visible = showReasoning ? steps : steps.filter((s) => s.kind !== "reasoning");
+	if (!visible.length) return null;
+	const toolCount = visible.filter((s) => s.kind === "tool").length;
 	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", {
 		className: "flex justify-start mb-2",
 		children: /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", {
 			className: "max-w-[85%] md:max-w-[75%] min-w-0 space-y-1.5",
-			children: [steps.map((step) => {
+			children: [visible.map((step) => {
+				if (step.kind === "narration") return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", {
+					className: "text-sm leading-relaxed whitespace-pre-wrap break-words text-foreground/90 min-w-0",
+					children: step.text
+				}, step.id);
 				if (step.kind === "reasoning") return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", {
 					className: "flex items-start gap-1.5 text-xs leading-relaxed text-muted-foreground/80",
 					children: [/* @__PURE__ */ (0, import_jsx_runtime.jsx)(Brain, { className: "w-3.5 h-3.5 mt-0.5 shrink-0 opacity-70" }), /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", {
@@ -128826,7 +128884,7 @@ var MessageBubble = (0, import_react.memo)(function MessageBubble({ msg, peer, o
 function sessionActivityStep(msg) {
 	if (msg.kind !== "session") return null;
 	const s = msg.payload?.session;
-	if (!s || s.type !== "reasoning" && s.type !== "tool") return null;
+	if (!s || s.type !== "narration" && s.type !== "reasoning" && s.type !== "tool") return null;
 	return {
 		id: msg.id,
 		kind: s.type,
@@ -128911,10 +128969,17 @@ function buildTimeline(messages, statusEvents, createdAt, importedHistory = [])
 			}
 		});
 	}
+	const responseKeys = /* @__PURE__ */ new Set();
+	for (const msg of messages) {
+		if (msg.kind !== "session") continue;
+		const s = msg.payload?.session;
+		if (s?.type === "response" && typeof s.turnId === "string") responseKeys.add(`${s.turnId} ${msg.body.trim()}`);
+	}
 	for (const msg of messages) {
 		if (isReactionEvent(msg)) continue;
 		const step = sessionActivityStep(msg);
 		if (step) {
+			if (step.kind === "narration" && step.turnId && responseKeys.has(`${step.turnId} ${step.text.trim()}`)) continue;
 			raw.push({
 				ts: step.ts,
 				entry: {
@@ -129112,6 +129177,7 @@ function ChatPanel({ threads, onBack, showBackButton }) {
 	const showError = useRelayStore((s) => s.showError);
 	const orchestrators = useRelayStore((s) => s.orchestrators);
 	const fetchOrchestrators = useRelayStore((s) => s.fetchOrchestrators);
+	const showReasoning = useRelayStore((s) => s.showReasoning);
 	const voiceTtsEnabled = useRelayStore((s) => s.voiceTtsEnabled);
 	const setVoiceTtsEnabled = useRelayStore((s) => s.setVoiceTtsEnabled);
 	const voiceInputMode = useRelayStore((s) => s.voiceInputMode);
@@ -129689,7 +129755,10 @@ function ChatPanel({ threads, onBack, showBackButton }) {
 									onPreviewReferencedPath: previewReferencedFile,
 									onPreviewReferencedPathEnd: scheduleCloseReferencedFilePreview
 								}, entry.msg.id);
-								if (entry.type === "activity") return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ActivityTrace, { steps: entry.steps }, `act-${entry.steps[0]?.id ?? entry.timestamp}`);
+								if (entry.type === "activity") return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ActivityTrace, {
+									steps: entry.steps,
+									showReasoning
+								}, `act-${entry.steps[0]?.id ?? entry.timestamp}`);
 								if (entry.type === "import-boundary") return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ImportedHistoryMarker, { history: entry.history }, `import-${entry.history.id}`);
 								if (entry.type === "imported-message") return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(ImportedMessageBubble, {
 									entry: entry.entry,
@@ -156013,6 +156082,7 @@ function SettingsView() {
 					]
 				})]
 			}),
+			/* @__PURE__ */ (0, import_jsx_runtime.jsx)(ChatDisplaySettings, {}),
 			/* @__PURE__ */ (0, import_jsx_runtime.jsx)(WorkspaceSettings, {}),
 			/* @__PURE__ */ (0, import_jsx_runtime.jsx)(StewardSettings, {}),
 			/* @__PURE__ */ (0, import_jsx_runtime.jsx)(VoiceSettings, {})
@@ -156087,6 +156157,29 @@ function WorkspaceSettings() {
 		]
 	});
 }
+function ChatDisplaySettings() {
+	const showReasoning = useRelayStore((s) => s.showReasoning);
+	const set = useRelayStore((s) => s.set);
+	return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("section", {
+		className: "space-y-3 rounded-lg border p-4",
+		children: /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", {
+			className: "flex items-center justify-between gap-2",
+			children: [/* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", {
+				className: "flex items-center gap-2",
+				children: [/* @__PURE__ */ (0, import_jsx_runtime.jsx)(Brain, { className: "w-4 h-4" }), /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("div", { children: [/* @__PURE__ */ (0, import_jsx_runtime.jsx)("h2", {
+					className: "text-sm font-semibold",
+					children: "Show reasoning details"
+				}), /* @__PURE__ */ (0, import_jsx_runtime.jsx)("p", {
+					className: "text-xs text-muted-foreground",
+					children: "Show the agent's internal thinking inline in chat, alongside its narration and tool steps. Off by default — narration is always shown either way."
+				})] })]
+			}), /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Switch, {
+				checked: showReasoning,
+				onCheckedChange: (v) => set({ showReasoning: v })
+			})]
+		})
+	});
+}
 function VoiceSettings() {
 	const voiceTtsEnabled = useRelayStore((s) => s.voiceTtsEnabled);
 	const setVoiceTtsEnabled = useRelayStore((s) => s.setVoiceTtsEnabled);
@@ -164034,6 +164127,16 @@ if ("serviceWorker" in navigator) {
     }
   }
 
+  .text-foreground\/90 {
+    color: var(--foreground);
+  }
+
+  @supports (color: color-mix(in lab, red, red)) {
+    .text-foreground\/90 {
+      color: color-mix(in oklab, var(--foreground) 90%, transparent);
+    }
+  }
+
   .text-green-400 {
     color: var(--color-green-400);
   }

package/runner/src/adapter.ts

@@ -211,9 +211,19 @@ function isPersistedRelayMessage(message: Message): boolean {
   return Number.isSafeInteger(message.id) && message.id > 0;
 }
 
+// #283 — one-line nudge that replaces the reply-scaffold footer for notification-class
+// (replyExpected:false) messages. Deliberately tiny so a bloated context can't drown the
+// no-reply rule established at session start. Shared with the Claude delivery path.
+export const NOTIFICATION_NUDGE = "↪ Notification — no reply needed.";
+
+// A notification is a persisted message the server marked replyExpected:false.
+export function isNotificationMessage(message: Message): boolean {
+  return isPersistedRelayMessage(message) && message.replyExpected === false;
+}
+
 function latestReplyableMessage(messages: Message[]): Message | undefined {
   return messages
-    .filter((message) => isPersistedRelayMessage(message) && !isMemoryInjection(message) && !isReactionNotification(message))
+    .filter((message) => isPersistedRelayMessage(message) && !isMemoryInjection(message) && !isReactionNotification(message) && message.replyExpected !== false)
     .at(-1);
 }
 
@@ -316,6 +326,9 @@ export function providerMessageText(messages: Message[]): string {
       "If you already delivered the useful response through Relay, do not send a separate status-only confirmation.",
       "If multiple messages arrived together, cover them in one reply instead of answering each line separately.",
     ].join("\n"));
+  } else if (messages.some(isNotificationMessage)) {
+    // #283 — pure notification batch: no scaffold, just the one-line no-reply nudge.
+    sections.push(NOTIFICATION_NUDGE);
   }
   return sections.join("\n\n");
 }

package/src/branch-landed.ts

@@ -78,6 +78,7 @@ export function notifyBranchLanded(input: BranchLandedInput): void {
       subject: "Your branch landed",
       body: `✅ ${branchLabel} landed on \`${base}\`${shaLabel}${subjectLabel}.${continueLabel}`,
       payload,
+      replyExpected: false,
     });
   }
 
@@ -93,6 +94,7 @@ export function notifyBranchLanded(input: BranchLandedInput): void {
       subject: `Merged to ${base}`,
       body: `🔀 ${branchLabel}${authorLabel} merged to \`${base}\`${shaLabel}${subjectLabel}.`,
       payload,
+      replyExpected: false,
     });
   }
 }

package/src/db.ts

@@ -226,6 +226,7 @@ export function initDb(path: string = "agent-relay.db"): Database {
       body TEXT NOT NULL,
       thread_id INTEGER,
       reply_to INTEGER REFERENCES messages(id),
+      reply_expected INTEGER NOT NULL DEFAULT 1,
       claimable INTEGER NOT NULL DEFAULT 0,
       claimed_by TEXT,
       claimed_at INTEGER,
@@ -857,6 +858,9 @@ export function initDb(path: string = "agent-relay.db"): Database {
     db.run("ALTER TABLE messages ADD COLUMN thread_id INTEGER");
     db.run("ALTER TABLE messages ADD COLUMN reply_to INTEGER REFERENCES messages(id)");
   }
+  if (!colNames.includes("reply_expected")) {
+    db.run("ALTER TABLE messages ADD COLUMN reply_expected INTEGER NOT NULL DEFAULT 1");
+  }
   if (!colNames.includes("claimable")) {
     db.run("ALTER TABLE messages ADD COLUMN claimable INTEGER NOT NULL DEFAULT 0");
     db.run("ALTER TABLE messages ADD COLUMN claimed_by TEXT");
@@ -1292,6 +1296,9 @@ function rowToMessage(row: any): Message {
     body: row.body,
     threadId: row.thread_id ?? undefined,
     replyTo: row.reply_to ?? undefined,
+    // Default (true) stays absent to match the `claimable` idiom and keep notification-free
+    // messages byte-identical on the wire; only an explicit notification surfaces false (#283).
+    replyExpected: row.reply_expected === 0 ? false : undefined,
     claimable: row.claimable === 1 ? true : undefined,
     claimedBy: row.claimed_by ?? undefined,
     claimedAt: row.claimed_at ?? undefined,
@@ -3794,12 +3801,12 @@ export function sendMessageWithResult(input: SendMessageInput): { message: Messa
 
   const insert = db.query(`
     INSERT INTO messages (
-      from_agent, to_target, kind, channel, subject, body, thread_id, reply_to, claimable,
+      from_agent, to_target, kind, channel, subject, body, thread_id, reply_to, reply_expected, claimable,
       idempotency_key, delivery_status, queued_at, max_age_seconds, resolved_to_agent,
       payload, meta, created_at, occurred_at
     )
     VALUES (
-      $from, $to, $kind, $channel, $subject, $body, $threadId, $replyTo, $claimable,
+      $from, $to, $kind, $channel, $subject, $body, $threadId, $replyTo, $replyExpected, $claimable,
       $idempotencyKey, $deliveryStatus, $queuedAt, $maxAgeSeconds, $resolvedToAgent,
       $payload, $meta, $now, $occurredAt
     )
@@ -3833,6 +3840,9 @@ export function sendMessageWithResult(input: SendMessageInput): { message: Messa
       $body: input.body,
       $threadId: threadId,
       $replyTo: input.replyTo ?? null,
+      // Server-owned reply obligation (#283): true by default; only an explicit false marks
+      // a notification. Stored 0/1 so the footer renderer + reply tracker key off one column.
+      $replyExpected: input.replyExpected === false ? 0 : 1,
       $claimable: claimable ? 1 : 0,
       $idempotencyKey: input.idempotencyKey ?? null,
       $deliveryStatus: deliveryStatus,
@@ -4318,6 +4328,9 @@ export function pollMessages(query: PollQuery): Message[] {
 }
 
 function messageRequiresReply(message: Message): boolean {
+  // Server-owned notification flag (#283) wins over every kind/sender heuristic below: an
+  // explicit replyExpected:false is a fire-and-forget message that must never become an obligation.
+  if (message.replyExpected === false) return false;
   if (message.kind === "system" || message.kind === "control" || message.kind === "session") return false;
   if (message.from === "user") return true;
   if (message.kind === "task" || message.kind === "channel.event") return true;

package/src/mcp.ts

@@ -247,19 +247,19 @@ const TOOLS: ToolDefinition[] = [
   },
   {
     name: "relay_spawn_agent",
-    description: "Spawn a long-living provider agent through Relay's orchestrator. Gated: requires the command:spawn scope, granted only to agents whose profile sets maxSpawnedAgents>0, up to that live-children quota. Spawned agents cannot themselves spawn (no grandchildren).",
+    description: "Spawn a long-living provider agent through Relay's orchestrator, optionally handing it its first task via `prompt` in the same call. Defaults to your own host (override with orchestratorId) and returns the resolved agent id once it registers. Gated: requires the command:spawn scope, granted only to agents whose profile sets maxSpawnedAgents>0, up to that live-children quota. Spawned agents cannot themselves spawn (no grandchildren).",
     requiredScopes: ["command:spawn"],
     inputSchema: {
       type: "object",
       properties: {
         provider: { type: "string", enum: SPAWN_PROVIDERS },
-        orchestratorId: { type: "string" },
-        cwd: { type: "string" },
+        orchestratorId: { type: "string", description: "Target host. Defaults to the host that owns cwd, else YOUR OWN host — only set it to spawn onto a different machine." },
+        cwd: { type: "string", description: "Working directory for the agent. Must resolve within the target orchestrator's base directory (enforced server-side)." },
         label: { type: "string" },
         model: { type: "string" },
         effort: { type: "string", enum: VALID_EFFORTS },
         approvalMode: { type: "string", enum: APPROVAL_MODES },
-        prompt: { type: "string" },
+        prompt: { type: "string", description: "Initial task/message delivered to the agent on launch — spawn and hand it its first instruction in one call (no separate follow-up message needed)." },
         systemPromptAppend: { type: "string" },
         profile: { type: "string", description: "Agent profile name to apply (env, instructions, permissions, MCP/skills, spawn quota)." },
         tags: { type: "array", items: { type: "string" } },
@@ -267,6 +267,7 @@ const TOOLS: ToolDefinition[] = [
         providerArgs: { type: "array", items: { type: "string" } },
         policyName: { type: "string" },
         spawnRequestId: { type: "string" },
+        waitForRegistrationMs: { type: "integer", minimum: 0, maximum: 30000, description: "How long to wait for the spawned agent to register before returning, so the response carries its resolved agent id (default 8000; 0 = return immediately with just spawnRequestId)." },
       },
       required: ["provider"],
       additionalProperties: false,
@@ -485,7 +486,7 @@ async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<s
     else if (name === "relay_agent_status") result = relayAgentStatus(args);
     else if (name === "relay_find_agents") result = relayFindAgents(auth, args);
     else if (name === "relay_whoami") result = relayWhoami(auth);
-    else if (name === "relay_spawn_agent") result = relaySpawnAgent(auth, args);
+    else if (name === "relay_spawn_agent") result = await relaySpawnAgent(auth, args);
     else if (name === "relay_shutdown_agent") result = relayShutdownAgent(auth, args);
     else if (name === "relay_workspace_status") result = await relayWorkspaceStatus(auth, args);
     else if (name === "relay_workspace_list") result = relayWorkspaceList(auth, args);
@@ -763,10 +764,12 @@ function relayFindAgents(auth: McpAuthContext, args: Record<string, unknown>): R
   return { agents, count: agents.length };
 }
 
-function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
+async function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknown>): Promise<Record<string, unknown>> {
   const provider = enumField(args.provider, "provider", SPAWN_PROVIDERS) as SpawnProvider;
   const cwd = optionalString(args.cwd, "cwd", 500);
-  const orchestrator = selectSpawnOrchestrator(provider, optionalString(args.orchestratorId, "orchestratorId", 200), cwd);
+  const callerId = callerAgentId(auth);
+  const preferHost = callerId ? getAgent(callerId)?.machine : undefined;
+  const orchestrator = selectSpawnOrchestrator(provider, optionalString(args.orchestratorId, "orchestratorId", 200), cwd, preferHost);
   const resolvedCwd = cwd || orchestrator.baseDir;
   if (cwd && !isPathWithinBase(cwd, orchestrator.baseDir)) {
     throw new ValidationError(`cwd must be within orchestrator base directory: ${orchestrator.baseDir}`);
@@ -781,7 +784,6 @@ function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknown>): R
   // #221 runtime gate (belt; the coarse `command:spawn` scope is enforced in callTool, and is
   // granted only to agents whose profile sets maxSpawnedAgents>0 and never to children).
   // Server/admin tokens have no caller identity → unrestricted by design.
-  const callerId = callerAgentId(auth);
   if (callerId) {
     const me = getAgent(callerId);
     if (me?.spawnedBy) {
@@ -841,7 +843,27 @@ function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknown>): R
     }),
   });
   emitCommand(command);
-  return { ok: true, orchestratorId: orchestrator.id, provider, command };
+
+  // #255: resolve the spawned agent id once it registers. Spawn is a fire-and-forget command
+  // over the bus; the child registers back to THIS relay (same DB) with meta.spawnRequestId set,
+  // so a bounded poll links the request to the agent without a separate relay_find_agents round
+  // trip. waitForRegistrationMs:0 opts out (pure fire-and-forget); the default is short because
+  // isolated-worktree spawns register near-instantly (symlinked deps).
+  const waitMs = Math.min(optionalNonNegativeInt(args.waitForRegistrationMs, "waitForRegistrationMs") ?? 8000, 30000);
+  const agentId = waitMs > 0 ? await waitForSpawnedAgent(spawnRequestId, waitMs) : null;
+  return { ok: true, spawnRequestId, orchestratorId: orchestrator.id, provider, agentId, registered: agentId !== null, command };
+}
+
+// Poll the agents table for the child that registers with this spawnRequestId (#255). Returns
+// the resolved agent id, or null on timeout (the caller still has spawnRequestId to poll later).
+async function waitForSpawnedAgent(spawnRequestId: string, timeoutMs: number, pollMs = 300): Promise<string | null> {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const match = listAgents().find((a) => a.meta?.spawnRequestId === spawnRequestId);
+    if (match) return match.id;
+    if (Date.now() >= deadline) return null;
+    await new Promise<void>((resolve) => setTimeout(resolve, Math.min(pollMs, Math.max(0, deadline - Date.now()))));
+  }
 }
 
 function relayShutdownAgent(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
@@ -1062,7 +1084,12 @@ function policyStatusPayload(policy: NonNullable<ReturnType<typeof getSpawnPolic
   };
 }
 
-function selectSpawnOrchestrator(provider: SpawnProvider, orchestratorId?: string, cwd?: string): NonNullable<ReturnType<typeof getOrchestrator>> {
+function selectSpawnOrchestrator(
+  provider: SpawnProvider,
+  orchestratorId?: string,
+  cwd?: string,
+  preferHost?: string,
+): NonNullable<ReturnType<typeof getOrchestrator>> {
   if (orchestratorId) {
     const orchestrator = getOrchestrator(orchestratorId);
     if (!orchestrator) throw new McpNotFoundError(`orchestrator ${orchestratorId} not found`);
@@ -1075,6 +1102,14 @@ function selectSpawnOrchestrator(provider: SpawnProvider, orchestratorId?: strin
     const match = candidates.find((item) => isPathWithinBase(cwd, item.baseDir));
     if (match) return match;
   }
+  // #255: with neither an explicit id nor a cwd to pin the host, default to the CALLER's own
+  // host instead of silently grabbing candidates[0] (a foreign host whose baseDir would then
+  // reject the caller's cwd — the footgun the spawn recipe warned about). An agent's `machine`
+  // is its OS hostname; match it against the orchestrator hostname (or id, defensively).
+  if (preferHost) {
+    const own = candidates.find((item) => item.hostname === preferHost || item.id === preferHost);
+    if (own) return own;
+  }
   const orchestrator = candidates[0];
   if (!orchestrator) throw new McpNotFoundError(`no orchestrator available for provider: ${provider}`);
   return orchestrator;
@@ -1327,6 +1362,12 @@ function optionalPositiveInt(value: unknown, field: string): number | undefined
   return value;
 }
 
+function optionalNonNegativeInt(value: unknown, field: string): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new ValidationError(`${field} must be a non-negative integer`);
+  return value;
+}
+
 function optionalFutureTimestamp(value: unknown, field: string): number | undefined {
   const timestamp = optionalPositiveInt(value, field);
   if (timestamp !== undefined && timestamp <= Date.now()) throw new ValidationError(`${field} must be a future unix timestamp in milliseconds`);

package/src/notify.ts

@@ -10,6 +10,13 @@ export interface SystemNotifyOptions {
   kind?: MessageKind;
   /** Sender id; defaults to "system". */
   from?: string;
+  /**
+   * #283 — set false for a fire-and-forget notification (merge notice, lifecycle event): the
+   * server suppresses the reply-scaffold footer and the reply-obligation tracker skips it.
+   * Omit (default true) for system messages that genuinely want the agent to act/answer
+   * (steward task assignments, conflict handoffs).
+   */
+  replyExpected?: boolean;
 }
 
 /**
@@ -25,6 +32,7 @@ export function notifySystemMessage(to: string, opts: SystemNotifyOptions): Mess
     subject: opts.subject,
     body: opts.body,
     payload: opts.payload,
+    replyExpected: opts.replyExpected,
   });
   emitNewMessage(msg);
   return msg;

package/src/routes.ts

@@ -520,6 +520,9 @@ function normalizeMessageInput(body: unknown): SendMessageInput {
   if (body.claimable !== undefined && typeof body.claimable !== "boolean") {
     throw new ValidationError("claimable must be a boolean");
   }
+  if (body.replyExpected !== undefined && typeof body.replyExpected !== "boolean") {
+    throw new ValidationError("replyExpected must be a boolean");
+  }
 
   const input: SendMessageInput = {
     from: cleanString(body.from, "from", { required: true, max: 200 })!,
@@ -527,6 +530,7 @@ function normalizeMessageInput(body: unknown): SendMessageInput {
     body: cleanString(body.body, "body", { required: true, max: MAX_BODY_BYTES })!,
     kind: kind as SendMessageInput["kind"] | undefined,
     replyTo: cleanPositiveId(body.replyTo, "replyTo"),
+    replyExpected: body.replyExpected as boolean | undefined,
     claimable: body.claimable as boolean | undefined,
     idempotencyKey: cleanString(body.idempotencyKey, "idempotencyKey", { max: 240 }),
   };