agent-relay 13.2.0 → 13.4.0

package/dist/cli/commands/agent.js

@@ -1,15 +1,7 @@
 import { addSdkOptions, printJson, runSdk, sdkOptionsFromOpts, withSdkDefaults, } from '../lib/sdk-command.js';
-import { RelayError } from '@agent-relay/sdk';
+import { AgentRemovalPendingError, isNotFoundError, parseRemovalWaitTimeout, waitForAgentRemoval, } from '../lib/agent-removal.js';
 import { withAgentRegistrationDeadline, withDeadline } from '../lib/agent-registration.js';
 import { attributableReleaseReason } from '../lib/release-reason.js';
-function isNotFoundError(error) {
-    if (error instanceof RelayError)
-        return error.code === 'not_found' || error.statusCode === 404;
-    const statusCode = error && typeof error === 'object'
-        ? (error.statusCode ?? error.status)
-        : undefined;
-    return Number(statusCode) === 404;
-}
 function withAgentDefaults(overrides = {}) {
     return {
         ...withSdkDefaults(overrides),
@@ -95,21 +87,34 @@ export function registerAgentCommands(program, overrides = {}) {
         .command('remove')
         .description('Remove an agent while preserving attributed message history')
         .argument('<name>', 'Agent name')
-        .option('--reason <reason>', 'Removal reason')).action(async (name, opts) => {
+        .option('--reason <reason>', 'Removal reason')
+        .option('--wait', 'Wait until the registration is cleared', false)
+        .option('--no-wait', 'Return after the removal is accepted')
+        .option('--wait-timeout <ms>', 'Registration clearance timeout', '30000')).action(async (name, opts) => {
         await runSdk(deps, async () => {
             const relay = deps.createWorkspaceRelay(sdkOptionsFromOpts(opts));
             const reason = attributableReleaseReason(opts.reason, process.env.RELAY_AGENT_NAME ?? 'agent-relay CLI', 'agent removed');
+            const waitTimeoutMs = opts.wait === true ? parseRemovalWaitTimeout(opts.waitTimeout) : undefined;
             const result = await relay.workspace.release({ name, reason, deleteAgent: true });
-            // The release endpoint acknowledges an async action invocation — a
-            // resolved promise means the request was accepted, not that the
-            // deletion has finished. Only claim "Removed" once the invocation
-            // itself reports completion; otherwise say what actually happened.
-            if (result.status === 'completed') {
-                deps.log(`Removed agent ${name}.`);
-            }
-            else {
-                deps.log(`Removal of agent ${name} was initiated (status: ${result.status ?? 'pending'}) and is processed asynchronously.`);
+            if (waitTimeoutMs !== undefined) {
+                const removal = await waitForAgentRemoval({
+                    name,
+                    getAgent: (name) => relay.agents.get(name),
+                    listAgents: () => relay.agents.list(),
+                    timeoutMs: waitTimeoutMs,
+                });
+                if (removal.cleared) {
+                    deps.log(`Removed agent ${name}.`);
+                    return;
+                }
+                if (removal.observedPresent)
+                    throw new AgentRemovalPendingError(name);
+                // Unverifiable clearance keeps the asynchronous acknowledgement.
+                deps.error(`Could not verify removal: ${removal.readError ?? 'registration unavailable'}`);
+                deps.log(`Removal of agent ${name} was initiated (status: ${result.status ?? 'pending'}) and is processed asynchronously; registration clearance could not be verified.`);
+                return;
             }
+            deps.log(`Removal of agent ${name} was initiated (status: ${result.status ?? 'pending'}) and is processed asynchronously. Use --wait to verify the name is reusable.`);
         });
     });
 }

package/dist/cli/commands/agent.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../src/cli/commands/agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../../src/cli/commands/agent.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/fleet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fleet.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/fleet.ts"],"names":[],"mappings":"AAGA,OAAO,EAAwB,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAIL,uBAAuB,EACvB,uBAAuB,EACvB,mCAAmC,EACnC,qBAAqB,EAKtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAGL,KAAK,wBAAwB,EAE9B,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAgB,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAkBhE,OAAO,EAAE,8BAA8B,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,EAAE,wBAAwB,EAAmC,MAAM,wBAAwB,CAAC;AAEnG,OAAO,EAEL,yBAAyB,EACzB,+BAA+B,EAG/B,KAAK,gBAAgB,EACtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAML,KAAK,cAAc,EACpB,MAAM,uBAAuB,CAAC;AA8K/B,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,gBAAgB,CAAC;IACvB,GAAG,EAAE,cAAc,CAAC;IACpB,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAClE,0BAA0B,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,wBAAwB,CAAC;IACpF,yBAAyB,EAAE,OAAO,yBAAyB,CAAC;IAC5D,wBAAwB,EAAE,OAAO,wBAAwB,CAAC;IAC1D,eAAe,EAAE,OAAO,eAAe,CAAC;IACxC,qBAAqB,EAAE,OAAO,qBAAqB,CAAC;IACpD,+BAA+B,EAAE,OAAO,+BAA+B,CAAC;IACxE,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,mCAAmC,EAAE,OAAO,mCAAmC,CAAC;IAChF,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAClC,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IACnC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IACpC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,KAAK,CAAC;IAC9B,mBAAmB,EAAE,OAAO,8BAA8B,CAAC;CAC5D;AAqID,6EAA6E;AAC7E,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,EAChB,SAAS,GAAE,OAAO,CAAC,wBAAwB,CAAM,GAChD,IAAI,CAm8BN"}
+{"version":3,"file":"fleet.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/fleet.ts"],"names":[],"mappings":"AAIA,OAAO,EAAwB,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAIL,uBAAuB,EACvB,uBAAuB,EACvB,mCAAmC,EACnC,qBAAqB,EAKtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAGL,KAAK,wBAAwB,EAE9B,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAgB,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAC;AA+BhE,OAAO,EAAE,8BAA8B,EAAE,MAAM,kBAAkB,CAAC;AAClE,OAAO,EAAE,wBAAwB,EAAmC,MAAM,wBAAwB,CAAC;AAEnG,OAAO,EAEL,yBAAyB,EACzB,+BAA+B,EAG/B,KAAK,gBAAgB,EACtB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAML,KAAK,cAAc,EACpB,MAAM,uBAAuB,CAAC;AAkM/B,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,gBAAgB,CAAC;IACvB,GAAG,EAAE,cAAc,CAAC;IACpB,GAAG,EAAE,MAAM,MAAM,CAAC;IAClB,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAClE,0BAA0B,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,wBAAwB,CAAC;IACpF,yBAAyB,EAAE,OAAO,yBAAyB,CAAC;IAC5D,wBAAwB,EAAE,OAAO,wBAAwB,CAAC;IAC1D,eAAe,EAAE,OAAO,eAAe,CAAC;IACxC,qBAAqB,EAAE,OAAO,qBAAqB,CAAC;IACpD,+BAA+B,EAAE,OAAO,+BAA+B,CAAC;IACxE,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,mCAAmC,EAAE,OAAO,mCAAmC,CAAC;IAChF,uBAAuB,EAAE,OAAO,uBAAuB,CAAC;IACxD,GAAG,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAClC,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IACnC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IACpC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,KAAK,CAAC;IAC9B,mBAAmB,EAAE,OAAO,8BAA8B,CAAC;CAC5D;AAqID,6EAA6E;AAC7E,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,EAChB,SAAS,GAAE,OAAO,CAAC,wBAAwB,CAAM,GAChD,IAAI,CAwjCN"}

package/dist/cli/commands/fleet.js

@@ -1,3 +1,4 @@
+import { readTaskInput, validateTaskSize } from '../lib/task-input.js';
 import { randomUUID } from 'node:crypto';
 import path from 'node:path';
 import { InvalidArgumentError } from 'commander';
@@ -11,13 +12,15 @@ import { readBrokerConnection } from '../lib/broker-lifecycle.js';
 import { spawnAgentWithClient } from '../lib/client-factory.js';
 import { formatRelativeTime, sanitizeForTerminalLine } from '../lib/formatting.js';
 import { connectProjectBrokerClient } from '../lib/project-broker-client.js';
-import { isAvailableFleetNode } from '../lib/fleet-live-agents.js';
+import { AgentRemovalPendingError, parseRemovalWaitTimeout, waitForAgentRemoval, } from '../lib/agent-removal.js';
+import { classifySpawnFailure, mayStillBeRunning, nameTakenSpawnError, pendingSpawnError, probeSpawnLiveness, terminalSpawnOutcome, } from '../lib/spawn-liveness.js';
+import { heartbeatAgeMs, MAX_LIVE_HEARTBEAT_AGE_MS, isAvailableFleetNode } from '../lib/fleet-live-agents.js';
 import { declaredWorkforceMetadata } from '../lib/registration-metadata.js';
 import { redactSecrets } from '../lib/redact.js';
 import { attributableReleaseReason } from '../lib/release-reason.js';
 import { retireOwnedIntegrationBindings } from './integration.js';
 import { resolveSandboxRepository } from '../lib/sandbox-repo.js';
-import { spawnPlacementReceipt } from '../lib/spawn-lifecycle.js';
+import { sanitizedSpawnReceipt, spawnPlacementReceipt } from '../lib/spawn-lifecycle.js';
 import { resolveAgentToken, resolveWorkspaceSelection, persistWorkspaceRelaycastTarget, resolveWorkspaceKeyWithSource, resolveWorkspaceTransport, } from '../lib/sdk-client.js';
 import { addSdkOptions, printJson, runSdk, sdkOptionsFromOpts, withSdkDefaults, } from '../lib/sdk-command.js';
 const FLEET_NODES_ALWAYS_ON_MESSAGE = 'Fleet nodes need no per-workspace enablement; this command is a no-op.';
@@ -134,12 +137,12 @@ function spawnInvocationWithMergedPlacement(invocation) {
         ...invocation,
         placement: {
             ...(sdkPlacement ?? {}),
-            dispatchState: receipt.dispatchState,
+            dispatchState: sdkPlacement?.dispatchState ?? receipt.dispatchState,
             ...(invocationId ? { invocationId } : {}),
         },
     };
 }
-function throwForTerminalSpawnFailure(invocation) {
+function throwForTerminalSpawnFailure(invocation, name) {
     const placement = spawnPlacementReceipt(invocation);
     if (placement.state !== 'failed')
         return;
@@ -147,7 +150,7 @@ function throwForTerminalSpawnFailure(invocation) {
     const message = typeof invocation.error === 'string' && invocation.error.trim()
         ? invocation.error
         : 'Fleet spawn invocation reported a terminal failure.';
-    throw new RelayPlacementError('spawn_failed', message, {
+    const error = new RelayPlacementError('spawn_failed', message, {
         capability: typeof invocation.capability === 'string' ? invocation.capability : 'spawn',
         attempts: 1,
         ...(invocationId ? { invocationId } : {}),
@@ -155,6 +158,26 @@ function throwForTerminalSpawnFailure(invocation) {
         dispatchState: placement.dispatchState,
         receipt: invocation,
     });
+    throw classifySpawnFailure(message) ? nameTakenSpawnError(name, error) : error;
+}
+// Keep placement codes, receipts and cleanup behavior intact while explaining
+// why releasing a process alone does not make its Relaycast name reusable.
+async function runFleetSpawn(deps, fn) {
+    await runSdk(deps, async () => {
+        try {
+            await fn();
+        }
+        catch (error) {
+            if (error instanceof Error && /\bagent_already_exists\b/.test(error.message)) {
+                error.message +=
+                    ' Fleet release keeps the Relaycast identity unless --delete-agent is passed.' +
+                        ' To free a name you own, run `agent-relay fleet release <name> --delete-agent --wait`' +
+                        ' in the same workspace, then retry spawning once it reports clearance. This permanently' +
+                        ' deletes the identity and retires its provider bindings.';
+            }
+            throw error;
+        }
+    });
 }
 function withFleetDefaults(overrides = {}) {
     const core = overrides.core ?? withDefaults();
@@ -306,12 +329,65 @@ export function registerFleetCommands(program, overrides = {}) {
         .option('--all', 'Include offline/history nodes the way `fleet nodes --all` does')).action(async (options) => {
         await runFleetAgentList(deps, options);
     });
+    addSdkOptions(group
+        .command('spawn-status')
+        .description('Read an existing spawn dispatch without launching another agent')
+        .argument('<invocation-id>', 'Invocation ID returned by fleet spawn')).action(async (invocationId, options) => {
+        await runSdk(deps.sdk, async () => {
+            const clientOptions = sdkOptionsFromOpts(options);
+            let token = resolveAgentToken(clientOptions);
+            let launcherName;
+            let workspace;
+            try {
+                if (!token) {
+                    workspace = deps.sdk.createWorkspaceRelay(clientOptions);
+                    const name = `fleet-status-launcher-${randomUUID().slice(0, 8)}`;
+                    const launcher = await workspace.workspace.register({ name, metadata: { purpose: 'fleet-spawn-status' } }, { strict: true });
+                    launcherName = name;
+                    token = launcher.token;
+                    if (!token)
+                        throw new Error('The temporary fleet status launcher did not receive an agent token.');
+                }
+                // A minted launcher token must read from the gateway that minted it, and
+                // never alongside the workspace key that minted it (createAgentRelay
+                // rejects that pair), matching the spawn path's minted-token client.
+                const relay = deps.sdk.createAgentRelay(launcherName
+                    ? { token, baseUrl: resolveWorkspaceTransport(clientOptions).baseUrl }
+                    : { ...clientOptions, token });
+                const invocation = await relay.messaging.commands.getInvocation('spawn', invocationId);
+                // Keep this read-only surface on the existing safe receipt projection.
+                const receipt = sanitizedSpawnReceipt(invocation);
+                const result = spawnInvocationWithPlacement(receipt);
+                const output = receipt.output;
+                // --no-confirm dispatches may legitimately report launch without readiness.
+                // Preserve that evidence instead of claiming the launched worker failed.
+                if (['completed', 'success', 'succeeded'].includes(String(receipt.status).toLowerCase()) &&
+                    output?.spawned === true &&
+                    output.ready === false) {
+                    result.placement = { ...spawnPlacementReceipt(receipt), state: 'accepted' };
+                }
+                printJson(deps.sdk, { invocation: result });
+            }
+            finally {
+                if (launcherName && workspace) {
+                    await workspace.workspace
+                        .release({
+                        name: launcherName,
+                        reason: 'Temporary fleet spawn status launcher completed',
+                        deleteAgent: true,
+                    })
+                        .catch((error) => deps.warn(redactSecrets(String(error))));
+                }
+            }
+        });
+    });
     addSdkOptions(group
         .command('spawn')
         .description('Spawn locally by default, or select a fleet node or Cloud sandbox explicitly')
         .argument('<cli>', 'AI CLI to launch', parseFleetCli)
         .requiredOption('--name <name>', 'Worker agent name')
-        .requiredOption('--task <text>', 'Initial task instructions')
+        .option('--task <text>', 'Initial task instructions')
+        .option('--task-file <path>', 'Read the initial task from a local UTF-8 file')
         .option('--auto-place', 'Request automatic eligible-node placement in the Relay workspace')
         .option('--node <name>', 'Target a specific fleet node')
         .option('--target-node <name>', 'Alias for --node')
@@ -334,11 +410,11 @@ export function registerFleetCommands(program, overrides = {}) {
         .option('--objective <objective>', 'Declared objective (defaults to --task when omitted)')
         .option('--session-ref <reference>', 'Session reference for a resumable targeted spawn')
         .option('--no-confirm', 'Report a targeted spawn as soon as the node accepts it, without waiting for the node to confirm the agent actually launched')
-        .option('--confirm-timeout <ms>', `How long a targeted spawn waits for harness readiness (minimum ${MIN_VERIFIED_CONFIRM_TIMEOUT_MS}ms)`, '120000')).action(async (cli, options) => {
-        await runSdk(deps.sdk, async () => {
+        .option('--confirm-timeout <ms>', `How long a targeted spawn waits for harness readiness (minimum ${MIN_VERIFIED_CONFIRM_TIMEOUT_MS}ms)`, '360000')).action(async (cli, options) => {
+        await runFleetSpawn(deps.sdk, async () => {
             const clientOptions = sdkOptionsFromOpts(options);
             const name = requiredText(options.name, 'Worker name');
-            const task = requiredText(options.task, 'Task');
+            const task = (await readTaskInput(options.task, options.taskFile, true, { cli }));
             let targetNode = optionalText(options.targetNode, 'Target node') ?? optionalText(options.node, 'Node');
             const useSandbox = options.sandbox === true;
             // Explicit hosted credentials/transport and personas retain their legacy
@@ -414,7 +490,7 @@ export function registerFleetCommands(program, overrides = {}) {
             const objective = optionalText(options.objective, 'Objective');
             const sessionRef = optionalText(options.sessionRef, 'Session reference');
             const registrationMetadata = declaredWorkforceMetadata({ organization, project, workstream, role, objective }, task);
-            const confirmTimeoutText = optionalText(options.confirmTimeout, 'Confirm timeout') ?? '120000';
+            const confirmTimeoutText = optionalText(options.confirmTimeout, 'Confirm timeout') ?? '360000';
             const confirmTimeoutMs = Number(confirmTimeoutText);
             if (!Number.isFinite(confirmTimeoutMs) || confirmTimeoutMs <= 0) {
                 throw new Error('--confirm-timeout must be a positive number of milliseconds.');
@@ -838,31 +914,73 @@ export function registerFleetCommands(program, overrides = {}) {
                             'The Relayfile daemon synchronizes this tree; it intentionally has no .git directory.',
                         ].join(' ')
                         : undefined;
-                    const invocation = await relay.messaging.placement.spawn({
-                        capability: `spawn:${cli}`,
-                        node: targetNode,
-                        failFast: true,
-                        confirm,
-                        ...(confirm ? { confirmTimeoutMs: confirmTimeoutMs } : {}),
-                        input: {
+                    const spawnTask = sandbox &&
+                        checkoutRepository &&
+                        sandboxRepository &&
+                        mountSandboxRelayfile &&
+                        sandbox.outcome === 'provisioned'
+                        ? `${task}\n\nAgent Relay sandbox context: Relayfile records are available at ${sandbox.relayfileMountPath ?? '/workspace'}. The source checkout is separate; use ${workerCwd ?? 'the worker checkout'} for repository files and the mount for Relayfile records.`
+                        : liveSandboxContext
+                            ? `${task}\n\n${liveSandboxContext}`
+                            : task;
+                    // The sandbox context is appended after readTaskInput accepted the
+                    // task, so the composed task is what the worker must receive.
+                    validateTaskSize(spawnTask, { cli });
+                    let invocation;
+                    try {
+                        invocation = await relay.messaging.placement.spawn({
+                            capability: `spawn:${cli}`,
+                            node: targetNode,
+                            failFast: true,
+                            confirm,
+                            ...(confirm ? { confirmTimeoutMs: confirmTimeoutMs } : {}),
+                            input: {
+                                name,
+                                cli,
+                                task: spawnTask,
+                                ...(channel ? { channels: [channel] } : {}),
+                                ...(model ? { model } : {}),
+                                ...(workerCwd ? { worker_cwd: workerCwd } : {}),
+                                ...registrationMetadata,
+                                ...(sessionRef ? { session_ref: sessionRef } : {}),
+                            },
+                        });
+                    }
+                    catch (error) {
+                        if (!(error instanceof RelayPlacementError))
+                            throw error;
+                        if (error.code === 'spawn_failed' && classifySpawnFailure(error.message))
+                            throw nameTakenSpawnError(name, error);
+                        if (error.code !== 'spawn_unconfirmed')
+                            throw error;
+                        const liveness = await probeSpawnLiveness({
                             name,
-                            cli,
-                            task: sandbox &&
-                                checkoutRepository &&
-                                sandboxRepository &&
-                                mountSandboxRelayfile &&
-                                sandbox.outcome === 'provisioned'
-                                ? `${task}\n\nAgent Relay sandbox context: Relayfile records are available at ${sandbox.relayfileMountPath ?? '/workspace'}. The source checkout is separate; use ${workerCwd ?? 'the worker checkout'} for repository files and the mount for Relayfile records.`
-                                : liveSandboxContext
-                                    ? `${task}\n\n${liveSandboxContext}`
-                                    : task,
-                            ...(channel ? { channels: [channel] } : {}),
-                            ...(model ? { model } : {}),
-                            ...(workerCwd ? { worker_cwd: workerCwd } : {}),
-                            ...registrationMetadata,
-                            ...(sessionRef ? { session_ref: sessionRef } : {}),
-                        },
-                    });
+                            targetNode,
+                            ...(error.invocationId
+                                ? {
+                                    getInvocation: () => relay.messaging.commands.getInvocation('spawn', error.invocationId),
+                                }
+                                : {}),
+                            createClient: () => {
+                                const workspace = deps.sdk.createWorkspaceRelay(relaycastClientOptions);
+                                return { nodes: workspace.nodes, agents: workspace.agents };
+                            },
+                        });
+                        if (liveness.evidence === 'invocation_terminal') {
+                            try {
+                                invocation = terminalSpawnOutcome(liveness.invocation, error, confirm);
+                            }
+                            catch (terminalError) {
+                                if (terminalError instanceof RelayPlacementError &&
+                                    classifySpawnFailure(terminalError.message))
+                                    throw nameTakenSpawnError(name, terminalError);
+                                throw terminalError;
+                            }
+                        }
+                        else {
+                            throw pendingSpawnError(name, error, liveness, error.message);
+                        }
+                    }
                     const printableSandbox = (sandbox?.outcome === 'provisioned' || sandbox?.outcome === 'reused') && sandbox.relaycastTarget
                         ? {
                             ...sandbox,
@@ -884,9 +1002,7 @@ export function registerFleetCommands(program, overrides = {}) {
                     });
                 }
                 catch (error) {
-                    if (shouldCleanupSandbox &&
-                        sandbox?.outcome === 'provisioned' &&
-                        !(error instanceof RelayPlacementError && error.state === 'unconfirmed_may_be_running')) {
+                    if (shouldCleanupSandbox && sandbox?.outcome === 'provisioned' && !mayStillBeRunning(error)) {
                         await deps
                             .deleteCloudFleetSandbox({
                             cloudWorkspaceId: sandbox.cloudWorkspaceId,
@@ -960,7 +1076,7 @@ export function registerFleetCommands(program, overrides = {}) {
                     }
                     : {}),
             });
-            throwForTerminalSpawnFailure(invocation);
+            throwForTerminalSpawnFailure(invocation, name);
             printJson(deps.sdk, { invocation: spawnInvocationWithPlacement(invocation) });
         });
     });
@@ -969,12 +1085,16 @@ export function registerFleetCommands(program, overrides = {}) {
         .description('Release a spawned fleet agent')
         .argument('<name>', 'Worker agent name')
         .option('--reason <reason>', 'Release reason')
-        .option('--delete-agent', 'Permanently delete the agent after release')
+        .option('--delete-agent', 'Permanently delete the agent after release so its name can be reused')
+        .option('--wait', 'With --delete-agent, wait for registration clearance', false)
+        .option('--no-wait', 'Return after release is accepted')
+        .option('--wait-timeout <ms>', 'Registration clearance timeout', '30000')
         .option('--unsubscribe-bindings', 'Retire provider bindings owned by this identity (implied by --delete-agent)')).action(async (name, options) => {
         await runSdk(deps.sdk, async () => {
             warnIfInferredFromProjectSession(options, deps.warn);
             const workerName = requiredText(name, 'Worker name');
             const deleteAgent = options.deleteAgent === true;
+            const waitTimeoutMs = deleteAgent && options.wait === true ? parseRemovalWaitTimeout(options.waitTimeout) : undefined;
             const sdkOpts = sdkOptionsFromOpts(options);
             // One transport for both cleanup and release. Cleanup otherwise
             // substitutes the local broker session whenever --workspace-key is
@@ -1018,6 +1138,21 @@ export function registerFleetCommands(program, overrides = {}) {
                     reason,
                     deleteAgent: true,
                 });
+                if (waitTimeoutMs !== undefined) {
+                    // Construct/read on the same selected transport; unavailable credentials are uncertainty.
+                    const removal = await waitForAgentRemoval({
+                        name: workerName,
+                        getAgent: (name) => deps.sdk.createWorkspaceRelay(transport).agents.get(name),
+                        listAgents: () => deps.sdk.createWorkspaceRelay(transport).agents.list(),
+                        timeoutMs: waitTimeoutMs,
+                    });
+                    printJson(deps.sdk, { ...deleted, removal });
+                    if (!removal.cleared && removal.observedPresent)
+                        throw new AgentRemovalPendingError(workerName);
+                    if (!removal.cleared)
+                        deps.warn(`Removal was initiated asynchronously; could not verify clearance: ${removal.readError}`);
+                    return;
+                }
                 printJson(deps.sdk, deleted);
                 return;
             }
@@ -1302,12 +1437,21 @@ async function runFleetAgentList(deps, options) {
         }
         const now = new Date();
         const output = buildRows({ contributions, roster }, now);
+        const heartbeatNodes = contributions.map(({ node }) => ({
+            name: node.name,
+            lastHeartbeatAt: node.lastHeartbeatAt ?? null,
+            heartbeatAgeMs: heartbeatAgeMs(node, now.getTime()),
+        }));
+        if (heartbeatNodes.some((node) => node.heartbeatAgeMs !== null && node.heartbeatAgeMs > MAX_LIVE_HEARTBEAT_AGE_MS)) {
+            deps.warn('Some node heartbeats are older than 36 seconds. Listings are heartbeat snapshots and can differ within one heartbeat window.');
+        }
         if (options.pretty === true) {
             deps.log(formatPretty(output));
             return;
         }
         printJson(deps.sdk, {
             generatedAt: now.toISOString(),
+            nodes: heartbeatNodes,
             localNode: localNodeName ?? null,
             perNode: output.perNode,
             unplacedRoster: output.unplacedRoster,