feat: add routed ping and structured targeting

docs/plans/2026-08-12-spawn-robustness.md

@@ -79,4 +79,3 @@
 4. Review the final diff and run the bounded local CodeRabbit pre-commit review.
 5. Commit with the live agent-identity trailer, push the assigned branch, and open a signed ready-for-review PR.
 6. Append the collab log line and inbox-ping `cmuxlayerClaude-9c55eb04` with the PR URL. If the inbox is unarmed, append the PR URL as the final line of `phase-7/findings.md`.
-

src/daemon.ts

@@ -32,6 +32,7 @@ import {
 import {
   ackedIds,
   dispatchOnce,
+  formatInboxPing,
   inboxPath,
   monitorAlive,
   readLastAgentHeartbeat,
@@ -872,7 +873,10 @@ export class CmuxLayerDaemon {
           }
           await guardedRelay({
             agent_id: owner.agent_id,
-            text: `[inbox] monitor recovery message ${message.id} — read ${inboxPath(owner.agent_id, inboxOpts)}, re-arm, then ack`,
+            text: formatInboxPing(
+              message,
+              inboxPath(owner.agent_id, inboxOpts),
+            ),
             press_enter: true,
             allow_busy: true,
             source_event: "dispatch_nudge",

src/inbox.ts

@@ -39,6 +39,12 @@ export interface InboxMessage {
   id: string;
   ts_ms: number;
   from: string;
+  /** Authoritative agent id to use for replies. Never infer this from pane focus. */
+  reply_to: string;
+  /** Optional observed surface ref. Stale-able hint only; never a routing address. */
+  via?: string;
+  /** Observation timestamp paired with via. */
+  observed_at?: string;
   /** Recipient agent id (own-tag) or "orc". Each agent monitors only its own inbox. */
   to: string;
   tag: string;
@@ -90,6 +96,12 @@ export type InboxMonitorState = "never-armed" | "alive" | "stale";
 
 export interface DispatchInput {
   from: string;
+  /** Resolved sender agent id. Defaults to from for non-engine/internal callers. */
+  reply_to?: string;
+  /** Optional sender surface ref hint. Routing must continue to use reply_to. */
+  via?: string;
+  /** Optional ISO timestamp for the via observation. */
+  observed_at?: string;
   to?: string;
   tag?: string;
   task: string;
@@ -325,6 +337,13 @@ export function dispatch(
     id: input.id ?? genId(ts),
     ts_ms: ts,
     from: input.from,
+    reply_to: input.reply_to ?? input.from,
+    ...(input.via
+      ? {
+          via: input.via,
+          observed_at: input.observed_at ?? new Date(ts).toISOString(),
+        }
+      : {}),
     to: input.to ?? agentId,
     tag: input.tag ?? "dispatch",
     task: input.task,
@@ -334,6 +353,16 @@ export function dispatch(
   return msg;
 }
 
+/** One connector-authored composer shape for all inbox wakes. */
+export function formatInboxPing(message: InboxMessage, path: string): string {
+  const replyTo = message.reply_to || message.from;
+  const viaHint =
+    message.via && message.observed_at
+      ? ` via:${message.via} observed_at:${message.observed_at}`
+      : "";
+  return `[inbox] ${message.id} — reply_to: ${replyTo}${viaHint} — read ${path}`;
+}
+
 export function dispatchOnce(
   agentId: string,
   input: DispatchInput & { id: string },

tests/daemon.test.ts

@@ -23,7 +23,7 @@ import {
   readMonitorRegistry,
   registerMonitor,
 } from "../src/monitor-registry.js";
-import { ack, readInbox } from "../src/inbox.js";
+import { ack, inboxPath, readInbox } from "../src/inbox.js";
 
 const TEST_ROOT = join("/tmp", "cmuxlayer-daemon-test");
 const TEST_OBSERVER_OWNER = "cmux:/tmp/cmux-daemon-test.sock";
@@ -920,15 +920,15 @@ describe("CmuxLayerDaemon", () => {
       collapsed_reason: "owner-wedged",
     });
     expect(monitorOwnerWedgedNotify).toHaveBeenCalledTimes(1);
-    expect(guardedRelays[0]).toHaveBeenCalledWith(
-      expect.objectContaining({
-        agent_id: "worker-a",
-        text: expect.stringContaining("read"),
-        press_enter: true,
-        allow_busy: true,
-        source_event: "dispatch_nudge",
-      }),
-    );
+    const rearmMessage = readInbox("worker-a", { baseDir: inboxBaseDir })[0]!;
+    expect(rearmMessage.reply_to).toBe("cmuxlayer-daemon");
+    expect(guardedRelays[0]).toHaveBeenCalledWith({
+      agent_id: "worker-a",
+      text: `[inbox] ${rearmMessage.id} — reply_to: ${rearmMessage.reply_to} — read ${inboxPath("worker-a", { baseDir: inboxBaseDir })}`,
+      press_enter: true,
+      allow_busy: true,
+      source_event: "dispatch_nudge",
+    });
     expect(clients[0]?.send).not.toHaveBeenCalled();
     expect(clients[0]?.sendKey).not.toHaveBeenCalled();
   });

tests/default-palette.test.ts

@@ -15,7 +15,6 @@ const THIN_CORE_TOOL_NAMES = [
   "read_screen",
   "my_agents",
   "list_agents",
-  "broadcast",
   "close_surface",
   "dispatch_to_agent",
   "list_surfaces",

tests/inbox-nudge.test.ts

@@ -28,6 +28,7 @@ import { tmpdir } from "node:os";
 import { createServer } from "../src/server.js";
 import {
   agentDir,
+  inboxPath,
   writeHeartbeat,
   readInbox,
 } from "../src/inbox.js";
@@ -287,8 +288,10 @@ describe("dispatch_to_agent nudge (state-independent inbox wake)", () => {
     const nudgeCall = after.at(-1)!;
     const nudgeText = String(nudgeCall.at(-1) ?? "");
     expect(nudgeCall.join(" ")).toContain("surface:new");
-    expect(nudgeCall.join(" ")).toContain("inbox");
-    expect(nudgeText).not.toMatch(/[\n\r]/);
+    const message = readInbox(agentId, { baseDir: inboxDir }).at(-1)!;
+    expect(nudgeText).toBe(
+      `[inbox] ${message.id} — reply_to: ${message.reply_to} — read ${inboxPath(agentId, { baseDir: inboxDir })}`,
+    );
     // And the message itself is durably in the inbox file.
     expect(
       readInbox(agentId, { baseDir: inboxDir }).map((m) => m.task),
@@ -351,6 +354,120 @@ describe("dispatch_to_agent nudge (state-independent inbox wake)", () => {
     expect(sendCalls(exec).length).toBe(before);
   });
 
+  it("wakes an idle live agent exactly once on enqueue even when its monitor is fresh", async () => {
+    const agentId = await spawnTestAgent(server);
+    const engine = server._registeredTools["interact"]._engine;
+    const idle = engine.stateMgr.updateRecord(agentId, { state: "idle" });
+    engine.getRegistry().set(agentId, idle);
+    writeHeartbeat(agentId, { baseDir: inboxDir });
+
+    const before = sendCalls(exec).length;
+    const result = await server._registeredTools["dispatch_to_agent"].handler(
+      {
+        agent_id: agentId,
+        task: "GO",
+        from: "orc",
+        tag: "dispatch",
+        persist: false,
+        nudge: "auto",
+      },
+      {} as any,
+    );
+    const parsed =
+      result.structuredContent ?? JSON.parse(result.content[0].text);
+    const message = readInbox(agentId, { baseDir: inboxDir }).at(-1)!;
+    const after = sendCalls(exec);
+
+    expect(parsed.ok).toBe(true);
+    expect(parsed.monitor_state).toBe("alive");
+    expect(parsed.nudge).toMatchObject({ attempted: true, sent: true });
+    expect(after).toHaveLength(before + 1);
+    expect(String(after.at(-1)?.at(-1) ?? "")).toBe(
+      `[inbox] ${message.id} — reply_to: ${message.reply_to} — read ${inboxPath(agentId, { baseDir: inboxDir })}`,
+    );
+  });
+
+  it("puts the resolved caller agent id in the envelope and ping reply address", async () => {
+    const agentId = await spawnTestAgent(server);
+    const engine = server._registeredTools["interact"]._engine;
+    const target = engine.getRegistry().get(agentId)!;
+    const idle = engine.stateMgr.updateRecord(agentId, { state: "idle" });
+    engine.getRegistry().set(agentId, idle);
+    const caller = {
+      ...target,
+      agent_id: "golems-caller",
+      surface_id: "surface:golems",
+      surface_uuid: "22222222-2222-4222-8222-222222222222",
+      state: "ready",
+    };
+    engine.stateMgr.writeState(caller);
+    engine.getRegistry().set(caller.agent_id, caller);
+    writeHeartbeat(agentId, { baseDir: inboxDir });
+
+    const before = sendCalls(exec).length;
+    const result = await runWithCallerContext(
+      { surfaceId: caller.surface_uuid },
+      () =>
+        server._registeredTools["dispatch_to_agent"].handler(
+          {
+            agent_id: agentId,
+            task: "Reply to the sender, not your own pane",
+            from: "ambiguous-human-label",
+            nudge: "auto",
+          },
+          {} as any,
+        ),
+    );
+    const parsed =
+      result.structuredContent ?? JSON.parse(result.content[0].text);
+    const message = readInbox(agentId, { baseDir: inboxDir }).at(-1)!;
+    const after = sendCalls(exec);
+
+    expect(parsed.ok).toBe(true);
+    expect(message).toMatchObject({
+      from: "ambiguous-human-label",
+      reply_to: caller.agent_id,
+      via: caller.surface_id,
+      observed_at: expect.any(String),
+    });
+    expect(after).toHaveLength(before + 1);
+    expect(String(after.at(-1)?.at(-1) ?? "")).toBe(
+      `[inbox] ${message.id} — reply_to: ${caller.agent_id} via:${caller.surface_id} observed_at:${message.observed_at} — read ${inboxPath(agentId, { baseDir: inboxDir })}`,
+    );
+    expect(String(after.at(-1)?.at(-1) ?? "")).not.toContain("workspace:");
+  });
+
+  it("durably appends with the supplied sender id when caller surface is unresolved", async () => {
+    const agentId = await spawnTestAgent(server);
+
+    const result = await runWithCallerContext(
+      { surfaceId: "surface:missing-caller" },
+      () =>
+        server._registeredTools["dispatch_to_agent"].handler(
+          {
+            agent_id: agentId,
+            task: "Recovery message must survive stale caller state",
+            from: "cmuxlayerClaude-recovery",
+            nudge: "never",
+          },
+          {} as any,
+        ),
+    );
+    const parsed =
+      result.structuredContent ?? JSON.parse(result.content[0].text);
+    const message = readInbox(agentId, { baseDir: inboxDir }).at(-1)!;
+
+    expect(parsed.ok).toBe(false);
+    expect(parsed.durable).toBe(true);
+    expect(parsed.error_code).toBe("inbox_monitor_never_armed");
+    expect(message).toMatchObject({
+      from: "cmuxlayerClaude-recovery",
+      reply_to: "cmuxlayerClaude-recovery",
+      task: "Recovery message must survive stale caller state",
+    });
+    expect(message).not.toHaveProperty("via");
+  });
+
   it("republishes a Claude idle-to-working transition without shrinking any lane", async () => {
     await server.close();
     const idleScreen = [

tests/inbox.test.ts

@@ -154,6 +154,7 @@ describe("inbox write-channel", () => {
   it("dispatch appends a message with defaults (to=agent, tag=dispatch) and id", () => {
     const m = dispatch("a1", { from: "orc", task: "do X" }, opts);
     expect(m.to).toBe("a1");
+    expect(m.reply_to).toBe("orc");
     expect(m.tag).toBe("dispatch");
     expect(m.id).toBeTruthy();
     expect(m.ts_ms).toBe(1_000_000);
@@ -162,6 +163,28 @@ describe("inbox write-channel", () => {
     expect(all[0].task).toBe("do X");
   });
 
+  it("stores an optional stale-able surface hint only beside the durable reply id", () => {
+    const m = dispatch(
+      "coach",
+      {
+        from: "golems",
+        reply_to: "golems-agent-id",
+        via: "surface:golems",
+        observed_at: "2026-08-12T18:00:00.000Z",
+        task: "reply through the registry",
+      },
+      opts,
+    );
+
+    expect(m).toMatchObject({
+      reply_to: "golems-agent-id",
+      via: "surface:golems",
+      observed_at: "2026-08-12T18:00:00.000Z",
+    });
+    expect(m).not.toHaveProperty("tab");
+    expect(m).not.toHaveProperty("tab_name");
+  });
+
   it("dispatchOnce keeps one durable message for a stable recovery id", () => {
     const first = dispatchOnce(
       "a1-once",