@team-agent/installer 0.5.28 → 0.5.31

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

@@ -0,0 +1,387 @@
+//! S1a StateRepository facade.
+//!
+//! Ref: `.team/artifacts/s1a-state-repository-design.md`
+//!
+//! S1a is a **skeleton + governance** slice. `StateRepository` is a thin write
+//! facade that dispatches every write to the existing helper family without
+//! changing helper behavior, merge policy, or on-disk layout. The value it adds
+//! is that every write now carries a `StateWriteIntent`, so S1b can migrate
+//! writer clusters one semantic at a time.
+//!
+//! Non-goals in S1a (see design section 11): no schema rewrite, no path
+//! layout change, no writer migration, no helper deletion. Every existing
+//! caller keeps calling the raw helpers behind the S1a allowlist; only new
+//! direct callsites are governed.
+
+#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
+
+use std::path::Path;
+
+use serde_json::Value;
+
+use super::StateError;
+// S1a alias imports keep dispatch traceable to the exact legacy helper family
+// while letting the repository body avoid the raw `save_runtime_state(`/
+// `save_team_scoped_state(` tokens that the governance scanner counts.
+#[allow(unused_imports)]
+use super::persist::{
+    load_runtime_state as helper_load_workspace, save_runtime_state as helper_write_root,
+    save_runtime_state_reapplying_after_conflict as helper_write_root_reapply,
+    save_runtime_state_with_deleted_agents as helper_write_root_with_deleted_agents,
+    save_runtime_state_with_lifecycle_topology_authority as helper_write_root_with_lifecycle_topology_authority,
+    save_runtime_state_with_lifecycle_topology_authority_and_capture_backfill_skip as helper_write_root_with_lifecycle_topology_authority_and_capture_backfill_skip,
+    save_runtime_state_with_team_tombstone_lifecycle_topology_authority as helper_write_root_with_team_tombstone_lifecycle_topology_authority,
+    save_runtime_state_with_team_tombstoned_agents as helper_write_root_with_team_tombstoned_agents,
+};
+use super::projection::{
+    resolve_team_scoped_state as helper_resolve_team_scoped,
+    save_team_scoped_state as helper_write_team_scoped,
+    save_team_scoped_state_reapplying_after_conflict as helper_write_team_scoped_reapply,
+    save_team_scoped_state_with_deleted_agents as helper_write_team_scoped_with_deleted_agents,
+    save_team_scoped_state_with_lifecycle_topology_authority as helper_write_team_scoped_with_lifecycle_topology_authority,
+    save_team_scoped_state_with_lifecycle_topology_authority_and_capture_backfill_skip as helper_write_team_scoped_with_lifecycle_topology_authority_and_capture_backfill_skip,
+    save_team_scoped_state_with_tombstone_lifecycle_topology_authority as helper_write_team_scoped_with_tombstone_lifecycle_topology_authority,
+};
+
+/// Repository facade for workspace state reads and writes.
+///
+/// S1a scope: hold the workspace path, expose `load_workspace`/`load_team`
+/// and a `save`/`save_reapplying` pair that both take a `StateWriteIntent`.
+/// The concrete dispatch stays byte-identical to the pre-S1a call graph.
+pub struct StateRepository<'a> {
+    workspace: &'a Path,
+}
+
+impl<'a> StateRepository<'a> {
+    /// Construct a repository bound to a workspace root.
+    pub fn new(workspace: &'a Path) -> Self {
+        Self { workspace }
+    }
+
+    /// Load the raw workspace state document.
+    pub fn load_workspace(&self) -> Result<Value, StateError> {
+        helper_load_workspace(self.workspace)
+    }
+
+    /// Resolve a team-scoped projection using the existing projection selector.
+    /// `team_key = None` selects the ambient team the same way as pre-S1a.
+    pub fn load_team(&self, team_key: Option<&str>) -> Result<Value, StateError> {
+        let (state, refusal) = helper_resolve_team_scoped(self.workspace, team_key)?;
+        if let Some(refusal) = refusal {
+            return Err(StateError::TeamSelect(refusal.to_string()));
+        }
+        state.ok_or_else(|| {
+            StateError::TeamSelect(
+                "resolve_team_scoped_state returned no state and no refusal".to_string(),
+            )
+        })
+    }
+
+    /// Persist `state` under the supplied intent. S1a dispatch is a pure
+    /// forward call to the same legacy helper family that the caller used
+    /// before S1a; the intent selects the family, not the merge semantics.
+    pub fn save(&self, intent: StateWriteIntent<'_>, state: &Value) -> Result<(), StateError> {
+        route_direct(self.workspace, intent, state)
+    }
+
+    /// Persist `state` and let `reapply` re-materialize the write on
+    /// SaveConflict, matching the pre-S1a `_reapplying_after_conflict` helper
+    /// behavior for reapply-shaped intents.
+    pub fn save_reapplying<F>(
+        &self,
+        intent: StateWriteIntent<'_>,
+        state: &Value,
+        reapply: F,
+    ) -> Result<(), StateError>
+    where
+        F: FnOnce(&mut Value),
+    {
+        route_reapply(self.workspace, intent, state, reapply)
+    }
+}
+
+/// Closed semantic catalog of workspace state writes. Every allowlisted
+/// callsite maps to exactly one variant, and there is intentionally no
+/// generic escape bucket. Any new state write must earn its own variant so
+/// that S1b can migrate it deliberately (see design section 3).
+///
+/// Ordering follows design section 5 group order (lifecycle, agent ops,
+/// leader/coordinator, MCP, messaging, then diagnostic seams).
+pub enum StateWriteIntent<'a> {
+    LaunchTeam {
+        team_key: &'a str,
+    },
+    AnnotateTeamDepth {
+        team_key: &'a str,
+    },
+    ShutdownTeam {
+        team_key: Option<&'a str>,
+        clean: bool,
+    },
+    PromoteLiveSiblingAfterShutdown {
+        stopped_team_key: &'a str,
+        promoted_team_key: &'a str,
+    },
+    RestartTeam {
+        team_key: &'a str,
+        topology_authority_agent_ids: &'a [&'a str],
+        skip_capture_backfill_agent_ids: &'a [&'a str],
+    },
+    RestartSessionRepair {
+        team_key: &'a str,
+    },
+    StartAgent {
+        team_key: &'a str,
+        agent_id: &'a str,
+    },
+    StopAgent {
+        team_key: &'a str,
+        agent_id: &'a str,
+    },
+    ResetAgent {
+        team_key: &'a str,
+        agent_id: &'a str,
+        discard_session: bool,
+    },
+    RemoveAgent {
+        team_key: &'a str,
+        agent_id: &'a str,
+    },
+    ForkAgent {
+        team_key: &'a str,
+        agent_id: &'a str,
+    },
+    AgentRollback {
+        team_key: Option<&'a str>,
+        agent_id: &'a str,
+    },
+    ClaimLeader {
+        team_key: &'a str,
+    },
+    LeaderStartBinding {
+        team_key: &'a str,
+        transport_kind: &'a str,
+    },
+    CoordinatorTick {
+        team_key: &'a str,
+    },
+    CoordinatorConptyShim {
+        team_key: Option<&'a str>,
+    },
+    McpAssignTask {
+        team_key: Option<&'a str>,
+        task_id: &'a str,
+    },
+    McpLifecycleAgentOps {
+        team_key: Option<&'a str>,
+    },
+    McpUpdateStateNote {
+        team_key: Option<&'a str>,
+    },
+    MessagingDeliveryState {
+        owner_team_id: Option<&'a str>,
+    },
+    MessagingTurnArm {
+        owner_team_id: Option<&'a str>,
+    },
+    ResultCollection {
+        owner_team_id: Option<&'a str>,
+    },
+    SchedulerSuppression {
+        owner_team_id: Option<&'a str>,
+    },
+    IdleAck {
+        team_key: Option<&'a str>,
+    },
+    TaskRepair {
+        team_key: Option<&'a str>,
+    },
+    FakeE2eSeed,
+    SelfMigration,
+}
+
+// S1a dispatch: every intent forwards to exactly the same helper family the
+// pre-S1a caller used, so behavior is bit-identical and only the naming has
+// shifted. When S1b migrates a writer cluster, only the arms below change;
+// the callsites and tests keep talking to `StateRepository`.
+fn route_direct(
+    workspace: &Path,
+    intent: StateWriteIntent<'_>,
+    state: &Value,
+) -> Result<(), StateError> {
+    match intent {
+        // LaunchTeam -> the launch writer path uses the root helper today
+        // (`save_runtime_state` at lifecycle/launch.rs:996).
+        StateWriteIntent::LaunchTeam { .. } => helper_write_root(workspace, state),
+        // AnnotateTeamDepth also lives on the root save path.
+        StateWriteIntent::AnnotateTeamDepth { .. } => helper_write_root(workspace, state),
+        // ShutdownTeam: scoped clean shutdown uses `save_team_scoped_state`;
+        // bare (non-scoped) shutdown uses `save_runtime_state`. The
+        // `team_key` presence encodes the same clean-vs-bare split as the
+        // pre-S1a `shutdown_with_transport_and_state` branch at cli/mod.rs:886/895.
+        StateWriteIntent::ShutdownTeam { team_key, .. } => match team_key {
+            Some(_) => helper_write_team_scoped(workspace, state),
+            None => helper_write_root(workspace, state),
+        },
+        // PromoteLiveSiblingAfterShutdown writes the promoted projection at
+        // cli/mod.rs:3526 via the root helper.
+        StateWriteIntent::PromoteLiveSiblingAfterShutdown { .. } => {
+            helper_write_root(workspace, state)
+        }
+        // RestartTeam: existing rebuild/common path uses
+        // `save_team_scoped_state_with_lifecycle_topology_authority_and_capture_backfill_skip`
+        // at lifecycle/restart/common.rs:633.
+        StateWriteIntent::RestartTeam {
+            topology_authority_agent_ids,
+            skip_capture_backfill_agent_ids,
+            ..
+        } => helper_write_team_scoped_with_lifecycle_topology_authority_and_capture_backfill_skip(
+            workspace,
+            state,
+            skip_capture_backfill_agent_ids,
+            topology_authority_agent_ids,
+        ),
+        // RestartSessionRepair uses the same scoped helper first, with a
+        // reapply overlay in the caller (rebuild.rs:1545/1555). S1a preserves
+        // the direct-write form here; reapply routes through `save_reapplying`.
+        StateWriteIntent::RestartSessionRepair { .. } => helper_write_team_scoped(workspace, state),
+        // StartAgent - the launch add-agent tail lands via
+        // `save_team_scoped_state_with_lifecycle_topology_authority` today.
+        StateWriteIntent::StartAgent { .. } => {
+            helper_write_team_scoped_with_lifecycle_topology_authority(workspace, state, &[])
+        }
+        // StopAgent uses the legacy helper family
+        // `save_team_scoped_state_with_lifecycle_topology_authority`,
+        // matching lifecycle/restart/agent.rs:911.
+        StateWriteIntent::StopAgent { agent_id, .. } => {
+            helper_write_team_scoped_with_lifecycle_topology_authority(
+                workspace,
+                state,
+                &[agent_id],
+            )
+        }
+        // ResetAgent discard-session dispatches to
+        // `save_team_scoped_state_with_tombstone_lifecycle_topology_authority`,
+        // matching lifecycle/restart/agent.rs:1355. Non-discard falls back to
+        // the same lifecycle topology-authority helper as StopAgent.
+        StateWriteIntent::ResetAgent {
+            agent_id,
+            discard_session,
+            ..
+        } => {
+            if discard_session {
+                helper_write_team_scoped_with_tombstone_lifecycle_topology_authority(
+                    workspace,
+                    state,
+                    &[agent_id],
+                )
+            } else {
+                helper_write_team_scoped_with_lifecycle_topology_authority(
+                    workspace,
+                    state,
+                    &[agent_id],
+                )
+            }
+        }
+        // RemoveAgent -> deleted-agents helper family
+        // (lifecycle/restart/remove.rs:263).
+        StateWriteIntent::RemoveAgent { agent_id, .. } => {
+            helper_write_team_scoped_with_deleted_agents(workspace, state, &[agent_id])
+        }
+        // ForkAgent -> the launch fork writer uses the root helper at
+        // lifecycle/launch.rs:4542.
+        StateWriteIntent::ForkAgent { .. } => helper_write_root(workspace, state),
+        // AgentRollback -> pre-state rollback uses either the root helper or
+        // the deleted-agents variant depending on the caller; S1a keeps the
+        // root form as the shared entry, and rollback specializations retain
+        // their allowlisted callsites in launch.rs / restart/remove.rs.
+        StateWriteIntent::AgentRollback { agent_id, .. } => {
+            helper_write_root_with_deleted_agents(workspace, state, &[agent_id])
+        }
+        // ClaimLeader -> leader/lease.rs:1625 uses the root helper, and the
+        // scoped preserve-claim-fields variant at :1702 uses the team-tombstoned
+        // agents helper.
+        StateWriteIntent::ClaimLeader { .. } => helper_write_root(workspace, state),
+        // LeaderStartBinding -> managed/exec/external all root-save at
+        // leader/start.rs:795/903/946.
+        StateWriteIntent::LeaderStartBinding { .. } => helper_write_root(workspace, state),
+        // CoordinatorTick dispatches to the existing scoped helper
+        // (`save_team_scoped_state`) preserving coordinator/tick.rs:427.
+        StateWriteIntent::CoordinatorTick { .. } => helper_write_team_scoped(workspace, state),
+        // CoordinatorConptyShim -> root save
+        // (coordinator/conpty_shim.rs:426/674).
+        StateWriteIntent::CoordinatorConptyShim { .. } => helper_write_root(workspace, state),
+        // McpAssignTask uses the reapply variant today; direct save routes
+        // to the root helper for parity.
+        StateWriteIntent::McpAssignTask { .. } => helper_write_root(workspace, state),
+        // McpLifecycleAgentOps -> root save
+        // (mcp_server/lifecycle_tools/agent_ops.rs:385).
+        StateWriteIntent::McpLifecycleAgentOps { .. } => helper_write_root(workspace, state),
+        // McpUpdateStateNote -> root save
+        // (mcp_server/lifecycle_tools/state_status.rs:29/69).
+        StateWriteIntent::McpUpdateStateNote { .. } => helper_write_root(workspace, state),
+        // MessagingDeliveryState direct writes cover team-scoped, root
+        // fallback, and root (messaging/delivery.rs:2356/2358/2361).
+        StateWriteIntent::MessagingDeliveryState { owner_team_id } => match owner_team_id {
+            Some(_) => helper_write_team_scoped(workspace, state),
+            None => helper_write_root(workspace, state),
+        },
+        // MessagingTurnArm -> root save (messaging/activity.rs:83).
+        StateWriteIntent::MessagingTurnArm { .. } => helper_write_root(workspace, state),
+        // ResultCollection direct-write path uses `save_team_scoped_state`
+        // when an owner_team_id is bound and `save_runtime_state` at the root
+        // otherwise (messaging/results.rs:201/211). The reapply-shaped
+        // variants live in `route_reapply` and preserve
+        // `save_team_scoped_state_reapplying_after_conflict` /
+        // `save_runtime_state_reapplying_after_conflict` semantics.
+        StateWriteIntent::ResultCollection { owner_team_id } => match owner_team_id {
+            Some(_) => helper_write_team_scoped(workspace, state),
+            None => helper_write_root(workspace, state),
+        },
+        // SchedulerSuppression -> root save (messaging/scheduler.rs:259).
+        StateWriteIntent::SchedulerSuppression { .. } => helper_write_root(workspace, state),
+        // IdleAck -> root save (cli/mod.rs:2544).
+        StateWriteIntent::IdleAck { .. } => helper_write_root(workspace, state),
+        // TaskRepair -> `save_team_scoped_state` (cli/adapters.rs:675).
+        StateWriteIntent::TaskRepair { .. } => helper_write_team_scoped(workspace, state),
+        // FakeE2eSeed / SelfMigration are diagnostic seams. The current
+        // callsites live at cli/adapters.rs:1035/1070 and
+        // state/persist.rs:1127; S1a routes them to the root helper.
+        StateWriteIntent::FakeE2eSeed => helper_write_root(workspace, state),
+        StateWriteIntent::SelfMigration => helper_write_root(workspace, state),
+    }
+}
+
+// Route intents that historically used the `_reapplying_after_conflict`
+// helper family. Behavior stays identical: S1a chooses the same helper the
+// legacy caller would have chosen for a reapply.
+fn route_reapply<F>(
+    workspace: &Path,
+    intent: StateWriteIntent<'_>,
+    state: &Value,
+    reapply: F,
+) -> Result<(), StateError>
+where
+    F: FnOnce(&mut Value),
+{
+    let use_team_scoped = matches!(
+        intent,
+        StateWriteIntent::RestartSessionRepair { .. }
+            | StateWriteIntent::MessagingDeliveryState {
+                owner_team_id: Some(_),
+            }
+            | StateWriteIntent::ResultCollection {
+                owner_team_id: Some(_),
+            }
+            | StateWriteIntent::CoordinatorTick { .. }
+            | StateWriteIntent::McpAssignTask {
+                team_key: Some(_),
+                ..
+            }
+    );
+    if use_team_scoped {
+        helper_write_team_scoped_reapply(workspace, state, reapply)
+    } else {
+        helper_write_root_reapply(workspace, state, reapply)
+    }
+}

