@team-agent/installer 0.5.61 → 0.5.63

package/crates/team-agent/src/provider/session/resume.rs

@@ -1,4 +1,5 @@
-//! unit-5 (Stage 2) — resume preflight + closed `ResumeRefusalReason` enum.
+//!
+//! unit-5 (Stage 2) — closed `ResumeRefusalReason` enum and recovery hints.
 //!
 //! Today the restart resume gate flattens every refusal into one of two
 //! opaque strings:
@@ -159,110 +160,6 @@ impl ResumeRefusalReason {
     }
 }
 
-/// Outcome of `ResumePreflight::check`.
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub enum ResumePreflightOutcome {
-    /// Worker can resume from the named session.
-    Resume { session_id: String },
-    /// `--allow-fresh` was set; worker will start fresh.
-    FreshStart,
-    /// Resume refused. Caller MUST NOT proceed with teardown/spawn.
-    Refuse { reason: ResumeRefusalReason },
-}
-
-/// Information about whether a provider backing file is present on disk.
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct ProviderBackingCheck {
-    pub paths: Vec<PathBuf>,
-    pub exists: bool,
-}
-
-/// Per-decision detail emitted to events / JSON.
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct ResumeDecisionDetail {
-    pub agent_id: String,
-    pub session_id: Option<String>,
-    pub provider: String,
-    pub backing: Option<ProviderBackingCheck>,
-    pub outcome: ResumePreflightOutcome,
-}
-
-/// Pure resume preflight evaluator. No I/O — callers pass facts in.
-pub struct ResumePreflight;
-
-impl ResumePreflight {
-    /// Decide a single worker's resume outcome from the facts the
-    /// restart code already collected. Mirrors the existing
-    /// `classify_restart_plan_with_resume_validation` decision tree:
-    ///
-    ///   * session_id present + provider can resume + backing exists -> Resume
-    ///   * session_id present + (no resume OR no backing) + allow_fresh -> FreshStart
-    ///   * session_id present + (no resume OR no backing) + !allow_fresh -> Refuse
-    ///   * session_id absent + allow_fresh -> FreshStart
-    ///   * session_id absent + !allow_fresh -> Refuse(NoSessionId)
-    pub fn check(
-        session_id: Option<&str>,
-        provider_can_resume: bool,
-        backing: Option<&ProviderBackingCheck>,
-        provider_name: &str,
-        allow_fresh: bool,
-    ) -> ResumePreflightOutcome {
-        Self::check_with_hint(
-            session_id,
-            provider_can_resume,
-            backing,
-            provider_name,
-            allow_fresh,
-            None,
-        )
-    }
-
-    /// Layer 2 self-healing variant: same decision tree as
-    /// [`Self::check`], but propagates an optional `RecoveryHint` into
-    /// the `SessionBackingStoreMissing` refusal so the CLI / event log
-    /// can surface a "look for session named X under cwd Y" pointer to
-    /// the operator. The hint is for HUMAN consumption only — no
-    /// auto-resume happens off it (Layer 3 follow-up).
-    pub fn check_with_hint(
-        session_id: Option<&str>,
-        provider_can_resume: bool,
-        backing: Option<&ProviderBackingCheck>,
-        provider_name: &str,
-        allow_fresh: bool,
-        recovery_hint: Option<RecoveryHint>,
-    ) -> ResumePreflightOutcome {
-        match session_id {
-            Some(sid) if provider_can_resume => {
-                let backing_present = backing.map(|b| b.exists).unwrap_or(true);
-                if backing_present {
-                    ResumePreflightOutcome::Resume {
-                        session_id: sid.to_string(),
-                    }
-                } else if allow_fresh {
-                    ResumePreflightOutcome::FreshStart
-                } else {
-                    ResumePreflightOutcome::Refuse {
-                        reason: ResumeRefusalReason::SessionBackingStoreMissing {
-                            checked_paths: backing.map(|b| b.paths.clone()).unwrap_or_default(),
-                            recovery_hint,
-                        },
-                    }
-                }
-            }
-            Some(_) if allow_fresh => ResumePreflightOutcome::FreshStart,
-            Some(_) => ResumePreflightOutcome::Refuse {
-                reason: ResumeRefusalReason::ProviderResumeUnsupported {
-                    provider: provider_name.to_string(),
-                },
-            },
-            None if allow_fresh => ResumePreflightOutcome::FreshStart,
-            None => ResumePreflightOutcome::Refuse {
-                reason: ResumeRefusalReason::NoSessionId,
-            },
-        }
-    }
-}
-
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -287,58 +184,6 @@ mod tests {
         assert!(matches!(r, ResumeRefusalReason::Other { .. }));
     }
 
