agent-relay 11.11.0 → 12.1.0

package/README.md

@@ -48,6 +48,70 @@ agent-relay node agent release <name>
 
 For AI SDK native harnesses, attach renders structured activity, text, tools, approvals, files, usage, and lifecycle events. Add `--json` for NDJSON, `--reasoning` for reasoning events, or `--diagnostics` for sidecar diagnostics. Native harness `drive` is line-oriented and acknowledged; native harness `passthrough` is unsupported because no terminal stream exists. PTY attach behavior is unchanged.
 
+### Local operation during a Relaycast outage
+
+```bash
+agent-relay node up --local-only
+agent-relay node status
+agent-relay node agent spawn claude --runtime pty
+agent-relay node agent attach <name> --mode view
+```
+
+`--local-only` deliberately starts a **DEGRADED** broker without waiting for
+Relaycast. Startup, `/health`, `/api/status`, and `node status` report that mode.
+The authenticated `/api/session` exposes `operation_mode: "local_only"` and
+`degraded: true`; its existing `mode` still describes persistence.
+The standalone broker accepts `init --local-only --persist`; SDK callers can
+set `AGENT_RELAY_LOCAL_ONLY=1` and enable persistence. The API must bind to a
+loopback IP, and the mode supports a single workspace key.
+
+Local spawn, terminal view/input, and the durable automatic delivery queue
+remain available. `POST /api/send` accepts only a worker currently running on
+this broker; channel, cross-workspace, and remote destinations are rejected.
+It reports `delivery_status: "queued_local"`, `local: true`, and
+`relaycast_published: false`. Acceptance means the work was saved, not that an
+agent has read it. Pending work survives restart and waits for an absent local
+recipient to respawn without exhausting retries. A restarted recipient gets a
+fresh transport retry budget. Explicit release and exhausted transport failures
+while the recipient is present still use the dead-letter lifecycle. Manual-flush mode is
+unavailable and returns `capability_disabled` explicitly.
+
+Fleet routing, worker presence, remote terminal attachment, node capability
+providers, and injected Relaycast messaging tools are disabled. Local agents
+receive a degraded-mode notice. Their model provider and any tools they
+configure themselves still have their own connectivity requirements.
+
+When a workspace key is configured through the normal workspace selection,
+the broker retries an independent audit connection in the background. Audit
+endpoints require HTTPS, with HTTP allowed only for literal loopback IPs used
+in local development. Audit records never follow HTTP redirects. Queued
+local delivery records are persisted in `state-<name>.local-outbox.json` beside
+broker state, then reconciled as `local.delivery.queued` events under a separate
+broker audit identity when Relaycast responds. These events contain the
+original delivery/event IDs, sender, recipient, body, and queue timestamp.
+They record local acceptance, not model completion. They are **audit replay**,
+not re-sent messages: replay must never execute the work twice or address a
+local worker name on another machine. Reconciliation is at least once; consumers
+can deduplicate by `event_id` after an ambiguous response or crash.
+
+`node status` reports the reconciliation backlog and the last connection
+result. Without a workspace key, local work still runs and records remain on
+disk with no upload destination; no workspace is created. A nonempty unscoped
+backlog cannot acquire a destination on restart. Keep its state directory and
+continue without a key, or select a different state directory for new work
+with a configured destination. The outbox
+is bounded to 10,000 records / 32 MiB and rejects new sends when full. A digest
+pins a configured backlog to its original workspace key and Relaycast base URL;
+restore that configuration to drain it before rotating keys or changing the
+destination. Corrupt outboxes cause an explicit startup failure rather than
+being discarded. Preserve the state directory until reconciliation completes.
+
+Recovery never silently enables fleet capabilities. Stop the broker and start
+normally (without the flag or environment opt-in) to enable them; a normal
+restart drains retained audit backlog only when its configured destination and
+digest match; an unscoped backlog remains on disk. Restart local workers as needed
+to give them Relaycast messaging tools and registered identities.
+
 ### Workspace binding and recovery
 
 `agent-relay up` and `agent-relay node up` resolve the workspace through one

