@team-agent/installer 0.4.1 → 0.4.2

package/crates/team-agent/src/cli/tests/lane_c.rs

@@ -196,7 +196,7 @@ use super::*;
     #[test]
     fn inbox_golden_shape_is_agent_id_and_since_not_agent_limit() {
         let ws = tmp_workspace();
-        let v = status_port::inbox(&ws, "alpha", 20, None, true).expect("inbox");
+        let v = status_port::inbox(&ws, "alpha", 20, None, true, None).expect("inbox");
         let obj = v.as_object().expect("inbox dict");
         let order: Vec<&str> = obj.keys().map(String::as_str).collect();
         assert_eq!(

package/crates/team-agent/src/cli/tests/leader_watch.rs

@@ -167,9 +167,11 @@ use super::*;
         assert_eq!(r.status, crate::leader::LeaseStatus::Claimed);
         assert_eq!(r.owner_epoch, Some(crate::model::ids::OwnerEpoch(3)));
         assert_eq!(r.bound_pane_id, Some(caller.clone()));
-        assert_eq!(state["leader_receiver"]["pane_id"], json!("%5"));
-        assert_eq!(state["team_owner"]["pane_id"], json!("%5"));
-        assert_eq!(state["team_owner"]["owner_epoch"], json!(3));
+        // Stage 3d: canonical owner/receiver at teams.<team_key>.
+        let team_key = crate::state::projection::team_state_key(&state);
+        assert_eq!(state["teams"][&team_key]["leader_receiver"]["pane_id"], json!("%5"));
+        assert_eq!(state["teams"][&team_key]["team_owner"]["pane_id"], json!("%5"));
+        assert_eq!(state["teams"][&team_key]["team_owner"]["owner_epoch"], json!(3));
     }
 
     struct LeaderPortSeededLiveness {

package/crates/team-agent/src/cli/tests/main_preserved.rs

@@ -186,7 +186,7 @@ fn seed_team_spec(ws: &std::path::Path) {
         let mid = store
             .create_message(None, "leader", "w1", "hello w1", None, true, None)
             .unwrap();
-        let v = status_port::inbox(&ws, "w1", 20, None, true).expect("inbox");
+        let v = status_port::inbox(&ws, "w1", 20, None, true, None).expect("inbox");
         let messages = v["messages"].as_array().expect("messages array");
         assert_eq!(
             messages.len(),
@@ -217,7 +217,7 @@ fn seed_team_spec(ws: &std::path::Path) {
         store.create_message(None, "leader", "w1", "to w1", None, true, None).unwrap();
         store.create_message(None, "w1", "leader", "from w1", None, true, None).unwrap();
         store.create_message(None, "leader", "w2", "unrelated to w2", None, true, None).unwrap();
-        let v = status_port::inbox(&ws, "w1", 20, None, true).expect("inbox");
+        let v = status_port::inbox(&ws, "w1", 20, None, true, None).expect("inbox");
         let messages = v["messages"].as_array().expect("messages array");
         let mut contents: Vec<String> =
             messages.iter().map(|m| m["content"].as_str().unwrap().to_string()).collect();
@@ -343,6 +343,7 @@ fn seed_team_spec(ws: &std::path::Path) {
             workspace: ws.clone(),
             timeout: 0.0,
             json: true,
+            team: None,
         }).expect("wait-ready"));
         assert_eq!(value["ok"], json!(false), "wait-ready must not fake success before workers are ready");
         assert_eq!(value.pointer("/readiness/ready"), Some(&json!(false)));
@@ -386,6 +387,7 @@ fn seed_team_spec(ws: &std::path::Path) {
             workspace: ws.clone(),
             timeout: 0.0,
             json: true,
+            team: None,
         }).expect("wait-ready"));
         assert_eq!(
             value.pointer("/readiness/mcp_ready"),
@@ -571,6 +573,7 @@ fn seed_team_spec(ws: &std::path::Path) {
                 workspace: ws.clone(),
                 result_file: None,
                 json: true,
+                team: None,
             })
             .unwrap(),
         );