-    #[test]
-    fn preflight_resume_when_session_and_backing_present() {
-        let backing = ProviderBackingCheck {
-            paths: vec![PathBuf::from("/tmp/x.jsonl")],
-            exists: true,
-        };
-        let out = ResumePreflight::check(Some("sess-1"), true, Some(&backing), "codex", false);
-        assert!(matches!(out, ResumePreflightOutcome::Resume { .. }));
-    }
-
-    #[test]
-    fn preflight_refuses_when_session_id_missing_without_allow_fresh() {
-        let out = ResumePreflight::check(None, true, None, "codex", false);
-        assert_eq!(
-            out,
-            ResumePreflightOutcome::Refuse {
-                reason: ResumeRefusalReason::NoSessionId
-            }
-        );
-    }
-
-    #[test]
-    fn preflight_distinguishes_backing_missing_from_no_session_id() {
-        let backing = ProviderBackingCheck {
-            paths: vec![PathBuf::from("/missing.jsonl")],
-            exists: false,
-        };
-        let out = ResumePreflight::check(Some("sess-x"), true, Some(&backing), "codex", false);
-        match out {
-            ResumePreflightOutcome::Refuse { reason } => {
-                assert_eq!(reason.wire(), "session_backing_store_missing");
-            }
-            other => panic!("expected backing-missing refusal; got {other:?}"),
-        }
-    }
-
-    #[test]
-    fn preflight_allow_fresh_converts_refusals_to_fresh() {
-        let backing = ProviderBackingCheck {
-            paths: vec![PathBuf::from("/missing.jsonl")],
-            exists: false,
-        };
-        assert_eq!(
-            ResumePreflight::check(None, true, None, "codex", true),
-            ResumePreflightOutcome::FreshStart
-        );
-        assert_eq!(
-            ResumePreflight::check(Some("sess-x"), true, Some(&backing), "codex", true),
-            ResumePreflightOutcome::FreshStart
-        );
-    }
-
     // Layer 2 self-healing tests ────────────────────────────────────────────
 
     #[test]
@@ -364,56 +209,4 @@ mod tests {
         };
         assert_eq!(hint.picker_hint(), "codex session");
     }
-
-    #[test]
-    fn preflight_with_hint_attaches_to_backing_missing_refusal() {
-        let backing = ProviderBackingCheck {
-            paths: vec![PathBuf::from("/missing.jsonl")],
-            exists: false,
-        };
-        let hint = RecoveryHint {
-            provider_session_name_hint: Some("coder".to_string()),
-            spawn_cwd: Some(PathBuf::from("/repo")),
-            provider: "claude".to_string(),
-        };
-        let out = ResumePreflight::check_with_hint(
-            Some("sess-1"),
-            true,
-            Some(&backing),
-            "claude",
-            false,
-            Some(hint.clone()),
-        );
-        match out {
-            ResumePreflightOutcome::Refuse {
-                reason:
-                    ResumeRefusalReason::SessionBackingStoreMissing {
-                        recovery_hint: Some(h),
-                        ..
-                    },
-            } => {
-                assert_eq!(h, hint);
-            }
-            other => panic!("expected SessionBackingStoreMissing with hint; got {other:?}"),
-        }
-    }
-
-    #[test]
-    fn preflight_no_hint_legacy_behavior_unchanged() {
-        // Default check() (no hint) still produces None recovery_hint —
-        // wire-string-compatible with pre-Layer-2 callers.
-        let backing = ProviderBackingCheck {
-            paths: vec![PathBuf::from("/missing.jsonl")],
-            exists: false,
-        };
-        let out = ResumePreflight::check(Some("sess-x"), true, Some(&backing), "codex", false);
-        match out {
-            ResumePreflightOutcome::Refuse {
-                reason: ResumeRefusalReason::SessionBackingStoreMissing { recovery_hint, .. },
-            } => {
-                assert!(recovery_hint.is_none());
-            }
-            other => panic!("expected backing-missing refusal; got {other:?}"),
-        }
-    }
 }

