@team-agent/installer 0.5.74 → 0.5.77

package/crates/team-agent/src/lifecycle/tests/worker_spawn_env_red.rs

@@ -54,14 +54,14 @@ fn worker_spawn_inherits_parent_process_env_for_proxy_and_ca() {
         &launch_transport,
     )
     .expect("launch fixture should spawn worker");
-    let launch_command_line = launch_transport.single_spawn_command_line();
+    let launch_spawn = launch_transport.single_spawn();
 
     let restart_team = compiled_team_dir("restart", &[("worker_a", "Restart Worker")]);
     seed_restart_state(&restart_team, "worker_a");
     let restart_transport = RecordingTransport::new().with_session_present(false);
     restart_with_transport(&restart_team, true, None, &restart_transport)
         .expect("restart fixture should spawn worker");
-    let restart_command_line = restart_transport.single_spawn_command_line();
+    let restart_spawn = restart_transport.single_spawn();
 
     let add_team = compiled_team_dir("add-agent", &[("worker_a", "Existing Worker")]);
     seed_running_add_agent_state(&add_team, "worker_a");
@@ -77,17 +77,15 @@ fn worker_spawn_inherits_parent_process_env_for_proxy_and_ca() {
         &add_transport,
     )
     .expect("add-agent fixture should spawn worker");
-    let add_command_line = add_transport.single_spawn_command_line();
+    let add_spawn = add_transport.single_spawn();
 
     let failures = [
-        ("quick-start launch", launch_command_line, "worker_a"),
-        ("restart", restart_command_line, "worker_a"),
-        ("add-agent", add_command_line, "worker_b"),
+        ("quick-start launch", launch_spawn, "worker_a"),
+        ("restart", restart_spawn, "worker_a"),
+        ("add-agent", add_spawn, "worker_b"),
     ]
     .into_iter()
-    .flat_map(|(surface, command_line, agent_id)| {
-        spawn_env_contract_failures(surface, &command_line, agent_id)
-    })
+    .flat_map(|(surface, spawn, agent_id)| spawn_env_contract_failures(surface, &spawn, agent_id))
     .collect::<Vec<_>>();
 
     assert!(
@@ -97,6 +95,61 @@ fn worker_spawn_inherits_parent_process_env_for_proxy_and_ca() {
     );
 }
 
+#[test]
+fn tmux_control_filter_uses_env_keys_not_substring_in_inherited_values() {
+    let mut env = BTreeMap::from([
+        ("TA_SPAWN_ENV_CANARY".to_string(), "FOO".to_string()),
+        (
+            "HTTP_PROXY".to_string(),
+            "http://canary-proxy:1".to_string(),
+        ),
+        (
+            "NODE_EXTRA_CA_CERTS".to_string(),
+            "/canary/ca.pem".to_string(),
+        ),
+        ("TEAM_AGENT_WORKSPACE".to_string(), "/ws".to_string()),
+        (
+            "TEAM_AGENT_OWNER_TEAM_ID".to_string(),
+            "teamdir".to_string(),
+        ),
+        ("TEAM_AGENT_AGENT_ID".to_string(), "worker_a".to_string()),
+        (
+            "HARNESS_PROBE".to_string(),
+            "printf 'LS_USR_BIN_TMUX=%s\\n'\n".to_string(),
+        ),
+    ]);
+    let spawn = RecordedSpawn {
+        argv: vec!["codex".to_string()],
+        env: env.clone(),
+        env_unset: Vec::new(),
+        session: SessionName::new("s"),
+        window: WindowName::new("w"),
+        pane_id: PaneId::new("%1"),
+    };
+    assert!(
+        spawn_env_contract_failures("harness-value", &spawn, "worker_a").is_empty(),
+        "inherited values may contain the letters TMUX= without leaking TMUX/TMUX_PANE keys"
+    );
+
+    env.insert(
+        "TMUX".to_string(),
+        "/tmp/tmux-canary/default,1".to_string(),
+    );
+    let leaked = RecordedSpawn {
+        env,
+        ..spawn
+    };
+    let failures = spawn_env_contract_failures("key-leak", &leaked, "worker_a");
+    assert!(
+        failures.iter().any(|row| row.contains("present_keys=") && row.contains("TMUX")),
+        "actual TMUX key must still fail closed; failures={failures:?}"
+    );
+    assert!(
+        failures.iter().all(|row| !row.contains("command_line=")),
+        "failures must not dump command_line; failures={failures:?}"
+    );
+}
+
 #[test]
 #[serial(env)]
 fn worker_spawn_scrubs_cross_provider_process_identity_but_keeps_config_env() {
@@ -234,42 +287,67 @@ fn worker_spawn_stays_out_of_coordinator_tick_and_daemon_preserves_parent_env()
     );
 }
 
