@team-agent/installer 0.5.60 → 0.5.62

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,6 +1,8 @@
+//!
 use std::path::{Path, PathBuf};
 
-use crate::provider::types::SessionId;
+use crate::provider::helpers::find_session_id;
+use crate::provider::types::{CaptureVia, CapturedSession, Confidence, RolloutPath, SessionId};
 use crate::provider::Provider;
 
 use super::{CaptureSessionContext, CapturedSessionCandidate};
@@ -14,7 +16,7 @@ pub(crate) fn projects_dir_for_cwd(home: &Path, spawn_cwd: &Path) -> Option<Path
     Some(home.join(".claude").join("projects").join(encoded))
 }
 
-fn encode_projects_dir(path: &str) -> String {
+pub(super) fn encode_projects_dir(path: &str) -> String {
     let mut out = String::with_capacity(path.len());
     for c in path.chars() {
         if c.is_ascii_alphanumeric() {
@@ -26,6 +28,65 @@ fn encode_projects_dir(path: &str) -> String {
     out
 }
 
+pub(super) fn scan_expected_session(
+    context: &CaptureSessionContext,
+) -> Vec<CapturedSessionCandidate> {
+    let Some(expected) = context.expected_session_id.as_ref() else {
+        return Vec::new();
+    };
+    let Some(projects_root) = context.provider_projects_root.clone().or_else(|| {
+        std::env::var_os("HOME")
+            .map(PathBuf::from)
+            .map(|home| home.join(".claude").join("projects"))
+    }) else {
+        return Vec::new();
+    };
+    let canonical =
+        std::fs::canonicalize(&context.spawn_cwd).unwrap_or_else(|_| context.spawn_cwd.clone());
+    let encoded = encode_projects_dir(&canonical.to_string_lossy());
+    if encoded.is_empty() {
+        return Vec::new();
+    }
+    let path = projects_root
+        .join(encoded)
+        .join(format!("{}.jsonl", expected.as_str()));
+    let Ok(text) = super::common::read_head_text(&path, super::common::CAPTURE_HEAD_BYTES) else {
+        return Vec::new();
+    };
+    let records = super::common::parse_session_records(&text);
+    let session_matches = records
+        .iter()
+        .find_map(find_session_id)
+        .is_some_and(|session_id| session_id == expected.as_str());
+    let has_lifecycle_record = records.iter().any(|record| {
+        matches!(
+            record.get("type").and_then(serde_json::Value::as_str),
+            Some("user" | "assistant")
+        )
+    });
+    if !session_matches
+        || !has_lifecycle_record
+        || records_have_leader_marker(&records)
+        || !records.iter().any(has_cwd_field)
+    {
+        return Vec::new();
+    }
+    let embedded_agent_id = super::common::embedded_team_agent_worker_id_from_text(&text);
+    let positive_agent_id_match = embedded_agent_id.as_deref() == Some(context.agent_id.as_str());
+    vec![CapturedSessionCandidate {
+        captured: CapturedSession {
+            session_id: Some(expected.clone()),
+            rollout_path: Some(RolloutPath::new(path)),
+            captured_via: CaptureVia::FsWatch,
+            attribution_confidence: Confidence::High,
+            spawn_cwd: context.spawn_cwd.clone(),
+        },
+        embedded_agent_id,
+        positive_agent_id_match,
+        agent_path_match: false,
+    }]
+}
+
 pub(crate) fn rollout_path_has_leader_marker(provider: Provider, rollout_path: &Path) -> bool {
     if !matches!(provider, Provider::Claude | Provider::ClaudeCode) {
         return false;
@@ -112,6 +173,7 @@ mod tests {
         std::fs::create_dir_all(dir).unwrap();
         let path = dir.join(format!("{uuid}.jsonl"));
         let line = serde_json::json!({
+            "type": "user",
             "sessionId": uuid,
             "cwd": cwd.to_string_lossy(),
         });
@@ -119,6 +181,11 @@ mod tests {
         path
     }
 
+    fn expected_transcript_dir(projects_root: &Path, cwd: &Path) -> PathBuf {
+        let canonical = std::fs::canonicalize(cwd).unwrap_or_else(|_| cwd.to_path_buf());
+        projects_root.join(encode_projects_dir(&canonical.to_string_lossy()))
+    }
+
     #[test]
     fn claude_leader_marker_in_custom_title_is_detected() {
         let records = vec![serde_json::json!({
@@ -205,7 +272,11 @@ mod tests {
         std::fs::create_dir_all(&cwd).unwrap();
         let proj = base.join("projects");
         write_transcript(&proj, "11111111-1111-4111-8111-111111111111", &cwd);
-        write_transcript(&proj, "22222222-2222-4222-8222-222222222222", &cwd);
+        let expected = write_transcript(
+            &expected_transcript_dir(&proj, &cwd),
+            "22222222-2222-4222-8222-222222222222",
+            &cwd,
+        );
         let ctx = CaptureSessionContext {
             agent_id: "w1".to_string(),
             spawn_cwd: cwd.clone(),
@@ -221,6 +292,10 @@ mod tests {
             out[0].captured.session_id.as_ref().unwrap().as_str(),
             "22222222-2222-4222-8222-222222222222"
         );
+        assert_eq!(
+            out[0].captured.rollout_path.as_ref().unwrap().as_path(),
+            expected
+        );
         let _ = std::fs::remove_dir_all(&base);
     }
 
@@ -284,6 +359,21 @@ mod tests {
         let proj = base.join("projects");
         let leader = write_transcript(&proj, "11111111-1111-4111-8111-111111111111", &cwd);
         let stale = write_transcript(&proj, "22222222-2222-4222-8222-222222222222", &cwd);
+        let addressed =
+            expected_transcript_dir(&proj, &cwd).join("99999999-9999-4999-8999-999999999999.jsonl");
+        std::fs::create_dir_all(addressed.parent().unwrap()).unwrap();
+        std::fs::write(
+            &addressed,
+            format!(
+                "{}\n",
+                serde_json::json!({
+                    "type": "user",
+                    "sessionId": "22222222-2222-4222-8222-222222222222",
+                    "cwd": cwd.to_string_lossy(),
+                })
+            ),
+        )
+        .unwrap();
         let _ = (leader, stale);
         let ctx = CaptureSessionContext {
             agent_id: "claude-worker".to_string(),

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};
@@ -26,25 +27,36 @@ pub(super) fn candidate_session_files(
 ) -> Result<Vec<SessionCandidate>, ProviderError> {
     let mut out = Vec::new();
     if let Some(root) = context.provider_projects_root.as_ref() {
-        collect_optional_candidate_files(root, &context.agent_id, &mut out)?;
+        let allowed_team_root =
+            matches!(provider, Provider::Claude | Provider::ClaudeCode).then_some(root.as_path());
+        collect_optional_candidate_files(root, &context.agent_id, allowed_team_root, &mut out)?;
     }
-    collect_candidate_files(&context.spawn_cwd, &context.agent_id, 0, false, &mut out)?;
+    collect_candidate_files(
+        &context.spawn_cwd,
+        &context.agent_id,
+        0,
+        false,
+        None,
+        &mut out,
+    )?;
     if let Some(home) = std::env::var_os("HOME").map(PathBuf::from) {
         match provider {
             Provider::Codex => {
                 collect_optional_candidate_files(
                     &home.join(".codex").join("sessions"),
                     &context.agent_id,
+                    None,
                     &mut out,
                 )?;
             }
             Provider::Claude | Provider::ClaudeCode => {
                 if let Some(dir) = super::claude::projects_dir_for_cwd(&home, &context.spawn_cwd) {
-                    collect_optional_candidate_files(&dir, &context.agent_id, &mut out)?;
+                    collect_optional_candidate_files(&dir, &context.agent_id, None, &mut out)?;
                 }
                 collect_optional_candidate_files(
                     &home.join(".claude").join("projects"),
                     &context.agent_id,
+                    None,
                     &mut out,
                 )?;
             }
@@ -275,10 +287,11 @@ fn complete_head_text(bytes: &[u8]) -> String {
 fn collect_optional_candidate_files(
     dir: &Path,
     agent_id: &str,
+    allowed_team_root: Option<&Path>,
     out: &mut Vec<SessionCandidate>,
 ) -> Result<(), ProviderError> {
     if dir.exists() {
-        let _ = collect_candidate_files(dir, agent_id, 0, true, out);
+        let _ = collect_candidate_files(dir, agent_id, 0, true, allowed_team_root, out);
     }
     Ok(())
 }
@@ -288,6 +301,7 @@ fn collect_candidate_files(
     agent_id: &str,
     depth: usize,
     requires_cwd_match: bool,
+    allowed_team_root: Option<&Path>,
     out: &mut Vec<SessionCandidate>,
 ) -> Result<(), ProviderError> {
     if depth > 4 {
@@ -309,9 +323,10 @@ fn collect_candidate_files(
                 agent_id,
                 depth.saturating_add(1),
                 requires_cwd_match,
+                allowed_team_root,
                 out,
             )?;
-        } else if looks_like_session_file(&path, agent_id) {
+        } else if looks_like_session_file(&path, agent_id, allowed_team_root) {
             out.push(SessionCandidate {
                 path,
                 requires_cwd_match,
@@ -321,8 +336,10 @@ fn collect_candidate_files(
     Ok(())
 }
 
-fn looks_like_session_file(path: &Path, agent_id: &str) -> bool {
-    if path_is_under_team_runtime(path) {
+fn looks_like_session_file(path: &Path, agent_id: &str, allowed_team_root: Option<&Path>) -> bool {
+    if path_is_under_team_runtime(path)
+        && !allowed_team_root.is_some_and(|root| path.starts_with(root))
+    {
         return false;
     }
     let Some(name) = path.file_name().and_then(|s| s.to_str()) else {

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,
@@ -61,6 +41,11 @@ pub(crate) fn scan_session_candidates_once(
     if matches!(provider, Provider::Copilot) {
         return Ok(copilot::scan_session_store(context));
     }
+    if matches!(provider, Provider::Claude | Provider::ClaudeCode)
+        && context.expected_session_id.is_some()
+    {
+        return Ok(claude::scan_expected_session(context));
+    }
 
     let candidates = common::candidate_session_files(provider, context)?;
     let mut out = common::parse_candidate_files(provider, context, candidates);
@@ -82,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`.
 //!