package/crates/team-agent/src/provider/session_scan/claude.rs

@@ -1,3 +1,4 @@
+//!
 use std::path::{Path, PathBuf};
 
 use crate::provider::helpers::find_session_id;

package/crates/team-agent/src/provider/session_scan/codex.rs

@@ -1,3 +1,4 @@
+//!
 pub(super) fn parse_spawned_at(raw: &str) -> Option<std::time::SystemTime> {
     chrono::DateTime::parse_from_rfc3339(raw)
         .ok()

package/crates/team-agent/src/provider/session_scan/common.rs

@@ -1,3 +1,4 @@
+//!
 use std::path::{Path, PathBuf};
 
 use crate::provider::helpers::{find_session_id, parse_jsonl_records};

package/crates/team-agent/src/provider/session_scan/copilot.rs

@@ -1,3 +1,4 @@
+//!
 use std::path::Path;
 
 use crate::provider::types::{CaptureVia, CapturedSession, Confidence, RolloutPath, SessionId};

package/crates/team-agent/src/provider/session_scan.rs

@@ -1,3 +1,4 @@
+//!
 //! Provider session-scan boundary.
 //!
 //! `ProviderAdapter` keeps the public polling facade in `adapter.rs`; this
@@ -14,27 +15,6 @@ pub(crate) mod codex;
 pub(crate) mod common;
 pub(crate) mod copilot;
 
-/// Marker label for which scan strategy a provider uses.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum SessionScanStrategy {
-    CodexJsonl,
-    ClaudeTranscript,
-    CopilotHome,
-    NotRequired,
-}
-
-impl SessionScanStrategy {
-    pub fn for_provider(provider: Provider) -> Self {
-        match provider {
-            Provider::Codex => Self::CodexJsonl,
-            Provider::Claude | Provider::ClaudeCode => Self::ClaudeTranscript,
-            Provider::Copilot => Self::CopilotHome,
-            Provider::GeminiCli => Self::NotRequired,
-            Provider::Fake => Self::NotRequired,
-        }
-    }
-}
-
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct CaptureSessionContext {
     pub agent_id: String,
@@ -87,24 +67,3 @@ pub(crate) fn scan_session_candidates_once(
 }
 
 pub(crate) use claude::rollout_path_has_leader_marker as rollout_path_has_claude_leader_marker;
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn strategy_per_provider() {
-        assert_eq!(
-            SessionScanStrategy::for_provider(Provider::Codex),
-            SessionScanStrategy::CodexJsonl
-        );
-        assert_eq!(
-            SessionScanStrategy::for_provider(Provider::Claude),
-            SessionScanStrategy::ClaudeTranscript
-        );
-        assert_eq!(
-            SessionScanStrategy::for_provider(Provider::Fake),
-            SessionScanStrategy::NotRequired
-        );
-    }
-}

package/crates/team-agent/src/provider/startup_prompt.rs

@@ -1,3 +1,4 @@
+//!
 //! codex startup-prompt recognizer — workspace-trust + update-skip screen detection.
 //!
 //! Golden (READ-ONLY truth `team-agent-public` v0.2.11): `provider_cli/codex.py`

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