package/dist/cli/agent-relay-mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-relay-mcp.d.ts","sourceRoot":"","sources":["../../src/cli/agent-relay-mcp.ts"],"names":[],"mappings":";AAOA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA4CpE,OAAO,KAAK,EAEV,0BAA0B,EAC1B,SAAS,EAET,mBAAmB,EACnB,aAAa,EACb,aAAa,EAEd,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAC;AAEjE,eAAO,MAAM,uBAAuB,QACuC,CAAC;AA4I5E,eAAO,MAAM,4BAA4B,unEAgCF,CAAC;AAWxC,KAAK,2BAA2B,GAAG;IACjC,OAAO,EAAE,mBAAmB,CAAC;IAC7B,UAAU,EAAE,aAAa,CAAC;IAC1B,QAAQ,EAAE,MAAM,aAAa,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,eAAe,CAAC,EAAE,SAAS,CAAC;IAC5B,gFAAgF;IAChF,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC,CAAC;AAcF;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CASrE;AAgCD,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAOjE;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAMnF;AAsID,wBAAsB,uBAAuB,CAAC,EAC5C,OAAO,EACP,UAAU,EACV,QAAQ,EACR,IAAI,EACJ,IAAI,EACJ,OAAO,EACP,QAAQ,EACR,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,qBAAqB,GACtB,EAAE,2BAA2B,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA+FhE;AAurBD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,0BAA0B,GAAG,SAAS,CA6MxF;AASD,wBAAsB,4BAA4B,CAChD,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,0BAA0B,CAAC,CA0BrC;AAED,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAShG;AAED,wBAAgB,cAAc,IAAI,0BAA0B,CAsC3D"}
+{"version":3,"file":"agent-relay-mcp.d.ts","sourceRoot":"","sources":["../../src/cli/agent-relay-mcp.ts"],"names":[],"mappings":";AAOA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAmDpE,OAAO,KAAK,EAEV,0BAA0B,EAC1B,SAAS,EAET,mBAAmB,EACnB,aAAa,EACb,aAAa,EAEd,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAC;AAEjE,eAAO,MAAM,uBAAuB,QACuC,CAAC;AA2T5E,eAAO,MAAM,4BAA4B,unEAgCF,CAAC;AAWxC,KAAK,2BAA2B,GAAG;IACjC,OAAO,EAAE,mBAAmB,CAAC;IAC7B,UAAU,EAAE,aAAa,CAAC;IAC1B,QAAQ,EAAE,MAAM,aAAa,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,eAAe,CAAC,EAAE,SAAS,CAAC;IAC5B,gFAAgF;IAChF,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC,CAAC;AAcF;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CASrE;AAgCD,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAOjE;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAMnF;AAsID,wBAAsB,uBAAuB,CAAC,EAC5C,OAAO,EACP,UAAU,EACV,QAAQ,EACR,IAAI,EACJ,IAAI,EACJ,OAAO,EACP,QAAQ,EACR,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,qBAAqB,GACtB,EAAE,2BAA2B,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA+FhE;AAysBD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,0BAA0B,GAAG,SAAS,CA6MxF;AASD,wBAAsB,4BAA4B,CAChD,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,0BAA0B,CAAC,CA0BrC;AAED,wBAAsB,uBAAuB,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAShG;AAED,wBAAgB,cAAc,IAAI,0BAA0B,CAsC3D"}

package/dist/cli/agent-relay-mcp.js

@@ -6,11 +6,12 @@ import { isDeepStrictEqual } from 'node:util';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ListToolsRequestSchema, SubscribeRequestSchema, UnsubscribeRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
-import { AgentRelay, RELAYCAST_SDK_VERSION, createAgentClient, createObserverToken, createRealtimeClient, createWorkspaceClient, isInvalidAgentTokenError, } from '@agent-relay/sdk';
+import { AgentRelay, RELAYCAST_SDK_VERSION, createAgentClient, createObserverToken, createRealtimeClient, createWorkspaceClient, isInvalidAgentTokenError, safeRelayErrorMessage, } from '@agent-relay/sdk';
 import { z } from 'zod';
 import { declaredWorkforceMetadata } from './lib/registration-metadata.js';
 import { DEFAULT_AGENT_REGISTRATION_TIMEOUT_MS, withAgentRegistrationDeadline, withDeadline, } from './lib/agent-registration.js';
 import { attributableReleaseReason } from './lib/release-reason.js';
