agent-relay-server 0.27.2 → 0.29.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.29.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.18"
   },
   "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,54 @@ function BusyIndicator({ blockedLabel, onInterrupt }) {
 		})
 	});
 }
-function ActivityTrace({ steps }) {
-	const [hideTools, setHideTools] = (0, import_react.useState)(false);
-	if (!steps.length) return null;
-	const toolCount = steps.filter((s) => s.kind === "tool").length;
+var HIDE_TOOLS_KEY = "agent-relay:chat-hide-tools";
+var hideToolsStore = (() => {
+	const listeners = /* @__PURE__ */ new Set();
+	let value = (() => {
+		try {
+			return window.localStorage.getItem(HIDE_TOOLS_KEY) === "on";
+		} catch {
+			return false;
+		}
+	})();
+	const emit = () => listeners.forEach((l) => l());
+	if (typeof window !== "undefined") window.addEventListener("storage", (e) => {
+		if (e.key !== HIDE_TOOLS_KEY) return;
+		value = e.newValue === "on";
+		emit();
+	});
+	return {
+		subscribe(cb) {
+			listeners.add(cb);
+			return () => listeners.delete(cb);
+		},
+		get: () => value,
+		toggle() {
+			value = !value;
+			try {
+				window.localStorage.setItem(HIDE_TOOLS_KEY, value ? "on" : "off");
+			} catch {}
+			emit();
+		}
+	};
+})();
+function useHideTools() {
+	return [(0, import_react.useSyncExternalStore)(hideToolsStore.subscribe, hideToolsStore.get, () => false), hideToolsStore.toggle];
+}
+function ActivityTrace({ steps, showReasoning }) {
+	const [hideTools, toggleHideTools] = useHideTools();
+	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", {
@@ -128044,7 +128136,7 @@ function ActivityTrace({ steps }) {
 					})]
 				}, step.id);
 			}), toolCount > 0 && /* @__PURE__ */ (0, import_jsx_runtime.jsxs)("button", {
-				onClick: () => setHideTools((v) => !v),
+				onClick: toggleHideTools,
 				className: "flex items-center gap-1 text-[11px] text-muted-foreground/50 hover:text-muted-foreground transition-colors text-left",
 				children: [/* @__PURE__ */ (0, import_jsx_runtime.jsx)(ChevronRight, { className: cn$2("w-3 h-3 shrink-0 transition-transform", !hideTools && "rotate-90") }), /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { children: hideTools ? `show ${toolCount} tool step${toolCount === 1 ? "" : "s"}` : "hide tool steps" })]
 			})]
@@ -128826,7 +128918,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 +129003,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 +129211,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 +129789,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 +156116,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 +156191,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 +164161,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/agent-ref.ts

@@ -14,14 +14,14 @@
 import { STALE_TTL_MS } from "./config";
 import type { AgentCard } from "./types";
 
