fix: report unproven fleet spawns as unconfirmed

KH
2d ago
+186-68

Summary

  • Keep explicit spawned:false results as hard failures.
  • Treat completed delegated invocations without ready:true proof as spawn_unconfirmed / unconfirmed_may_be_running, and preserve their output instead of reporting a false hard failure.
  • Add regression coverage for the SDK placement, CLI confirmation, and node delegation paths.

Investigation

Several fleet nodes were online but their handlers reported relay-broker/12.4.0; only kjg-lap published the live-agent-name heartbeat expected by current relay code. Fleet listings and counts on those nodes were consequently incomplete or inconsistent. Current Relay source already has Body+Enter sequencing with write acknowledgments for PTY injection, exact live-name heartbeats, and bounded readiness gates. Existing nodes need the updated broker release and a broker restart to pick up those fixes. No nodes were restarted during this investigation.

Verification

  • Targeted Vitest regressions: 12 passed.
  • npm run build:sdk, npm run build:fleet, and CLI npx tsc --noEmit passed.

🤖 Generated with Claude Code

[!NOTE]
Medium Risk
Changes spawn outcome classification across SDK, MCP, CLI, and fleet node delegation, which affects orchestration retry behavior and duplicate-spawn risk if callers ignore the new unconfirmed state.

Overview
Completed spawn invocations that lack explicit spawned:true and ready:true proof are no longer treated as hard failures. They now surface as spawn_unconfirmed with state unconfirmed_may_be_running, including guidance not to retry blindly because the worker may already be running.

Explicit spawned:false remains a definitive failure (spawn_failed / failed) across the SDK placement.spawn path, MCP spawn verification, spawnLifecycleState, and fleet serve-node delegation confirmation.

serve-node stops throwing on ambiguous completed child results and returns preserved broker output (or an empty object) so upper layers can classify unconfirmed spawns instead of reporting a false terminal error.

fleet spawn and legacy MCP add_agent now succeed or return structured unconfirmed placement rather than exiting with a failed spawn when proof is missing. Fleet attach sends recent_spawn: true on the first terminal session ticket request so the server can retry agent visibility after a spawn that finished just before the Cloud row appears.

Reviewed by Cursor Bugbot for commit 60f45c36741d77d8cbf26da5ac9bdeeaba08f589. Bugbot is set up for automated code reviews on this repo. Configure here.

Agent Relay sessions

  • codex session 01a0f63e · opened via gh pr create · last active 2026-10-01