@team-agent/installer 0.5.119 → 0.5.121

package/crates/team-agent/src/cli/tests/parser_safety.rs

@@ -0,0 +1,383 @@
+//! Public Phase-0 parser regressions. No model, real team or external pane is used.
+#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
+use super::*;
+use std::sync::atomic::{AtomicU64, Ordering};
+
+fn strings(args: &[&str]) -> Vec<String> {
+    args.iter().map(|arg| (*arg).to_string()).collect()
+}
+
+struct Sandbox(PathBuf);
+impl Sandbox {
+    fn new() -> Self {
+        static NEXT: AtomicU64 = AtomicU64::new(0);
+        let dir = std::env::temp_dir().join(format!(
+            "ta-cli-parser334-{}-{}",
+            std::process::id(),
+            NEXT.fetch_add(1, Ordering::Relaxed)
+        ));
+        std::fs::create_dir(&dir).unwrap();
+        Self(dir)
+    }
+    fn reject(&self, args: &[&str]) {
+        assert_eq!(run(&strings(args), &self.0), ExitCode::Usage, "{args:?}");
+        assert!(
+            std::fs::read_dir(&self.0).unwrap().next().is_none(),
+            "parser errors must not create state, logs, roles or a database: {args:?}"
+        );
+    }
+}
+impl Drop for Sandbox {
+    fn drop(&mut self) {
+        let _ = std::fs::remove_dir_all(&self.0);
+    }
+}
+
+#[test]
+fn p1_read_and_lifecycle_unknown_flags_are_usage_without_writes() {
+    for command in [
+        "status",
+        "shutdown",
+        "restart",
+        "approvals",
+        "doctor",
+        "models",
+    ] {
+        let sandbox = Sandbox::new();
+        sandbox.reject(&[command, "--worksapce", "never-selected", "--json"]);
+    }
+}
+
+#[test]
+fn p1_missing_duplicate_extra_and_invalid_numeric_arguments_refuse() {
+    for args in [
+        vec!["status", "--workspace"],
+        vec!["status", "--workspace", "--team", "x"],
+        vec!["status", "--team=x", "--team", "y"],
+        vec!["status", "worker", "extra"],
+        vec!["shutdown", "extra"],
+        vec!["inbox", "leader", "--limit", "NaN"],
+        vec!["inbox", "leader", "-n", "3", "--limit=4"],
+        vec!["restart", "--session-converge-deadline=inf"],
+        vec!["status", "--detail", "--summary"],
+    ] {
+        Sandbox::new().reject(&args);
+    }
+}
+
+#[test]
+fn p2_equal_and_split_values_have_identical_fields_without_losing_equals() {
+    let sandbox = Sandbox::new();
+    let path = sandbox.0.join("space = directory");
+    std::fs::create_dir(&path).unwrap();
+    let path = path.to_string_lossy();
+    let split = parse_args(&strings(&[
+        "--workspace",
+        &path,
+        "--name",
+        "x=y",
+        "--timeout",
+        "1.25",
+    ]));
+    let inline = parse_args(&strings(&[
+        &format!("--workspace={path}"),
+        "--name=x=y",
+        "--timeout=1.25",
+    ]));
+    assert_eq!(inline.workspace, split.workspace);
+    assert_eq!(inline.name, split.name);
+    assert_eq!(inline.timeout, split.timeout);
+    for path in [r"C:\owned dir\a=b", r"\\server\share\a=b"] {
+        assert_eq!(
+            parse_args(&strings(&[&format!("--workspace={path}")])).workspace,
+            Some(PathBuf::from(path))
+        );
+    }
+}
+
+#[test]
+fn p2_missing_explicit_workspace_never_falls_back_to_cwd_or_writes_logs() {
+    for inline in [false, true] {
+        let sandbox = Sandbox::new();
+        let missing = sandbox.0.join("missing=a b").to_string_lossy().to_string();
+        let mut args = vec!["status".to_string()];
+        if inline {
+            args.push(format!("--workspace={missing}"));
+        } else {
+            args.extend(["--workspace".to_string(), missing]);
+        }
+        assert_eq!(run(&args, &sandbox.0), ExitCode::Usage);
+        assert!(std::fs::read_dir(&sandbox.0).unwrap().next().is_none());
+    }
+}
+
+#[test]
+fn p3_bare_restart_is_never_interpreted_as_workspace_even_if_directory_exists() {
+    for exists in [false, true] {
+        let sandbox = Sandbox::new();
+        if exists {
+            std::fs::create_dir(sandbox.0.join("worker")).unwrap();
+        }
+        assert!(matches!(
+            restart_args(&strings(&["worker"]), &sandbox.0),
+            Err(CliError::Usage(_))
+        ));
+        assert!(matches!(
+            restart_args(&strings(&["reviewer.v2"]), &sandbox.0),
+            Err(CliError::Usage(_))
+        ));
+    }
+}
+
+#[test]
+fn p4_attach_requires_explicit_nonempty_provider_but_keeps_declared_identity() {
+    let sandbox = Sandbox::new();
+    for args in [vec![], vec!["--provider="], vec!["--provider", ""]] {
+        assert!(matches!(
+            attach_leader_args(&strings(&args), &sandbox.0),
+            Err(CliError::Usage(_))
+        ));
+    }
+    for provider in ["pi", "claude", "codex"] {
+        let expected = parse_cli_provider(provider).unwrap();
+        assert_eq!(
+            attach_leader_args(&strings(&["--provider", provider]), &sandbox.0)
+                .unwrap()
+                .provider,
+            expected
+        );
+    }
+}
+
+#[test]
+fn p5_start_force_refuses_and_guides_to_existing_stop_start_commands() {
+    let sandbox = Sandbox::new();
+    match start_agent_args(&strings(&["worker", "--force"]), &sandbox.0) {
+        Err(CliError::Usage(message)) => {
+            assert!(
+                message.contains("stop-agent") && message.contains("start-agent"),
+                "{message}"
+            );
+        }
+        _ => panic!("--force must not be accepted and then silently discarded"),
+    }
+}
+
+#[test]
+fn payload_delimiter_preserves_help_no_display_and_equal_bytes() {
+    let parsed = parse_args(&strings(&[
+        "worker",
+        "--",
+        "--help",
+        "--no-display",
+        "--workspace=a=b",
+    ]));
+    assert_eq!(
+        parsed.positionals,
+        strings(&["worker", "--help", "--no-display", "--workspace=a=b"])
+    );
+    assert!(parsed.workspace.is_none());
+    let literal = strings(&["--", "--help", "--no-display", "--workspace=a=b"]);
+    assert_eq!(
+        leader_launcher_args(&literal).unwrap().provider_args,
+        literal[1..]
+    );
+}
+
+#[test]
+fn consumed_prompt_help_does_not_trigger_global_help_or_scope_fallback() {
+    let sandbox = Sandbox::new();
+    sandbox.reject(&[
+        "add-agent",
+        "worker",
+        "--prompt",
+        "--help",
+        "--provider",
+        "pi",
+        "--bypass",
+        "false",
+        "--workspace",
+        "missing",
+    ]);
+}
+
+#[test]
+fn real_control_help_remains_an_effect_free_short_circuit() {
+    let sandbox = Sandbox::new();
+    assert_eq!(
+        run(&strings(&["status", "--unknown", "--help"]), &sandbox.0),
+        ExitCode::Ok
+    );
+    assert!(std::fs::read_dir(&sandbox.0).unwrap().next().is_none());
+}
+
+#[test]
+fn every_dispatch_command_has_a_closed_control_schema() {
+    for spec in COMMAND_SPECS {
+        if !matches!(spec.kind, CommandKind::Dispatch(_))
+            || matches!(spec.name, "route" | "leader-prompt")
+        {
+            continue;
+        }
+        // Family grammars select the concrete operation before its closed
+        // schema; the family itself has no permissive catch-all flag parser.
+        let schema = if matches!(spec.name, "team" | "agent") {
+            "intent-start"
+        } else {
+            spec.name
+        };
+        let checked = super::super::arguments::parse(schema, &strings(&["--help"])).unwrap();
+        assert!(checked.help, "{} must have a schema", spec.name);
+        let compatibility =
+            super::super::arguments::parse(schema, &strings(&["--no-display"])).unwrap();
+        assert!(
+            compatibility.tokens.is_empty(),
+            "explicit legacy no-display control: {}",
+            spec.name
+        );
+        assert!(super::super::arguments::parse(schema, &strings(&["--unknown"])).is_err());
+    }
+    for command in ["wait", "coordinator", "attach-app-server-leader"] {
+        assert!(
+            super::super::arguments::parse(command, &strings(&["--workspace", "--once"])).is_err()
+        );
+    }
+}
+
+#[test]
+fn canonical_scope_equal_and_split_share_one_directory_and_reject_conflicts() {
+    let sandbox = Sandbox::new();
+    let selected = sandbox.0.join("scope=a b");
+    std::fs::create_dir(&selected).unwrap();
+    let canonical = std::fs::canonicalize(&selected).unwrap();
+    for args in [
+        strings(&["--workspace", "scope=a b"]),
+        strings(&["--workspace=scope=a b"]),
+    ] {
+        let checked = super::super::arguments::parse("status", &args).unwrap();
+        let args = resolve_command_scope("status", checked.tokens, &sandbox.0).unwrap();
+        assert_eq!(parse_args(&args).workspace, Some(canonical.clone()));
+    }
+    let args =
+        super::super::arguments::parse("restart", &strings(&["./scope=a b", "--workspace=."]))
+            .unwrap();
+    assert!(matches!(
+        resolve_command_scope("restart", args.tokens, &sandbox.0),
+        Err(CliError::Usage(_))
+    ));
+    let args = super::super::arguments::parse(
+        "restart",
+        &strings(&["./scope=a b", "--workspace=scope=a b"]),
+    )
+    .unwrap();
+    let args = resolve_command_scope("restart", args.tokens, &sandbox.0).unwrap();
+    assert_eq!(
+        restart_args(&args, &sandbox.0).unwrap().workspace,
+        canonical
+    );
+}
+
+#[test]
+fn payload_help_is_not_control_and_compatibility_flags_do_not_delete_literals() {
+    let checked = super::super::arguments::parse(
+        "add-agent",
+        &strings(&["w", "--provider=pi", "--bypass=false", "--prompt", "--help"]),
+    )
+    .unwrap();
+    assert!(!checked.help);
+    let (_, patch) = role_agent_args(&checked.tokens, true).unwrap();
+    assert_eq!(patch.prompt.as_deref(), Some("--help"));
+    let checked = super::super::arguments::parse(
+        "send",
+        &strings(&["w", "--", "--help", "--no-display", "--workspace=a=b"]),
+    )
+    .unwrap();
+    assert!(!checked.help);
+    assert_eq!(
+        parse_args(&checked.tokens).positionals,
+        strings(&["w", "--help", "--no-display", "--workspace=a=b"])
+    );
+    let checked = super::super::arguments::parse(
+        "quick-start",
+        &strings(&["--no-display", "--", "--no-display"]),
+    )
+    .unwrap();
+    assert_eq!(checked.tokens, strings(&["--", "--no-display"]));
+    assert!(super::super::arguments::parse("status", &strings(&["--yes"])).is_err());
+    assert!(!super::super::arguments::has_flag(
+        "add-agent",
+        &strings(&["--prompt", "--json"]),
+        "--json"
+    ));
+}
+
+#[test]
+fn restart_node_directory_phase1_migration_refuses_without_mutating_state() {
+    for agent in [false, true] {
+        for directory in [false, true] {
+            let sandbox = Sandbox::new();
+            let runtime = sandbox.0.join(".team/runtime");
+            std::fs::create_dir_all(&runtime).unwrap();
+            let state = if agent {
+                r#"{"agents":{"worker":{"status":"stopped"}}}"#
+            } else {
+                r#"{"agents":{}}"#
+            };
+            std::fs::write(runtime.join("state.json"), state).unwrap();
+            if directory {
+                std::fs::create_dir(sandbox.0.join("worker")).unwrap();
+            }
+            assert_eq!(
+                run(&strings(&["restart", "worker"]), &sandbox.0),
+                // P3 Phase1: a plain ID is an agent intent; same-name directory
+                // remains a syntax ambiguity. Incomplete runtime still refuses.
+                if directory {
+                    ExitCode::Usage
+                } else {
+                    ExitCode::Error
+                }
+            );
+            assert_eq!(
+                std::fs::read_to_string(runtime.join("state.json")).unwrap(),
+                state
+            );
+            // Canonical planning refusals are effect-free envelopes; legacy
+            // restart diagnostics remain on their frozen entry point.
+            assert!(!sandbox.0.join(".team/logs").exists());
+        }
+    }
+}
+
+#[test]
+fn text_queries_and_native_rendering_switches_keep_literal_boundaries() {
+    for backend in ["tmux", "TMUX", " conpty "] {
+        let input = format!("--backend={backend}");
+        let checked = super::super::arguments::parse("quick-start", &[input]).unwrap();
+        let parsed = quick_start_args(&checked.tokens, Path::new(".")).unwrap();
+        assert_eq!(parsed.backend.as_deref(), Some(backend));
+    }
+    for query in ["", "  ", "--help", "a=b"] {
+        let checked =
+            super::super::arguments::parse("models", &strings(&[&format!("--search={query}")]))
+                .unwrap();
+        assert!(!checked.help);
+        let parsed = models_args(&checked.tokens).unwrap();
+        assert_eq!(
+            parsed.search.as_deref(),
+            (!query.trim().is_empty()).then_some(query)
+        );
+    }
+    let checked =
+        super::super::arguments::parse("models", &strings(&["--search", "--help"])).unwrap();
+    assert!(!checked.help);
+    assert!(super::super::arguments::has_flag(
+        "pi",
+        &strings(&["--json", "--", "--help"]),
+        "--json"
+    ));
+    assert!(!super::super::arguments::has_flag(
+        "pi",
+        &strings(&["--", "--json"]),
+        "--json"
+    ));
+}