@@ -611,6 +614,7 @@ fn seed_team_spec(ws: &std::path::Path) {
                 workspace: ws.clone(),
                 alert_type: None,
                 json: true,
+                team: None,
             })
             .unwrap(),
         );
@@ -637,6 +641,7 @@ fn seed_team_spec(ws: &std::path::Path) {
             cmd_stuck_list(&StuckListArgs {
                 workspace: ws.clone(),
                 json: true,
+                team: None,
             })
             .unwrap(),
         );
@@ -646,6 +651,26 @@ fn seed_team_spec(ws: &std::path::Path) {
             "stuck-list must read the persisted state mirror, not return a hard-coded empty list"
         );
     }
+
+    #[test]
+    fn stuck_cancel_explicit_team_is_rejected_until_backend_is_scoped() {
+        let ws = tmp_workspace();
+        seed_collect_state(&ws);
+        let err = cmd_stuck_cancel(&StuckCancelArgs {
+            agent: "fake_impl".to_string(),
+            workspace: ws.clone(),
+            alert_type: None,
+            json: true,
+            team: Some("current".to_string()),
+        })
+        .expect_err("explicit --team must not silently write global stuck suppression");
+        assert!(
+            err.to_string().contains("not supported yet"),
+            "stuck-cancel --team must be an explicit refusal until backend supports scoped writes; got {err}"
+        );
+        let _ = std::fs::remove_dir_all(&ws);
+    }
+
     #[test]
     fn stuck_cancel_invalid_alert_type_is_rejected() {
         let ws = tmp_workspace();
@@ -717,6 +742,7 @@ fn seed_team_spec(ws: &std::path::Path) {
                 status: "done".to_string(),
                 summary: Some("manual repair accepted".to_string()),
                 json: true,
+                team: None,
             })
             .expect("repair-state should not fail on a valid runtime state"),
         );

package/crates/team-agent/src/cli/tests/peer_allow.rs

@@ -43,6 +43,7 @@ fn app_call(ws: &std::path::Path, a: &str, b: &str) -> CmdResult {
         b: b.to_string(),
         workspace: ws.to_path_buf(),
         json: false,
+        team: None,
     })
     .expect("allow-peer-talk is a compat-noop and must not error")
 }
@@ -135,3 +136,21 @@ fn allow_peer_talk_unknown_agents_succeed_no_validation() {
     );
     let _ = std::fs::remove_dir_all(&ws);
 }
+
+#[test]
+fn allow_peer_talk_explicit_team_is_rejected_until_backend_is_scoped() {
+    let ws = tmp_workspace();
+    let err = cmd_allow_peer_talk(&AllowPeerTalkArgs {
+        a: "alpha".to_string(),
+        b: "bravo".to_string(),
+        workspace: ws.clone(),
+        json: true,
+        team: Some("current".to_string()),
+    })
+    .expect_err("explicit --team must not silently write the global peer allowlist");
+    assert!(
+        err.to_string().contains("not supported yet"),
+        "allow-peer-talk --team must be an explicit refusal until backend supports scoped writes; got {err}"
+    );
+    let _ = std::fs::remove_dir_all(&ws);
+}

package/crates/team-agent/src/cli/tests/repair_state_byte_lock.rs

@@ -130,9 +130,54 @@ fn repair_args(
         status: status.to_string(),
         summary: summary.map(str::to_string),
         json,
+        team: None,
     }
 }
 
