@team-agent/installer 0.4.0 → 0.4.2

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

@@ -357,16 +357,28 @@ fn backfill_leader_binding_for_delivery_view(
     let Some(obj) = state.as_object_mut() else {
         return;
     };
+    // Stage 3a (identity-boundary unified plan, architect direction
+    // 2026-06-23): route the in-memory backfill through the ownership
+    // repository. This in-memory promote is a delivery-view helper, NOT a
+    // persistent write — but funneling it through the same API as the
+    // canonical writers keeps the writer surface consistent for the
+    // acceptance contract (architect §6 verdict 2: zero `insert("team_owner")`
+    // outside ownership module). The repository call only touches the
+    // top-level (we pass empty team_key) so it matches the pre-3a backfill
+    // semantics exactly: top-level fields populated when missing, no
+    // teams-projection write.
+    let mut record = crate::state::ownership::OwnershipWrite::new();
     if !obj.contains_key("leader_receiver") {
         if let Some(receiver) = raw_state.get("leader_receiver").filter(|v| !v.is_null()) {
-            obj.insert("leader_receiver".to_string(), receiver.clone());
+            record = record.with_leader_receiver(receiver.clone());
         }
     }
     if !obj.contains_key("team_owner") {
         if let Some(owner) = raw_state.get("team_owner").filter(|v| !v.is_null()) {
-            obj.insert("team_owner".to_string(), owner.clone());
+            record = record.with_team_owner(owner.clone());
         }
     }
+    crate::state::ownership::write_owner(state, "", record);
 }
 
 fn can_backfill_top_level_leader_binding(raw_state: &serde_json::Value) -> bool {
@@ -459,8 +471,13 @@ fn owner_pane_is_dead(state: &serde_json::Value) -> bool {
     {
         return true;
     }
-    let Some(pane_id) = state
-        .get("team_owner")
+    // Stage 3a (identity-boundary unified plan, architect direction
+    // 2026-06-23): route owner read through the ownership repository.
+    // `state` here is already team-projected by the upstream
+    // `send_message` flow, so the empty-team-key path returns the same
+    // top-level owner the legacy direct read produced. Stage 5 will swap
+    // the data source under the repository.
+    let Some(pane_id) = crate::state::ownership::read_owner_value(state, "")
         .and_then(|owner| owner.get("pane_id"))
         .and_then(serde_json::Value::as_str)
         .filter(|pane| !pane.is_empty())

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

@@ -1062,6 +1062,24 @@ fn scan_session_candidates_once(
         }) {
             return Ok(vec![hit.clone()]);
         }
+        // Stage 1 (identity-boundary unified plan, architect direction
+        // 2026-06-23): for Claude/ClaudeCode with an expected session id,
+        // an exact-id miss MUST NOT fall back to same-cwd latest. Pre-fix
+        // the scanner returned every same-cwd candidate sorted with
+        // expected-first; with no exact match, that handed `frontend`'s
+        // transcript to `reviewer` in the AI-sync repro. Mirror Copilot's
+        // stricter contract: keep only candidates with a positive worker
+        // identity match (TEAM_AGENT_ID literal in the transcript head, or
+        // path-encoded agent_id). If none, return empty — capture stays
+        // pending/ambiguous, which is safer than misattribution.
+        if matches!(provider, Provider::Claude | Provider::ClaudeCode) {
+            let positive_only: Vec<CapturedSessionCandidate> = out
+                .iter()
+                .filter(|candidate| candidate.positive_agent_id_match || candidate.agent_path_match)
+                .cloned()
+                .collect();
+            return Ok(positive_only);
+        }
     }
     // E6 层1·B(主路径,交互式现实):cwd 匹配但盘上有多个 sibling transcript(claude 自生成,
     // 不采用预定 UUID)→ 用 spawn 时间窗唯一选:只留 mtime >= spawned_at 的候选,打破歧义。
@@ -1086,6 +1104,10 @@ fn scan_session_candidates_once(
             }
         }
     }