+import { sanitizedSpawnReceipt, spawnPlacementReceipt, } from './lib/spawn-lifecycle.js';
 import { initTelemetry, shutdown as shutdownTelemetry } from './telemetry/index.js';
 import { RealtimeResourceBridge, SubscriptionManager, registerResourceDefinitions } from './mcp/resources.js';
 import { jsonContent, jsonResult, textContent } from './mcp/tool-results.js';
@@ -28,11 +29,30 @@ const EXIT_AFTER_TASK_INSTRUCTION = '## Post-task exit\n' +
 function withExitAfterTaskInstruction(task) {
     return `${task}\n\n${EXIT_AFTER_TASK_INSTRUCTION}`;
 }
-const PERSONA_SPAWN_TIMEOUT_MS = 130_000;
-const PERSONA_SPAWN_POLL_MS = 250;
-const PERSONA_SPAWN_TIMEOUT_MESSAGE = 'Persona spawn timed out before broker registration and harness readiness.';
-const PERSONA_SPAWN_SUCCESS_STATUSES = new Set(['completed', 'succeeded', 'success']);
-const PERSONA_SPAWN_FAILURE_STATUSES = new Set(['failed', 'error', 'cancelled', 'canceled']);
+const VERIFIED_SPAWN_TIMEOUT_MS = 130_000;
+const VERIFIED_SPAWN_POLL_MS = 250;
+const VERIFIED_SPAWN_TIMEOUT_MESSAGE = 'Spawn timed out before broker registration and harness readiness.';
+const VERIFIED_SPAWN_MISSING_READY_MESSAGE = 'Spawn completed without broker registration and harness readiness proof. The resolved spawn handler must honor top-level verify_ready and return spawned:true and ready:true. For a broker handler, use a release containing Relay PR #1708.';
+const VERIFIED_SPAWN_SUCCESS_STATUSES = new Set(['completed', 'succeeded', 'success']);
+const VERIFIED_SPAWN_FAILURE_STATUSES = new Set(['failed', 'error', 'cancelled', 'canceled', 'denied']);
+class VerifiedSpawnError extends Error {
+    code;
+    invocationId;
+    state;
+    dispatchState;
+    node;
+    receipt;
+    constructor(message, context) {
+        super(message);
+        this.name = 'VerifiedSpawnError';
+        this.code = context.code ?? (context.state === 'failed' ? 'spawn_failed' : 'spawn_unconfirmed');
+        this.state = context.state;
+        this.dispatchState = context.dispatchState ?? 'unknown';
+        this.invocationId = context.invocationId;
+        this.node = context.node;
+        this.receipt = context.receipt;
+    }
+}
 function recordValue(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value)
         ? value