+fn team_repair_state(ws: &std::path::Path, team: &str) -> serde_json::Value {
+    json!({
+        "active_team_key": team,
+        "status": "alive",
+        "spec_path": ws.join(".team").join("runtime").join(team).join("team.spec.yaml").to_string_lossy(),
+        "session_name": format!("team-agent-{team}"),
+        "leader": {"id": "leader"},
+        "agents": {"fake_impl": {"status": "stopped", "provider": "fake"}},
+        "tasks": [{
+            "id": "task_impl",
+            "title": format!("{team} implementation"),
+            "type": "implementation",
+            "assignee": null,
+            "deps": [],
+            "acceptance": ["fake result collected"],
+            "status": "pending"
+        }]
+    })
+}
+
+fn seed_two_team_repair_workspace(ws: &std::path::Path) {
+    std::fs::create_dir_all(ws.join(".team").join("logs")).unwrap();
+    for team in ["alpha", "beta"] {
+        let spec_dir = ws.join(".team").join("runtime").join(team);
+        std::fs::create_dir_all(&spec_dir).unwrap();
+        std::fs::write(
+            spec_dir.join("team.spec.yaml"),
+            REPAIR_SPEC_TEMPLATE.replace("__WS__", &ws.to_string_lossy()),
+        )
+        .unwrap();
+    }
+    crate::state::persist::save_runtime_state(
+        ws,
+        &json!({
+            "active_team_key": "alpha",
+            "teams": {
+                "alpha": team_repair_state(ws, "alpha"),
+                "beta": team_repair_state(ws, "beta"),
+            }
+        }),
+    )
+    .unwrap();
+}
+
 // Golden source:
 // - cli/parser.py:303-310 registers `repair-state --workspace --task --assignee --status --summary --json`.
 // - cli/commands.py:196-203 delegates all five args to `runtime.repair_state`.
@@ -248,6 +293,33 @@ fn repair_state_rejects_status_outside_task_statuses() {
     let _ = std::fs::remove_dir_all(&ws);
 }
 
+#[test]
+fn repair_state_explicit_team_updates_selected_team_not_active_team() {
+    let ws = tmp_workspace();
+    seed_two_team_repair_workspace(&ws);
+    let mut args = repair_args(&ws, "done", Some("patched beta"), true);
+    args.team = Some("beta".to_string());
+
+    let cmd = cmd_repair_state(&args).expect("repair-state --team beta should update beta");
+    assert_eq!(cmd.exit, ExitCode::Ok);
+    let state = crate::state::persist::load_runtime_state(&ws).unwrap();
+    assert_eq!(
+        state["teams"]["alpha"]["tasks"][0]["status"],
+        json!("pending"),
+        "repair-state --team beta must not mutate active/default alpha"
+    );
+    assert_eq!(
+        state["teams"]["beta"]["tasks"][0]["status"],
+        json!("done"),
+        "repair-state must consume args.team and update beta"
+    );
+    assert_eq!(
+        state["teams"]["beta"]["tasks"][0]["last_result_summary"],
+        json!("patched beta")
+    );
+    let _ = std::fs::remove_dir_all(&ws);
+}
+
 // CONTRACT (real-machine repair_state product FAIL): rt-host-d ran `repair-state --task rp1 --status done`
 // in a quick-start workspace whose spec lives in a teamdir (state.spec_path -> <ws>/teamdir/team.spec.yaml),
 // NOT at <ws>/team.spec.yaml. Rust cmd_repair_state calls load_team_spec(workspace) which HARDCODES

package/crates/team-agent/src/cli/tests/run_delegation.rs

@@ -205,7 +205,6 @@ fn current_uid() -> Option<String> {
             name: None,
             team_id: None,
             yes: true,
-            fresh: false,
             no_display: false,
             json: true,
         };
@@ -240,7 +239,6 @@ fn current_uid() -> Option<String> {
             name: None,
             team_id: None,
             yes: false,
-            fresh: false,
             no_display: false,
             json: true,
         };
