@team-agent/installer 0.5.73 → 0.5.74

package/Cargo.lock

@@ -581,7 +581,7 @@ dependencies = [
 
 [[package]]
 name = "team-agent"
-version = "0.5.73"
+version = "0.5.74"
 dependencies = [
  "anyhow",
  "chrono",

package/Cargo.toml

@@ -9,7 +9,7 @@ members = ["crates/team-agent", "crates/win-conpty-phase0", "crates/conpty-trans
 
 [workspace.package]
 edition = "2021"
-version = "0.5.73"
+version = "0.5.74"
 license = "AGPL-3.0"
 rust-version = "1.95"
 

package/crates/team-agent/src/cli/adapters.rs

@@ -129,6 +129,9 @@ pub fn cmd_quick_start(args: &QuickStartArgs) -> Result<CmdResult, CliError> {
         .get("status")
         .and_then(Value::as_str)
         .map(str::to_string);
+    if !args.detail {
+        lifecycle_port::compact_quick_start_value(&mut value);
+    }
     if args.json
         || value.get("ok").and_then(Value::as_bool) == Some(false)
         || session_capture_incomplete
@@ -1377,10 +1380,12 @@ pub fn cmd_takeover(args: &TakeoverArgs) -> Result<CmdResult, CliError> {
 
 /// `cmd_claim_leader`(`commands.py:156`)。
 pub fn cmd_claim_leader(args: &ClaimLeaderArgs) -> Result<CmdResult, CliError> {
-    Ok(CmdResult::from_json(
-        leader_port::claim_leader(&args.workspace, args.team.as_deref(), args.confirm)?,
-        args.json,
-    ))
+    let mut value =
+        leader_port::claim_leader(&args.workspace, args.team.as_deref(), args.confirm)?;
+    if !args.detail {
+        leader_port::compact_lease_value(&mut value);
+    }
+    Ok(CmdResult::from_json(value, args.json))
 }
 
 /// `cmd_identity`(`commands.py:160`)。
@@ -1401,15 +1406,16 @@ pub fn cmd_shutdown(args: &ShutdownArgs) -> Result<CmdResult, CliError> {
 
 /// `cmd_restart`(`commands.py:344`)。
 pub fn cmd_restart(args: &RestartArgs) -> Result<CmdResult, CliError> {
-    Ok(CmdResult::from_json(
-        lifecycle_port::restart(
-            &args.workspace,
-            args.allow_fresh,
-            args.team.as_deref(),
-            args.session_converge_deadline_ms,
-        )?,
-        args.json,
-    ))
+    let mut value = lifecycle_port::restart(
+        &args.workspace,
+        args.allow_fresh,
+        args.team.as_deref(),
+        args.session_converge_deadline_ms,
+    )?;
+    if !args.detail {
+        lifecycle_port::compact_restart_value(&mut value);
+    }
+    Ok(CmdResult::from_json(value, args.json))
 }
 
 /// `cmd_start_agent`(`commands.py:348`)。

package/crates/team-agent/src/cli/emit.rs

@@ -374,7 +374,7 @@ fn command_help(command: Option<&str>) -> String {
     match command {
         None => default_help(),
         Some("init") => compat_hidden_help("init", "usage: team-agent init [--workspace WORKSPACE] [--force] [--json]"),
-        Some("quick-start") => "usage: team-agent quick-start [TEAMDIR] [--workspace WORKSPACE] [--name NAME] [--team-id TEAM|--team TEAM] [--yes] [--no-display] [--backend tmux|conpty] [--json]\n\ndefaults: display_backend=adaptive; set display_backend: none in TEAM.md or pass --no-display to use one worker window per agent.\n\n--backend selects the worker transport (Phase 1d Batch 2): tmux (default on POSIX; unchanged behavior), conpty (Windows-native ConPTY worker transport; requires the shim binary and Windows host).\n\nAfter a successful start, use the returned `send_commands` (or choose an agent explicitly) with `team-agent send AGENT MESSAGE`.".to_string(),
+        Some("quick-start") => "usage: team-agent quick-start [TEAMDIR] [--workspace WORKSPACE] [--name NAME] [--team-id TEAM|--team TEAM] [--yes] [--no-display] [--backend tmux|conpty] [--json] [--detail]\n\ndefaults: display_backend=adaptive; set display_backend: none in TEAM.md or pass --no-display to use one worker window per agent.\n\n--backend selects the worker transport (Phase 1d Batch 2): tmux (default on POSIX; unchanged behavior), conpty (Windows-native ConPTY worker transport; requires the shim binary and Windows host).\n\n--detail includes internal receiver/topology diagnostics in JSON output.\n\nAfter a successful start, use the returned `send_commands` (or choose an agent explicitly) with `team-agent send AGENT MESSAGE`.".to_string(),
         Some("start") => compat_hidden_help("start", "usage: team-agent start [TEAMDIR] [--yes] [--fresh] [--json]"),
         Some("compile") => "usage: team-agent compile --team TEAM [--out FILE] [--json]".to_string(),
         Some("send") => concat!(
@@ -391,7 +391,7 @@ fn command_help(command: Option<&str>) -> String {
         Some("models") => "usage: team-agent models --provider pi [--search TEXT] [--json]\n\nPrints models.v1 exact role_model entries; each entry includes current=true|false. Catalog readiness is reported as auth=ok|not_ready with auth_basis=catalog_visibility.".to_string(),
         Some("stop") => compat_hidden_help("stop", "usage: team-agent stop [--workspace WORKSPACE] [--team TEAM] [--keep-logs] [--json]"),
         Some("shutdown") => "usage: team-agent shutdown [--workspace WORKSPACE] [--team TEAM] [--keep-logs] [--json]".to_string(),
-        Some("restart") => "usage: team-agent restart [WORKSPACE] [--team TEAM] [--allow-fresh] [--session-converge-deadline SECONDS] [--json]".to_string(),
+        Some("restart") => "usage: team-agent restart [WORKSPACE] [--team TEAM] [--allow-fresh] [--session-converge-deadline SECONDS] [--json] [--detail]".to_string(),
         Some("restart-agent") => compat_hidden_help("restart-agent", "usage: team-agent restart-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--discard-session] [--no-display] [--json]"),
         Some("reset-agent") => "usage: team-agent reset-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--discard-session] [--no-display] [--json]".to_string(),
         Some("start-agent") => "usage: team-agent start-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--force] [--allow-fresh] [--no-display] [--json]\n\nAfter a successful start, use the returned `send_commands` with `team-agent send AGENT MESSAGE`.".to_string(),
@@ -405,7 +405,7 @@ fn command_help(command: Option<&str>) -> String {
         Some("stuck-cancel") => "usage: team-agent stuck-cancel AGENT [--workspace WORKSPACE] [--alert-type stuck|idle_fallback|cross_worker_deadlock|all] [--json]".to_string(),
         Some("acknowledge-idle") => "usage: team-agent acknowledge-idle [--workspace WORKSPACE] [--team TEAM] [--json]".to_string(),
         Some("takeover") => "usage: team-agent takeover [--workspace WORKSPACE] [--team TEAM] [--confirm] [--json]".to_string(),
-        Some("claim-leader") => "usage: team-agent claim-leader [--workspace WORKSPACE] [--team TEAM] [--confirm] [--json]".to_string(),
+        Some("claim-leader") => "usage: team-agent claim-leader [--workspace WORKSPACE] [--team TEAM] [--confirm] [--json] [--detail]".to_string(),
         Some("attach-leader") => "usage: team-agent attach-leader [--workspace WORKSPACE] [--team TEAM] [--pane PANE] [--provider PROVIDER] [--confirm] [--json]".to_string(),
         Some("attach-app-server-leader") => "usage: team-agent attach-app-server-leader [--workspace WORKSPACE] [--team TEAM] --socket unix:///path.sock --thread-id THREAD_ID [--json]".to_string(),
         Some("identity") => "usage: team-agent identity [--workspace WORKSPACE] [--team TEAM] [--json]".to_string(),
@@ -1063,6 +1063,7 @@ fn quick_start_args(args: &[String], cwd: &Path) -> Result<QuickStartArgs, CliEr
         yes: parsed.yes,
         no_display: parsed.no_display,
         json: parsed.json,
+        detail: parsed.detail,
         backend: parsed.backend,
     })
 }
@@ -1404,6 +1405,7 @@ fn claim_leader_args(args: &[String], cwd: &Path) -> ClaimLeaderArgs {
         team: parsed.team,
         confirm: parsed.confirm,
         json: parsed.json,
+        detail: parsed.detail,
     }
 }
 
@@ -1477,6 +1479,7 @@ fn restart_args(args: &[String], cwd: &Path) -> Result<RestartArgs, CliError> {
         allow_fresh: parsed.allow_fresh,
         session_converge_deadline_ms: parsed.session_converge_deadline_ms,
         json: parsed.json,
+        detail: parsed.detail,
     })
 }
 

package/crates/team-agent/src/cli/mod.rs

@@ -3233,6 +3233,33 @@ pub mod lifecycle_port {
         );
     }
 
+    const COMPACT_READINESS_KEYS: [&str; 6] = [
+        "all_workers_spawned",
+        "state",
+        "ready",
+        "reason",
+        "next_action",
+        "unhealthy_agents",
+    ];
+
+    fn compact_readiness_object(value: Option<&mut Value>) {
+        let Some(object) = value.and_then(Value::as_object_mut) else {
+            return;
+        };
+        object.retain(|key, _| COMPACT_READINESS_KEYS.contains(&key.as_str()));
+    }
+
+    pub(crate) fn compact_quick_start_value(value: &mut Value) {
+        if let Some(object) = value.as_object_mut() {
+            // Default contract: outcome, error/next action, attach/send, and a
+            // short readiness verdict. Diagnostic aliases stay behind --detail.
+            object.remove("agent_ids");
+            object.remove("dry_run");
+            compact_readiness_object(object.get_mut("readiness"));
+            compact_readiness_object(object.get_mut("worker_readiness"));
+        }
+    }
+
     fn quick_start_value(report: crate::lifecycle::QuickStartReport) -> Value {
         match report {
             crate::lifecycle::QuickStartReport::Ready {
@@ -3265,6 +3292,7 @@ pub mod lifecycle_port {
                         ),
                         false,
                         json!({
+                            "reason": "worker_unhealthy",
                             "all_spawned": all_spawned,
                             "all_workers_spawned": all_workers_spawned,
                             "all_attached_receiver": all_attached_receiver,
@@ -3383,6 +3411,8 @@ pub mod lifecycle_port {
                 attach_commands,
             } => json!({
                 "ok": false,
+                "status": "existing_runtime",
+                "reason": "team already has runtime state; use restart",
                 "summary": "existing runtime",
                 "team": team,
                 "session_name": session_name.map(|s| s.as_str().to_string()),
@@ -3398,6 +3428,8 @@ pub mod lifecycle_port {
                 attach_commands,
             } => json!({
                 "ok": false,
+                "status": "preflight_blocked",
+                "reason": "quick-start preflight blocked",
                 "summary": summary,
                 "blockers": blockers,
                 "next_actions": next_actions,
@@ -3411,6 +3443,89 @@ pub mod lifecycle_port {
     mod quick_start_value_tests {
         use super::*;
 
+        #[test]
+        fn quick_start_default_receipt_is_compact_but_detail_preserves_readiness() {
+            let readiness = json!({
+                "all_spawned": true,
+                "all_workers_spawned": true,
+                "all_attached_receiver": false,
+                "attached_receiver": false,
+                "leader_receiver_attached": false,
+                "all_resumable_have_session": true,
+                "all_resumable_agents_have_sessions": true,
+                "ready": false,
+                "state": "leader_receiver_unbound",
+                "session_capture_complete": true,
+                "session_capture_incomplete": false,
+                "incomplete_session_capture_agents": [],
+                "pending_session_agent_ids": [],
+                "reason": "launched team has no attached leader receiver",
+                "next_action": "claim-leader"
+            });
+            let detail = json!({
+                "ok": false,
+                "status": "leader_receiver_unbound",
+                "reason": "launched team has no attached leader receiver",
+                "ready": false,
+                "session_name": "team-fresh",
+                "next_actions": ["claim-leader"],
+                "attach_commands": ["tmux attach"],
+                "send_commands": ["team-agent send worker hi"],
+                "agent_ids": ["worker"],
+                "readiness": readiness.clone(),
+                "worker_readiness": readiness,
+                "dry_run": false
+            });
+            let mut default = detail.clone();
+            compact_quick_start_value(&mut default);
+            assert_eq!(default["status"], json!("leader_receiver_unbound"));
+            assert_eq!(
+                default["reason"],
+                json!("launched team has no attached leader receiver")
+            );
+            assert_eq!(default["next_actions"], json!(["claim-leader"]));
+            assert_eq!(default["attach_commands"], json!(["tmux attach"]));
+            assert_eq!(
+                default["send_commands"],
+                json!(["team-agent send worker hi"])
+            );
+            assert!(default.get("agent_ids").is_none());
+            assert!(default.get("dry_run").is_none());
+            assert_eq!(default["readiness"]["all_workers_spawned"], json!(true));
+            assert_eq!(default["readiness"]["state"], json!("leader_receiver_unbound"));
+            assert_eq!(default["readiness"]["next_action"], json!("claim-leader"));
+            assert!(default["readiness"].get("all_spawned").is_none());
+            assert!(default["readiness"].get("all_attached_receiver").is_none());
+            assert!(default["readiness"].get("leader_receiver_attached").is_none());
+            assert_eq!(
+                default["worker_readiness"]["all_workers_spawned"],
+                json!(true)
+            );
+            assert!(default["worker_readiness"].get("all_spawned").is_none());
+            assert!(detail["readiness"].get("all_spawned").is_some());
+            assert!(detail["worker_readiness"].get("leader_receiver_attached").is_some());
+        }
+
+        #[test]
+        fn restart_default_receipt_is_compact_but_detail_preserves_coordinator() {
+            let detail = json!({
+                "ok": false,
+                "status": "partial",
+                "reason": "restart_agent_failed",
+                "failed_agents": [{"agent_id": "worker", "error": "spawn failed"}],
+                "next_actions": ["restart-agent worker"],
+                "attach_commands": [],
+                "coordinator": {"status": "running", "transport": "default"}
+            });
+            let mut default = detail.clone();
+            compact_restart_value(&mut default);
+            assert_eq!(default["status"], json!("partial"));
+            assert_eq!(default["reason"], json!("restart_agent_failed"));
+            assert_eq!(default["next_actions"], json!(["restart-agent worker"]));
+            assert!(default.get("coordinator").is_none());
+            assert!(detail.get("coordinator").is_some());
+        }
+
         #[test]
         fn existing_runtime_json_includes_attach_commands() {
             let value = quick_start_value(crate::lifecycle::QuickStartReport::ExistingRuntime {
@@ -3500,6 +3615,15 @@ pub mod lifecycle_port {
         }
     }
 
+    pub(crate) fn compact_restart_value(value: &mut Value) {
+        if let Some(object) = value.as_object_mut() {
+            // Coordinator internals remain available only through --detail;
+            // outcome, failed-agent errors, attach commands and next actions
+            // stay in the default receipt.
+            object.remove("coordinator");
+        }
+    }
+
     fn restart_value(report: crate::lifecycle::RestartReport, team: Option<&str>) -> Value {
         match report {
             crate::lifecycle::RestartReport::Restarted {
@@ -3855,6 +3979,7 @@ pub mod lifecycle_port {
                     "status_class": "refused_resume_atomicity",
                     "allow_fresh": allow_fresh,
                     "error": error_str,
+                    "next_action": "pass --allow-fresh to start fresh, or restore the provider session backing files",
                     "unresumable": unresumable_detail,
                     "unresumable_ids": unresumable_ids,
                     "reminder": crate::cli::QUICK_START_REMINDER,
@@ -3894,6 +4019,7 @@ pub mod lifecycle_port {
                 "status": "refused_invalid_first_send_at",
                 "allow_fresh": allow_fresh,
                 "error": error,
+                "next_action": "pass --allow-fresh to discard the invalid session marker and start fresh",
                 "invalid": invalid.iter().map(|w| w.worker_id.as_str()).collect::<Vec<_>>(),
                 "reminder": crate::cli::QUICK_START_REMINDER,
             }),
@@ -5075,6 +5201,31 @@ pub mod leader_port {
         })
     }
 
+    pub(crate) fn compact_lease_value(value: &mut Value) {
+        let topology_status = value
+            .get("topology_convergence")
+            .and_then(|topology| topology.get("status"))
+            .cloned();
+        if value.get("reason").is_none() {
+            if let Some(status) = topology_status {
+                if status.as_str() != Some("converged") {
+                    value["reason"] = status;
+                }
+            }
+        }
+        if let Some(obj) = value.as_object_mut() {
+            for key in [
+                "owner_epoch",
+                "leader_receiver",
+                "team_owner",
+                "topology_convergence",
+                "leader_registry",
+            ] {
+                obj.remove(key);
+            }
+        }
+    }
+
     fn lease_value(result: crate::leader::LeaseResult) -> Value {
         let mut out = serde_json::Map::new();
         out.insert("ok".to_string(), json!(result.ok));

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

@@ -238,6 +238,34 @@ fn leader_port_takeover_confirm_without_pane_refuses_caller_pane_missing() {
         );
 }
 
+#[test]
+fn claim_leader_default_response_hides_internal_binding_details() {
+    let mut value = serde_json::json!({
+        "ok": true,
+        "status": "already_bound",
+        "owner_epoch": 3,
+        "bound_pane_id": "%77",
+        "leader_receiver": {"pane_id": "%77"},
+        "team_owner": {"pane_id": "%77"},
+        "topology_convergence": {"status": "not_converged_old_endpoint_live"},
+        "leader_registry": {"status": "registered"}
+    });
+    super::leader_port::compact_lease_value(&mut value);
+    assert_eq!(value["ok"], json!(true));
+    assert_eq!(value["status"], json!("already_bound"));
+    assert_eq!(value["bound_pane_id"], json!("%77"));
+    assert_eq!(value["reason"], json!("not_converged_old_endpoint_live"));
+    for field in [
+        "owner_epoch",
+        "leader_receiver",
+        "team_owner",
+        "topology_convergence",
+        "leader_registry",
+    ] {
+        assert!(value.get(field).is_none(), "default claim response leaked {field}");
+    }
+}
+
 // RED — claim_leader(confirm=false) with no $TMUX_PANE: runtime.claim_leader is
 // ALSO Family A (runtime.py:791) -> the bind gate fires FIRST, so the no-pane
 // refusal is caller_pane_missing (NOT the leader-lane "not_in_tmux_pane").

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

@@ -225,6 +225,7 @@ fn cli_quick_start_invokes_real_lifecycle_compiles_spec() {
         no_display: false,
         backend: None,
         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.
@@ -260,6 +261,7 @@ fn cli_quick_start_invalid_spec_surfaces_real_compile_error() {
         no_display: false,
         backend: None,
         json: true,
+        detail: false,
     };
     let text = outcome_text(cmd_quick_start(&args));
     assert!(
@@ -281,6 +283,7 @@ fn cli_restart_missing_spec_surfaces_real_teamselect() {
         allow_fresh: false,
         session_converge_deadline_ms: None,
         json: true,
+        detail: false,
     };
     let text = outcome_text(cmd_restart(&args));
     // RED-2-STILL: entry gate now resolves via canonical_run_workspace; for a no-spec workspace

package/crates/team-agent/src/cli/types.rs

@@ -297,6 +297,8 @@ pub struct QuickStartArgs {
     pub yes: bool,
     pub no_display: bool,
     pub json: bool,
+    /// Include internal receiver/topology diagnostics in the response.
+    pub detail: bool,
     /// 0.5.x Phase 1d Batch 2: explicit backend override
     /// (`--backend <tmux|conpty>`). `None` = default (factory 5-layer
     /// resolution; almost always `tmux` on a cold quick-start).
@@ -433,6 +435,8 @@ pub struct ClaimLeaderArgs {
     pub team: Option<String>,
     pub confirm: bool,
     pub json: bool,
+    /// Include internal receiver/topology diagnostics in the response.
+    pub detail: bool,
 }
 
 /// `attach-leader` public CLI args. `cmd_attach_leader` consumes the typed pane/provider
@@ -482,6 +486,8 @@ pub struct RestartArgs {
     pub allow_fresh: bool,
     pub session_converge_deadline_ms: Option<u64>,
     pub json: bool,
+    /// Include internal receiver/topology diagnostics in the response.
+    pub detail: bool,
 }
 
 /// `start-agent`(`parser.py:369`)。

package/crates/team-agent/src/compiler.rs

@@ -30,7 +30,8 @@ use std::path::Path;
 use crate::communication_mode::CommunicationMode;
 use crate::model::enums::{Provider, ProviderEffort};
 use crate::model::yaml::Value;
-use crate::model::{paths, spec, yaml, ModelError};
+use crate::model::{paths, permissions, spec, yaml, ModelError};
+use crate::provider::adapters::pi::first_unsupported_pi_tool_category;
 use crate::provider::wire::{
     builtin_provider_model as wire_builtin_provider_model, is_claude_family,
     parse_canonical_provider, provider_model_keys,
@@ -764,6 +765,18 @@ fn validate_pi_role_fields(meta: &Value, path: &Path, provider: &str) -> Result<
             path.display()
         )));
     }
+    let expanded = permissions::expand_tool_strings(tools.iter().map(String::as_str));
+    if let Some(category) = first_unsupported_pi_tool_category(
+        expanded
+            .iter()
+            .filter(|category| permissions::is_canonical_tool(category))
+            .map(String::as_str),
+    ) {
+        return Err(ModelError::Validation(format!(
+            "{}: Pi does not support Team Agent tool category {category:?}; remove it from the role's tools",
+            path.display()
+        )));
+    }
     Ok(())
 }
 

package/crates/team-agent/src/leader/lease.rs

@@ -288,6 +288,23 @@ struct AttachLeaderTarget {
 
 fn attach_leader_targets(workspace: &Path, state: &Value) -> Vec<AttachLeaderTarget> {
     let mut targets = Vec::new();
+    // The caller's verified tmux server is authoritative for discovering its
+    // leader pane. Keep state-recorded worker endpoints as additional targets,
+    // but do not let a cross-socket pane-id collision hide the caller pane.
+    if let Some(endpoint) = crate::tmux_backend::socket_name_from_tmux_env() {
+        let backend = tmux_backend_for_endpoint(&endpoint);
+        let resolved_endpoint = backend.tmux_endpoint();
+        targets.extend(
+            backend
+                .list_targets()
+                .unwrap_or_default()
+                .into_iter()
+                .map(|info| AttachLeaderTarget {
+                    info,
+                    endpoint: resolved_endpoint.clone(),
+                }),
+        );
+    }
     for endpoint in state_recorded_tmux_endpoints(state) {
         let backend = tmux_backend_for_endpoint(&endpoint);
         let resolved_endpoint = backend.tmux_endpoint();
@@ -554,7 +571,18 @@ pub fn claim_leader(
                     "explicit cross-workspace claim requires an absolute tmux endpoint".to_string(),
                 ));
             }
-            let nonce = next_pane_binding_nonce(workspace, endpoint, &candidate.info.pane_id);
+            // A live pane nonce identifies the pane instance, not this team's
+            // claim. Preserve it so another child team remains authorized.
+            let nonce = pane_binding_nonce_for_claim(
+                workspace,
+                endpoint,
+                &candidate.info.pane_id,
+                candidate
+                    .info
+                    .leader_env
+                    .get(crate::tmux_backend::PANE_BINDING_NONCE_METADATA_KEY)
+                    .map(String::as_str),
+            );
             target.scope_authority = Some("explicit_claim".to_string());
             target.authorized_team_workspace = Some(canonical_workspace(workspace));
             target.binding_nonce = Some(nonce);
@@ -600,7 +628,7 @@ pub fn claim_leader(
         confirm,
         &event_log,
         &liveness,
-        caller_target.as_ref(),
+        caller_target.as_mut(),
         caller_pane_info,
         scoped_team.map(|_| team_id.as_str()),
     )?;
@@ -692,7 +720,7 @@ fn claim_lease_no_incident_with_target(
     confirm: bool,
     event_log: &crate::event_log::EventLog,
     liveness: &dyn crate::state::owner_gate::PaneLivenessProbe,
-    caller_target: Option<&LeaderClaimTarget>,
+    mut caller_target: Option<&mut LeaderClaimTarget>,
     caller_pane_info: Option<&PaneInfo>,
     scoped_team: Option<&str>,
 ) -> Result<LeaseResult, LeaderError> {
@@ -734,9 +762,13 @@ fn claim_lease_no_incident_with_target(
     let non_empty_caller_pane = NonEmptyPaneId::try_from_pane(caller_pane)?;
     let bound_endpoint_matches_caller = bound_endpoint_matches_current_process(state);
     if bound_pane_id.as_deref() == Some(caller_pane.as_str()) && bound_endpoint_matches_caller {
-        write_claim_target_pane_nonce(caller_target)?;
+        if let Some(target) = caller_target.as_deref_mut() {
+            write_claim_target_pane_nonce(target)?;
+        }
         let current_endpoint = crate::tmux_backend::socket_name_from_tmux_env();
-        let observed_endpoint = caller_target.and_then(|target| target.endpoint.as_deref());
+        let observed_endpoint = caller_target
+            .as_deref()
+            .and_then(|target| target.endpoint.as_deref());
         let convergence_candidate = observed_endpoint.or(current_endpoint.as_deref());
         let candidate_source = if observed_endpoint.is_some() {
             Some("observed_target_endpoint")
@@ -758,7 +790,7 @@ fn claim_lease_no_incident_with_target(
                 pane_info,
                 observed_endpoint.or(current_endpoint.as_deref()),
                 scoped_team.or(team),
-                caller_target,
+                caller_target.as_deref(),
             )
         });
         if converged || observation_refreshed {
@@ -924,23 +956,33 @@ fn claim_lease_no_incident_with_target(
     } else {
         LeaseReason::VacantAcquired
     };
-    write_claim_target_pane_nonce(caller_target)?;
+    if let Some(target) = caller_target.as_deref_mut() {
+        write_claim_target_pane_nonce(target)?;
+    }
     let mut identity = leader_identity_context(workspace, Some(team_id.as_str()), Some(state))?;
-    if let Some(uuid) = caller_target.and_then(|target| target.leader_session_uuid.as_ref()) {
+    if let Some(uuid) = caller_target
+        .as_deref()
+        .and_then(|target| target.leader_session_uuid.as_ref()) {
         identity.leader_session_uuid = uuid.clone();
     }
     let next_epoch = OwnerEpoch(pre_epoch.0.saturating_add(1));
-    let provider = caller_target.map_or_else(|| prior_provider(state), |target| target.provider);
-    let observed_endpoint = caller_target.and_then(|target| target.endpoint.clone());
+    let provider = caller_target
+        .as_deref()
+        .map_or_else(|| prior_provider(state), |target| target.provider);
+    let observed_endpoint = caller_target
+        .as_deref()
+        .and_then(|target| target.endpoint.clone());
     let mut receiver = make_receiver(
         provider,
         &non_empty_caller_pane,
         &identity.leader_session_uuid,
         next_epoch,
         Discovery::ClaimLeader,
-        caller_target.and_then(|target| target.pane_info.clone()),
+        caller_target
+            .as_deref()
+            .and_then(|target| target.pane_info.clone()),
     );
-    if let Some(target) = caller_target {
+    if let Some(target) = caller_target.as_deref() {
         receiver.scope_authority.clone_from(&target.scope_authority);
         receiver
             .authorized_team_workspace
@@ -1540,10 +1582,10 @@ fn workspace_claim_target_from_pane_info(
     claim_target_from_pane_info(target)
 }
 
-fn write_claim_target_pane_nonce(target: Option<&LeaderClaimTarget>) -> Result<(), LeaderError> {
-    let Some(target) = target.filter(|target| target.scope_authority.is_some()) else {
+fn write_claim_target_pane_nonce(target: &mut LeaderClaimTarget) -> Result<(), LeaderError> {
+    if target.scope_authority.is_none() {
         return Ok(());
-    };
+    }
     let endpoint = target.endpoint.as_deref().ok_or_else(|| {
         LeaderError::Validation("explicit claim is missing its tmux endpoint".to_string())
     })?;
@@ -1557,13 +1599,30 @@ fn write_claim_target_pane_nonce(target: Option<&LeaderClaimTarget>) -> Result<(
     let nonce = target.binding_nonce.as_deref().ok_or_else(|| {
         LeaderError::Validation("explicit claim is missing its pane binding nonce".to_string())
     })?;
-    tmux_backend_for_endpoint(endpoint)
-        .set_pane_binding_nonce(pane, nonce)
-        .map_err(|error| {
-            LeaderError::Validation(format!(
-                "failed to bind the explicit leader pane instance: {error}"
-            ))
+    let live_nonce = target
+        .pane_info
+        .as_ref()
+        .and_then(|info| {
+            info.leader_env
+                .get(crate::tmux_backend::PANE_BINDING_NONCE_METADATA_KEY)
+                .map(String::as_str)
         })
+        .filter(|nonce| !nonce.is_empty());
+    // The pane option is the pane-instance identity shared by all authorized
+    // teams. Rewriting an observed value would revoke another team's grant.
+    let effective_nonce = if let Some(live_nonce) = live_nonce {
+        live_nonce.to_string()
+    } else {
+        tmux_backend_for_endpoint(endpoint)
+            .set_pane_binding_nonce_if_unset(pane, nonce)
+            .map_err(|error| {
+                LeaderError::Validation(format!(
+                    "failed to bind the explicit leader pane instance: {error}"
+                ))
+            })?
+    };
+    target.binding_nonce = Some(effective_nonce);
+    Ok(())
 }
 
 fn canonical_workspace(workspace: &Path) -> PathBuf {
@@ -1591,6 +1650,18 @@ fn next_pane_binding_nonce(workspace: &Path, endpoint: &str, pane: &PaneId) -> S
         .collect()
 }
 
+fn pane_binding_nonce_for_claim(
+    workspace: &Path,
+    endpoint: &str,
+    pane: &PaneId,
+    live_nonce: Option<&str>,
+) -> String {
+    live_nonce
+        .filter(|nonce| !nonce.is_empty())
+        .map(str::to_string)
+        .unwrap_or_else(|| next_pane_binding_nonce(workspace, endpoint, pane))
+}
+
 fn target_leader_session_uuid(target: &PaneInfo) -> Option<crate::model::ids::LeaderSessionUuid> {
     target
         .leader_env
@@ -2568,6 +2639,20 @@ mod tests {
         assert_ne!(first, second);
     }
 
+    #[test]
+    fn explicit_claim_generates_nonce_only_when_live_nonce_is_missing() {
+        let workspace = Path::new("/tmp/workspace-a");
+        let endpoint = "/tmp/team-agent-live.sock";
+        let pane = PaneId::new("%7");
+        let generated = pane_binding_nonce_for_claim(workspace, endpoint, &pane, None);
+        assert_eq!(generated.len(), 32);
+        assert!(generated.chars().all(|ch| ch.is_ascii_hexdigit()));
+        assert_eq!(
+            pane_binding_nonce_for_claim(workspace, endpoint, &pane, Some("live-nonce")),
+            "live-nonce"
+        );
+    }
+
     #[test]
     fn claim_authority_preserves_recorded_absolute_observation() {
         let workspace = Path::new("/tmp/workspace-a");