@@ -47,9 +67,59 @@ function invocationRef(value) {
     const invocationId = invocationText(record, 'invocationId', 'invocation_id');
     if (!invocationId)
         return undefined;
+    const node = invocationText(record, 'handlerNodeId', 'handler_node_id') ??
+        invocationText(record, 'dispatchedNodeId', 'dispatched_node_id');
     return {
         invocationId,
         actionName: invocationText(record, 'actionName', 'action_name') ?? 'spawn',
+        ...(node ? { node } : {}),
+        dispatchState: dispatchStateFor(record),
+    };
+}
+function spawnReceipt(value) {
+    return spawnPlacementReceipt(value);
+}
+function dispatchStateFor(value, fallback = 'unknown') {
+    const state = spawnReceipt(value).dispatchState;
+    return state === 'dispatched' || state === 'not_dispatched' ? state : fallback;
+}
+/**
+ * Dispatch evidence for a *later* invocation read, given the dispatch state
+ * already frozen from the ack. `spawnReceipt`/`dispatchStateFor` treats a
+ * terminal status (e.g. `completed`) as dispatch evidence on its own — valid
+ * for the ack itself, where a synchronous handler really can report a
+ * terminal status immediately. It is not valid here: once the ack is known
+ * `not_dispatched` (a `pending`/`queued` ack with no node id), a later poll
+ * observing `completed`/`invoked` must not retroactively manufacture
+ * `dispatched` from that status. A node id appearing on the later record is
+ * real, new routing evidence and is trusted; a bare status change is not.
+ */
+function dispatchStateForRecord(record, ackDispatchState) {
+    if (ackDispatchState === 'dispatched')
+        return 'dispatched';
+    const nodeId = invocationText(record, 'dispatchedNodeId', 'dispatched_node_id') ??
+        invocationText(record, 'handlerNodeId', 'handler_node_id');
+    return nodeId ? 'dispatched' : ackDispatchState;
+}
+function terminalSpawnFailureResult(invocation) {
+    const placement = spawnReceipt(invocation);
+    if (placement.state !== 'failed')
+        return undefined;
+    return {
+        ...jsonContent({
+            ok: false,
+            error: {
+                code: 'spawn_failed',
+                state: 'failed',
+                ...(placement.invocationId ? { invocationId: placement.invocationId } : {}),
+                dispatchState: dispatchStateFor(invocation),
+                receipt: sanitizedSpawnReceipt(invocation),
+                message: typeof invocation.error === 'string' && invocation.error.trim()
+                    ? safeRelayErrorMessage(invocation.error)
+                    : 'Fleet spawn invocation reported a terminal failure.',
+            },
+        }),
+        isError: true,
     };
 }
 function nestedPersonaSpawnRef(invocation) {
@@ -64,13 +134,13 @@ function nestedPersonaSpawnRef(invocation) {
 async function getInvocationBeforeDeadline(actions, current, deadline) {
     const remainingMs = deadline - Date.now();
     if (remainingMs <= 0)
-        throw new Error(PERSONA_SPAWN_TIMEOUT_MESSAGE);
+        throw new Error(VERIFIED_SPAWN_TIMEOUT_MESSAGE);
     let timeout;
     try {
         return await Promise.race([
             actions.getInvocation(current.actionName, current.invocationId),
             new Promise((_resolve, reject) => {
-                timeout = setTimeout(() => reject(new Error(PERSONA_SPAWN_TIMEOUT_MESSAGE)), remainingMs);
+                timeout = setTimeout(() => reject(new Error(VERIFIED_SPAWN_TIMEOUT_MESSAGE)), remainingMs);
             }),
         ]);
     }
@@ -89,46 +159,104 @@ async function pollInvocation(actions, current, deadline) {
             return await getInvocationBeforeDeadline(actions, current, deadline);
         }
         catch (error) {
-            if (isInvocationAuthorizationError(error))
-                throw error;
+            if (isInvocationAuthorizationError(error)) {
+                throw new VerifiedSpawnError(`Spawn confirmation could not be read after acceptance (${error instanceof Error ? error.message : String(error)}). The invocation may still be running; do not retry without checking it first. Invocation: ${current.invocationId}.`, {
+                    code: 'spawn_unconfirmed',
+                    state: 'unconfirmed_may_be_running',
+                    invocationId: current.invocationId,
+                    dispatchState: current.dispatchState,
+                    ...(current.node ? { node: current.node } : {}),
+                });
+            }
             if (Date.now() >= deadline) {
-                throw new Error(PERSONA_SPAWN_TIMEOUT_MESSAGE, { cause: error });
+                throw new VerifiedSpawnError(`${VERIFIED_SPAWN_TIMEOUT_MESSAGE} The invocation may still be running; do not retry without checking it first. Invocation: ${current.invocationId}.`, {
+                    state: 'unconfirmed_may_be_running',
+                    invocationId: current.invocationId,
+                    dispatchState: current.dispatchState,
+                    ...(current.node ? { node: current.node } : {}),
+                    receipt: { status: 'unknown' },
+                });
             }
-            await new Promise((resolve) => setTimeout(resolve, PERSONA_SPAWN_POLL_MS));
+            await new Promise((resolve) => setTimeout(resolve, VERIFIED_SPAWN_POLL_MS));
         }
     }
 }
-async function waitForPersonaSpawn(actions, ackValue, timeoutMs = PERSONA_SPAWN_TIMEOUT_MS) {
+function missingVerifiedSpawnProof(record, ack, invocationId) {
+    const handler = invocationText(record, 'handlerNodeId', 'handler_node_id') ??
+        invocationText(record, 'dispatchedNodeId', 'dispatched_node_id') ??
+        invocationText(ack, 'handlerNodeId', 'handler_node_id') ??
+        'unknown';
+    return `${VERIFIED_SPAWN_MISSING_READY_MESSAGE} Resolved handler node: ${handler}; invocation: ${invocationId}.`;
+}
+async function waitForVerifiedSpawn(actions, ackValue, timeoutMs = VERIFIED_SPAWN_TIMEOUT_MS) {
     const ack = recordValue(ackValue);
     let current = invocationRef(ack);
-    if (!current)
-        throw new Error('Persona spawn did not return an invocation id.');
+    if (!current) {
+        throw new VerifiedSpawnError('Spawn returned no invocation id; the dispatch is unconfirmed and may still be running. Do not retry blindly.', { state: 'unconfirmed_may_be_running', dispatchState: dispatchStateFor(ack) });
+    }
     const deadline = Date.now() + timeoutMs;
     const followed = new Set([`${current.actionName}\u001f${current.invocationId}`]);
     for (;;) {
         const invocation = await pollInvocation(actions, current, deadline);
         const record = recordValue(invocation);
         const status = invocationText(record, 'status')?.toLowerCase();
-        if (status && PERSONA_SPAWN_SUCCESS_STATUSES.has(status)) {
+        if (status && VERIFIED_SPAWN_SUCCESS_STATUSES.has(status)) {
             const nested = nestedPersonaSpawnRef(record);
             if (nested) {
                 const key = `${nested.actionName}\u001f${nested.invocationId}`;
                 if (followed.has(key)) {
-                    throw new Error('Persona spawn returned a cyclic nested invocation.');
+                    throw new VerifiedSpawnError('Persona spawn returned a cyclic nested invocation.', {
+                        code: 'spawn_failed',
+                        state: 'failed',
+                        dispatchState: dispatchStateForRecord(record, current.dispatchState),
+                        invocationId: current.invocationId,
+                        receipt: record,
+                    });
                 }
                 followed.add(key);
                 current = nested;
                 continue;
             }
+            const output = recordValue(record.output);
+            if (output.spawned !== true || output.ready !== true) {
+                throw new VerifiedSpawnError(missingVerifiedSpawnProof(record, ack, current.invocationId), {
+                    code: 'spawn_failed',
+                    state: 'failed',
+                    dispatchState: dispatchStateForRecord(record, current.dispatchState),
+                    invocationId: current.invocationId,
+                    node: invocationText(record, 'handlerNodeId', 'handler_node_id') ??
+                        invocationText(record, 'dispatchedNodeId', 'dispatched_node_id') ??
+                        current.node,
+                    receipt: record,
+                });
+            }
             return invocation;
         }
-        if (status && PERSONA_SPAWN_FAILURE_STATUSES.has(status)) {
-            throw new Error(invocationText(record, 'error') ?? `Persona spawn ${status}.`);
+        if (status && VERIFIED_SPAWN_FAILURE_STATUSES.has(status)) {
+            throw new VerifiedSpawnError(invocationText(record, 'error') ?? `Spawn ${status}.`, {
+                code: 'spawn_failed',
+                state: 'failed',
+                dispatchState: dispatchStateForRecord(record, current.dispatchState),
+                invocationId: current.invocationId,
+                node: invocationText(record, 'handlerNodeId', 'handler_node_id') ??
+                    invocationText(record, 'dispatchedNodeId', 'dispatched_node_id') ??
+                    current.node,
+                receipt: record,
+            });
         }
         if (Date.now() >= deadline) {
-            throw new Error(PERSONA_SPAWN_TIMEOUT_MESSAGE);
+            throw new VerifiedSpawnError(`${VERIFIED_SPAWN_TIMEOUT_MESSAGE} The invocation may still be running; do not retry without checking it first. Invocation: ${current.invocationId}.`, {
+                code: 'spawn_unconfirmed',
+                state: 'unconfirmed_may_be_running',
+                dispatchState: dispatchStateForRecord(record, current.dispatchState),
+                invocationId: current.invocationId,
+                node: invocationText(record, 'handlerNodeId', 'handler_node_id') ??
+                    invocationText(record, 'dispatchedNodeId', 'dispatched_node_id') ??
+                    current.node,
+                receipt: record,
+            });
         }
-        await new Promise((resolve) => setTimeout(resolve, PERSONA_SPAWN_POLL_MS));
+        await new Promise((resolve) => setTimeout(resolve, VERIFIED_SPAWN_POLL_MS));
     }
 }
 export const AGENT_RELAY_MCP_INSTRUCTIONS = `You are an AI agent in a collaborative workspace powered by Agent Relay. You can communicate with other agents using these MCP tools:
@@ -435,12 +563,6 @@ export async function registerAgentWithRebind({ session, setSession, getRelay, n
         warnings,
     };
 }
-function requireSpawnActions(client) {
-    if (!client.actions) {
-        throw new Error('spawn requires an agent-scoped Relaycast actions client.');
-    }
-    return client.actions;
-}
 function validateSpawnRequest({ cli, persona, model, sessionRef, cwd, personaCwd }) {
     if (Boolean(cli) === Boolean(persona)) {
         throw new Error('spawn requires exactly one of `cli` or `persona`.');
@@ -463,7 +585,7 @@ function buildSpawnActionInput({ name, cli, persona, task, cwd, personaCwd, work
     const registryCwd = personaCwd ?? cwd;
     return {
         name,
-        ...(cli ? { cli } : { persona, capability: 'spawn:persona' }),
+        ...(cli ? { cli, verify_ready: true } : { persona, capability: 'spawn:persona' }),
         ...(task ? { task } : {}),
         ...(persona && registryCwd ? { cwd: registryCwd } : {}),
         ...(workerCwd ? { worker_cwd: workerCwd } : {}),
@@ -474,14 +596,31 @@ function buildSpawnActionInput({ name, cli, persona, task, cwd, personaCwd, work
         ...(selectedChannels ? { channels: selectedChannels } : {}),
     };
 }
-async function invokeVerifiedPersonaSpawn(session, asIdentity, baseUrl, actionInput) {
+async function invokeVerifiedSpawn(session, asIdentity, baseUrl, actionInput) {
     const agentToken = asIdentity ? session.agents.get(asIdentity)?.agentToken : session.agentToken;
     if (!agentToken) {
-        throw new Error('Persona spawn requires a registered agent identity.');
+        throw new Error('Spawn requires a registered agent identity.');
     }
     const commands = new AgentRelay({ agentToken, baseUrl }).messaging.commands;
     const invocation = await commands.invoke('spawn', actionInput);
-    return waitForPersonaSpawn(commands, invocation);
+    return waitForVerifiedSpawn(commands, invocation);
+}
+function verifiedSpawnErrorResult(error) {
+    return {
+        ...jsonContent({
+            ok: false,
+            error: {
+                code: error.code,
+                state: error.state,
+                dispatchState: error.dispatchState,
+                ...(error.invocationId ? { invocationId: error.invocationId } : {}),
+                ...(error.node ? { node: error.node } : {}),
+                ...(error.receipt ? { receipt: sanitizedSpawnReceipt(error.receipt) } : {}),
+                message: safeRelayErrorMessage(error),
+            },
+        }),
+        isError: true,
+    };
 }
 /**
  * Read the agent record back and confirm the supplied metadata is on it.
@@ -798,7 +937,7 @@ function registerAgentRelayTools(server, getRelay, getAgentClient, getSession, s
             '"spawn an opus claude agent" → cli:"claude", model:"claude-opus-4-8"; ' +
             '"spawn a sonnet claude agent" → cli:"claude", model:"claude-sonnet-4-6". ' +
             'Do NOT use the built-in Agent/Task tool for relay workers. ' +
-            'Returns the spawn record for the new worker, including the name it registered under. The worker boots asynchronously, so a successful return means the spawn was accepted, not that the worker is ready — watch for its messages or poll "list_agents" to confirm it came online.',
+            'Returns the registered worker name. Raw CLI spawns return only after the broker confirms registration and harness readiness. Persona spawns follow their registered handler completion contract.',
         inputSchema: {
             name: z.string().describe('Worker agent name'),
             cli: z
@@ -825,26 +964,32 @@ function registerAgentRelayTools(server, getRelay, getAgentClient, getSession, s
         },
         outputSchema: jsonResult,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
-    }, async ({ name, cli, task, channel, persona, model, spawn_mode, exit_after_task }) => jsonContent(await getRelay().agents.spawn({
-        name,
-        cli,
-        task: exit_after_task ||
-            spawn_mode === 'task_exit' ||
-            spawn_mode === 'task-exit' ||
-            spawn_mode === 'single_shot' ||
-            spawn_mode === 'single-shot'
-            ? withExitAfterTaskInstruction(task)
-            : task,
-        channel,
-        persona,
-        // SpawnAgentRequest has no top-level model field; pass via metadata
-        // so the broker can extract it and forward --model to the launched CLI.
-        metadata: model ? { model } : undefined,
-    })));
+    }, async ({ name, cli, task, channel, persona, model, spawn_mode, exit_after_task }) => {
+        const invocation = await getRelay().agents.spawn({
+            name,
+            cli,
+            task: exit_after_task ||
+                spawn_mode === 'task_exit' ||
+                spawn_mode === 'task-exit' ||
+                spawn_mode === 'single_shot' ||
+                spawn_mode === 'single-shot'
+                ? withExitAfterTaskInstruction(task)
+                : task,
+            channel,
+            persona,
+            // SpawnAgentRequest has no top-level model field; pass via metadata
+            // so the broker can extract it and forward --model to the launched CLI.
+            metadata: model ? { model } : undefined,
+        });
+        const failure = terminalSpawnFailureResult(invocation);
+        if (failure)
+            return failure;
+        return jsonContent({ ...invocation, placement: spawnReceipt(invocation) });
+    });
     server.registerTool('spawn', {
         title: 'Spawn Agent',
         description: 'Invoke the fleet spawn action with either a raw `cli` or an AgentWorkforce `persona` name/path. ' +
-            'Persona requests route to a node exposing `spawn:persona` (for example, `defineWorkforcePersonaSpawnNode` from `@agentworkforce/local-surface`) and return only after broker registration and harness readiness are verified. Raw CLI requests retain asynchronous acknowledgement behavior.',
+            'Persona requests route to a node exposing `spawn:persona` (for example, `defineWorkforcePersonaSpawnNode` from `@agentworkforce/local-surface`). Both forms return only after broker registration and harness readiness are verified.',
         inputSchema: {
             name: z.string().describe('Agent name'),
             cli: z
@@ -885,7 +1030,6 @@ function registerAgentRelayTools(server, getRelay, getAgentClient, getSession, s
             openWorldHint: true,
         },
     }, async ({ name, cli, persona, task, cwd, persona_cwd, worker_cwd, channel, channels, model, organization, project, workstream, role, objective, session_ref, target_node, as, }) => {
-        const actions = requireSpawnActions(getAgentClient(as));
         const request = {
             name,
             cli,
@@ -907,10 +1051,18 @@ function registerAgentRelayTools(server, getRelay, getAgentClient, getSession, s
         };
         validateSpawnRequest(request);
         const actionInput = buildSpawnActionInput(request);
-        const invocation = persona
-            ? await invokeVerifiedPersonaSpawn(getSession(), as, baseUrl, actionInput)
-            : await actions.invoke('spawn', actionInput);
-        return jsonContent({ invocation });
+        try {
+            const invocation = await invokeVerifiedSpawn(getSession(), as, baseUrl, actionInput);
+            return jsonContent({
+                invocation,
+                placement: { state: 'ready', ...spawnReceipt(recordValue(invocation)) },
+            });
+        }
+        catch (error) {
+            if (error instanceof VerifiedSpawnError)
+                return verifiedSpawnErrorResult(error);
+            throw error;
+        }
     });
     server.registerTool('remove_agent', {
         title: 'Remove Agent',