package/crates/team-agent/src/cli/tests/run_delegation.rs

@@ -1,5 +1,8 @@
 use super::*;
 
+#[path = "../../../tests/support/hermetic.rs"]
+mod hermetic_guard;
+
 struct TeamSocketGuard {
     ws: std::path::PathBuf,
 }
@@ -212,10 +215,16 @@ fn run_dispatches_quick_start_compiles_spec() {
 // coordinator/health.rs, message_store.
 // =========================================================================
 #[test]
-fn cli_quick_start_invokes_real_lifecycle_compiles_spec() {
-    let team = deleg_team_dir_with_healthy_coordinator();
-    let ws = crate::model::paths::team_workspace(&team).unwrap();
-    let _guard = TeamSocketGuard { ws };
+#[serial_test::serial(env)]
+fn cli_quick_start_invokes_real_lifecycle_admission_before_runtime_effects() {
+    let env = hermetic_guard::HermeticTestEnv::enter("issue337-cli-admission");
+    env.scrub_tmux();
+    env.assert_no_real_tmux();
+    let workspace = env.workspace("ws");
+    let team = workspace.join("roles");
+    std::fs::create_dir_all(team.join("agents")).unwrap();
+    std::fs::write(team.join("TEAM.md"), DELEG_TEAM_MD).unwrap();
+    std::fs::write(team.join("agents/implementer.md"), DELEG_VALID_ROLE).unwrap();
     let args = QuickStartArgs {
         workspace: crate::model::paths::team_workspace(&team).unwrap(),
         agents_dir: team.clone(),
@@ -226,16 +235,17 @@ fn cli_quick_start_invokes_real_lifecycle_compiles_spec() {
         json: true,
         detail: false,
     };
-    let _ = cmd_quick_start(&args); // real quick_start compiles the spec before any coordinator/launch step
-                                    // E5: spec compiled to .team/runtime/<team_key>/, NOT the user team dir.
-    let team_key = "clidelegteam";
-    let workspace = crate::model::paths::team_workspace(&team).unwrap();
-    let runtime_spec = crate::model::paths::runtime_spec_path(&workspace, &team_key);
-    assert!(
-            runtime_spec.exists(),
-            "cmd_quick_start must delegate to crate::lifecycle::quick_start, which compiles team.spec.yaml \
-             under .team/runtime/<team_key>/; the placeholder never writes it"
-        );
+    let result = cmd_quick_start(&args).expect("real lifecycle admission");
+    assert_eq!(result.exit, ExitCode::Error);
+    let CmdOutput::Json(value) = result.output else { panic!() };
+    assert_eq!(value["status"], "preflight_blocked");
+    assert!(value["blockers"].to_string().contains("caller_pane_missing"));
+    assert_eq!(value["effects"]["worker_panes_started"], json!([]));
+    assert_eq!(value["effects"]["coordinator_start"], "not_attempted");
+    let runtime_spec = crate::model::paths::runtime_spec_path(&args.workspace, "clidelegteam");
+    assert!(!runtime_spec.exists(), "#337 admission precedes runtime spec publication");
+    assert!(!crate::state::persist::runtime_state_path(&args.workspace).exists());
+    assert!(!args.workspace.join(".team/team.db").exists());
     assert!(
         !team.join("team.spec.yaml").exists(),
         "E5: quick_start must NOT write spec into the user team dir"
@@ -333,12 +343,10 @@ fn cli_add_agent_duplicate_id_surfaces_real_error() {
         );
 }
 
-// 5 [P1] — cmd_status --json emits the concise nine-field node projection.
-// Status must not leak coordinator/db/history diagnostics; missing exact nodeprobe evidence remains
-// an explicit unknown projection. The fixture still seeds a real store to ensure the status path
-// does not accidentally depend on coordinator or mailbox reads.
+// Nine base fields remain; #338 adds only observation reason and scoped action
+// when uncertain. No coordinator/db/history/payload data enters the node.
 #[test]
-fn cli_status_emits_nine_field_brief_without_diagnostics() {
+fn cli_status_emits_brief_with_scoped_unknown_diagnostics() {
     let ws = seed_status_workspace(); // writes .team/runtime/state.json
     let store = crate::message_store::MessageStore::open(&ws).unwrap();
     let _ = store
@@ -406,10 +414,46 @@ fn cli_status_emits_nine_field_brief_without_diagnostics() {
             "health",
             "session_name",
             "tmux_command",
+            "observation_reason",
+            "next_action",
         ]
         .into_iter()
         .collect()
     );
+    assert_eq!(nodes[0]["runtime_status"], "unknown");
+    assert!(!nodes[0]["observation_reason"].as_str().unwrap().is_empty());
+    assert!(nodes[0]["next_action"].as_str().unwrap().contains(&*args.workspace.to_string_lossy()));
+}
+
+#[test]
+#[serial_test::serial(env)]
+fn issue338_doctor_reports_same_scope_unknown_observations_without_state_writes() {
+    let env = hermetic_guard::HermeticTestEnv::enter("issue338-doctor");
+    env.scrub_tmux();
+    env.assert_no_real_tmux();
+    let workspace = env.workspace("ws");
+    crate::state::persist::save_runtime_state(&workspace, &json!({
+        "team_key": "current", "session_name": "test-workers",
+        "agents": {"worker": {"provider": "pi", "status": "running"}},
+    })).unwrap();
+    // Complete the existing legacy-to-current state normalization as fixture
+    // preparation; this test covers observation of an already-current runtime.
+    crate::state::persist::load_runtime_state(&workspace).unwrap();
+    let state_path = crate::state::persist::runtime_state_path(&workspace);
+    let before = std::fs::read(&state_path).unwrap();
+    let result = cmd_doctor(&DoctorArgs {
+        spec: None, workspace: workspace.clone(), gate: None, comms: false,
+        team: Some("current".into()), fix: false, fix_schema: false,
+        cleanup_orphans: false, confirm: false, json: true,
+    }).unwrap();
+    let CmdOutput::Json(value) = result.output else { panic!() };
+    let node = &value["runtime"]["observations"][0];
+    assert_eq!(node["name"], "worker");
+    assert_eq!(node["observation_reason"], "endpoint_unregistered");
+    let action = node["next_action"].as_str().unwrap();
+    assert!(action.contains("--team 'current'"));
+    assert!(action.contains(&*workspace.to_string_lossy()));
+    assert_eq!(std::fs::read(state_path).unwrap(), before);
 }
 
 // 6 [P1] — cmd_shutdown delegates to the REAL crate::coordinator::stop_coordinator (+ tmux

package/crates/team-agent/src/cli/tests/shutdown_kill_plan.rs

@@ -1254,6 +1254,62 @@ fn bounded_coordinator_stop_returns_grace_window_late_success() {
     assert_eq!(report.status, crate::coordinator::StopOutcome::Stopped);
 }
 
+#[test]
+fn bounded_coordinator_stop_retains_completion_beyond_old_1150ms_cap() {
+    let ws = tmp_shutdown_workspace("coordinator-stop-after-old-cap");
+    let cleanup = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
+    let worker_cleanup = cleanup.clone();
+    let report = crate::cli::lifecycle_port::stop_coordinator_bounded_with(
+        crate::coordinator::WorkspacePath::new(ws),
+        std::time::Duration::from_secs(20),
+        move |_workspace| {
+            std::thread::sleep(std::time::Duration::from_millis(1300));
+            worker_cleanup.store(true, std::sync::atomic::Ordering::SeqCst);
+            Ok(crate::coordinator::StopReport {
+                ok: true,
+                status: crate::coordinator::StopOutcome::Stopped,
+                pid: Some(crate::coordinator::Pid::new(12345)),
+            })
+        },
+    )
+    .expect("completion inside the shutdown budget must not be abandoned")
+    .expect("owned stop completed successfully");
+
+    assert!(cleanup.load(std::sync::atomic::Ordering::SeqCst));
+    assert!(report.ok);
+    assert_eq!(report.status, crate::coordinator::StopOutcome::Stopped);
+}
+
+#[test]
+fn bounded_coordinator_stop_does_not_claim_completion_after_budget_exhaustion() {
+    let ws = tmp_shutdown_workspace("coordinator-stop-real-timeout");
+    let (release_tx, release_rx) = std::sync::mpsc::channel();
+    let (completed_tx, completed_rx) = std::sync::mpsc::channel();
+    let report = crate::cli::lifecycle_port::stop_coordinator_bounded_with(
+        crate::coordinator::WorkspacePath::new(ws),
+        std::time::Duration::from_millis(1),
+        move |_workspace| {
+            release_rx.recv().unwrap();
+            completed_tx.send(()).unwrap();
+            Ok(crate::coordinator::StopReport {
+                ok: true,
+                status: crate::coordinator::StopOutcome::Stopped,
+                pid: Some(crate::coordinator::Pid::new(12345)),
+            })
+        },
+    );
+
+    assert!(report.is_none(), "an unfinished stop must remain unknown");
+    assert!(matches!(
+        completed_rx.try_recv(),
+        Err(std::sync::mpsc::TryRecvError::Empty)
+    ));
+    release_tx.send(()).unwrap();
+    completed_rx
+        .recv_timeout(std::time::Duration::from_secs(5))
+        .expect("release the controlled worker without leaving a blocked thread");
+}
+
 #[test]
 fn shutdown_outcome_late_or_postcheck_gone_is_ok_with_lsof_diagnostic() {
     let out = crate::cli::lifecycle_port::classify_shutdown_outcome(

package/crates/team-agent/src/cli/tests/verb_install_skill.rs

@@ -84,9 +84,10 @@ fn install_skill_invalid_target_is_usage_error() {
     );
     assert_eq!(
         code,
-        ExitCode::Error,
-        "install-skill --target bogus must error (CliError::Usage -> emit_cli_error exit 1)"
+        ExitCode::Usage,
+        "invalid control values must fail as Usage2 before installation"
     );
+    assert!(!ws.join(".team/logs").exists());
     let _ = std::fs::remove_dir_all(&ws);
     let _ = std::fs::remove_dir_all(source.parent().unwrap());
 }

package/crates/team-agent/src/cli/tests/verb_profile.rs

@@ -194,7 +194,9 @@ fn profile_init_accepts_local_proxy_mode_and_rejects_unknown_values() {
         ]),
         &ws,
     );
-    assert_eq!(invalid, ExitCode::Error, "unknown proxy mode must fail");
+    assert_eq!(invalid, ExitCode::Usage, "unknown proxy mode must fail as Usage2");
+    assert!(!profiles_dir(&ws).join("bad_proxy.env").exists());
+    assert!(!ws.join(".team/logs").exists());
     let _ = std::fs::remove_dir_all(&ws);
 }
 

package/crates/team-agent/src/contract_runtime/backend.rs

@@ -689,7 +689,7 @@ fn write_role(binding: &Binding, identity: &InstanceIdentity, role: &RoleConfig)
     file.sync_all()?;
     Ok(())
 }
-pub(super) fn read_role(binding: &Binding, identity: &InstanceIdentity) -> Result<RoleConfig, BackendError> {
+pub(crate) fn read_role(binding: &Binding, identity: &InstanceIdentity) -> Result<RoleConfig, BackendError> {
     let mut path = role_path(binding, identity);
     // Existing generation-one deployments retain their immutable source.
     if identity.generation == Generation(1) {

package/crates/team-agent/src/db/message_store.rs

@@ -585,6 +585,30 @@ impl MessageStore {
         Ok(rows == 1)
     }
 
+    /// Release only an owned claim that has performed no input. Readiness
+    /// waiting must remain retryable without consuming the input-attempt budget.
+    /// A changed attempt, status, or error means this caller no longer owns it.
+    pub(crate) fn release_delivery_before_input(
+        &self,
+        message_id: &str,
+        attempt: u32,
+        reason: &str,
+    ) -> Result<bool, MessageStoreError> {
+        if attempt == 0 || reason.is_empty() {
+            return Ok(false);
+        }
+        let conn = crate::db::schema::open_db(&self.path)?;
+        let rows = conn.execute(
+            "update messages
+             set delivery_attempts = delivery_attempts - 1,
+                 error = ?3, updated_at = ?4
+             where message_id = ?1 and status = 'target_resolved'
+               and error is null and delivery_attempts = ?2",
+            params![message_id, attempt, reason, now_ts()],
+        )?;
+        Ok(rows == 1)
+    }
+
     /// Read inbox rows through [`Self::inbox`]; recovery transitions below are
     /// separate repository owners and are not claim eligibility.
     pub fn requeue_blocked_leader_messages(
@@ -1168,6 +1192,47 @@ mod tests {
         assert_eq!(col_i64(&read(&s), &mid, "delivery_attempts"), 1);
     }
 
+    #[test]
+    fn release_delivery_before_input_preserves_budget_and_single_winner() {
+        let s = store();
+        let mid = s.create_message(Some("t"), "s", "r", "c", None, true, None).unwrap();
+        assert!(s.claim_for_delivery(&mid).unwrap());
+        assert!(!s.claim_for_delivery(&mid).unwrap());
+        assert!(s.release_delivery_before_input(&mid, 1, "mcp_handshake_missing").unwrap());
+        assert_eq!(col_i64(&read(&s), &mid, "delivery_attempts"), 0);
+        assert_eq!(col_str(&read(&s), &mid, "error").as_deref(), Some("mcp_handshake_missing"));
+        assert!(!s.release_delivery_before_input(&mid, 1, "late").unwrap());
+        assert!(s.claim_for_delivery(&mid).unwrap());
+        assert!(!s.claim_for_delivery(&mid).unwrap());
+        assert_eq!(col_i64(&read(&s), &mid, "delivery_attempts"), 1);
+    }
+
+    #[test]
+    fn release_delivery_before_input_cannot_overwrite_changed_claims() {
+        let s = store();
+        let mid = s.create_message(Some("t"), "s", "r", "c", None, true, None).unwrap();
+        assert!(s.claim_for_delivery(&mid).unwrap());
+        assert!(!s.release_delivery_before_input(&mid, 0, "missing").unwrap());
+        assert!(!s.release_delivery_before_input(&mid, 2, "stale").unwrap());
+        s.mark(&mid, "target_resolved", Some("other_owner")).unwrap();
+        assert!(!s.release_delivery_before_input(&mid, 1, "stale").unwrap());
+        assert_eq!(col_str(&read(&s), &mid, "error").as_deref(), Some("other_owner"));
+        assert!(s.claim_for_delivery(&mid).unwrap());
+        assert!(!s.release_delivery_before_input(&mid, 1, "old_claim").unwrap());
+        assert_eq!(col_i64(&read(&s), &mid, "delivery_attempts"), 2);
+        assert_eq!(col_str(&read(&s), &mid, "error"), None);
+        for status in ["cancelled", "delivered", "submitted_unverified"] {
+            // Each terminal/effect state needs its own row: mark correctly
+            // refuses to downgrade a previously delivered row.
+            let changed = s.create_message(Some("t"), "s", "r", "c", None, true, None).unwrap();
+            assert!(s.claim_for_delivery(&changed).unwrap());
+            s.mark(&changed, status, None).unwrap();
+            assert!(!s.release_delivery_before_input(&changed, 1, "stale").unwrap());
+            assert_eq!(status_of(&read(&s), &changed), status);
+            assert_eq!(col_i64(&read(&s), &changed, "delivery_attempts"), 1);
+        }
+    }
+
     #[test]
     fn claim_for_delivery_never_claims_stored_only_presentation() {
         let s = store();