@@ -339,7 +337,7 @@ fn current_uid() -> Option<String> {
         crate::coordinator::write_coordinator_metadata(&wp, me, crate::coordinator::MetadataSource::Boot).unwrap();
         std::fs::write(crate::coordinator::coordinator_pid_path(&wp), me.to_string()).unwrap();
 
-        let args = StatusArgs { agent: None, workspace: ws, detail: true, summary: false, json: true };
+        let args = StatusArgs { agent: None, workspace: ws, detail: true, summary: false, json: true, team: None };
         let r = cmd_status(&args).expect("cmd_status");
         let value = match r.output {
             CmdOutput::Json(v) => v,

package/crates/team-agent/src/cli/tests/status_send.rs

@@ -268,6 +268,7 @@ use super::*;
             detail: false,
             summary: false,
             json: false,
+            team: None,
         };
 
         let r = cmd_status_for_team(&args, None).expect("status");

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

@@ -86,7 +86,7 @@ impl CliError {
             payload.session_name = Some(session.clone());
             if command == "quick-start" {
                 payload.action = format!(
-                    "tmux session `{session}` already exists. It may be your own existing team. To resume it use `team-agent restart` (NOT --fresh, which discards context). Only if you want a separate team, change `name:` in TEAM.md and run quick-start again. Never terminate existing tmux sessions from quick-start."
+                    "tmux session `{session}` already exists. It may be your own existing team. To resume it use `team-agent restart`. If recovery is impossible, use `team-agent restart --allow-fresh` only after explicit context-loss consent. Only if you want a separate team, change `name:` in TEAM.md and run quick-start again. Never terminate existing tmux sessions from quick-start."
                 );
                 payload.next_actions = Some(vec![
                     "If this is your existing team, resume it with `team-agent restart`.".to_string(),
@@ -270,9 +270,13 @@ pub struct QuickStartArgs {
     pub name: Option<String>,
     pub team_id: Option<String>,
     pub yes: bool,
-    pub fresh: bool,
     pub no_display: bool,
     pub json: bool,
+    // Stage QR (quick-start/restart separation, design doc
+    // .team/artifacts/quickstart-restart-separation-design.md): the
+    // `fresh` field is intentionally REMOVED. Reset semantics now live
+    // exclusively on restart (`restart --allow-fresh`) and must be
+    // user-confirmed. quick-start is now an initial-creation-only verb.
 }
 
 /// `init`(`parser.py` bootstrap verb)。
@@ -355,6 +359,9 @@ pub struct AllowPeerTalkArgs {
     pub b: String,
     pub workspace: PathBuf,
     pub json: bool,
+    /// Parsed but rejected until peer allowlist storage grows a team-scoped
+    /// backend column.
+    pub team: Option<String>,
 }
 
 /// `status`(`parser.py:182`)。`--summary`/`--json`/`--detail` 三态(summary xor json,见 `cmd_status`)。
@@ -365,6 +372,9 @@ pub struct StatusArgs {
     pub detail: bool,
     pub summary: bool,
     pub json: bool,
+    /// Stage 4: explicit `--team` scope (read-only command; multi-team
+    /// workspaces use this for filtering, not for refusal).
+    pub team: Option<String>,
 }
 
 /// `watch`(`parser.py:190`)。无 `--json`(纯 stream 到 SystemExit)。
@@ -380,6 +390,8 @@ pub struct ApprovalsArgs {
     pub agent: Option<String>,
     pub workspace: PathBuf,
     pub json: bool,
+    /// Stage 4: explicit `--team` scope.
+    pub team: Option<String>,
 }
 
 /// `inbox`(`parser.py:217`)。`--since` ISO8601(claim-leader inbox_hint 复用)。
@@ -390,6 +402,8 @@ pub struct InboxArgs {
     pub limit: usize,
     pub since: Option<String>,
     pub json: bool,
+    /// Stage 4: explicit `--team` scope.
+    pub team: Option<String>,
 }
 
 /// `takeover`(`parser.py:242`)。`--confirm` 必需(覆写 recorded team_owner)。
@@ -521,6 +535,8 @@ pub struct RemoveAgentArgs {
 pub struct StuckListArgs {
     pub workspace: PathBuf,
     pub json: bool,
+    /// Stage 4: explicit `--team` scope (read-only enumeration).
+    pub team: Option<String>,
 }
 
 /// `stuck-cancel`(`parser.py:429`)。`--alert-type` ∈ {stuck, idle_fallback, all},默认 stuck。
@@ -531,6 +547,9 @@ pub struct StuckCancelArgs {
     /// `None` 表 `all`(展开全集);`Some(AlertType)` 表单类型。
     pub alert_type: Option<AlertType>,
     pub json: bool,
+    /// Parsed but rejected until stuck suppression storage grows a team-scoped
+    /// backend selector.
+    pub team: Option<String>,
 }
 
 /// `acknowledge-idle`(`parser.py:436`)。
@@ -573,6 +592,8 @@ pub enum DoctorGate {
 pub struct SessionsArgs {
     pub workspace: PathBuf,
     pub json: bool,
+    /// Stage 4: explicit `--team` scope (read-only enumeration).
+    pub team: Option<String>,
 }
 
 /// `validate [spec=team.spec.yaml] --json`(`parser.py:120`)。
@@ -608,6 +629,10 @@ pub struct CollectArgs {
     pub workspace: PathBuf,
     pub result_file: Option<PathBuf>,
     pub json: bool,
+    /// Stage 4: explicit `--team` scope. Destructive (consumes result
+    /// envelopes); CLI dispatch refuses bare invocation in a
+    /// multi-alive-team workspace.
+    pub team: Option<String>,
 }
 
 /// `settle`(`parser.py:177`)。
@@ -631,6 +656,10 @@ pub struct RepairStateArgs {
     pub status: String,
     pub summary: Option<String>,
     pub json: bool,
+    /// Stage 4: explicit `--team` scope. Destructive (rewrites task state);
+    /// CLI dispatch refuses bare invocation in a multi-alive-team
+    /// workspace.
+    pub team: Option<String>,
 }
 
 /// `diagnose`(`parser.py:298`) runtime health report, distinct from `doctor`.
@@ -638,6 +667,8 @@ pub struct RepairStateArgs {
 pub struct DiagnoseArgs {
     pub workspace: PathBuf,
     pub json: bool,
+    /// Stage 4: explicit `--team` scope (read-only health report).
+    pub team: Option<String>,
 }
 
 /// `preflight`(`parser.py:160`)。
@@ -653,6 +684,8 @@ pub struct WaitReadyArgs {
     pub workspace: PathBuf,
     pub timeout: f64,
     pub json: bool,
+    /// Stage 4: explicit `--team` scope (read-only readiness probe).
+    pub team: Option<String>,
 }
 
 /// `e2e`(`parser.py:449`)。

package/crates/team-agent/src/coordinator/runtime_detectors.rs

@@ -216,8 +216,13 @@ fn detect_leader_api_error(
                 .and_then(Value::as_str)
                 .map(ToString::to_string)
         });
-    let leader_session_uuid = state
-        .get("team_owner")
+    // Stage 3a (identity-boundary unified plan, architect direction
+    // 2026-06-23): route owner read through the ownership repository.
+    // The coordinator state here is the workspace runtime state — Stage 5
+    // will swap to per-team state and this read follows automatically.
+    // capture.leader_receiver fallback is kept as evidence, not owner truth
+    // (architect §4 cross-module risk: capture fallback is evidence-only).
+    let leader_session_uuid = crate::state::ownership::read_owner_value(state, "")
         .and_then(|owner| owner.get("leader_session_uuid"))
         .or_else(|| {
             capture

package/crates/team-agent/src/diagnose/comms.rs

@@ -82,11 +82,19 @@ fn receiver_binding_snapshot(workspace: &Path, team: Option<&TeamKey>) -> Value
     };
     let state = selected.state;
     let receiver = state.get("leader_receiver").and_then(Value::as_object);
+    // Stage 2 (identity-boundary unified plan, architect direction
+    // 2026-06-23): route owner pane lookup through the ownership repository.
+    // `selected.state` is already team-projected by the selector, so the
+    // empty-team-key path returns the same top-level owner the legacy direct
+    // read produced — but Stage 5 will swap the data source under the
+    // repository and this diagnose surface follows automatically. The
+    // `owner` key fallback is retained for callers that pre-date the
+    // `team_owner` rename.
     let owner_pane_id = state
         .get("owner")
-        .or_else(|| state.get("team_owner"))
-        .and_then(|v| v.get("pane_id"))
         .cloned()
+        .or_else(|| crate::state::ownership::read_owner_value(&state, "").cloned())
+        .and_then(|v| v.get("pane_id").cloned())
         .unwrap_or(Value::Null);
     let caller_pane_id = std::env::var("TMUX_PANE").ok().map(Value::String).unwrap_or(Value::Null);
     let pane_id = receiver

package/crates/team-agent/src/leader/lease.rs

@@ -1031,6 +1031,17 @@ fn scan_agents_for_pane(agents: Option<&Value>, caller_pane: &PaneId) -> Option<
     None
 }
 
+/// Stage 3a (identity-boundary unified plan, architect direction 2026-06-23)
+/// + Stage 3 owner persist fix (architect direction 2026-06-24): route the
+/// in-memory binding write through the `state::ownership` API. The
+/// canonical team_key is derived from `active_team_key` first (the explicit
+/// scope set by `project_top_level_view` when an explicit team was passed
+/// to claim-leader) and only falls back to `team_state_key(state)` for the
+/// legacy unscoped flow. Without the `active_team_key` preference, an
+/// explicit `claim-leader --team alpha` whose projected state was emptied
+/// of team_dir/session_name would derive "current" and write the owner to
+/// `teams.current`, while `save_claim_team_scoped_state` expected
+/// `teams.alpha` — the S3-OWNER-001 persistence loss shape.
 fn write_binding_to_state(
     state: &mut Value,
     receiver: &LeaderReceiver,
@@ -1039,12 +1050,15 @@ fn write_binding_to_state(
     if !state.is_object() {
         *state = json!({});
     }
-    let Some(root) = state.as_object_mut() else {
+    if !state.is_object() {
         return Err(LeaderError::Validation("state root is not an object".to_string()));
-    };
-    root.insert("leader_receiver".to_string(), serde_json::to_value(receiver)?);
-    root.insert("team_owner".to_string(), serde_json::to_value(owner)?);
-    root.insert("owner_epoch".to_string(), json!(owner.owner_epoch.0));
+    }
+    let team_key = canonical_owner_write_key(state);
+    let record = crate::state::ownership::OwnershipWrite::new()
+        .with_leader_receiver(serde_json::to_value(receiver)?)
+        .with_team_owner(serde_json::to_value(owner)?)
+        .with_owner_epoch(owner.owner_epoch.0);
+    crate::state::ownership::write_owner(state, &team_key, record);
     Ok(())
 }
 
@@ -1055,13 +1069,34 @@ fn write_receiver_to_state(
     if !state.is_object() {
         *state = json!({});
     }
-    let Some(root) = state.as_object_mut() else {
+    if !state.is_object() {
         return Err(LeaderError::Validation("state root is not an object".to_string()));
-    };
-    root.insert("leader_receiver".to_string(), serde_json::to_value(receiver)?);
+    }
+    let team_key = canonical_owner_write_key(state);
+    let record = crate::state::ownership::OwnershipWrite::new()
+        .with_leader_receiver(serde_json::to_value(receiver)?);
+    crate::state::ownership::write_owner(state, &team_key, record);
     Ok(())
 }
 
+/// Stage 3 owner persist fix (architect direction 2026-06-24): determine
+/// the canonical team_key for an in-memory ownership write. When the state
+/// carries an `active_team_key` (set by `project_top_level_view` whenever
+/// an explicit team was scoped into the claim path), trust it — that's the
+/// requested team that `save_claim_team_scoped_state` will read back. Only
+/// fall back to `team_state_key(state)` for the legacy unscoped flow where
+/// the writer must derive team identity from session/dir/spec_path fields.
+fn canonical_owner_write_key(state: &Value) -> String {
+    if let Some(active) = state
+        .get("active_team_key")
+        .and_then(Value::as_str)
+        .filter(|key| !key.is_empty())
+    {
+        return active.to_string();
+    }
+    crate::state::projection::team_state_key(state)
+}
+
 fn state_receiver(state: &Value) -> Option<LeaderReceiver> {
     state
         .get("leader_receiver")
@@ -1139,9 +1174,16 @@ fn save_claim_team_scoped_state(workspace: &Path, state: &Value, target_key: &st
             .entry(existing_key)
             .or_insert_with(|| crate::state::projection::compact_team_state(&existing));
     }
+    // Stage 3 owner persist fix (architect direction 2026-06-24,
+    // .team/artifacts/stage3-owner-persist-fix.md): after Stage 3d removed
+    // top-level dual-write, the canonical ownership record lives ONLY at
+    // `state.teams[target_key].{team_owner, leader_receiver, owner_epoch}`.
+    // `compact_team_state(state)` strips the `teams` key entirely — that
+    // dropped the just-written nested ownership record on disk. Use the
+    // preserving helper so the canonical fields survive the compaction.
     teams.insert(
         target_key.to_string(),
-        crate::state::projection::compact_team_state(state),
+        compact_team_state_preserving_ownership(state, target_key),
     );
     let existing_primary_key = existing
         .get("session_name")
@@ -1154,16 +1196,18 @@ fn save_claim_team_scoped_state(workspace: &Path, state: &Value, target_key: &st
     } else {
         value_object(&existing)
     };
-    if !had_existing_teams
-        || existing_primary_key.as_deref().is_none_or(|key| key == target_key)
-        || existing_active_key == Some(target_key)
-    {
-        for key in ["leader_receiver", "team_owner", "owner_epoch"] {
-            if let Some(value) = state.get(key) {
-                merged.insert(key.to_string(), value.clone());
-            }
-        }
-    }
+    // Stage 3 top-level cleanup (architect direction 2026-06-24,
+    // .team/artifacts/stage3-toplevel-cleanup-fix.md + stage3-save-strip-fix.md):
+    // the legacy top-level owner copy loop is gone; the canonical-aware
+    // strip is now performed at the persistence boundary
+    // (`state::persist::save_runtime_state_with_merge_exceptions`), which
+    // every save_runtime_state* path funnels through. This per-call-site
+    // strip call has been removed — the save output handles cleanup
+    // uniformly for claim / restart / shutdown / start-agent / stop-agent
+    // / coordinator tick / promote sibling. `had_existing_teams` /
+    // primary/active key computations are retained as dead writes only
+    // via _ binding — they no longer gate any owner promote.
+    let _ = (had_existing_teams, existing_primary_key, existing_active_key);
     merged.insert("teams".to_string(), Value::Object(teams));
     crate::state::persist::save_runtime_state(workspace, &Value::Object(merged))?;
     Ok(())
@@ -1173,6 +1217,41 @@ fn value_object(value: &Value) -> serde_json::Map<String, Value> {
     value.as_object().cloned().unwrap_or_default()
 }
 
+/// Stage 3 owner persist fix (architect direction 2026-06-24,
+/// .team/artifacts/stage3-owner-persist-fix.md): build the per-team
+/// snapshot used by `save_claim_team_scoped_state` so the canonical
+/// `teams.<target_key>.{team_owner, leader_receiver, owner_epoch}` record
+/// survives the `compact_team_state` strip. Without this helper the
+/// claim-leader save loses the just-written nested ownership record (the
+/// S3-OWNER-001 evidence shape: `persisted_owner_locations=[]`).
+///
+/// Behaviour:
+/// - Start from the existing `compact_team_state(state)` (strips `teams`).
+/// - Look up `state.teams[target_key].{team_owner, leader_receiver, owner_epoch}`
+///   and copy each present field into the compacted entry.
+/// - Top-level owner fields stay UNTOUCHED — Stage 3d's canonical-only
+///   shape is preserved on disk.
+fn compact_team_state_preserving_ownership(state: &Value, target_key: &str) -> Value {
+    let mut entry = crate::state::projection::compact_team_state(state);
+    let Some(entry_obj) = entry.as_object_mut() else {
+        return entry;
+    };
+    let Some(owner_obj) = state
+        .get("teams")
+        .and_then(Value::as_object)
+        .and_then(|teams| teams.get(target_key))
+        .and_then(Value::as_object)
+    else {
+        return entry;
+    };
+    for key in ["team_owner", "leader_receiver", "owner_epoch"] {
+        if let Some(value) = owner_obj.get(key) {
+            entry_obj.insert(key.to_string(), value.clone());
+        }
+    }
+    entry
+}
+
 /// `_detect_dual_state_divergence`(card §85 C18;`__init__.py:556`)。workspace-level 与
 /// team-level snapshot 在 owner_uuid/receiver_pane_id/owner_epoch 上是否分叉 → `Some(详情)`。
 /// **CROSS-LANE**:snapshot 读经 step 13 restart。