-export interface ResolveOptions {
+interface ResolveOptions {
   /** Exclude this agent id from matches (e.g. the requester, when pairing). */
   excludeId?: string;
   /** Clock injection for tests. */
   now?: number;
 }
 
-export type ResolveResult =
+type ResolveResult =
   | { status: "resolved"; agent: AgentCard }
   | { status: "ambiguous"; candidates: AgentCard[] }
   | { status: "not_found"; offlineMatches: AgentCard[] };
@@ -136,7 +136,7 @@ export interface DeliveryReceipt {
   reason?: string;
 }
 
-export type SendPlan =
+type SendPlan =
   // resolved/fan-out/passthrough carry the (possibly rewritten) canonical `to`
   | { kind: "direct" | "fanout" | "passthrough"; to: string; receipt: DeliveryReceipt }
   | { kind: "not_found"; message: string }

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/cli.ts

@@ -44,7 +44,7 @@ import {
 } from "./upgrade";
 import { formatMemoryBrokerSmokeResult, runMemoryBrokerSmoke } from "./memory-broker-smoke";
 import { MAX_BODY_BYTES, VERSION } from "./config";
-import { DEFAULT_CONTEXT_PROBE_STATE_DIR, runContextProbe } from "agent-relay-sdk/context-probe";
+import { runContextProbe } from "agent-relay-sdk/context-probe";
 import { shellQuote } from "agent-relay-sdk/shell-utils";
 import { errMessage, RELAY_TOKEN_HEADER } from "agent-relay-sdk";
 import type { WorkspaceDepsRefreshResult } from "agent-relay-sdk";
@@ -686,7 +686,7 @@ async function handleContextProbeCommand(args: string[]): Promise<void> {
   let wrapCommand: string | undefined;
   let wrapRequested = false;
   let agentId: string | undefined;
-  let stateDir = DEFAULT_CONTEXT_PROBE_STATE_DIR;
+  let stateDir: string | undefined;
   let standalone = false;
 
   for (let i = 0; i < inputArgs.length; i++) {
@@ -718,7 +718,7 @@ async function handleContextProbeCommand(args: string[]): Promise<void> {
       "context-probe",
       ...(wrapRequested ? ["--wrap", ...(wrapCommand ? [shellQuote(wrapCommand)] : [])] : ["--standalone"]),
       ...(agentId ? ["--agent-id", shellQuote(agentId)] : []),
-      ...(stateDir !== DEFAULT_CONTEXT_PROBE_STATE_DIR ? ["--state-dir", shellQuote(stateDir)] : []),
+      ...(stateDir ? ["--state-dir", shellQuote(stateDir)] : []),
     ].join(" ");
     console.log(command);
     return;

package/src/contracts.ts

@@ -21,7 +21,7 @@ export interface RuntimePackageMetadata {
   version: string;
 }
 
-export interface ContractRequirement {
+interface ContractRequirement {
   min: number;
   maxExclusive: number;
 }

package/src/db.ts

@@ -1,6 +1,6 @@
 import { Database } from "bun:sqlite";
 import { randomUUID } from "node:crypto";
-import { isRecord, stringValue } from "agent-relay-sdk";
+import { isRecord, stringValue, isMechanicalMessageKind } from "agent-relay-sdk";
 import { ORCHESTRATOR_PROTOCOL_VERSION, VERSION } from "./config.ts";
 import { parseJson } from "./utils";
 import {
@@ -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,7 +4328,10 @@ export function pollMessages(query: PollQuery): Message[] {
 }
 
 function messageRequiresReply(message: Message): boolean {
-  if (message.kind === "system" || message.kind === "control" || message.kind === "session") return false;
+  // 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 (isMechanicalMessageKind(message.kind)) return false;
   if (message.from === "user") return true;
   if (message.kind === "task" || message.kind === "channel.event") return true;
   return Boolean(message.payload?.source);
@@ -4780,7 +4793,7 @@ export type AnalyticsPeriod = keyof typeof ANALYTICS_PERIODS;
 // Message → category, the ONE place this mapping lives (server-side SQL). Order is
 // significant: a claimable/system/pair/channel message is classified as such even
 // when it is also a reply; only an otherwise-plain reply counts as "Replies".
-export const ANALYTICS_CATEGORIES = ["Messages", "Replies", "Work items", "System", "Pair", "Channel"] as const;
+const ANALYTICS_CATEGORIES = ["Messages", "Replies", "Work items", "System", "Pair", "Channel"] as const;
 export type AnalyticsCategory = (typeof ANALYTICS_CATEGORIES)[number];
 const ANALYTICS_CATEGORY_SQL = `
   CASE
@@ -5440,7 +5453,7 @@ export function setWorkspaceBranch(id: string, branch: string, baseSha?: string)
 // of these is a candidate steward; the repo is worth coordinating.
 const STEWARD_LIVE_STATUSES = "'active', 'ready', 'conflict', 'review_requested', 'merge_planned'";
 
-export interface RepoStewardRecord {
+interface RepoStewardRecord {
   repoRoot: string;
   stewardAgentId?: string;
   lastStewardAgentId?: string;
@@ -5557,7 +5570,7 @@ function electWorkspaceStewardsForAgent(agentId: string): void {
 
 // --- Per-repo merge serialization lease (issue #157) -----------------------
 
-export interface MergeLeaseRecord {
+interface MergeLeaseRecord {
   repoRoot: string;
   workspaceId: string;
   commandId?: string;

package/src/http-body.ts

@@ -1,5 +1,5 @@
 /** Concatenate body chunks into a single contiguous Uint8Array. */
-export function concatBytes(chunks: Uint8Array[]): Uint8Array {
+function concatBytes(chunks: Uint8Array[]): Uint8Array {
   const total = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
   const output = new Uint8Array(total);
   let offset = 0;

package/src/insights-db.ts

@@ -46,7 +46,7 @@ function rowToObservation(row: ObservationRow): InsightObservation {
   };
 }
 
-export interface RecordObservationInput {
+interface RecordObservationInput {
   sessionId: string;
   agentId?: string;
   project?: string;
@@ -99,7 +99,7 @@ export function getObservation(id: number): InsightObservation | null {
   return row ? rowToObservation(row) : null;
 }
 
-export interface ListObservationsQuery {
+interface ListObservationsQuery {
   project?: string;
   signal?: string;
   sessionId?: string;

package/src/lifecycle-manager.ts

@@ -8,6 +8,7 @@ import {
   upsertManagedAgentState,
 } from "./config-store";
 import { emitRelayEvent } from "./events";
+import { emitMessageDeliveryUpdated } from "./sse";
 import { emitCommandEvent } from "./command-events";
 import { buildManagedSpawnParams } from "./managed-policy";
 import { generateSpawnRequestId } from "./spawn-command";
@@ -95,6 +96,9 @@ export class LifecycleManager {
         subject: `policy:${meta.policyName}`,
         data: { policyName: meta.policyName, agentId, messageIds: available.map((message) => message.id), count: available.length },
       });
+      // queued → pending changed delivery_status; refresh the dashboard delivery
+      // badge now rather than letting it sit stale until the next poll (#265).
+      for (const message of available) emitMessageDeliveryUpdated(message);
     }
   }
 

package/src/managed-policy.ts

@@ -20,7 +20,7 @@ export function effectiveManagedPolicyWorkspaceMode(policy: SpawnPolicy): Worksp
   return policy.binding?.type === "channel" ? "shared" : "inherit";
 }
 
-export interface ManagedSpawnContext {
+interface ManagedSpawnContext {
   createdBy: string;
   requestedAt?: number;
 }

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

@@ -2,7 +2,7 @@ import { sendMessage } from "./db";
 import { emitNewMessage } from "./sse";
 import type { Message, MessageKind } from "./types";
 
-export interface SystemNotifyOptions {
+interface SystemNotifyOptions {
   subject?: string;
   body: string;
   payload?: Record<string, unknown>;
@@ -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/orchestrator-lookup.ts

@@ -1,6 +1,6 @@
 import { listOrchestrators } from "./db";
 
-export interface ManagedAgentMatch {
+interface ManagedAgentMatch {
   agentId?: string;
   sessionName?: string;
   tmuxSession?: string;

package/src/routes.ts

@@ -163,7 +163,7 @@ import { planSend } from "./agent-ref";
 import { defaultProviderConfig, loadProviderConfig, providerConfigPublic, writeProviderConfig } from "../runner/src/config";
 import type { ProviderConfig } from "../runner/src/adapter";
 import { type ProviderEffort } from "agent-relay-sdk/provider-catalog";
-import { errMessage, isRecord, SPAWN_PROVIDERS, VALID_WORKSPACE_MODES, VALID_EFFORTS, APPROVAL_MODES, RELAY_TOKEN_HEADER } from "agent-relay-sdk";
+import { errMessage, isRecord, SPAWN_PROVIDERS, VALID_WORKSPACE_MODES, VALID_EFFORTS, APPROVAL_MODES, RELAY_TOKEN_HEADER, isMechanicalMessageKind, isReservedAgentId } from "agent-relay-sdk";
 import { effectiveProviderCatalogList } from "./provider-catalog-store";
 import { buildManagedSpawnParams, effectiveManagedPolicyWorkspaceMode } from "./managed-policy";
 import { buildSpawnCommand, generateSpawnRequestId, resolveSpawnModelParams, type SpawnModelParams } from "./spawn-command";
@@ -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 }),
   };
@@ -1278,7 +1282,13 @@ const postAgent: Handler = async (req) => {
         const available = resolveQueuedPolicyMessages(policyName, agent.id);
         if (available.length) {
           emitMessageAvailable(policyName, agent.id, available);
-          for (const message of available) emitNewMessage(message);
+          for (const message of available) {
+            emitNewMessage(message);
+            // queued → pending flips delivery_status; the dashboard dedups message.new
+            // by id (the message already shows as "queued"), so without an explicit
+            // delivery_updated the badge stays stale until the next poll (#265).
+            emitMessageDeliveryUpdated(message);
+          }
         }
       }
     }
@@ -5177,9 +5187,20 @@ const postMessage: Handler = async (req) => {
     }
     applyReplyRouting(input);
     if (!input.to) return error("to is required (or provide replyTo to auto-route)");
+    // Mechanical lifecycle/observability posts (system/control/session) addressed to a
+    // reserved sink ("user"/"system") are the relay's own lane, not agent-directed
+    // messaging. A managed token's recipient constraints (targets/policies/agents) gate
+    // which *agents* it may message — they must NOT gate a session-mirror capture to the
+    // reserved sink, or constrained tokens (telegram policy, codex steward) 403 → the
+    // runner's outbox retries 12× and poisons the record → the dashboard silently loses
+    // the turn (#284, same outbox-poison failure mode as #184). The message:send scope
+    // and any channel constraint still apply; we only drop the target/agentId predicate.
+    const reservedSinkPost = isMechanicalMessageKind(input.kind) && isReservedAgentId(input.to);
     const denied = authorizeRoute(req, {
       scope: "message:send",
-      resource: { target: input.to, channel: input.channel, agentId: input.from },
+      resource: reservedSinkPost
+        ? { channel: input.channel }
+        : { target: input.to, channel: input.channel, agentId: input.from },
     });
     if (denied) return denied;
     // Resolve the target through the shared planner — the SAME matcher the MCP send tool
@@ -5194,8 +5215,7 @@ const postMessage: Handler = async (req) => {
     // "session" = observed assistant turn (Phase 1 live-session lane). It is captured
     // from the provider transcript and stored for the dashboard chat; it must persist
     // regardless of target liveness and never be re-delivered into a session.
-    const bypassKinds = ["system", "control", "session"];
-    if (!bypassKinds.includes(input.kind ?? "")) {
+    if (!isMechanicalMessageKind(input.kind)) {
       const plan = planSend(input.to, listAgents());
       if (plan.kind === "ambiguous") return error(plan.message, 409);
       if (plan.kind !== "not_found") input.to = plan.to;
@@ -5245,7 +5265,7 @@ const postMessage: Handler = async (req) => {
 };
 
 function automaticMemoryTarget(message: { to: string; resolvedToAgent?: string; kind: string }): string | null {
-  if (message.kind === "system" || message.kind === "control" || message.kind === "session") return null;
+  if (isMechanicalMessageKind(message.kind)) return null;
   const target = message.resolvedToAgent ?? message.to;
   if (!isDirectTarget(target)) return null;
   const agent = getAgent(target);

package/src/runtime-tokens.ts

@@ -118,7 +118,7 @@ export function issueRunnerRuntimeToken(input: {
   });
 }
 
-export function issueChildRunnerRuntimeToken(input: {
+function issueChildRunnerRuntimeToken(input: {
   parentAgentId: string;
   orchestratorId: string;
   cwd: string;
@@ -239,7 +239,7 @@ export function runnerRuntimeTokenEnv(input: {
   };
 }
 
-export function childRunnerRuntimeTokenEnv(input: {
+function childRunnerRuntimeTokenEnv(input: {
   parentAgentId: string;
   orchestratorId: string;
   cwd: string;

package/src/security.ts

@@ -200,6 +200,9 @@ export function requiredScopeFor(method: string, pathname: string): string | nul
   if (pathname.startsWith("/api/maintenance")) return "system:admin";
   if (pathname.startsWith("/api/tasks")) return method === "GET" ? "task:read" : "task:write";
   if (pathname.startsWith("/api/pairs")) return method === "GET" ? "pairs:read" : "pairs:write";
+  // Insights config (the feature toggle) stays admin-only via the default; only the
+  // mechanical observation feed is writable by lower-privilege callers.
+  if (pathname === "/api/insights/observations") return method === "GET" ? "insights:read" : "insights:write";
   if (pathname.startsWith("/api/system/")) return "system:admin";
   return null;
 }
@@ -268,6 +271,11 @@ export function requiredComponentScopeFor(method: string, pathname: string): str
   if (pathname.startsWith("/api/agent-profiles")) return method === "GET" ? "agent:read" : "agent:write";
   if (pathname.startsWith("/api/tasks")) return method === "GET" ? "task:read" : "task:write";
   if (pathname.startsWith("/api/orchestrators")) return method === "GET" ? "agent:read" : "command:write";
+  // The Runner posts the #184 context-gathering signal here (source:"server") via its
+  // provider token. Without this case the path fell through to the system:admin default
+  // below and every observation was 403-dropped — the whole Insights feed stayed empty.
+  // Config (the feature toggle) intentionally keeps falling through to system:admin.
+  if (pathname === "/api/insights/observations") return method === "GET" ? "insights:read" : "insights:write";
   if (pathname.startsWith("/api/system/")) return "system:admin";
   return "system:admin";
 }

package/src/spawn-command.ts

@@ -17,7 +17,7 @@ export function generateSpawnRequestId(): string {
   return `sp_${randomUUID()}`;
 }
 
-export interface ResolveSpawnModelParamsOptions {
+interface ResolveSpawnModelParamsOptions {
   /**
    * What to do when provider-catalog resolution throws (e.g. unknown model, or
    * effort without a model):
@@ -69,7 +69,7 @@ export function resolveSpawnModelParams(
  * Every field that can appear in a spawn command-bus payload.
  * Optional fields are omitted from the result when undefined.
  */
-export interface BuildSpawnCommandOptions {
+interface BuildSpawnCommandOptions {
   provider: SpawnProvider | string;
   cwd: string;
   /** Correlation id; omitted from the payload when absent (e.g. automation spawns use automationRunId instead). */

package/src/token-db.ts

@@ -57,7 +57,7 @@ const BUILT_IN_PROFILES: Array<Omit<TokenProfile, "createdAt" | "updatedAt">> =
     name: "Provider Agent",
     description: "Coding-agent runtime access for messages, commands, tasks, and scoped memory reads.",
     role: "provider",
-    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use"],
+    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "insights:write"],
     ttlSeconds: 24 * 60 * 60,
     builtIn: true,
     createdBy: "system",
@@ -67,7 +67,7 @@ const BUILT_IN_PROFILES: Array<Omit<TokenProfile, "createdAt" | "updatedAt">> =
     name: "Provider Child Agent",
     description: "Delegated child-agent runtime access, constrained to its parent and spawn request.",
     role: "provider",
-    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use"],
+    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "insights:write"],
     constraints: { canDelegate: false },
     ttlSeconds: 2 * 60 * 60,
     builtIn: true,
@@ -78,7 +78,7 @@ const BUILT_IN_PROFILES: Array<Omit<TokenProfile, "createdAt" | "updatedAt">> =
     name: "Provider Interactive Agent",
     description: "User-launched provider runtime access constrained to its own agent and cwd for long interactive sessions.",
     role: "provider",
-    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use"],
+    scope: ["agent:read", "agent:write", "message:read", "message:send", "command:read", "command:write", "task:read", "task:write", "memory:read", "artifact:read", "artifact:write", "mcp:use", "insights:write"],
     constraints: { terminalAttach: false, logsRead: false, canDelegate: false },
     ttlSeconds: 30 * 24 * 60 * 60,
     builtIn: true,

package/src/upgrade.ts

@@ -249,7 +249,7 @@ export function createUpgradePlan(snapshot: UpgradeSnapshot, options: UpgradeOpt
   };
 }
 
-export type ExecuteUpgradeOptions = {
+type ExecuteUpgradeOptions = {
   dryRun?: boolean;
   runner?: Runner;
   /** Re-register grace window for post-restart version checks (default 30s). */

package/src/workspace-actions.ts

@@ -41,7 +41,7 @@ export const WORKSPACE_ACTIONS = [
 ] as const;
 export type WorkspaceAction = (typeof WORKSPACE_ACTIONS)[number];
 
-export interface ApplyWorkspaceActionInput {
+interface ApplyWorkspaceActionInput {
   action: WorkspaceAction;
   agentId?: string;
   detail?: string;
@@ -62,7 +62,7 @@ export interface ApplyWorkspaceActionInput {
   auditMetadata?: Record<string, unknown>;
 }
 
-export type WorkspaceActionResult =
+type WorkspaceActionResult =
   | {
       ok: true;
       httpStatus: number;
@@ -320,10 +320,10 @@ export function buildWorkspaceDepsRefreshCommand(
   return { ok: true, command };
 }
 
-export const DEFAULT_WORKSPACE_WAIT_MS = 300_000;
-export const MAX_WORKSPACE_WAIT_MS = 600_000;
+const DEFAULT_WORKSPACE_WAIT_MS = 300_000;
+const MAX_WORKSPACE_WAIT_MS = 600_000;
 
-export interface WaitForWorkspaceResult {
+interface WaitForWorkspaceResult {
   workspace: WorkspaceRecord | null;
   /** The status when the wait began. */
   fromStatus?: WorkspaceStatus;

package/src/workspace-claim.ts

@@ -4,9 +4,9 @@ import type { WorkspaceRecord } from "./types";
 // auto-merge (Layer 0) doesn't race it (#208 / steward report §1). The claim is a
 // TTL'd lease stored in row metadata, so a dead steward can't block the workspace
 // forever — it expires and auto-merge resumes. Renew by re-claiming.
-export const STEWARD_CLAIM_TTL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_CLAIM_TTL_MS) || 15 * 60_000;
+const STEWARD_CLAIM_TTL_MS = Number(process.env.AGENT_RELAY_WORKSPACE_CLAIM_TTL_MS) || 15 * 60_000;
 
-export interface WorkspaceClaim {
+interface WorkspaceClaim {
   by?: string;
   purpose?: string;
   claimedAt?: number;

package/src/workspace-merge.ts

@@ -10,7 +10,7 @@ import {
 import type { Command, WorkspaceMergeStrategy, WorkspaceRecord } from "./types";
 import { isPathWithinBase } from "./utils";
 
-export interface RequestWorkspaceMergeOptions {
+interface RequestWorkspaceMergeOptions {
   /** Who asked for the merge (lease holder + audit). e.g. an agent id, "dashboard", "auto-merge". */
   requestedBy: string;
   /** Merge strategy; "auto" lets the host pick pr-vs-rebase-ff. Defaults to "auto". */
@@ -26,7 +26,7 @@ export interface RequestWorkspaceMergeOptions {
   metadata?: Record<string, unknown>;
 }
 
-export type RequestWorkspaceMergeResult =
+type RequestWorkspaceMergeResult =
   | { ok: true; command: Command; workspace: WorkspaceRecord }
   | { ok: false; status: number; error: string };
 

package/src/workspace-orphans.ts

@@ -141,7 +141,7 @@ function knownRepoRoots(workspaces: WorkspaceRecord[]): string[] {
   return [...new Set(workspaces.map((ws) => ws.repoRoot).filter(Boolean))];
 }
 
-export interface CollectOrphansResult {
+interface CollectOrphansResult {
   orphans: WorkspaceOrphan[];
   /** Live isolated rows whose worktree is missing on disk (DB→disk drift). */
   missingWorktrees: Array<{

package/src/workspace-phase.ts

@@ -71,7 +71,7 @@ export function worktreeReapable(state: WorktreeReapState | null | undefined): b
 // instead of the old behavior where it looked healthy for 90 minutes.
 export const LAND_PENDING_STALL_MS = 15 * 60 * 1000;
 
-export type WorkspacePhase =
+type WorkspacePhase =
   | "working" // active — your turn: commit, then mark ready
   | "land-pending" // ready | review_requested — handed off; auto-merge will land it
   | "landing" // merge_planned — merge dispatched, in progress
@@ -79,7 +79,7 @@ export type WorkspacePhase =
   | "landed" // merged — on the base; a fresh rebased branch is coming
   | "closed"; // abandoned | cleanup_requested | cleaned — torn down
 
-export interface WorkspaceNextAction {
+interface WorkspaceNextAction {
   /** MCP tool to call (when the agent is on the MCP surface). */
   tool?: string;
   /** Equivalent CLI invocation (when the agent is on the shell surface). */