@@ -1,3 +1,4 @@
+//!
 //! provider 共享类型:enums / newtypes / ProviderCaps / ProviderError / 捕获+classify payload / 占位结构。
 
 use std::collections::{BTreeMap, BTreeSet};

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

@@ -1,3 +1,4 @@
+//!
 //! Provider wire-format helpers — the single source of truth for converting
 //! `Provider` ↔ string forms used across state JSON, CLI args, log fields,
 //! and the workers we shell out to.

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

@@ -1,3 +1,4 @@
+//!
 //! identity:leader receiver identity 派生 / 迁移 / first-time binding(真相源 `state.py`)。
 //!
 //! Python 直接读 `os.environ`/`os.getcwd()`/`Path.resolve()`;此处把**环境变量**经
@@ -44,8 +45,9 @@ fn path_str(p: &Path) -> String {
     p.to_string_lossy().into_owned()
 }
 
+///
 /// `_identity_os_user`(`state.py:275`):`USER` or `USERNAME` or `""`。
-pub fn identity_os_user(env: &dyn IdentityEnv) -> String {
+fn identity_os_user(env: &dyn IdentityEnv) -> String {
     let user = env_str(env, "USER");
     if !user.is_empty() {
         return user;
@@ -57,9 +59,10 @@ pub fn identity_os_user(env: &dyn IdentityEnv) -> String {
     String::new()
 }
 
+///
 /// `_identity_machine_fingerprint`(`state.py:279`):team_owner/leader_receiver 的非空
 /// machine_fingerprint 优先,否则 env `TEAM_AGENT_MACHINE_FINGERPRINT` or `""`。
-pub fn identity_machine_fingerprint(state: &Value, env: &dyn IdentityEnv) -> String {
+fn identity_machine_fingerprint(state: &Value, env: &dyn IdentityEnv) -> String {
     for key in ["team_owner", "leader_receiver"] {
         if let Some(fp) = state
             .get(key)
@@ -74,9 +77,10 @@ pub fn identity_machine_fingerprint(state: &Value, env: &dyn IdentityEnv) -> Str
     env_str(env, "TEAM_AGENT_MACHINE_FINGERPRINT")
 }
 
+///
 /// `_identity_workspace_abspath`(`state.py:264`):按 workspace→team_dir→spec_path→fallback
 /// 顺序派生 workspace 绝对路径(各分支先 `resolve()` 再做 parent 导航)。
-pub fn identity_workspace_abspath(
+fn identity_workspace_abspath(
     state: &Value,
     env: &dyn IdentityEnv,
     workspace: Option<&Path>,
@@ -157,9 +161,10 @@ fn leader_session_uuid_for_state(
     Ok(uuid.as_str().to_string())
 }
 
+///
 /// `_migrate_team_identity`(`state.py:295`):为缺 `leader_session_uuid` 的 team_owner /
 /// leader_receiver 填入派生 uuid。返回是否有改动。
-pub fn migrate_team_identity(
+fn migrate_team_identity(
     state: &mut Value,
     env: &dyn IdentityEnv,
     workspace: Option<&Path>,
@@ -189,6 +194,7 @@ pub fn migrate_team_identity(
     Ok(changed)
 }
 
+///
 /// `_migrate_state_identity`(`state.py:306`):顶层(有 session_name 时)+ 每个 team 子状态迁移。
 pub fn migrate_state_identity(
     state: &mut Value,
@@ -220,6 +226,7 @@ pub fn migrate_state_identity(
     Ok(changed)
 }
 
+///
 /// `_caller_identity_from_env`(`state.py:316`):env override/env/derived → 5 字段 caller 身份。
 pub fn caller_identity_from_env(
     state: Option<&Value>,
@@ -282,9 +289,10 @@ pub fn caller_identity_from_env(
     })
 }
 
+///
 /// `populate_team_owner_from_env`(`state.py:414`):已有 team_owner → 仅补迁移 uuid 后返回;
 /// 否则从 env caller 身份 seed team_owner(无 pane_id → `None`)。`now_iso` = claimed_at。
-pub fn populate_team_owner_from_env(
+fn populate_team_owner_from_env(
     state: &mut Value,
     source: &str,
     env: &dyn IdentityEnv,
@@ -320,6 +328,7 @@ pub fn populate_team_owner_from_env(
     Ok(Some(owner))
 }
 
+///
 /// `apply_first_time_leader_binding`(`state.py:434`):命令 + workspace realpath 双门后,
 /// 写入 team_owner / leader_receiver(owner_epoch=0)。拒绝 dict 字节对齐 Python(含 `pane` +
 /// `repr()` 错误串)。`command_looks_usable`(`_leader_command_looks_usable`,step 11)经闭包注入。
@@ -411,6 +420,7 @@ pub fn apply_first_time_leader_binding(
     json!({ "ok": true, "pane": pane_info, "warning": null, "first_time": true })
 }
 
+///
 /// `leader_env_exports`(`state.py:469`):receiver + identity → 6 个 leader env 导出(插入序)。
 pub fn leader_env_exports(receiver: &Value, identity: &Value) -> Vec<(String, String)> {
     vec![
@@ -441,6 +451,7 @@ pub fn leader_env_exports(receiver: &Value, identity: &Value) -> Vec<(String, St
     ]
 }
 
+///
 /// `validate_leader_uuid_from_targets`(`state.py:480`):fake provider 直过;否则核对 targets
 /// 扫描成功 + receiver.pane_id 在 targets 中存在。
 pub fn validate_leader_uuid_from_targets(receiver: &Value, targets: &Value) -> Value {

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

@@ -1,3 +1,4 @@
+//!
 //! Stage 0 of the identity-boundary unified plan (architect direction
 //! 2026-06-23): `SessionAttributionKey`.
 //!

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

@@ -1,3 +1,4 @@
+//!
 //! step 5 · state — state.json 持久化 / identity / owner-gate / projection(真相源 `state.py`)。
 //!
 //! §6 step 5:原子写/锁/self-heal(**bug-084** 血泪)/ team projection / leader receiver identity /
@@ -32,6 +33,7 @@ pub mod selector;
 use serde_json::Value;
 use thiserror::Error;
 
+///
 /// Python 真值语义(`null`/`false`/`0`/`""`/`[]`/`{}` → false),`state` 模块共用。
 pub(crate) fn json_truthy(v: &Value) -> bool {
     match v {

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

@@ -1,3 +1,4 @@
+//!
 //! owner-gate:trust own-vs-foreign(§11 / bug-064 / bug-082 血泪;真相源 `state.py`)。
 //!
 //! 三核心纯判定(集成 send_message/MCP 是 step 11/14):
@@ -37,6 +38,7 @@ pub struct CallerIdentity {
     pub leader_session_uuid_source: String,
 }
 
+///
 /// `check_team_owner`(`state.py:366`)的纯判定版:caller 身份 + 是否有 TEAM_AGENT_ID + liveness 注入。
 /// 返回 `None`=允许(own / 无 owner / 死 owner pane 可接管);`Some(dict)`=拒绝(team_owner_mismatch)。
 ///
@@ -123,6 +125,7 @@ fn caller_to_value(c: &CallerIdentity) -> Value {
     })
 }
 
+///
 /// `worker_sender_bypasses_owner_gate`(`state.py:400`):worker peer-send 绕过 owner 门。
 /// 返回 `Some(agent_id)`=绕过;`None`=不绕过(走 owner 门)。
 pub fn worker_sender_bypasses_owner_gate(
@@ -160,6 +163,7 @@ pub fn worker_sender_bypasses_owner_gate(
     Some(sender.to_string())
 }
 
+///
 /// §11 realpath own-vs-foreign(`state.py:449`):**两边 canonicalize** 后全等才判 own。
 /// macOS `/tmp → /private/tmp` 软链不对称由「两边 canonicalize」消除。canonicalize 失败(路径不存在)
 /// → 退化为词法绝对比较(此时无软链可解,等价)。**禁 basename/startswith/子串/反推**。
@@ -187,6 +191,7 @@ fn lexical_abs(p: &Path) -> std::path::PathBuf {
     }
 }
 
+///
 /// `os.path.realpath` 等价(对抗 P0-B):全路径存在 → `canonicalize`;否则对**最长存在前缀**
 /// canonicalize(解析其软链)再拼回缺失末段(规范化 `..`/`.`)。这复刻 Python「解析存在部分的
 /// 软链 + 保留不存在末段」,修掉「父目录是软链 + 末段不存在 → 漏判 own」的 §11 血泪。

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

@@ -1,3 +1,4 @@
+//!
 //! Stage 2 of identity-boundary unified plan (architect direction 2026-06-23):
 //! `state::ownership` — single read entry point for `team_owner` lookups.
 //!
@@ -41,7 +42,7 @@ use crate::state::projection::{read_owner as projection_read_owner, team_state_k
 /// owner value. CLI status / diagnose use it to surface legacy duplicate
 /// warnings.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum OwnershipSource {
+enum OwnershipSource {
     /// Stage 5 canonical path: `.team/runtime/<team_key>/state.json` (not
     /// yet emitted — placeholder for forward compatibility).
     CanonicalPerTeamState,
@@ -57,11 +58,12 @@ pub enum OwnershipSource {
 /// caller consumes (same shape as `state.get("team_owner")` returned today);
 /// the `source` is diagnostic.
 #[derive(Debug, Clone)]
-pub struct OwnershipRead<'a> {
+struct OwnershipRead<'a> {
     pub value: &'a Value,
     pub source: OwnershipSource,
 }
 
+///
 /// Stage 2 entry point: read the team owner for the given `team_key` from an
 /// in-memory state value, honouring the legacy precedence. Returns `None` if
 /// no source carries a non-empty, valid owner record.
@@ -73,7 +75,7 @@ pub struct OwnershipRead<'a> {
 /// This deliberately reuses `projection::read_owner` so the pane-id validity
 /// check (`%N` or all-digits) stays in one place. The repository's value-add
 /// is the precedence ordering and the `OwnershipSource` tag.
-pub fn read_owner_for_team<'a>(state: &'a Value, team_key: &str) -> Option<OwnershipRead<'a>> {
+fn read_owner_for_team<'a>(state: &'a Value, team_key: &str) -> Option<OwnershipRead<'a>> {
     // Step 1 (Stage 5): canonical per-team state. Stage 2 does not consult
     // a separate file yet — owner truth still lives in the in-memory state.
     // Once Stage 5 wires `.team/runtime/<team_key>/state.json` as canonical,
@@ -109,6 +111,7 @@ pub fn read_owner_for_team<'a>(state: &'a Value, team_key: &str) -> Option<Owner
     None
 }
 
+///
 /// Convenience: just the JSON value, no diagnostic source. Returns `None`
 /// when no owner is found. Stable across Stage 5 — only the lookup
 /// implementation will move.
@@ -116,6 +119,7 @@ pub fn read_owner_value<'a>(state: &'a Value, team_key: &str) -> Option<&'a Valu
     read_owner_for_team(state, team_key).map(|read| read.value)
 }
 
+///
 /// Stage 3 (identity-boundary unified plan, architect direction 2026-06-23):
 /// single write entry point for owner mutations. Pre-Stage-3, owner writes
 /// were spread across 13 sites (claim/attach/readopt/managed-leader/quick-
@@ -187,6 +191,7 @@ pub fn write_owner(state: &mut Value, team_key: &str, record: OwnershipWrite) {
     }
 }
 
+///
 /// Stage 3 top-level cleanup (architect direction 2026-06-24,
 /// .team/artifacts/stage3-toplevel-cleanup-fix.md): strip the legacy
 /// top-level `team_owner / leader_receiver / owner_epoch` fields from a
@@ -202,12 +207,13 @@ pub fn write_owner(state: &mut Value, team_key: &str, record: OwnershipWrite) {
 /// load-time path — legacy single-team states may still have only
 /// top-level owner and no canonical `teams.<key>` owner, and a blind load
 /// strip would lose ownership before migration.
-pub fn strip_top_level_ownership(root: &mut serde_json::Map<String, Value>) {
+fn strip_top_level_ownership(root: &mut serde_json::Map<String, Value>) {
     for key in ["team_owner", "leader_receiver", "owner_epoch"] {
         root.remove(key);
     }
 }
 
+///
 /// Stage 3 save-output canonical-aware strip (architect direction
 /// 2026-06-24, .team/artifacts/stage3-save-strip-fix.md): conditional
 /// version of `strip_top_level_ownership` used by `state::persist`'s

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

@@ -1,3 +1,4 @@
+//!
 //! Stage 0 of the identity-boundary unified plan (architect direction
 //! 2026-06-23): `TeamScope` + `TeamRuntimePaths` foundation.
 //!
@@ -42,6 +43,7 @@ pub struct TeamScope {
 }
 
 impl TeamScope {
+    ///
     /// Construct a TeamScope from an already-resolved workspace + team_key.
     /// Callers that have a display name must resolve it through the existing
     /// `state::selector` machinery first; this constructor refuses an empty
@@ -66,6 +68,7 @@ impl TeamScope {
         &self.team_key
     }
 
+    ///
     /// Convenience: derive the path helper from this scope.
     pub fn paths(&self) -> TeamRuntimePaths {
         TeamRuntimePaths::for_scope(self)
@@ -110,6 +113,7 @@ impl TeamRuntimePaths {
         &self.team_key
     }
 
+    ///
     /// `.team/runtime/teams/<team_key>/` — the team's future B3 runtime
     /// directory. It is not used as product authority until the B3 migration;
     /// current callers must keep using `runtime_state_path`.
@@ -119,6 +123,7 @@ impl TeamRuntimePaths {
             .join(&self.team_key)
     }
 
+    ///
     /// Transitional runtime spec path. Mirrors the existing
     /// `runtime_spec_path` helper while specs remain at
     /// `.team/runtime/<team_key>/team.spec.yaml`.
@@ -126,6 +131,7 @@ impl TeamRuntimePaths {
         runtime_spec_path(&self.workspace, &self.team_key)
     }
 
+    ///
     /// `.team/runtime/teams/<team_key>/state.json` — the canonical per-team
     /// state path that B3 will start writing. Not used by current product
     /// code; callers must continue using `runtime_state_path` until B3
@@ -134,11 +140,13 @@ impl TeamRuntimePaths {
         self.team_dir().join("state.json")
     }
 
+    ///
     /// `.team/runtime/teams/<team_key>/coordinator.pid` — future sidecar location.
     pub fn coordinator_pid_path(&self) -> PathBuf {
         self.team_dir().join("coordinator.pid")
     }
 
+    ///
     /// `.team/runtime/teams/<team_key>/coordinator.log` — future sidecar location.
     pub fn coordinator_log_path(&self) -> PathBuf {
         self.team_dir().join("coordinator.log")
@@ -180,6 +188,7 @@ pub enum CommandScope {
 }
 
 impl CommandScope {
+    ///
     /// Resolve the CLI's `--team` argument against the workspace state.
     /// On any I/O error the empty case is returned — destructive commands
     /// will run their own selector and surface the real error.
@@ -202,6 +211,7 @@ impl CommandScope {
         }
     }
 
+    ///
     /// Convert to an `Option<String>` for backward compatibility with
     /// existing `args.team.as_deref()` call sites.
     pub fn team_key(&self) -> Option<&str> {
@@ -211,11 +221,13 @@ impl CommandScope {
         }
     }
 
+    ///
     /// True iff there are 2+ alive teams and no explicit `--team`.
     pub fn is_ambiguous(&self) -> bool {
         matches!(self, Self::Ambiguous(_))
     }
 
+    ///
     /// The candidate list when ambiguous; empty otherwise.
     pub fn candidates(&self) -> &[String] {
         match self {