-fn spawn_env_contract_failures(surface: &str, command_line: &str, agent_id: &str) -> Vec<String> {
+fn spawn_env_has_tmux_control_assignment(spawn: &RecordedSpawn) -> bool {
+    spawn.env.contains_key("TMUX")
+        || spawn.env.contains_key("TMUX_PANE")
+        || spawn.argv.iter().any(|part| {
+            part.split_whitespace().any(|tok| {
+                tok == "TMUX" || tok.starts_with("TMUX=") || tok.starts_with("TMUX_PANE=")
+            })
+        })
+}
+
+fn spawn_env_contract_failures(
+    surface: &str,
+    spawn: &RecordedSpawn,
+    agent_id: &str,
+) -> Vec<String> {
     let mut failures = Vec::new();
-    for expected in [
-        "TA_SPAWN_ENV_CANARY=FOO",
-        "HTTP_PROXY=http://canary-proxy:1",
-        "NODE_EXTRA_CA_CERTS=/canary/ca.pem",
-        "TEAM_AGENT_WORKSPACE=",
-        "TEAM_AGENT_OWNER_TEAM_ID=teamdir",
+    for (key, expected) in [
+        ("TA_SPAWN_ENV_CANARY", Some("FOO")),
+        ("HTTP_PROXY", Some("http://canary-proxy:1")),
+        ("NODE_EXTRA_CA_CERTS", Some("/canary/ca.pem")),
+        ("TEAM_AGENT_OWNER_TEAM_ID", Some("teamdir")),
     ] {
-        if !command_line.contains(expected) {
-            failures.push(format!(
-                "{surface}: missing `{expected}`; worker spawn must inherit parent env and overlay Team Agent identity; command_line={command_line:?}"
-            ));
+        match (spawn.env.get(key).map(String::as_str), expected) {
+            (Some(actual), Some(wanted)) if actual == wanted => {}
+            (Some(_), Some(wanted)) => failures.push(format!(
+                "{surface}: `{key}` present but not `{wanted}`"
+            )),
+            _ => failures.push(format!(
+                "{surface}: missing `{key}` overlay/inherit"
+            )),
         }
     }
-    if !command_line.contains(&format!("TEAM_AGENT_AGENT_ID={agent_id}")) {
+    if spawn
+        .env
+        .get("TEAM_AGENT_WORKSPACE")
+        .is_none_or(|value| value.is_empty())
+    {
+        failures.push(format!("{surface}: missing `TEAM_AGENT_WORKSPACE` overlay"));
+    }
+    if spawn.env.get("TEAM_AGENT_AGENT_ID").map(String::as_str) != Some(agent_id) {
         failures.push(format!(
-            "{surface}: missing `TEAM_AGENT_AGENT_ID={agent_id}` overlay; command_line={command_line:?}"
+            "{surface}: missing `TEAM_AGENT_AGENT_ID={agent_id}` overlay"
         ));
     }
-    if command_line.contains("TMUX=") || command_line.contains("TMUX_PANE=") {
+    if spawn_env_has_tmux_control_assignment(spawn) {
+        let present: Vec<&str> = ["TMUX", "TMUX_PANE"]
+            .into_iter()
+            .filter(|key| spawn.env.contains_key(*key))
+            .collect();
         failures.push(format!(
-            "{surface}: worker spawn must filter tmux control env from inherited parent env; command_line={command_line:?}"
+            "{surface}: worker spawn must filter tmux control env from inherited parent env; present_keys={present:?}"
         ));
     }
-    if !command_line.split_whitespace().any(|part| part == "codex") {
+    if !spawn.argv.iter().any(|part| part == "codex") {
         failures.push(format!(
-            "{surface}: provider executable must remain the command name `codex`; command_line={command_line:?}"
+            "{surface}: provider executable must remain the command name `codex`"
         ));
     }
-    if command_line
-        .split_whitespace()
-        .any(|part| part.ends_with("/codex"))
-    {
+    if spawn.argv.iter().any(|part| part.ends_with("/codex")) {
         failures.push(format!(
-            "{surface}: provider executable must not be hard-coded as an absolute codex path; command_line={command_line:?}"
+            "{surface}: provider executable must not be hard-coded as an absolute codex path"
         ));
     }
     failures
@@ -580,6 +658,7 @@ impl RecordingTransport {
         self
     }
 
+    #[allow(dead_code)]
     fn single_spawn_command_line(&self) -> String {
         self.single_spawn().command_line()
     }

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

@@ -797,6 +797,8 @@ pub enum RestartReport {
         coordinator: CoordinatorStartSummary,
         next_actions: Vec<String>,
         attach_commands: Vec<String>,
+        /// Debt returned by this restart's best-effort auto-attach, if any.
+        attach_window_failures: Option<serde_json::Value>,
     },
     /// At least one worker failed during live spawn, but other workers were isolated
     /// and restarted. The CLI reports `status=partial` and exits non-zero.
@@ -811,6 +813,8 @@ pub enum RestartReport {
         coordinator: CoordinatorStartSummary,
         next_actions: Vec<String>,
         attach_commands: Vec<String>,
+        /// Debt returned by this restart's best-effort auto-attach, if any.
+        attach_window_failures: Option<serde_json::Value>,
     },
     /// All workers failed during live spawn. No worker is reported as restarted.
     Failed {

package/crates/team-agent/src/messaging/delivery.rs

@@ -31,9 +31,9 @@ use crate::provider::wire::{
     is_claude_family, parse_canonical_provider, parse_provider, provider_wire,
 };
 use crate::transport::{
-    submit_verification_wire, turn_verification_wire, CaptureRange, InjectPayload, InjectReport,
-    InjectVerification, Key, PaneId, PaneInfo, SessionName, SubmitObserver, SubmitVerification,
-    Target, Transport, WindowName,
+    submit_verification_wire, turn_verification_wire, CaptureRange, CaptureSampleOutcome,
+    InjectPayload, InjectReport, InjectVerification, InputSurfaceProbe, Key, PaneId, PaneInfo,
+    QueryOutcome, SessionName, SubmitObserver, SubmitVerification, Target, Transport, WindowName,
 };
 
 use super::helpers::{message_exists, MessageStatusShadow};
@@ -749,16 +749,20 @@ pub fn deliver_pending_message(
         // are preserved byte-for-byte for grep compatibility; new keys are
         // ADDITIONAL.
         let submit_attempts_detail = render_submit_diagnostics(&inject_report);
-        event_log.write(
-            "send.unverified",
-            serde_json::json!({
-                "message_id": message_id,
-                "recipient": message.recipient,
-                "reason": reason,
-                "attempts": inject_report.attempts,
-                "submit_attempts_detail": submit_attempts_detail,
-            }),
-        )?;
+        let mut unverified = serde_json::json!({
+            "message_id": message_id,
+            "recipient": message.recipient,
+            "reason": reason,
+            "attempts": inject_report.attempts,
+            "submit_attempts_detail": submit_attempts_detail,
+        });
+        merge_inject_readback_fields(
+            &mut unverified,
+            &inject_report,
+            Some(&target),
+            resolved.metadata.as_ref(),
+        );
+        event_log.write("send.unverified", unverified)?;
         if inject_report.attempts >= u32::from(SEND_RETRY_MAX_ATTEMPTS) {
             store.mark(message_id, "failed", Some("send_unverified_exhausted"))?;
             emit_send_failed_exhausted(
@@ -1070,7 +1074,7 @@ fn persist_submit_verification(workspace: &Path, message_id: &str, report: &Inje
     if std::fs::create_dir_all(&dir).is_err() {
         return;
     }
-    let body = serde_json::json!({
+    let mut body = serde_json::json!({
         "message_id": message_id,
         "submit_verification": format!("{:?}", report.submit_verification),
         "inject_verification": format!("{:?}", report.inject_verification),
@@ -1078,6 +1082,7 @@ fn persist_submit_verification(workspace: &Path, message_id: &str, report: &Inje
         "submit_verified": inject_submit_verified(report),
         "attempts": report.attempts,
     });
+    merge_inject_readback_fields(&mut body, report, None, None);
     let _ = std::fs::write(dir.join("submit-verification.json"), format!("{body}\n"));
 }
 
@@ -1914,6 +1919,116 @@ fn render_submit_diagnostics(report: &InjectReport) -> serde_json::Value {
     )
 }
 
+fn json_opt_bool(value: Option<bool>) -> serde_json::Value {
+    match value {
+        Some(flag) => serde_json::Value::Bool(flag),
+        None => serde_json::Value::Null,
+    }
+}
+
+fn inject_pane_id(target: &Target) -> Option<&str> {
+    match target {
+        Target::Pane(pane) => Some(pane.as_str()),
+        Target::SessionWindow { .. } => None,
+    }
+}
+
+fn merge_inject_readback_fields(
+    event: &mut serde_json::Value,
+    report: &InjectReport,
+    target: Option<&Target>,
+    metadata: Option<&TargetMetadata>,
+) {
+    if let Some(metadata) = metadata {
+        append_target_metadata(event, metadata);
+    }
+    let Some(obj) = event.as_object_mut() else {
+        return;
+    };
+    let inject_pane = target.and_then(inject_pane_id);
+    if let Some(pane) = inject_pane {
+        obj.insert(
+            "inject_target_pane_id".to_string(),
+            serde_json::json!(pane),
+        );
+    }
+    let resolved_pane = metadata.map(|meta| meta.target_pane_id.as_str());
+    obj.insert(
+        "target_pane_matched".to_string(),
+        json_opt_bool(match (inject_pane, resolved_pane) {
+            (Some(left), Some(right)) => Some(left == right),
+            _ => None,
+        }),
+    );
+    let inject_endpoint = metadata.and_then(|meta| meta.tmux_endpoint.as_deref());
+    // metadata.tmux_endpoint is the transport used to resolve; compare to
+    // itself is tautological. Equality vs inject target id is the pane check
+    // above. Socket equality is recorded when both sides exist on metadata.
+    obj.insert(
+        "resolved_tmux_endpoint_present".to_string(),
+        serde_json::Value::Bool(inject_endpoint.is_some()),
+    );
+    let diag = report.submit_diagnostics.as_ref();
+    obj.insert(
+        "token_seen_before_paste".to_string(),
+        json_opt_bool(diag.and_then(|d| d.token_seen_before_paste)),
+    );
+    obj.insert(
+        "token_seen_after_paste".to_string(),
+        json_opt_bool(diag.and_then(|d| d.token_seen_after_paste)),
+    );
+    obj.insert(
+        "token_seen_after_enter".to_string(),
+        json_opt_bool(diag.and_then(|d| d.token_seen_after_enter)),
+    );
+    obj.insert(
+        "capture_ok_count".to_string(),
+        serde_json::json!(diag.map(|d| d.capture_ok_count).unwrap_or(0)),
+    );
+    obj.insert(
+        "capture_err_count".to_string(),
+        serde_json::json!(diag.map(|d| d.capture_err_count).unwrap_or(0)),
+    );
+    obj.insert(
+        "capture_sample_count".to_string(),
+        serde_json::json!(diag.map(|d| d.capture_sample_count).unwrap_or(0)),
+    );
+    obj.insert(
+        "last_capture_outcome".to_string(),
+        serde_json::json!(diag
+            .map(|d| d.last_capture_outcome.as_str())
+            .unwrap_or(CaptureSampleOutcome::NotAttempted.as_str())),
+    );
+    obj.insert(
+        "pane_command_basename".to_string(),
+        diag.and_then(|d| d.pane_command_basename.as_deref())
+            .map(|name| serde_json::json!(name))
+            .unwrap_or(serde_json::Value::Null),
+    );
+    obj.insert(
+        "pane_command_query".to_string(),
+        serde_json::json!(diag
+            .map(|d| d.pane_command_query.as_str())
+            .unwrap_or(QueryOutcome::Unavailable.as_str())),
+    );
+    obj.insert(
+        "input_surface".to_string(),
+        serde_json::json!(diag
+            .map(|d| d.input_surface.as_str())
+            .unwrap_or(InputSurfaceProbe::Unavailable.as_str())),
+    );
+    obj.insert(
+        "diag_target_pane_id".to_string(),
+        diag.and_then(|d| d.target_pane_id.as_deref())
+            .map(|pane| serde_json::json!(pane))
+            .unwrap_or(serde_json::Value::Null),
+    );
+    obj.insert(
+        "diag_target_pane_query_matched".to_string(),
+        json_opt_bool(diag.and_then(|d| d.target_pane_query_matched)),
+    );
+}
+
 #[allow(clippy::too_many_arguments)]
 fn emit_send_failed_exhausted(
     workspace: &Path,
@@ -1944,21 +2059,22 @@ fn emit_send_failed_exhausted(
         .and_then(|r| r.submit_diagnostics.as_ref())
         .and_then(|d| d.attempts_detail.last())
         .map(|a| a.pane_tail_excerpt.clone());
-    event_log.write(
-        "send.failed",
-        serde_json::json!({
-            "message_id": message_id,
-            "recipient": recipient,
-            "attempts": attempts,
-            "max_attempts": SEND_RETRY_MAX_ATTEMPTS,
-            "reason": failure_reason,
-            "verification": verification,
-            "submit_attempts_detail": submit_attempts_detail,
-            "total_elapsed_ms": total_elapsed_ms,
-            "last_matched_literal": last_matched_literal,
-            "last_pane_tail_excerpt": last_pane_tail_excerpt,
-        }),
-    )?;
+    let mut failed = serde_json::json!({
+        "message_id": message_id,
+        "recipient": recipient,
+        "attempts": attempts,
+        "max_attempts": SEND_RETRY_MAX_ATTEMPTS,
+        "reason": failure_reason,
+        "verification": verification,
+        "submit_attempts_detail": submit_attempts_detail,
+        "total_elapsed_ms": total_elapsed_ms,
+        "last_matched_literal": last_matched_literal,
+        "last_pane_tail_excerpt": last_pane_tail_excerpt,
+    });
+    if let Some(report) = inject_report {
+        merge_inject_readback_fields(&mut failed, report, None, None);
+    }
+    event_log.write("send.failed", failed)?;
     let content = format!(
         "send.failed\nerror: send to {recipient} failed with {failure_reason} after {attempts}/{SEND_RETRY_MAX_ATTEMPTS} attempts\naction: inspect the target pane and retry the send\nlog: .team/logs/events.jsonl"
     );
@@ -3266,4 +3382,59 @@ mod paste_floor_tests {
             Duration::ZERO
         );
     }
+
+    fn empty_report() -> InjectReport {
+        InjectReport {
+            stage_reached: crate::transport::InjectStage::Submit,
+            inject_verification: InjectVerification::CaptureMissingToken,
+            submit_verification: SubmitVerification::SubmitConsumptionUnverified,
+            turn_verification: crate::transport::TurnVerification::NotYetObserved,
+            attempts: 1,
+            submit_diagnostics: Some(crate::transport::SubmitDiagnostics {
+                last_capture_outcome: CaptureSampleOutcome::Failed,
+                capture_err_count: 1,
+                capture_sample_count: 1,
+                pane_command_basename: Some("grok".to_string()),
+                pane_command_query: QueryOutcome::Observed,
+                input_surface: InputSurfaceProbe::Input,
+                target_pane_id: Some("%9".to_string()),
+                target_pane_query_matched: Some(true),
+                token_seen_after_paste: None,
+                ..crate::transport::SubmitDiagnostics::default()
+            }),
+        }
+    }
+
+    #[test]
+    fn inject_readback_fields_are_safe_scalars_and_keep_attempts_array() {
+        let report = empty_report();
+        let mut event = serde_json::json!({
+            "message_id": "msg_x",
+            "submit_attempts_detail": [{"matched": false}],
+        });
+        merge_inject_readback_fields(
+            &mut event,
+            &report,
+            Some(&Target::Pane(PaneId::new("%9"))),
+            None,
+        );
+        assert_eq!(event["last_capture_outcome"], serde_json::json!("failed"));
+        assert_eq!(event["token_seen_after_paste"], serde_json::Value::Null);
+        assert_eq!(event["pane_command_basename"], serde_json::json!("grok"));
+        assert_eq!(event["input_surface"], serde_json::json!("input"));
+        assert_eq!(event["inject_target_pane_id"], serde_json::json!("%9"));
+        assert!(event["submit_attempts_detail"].is_array());
+        assert!(event.get("pane_tail_excerpt").is_none());
+        let dump = event.to_string();
+        assert!(
+            !dump.contains("--help") && !dump.contains("argv"),
+            "readback fields must not leak argv: {dump}"
+        );
+        assert_eq!(
+            report.inject_verification,
+            InjectVerification::CaptureMissingToken
+        );
+        assert!(!inject_submit_verified(&report));
+        assert!(!pane_readback_verified(&report));
+    }
 }

package/crates/team-agent/src/messaging/leader_channel.rs

@@ -7,6 +7,11 @@ use crate::codex_app_server::AppServerBinding;
 use crate::model::pane_authority_refusal::PaneWorkspaceMismatchFacts;
 use crate::transport::{PaneInfo, Transport};
 
+/// Scope authority written by a fresh quick-start caller binding. It is distinct
+/// from an operator-initiated explicit claim, but uses the same pane-instance
+/// nonce and exact workspace checks at delivery.
+pub(crate) const FRESH_CALLER_SCOPE_AUTHORITY: &str = "fresh_caller";
+
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum LiveLeaderChannel {
     DirectTmux(DirectTmuxLeaderChannel),
@@ -117,7 +122,7 @@ pub fn resolve_live_leader_channel(
     };
     if let Some(observed_pane_workspace) = observed.current_path.clone() {
         if !path_is_in_workspace(&observed_pane_workspace, workspace)
-            && !explicit_claim_authority_matches(workspace, receiver, &observed)
+            && !scoped_authority_matches(workspace, receiver, &observed)
         {
             return LeaderChannelResolution::Unbound(LeaderChannelUnbound::PaneWorkspaceMismatch(
                 PaneWorkspaceMismatchFacts {
@@ -138,12 +143,16 @@ pub fn resolve_live_leader_channel(
     }))
 }
 
-fn explicit_claim_authority_matches(
+fn scoped_authority_matches(
     workspace: &Path,
     receiver: &Value,
     observed: &PaneInfo,
 ) -> bool {
-    if string_field(receiver, "scope_authority") != Some("explicit_claim") {
+    let authority = string_field(receiver, "scope_authority");
+    if !matches!(
+        authority,
+        Some("explicit_claim") | Some(FRESH_CALLER_SCOPE_AUTHORITY)
+    ) {
         return false;
     }
     let Some(authorized_workspace) = string_field(receiver, "authorized_team_workspace") else {

package/crates/team-agent/src/messaging/watchers.rs

@@ -653,12 +653,30 @@ pub fn recover_watchers_for_incident(
 /// row for watcher-backed messages. A `submitted_pending_acceptance` row has
 /// already crossed the transport boundary and is claim-immutable. Any future
 /// retry belongs to a separate typed recovery arm, not attach/claim convergence.
+/// Compatibility helper retained for callers that only need the total.
+/// The typed recovery path below is the single writer; this wrapper performs
+/// no second requeue and only maps the first result to `total()`.
 pub(crate) fn requeue_blocked_leader_messages(
     store: &MessageStore,
     event_log: &EventLog,
     owner_team_id: &TeamKey,
     claimed_pane_id: &PaneId,
 ) -> Result<usize, MessagingError> {
+    requeue_blocked_leader_messages_with_counts(
+        store,
+        event_log,
+        owner_team_id,
+        claimed_pane_id,
+    )
+    .map(crate::message_store::BlockedLeaderRequeueCounts::total)
+}
+
+pub(crate) fn requeue_blocked_leader_messages_with_counts(
+    store: &MessageStore,
+    event_log: &EventLog,
+    owner_team_id: &TeamKey,
+    claimed_pane_id: &PaneId,
+) -> Result<crate::message_store::BlockedLeaderRequeueCounts, MessagingError> {
     // E6 (0.5.9 offline-mailbox §6.5): also requeue rows that a third-party
     // sender left in `queued_until_leader_attach` via the leader mailbox.
     // Same idempotent requeue funnel (row/message_id/leader_notification_log
@@ -690,7 +708,7 @@ pub(crate) fn requeue_blocked_leader_messages(
             }),
         )?;
     }
-    Ok(requeued)
+    Ok(counts)
 }
 
 /// `requeue_delivery_exhausted_watchers`: attach-leader 成功后把已经耗尽投递
@@ -702,12 +720,33 @@ pub(crate) fn requeue_blocked_leader_messages(
 /// `deliver_pending_messages` never re-picks — the new leader would never see the
 /// pending notification.
 pub fn requeue_delivery_exhausted_watchers(
-    _workspace: &Path,
+    workspace: &Path,
     store: &MessageStore,
     event_log: &EventLog,
     owner_team_id: &TeamKey,
     claimed_pane_id: &PaneId,
 ) -> Result<Vec<WatcherNotice>, MessagingError> {
+    requeue_delivery_exhausted_watchers_with_counts(
+        workspace,
+        store,
+        event_log,
+        owner_team_id,
+        claimed_pane_id,
+    )
+    .map(|(notices, _)| notices)
+}
+
+/// Attach-leader's typed recovery result. The counts come from the same
+/// owner-team scoped attach-recovery call (the watcher and message updates
+/// remain their existing transactions), so an attach caller can expose only
+/// this operation's debt rather than scanning arbitrary historical events.
+pub(crate) fn requeue_delivery_exhausted_watchers_with_counts(
+    _workspace: &Path,
+    store: &MessageStore,
+    event_log: &EventLog,
+    owner_team_id: &TeamKey,
+    claimed_pane_id: &PaneId,
+) -> Result<(Vec<WatcherNotice>, crate::message_store::BlockedLeaderRequeueCounts), MessagingError> {
     let conn = crate::db::schema::open_db(store.db_path())?;
     let mut stmt = conn.prepare(
         "select watcher_id, result_id, status from result_watchers
@@ -748,8 +787,13 @@ pub fn requeue_delivery_exhausted_watchers(
         )?;
     }
     drop(stmt);
-    let _ = requeue_blocked_leader_messages(store, event_log, owner_team_id, claimed_pane_id)?;
-    Ok(out)
+    let counts = requeue_blocked_leader_messages_with_counts(
+        store,
+        event_log,
+        owner_team_id,
+        claimed_pane_id,
+    )?;
+    Ok((out, counts))
 }
 
 /// `delivered_result_message` (`result_delivery.py:394`):内容级去重 —— 查某 result_id 是否已有

package/crates/team-agent/src/state/paths.rs

@@ -27,7 +27,7 @@
 use std::path::{Path, PathBuf};
 
 use crate::model::paths::{runtime_dir, runtime_spec_path};
-use crate::state::persist::load_runtime_state;
+use crate::state::persist::{load_runtime_state, load_runtime_state_without_migrations};
 use crate::state::projection::team_state_candidates;
 
 /// The identity of a team within a workspace. Carries the *workspace root*
@@ -193,10 +193,25 @@ impl CommandScope {
     /// On any I/O error the empty case is returned — destructive commands
     /// will run their own selector and surface the real error.
     pub fn resolve(workspace: &Path, requested_team: Option<&str>) -> Self {
+        Self::resolve_from_state(requested_team, load_runtime_state(workspace))
+    }
+
+    /// Ambiguity gate for read-only commands. Must not migrate or persist state.
+    pub fn resolve_readonly(workspace: &Path, requested_team: Option<&str>) -> Self {
+        Self::resolve_from_state(
+            requested_team,
+            load_runtime_state_without_migrations(workspace),
+        )
+    }
+
+    fn resolve_from_state(
+        requested_team: Option<&str>,
+        loaded: Result<serde_json::Value, crate::state::StateError>,
+    ) -> Self {
         if let Some(team) = requested_team.filter(|t| !t.is_empty()) {
             return Self::Resolved(team.to_string());
         }
-        let Ok(state) = load_runtime_state(workspace) else {
+        let Ok(state) = loaded else {
             return Self::EmptyWorkspace;
         };
         let alive = team_state_candidates(&state);