+    // Non-Claude / non-strict providers with an expected id but no exact
+    // match: order expected-first so the allocator's `unique_available_candidate`
+    // sees the deterministically preferred candidate. Claude/ClaudeCode took
+    // the strict positive-only return above and never reaches here.
     if let Some(expected) = context.expected_session_id.as_ref() {
         out.sort_by_key(|candidate| {
             candidate

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

@@ -194,6 +194,40 @@ where
             continue;
         };
         if let Some(candidate) = assignments.get(&item.agent_id) {
+            // Stage 1 (identity-boundary unified plan, architect direction
+            // 2026-06-23): defensive expected-id guard. The adapter scanner
+            // is the primary defence (Claude no longer falls back to same-
+            // cwd latest when expected_session_id is set), but the allocator
+            // also goes through a one-to-one global pass that could match a
+            // wrong candidate if the per-agent list still has stale entries.
+            // Refuse to write `session_id`/`rollout_path` when the candidate's
+            // session_id is set AND differs from the pending expected_session_id.
+            // Capture stays pending; the agent is marked ambiguous so the
+            // operator sees it.
+            let mismatch = item
+                .context
+                .expected_session_id
+                .as_ref()
+                .zip(candidate.captured.session_id.as_ref())
+                .is_some_and(|(expected, captured)| expected.as_str() != captured.as_str());
+            if mismatch {
+                report.ambiguous.push(AmbiguousSessionCapture {
+                    agent_id: item.agent_id.clone(),
+                    spawn_cwd: item.context.spawn_cwd.to_string_lossy().to_string(),
+                });
+                if finalize_ambiguous {
+                    agent_obj.insert(
+                        "attribution_ambiguous".to_string(),
+                        serde_json::json!(true),
+                    );
+                    agent_obj.insert(
+                        "captured_at".to_string(),
+                        serde_json::json!(chrono::Utc::now().to_rfc3339()),
+                    );
+                    report.changed = true;
+                }
+                continue;
+            }
             apply_captured_session(agent_obj, &candidate.captured);
             report.changed = true;
             report.assigned.push(item.agent_id);
@@ -499,7 +533,54 @@ fn allocate_session_candidates(
 ) -> (BTreeMap<String, CapturedSessionCandidate>, BTreeSet<String>) {
     let mut assignments = BTreeMap::new();
     let mut ambiguous = BTreeSet::new();
+
+    // Stage 1 amendment (architect direction 2026-06-23, S1-CAPTURE-002 fix):
+    // ExpectedSessionId pre-pass. For each pending agent that carries an
+    // `_pending_session_id`, the strongest possible binding is the candidate
+    // whose `session_id` exactly matches that expected id. Run this BEFORE
+    // the existing PositiveAgentId / PathAgentId / global one-to-one passes,
+    // because the global one-to-one pass uses
+    // `remaining_agents.zip(candidates.into_values())` (BTreeMap sorted by
+    // candidate-key, not by agent ownership) and can produce CROSS
+    // assignments (claude-a → claude-b's transcript and vice versa) when two
+    // pending agents both have expected ids but no PositiveAgentId/PathAgentId
+    // hint — those would be rejected by the mismatch guard at apply time,
+    // leaving both agents `attribution_ambiguous` instead of correctly
+    // bound. With this pre-pass the global one-to-one only ever sees agents
+    // that have NO expected id (or whose expected candidate is unavailable
+    // / collides), and the cross-assignment hazard is eliminated.
     for item in pending {
+        let Some(expected) = item.context.expected_session_id.as_ref() else {
+            continue;
+        };
+        let Some(agent_candidates) = candidates_by_agent.get(&item.agent_id) else {
+            continue;
+        };
+        let exact_matches: Vec<&CapturedSessionCandidate> = agent_candidates
+            .iter()
+            .filter(|candidate| {
+                candidate
+                    .captured
+                    .session_id
+                    .as_ref()
+                    .is_some_and(|sid| sid.as_str() == expected.as_str())
+            })
+            .filter(|candidate| !candidate_keys_collide(candidate, claimed))
+            .collect();
+        // Uniqueness requirement: only assign when the expected id maps to
+        // exactly one available candidate. Multiple matches or a colliding
+        // single match leave the agent for the ambiguity path below.
+        if exact_matches.len() == 1 {
+            let candidate = exact_matches[0].clone();
+            claimed.extend(captured_provider_session_keys(&candidate.captured));
+            assignments.insert(item.agent_id.clone(), candidate);
+        }
+    }
+
+    for item in pending {
+        if assignments.contains_key(&item.agent_id) {
+            continue;
+        }
         if let Some(candidate) = unique_available_candidate(
             candidates_by_agent.get(&item.agent_id),
             claimed,
@@ -711,12 +792,19 @@ fn parse_provider(raw: &str) -> Option<Provider> {
 #[cfg(test)]
 pub(crate) mod test_support {
     use super::*;
+    use std::sync::Arc;
 
     #[derive(Clone)]
     pub(crate) struct CaptureCandidatesAdapter {
         provider: Provider,
         fail_agent_id: Option<String>,
         error: String,
+        /// Stage 1 amendment test support (architect direction 2026-06-23):
+        /// per-agent candidate map. When set, the adapter returns the mapped
+        /// candidates for `context.agent_id` instead of an empty list. Lets
+        /// the allocator-level test inject expected-id candidates for two
+        /// pending agents and observe cross-assignment regressions.
+        candidates_by_agent: Option<Arc<BTreeMap<String, Vec<CapturedSessionCandidate>>>>,
     }
 
     impl CaptureCandidatesAdapter {
@@ -725,8 +813,17 @@ pub(crate) mod test_support {
                 provider,
                 fail_agent_id: fail_agent_id.map(str::to_string),
                 error: error.to_string(),
+                candidates_by_agent: None,
             }
         }
+
+        pub(crate) fn with_candidates(
+            mut self,
+            candidates_by_agent: BTreeMap<String, Vec<CapturedSessionCandidate>>,
+        ) -> Self {
+            self.candidates_by_agent = Some(Arc::new(candidates_by_agent));
+            self
+        }
     }
 
     impl ProviderAdapter for CaptureCandidatesAdapter {
@@ -802,6 +899,11 @@ pub(crate) mod test_support {
             if self.fail_agent_id.as_deref() == Some(context.agent_id.as_str()) {
                 return Err(ProviderError::Io(self.error.clone()));
             }
+            if let Some(map) = self.candidates_by_agent.as_ref() {
+                if let Some(candidates) = map.get(&context.agent_id) {
+                    return Ok(candidates.clone());
+                }
+            }
             Ok(Vec::new())
         }
 
@@ -1007,4 +1109,130 @@ mod u1_tests {
         });
         assert!(!agent_session_complete(&agent_no_path));
     }
+
+    /// Stage 1 amendment regression (architect direction 2026-06-23,
+    /// S1-CAPTURE-002): two pending agents, each with a distinct
+    /// `_pending_session_id`. Each agent's candidate list contains ONLY its
+    /// own expected transcript (no positive worker identity hint, no path
+    /// agent id hint — the file basename is just a UUID). Pre-fix, the
+    /// allocator's `allocate_global_one_to_one` zipped agents (sorted by
+    /// agent_id) with candidates (sorted by candidate-key), producing CROSS
+    /// assignments that the mismatch guard then rejected — leaving both
+    /// agents `attribution_ambiguous`. Post-fix, the ExpectedSessionId
+    /// pre-pass binds each agent to its own expected candidate before any
+    /// global one-to-one runs.
+    #[test]
+    fn capture_allocator_expected_session_id_binds_each_worker_to_its_own_transcript() {
+        use crate::provider::{CaptureVia, Confidence, RolloutPath};
+        let dir = std::env::temp_dir().join(format!(
+            "ta-stage1-allocator-{}",
+            std::process::id()
+        ));
+        std::fs::create_dir_all(&dir).unwrap();
+        let rollout_a = dir.join("9a2d1668.jsonl");
+        let rollout_b = dir.join("3e824e89.jsonl");
+        std::fs::write(&rollout_a, b"{}\n").unwrap();
+        std::fs::write(&rollout_b, b"{}\n").unwrap();
+        let candidate_a = CapturedSessionCandidate {
+            captured: CapturedSession {
+                session_id: Some(SessionId::new(
+                    "9a2d1668-8987-4c36-8bde-a5135b10da02",
+                )),
+                rollout_path: Some(RolloutPath::new(rollout_a.clone())),
+                captured_via: CaptureVia::FsWatch,
+                attribution_confidence: Confidence::High,
+                spawn_cwd: dir.clone(),
+            },
+            // Critical: no positive worker identity hint. Pre-fix this is
+            // exactly the shape that fell through to global one-to-one.
+            positive_agent_id_match: false,
+            agent_path_match: false,
+        };
+        let candidate_b = CapturedSessionCandidate {
+            captured: CapturedSession {
+                session_id: Some(SessionId::new(
+                    "3e824e89-25ac-4b3f-b272-b4f733f6403c",
+                )),
+                rollout_path: Some(RolloutPath::new(rollout_b.clone())),
+                captured_via: CaptureVia::FsWatch,
+                attribution_confidence: Confidence::High,
+                spawn_cwd: dir.clone(),
+            },
+            positive_agent_id_match: false,
+            agent_path_match: false,
+        };
+        let mut candidates_by_agent: BTreeMap<String, Vec<CapturedSessionCandidate>> =
+            BTreeMap::new();
+        candidates_by_agent.insert("claude-a".to_string(), vec![candidate_a.clone()]);
+        candidates_by_agent.insert("claude-b".to_string(), vec![candidate_b.clone()]);
+
+        let cwd_str = dir.to_string_lossy().to_string();
+        let mut state = serde_json::json!({
+            "agents": {
+                "claude-a": {
+                    "provider": "claude",
+                    "status": "running",
+                    "spawn_cwd": cwd_str,
+                    "_pending_session_id": "9a2d1668-8987-4c36-8bde-a5135b10da02"
+                },
+                "claude-b": {
+                    "provider": "claude",
+                    "status": "running",
+                    "spawn_cwd": cwd_str,
+                    "_pending_session_id": "3e824e89-25ac-4b3f-b272-b4f733f6403c"
+                }
+            }
+        });
+        let adapter = test_support::CaptureCandidatesAdapter::new(Provider::Claude, None, "")
+            .with_candidates(candidates_by_agent);
+        let mut adapter_for = move |_provider| {
+            Box::new(adapter.clone()) as Box<dyn ProviderAdapter>
+        };
+
+        let report = capture_missing_provider_sessions_once(&mut state, &mut adapter_for, true, 0)
+            .expect("allocator pass should succeed");
+
+        // ExpectedSessionId pre-pass must bind each agent to its own
+        // expected transcript. No cross-assignment, no ambiguous mark.
+        let agents = state["agents"].as_object().expect("agents object");
+        assert_eq!(
+            agents["claude-a"]["session_id"].as_str(),
+            Some("9a2d1668-8987-4c36-8bde-a5135b10da02"),
+            "Stage 1 fix: claude-a must bind to its own expected transcript; \
+             state.claude-a={}",
+            agents["claude-a"]
+        );
+        assert_eq!(
+            agents["claude-b"]["session_id"].as_str(),
+            Some("3e824e89-25ac-4b3f-b272-b4f733f6403c"),
+            "Stage 1 fix: claude-b must bind to its own expected transcript; \
+             state.claude-b={}",
+            agents["claude-b"]
+        );
+        assert!(
+            agents["claude-a"]
+                .get("attribution_ambiguous")
+                .is_none_or(|v| v.as_bool() != Some(true)),
+            "Stage 1 fix: claude-a must NOT be flagged ambiguous after the \
+             expected-id pre-pass bound it; state.claude-a={}",
+            agents["claude-a"]
+        );
+        assert!(
+            agents["claude-b"]
+                .get("attribution_ambiguous")
+                .is_none_or(|v| v.as_bool() != Some(true)),
+            "Stage 1 fix: claude-b must NOT be flagged ambiguous; \
+             state.claude-b={}",
+            agents["claude-b"]
+        );
+        assert_eq!(
+            report.ambiguous.len(),
+            0,
+            "Stage 1 fix: capture report must record zero ambiguous; report={report:?}"
+        );
+
+        let _ = std::fs::remove_file(&rollout_a);
+        let _ = std::fs::remove_file(&rollout_b);
+        let _ = std::fs::remove_dir(&dir);
+    }
 }

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

@@ -272,9 +272,14 @@ pub fn populate_team_owner_from_env(
         "claimed_at": now_iso,
         "claimed_via": source,
     });
-    if let Some(o) = state.as_object_mut() {
-        o.insert("team_owner".to_string(), owner.clone());
-    }
+    // Stage 3a (identity-boundary unified plan, architect direction 2026-06-23):
+    // route the in-memory team_owner write through the ownership repository.
+    // Net behaviour preserved: still writes top-level (legacy dual-write);
+    // 3b/3c/3d will remove the read-side projection promote, persist
+    // copy-back, and finally the top-level write.
+    let record = crate::state::ownership::OwnershipWrite::new()
+        .with_team_owner(owner.clone());
+    crate::state::ownership::write_owner(state, &key, record);
     Ok(Some(owner))
 }
 
@@ -345,10 +350,13 @@ pub fn apply_first_time_leader_binding(
         "claimed_at": now_iso,
         "claimed_via": source,
     });
-    if let Some(o) = state.as_object_mut() {
-        o.insert("team_owner".to_string(), owner);
-        o.insert("leader_receiver".to_string(), receiver.clone());
-    }
+    // Stage 3a: route through ownership repository.
+    let team_key = team_state_key(state);
+    let record = crate::state::ownership::OwnershipWrite::new()
+        .with_team_owner(owner)
+        .with_leader_receiver(receiver.clone())
+        .with_owner_epoch(0);
+    crate::state::ownership::write_owner(state, &team_key, record);
     json!({ "ok": true, "pane": pane_info, "warning": null, "first_time": true })
 }
 
@@ -560,6 +568,12 @@ mod tests {
 
     #[test]
     fn populate_team_owner_seed_and_skip() {
+        // Stage 3d (identity-boundary unified plan, architect direction
+        // 2026-06-23): after the top-level dual-write was dropped, owner
+        // lives only at `state.teams.<team_key>.team_owner`. The test now
+        // resolves through the ownership repository so the precedence rule
+        // (teams.<key> first, then legacy top-level when team_state_key
+        // matches) is the single source of truth.
         let e_with_pane = env(&[
             ("TEAM_AGENT_LEADER_PANE_ID", "%9"),
             ("TEAM_AGENT_LEADER_PROVIDER", "codex"),
@@ -573,14 +587,21 @@ mod tests {
             &json!({"pane_id": "%9", "provider": "codex", "machine_fingerprint": "fp",
                     "leader_session_uuid": "u1", "claimed_at": "TS", "claimed_via": "autopopulate"}),
         );
-        same_repr(&state["team_owner"], &owner);
+        // The canonical key is whatever team_state_key derives for the
+        // empty state (fallback "current" in legacy single-team flow).
+        let team_key = crate::state::projection::team_state_key(&state);
+        let repo_owner = crate::state::ownership::read_owner_value(&state, &team_key)
+            .expect("Stage 3d: owner readable via ownership repository");
+        same_repr(repo_owner, &owner);
 
         // 无 pane_id → None,不写 owner。
         let mut state2 = json!({});
         assert!(populate_team_owner_from_env(&mut state2, "x", &env(&[]), "TS").unwrap().is_none());
-        assert!(state2.get("team_owner").is_none());
+        let team_key2 = crate::state::projection::team_state_key(&state2);
+        assert!(crate::state::ownership::read_owner_value(&state2, &team_key2).is_none());
 
-        // 已有 team_owner(缺 uuid)→ 迁移补 uuid 后返回。
+        // 已有 team_owner(缺 uuid)→ 迁移补 uuid 后返回。Legacy top-level shape
+        // still recognized (read precedence supports the migration window).
         let mut state3 = json!({"team_owner": {"pane_id": "%1", "machine_fingerprint": "fp"}, "session_name": "s"});
         let o3 = populate_team_owner_from_env(&mut state3, "x", &env(&[("USER", "u")]), "TS").unwrap().unwrap();
         assert_eq!(o3["leader_session_uuid"].as_str().unwrap().len(), 32);
@@ -589,6 +610,10 @@ mod tests {
     #[test]
     #[serial(env)]
     fn apply_first_time_binding_success_writes_state() {
+        // Stage 3d (identity-boundary unified plan, architect direction
+        // 2026-06-23): canonical owner now lives at
+        // `state.teams.<team_key>.{team_owner,leader_receiver}`. Read
+        // through the ownership repository.
         let _env = EnvUnsetGuard::unset(&["TMUX", "TMUX_PANE"]);
         let ws = temp_ws();
         let now = "2026-06-02T09:17:59.994383+00:00";
@@ -598,13 +623,18 @@ mod tests {
         let pane = json!({"pane_current_command": "codex", "pane_current_path": ws.to_string_lossy()});
         let r = apply_first_time_leader_binding(&ws, &mut state, &mut receiver, &pane, &identity, "claim", now, |_c, _p| true);
         same_repr(&r, &json!({"ok": true, "pane": pane, "warning": null, "first_time": true}));
+        let team_key = crate::state::projection::team_state_key(&state);
+        let team_owner = crate::state::ownership::read_owner_value(&state, &team_key)
+            .expect("Stage 3d: team_owner reachable via repository");
         same_repr(
-            &state["team_owner"],
+            team_owner,
             &json!({"pane_id": "%9", "provider": "codex", "machine_fingerprint": "fpX",
                     "leader_session_uuid": "uuidX", "owner_epoch": 0, "claimed_at": now, "claimed_via": "claim"}),
         );
+        // leader_receiver lives at the same canonical location.
+        let leader_receiver = state["teams"][&team_key]["leader_receiver"].clone();
         same_repr(
-            &state["leader_receiver"],
+            &leader_receiver,
             &json!({"pane_id": "%9", "provider": "codex", "leader_session_uuid": "uuidX",
                     "machine_fingerprint": "fpX", "owner_epoch": 0}),
         );

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

@@ -0,0 +1,134 @@
+//! Stage 0 of the identity-boundary unified plan (architect direction
+//! 2026-06-23): `SessionAttributionKey`.
+//!
+//! Pure additive: nobody constructs this type yet. Stage 1 (Claude strict
+//! capture) starts populating it inside `CaptureSessionContext`; Stage 4
+//! (CLI/DB scope gate) starts using it as the DB/event filter key.
+//!
+//! Why a struct, not a tuple:
+//! - The four fields are not interchangeable: `provider` selects the
+//!   tombstone/claimed-session table, `team_key` is the multi-team boundary,
+//!   `agent_id` is the worker identity inside a team, `session_id` is the
+//!   provider-issued transcript identity.
+//! - The architect's verdict §1 names this exact shape as the "shared
+//!   identity primitive" that owner / capture / multi-team all need so they
+//!   don't drift into per-module ad-hoc keys.
+//!
+//! Single-team behaviour: `team_key` is still populated (from
+//! `state::projection::team_state_key` or the same selector path Stage 0
+//! introduces). The key is invariant — capture/owner/CLI all read it from
+//! the same source.
+
+use crate::model::enums::Provider;
+
+/// The canonical identity of a "this worker owns this provider transcript"
+/// claim. Stage 1 + Stage 4 will both store and compare via this struct.
+///
+/// All four fields are non-empty by construction (the constructor refuses
+/// empty `team_key`, `agent_id`, or `session_id` — those would collapse
+/// distinct sessions into one).
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct SessionAttributionKey {
+    provider: Provider,
+    team_key: String,
+    agent_id: String,
+    session_id: String,
+}
+
+impl SessionAttributionKey {
+    pub fn new(
+        provider: Provider,
+        team_key: impl Into<String>,
+        agent_id: impl Into<String>,
+        session_id: impl Into<String>,
+    ) -> Option<Self> {
+        let team_key = team_key.into();
+        let agent_id = agent_id.into();
+        let session_id = session_id.into();
+        if team_key.is_empty() || agent_id.is_empty() || session_id.is_empty() {
+            return None;
+        }
+        Some(Self {
+            provider,
+            team_key,
+            agent_id,
+            session_id,
+        })
+    }
+
+    pub fn provider(&self) -> Provider {
+        self.provider
+    }
+
+    pub fn team_key(&self) -> &str {
+        &self.team_key
+    }
+
+    pub fn agent_id(&self) -> &str {
+        &self.agent_id
+    }
+
+    pub fn session_id(&self) -> &str {
+        &self.session_id
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn refuses_empty_team_key() {
+        assert!(
+            SessionAttributionKey::new(Provider::Claude, "", "agent_a", "sess_1").is_none()
+        );
+    }
+
+    #[test]
+    fn refuses_empty_agent_id() {
+        assert!(
+            SessionAttributionKey::new(Provider::Claude, "alpha", "", "sess_1").is_none()
+        );
+    }
+
+    #[test]
+    fn refuses_empty_session_id() {
+        assert!(
+            SessionAttributionKey::new(Provider::Claude, "alpha", "agent_a", "").is_none()
+        );
+    }
+
+    #[test]
+    fn accepts_well_formed_key_and_preserves_fields() {
+        let key = SessionAttributionKey::new(
+            Provider::Claude,
+            "alpha",
+            "reviewer",
+            "36dd1d1a-2766-4636-856c-03f14a4bb803",
+        )
+        .unwrap();
+        assert_eq!(key.provider(), Provider::Claude);
+        assert_eq!(key.team_key(), "alpha");
+        assert_eq!(key.agent_id(), "reviewer");
+        assert_eq!(key.session_id(), "36dd1d1a-2766-4636-856c-03f14a4bb803");
+    }
+
+    /// Same provider + agent_id + session_id but different team_key → distinct
+    /// identity. This is the multi-team isolation invariant the unified plan
+    /// requires (architect §1 cross point: tombstone/claimed by full
+    /// (provider, team_key, agent_id, session_id) tuple).
+    #[test]
+    fn different_team_keys_produce_different_keys() {
+        let alpha = SessionAttributionKey::new(Provider::Claude, "alpha", "reviewer", "s1").unwrap();
+        let beta = SessionAttributionKey::new(Provider::Claude, "beta", "reviewer", "s1").unwrap();
+        assert_ne!(alpha, beta);
+    }
+
+    /// Same team but different agent_id → distinct (per-worker isolation).
+    #[test]
+    fn different_agent_ids_produce_different_keys() {
+        let reviewer = SessionAttributionKey::new(Provider::Claude, "alpha", "reviewer", "s1").unwrap();
+        let frontend = SessionAttributionKey::new(Provider::Claude, "alpha", "frontend", "s1").unwrap();
+        assert_ne!(reviewer, frontend);
+    }
+}

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

@@ -15,7 +15,15 @@
 #![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
 
 pub mod identity;
+// Stage 0 of identity-boundary unified plan (architect direction 2026-06-23):
+// shared identity primitives. Pure additive — Stage 1+ consume these.
+pub mod identity_keys;
 pub mod owner_gate;
+// Stage 2 of identity-boundary unified plan: single read entry point for
+// `team_owner` lookups. Stage 3 will migrate writers; Stage 5 will swap
+// the data source to per-team canonical state without touching call sites.
+pub mod ownership;
+pub mod paths;
 pub mod persist;
 pub mod projection;
 pub mod selector;

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

@@ -39,13 +39,23 @@ pub struct CallerIdentity {
 
 /// `check_team_owner`(`state.py:366`)的纯判定版:caller 身份 + 是否有 TEAM_AGENT_ID + liveness 注入。
 /// 返回 `None`=允许(own / 无 owner / 死 owner pane 可接管);`Some(dict)`=拒绝(team_owner_mismatch)。
+///
+/// Stage 2 (identity-boundary unified plan, architect direction 2026-06-23):
+/// the owner is now looked up through `state::ownership::read_owner_value`
+/// instead of `state::projection::read_owner` directly. The two are
+/// equivalent today for the gate's `None` (empty team_key) path — both
+/// resolve to top-level `state.team_owner` — but routing through the
+/// repository means Stage 5 can swap the data source (per-team canonical
+/// `state.json`) without touching this gate. The empty-team-key argument
+/// preserves the pre-Stage-2 shape: gate callers feed an
+/// already-team-projected state and expect top-level reads.
 pub fn check_team_owner(
     state: &Value,
     caller: &CallerIdentity,
     has_team_agent_id: bool,
     liveness: &dyn PaneLivenessProbe,
 ) -> Option<Value> {
-    let owner = crate::state::projection::read_owner(state, None)?;
+    let owner = crate::state::ownership::read_owner_value(state, "")?;
     if !owner.is_object() || owner.as_object().is_none_or(serde_json::Map::is_empty) {
         return None;
     }