@team-agent/installer 0.5.23 → 0.5.25

package/Cargo.lock

@@ -575,7 +575,7 @@ dependencies = [
 
 [[package]]
 name = "team-agent"
-version = "0.5.23"
+version = "0.5.25"
 dependencies = [
  "anyhow",
  "chrono",

package/Cargo.toml

@@ -9,7 +9,7 @@ members = ["crates/team-agent", "crates/win-conpty-phase0", "crates/conpty-trans
 
 [workspace.package]
 edition = "2021"
-version = "0.5.23"
+version = "0.5.25"
 license = "AGPL-3.0"
 rust-version = "1.95"
 

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

@@ -171,10 +171,23 @@ pub(crate) fn diagnose_runtime_for_workspace(
     backend: &dyn Transport,
 ) -> (Value, Value) {
     let (mut issues, mut repairs) = diagnose_runtime(state, backend);
+    append_legacy_snapshot_issue(workspace, state, &mut issues);
     append_coordinator_health_issue(workspace, state, &mut issues, &mut repairs);
     (issues, repairs)
 }
 
+fn append_legacy_snapshot_issue(workspace: &std::path::Path, state: &Value, issues: &mut Value) {
+    let Ok(Some(details)) = crate::leader::detect_dual_state_divergence(workspace, state) else {
+        return;
+    };
+    if let Some(items) = issues.as_array_mut() {
+        items.push(json!({
+            "id": "legacy_snapshot_stale",
+            "details": details,
+        }));
+    }
+}
+
 fn append_coordinator_health_issue(
     workspace: &std::path::Path,
     state: &Value,

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

@@ -1615,33 +1615,14 @@ fn state_owner(state: &Value) -> Option<TeamOwner> {
         .and_then(|v| serde_json::from_value(v).ok())
 }
 
-/// `_write_lease_dual_state`(card §85 C17;`__init__.py:588`)。同一锁内写 workspace state.json
-/// + team/<session> snapshot,两份永不分叉。**CROSS-LANE**:snapshot 写经 step 13 restart。
+/// `_write_lease_dual_state` — Foundation-0 F0-2: the historical dual
+/// write to the legacy per-session snapshot has been retired
+/// (`.team/artifacts/foundation-0-slice-design.md` §§4-5). This helper
+/// now persists ONLY the canonical root state; retaining the public
+/// name for 0.5.x call-site stability. The B0 legacy snapshot is
+/// diagnostic-only via `lifecycle::save_team_runtime_snapshot`.
 pub fn write_lease_dual_state(workspace: &Path, state: &Value) -> Result<(), LeaderError> {
     crate::state::persist::save_runtime_state(workspace, state)?;
-    if let Some(session_name) = state.get("session_name").and_then(Value::as_str) {
-        write_team_snapshot_atomic(workspace, session_name, state)?;
-    }
-    Ok(())
-}
-
-fn write_team_snapshot_atomic(
-    workspace: &Path,
-    session_name: &str,
-    state: &Value,
-) -> Result<(), LeaderError> {
-    let snap_path = crate::lifecycle::helpers::team_snapshot_path(workspace, session_name);
-    let parent = snap_path
-        .parent()
-        .ok_or_else(|| LeaderError::Validation("team snapshot path has no parent".to_string()))?;
-    std::fs::create_dir_all(parent)?;
-    let tmp = parent.join(format!("state.json.tmp-{}", std::process::id()));
-    let data = serde_json::to_vec_pretty(state)?;
-    std::fs::write(&tmp, data)?;
-    if let Err(error) = std::fs::rename(&tmp, &snap_path) {
-        let _ = std::fs::remove_file(&tmp);
-        return Err(error.into());
-    }
     Ok(())
 }
 
@@ -1769,17 +1750,22 @@ fn compact_team_state_preserving_claim_fields(state: &Value, target_key: &str) -
     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。
-pub fn detect_dual_state_divergence(
+/// Foundation-0 F0-2: reader for legacy per-session snapshot vs
+/// canonical root state. Diagnostic-only after the dual-write retirement
+/// (`.team/artifacts/foundation-0-slice-design.md` §§4-5); product
+/// authority code never consults this — it exists so `status`/`diagnose`
+/// can surface `legacy_snapshot_stale` when the on-disk sidecar has
+/// drifted. Every touch of the legacy path constants below is marked
+/// `B0_DIAGNOSTIC_LEGACY_SNAPSHOT_READ` so the RED3 grep guard admits
+/// them as documented exceptions.
+pub fn detect_dual_state_divergence( // B0_DIAGNOSTIC_LEGACY_SNAPSHOT_READ: diagnostic-only entry point; no product save/route consumer.
     workspace: &Path,
     state: &Value,
 ) -> Result<Option<Value>, LeaderError> {
     let Some(session_name) = state.get("session_name").and_then(Value::as_str) else {
         return Ok(None);
     };
-    let snap_path = readable_team_snapshot_path(workspace, session_name);
+    let snap_path = readable_team_snapshot_path(workspace, session_name); // B0_DIAGNOSTIC_LEGACY_SNAPSHOT_READ: diagnostic legacy-shape path lookup.
     if !snap_path.exists() {
         return Ok(None);
     }
@@ -1794,10 +1780,13 @@ pub fn detect_dual_state_divergence(
         .or_else(|| get_path_u64(state, &["leader_receiver", "owner_epoch"]));
     let team_epoch = get_path_u64(&snap, &["team_owner", "owner_epoch"])
         .or_else(|| get_path_u64(&snap, &["leader_receiver", "owner_epoch"]));
+    let workspace_agent_bindings = agent_binding_summary(state);
+    let team_agent_bindings = agent_binding_summary(&snap);
     let diverged = workspace_owner_pane != team_owner_pane
         || workspace_owner_uuid != team_owner_uuid
         || workspace_receiver_pane != team_receiver_pane
-        || workspace_epoch != team_epoch;
+        || workspace_epoch != team_epoch
+        || workspace_agent_bindings != team_agent_bindings;
     if !diverged {
         return Ok(None);
     }
@@ -1810,16 +1799,47 @@ pub fn detect_dual_state_divergence(
         "team_receiver_pane": team_receiver_pane,
         "workspace_owner_epoch": workspace_epoch,
         "team_owner_epoch": team_epoch,
+        "workspace_agent_bindings": workspace_agent_bindings,
+        "team_agent_bindings": team_agent_bindings,
+        "_legacy_snapshot_stale": true,
     })))
 }
 
-fn readable_team_snapshot_path(workspace: &Path, session_name: &str) -> PathBuf {
-    let safe_path = crate::lifecycle::helpers::team_snapshot_path(workspace, session_name);
+fn agent_binding_summary(state: &Value) -> Value {
+    let mut out = serde_json::Map::new();
+    let Some(agents) = state.get("agents").and_then(Value::as_object) else {
+        return Value::Object(out);
+    };
+    for (agent_id, agent) in agents {
+        let mut binding = serde_json::Map::new();
+        for key in [
+            "pane_id",
+            "pane_pid",
+            "tmux_endpoint",
+            "tmux_socket",
+            "window",
+            "window_name",
+        ] {
+            if let Some(value) = agent.get(key) {
+                binding.insert(key.to_string(), value.clone());
+            }
+        }
+        if !binding.is_empty() {
+            out.insert(agent_id.clone(), Value::Object(binding));
+        }
+    }
+    Value::Object(out)
+}
+
+fn readable_team_snapshot_path(workspace: &Path, session_name: &str) -> PathBuf { // B0_DIAGNOSTIC_LEGACY_SNAPSHOT_READ: diagnostic-only path resolver.
+    let safe_path = crate::lifecycle::helpers::team_snapshot_path(workspace, session_name); // B0_DIAGNOSTIC_LEGACY_SNAPSHOT_READ: reuses helpers safe legacy path.
     if safe_path.exists() {
         return safe_path;
     }
+    // Raw legacy `runtime/teams` fallback for pre-safe-shape snapshots. // B0_DIAGNOSTIC_LEGACY_SNAPSHOT_READ
+    let legacy_dir = "teams"; // B0_DIAGNOSTIC_LEGACY_SNAPSHOT_READ
     crate::model::paths::runtime_dir(workspace)
-        .join("teams")
+        .join(legacy_dir)
         .join(session_name)
         .join("state.json")
 }

package/crates/team-agent/src/leader/rediscover/tests.rs

@@ -135,7 +135,12 @@ fn try_readopt_writes_owner_receiver_dual_state_and_events() {
     assert_eq!(owner_view["claimed_via"], json!("attach-leader"));
     assert_eq!(owner_view["owner_epoch"], json!(4));
     assert_eq!(receiver_view["discovery"], json!("attach_readopt"));
-    assert!(crate::model::paths::runtime_dir(&ws)
+    // Foundation-0 F0-2: the try_readopt success path no longer side-
+    // effects a legacy per-session snapshot; canonical teams.<key> is
+    // the sole authority. The legacy sidecar stays absent unless a
+    // diagnostic writer explicitly created it
+    // (`.team/artifacts/foundation-0-slice-design.md` §§4-5).
+    assert!(!crate::model::paths::runtime_dir(&ws)
         .join("teams")
         .join("sess")
         .join("state.json")

package/crates/team-agent/src/leader/tests/lease_api.rs

@@ -112,7 +112,15 @@ use super::*;
     // 强化:带 session_name 时必须落 BOTH —— workspace state.json + team/<session> snapshot,
     // 两份 team_owner.pane_id / owner_epoch 必须一致(永不分叉)。空 body Ok(()) 会被这里抓。
     #[test]
-    fn write_lease_dual_state_persists_both_locations_without_divergence() {
+    // Foundation-0 F0-2 conversion of the C17 dual-write invariant test:
+    // legacy per-session snapshot dual-write has been retired
+    // (`.team/artifacts/foundation-0-slice-design.md` §§4-5). The lease
+    // helper now persists ONLY the canonical root state; a legacy
+    // snapshot is diagnostic-only and never re-appears as a side effect
+    // of `write_lease_dual_state`. This test enforces exactly that:
+    // canonical root gets the owner tuple, and the legacy per-session
+    // path stays absent unless a diagnostic path explicitly writes it.
+    fn write_lease_dual_state_persists_canonical_root_only_no_legacy_side_effect() {
         let ws = std::env::temp_dir().join(format!("ta_rs_dual_{}", std::process::id()));
         std::fs::create_dir_all(&ws).unwrap();
         let state = serde_json::json!({
@@ -121,32 +129,33 @@ use super::*;
             "leader_receiver": {"pane_id": "%1", "owner_epoch": 2},
         });
         write_lease_dual_state(&ws, &state).unwrap();
-        // (1) workspace state.json(<ws>/.team/runtime/state.json)被写,team_owner.pane_id==%1。
+        // Canonical root state.json IS written; F0-2 keeps this as the
+        // single product authority.
         let ws_path = crate::state::persist::runtime_state_path(&ws);
         let ws_state: serde_json::Value =
             serde_json::from_str(&std::fs::read_to_string(&ws_path).expect("workspace state.json 必须存在")).unwrap();
         assert_eq!(ws_state["team_owner"]["pane_id"], serde_json::json!("%1"));
         assert_eq!(ws_state["team_owner"]["owner_epoch"], serde_json::json!(2));
-        // (2) team-level snapshot(<ws>/.team/runtime/teams/<session>/state.json)被写。
-        let snap_path = crate::model::paths::runtime_dir(&ws)
-            .join("teams")
-            .join("team-sess")
-            .join("state.json");
-        let snap_state: serde_json::Value =
-            serde_json::from_str(&std::fs::read_to_string(&snap_path).expect("team snapshot state.json 必须存在")).unwrap();
-        // (3) 两份永不分叉:owner pane_id / owner_epoch 必须相等(C17 核心不变量)。
-        assert_eq!(
-            ws_state["team_owner"]["pane_id"], snap_state["team_owner"]["pane_id"],
-            "workspace 与 team snapshot 的 owner pane 不得分叉"
-        );
-        assert_eq!(
-            ws_state["team_owner"]["owner_epoch"], snap_state["team_owner"]["owner_epoch"],
-            "workspace 与 team snapshot 的 owner_epoch 不得分叉"
+        // Legacy per-session snapshot MUST NOT be a side effect of the
+        // lease save path any more — this is the RED2 authority-write
+        // guard shape at the unit-test layer.
+        let legacy_snap = crate::lifecycle::helpers::team_snapshot_path(&ws, "team-sess");
+        assert!(
+            !legacy_snap.exists(),
+            "F0-2: write_lease_dual_state must not write the legacy per-session snapshot; found {}",
+            legacy_snap.display(),
         );
     }
 
     #[test]
     fn lease_divergence_reads_restart_snapshot_for_special_session_names() {
+        // Foundation-0 F0-2 conversion: `write_lease_dual_state` no longer
+        // side-effects a legacy snapshot; the divergence detector is a
+        // diagnostic reader that fires only when a diagnostic writer
+        // (e.g. `lifecycle::save_team_runtime_snapshot`) has produced
+        // the sidecar. Sequence exercised here: canonical root save →
+        // diagnostic snapshot save with a different pane → divergence
+        // reader observes the drift.
         let ws = std::env::temp_dir().join(format!("ta_rs_dual_special_{}", std::process::id()));
         std::fs::create_dir_all(&ws).unwrap();
         let state = serde_json::json!({
@@ -160,17 +169,21 @@ use super::*;
             .join("teams")
             .join("team:proj-中文")
             .join("state.json");
+        // F0-2: canonical save must not create either the restart-safe
+        // or the raw legacy snapshot as a side effect.
         assert!(
-            safe_path.exists(),
-            "lease snapshot must use the restart-safe path: {}",
+            !safe_path.exists(),
+            "F0-2: canonical write_lease_dual_state must not create the restart-safe legacy snapshot: {}",
             safe_path.display()
         );
         assert!(
             !raw_path.exists(),
-            "new lease writes must not create the legacy raw session path: {}",
+            "F0-2: canonical write_lease_dual_state must not create the raw legacy snapshot: {}",
             raw_path.display()
         );
 
+        // Diagnostic write path with a divergent pane so we can exercise
+        // the divergence reader below.
         let restart_state = serde_json::json!({
             "session_name": "team:proj-中文",
             "team_owner": {"pane_id": "%9", "owner_epoch": 2, "leader_session_uuid": "uuuu"},
@@ -180,13 +193,18 @@ use super::*;
         assert_eq!(restart_path, safe_path);
         assert!(
             restart_path.exists(),
-            "restart snapshot must be written to a real file: {}",
+            "diagnostic snapshot must be written to a real file: {}",
             restart_path.display()
         );
 
+        // F0-2 RED1 diagnostic marker is present on the on-disk file.
+        let snap_state: serde_json::Value =
+            serde_json::from_str(&std::fs::read_to_string(&restart_path).unwrap()).unwrap();
+        assert_eq!(snap_state["_not_authoritative"], serde_json::json!(true));
+
         let d = detect_dual_state_divergence(&ws, &state)
             .unwrap()
-            .expect("divergence detector must read the restart-written snapshot");
+            .expect("divergence detector must read the diagnostic snapshot");
         assert_eq!(d["workspace_owner_pane"], serde_json::json!("%1"));
         assert_eq!(d["team_owner_pane"], serde_json::json!("%9"));
         assert_eq!(d["workspace_receiver_pane"], serde_json::json!("%1"));

package/crates/team-agent/src/leader/tests/lease_claim.rs

@@ -10,13 +10,16 @@ use super::*;
     /// (bound-pane liveness + caller eligibility) deterministically with no tmux.
     #[test]
     #[serial_test::serial(env)]
-    fn claim_lease_no_incident_vacant_acquire_advances_epoch_and_dual_writes() {
+    // Foundation-0 F0-2 conversion: `claim_lease_no_incident` used to
+    // dual-write the legacy per-session snapshot; that is retired
+    // (`.team/artifacts/foundation-0-slice-design.md` §§4-5). Canonical
+    // teams.<team_key> now carries the sole authoritative owner tuple.
+    fn claim_lease_no_incident_vacant_acquire_advances_epoch_and_writes_canonical_only() {
         let _g = ENV_LOCK.lock().unwrap_or_else(|p| p.into_inner());
         let _e = EnvGuard::apply(&[("TEAM_AGENT_LEADER_SESSION_UUID_OVERRIDE", None)]);
         let ws = p2_temp_ws("claim_vacant");
         let team_id = TeamKey::new("current");
         let caller = PaneId::new("%5");
-        // empty (vacant) state with a session so dual-state writes both files.
         let mut state = serde_json::json!({"session_name": "team-agent-x"});
         let event_log = crate::event_log::EventLog::new(&ws);
         let live = seeded_liveness(&["%5"]);
@@ -35,45 +38,25 @@ use super::*;
         let receiver = r.receiver.as_ref().expect("claimed → receiver");
         assert_eq!(receiver.pane_id, caller);
         assert_eq!(receiver.discovery, Some(Discovery::ClaimLeader));
-        // Stage 3d (identity-boundary unified plan, architect direction
-        // 2026-06-23): canonical owner now lives at teams.<team_key>; the
-        // top-level dual-write was dropped. Read through the ownership
-        // repository which preserves the legacy precedence for callers
-        // that still consult top-level on migration states.
         let ws_path = crate::state::persist::runtime_state_path(&ws);
         let ws_state: serde_json::Value =
             serde_json::from_str(&std::fs::read_to_string(&ws_path).unwrap()).unwrap();
-        // The canonical team_key is what `team_state_key(state)` derives
-        // (here: state's session_name "team-agent-x" since no explicit
-        // team_key/team_dir/spec_path was seeded). The test's `team_id`
-        // parameter is the LOOKUP key but `claim_lease_no_incident` uses
-        // the state-derived key for canonical writes. Stage 5 will unify
-        // these via TeamRuntimePaths.
         let canonical_key = crate::state::projection::team_state_key(&ws_state);
         let ws_owner =
             crate::state::ownership::read_owner_value(&ws_state, &canonical_key)
                 .expect("Stage 3d: vacant acquire writes canonical owner");
         assert_eq!(ws_owner["pane_id"], serde_json::json!("%5"));
         assert_eq!(ws_owner["owner_epoch"], serde_json::json!(1));
-        // team_id parameter is currently unused by the canonical write
-        // (architect Stage 5 will close this gap); silence the warning.
         let _ = &team_id;
+        // F0-2: canonical claim path must NOT side-effect the legacy
+        // per-session snapshot any more.
         let snap_path = crate::model::paths::runtime_dir(&ws)
             .join("teams").join("team-agent-x").join("state.json");
-        let snap: serde_json::Value =
-            serde_json::from_str(&std::fs::read_to_string(&snap_path).unwrap()).unwrap();
-        // Snapshot is per-session; team_state_key on the snapshot derives
-        // from its session_name. Read top-level first (legacy snapshot
-        // layout), fall back to derived team key.
-        let snap_owner = snap
-            .get("team_owner")
-            .or_else(|| {
-                let key = crate::state::projection::team_state_key(&snap);
-                snap.get("teams").and_then(|t| t.get(key)).and_then(|e| e.get("team_owner"))
-            })
-            .expect("dual-state snapshot owner");
-        assert_eq!(snap_owner["pane_id"], serde_json::json!("%5"), "dual-state snapshot owner");
-        assert_eq!(snap_owner["owner_epoch"], serde_json::json!(1));
+        assert!(
+            !snap_path.exists(),
+            "F0-2: vacant claim must not write a legacy per-session snapshot; found {}",
+            snap_path.display(),
+        );
     }
 
     // RED — DEAD-OWNER RECOVER: bound pane %1 absent from live set, caller %5

package/crates/team-agent/src/lifecycle/helpers.rs

@@ -6,8 +6,24 @@ use std::path::{Path, PathBuf};
 
 use super::*;
 
-/// `save_team_runtime_snapshot(workspace, state)`(`restart/snapshot.py:42`,**bug-084**)。
-/// `os.replace` 原子写;`EACCES/EPERM/EBUSY` 退避重试,**绝不 unwrap**。
+/// `save_team_runtime_snapshot(workspace, state)` — Foundation-0 F0-2:
+/// this is now a **diagnostic-only** legacy per-session snapshot writer.
+/// Root/projection `.team/runtime/state.json` is the sole product
+/// authority; the file this writes carries `_not_authoritative:true`
+/// and pointers back to the canonical path so no reader can mistake it
+/// for the real runtime state. See
+/// `.team/artifacts/foundation-0-slice-design.md` §§4-5 F0-2.
+///
+/// Product save paths (attach/claim/start-agent/restart/stop/remove)
+/// must NOT call this — the RED2 grep guard enforces that. Retained
+/// callers are diagnostic/migration/test paths only.
+///
+/// Preserves the legacy path shape (`.team/runtime/teams/<session>/state.json`)
+/// so 0.5.x operators inspecting the file see the diagnostic marker
+/// rather than being surprised by a missing file. The B3 canonical
+/// team-key layout will live under a different path
+/// (`teams/<team_key>/...`), so this file also cannot be mistaken for
+/// the future canonical shape.
 pub fn save_team_runtime_snapshot(
     workspace: &Path,
     state: &serde_json::Value,
@@ -16,17 +32,34 @@ pub fn save_team_runtime_snapshot(
         .get("session_name")
         .and_then(|v| v.as_str())
         .ok_or_else(|| LifecycleError::StatePersist("session_name is required".to_string()))?;
-    // golden restart/snapshot.py:46-47 — team_runtime_snapshot_dir = runtime_dir(workspace)/teams/<safe>,
-    // and paths.py:25-26 runtime_dir = workspace/.team/runtime. Use the crate path helper so the snapshot
-    // lands at <ws>/.team/runtime/teams/<safe>, matching golden AND the rest of the crate (not the
-    // ".team"-less <ws>/runtime/teams that the original port wrote).
     let path = team_snapshot_path(workspace, session_name);
     let dir = path
         .parent()
         .ok_or_else(|| LifecycleError::StatePersist("snapshot path has no parent".to_string()))?;
     fs::create_dir_all(&dir).map_err(|e| persist_err("create snapshot dir", &e))?;
+    let canonical_path = crate::state::persist::runtime_state_path(workspace);
+    let generated_at = chrono::Utc::now().to_rfc3339();
+    // F0-2 RED1: annotate the snapshot payload with diagnostic-only
+    // metadata so any reader can immediately see it is derived, not
+    // authoritative. `_canonical_state_path` points at the real
+    // runtime authority; `_derived_from` names the code path that
+    // produced this file; `_generated_at` records freshness so stale
+    // snapshots are easy to identify.
+    let mut annotated = state.clone();
+    if let Some(obj) = annotated.as_object_mut() {
+        obj.insert("_not_authoritative".to_string(), serde_json::json!(true));
+        obj.insert(
+            "_canonical_state_path".to_string(),
+            serde_json::json!(canonical_path.to_string_lossy()),
+        );
+        obj.insert(
+            "_derived_from".to_string(),
+            serde_json::json!("lifecycle::save_team_runtime_snapshot"),
+        );
+        obj.insert("_generated_at".to_string(), serde_json::json!(generated_at));
+    }
     let tmp = dir.join("state.json.tmp");
-    let data = serde_json::to_vec_pretty(state)
+    let data = serde_json::to_vec_pretty(&annotated)
         .map_err(|e| LifecycleError::StatePersist(format!("serialize snapshot: {e}")))?;
     fs::write(&tmp, data).map_err(|e| persist_err("write snapshot temp", &e))?;
     fs::rename(&tmp, &path).map_err(|e| persist_err("replace snapshot", &e))?;

package/crates/team-agent/src/lifecycle/restart/agent.rs

@@ -915,12 +915,9 @@ pub(super) fn stop_agent_at_paths(
     )
     .map_err(|e| LifecycleError::StatePersist(e.to_string()))?;
     // golden operations.py:96-99: snapshot (side-effect), then state_file = write_team_state path.
-    // snapshot.py:19-21 returns None silently when session_name is falsy — mirror that no-op here so
-    // a workspace whose persisted state lacks session_name proceeds to write team_state and return ok
-    // (do NOT swallow OTHER snapshot errors). The stop/reset/remove-force paths all inherit this guard.
-    if session_name_present(&state) {
-        crate::lifecycle::helpers::save_team_runtime_snapshot(workspace, &state)?;
-    }
+    // Foundation-0 F0-2: legacy per-session snapshot dual-write retired
+    // (`.team/artifacts/foundation-0-slice-design.md` §§4-5). Root state
+    // remains the only save target on the stop path.
     let state_file = write_team_state(spec_workspace, &spec, &state)?;
     write_stop_complete_event(workspace, agent_id, &target_str, stopped)?;
     Ok(StopAgentReport {

package/crates/team-agent/src/lifecycle/restart/remove.rs

@@ -186,17 +186,12 @@ fn remove_agent_at_paths(
     );
     match result {
         Ok(success) => {
-            // golden agents.py:135: _save_team_runtime_snapshot runs OUTSIDE the try/except, and
-            // snapshot.py:19-21 returns None (no error) when session_name is falsy. Mirror that here:
-            // only snapshot when session_name is present, and never let it roll the committed removal back.
-            if success
-                .removed_state
-                .get("session_name")
-                .and_then(|v| v.as_str())
-                .is_some_and(|s| !s.is_empty())
-            {
-                let _ = crate::lifecycle::helpers::save_team_runtime_snapshot(workspace, &success.removed_state)?;
-            }
+            // Foundation-0 F0-2: the historical dual-write to the legacy
+            // per-session snapshot has been retired
+            // (`.team/artifacts/foundation-0-slice-design.md` §§4-5).
+            // Root/projection is the sole runtime authority; the
+            // snapshot writer stayed in `lifecycle::helpers` only for
+            // diagnostic/migration/test callers.
             write_remove_complete_event(
                 paths.run_workspace,
                 agent_id,

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

@@ -280,8 +280,10 @@ pub(crate) fn latest_reportable_message_for(
     agent_id: &str,
     owner_team_id: Option<&str>,
 ) -> Option<String> {
-    current_reportable_message_for(workspace, agent_id, owner_team_id)
-        .or_else(|| latest_delivered_direct_message_for(workspace, agent_id, owner_team_id))
+    match direct_message_attribution_for(workspace, agent_id, owner_team_id) {
+        DirectMessageAttribution::Reportable(message_id) => Some(message_id),
+        DirectMessageAttribution::BlockedByNewer { .. } | DirectMessageAttribution::None => None,
+    }
 }
 
 pub(crate) fn current_reportable_message_for(
@@ -306,6 +308,49 @@ pub(crate) fn latest_delivered_direct_message_for(
     latest_reportable_message_from_db(&conn, agent_id, owner_team_id)
 }
 
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub(crate) enum DirectMessageAttribution {
+    Reportable(String),
+    BlockedByNewer {
+        message_id: String,
+        status: String,
+        error: Option<String>,
+    },
+    None,
+}
+
+pub(crate) fn direct_message_attribution_for(
+    workspace: &Path,
+    agent_id: &str,
+    owner_team_id: Option<&str>,
+) -> DirectMessageAttribution {
+    use crate::db::message_store::MessageStore;
+    let Ok(store) = MessageStore::open(workspace) else {
+        return DirectMessageAttribution::None;
+    };
+    let Ok(conn) = crate::db::schema::open_db(store.db_path()) else {
+        return DirectMessageAttribution::None;
+    };
+    if let Some(message_id) = current_turn_message_for(workspace, &conn, agent_id, owner_team_id) {
+        return DirectMessageAttribution::Reportable(message_id);
+    }
+    match latest_direct_message_from_db(&conn, agent_id, owner_team_id) {
+        Some(candidate)
+            if reportable_message_status(&candidate.status, candidate.error.as_deref()) =>
+        {
+            DirectMessageAttribution::Reportable(candidate.message_id)
+        }
+        Some(candidate) if blocks_historical_fallback(&candidate.status) => {
+            DirectMessageAttribution::BlockedByNewer {
+                message_id: candidate.message_id,
+                status: candidate.status,
+                error: candidate.error,
+            }
+        }
+        Some(_) | None => DirectMessageAttribution::None,
+    }
+}
+
 fn current_turn_message_for(
     workspace: &Path,
     conn: &rusqlite::Connection,
@@ -419,9 +464,27 @@ fn latest_reportable_message_from_db(
     agent_id: &str,
     owner_team_id: Option<&str>,
 ) -> Option<String> {
-    let row = conn
-        .query_row(
-            "select m.message_id, m.status, m.error from messages m
+    let candidate = latest_direct_message_from_db(conn, agent_id, owner_team_id)?;
+    if reportable_message_status(&candidate.status, candidate.error.as_deref()) {
+        Some(candidate.message_id)
+    } else {
+        None
+    }
+}
+
+struct DirectMessageCandidate {
+    message_id: String,
+    status: String,
+    error: Option<String>,
+}
+
+fn latest_direct_message_from_db(
+    conn: &rusqlite::Connection,
+    agent_id: &str,
+    owner_team_id: Option<&str>,
+) -> Option<DirectMessageCandidate> {
+    conn.query_row(
+        "select m.message_id, m.status, m.error from messages m
              where m.recipient = ?1
                and (?2 is null or m.owner_team_id = ?2)
                and (m.task_id is null or m.task_id = '')
@@ -437,29 +500,25 @@ fn latest_reportable_message_from_db(
              order by m.created_at desc,
                case when m.status = 'delivered' then 0 else 1 end
              limit 1",
-            params![agent_id, owner_team_id],
-            |row| {
-                Ok((
-                    row.get::<_, String>(0)?,
-                    row.get::<_, String>(1)?,
-                    row.get::<_, Option<String>>(2)?,
-                ))
-            },
-        )
-        .optional()
-        .ok()
-        .flatten()?;
-    let (message_id, status, error) = row;
-    if reportable_message_status(&status, error.as_deref()) {
-        Some(message_id)
-    } else {
-        None
-    }
+        params![agent_id, owner_team_id],
+        |row| {
+            Ok(DirectMessageCandidate {
+                message_id: row.get::<_, String>(0)?,
+                status: row.get::<_, String>(1)?,
+                error: row.get::<_, Option<String>>(2)?,
+            })
+        },
+    )
+    .optional()
+    .ok()
+    .flatten()
 }
 
 fn reportable_message_status(status: &str, error: Option<&str>) -> bool {
-    matches!(
-        status,
-        "delivered" | "submitted" | "injected" | "visible"
-    ) && (status == "delivered" || error.is_none())
+    matches!(status, "delivered" | "submitted" | "injected" | "visible")
+        && (status == "delivered" || error.is_none())
+}
+
+fn blocks_historical_fallback(status: &str) -> bool {
+    matches!(status, "failed" | "refused" | "blocked")
 }

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

@@ -238,6 +238,9 @@ pub fn compact_tool_result(result: &Value) -> ToolResult {
             "durably_stored",
             "result_id",
             "task_id",
+            "attributed_message_id",
+            "attribution_scope",
+            "task_id_source",
             "agent_id",
             "new_agent_id",
             "source_agent_id",

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

@@ -20,10 +20,10 @@ use crate::state::persist::{
 use crate::messaging::{self, MessageTarget, SendOptions};
 
 use super::helpers::{
-    current_reportable_message_for, delivery_outcome_value, ensure_object, enum_value,
-    insert_array, is_worker_recipient, json_dumps_default, latest_delivered_direct_message_for,
+    current_reportable_message_for, delivery_outcome_value, direct_message_attribution_for,
+    ensure_object, enum_value, insert_array, is_worker_recipient, json_dumps_default,
     latest_task_for_assignee, non_empty_string, normalized_envelope_value, object_fields,
-    requires_ack_for_target, tool_runtime_error,
+    requires_ack_for_target, tool_runtime_error, DirectMessageAttribution,
 };
 use super::normalize::{
     compact_tool_result, normalize_report_envelope, normalize_result_status_observed,
@@ -336,42 +336,81 @@ impl TeamOrchestratorTools {
                 // message-scoped fallback, before defaulting to "manual".
                 //   1. explicit arg
                 //   2. current physical direct turn for this agent
-                //   3. latest delivered direct message with no result yet
-                //   4. latest nonterminal assigned task in teams.<owner>.tasks
-                //      (scoped) → top-level tasks
+                //   3. bounded latest reportable direct message with no result yet
+                //   4. latest nonterminal assigned task in teams.<owner>.tasks,
+                //      only when no newer failed/refused/blocked direct turn blocks fallback
                 //   5. "manual" — truly uncorrelated; collect still rejects
                 let owner_team_id_str = self.owner_team_id.as_ref().map(|t| t.as_str().to_string());
-                let resolved = task_id
-                    .map(ToString::to_string)
-                    .or_else(|| {
-                        self.agent_id.as_ref().and_then(|agent| {
-                            current_reportable_message_for(
-                                &self.workspace,
-                                agent.as_str(),
-                                owner_team_id_str.as_deref(),
-                            )
-                        })
-                    })
-                    .or_else(|| {
-                        self.agent_id.as_ref().and_then(|agent| {
-                            latest_delivered_direct_message_for(
-                                &self.workspace,
-                                agent.as_str(),
-                                owner_team_id_str.as_deref(),
-                            )
-                        })
-                    })
-                    .or_else(|| {
-                        self.agent_id.as_ref().and_then(|agent| {
-                            latest_task_for_assignee(
+                let mut attributed_message_id = None;
+                let mut attribution_scope = None;
+                let mut task_id_source = None;
+                let resolved = if let Some(task_id) = task_id {
+                    task_id.to_string()
+                } else if let Some(agent) = self.agent_id.as_ref() {
+                    if let Some(message_id) = current_reportable_message_for(
+                        &self.workspace,
+                        agent.as_str(),
+                        owner_team_id_str.as_deref(),
+                    ) {
+                        attributed_message_id = Some(message_id.clone());
+                        attribution_scope = Some("message");
+                        task_id_source = Some("current_turn_message");
+                        message_id
+                    } else {
+                        match direct_message_attribution_for(
+                            &self.workspace,
+                            agent.as_str(),
+                            owner_team_id_str.as_deref(),
+                        ) {
+                            DirectMessageAttribution::Reportable(message_id) => {
+                                attributed_message_id = Some(message_id.clone());
+                                attribution_scope = Some("message");
+                                task_id_source = Some("direct_message");
+                                message_id
+                            }
+                            DirectMessageAttribution::BlockedByNewer {
+                                message_id,
+                                status,
+                                error,
+                            } => {
+                                push_report_warning(
+                                    obj,
+                                    serde_json::json!({
+                                        "code": "result_attribution_blocked_by_newer_direct_message",
+                                        "field": "task_id",
+                                        "severity": "warning",
+                                        "advisory": true,
+                                        "message_id": message_id,
+                                        "message_status": status,
+                                        "message_error": error,
+                                    }),
+                                );
+                                "manual".to_string()
+                            }
+                            DirectMessageAttribution::None => latest_task_for_assignee(
                                 &self.workspace,
                                 agent.as_str(),
                                 owner_team_id_str.as_deref(),
                             )
-                        })
-                    })
-                    .unwrap_or_else(|| "manual".to_string());
+                            .unwrap_or_else(|| "manual".to_string()),
+                        }
+                    }
+                } else {
+                    "manual".to_string()
+                };
                 obj.insert("task_id".to_string(), Value::String(resolved));
+                if let Some(message_id) = attributed_message_id {
+                    obj.entry("attributed_message_id")
+                        .or_insert(Value::String(message_id));
+                }
+                if let Some(scope) = attribution_scope {
+                    obj.entry("attribution_scope")
+                        .or_insert(Value::String(scope.to_string()));
+                }
+                if let Some(source) = task_id_source {
+                    obj.entry("task_id_source")
+                        .or_insert(Value::String(source.to_string()));
+                }
             }
             if !obj.contains_key("agent_id") {
                 let resolved = agent_id
@@ -411,6 +450,7 @@ impl TeamOrchestratorTools {
         let normalized = normalize_report_envelope(&base);
         let warnings = report_result_integrity_warnings(&base, &normalized);
         let mut env_value = normalized_envelope_value(&normalized);
+        copy_report_attribution_fields(&base, &mut env_value);
         if !warnings.is_empty() {
             if let Some(obj) = env_value.as_object_mut() {
                 obj.insert("warnings".to_string(), Value::Array(warnings));
@@ -977,6 +1017,47 @@ fn merge_object_fields(existing: &mut Value, incoming: &Value) {
     }
 }
 
+fn copy_report_attribution_fields(source: &Value, target: &mut Value) {
+    let Some(src) = source.as_object() else {
+        return;
+    };
+    let Some(dst) = target.as_object_mut() else {
+        return;
+    };
+    for key in [
+        "attributed_message_id",
+        "attribution_scope",
+        "task_id_source",
+    ] {
+        if let Some(value) = src.get(key) {
+            dst.entry(key.to_string()).or_insert(value.clone());
+        }
+    }
+}
+
+fn push_report_warning(obj: &mut serde_json::Map<String, Value>, warning: Value) {
+    let Some(code) = warning.get("code").and_then(Value::as_str) else {
+        return;
+    };
+    let Some(field) = warning.get("field").and_then(Value::as_str) else {
+        return;
+    };
+    match obj.get_mut("warnings") {
+        Some(Value::Array(warnings)) => {
+            let exists = warnings.iter().any(|existing| {
+                existing.get("code").and_then(Value::as_str) == Some(code)
+                    && existing.get("field").and_then(Value::as_str) == Some(field)
+            });
+            if !exists {
+                warnings.push(warning);
+            }
+        }
+        _ => {
+            obj.insert("warnings".to_string(), Value::Array(vec![warning]));
+        }
+    }
+}
+
 fn write_team_tasks(state: &mut Value, team_key: &str, tasks: Vec<Value>) {
     let Some(root) = state.as_object_mut() else {
         return;

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

@@ -697,6 +697,7 @@ fn report_result_for_owner_team_inner(
             "task_id".to_string(),
             serde_json::Value::String(task_id.to_string()),
         );
+        copy_report_attribution_fields(envelope, &mut out);
         out.insert(
             "agent_id".to_string(),
             serde_json::Value::String(agent_id.to_string()),
@@ -927,6 +928,7 @@ fn report_result_for_owner_team_inner(
         "task_id".to_string(),
         serde_json::Value::String(task_id.to_string()),
     );
+    copy_report_attribution_fields(envelope, &mut out);
     out.insert(
         "agent_id".to_string(),
         serde_json::Value::String(agent_id.to_string()),
@@ -968,6 +970,21 @@ fn report_result_for_owner_team_inner(
     Ok(serde_json::Value::Object(out))
 }
 
+fn copy_report_attribution_fields(
+    envelope: &serde_json::Value,
+    out: &mut serde_json::Map<String, serde_json::Value>,
+) {
+    for key in [
+        "attributed_message_id",
+        "attribution_scope",
+        "task_id_source",
+    ] {
+        if let Some(value) = envelope.get(key) {
+            out.insert(key.to_string(), value.clone());
+        }
+    }
+}
+
 fn fallback_primary_error_text(cli_primary_error: Option<&str>, observed: String) -> String {
     match cli_primary_error.filter(|error| !error.trim().is_empty()) {
         Some(error) => format!("{error}; {observed}"),

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

@@ -5,7 +5,7 @@
 //! paths or behaviour. It introduces a shared vocabulary that Stage 2 (owner
 //! repository), Stage 5 (per-team runtime state), and Stage 6 (per-team
 //! coordinator) will all consume, so that no later stage has to hand-build
-//! `.team/runtime/<team_key>/...` paths or guess the canonical team_key from
+//! `.team/runtime/teams/<team_key>/...` paths or guess the canonical team_key from
 //! a display name.
 //!
 //! Canonical rules:
@@ -15,10 +15,10 @@
 //! - For the foundation slice, `TeamScope::new(team_key)` accepts whatever
 //!   the caller already resolved (state/selector + state/persist already do
 //!   this work). Slug/hash promotion to global uniqueness lands in Stage 5.
-//! - `TeamRuntimePaths` is the SINGLE place where the
-//!   `.team/runtime/<team_key>/` layout is constructed. Anywhere downstream
-//!   code today hand-joins `runtime_dir(ws).join(team_key).join(...)` it
-//!   should migrate to call a method on `TeamRuntimePaths` in a later stage.
+//! - `TeamRuntimePaths` is the SINGLE place where the future B3
+//!   `.team/runtime/teams/<team_key>/` layout is constructed. Anywhere
+//!   downstream code today hand-joins runtime team paths should migrate to
+//!   call a method on `TeamRuntimePaths` in a later stage.
 //!
 //! Single-team behaviour: unchanged. The foundation does not move data, does
 //! not introduce new files, and is invoked by zero existing call sites yet.
@@ -72,15 +72,15 @@ impl TeamScope {
     }
 }
 
-/// Single source of `.team/runtime/<team_key>/...` path construction.
+/// Single source of future B3 `.team/runtime/teams/<team_key>/...` path construction.
 ///
 /// Stage 2 (owner repository), Stage 5 (per-team state), Stage 6 (per-team
 /// coordinator), and Stage 7 (per-team tmux socket) will all migrate from
 /// hand-built paths to `TeamRuntimePaths`. Today nothing reads from these
 /// methods yet — the foundation just owns the layout decision so when later
-/// stages start writing `.team/runtime/<team_key>/state.json` (Stage 5) or
-/// `.team/runtime/<team_key>/coordinator.pid` (Stage 6), there is exactly
-/// one place to change the layout.
+/// stages start writing `.team/runtime/teams/<team_key>/state.json` (Stage 5)
+/// or `.team/runtime/teams/<team_key>/coordinator.pid` (Stage 6), there is
+/// exactly one place to change the layout.
 #[derive(Debug, Clone)]
 pub struct TeamRuntimePaths {
     workspace: PathBuf,
@@ -110,34 +110,36 @@ impl TeamRuntimePaths {
         &self.team_key
     }
 
-    /// `.team/runtime/<team_key>/` — the team's runtime directory. Today this
-    /// already exists (runtime_spec lives under it). Stage 5 will start
-    /// writing `state.json` here too.
+    /// `.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`.
     pub fn team_dir(&self) -> PathBuf {
-        runtime_dir(&self.workspace).join(&self.team_key)
+        runtime_dir(&self.workspace)
+            .join("teams")
+            .join(&self.team_key)
     }
 
-    /// `.team/runtime/<team_key>/team.spec.yaml` — runtime spec. Mirrors the
-    /// existing `runtime_spec_path` helper; provided here so downstream
-    /// callers don't need to import two layout APIs.
+    /// Transitional runtime spec path. Mirrors the existing
+    /// `runtime_spec_path` helper while specs remain at
+    /// `.team/runtime/<team_key>/team.spec.yaml`.
     pub fn spec_path(&self) -> PathBuf {
         runtime_spec_path(&self.workspace, &self.team_key)
     }
 
-    /// `.team/runtime/<team_key>/state.json` — the canonical per-team state
-    /// path that Stage 5 will start writing. Not used by Stage 0 product
-    /// code; callers must continue using `runtime_state_path` until Stage 5
+    /// `.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
     /// migrates the truth source.
     pub fn state_path(&self) -> PathBuf {
         self.team_dir().join("state.json")
     }
 
-    /// `.team/runtime/<team_key>/coordinator.pid` — Stage 6 sidecar location.
+    /// `.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/<team_key>/coordinator.log` — Stage 6 sidecar location.
+    /// `.team/runtime/teams/<team_key>/coordinator.log` — future sidecar location.
     pub fn coordinator_log_path(&self) -> PathBuf {
         self.team_dir().join("coordinator.log")
     }
@@ -240,23 +242,20 @@ mod tests {
     }
 
     #[test]
-    fn team_runtime_paths_layout_matches_existing_runtime_dir_layout() {
+    fn team_runtime_paths_layout_preannounces_b3_state_dir() {
         let paths = TeamRuntimePaths::new(PathBuf::from("/ws/proj"), "alpha");
-        assert_eq!(
-            paths.team_dir(),
-            PathBuf::from("/ws/proj/.team/runtime/alpha")
-        );
+        let b3_team_dir = PathBuf::from("/ws/proj/.team/runtime")
+            .join("teams")
+            .join("alpha");
+        assert_eq!(paths.team_dir(), b3_team_dir);
         assert_eq!(
             paths.spec_path(),
             PathBuf::from("/ws/proj/.team/runtime/alpha/team.spec.yaml")
         );
-        assert_eq!(
-            paths.state_path(),
-            PathBuf::from("/ws/proj/.team/runtime/alpha/state.json")
-        );
+        assert_eq!(paths.state_path(), b3_team_dir.join("state.json"));
         assert_eq!(
             paths.coordinator_pid_path(),
-            PathBuf::from("/ws/proj/.team/runtime/alpha/coordinator.pid")
+            b3_team_dir.join("coordinator.pid")
         );
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-agent/installer",
-  "version": "0.5.23",
+  "version": "0.5.25",
   "description": "npx installer for Team Agent",
   "keywords": [
     "codex",
@@ -20,9 +20,9 @@
     "team-agent-installer": "npm/install.mjs"
   },
   "optionalDependencies": {
-    "@team-agent/cli-darwin-arm64": "0.5.23",
-    "@team-agent/cli-darwin-x64": "0.5.23",
-    "@team-agent/cli-linux-x64": "0.5.23"
+    "@team-agent/cli-darwin-arm64": "0.5.25",
+    "@team-agent/cli-darwin-x64": "0.5.25",
+    "@team-agent/cli-linux-x64": "0.5.25"
   },
   "scripts": {
     "postinstall": "node npm/bincheck.mjs",