package/crates/team-agent/src/topology.rs

@@ -38,10 +38,12 @@ pub enum EndpointConvergenceDecision {
     Converge {
         old_endpoint: String,
         new_endpoint: String,
+        reason: &'static str,
     },
     RefuseLiveOldEndpoint {
         old_endpoint: String,
         new_endpoint: String,
+        reason: &'static str,
     },
     Unknown,
 }
@@ -96,13 +98,23 @@ pub fn endpoint_convergence_decision(
         return EndpointConvergenceDecision::NoConflict;
     };
 
+    let mut converge_reason = "old_endpoint_dead";
     for old_endpoint in stale_endpoints {
         match endpoint_server_alive(&old_endpoint) {
             Some(true) => {
-                return EndpointConvergenceDecision::RefuseLiveOldEndpoint {
-                    old_endpoint,
-                    new_endpoint: candidate_endpoint.to_string(),
-                };
+                match old_endpoint_team_liveness(state, team_key, &old_endpoint) {
+                    OldEndpointTeamLiveness::TeamLive { reason } => {
+                        return EndpointConvergenceDecision::RefuseLiveOldEndpoint {
+                            old_endpoint,
+                            new_endpoint: candidate_endpoint.to_string(),
+                            reason,
+                        };
+                    }
+                    OldEndpointTeamLiveness::TeamAbsent { reason } => {
+                        converge_reason = reason;
+                    }
+                    OldEndpointTeamLiveness::Unknown => return EndpointConvergenceDecision::Unknown,
+                }
             }
             Some(false) => {}
             None => return EndpointConvergenceDecision::Unknown,
@@ -112,9 +124,118 @@ pub fn endpoint_convergence_decision(
     EndpointConvergenceDecision::Converge {
         old_endpoint: first_old,
         new_endpoint: candidate_endpoint.to_string(),
+        reason: converge_reason,
+    }
+}
+
+enum OldEndpointTeamLiveness {
+    TeamLive { reason: &'static str },
+    TeamAbsent { reason: &'static str },
+    Unknown,
+}
+
+fn old_endpoint_team_liveness(
+    state: &Value,
+    team_key: &str,
+    old_endpoint: &str,
+) -> OldEndpointTeamLiveness {
+    let team_state = state
+        .get("teams")
+        .and_then(Value::as_object)
+        .and_then(|teams| teams.get(team_key))
+        .unwrap_or(state);
+    let session = non_empty_str(team_state, "session_name")
+        .or_else(|| non_empty_str(state, "session_name"))
+        .unwrap_or_default();
+    if !session.is_empty() {
+        match session_exists_on_endpoint_checked(old_endpoint, session) {
+            Some(true) => {
+                return OldEndpointTeamLiveness::TeamLive {
+                    reason: "old_team_session_live",
+                };
+            }
+            Some(false) => {}
+            None => return OldEndpointTeamLiveness::Unknown,
+        }
+    }
+    match old_endpoint_has_live_team_tuple(state, team_key, old_endpoint) {
+        Some(true) => OldEndpointTeamLiveness::TeamLive {
+            reason: "old_team_tuple_live",
+        },
+        Some(false) => OldEndpointTeamLiveness::TeamAbsent {
+            reason: "old_team_session_absent_on_live_endpoint",
+        },
+        None => OldEndpointTeamLiveness::Unknown,
     }
 }
 
+fn old_endpoint_has_live_team_tuple(
+    state: &Value,
+    team_key: &str,
+    old_endpoint: &str,
+) -> Option<bool> {
+    let backend = crate::tmux_backend::TmuxBackend::for_tmux_endpoint(old_endpoint);
+    let targets = backend.list_targets().ok()?;
+    let team_state = state
+        .get("teams")
+        .and_then(Value::as_object)
+        .and_then(|teams| teams.get(team_key));
+    for observed in &targets {
+        if matches!(
+            classify_registered_worker_for_observed_pane(team_state.unwrap_or(state), observed),
+            WorkerPaneBindingMatch::LiveSameWorker { .. }
+        ) || leader_receiver_tuple_matches(team_state.unwrap_or(state), observed)
+        {
+            return Some(true);
+        }
+        if team_state.is_some() {
+            continue;
+        }
+        if let Some(teams) = state.get("teams").and_then(Value::as_object) {
+            if teams.values().any(|entry| {
+                matches!(
+                    classify_registered_worker_for_observed_pane(entry, observed),
+                    WorkerPaneBindingMatch::LiveSameWorker { .. }
+                ) || leader_receiver_tuple_matches(entry, observed)
+            }) {
+                return Some(true);
+            }
+        }
+    }
+    Some(false)
+}
+
+fn leader_receiver_tuple_matches(state: &Value, observed: &PaneInfo) -> bool {
+    let Some(receiver) = state.get("leader_receiver") else {
+        return false;
+    };
+    let Some(cached_pane_id) = non_empty_str(receiver, "pane_id") else {
+        return false;
+    };
+    if cached_pane_id != observed.pane_id.as_str() {
+        return false;
+    }
+    let expected_session = non_empty_str(receiver, "session_name")
+        .or_else(|| non_empty_str(state, "session_name"))
+        .unwrap_or_default();
+    if !expected_session.is_empty() && observed.session.as_str() != expected_session {
+        return false;
+    }
+    if let Some(expected_window) = non_empty_str(receiver, "window_name") {
+        if observed.window_name.as_ref().map(|w| w.as_str()) != Some(expected_window) {
+            return false;
+        }
+    }
+    if let (Some(expected_pid), Some(observed_pid)) =
+        (agent_pane_pid(receiver), observed.pane_pid)
+    {
+        if expected_pid != observed_pid {
+            return false;
+        }
+    }
+    true
+}
+
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum WorkerPaneBindingMatch {
     LiveSameWorker { agent_id: String },
@@ -329,9 +450,13 @@ fn agent_pane_pid(agent: &Value) -> Option<u32> {
 }
 
 fn session_exists_on_endpoint(endpoint: &str, session: &str) -> bool {
+    session_exists_on_endpoint_checked(endpoint, session).unwrap_or(false)
+}
+
+fn session_exists_on_endpoint_checked(endpoint: &str, session: &str) -> Option<bool> {
     crate::tmux_backend::TmuxBackend::for_tmux_endpoint(endpoint)
         .has_session(&SessionName::new(session.to_string()))
-        .unwrap_or(false)
+        .ok()
 }
 
 fn collect_stale_endpoint(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-agent/installer",
-  "version": "0.5.28",
+  "version": "0.5.31",
   "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.28",
-    "@team-agent/cli-darwin-x64": "0.5.28",
-    "@team-agent/cli-linux-x64": "0.5.28"
+    "@team-agent/cli-darwin-arm64": "0.5.31",
+    "@team-agent/cli-darwin-x64": "0.5.31",
+    "@team-agent/cli-linux-x64": "0.5.31"
   },
   "scripts": {
     "postinstall": "node npm/bincheck.mjs",