@team-agent/installer 0.5.75 → 0.5.78

package/crates/team-agent/src/mcp_server/wire.rs

@@ -185,7 +185,7 @@ fn run_stdio_loop<R: BufRead, W: Write>(
     let mut report = ServerRunReport::default();
     let marker = McpServerLifecycleMarker::from_env(workspace);
     marker.write_started();
-    let result = run_stdio_loop_inner(&tools, reader, &mut writer, &mut report);
+    let result = run_stdio_loop_inner(&tools, reader, &mut writer, &mut report, &marker);
     match &result {
         Ok(_) => marker.write_exit("stdin_eof", None),
         Err(error) => marker.write_exit("fatal_error", Some(&error.to_string())),
@@ -198,16 +198,20 @@ fn run_stdio_loop_inner<R: BufRead, W: Write>(
     reader: R,
     writer: &mut W,
     report: &mut ServerRunReport,
+    marker: &McpServerLifecycleMarker,
 ) -> Result<ServerRunReport, McpError> {
     for line in reader.lines() {
         let line = line?;
         report.requests_read = report.requests_read.saturating_add(1);
-        let frame = handle_stdin_line(tools, &line, report)?;
+        let (frame, tools_list_success) = handle_stdin_line(tools, &line, report)?;
         if let Some(value) = frame {
             let value = crate::redaction::redact_external_value(&value);
             serde_json::to_writer(&mut *writer, &value)?;
             writer.write_all(b"\n")?;
             writer.flush()?;
+            if tools_list_success {
+                marker.write_tools_list_response_written();
+            }
             report.responses_written = report.responses_written.saturating_add(1);
         }
     }
@@ -219,29 +223,34 @@ fn handle_stdin_line(
     tools: &TeamOrchestratorTools,
     line: &str,
     report: &mut ServerRunReport,
-) -> Result<Option<Value>, McpError> {
+) -> Result<(Option<Value>, bool), McpError> {
     let request: Value = match serde_json::from_str(line) {
         Ok(value) => value,
         Err(err) => {
             report.error_frames = report.error_frames.saturating_add(1);
-            return Ok(Some(error_response_value(
-                RpcId::Null,
-                -32700,
-                format!("parse error: {err}"),
-            )));
+            return Ok((
+                Some(error_response_value(
+                    RpcId::Null,
+                    -32700,
+                    format!("parse error: {err}"),
+                )),
+                false,
+            ));
         }
     };
     if request.get("jsonrpc").and_then(Value::as_str) == Some("2.0") {
+        let is_tools_list = request.get("method").and_then(Value::as_str) == Some("tools/list");
         match handle_mcp(tools, &request)? {
             Some(response) => {
+                let tools_list_success = is_tools_list && response.error.is_none();
                 if response.error.is_some() {
                     report.error_frames = report.error_frames.saturating_add(1);
                 }
-                Ok(Some(serde_json::to_value(response)?))
+                Ok((Some(serde_json::to_value(response)?), tools_list_success))
             }
             None => {
                 report.notifications_skipped = report.notifications_skipped.saturating_add(1);
-                Ok(None)
+                Ok((None, false))
             }
         }
     } else {
@@ -252,7 +261,7 @@ fn handle_stdin_line(
                 err.to_envelope()
             }
         };
-        Ok(Some(value))
+        Ok((Some(value), false))
     }
 }
 
@@ -301,6 +310,23 @@ impl McpServerLifecycleMarker {
         self.write("mcp.server_started", None, None);
     }
 
+    fn write_tools_list_response_written(&self) {
+        let _ = EventLog::new(&self.workspace).write(
+            "mcp.tools_list_response_written",
+            serde_json::json!({
+                "method": "tools/list",
+                "success": true,
+                "agent_id": self.agent_id.as_deref(),
+                "owner_team_id": self.owner_team_id.as_deref(),
+                "workspace": self.workspace.display().to_string(),
+                "pid": self.pid,
+                "ppid": self.ppid,
+                "spawn_epoch": null,
+                "spawn_epoch_source": "unavailable",
+            }),
+        );
+    }
+
     fn write_exit(&self, reason: &str, error: Option<&str>) {
         self.write("mcp.server_exit", Some(reason), error);
     }
@@ -798,6 +824,109 @@ mod e23_lifecycle_marker_tests {
         path
     }
 
+    #[test]
+    fn stdio_loop_logs_tools_list_after_flush_once_per_response() {
+        let ws = marker_ws("tools-list-success");
+        let input = std::io::Cursor::new(
+            br#"{"jsonrpc":"2.0","id":1,"method":"tools/list"}
+{"jsonrpc":"2.0","id":2,"method":"tools/list"}
+"#.to_vec(),
+        );
+        let mut output = Vec::new();
+
+        let report = run_stdio_loop(&ws, input, &mut output).unwrap();
+
+        assert_eq!(report.responses_written, 2);
+        assert_eq!(output.iter().filter(|byte| **byte == b'\n').count(), 2);
+        let events = EventLog::new(&ws).tail(0).unwrap();
+        let tool_events: Vec<_> = events
+            .iter()
+            .filter(|event| event["event"] == serde_json::json!("mcp.tools_list_response_written"))
+            .collect();
+        assert_eq!(tool_events.len(), 2, "one event per successful tools/list response");
+        for event in tool_events {
+            assert_eq!(event["method"], serde_json::json!("tools/list"));
+            assert_eq!(event["success"], serde_json::json!(true));
+            assert_eq!(event["workspace"], serde_json::json!(ws.display().to_string()));
+            assert_eq!(event["pid"], serde_json::json!(std::process::id()));
+            assert_eq!(event["spawn_epoch"], serde_json::Value::Null);
+        }
+        let _ = std::fs::remove_dir_all(&ws);
+    }
+
+    #[test]
+    fn stdio_loop_does_not_log_tools_list_when_write_fails() {
+        struct FailingWriter;
+        impl Write for FailingWriter {
+            fn write(&mut self, _buf: &[u8]) -> std::io::Result<usize> {
+                Err(std::io::Error::other("simulated stdout write failure"))
+            }
+
+            fn flush(&mut self) -> std::io::Result<()> {
+                Ok(())
+            }
+        }
+
+        let ws = marker_ws("tools-list-write-fail");
+        let input = std::io::Cursor::new(
+            br#"{"jsonrpc":"2.0","id":1,"method":"tools/list"}"#.to_vec(),
+        );
+        let error = run_stdio_loop(&ws, input, FailingWriter).expect_err("write must fail");
+        assert!(error.to_string().contains("simulated stdout write failure"));
+        let events = EventLog::new(&ws).tail(0).unwrap();
+        assert!(!events
+            .iter()
+            .any(|event| event["event"] == serde_json::json!("mcp.tools_list_response_written")));
+        let _ = std::fs::remove_dir_all(&ws);
+    }
+
+    #[test]
+    fn stdio_loop_does_not_log_tools_list_when_flush_fails() {
+        struct FlushFailWriter(Vec<u8>);
+        impl Write for FlushFailWriter {
+            fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
+                self.0.extend_from_slice(buf);
+                Ok(buf.len())
+            }
+
+            fn flush(&mut self) -> std::io::Result<()> {
+                Err(std::io::Error::other("simulated stdout flush failure"))
+            }
+        }
+
+        let ws = marker_ws("tools-list-flush-fail");
+        let input = std::io::Cursor::new(
+            br#"{"jsonrpc":"2.0","id":1,"method":"tools/list"}"#.to_vec(),
+        );
+        let error = run_stdio_loop(&ws, input, FlushFailWriter(Vec::new()))
+            .expect_err("flush must fail");
+        assert!(error.to_string().contains("simulated stdout flush failure"));
+        let events = EventLog::new(&ws).tail(0).unwrap();
+        assert!(!events
+            .iter()
+            .any(|event| event["event"] == serde_json::json!("mcp.tools_list_response_written")));
+        let _ = std::fs::remove_dir_all(&ws);
+    }
+
+    #[test]
+    fn stdio_loop_does_not_log_tools_list_for_initialize_or_notification() {
+        let ws = marker_ws("tools-list-not-applicable");
+        let input = std::io::Cursor::new(
+            br#"{"jsonrpc":"2.0","id":1,"method":"initialize"}
+{"jsonrpc":"2.0","method":"notifications/initialized"}
+"#.to_vec(),
+        );
+        let mut output = Vec::new();
+
+        run_stdio_loop(&ws, input, &mut output).unwrap();
+
+        let events = EventLog::new(&ws).tail(0).unwrap();
+        assert!(!events
+            .iter()
+            .any(|event| event["event"] == serde_json::json!("mcp.tools_list_response_written")));
+        let _ = std::fs::remove_dir_all(&ws);
+    }
+
     #[test]
     fn stdio_loop_writes_started_and_stdin_eof_exit_markers() {
         let ws = marker_ws("eof");

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

@@ -31,9 +31,10 @@ use crate::provider::wire::{
     is_claude_family, parse_canonical_provider, parse_provider, provider_wire,
 };
 use crate::transport::{
-    submit_verification_wire, turn_verification_wire, CaptureRange, CaptureSampleOutcome,
-    InjectPayload, InjectReport, InjectVerification, InputSurfaceProbe, Key, PaneId, PaneInfo,
-    QueryOutcome, SessionName, SubmitObserver, SubmitVerification, Target, Transport, WindowName,
+    submit_verification_wire, turn_verification_wire, BusySignalKind, CaptureRange,
+    CaptureSampleOutcome, InjectPayload, InjectReport, InjectVerification, InputSurfaceProbe, Key,
+    PaneId, PaneInfo, QueryOutcome, SessionName, SubmitConsumptionReason, SubmitObserver,
+    SubmitVerification, Target, Transport, WindowName,
 };
 
 use super::helpers::{message_exists, MessageStatusShadow};
@@ -572,11 +573,11 @@ pub fn deliver_pending_message(
         canonical_owner_team_id.as_deref(),
         resolved.metadata.as_ref(),
     );
-    let recipient_single_enter = recipient_requires_single_enter(state, &message.recipient);
+    let recipient_cursor = recipient_is_cursor_agent(state, &message.recipient);
     let inject_attempt = crate::tmux_backend::with_paste_to_submit_floor(
         paste_to_submit_floor_for_recipient(state, &message.recipient),
         || {
-            crate::tmux_backend::with_cursor_single_enter(recipient_single_enter, || {
+            crate::tmux_backend::with_cursor_single_enter(recipient_cursor, || {
                 transport.inject_with_submit_observer(
                     &target,
                     &payload,
@@ -592,9 +593,7 @@ pub fn deliver_pending_message(
             // grok 忙时第一次回车只入显式队列。默认 send-now：只重按回车顶出去。
             // 无 `Enter:send now` 时零次额外按键，claude/codex 行为不变。
             // cursor：第二下 Enter 打断进行中回合，不走 flush。
-            if !crate::provider::submit_now::keep_provider_queue_requested()
-                && recipient_allows_explicit_queue_flush(state, &message.recipient)
-            {
+            if !crate::provider::submit_now::keep_provider_queue_requested() && !recipient_cursor {
                 match crate::provider::submit_now::flush_explicit_queue(transport, &target) {
                     Ok(flush) if flush.extra_enters > 0 => {
                         let _ = event_log.write(
@@ -1999,6 +1998,36 @@ fn merge_inject_readback_fields(
             .map(|d| d.last_capture_outcome.as_str())
             .unwrap_or(CaptureSampleOutcome::NotAttempted.as_str())),
     );
+    obj.insert(
+        "consumption_reason".to_string(),
+        serde_json::json!(diag
+            .map(|d| d.consumption_reason.as_str())
+            .unwrap_or("unknown")),
+    );
+    obj.insert(
+        "before_busy_signal_kind".to_string(),
+        serde_json::json!(diag.and_then(|d| d.before_busy_signal_kind.map(|kind| kind.as_str()))),
+    );
+    obj.insert(
+        "busy_signal_kind".to_string(),
+        serde_json::json!(diag.and_then(|d| d.busy_signal_kind.map(|kind| kind.as_str()))),
+    );
+    obj.insert(
+        "busy_line_from_bottom".to_string(),
+        serde_json::json!(diag.and_then(|d| d.busy_line_from_bottom)),
+    );
+    obj.insert(
+        "current_marker_in_bottom_15".to_string(),
+        serde_json::json!(diag.and_then(|d| d.current_marker_in_bottom_15)),
+    );
+    obj.insert(
+        "paste_identity_in_composer".to_string(),
+        serde_json::json!(diag.and_then(|d| d.paste_identity_in_composer)),
+    );
+    obj.insert(
+        "consumption_from_capture_result".to_string(),
+        serde_json::json!(diag.and_then(|d| d.consumption_from_capture_result)),
+    );
     obj.insert(
         "pane_command_basename".to_string(),
         diag.and_then(|d| d.pane_command_basename.as_deref())
@@ -2357,6 +2386,13 @@ fn recipient_provider(state: &serde_json::Value, recipient: &str) -> Option<Prov
         .and_then(parse_canonical_provider)
 }
 
+fn recipient_is_cursor_agent(state: &serde_json::Value, recipient: &str) -> bool {
+    matches!(
+        recipient_provider(state, recipient),
+        Some(Provider::CursorAgent)
+    )
+}
+
 /// ---
 /// purpose: paste→Enter 地板按收件人 provider 选择
 /// contract: CursorAgent 与 Grok 为 1s；其余（含 claude）为 ZERO
@@ -3391,6 +3427,13 @@ mod paste_floor_tests {
             turn_verification: crate::transport::TurnVerification::NotYetObserved,
             attempts: 1,
             submit_diagnostics: Some(crate::transport::SubmitDiagnostics {
+                consumption_reason: SubmitConsumptionReason::Unverified,
+                before_busy_signal_kind: Some(BusySignalKind::Working),
+                busy_signal_kind: Some(BusySignalKind::SpinnerGlyph),
+                busy_line_from_bottom: Some(2),
+                current_marker_in_bottom_15: Some(false),
+                paste_identity_in_composer: None,
+                consumption_from_capture_result: Some(false),
                 last_capture_outcome: CaptureSampleOutcome::Failed,
                 capture_err_count: 1,
                 capture_sample_count: 1,
@@ -3419,6 +3462,22 @@ mod paste_floor_tests {
             None,
         );
         assert_eq!(event["last_capture_outcome"], serde_json::json!("failed"));
+        assert_eq!(event["consumption_reason"], serde_json::json!("unverified"));
+        assert_eq!(
+            event["before_busy_signal_kind"],
+            serde_json::json!("working")
+        );
+        assert_eq!(event["busy_signal_kind"], serde_json::json!("spinner_glyph"));
+        assert_eq!(event["busy_line_from_bottom"], serde_json::json!(2));
+        assert_eq!(
+            event["current_marker_in_bottom_15"],
+            serde_json::json!(false)
+        );
+        assert_eq!(event["paste_identity_in_composer"], serde_json::Value::Null);
+        assert_eq!(
+            event["consumption_from_capture_result"],
+            serde_json::json!(false)
+        );
         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"));

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

@@ -229,3 +229,59 @@ fn string_field<'a>(value: &'a Value, key: &str) -> Option<&'a str> {
         .and_then(Value::as_str)
         .filter(|value| !value.is_empty())
 }
+
+#[cfg(test)]
+mod claim_rework_live_tests {
+    use super::*;
+    use crate::transport::test_support::OfflineTransport;
+    use crate::transport::{PaneId, PaneInfo, SessionName};
+    use serde_json::json;
+    use std::path::PathBuf;
+
+    #[test]
+    fn pending_receiver_is_not_a_live_channel() {
+        let workspace = PathBuf::from("/tmp/claim-rework-a3-pending");
+        let receiver = json!({
+            "mode": "direct_tmux",
+            "status": "pending",
+            "pane_id": "%1",
+            "tmux_socket": "/tmp/ta-offline.sock"
+        });
+        let transport = OfflineTransport::default().with_tmux_endpoint("/tmp/ta-offline.sock");
+        match resolve_live_leader_channel(&workspace, &receiver, &transport) {
+            LeaderChannelResolution::Unbound(LeaderChannelUnbound::ReceiverNotAttached) => {}
+            other => panic!("pending seed must not be live; got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn dead_pane_with_matching_endpoint_is_pane_not_live() {
+        let workspace = PathBuf::from("/tmp/claim-rework-a3-dead");
+        let endpoint = "/tmp/ta-claim-rework-a3.sock";
+        let receiver = json!({
+            "mode": "direct_tmux",
+            "status": "attached",
+            "pane_id": "%missing",
+            "tmux_socket": endpoint
+        });
+        let transport = OfflineTransport::default()
+            .with_tmux_endpoint(endpoint)
+            .with_targets(vec![PaneInfo {
+                pane_id: PaneId::new("%other"),
+                session: SessionName::new("team"),
+                window_index: None,
+                window_name: None,
+                pane_index: None,
+                tty: None,
+                current_command: None,
+                current_path: None,
+                active: true,
+                pane_pid: None,
+                leader_env: Default::default(),
+            }]);
+        match resolve_live_leader_channel(&workspace, &receiver, &transport) {
+            LeaderChannelResolution::Unbound(LeaderChannelUnbound::PaneNotLive) => {}
+            other => panic!("matching endpoint + missing pane must be PaneNotLive; got {other:?}"),
+        }
+    }
+}

package/crates/team-agent/src/messaging/tests/runtime.rs

@@ -3376,10 +3376,18 @@ fn gate054_status_surfaces_pending_leader_notifications() {
         entry.get("channel").and_then(serde_json::Value::as_str),
         Some("rebind_required")
     );
-    assert!(entry
+    let action = entry
         .get("action")
         .and_then(serde_json::Value::as_str)
-        .is_some_and(|action| action.contains("attach-leader") || action.contains("takeover")));
+        .unwrap_or("");
+    assert!(
+        action.contains("historical leader mailbox debt"),
+        "historical debt action must stay debt-scoped; action={action}"
+    );
+    assert!(
+        !action.contains("attach-leader") && !action.contains("takeover") && !action.contains("claim-leader"),
+        "historical debt must not authorize bind commands; action={action}"
+    );
 }
 
 #[test]

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/provider/adapters/cursor_agent.rs

@@ -15,10 +15,8 @@
 //! `.team/scripts/cursor_seat.sh` 实测一致：
 //!   `--trust --sandbox disabled --workspace <物理路径> [--force] [--model]`
 //! Role 不入 argv，写 `<workspace>/.cursor/rules/*.mdc` + `alwaysApply: true`。
-//! MCP 无 `--mcp-config`；身份必须写进 per-seat
-//! `provider-config/<id>/cursor/.cursor/mcp.json` 的 env 表
+//! MCP 无 `--mcp-config`；身份必须写进 `.cursor/mcp.json` 的 env 表
 //! （cursor 不把父进程 TEAM_AGENT_* 传给 MCP 子进程）。
-//! spawn 把 `--workspace` 指到该工程根，并用 `--add-dir` 挂上真 workspace。
 //!
 //! 隐藏 flag `--system-prompt` / `--allowed-tools` 实测存在但 help 未列，
 //! 随时可能消失。可以在注释里记录，代码里不许调。
@@ -75,8 +73,7 @@ pub(crate) fn cursor_agent_base_command(
     let _ = effort;
     // system_prompt 不入 argv（help 无 --rules / --append-system-prompt）。
     // launch 写 `<workspace>/.cursor/rules/team-agent-role-<agent_id>.mdc`。
-    // mcp_config 也不入 argv（无 --mcp-config）。launch 写
-    // `.team/runtime/provider-config/<id>/cursor/.cursor/mcp.json`
+    // mcp_config 也不入 argv（无 --mcp-config）。launch 写 `.cursor/mcp.json`
     // 并 `agent mcp enable team_orchestrator`。这里收下以免静默丢弃。
     let _ = (adapter, auth_mode, mcp_config, managed_mcp_config, system_prompt);
     argv.push("--workspace".to_string());

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);