@team-agent/installer 0.3.39 → 0.4.0

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

@@ -311,8 +311,16 @@ fn scoped_shutdown_keeps_owned_endpoint_when_sibling_session_remains() {
         crate::cli::lifecycle_port::shutdown_with_transport(&ws, true, Some("team-a"), &transport)
             .expect("shutdown should complete");
 
-    assert_eq!(out["ok"], json!(true));
-    assert_eq!(out["residuals"]["owned_files"], json!([]));
+    // 0.4.0 refactor: shutdown now reports `ok=false` when sessions appear as
+    // residuals (`status="failed"`). This test uses
+    // `with_targets_persist_after_kill()` which leaves the killed session
+    // visible to the residual probe, so the new refactor surfaces it as a
+    // residual. The actual contract of this test is the SOCKET keep behavior
+    // (owned endpoint preserved when sibling sessions live on it), which the
+    // assertions below cover. We assert no owned_files residual + socket on
+    // disk + no kill_server, which are the invariants this test actually
+    // exists to guard.
+    assert_eq!(out["residuals"]["owned_files"], json!([]), "full out={out}");
     assert!(
         socket.exists(),
         "owned endpoint stays while sibling team session remains"
@@ -677,7 +685,7 @@ fn shutdown_outcome_late_or_postcheck_gone_is_ok_with_lsof_diagnostic() {
             cleanup_truth_degraded: false,
             coordinator_timeout: true,
             coordinator_stop_ok: None,
-            coordinator_post_stop: crate::cli::lifecycle_port::CoordinatorStopObservation::Gone,
+            coordinator_post_stop: crate::cli::lifecycle_port::CoordinatorStopObservation::Gone, target_session_spared: false,
         },
     );
 
@@ -697,7 +705,7 @@ fn shutdown_outcome_coordinator_timeout_still_running_is_timeout() {
             cleanup_truth_degraded: false,
             coordinator_timeout: true,
             coordinator_stop_ok: None,
-            coordinator_post_stop: crate::cli::lifecycle_port::CoordinatorStopObservation::Running,
+            coordinator_post_stop: crate::cli::lifecycle_port::CoordinatorStopObservation::Running, target_session_spared: false,
         },
     );
 
@@ -717,7 +725,7 @@ fn shutdown_outcome_ps_table_degraded_still_partial_after_coordinator_gone() {
             cleanup_truth_degraded: true,
             coordinator_timeout: true,
             coordinator_stop_ok: None,
-            coordinator_post_stop: crate::cli::lifecycle_port::CoordinatorStopObservation::Gone,
+            coordinator_post_stop: crate::cli::lifecycle_port::CoordinatorStopObservation::Gone, target_session_spared: false,
         },
     );
 
@@ -911,7 +919,26 @@ fn e49_managed_leader_shutdown_spares_leader_session_and_kills_workers_per_pane(
             .any(|v| v.as_str() == Some("team-current")),
         "E49: report's spared_sessions MUST contain the leader session. Got {out_spared:?}"
     );
-    assert_eq!(out["ok"], json!(true));
+    // 0.4.0 refactor: when the target session is deliberately spared (E49
+    // managed-leader topology), shutdown reports
+    // `status="dirty_state", phase="target_session_spared", ok=false`. This
+    // is semantically the SUCCESS path for E49 — leader pane preserved — but
+    // the new refactor surfaces it as a non-clean exit so callers can detect
+    // residual sessions. The E49 invariant (leader spared, workers killed per
+    // pane) is already verified by the preceding `out_killed` / `out_spared`
+    // assertions; here we pin the new top-level shape.
+    assert_eq!(
+        out["status"],
+        json!("dirty_state"),
+        "0.4.0 refactor: managed-leader spare path surfaces dirty_state \
+         (target_session_spared) — leader was spared, not killed. Got out={out}"
+    );
+    assert_eq!(
+        out["phase"],
+        json!("target_session_spared"),
+        "0.4.0 refactor: phase must name the spare reason. Got out={out}"
+    );
+    assert_eq!(out["session_killed"], json!(false));
 }
 
 /// E49 regression guard: external-leader topology (is_external_leader=true)
@@ -1065,3 +1092,159 @@ fn shutdown_missing_topology_marker_defaults_to_managed_cleanup() {
         "missing topology marker must default to managed cleanup, not external kill-server"
     );
 }
+
+// ════════════════════════════════════════════════════════════════════════
+// unit-0 (Stage 0) characterization tests
+//
+// These pin the CURRENT classify_shutdown_outcome behavior so that the
+// Stage 1 refactor (unit-2: move shutdown into lifecycle and feed real
+// session-kill facts into the classifier) is detectable as a behavior
+// change rather than an accidental regression.
+//
+// The classifier today does NOT consume `session_killed` / `spared_sessions`
+// facts — it only looks at residuals. That is the 0.3.39 false-green bug
+// surface. The tests below LOCK the current OK/failed/partial/timeout
+// branches against opaque residual booleans so that:
+//   - unit-2 can wire in the missing topology facts and we observe the
+//     intended new behavior on the false-green scenario,
+//   - any unintended status change in OTHER branches breaks the suite.
+// ════════════════════════════════════════════════════════════════════════
+
+#[test]
+fn unit0_classify_outcome_no_residuals_returns_ok() {
+    // Baseline: nothing residual, coordinator clean -> ok/status:"ok".
+    let out = crate::cli::lifecycle_port::classify_shutdown_outcome(
+        crate::cli::lifecycle_port::ShutdownOutcomeInput {
+            kill_error: false,
+            session_residuals: false,
+            process_residuals: false,
+            owned_file_residuals: false,
+            cleanup_truth_degraded: false,
+            coordinator_timeout: false,
+            coordinator_stop_ok: Some(true),
+            coordinator_post_stop:
+                crate::cli::lifecycle_port::CoordinatorStopObservation::NotNeeded,
+            target_session_spared: false,
+        },
+    );
+    assert!(out.ok);
+    assert_eq!(out.status, "ok");
+    assert_eq!(out.phase, None);
+}
+
+#[test]
+fn unit0_classify_outcome_session_residual_returns_failed() {
+    let out = crate::cli::lifecycle_port::classify_shutdown_outcome(
+        crate::cli::lifecycle_port::ShutdownOutcomeInput {
+            kill_error: false,
+            session_residuals: true,
+            process_residuals: false,
+            owned_file_residuals: false,
+            cleanup_truth_degraded: false,
+            coordinator_timeout: false,
+            coordinator_stop_ok: Some(true),
+            coordinator_post_stop:
+                crate::cli::lifecycle_port::CoordinatorStopObservation::Gone,
+            target_session_spared: false,
+        },
+    );
+    assert!(!out.ok);
+    assert_eq!(out.status, "failed");
+}
+
+#[test]
+fn unit0_classify_outcome_coordinator_timeout_returns_timeout_phase() {
+    let out = crate::cli::lifecycle_port::classify_shutdown_outcome(
+        crate::cli::lifecycle_port::ShutdownOutcomeInput {
+            kill_error: false,
+            session_residuals: false,
+            process_residuals: false,
+            owned_file_residuals: false,
+            cleanup_truth_degraded: false,
+            coordinator_timeout: true,
+            coordinator_stop_ok: Some(false),
+            coordinator_post_stop:
+                crate::cli::lifecycle_port::CoordinatorStopObservation::Running,
+            target_session_spared: false,
+        },
+    );
+    assert!(!out.ok);
+    assert_eq!(out.status, "timeout");
+    assert_eq!(out.phase, Some("stop_coordinator"));
+}
+
+#[test]
+fn unit0_classify_outcome_cleanup_truth_degraded_returns_partial_os_probe() {
+    let out = crate::cli::lifecycle_port::classify_shutdown_outcome(
+        crate::cli::lifecycle_port::ShutdownOutcomeInput {
+            kill_error: false,
+            session_residuals: false,
+            process_residuals: false,
+            owned_file_residuals: false,
+            cleanup_truth_degraded: true,
+            coordinator_timeout: false,
+            coordinator_stop_ok: Some(true),
+            coordinator_post_stop:
+                crate::cli::lifecycle_port::CoordinatorStopObservation::Gone,
+            target_session_spared: false,
+        },
+    );
+    assert!(!out.ok);
+    assert_eq!(out.status, "partial");
+    assert_eq!(out.phase, Some("os_probe"));
+}
+
+#[test]
+fn unit2_classify_outcome_target_session_spared_is_not_green() {
+    // unit-2 false-green guard: when the target worker session was spared
+    // (still alive) the classifier MUST NOT return ok/status:"ok". This is
+    // the 0.3.39 shutdown false-green shape unit-2 fixes.
+    let out = crate::cli::lifecycle_port::classify_shutdown_outcome(
+        crate::cli::lifecycle_port::ShutdownOutcomeInput {
+            kill_error: false,
+            session_residuals: false,
+            process_residuals: false,
+            owned_file_residuals: false,
+            cleanup_truth_degraded: false,
+            coordinator_timeout: false,
+            coordinator_stop_ok: Some(true),
+            coordinator_post_stop:
+                crate::cli::lifecycle_port::CoordinatorStopObservation::Gone,
+            target_session_spared: true,
+        },
+    );
+    assert!(
+        !out.ok,
+        "false-green regression: target_session_spared=true must force ok=false"
+    );
+    assert_eq!(out.status, "dirty_state");
+    assert_eq!(out.phase, Some("target_session_spared"));
+}
+
+#[test]
+fn unit0_sessions_to_kill_leader_prefixed_session_is_always_spared() {
+    // Pinned invariant: a session named `team-agent-leader-*` is NEVER in
+    // the kill list, even without an anchor. unit-1/3 wraps this in typed
+    // identity; the behavior must remain identical.
+    use crate::transport::SessionName;
+    let session_names = vec![
+        SessionName::new("team-real-worker"),
+        SessionName::new("team-agent-leader-claude-x"),
+    ];
+    let decision = sessions_to_kill(&session_names, &BTreeSet::new());
+    match decision {
+        KillDecision::KillIndividually { to_kill, spared } => {
+            assert!(to_kill.iter().any(|s| s.as_str() == "team-real-worker"));
+            assert!(!to_kill
+                .iter()
+                .any(|s| s.as_str().starts_with("team-agent-leader-")));
+            assert!(spared
+                .iter()
+                .any(|s| s.as_str() == "team-agent-leader-claude-x"));
+        }
+        other => panic!(
+            "expected KillIndividually with leader spared; got {:?}",
+            other
+        ),
+    }
+}

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

@@ -23,6 +23,195 @@ use super::*;
     // RED: status_port::status is unimplemented!() so the call panics until ported.
     // =========================================================================
 
+    // =========================================================================
+    // RM-039-STAT-001 regression guard (real-machine evidence 2026-06-22).
+    //
+    // Architect verdict (bugs-stat001-sess001-architecture-analysis.md §root-cause):
+    // the coordinator-tick activity classifier writes
+    // `activity {status, confidence, rationale}` to the top-level
+    // `agents.<id>` slot of state.json (T1 invariant 60/61); the compact
+    // `status --json` projection MUST preserve it, last_output_at, and
+    // the enrich_agents-injected `interacted` marker. Lifecycle `status`
+    // and turn `activity.status` are separate fields per T1; the
+    // projection MUST NOT collapse them.
+    // =========================================================================
+    #[test]
+    fn rm039_stat001_compact_status_preserves_activity_last_output_and_interacted() {
+        let ws = seed_status_workspace();
+        let mut state = crate::state::persist::load_runtime_state(&ws).unwrap();
+        if let Some(agents) = state
+            .pointer_mut("/agents")
+            .and_then(serde_json::Value::as_object_mut)
+        {
+            if let Some(agent) = agents
+                .get_mut("a1")
+                .and_then(serde_json::Value::as_object_mut)
+            {
+                agent.insert(
+                    "activity".to_string(),
+                    json!({
+                        "status": "working",
+                        "confidence": 0.95,
+                        "rationale": "provider_jsonl:open_turn",
+                    }),
+                );
+                agent.insert(
+                    "last_output_at".to_string(),
+                    json!("2026-06-22T02:52:30+00:00"),
+                );
+                // first_send_at is already set by seed_status_workspace so
+                // enrich_agents will inject `interacted` with the same ISO value.
+            }
+        }
+        crate::state::persist::save_runtime_state(&ws, &state).unwrap();
+
+        let v = status_port::status(&ws, /*compact=*/ true, /*detail=*/ false)
+            .expect("compact status should project a value");
+        let agent = v
+            .pointer("/agents/a1")
+            .and_then(serde_json::Value::as_object)
+            .expect("seeded agent a1 must appear in compact projection");
+
+        // T1 split: lifecycle `status` stays unchanged.
+        assert_eq!(
+            agent.get("status").and_then(serde_json::Value::as_str),
+            Some("running"),
+            "RM-039-STAT-001: compact projection must NOT collapse `status` into `activity.status`"
+        );
+        // Turn activity preserved (the field that was historically dropped).
+        let activity = agent
+            .get("activity")
+            .expect("RM-039-STAT-001: compact projection must preserve `activity`");
+        assert_eq!(
+            activity.pointer("/status").and_then(serde_json::Value::as_str),
+            Some("working"),
+            "compact activity.status must survive the projection"
+        );
+        assert_eq!(
+            activity.pointer("/rationale").and_then(serde_json::Value::as_str),
+            Some("provider_jsonl:open_turn"),
+            "compact activity.rationale must survive the projection"
+        );
+        // last_output_at is the timestamp the classifier advances when
+        // scrollback digest changes; operators read it alongside activity.
+        assert_eq!(
+            agent.get("last_output_at").and_then(serde_json::Value::as_str),
+            Some("2026-06-22T02:52:30+00:00"),
+            "compact projection must preserve `last_output_at` for the \"is something moving\" view"
+        );
+        // enrich_agents injects `interacted` from first_send_at; the
+        // compact path must carry it (operators read it as a one-glance
+        // \"has the leader ever sent this worker a message?\" signal).
+        assert_eq!(
+            agent.get("interacted").and_then(serde_json::Value::as_str),
+            Some("2026-01-01T00:00:00Z"),
+            "compact projection must preserve `interacted` from enrich_agents"
+        );
+        let _ = std::fs::remove_dir_all(&ws);
+    }
+
+    // =========================================================================
+    // RM-039-STAT-001 second-round regression (architect verdict 2026-06-22).
+    //
+    // Real failure shape: tick wrote `activity` to root .agents.coder and
+    // .teams.current.agents.coder because `team_state_key` cascaded to the
+    // `team_dir = "./.team/current"` basename. But status's selector reads
+    // the `active_team_key = "rm039-status-working-891"` projection, which
+    // was stale. The compact whitelist alone cannot fix this — by the time
+    // compact_agent_state runs, the selected team slot already lacks activity.
+    //
+    // Fix expected at the projection/state-key layer: when load_runtime_state
+    // sees `active_team_key` naming an existing teams entry and no root
+    // `team_key`, it must promote `team_key = active_team_key` so subsequent
+    // tick writes and status reads agree on which teams entry to use. The
+    // assertion here drives the real CLI path through `status_port::status`.
+    // =========================================================================
+    #[test]
+    fn rm039_stat001_status_resolves_active_team_when_root_team_key_missing() {
+        let ws = seed_status_workspace();
+        // Seed the exact dirty shape from the evidence: active_team_key
+        // disagrees with team_dir basename; root team_key absent; the
+        // teams.<active> entry is stale (no activity); root + teams.current
+        // carry activity that the tick had already written there.
+        let active = "rm039-status-working-891";
+        let activity = json!({
+            "status": "working",
+            "confidence": 0.95,
+            "rationale": "provider_jsonl:open_turn",
+        });
+        let state = json!({
+            "session_name": "team-rm039-status-working",
+            "team_dir": "./.team/current",
+            "active_team_key": active,
+            // intentionally no top-level "team_key" — that is the bug shape.
+            "leader": {"id": "leader"},
+            "leader_receiver": {"pane_id": "%3", "status": "running"},
+            "agents": {
+                "coder": {
+                    "status": "running",
+                    "first_send_at": "2026-01-01T00:00:00Z",
+                    "activity": activity.clone(),
+                    "last_output_at": "2026-06-22T02:52:30+00:00",
+                }
+            },
+            "teams": {
+                "current": {
+                    "active_team_key": active,
+                    "session_name": "team-rm039-status-working",
+                    "agents": {
+                        "coder": {
+                            "status": "running",
+                            "first_send_at": "2026-01-01T00:00:00Z",
+                            "activity": activity.clone(),
+                        }
+                    }
+                },
+                active: {
+                    "active_team_key": active,
+                    "session_name": "team-rm039-status-working",
+                    "agents": {
+                        "coder": {
+                            "status": "running",
+                            "first_send_at": "2026-01-01T00:00:00Z",
+                            // NO `activity` here — this is the stale entry
+                            // that the selector landed on pre-fix.
+                        }
+                    }
+                }
+            }
+        });
+        std::fs::write(
+            ws.join(".team").join("runtime").join("state.json"),
+            serde_json::to_vec_pretty(&state).unwrap(),
+        )
+        .unwrap();
+
+        let v = status_port::status(&ws, /*compact=*/ true, /*detail=*/ false)
+            .expect("compact status should project a value");
+        let agent = v
+            .pointer("/agents/coder")
+            .and_then(serde_json::Value::as_object)
+            .expect("coder agent must appear in compact projection");
+        let got_activity = agent
+            .get("activity")
+            .expect("RM-039-STAT-001 second-round: activity must reach the compact projection \
+                     even when active_team_key disagrees with team_dir basename");
+        assert_eq!(
+            got_activity.pointer("/status").and_then(serde_json::Value::as_str),
+            Some("working"),
+            "RM-039-STAT-001 second-round: compact status.agents.coder.activity.status must \
+             be `working` when state.active_team_key names an existing teams entry, \
+             regardless of team_dir basename"
+        );
+        // Lifecycle status unchanged — T1 split invariant.
+        assert_eq!(
+            agent.get("status").and_then(serde_json::Value::as_str),
+            Some("running"),
+            "lifecycle status must NOT collapse into activity.status"
+        );
+        let _ = std::fs::remove_dir_all(&ws);
+    }
+
     #[test]
     fn status_port_status_compact_json_shape_against_seeded_fixture() {
         // cmd_status json branch (detail=false) delegates status_port::status(compact=true).

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

@@ -140,6 +140,7 @@ fn settle_success_json_byte_shape_wraps_collect() {
     seed_settle_workspace(&ws);
 
     let result = cmd_settle(&SettleArgs {
+        team: None,
         workspace: ws.clone(),
         json: true,
     })
@@ -204,6 +205,7 @@ fn settle_success_human_output_insertion_order() {
     seed_settle_workspace(&ws);
 
     let result = cmd_settle(&SettleArgs {
+        team: None,
         workspace: ws.clone(),
         json: false,
     })

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

@@ -614,6 +614,11 @@ pub struct CollectArgs {
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct SettleArgs {
     pub workspace: PathBuf,
+    /// Bug #6 (prerelease 0.4.0 gate review): explicit team scope. When
+    /// `Some`, settle scopes collect/status/team-state to this team via
+    /// `resolve_active_team(workspace, Some(team), ...)`. When `None`,
+    /// the selector falls back to top-level `active_team_key` (legacy).
+    pub team: Option<String>,
     pub json: bool,
 }
 

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

@@ -66,6 +66,7 @@ pub mod health;
 pub mod orphan;
 pub mod runtime_detectors;
 pub mod runtime_observation;
+pub mod steps;
 pub mod tick;
 pub mod types;
 

package/crates/team-agent/src/coordinator/steps/abnormal.rs

@@ -0,0 +1,4 @@
+//! unit-11 (Stage 4) — coordinator tick `abnormal` step group.
+//!
+//! Future home for abnormal-exit detection + classification steps from
+//! `coordinator/tick.rs`.

package/crates/team-agent/src/coordinator/steps/delivery.rs

@@ -0,0 +1,4 @@
+//! unit-11 (Stage 4) — coordinator tick `delivery` step group.
+//!
+//! Future home for the message-delivery FSM ticks from
+//! `coordinator/tick.rs`.

package/crates/team-agent/src/coordinator/steps/health_sync.rs

@@ -0,0 +1,4 @@
+//! unit-11 (Stage 4) — coordinator tick `health_sync` step group.
+//!
+//! Future home for worker-liveness reconciliation steps from
+//! `coordinator/tick.rs`.

package/crates/team-agent/src/coordinator/steps/mod.rs

@@ -0,0 +1,83 @@
+//! unit-11 (Stage 4) — coordinator tick steps namespace.
+//!
+//! The 3083 LOC `coordinator/tick.rs` orchestrator runs an ordered
+//! sequence of step groups per tick. This module establishes a named
+//! home for each group so future commits migrate them in small,
+//! reviewable pieces. The orchestrator stays in `tick.rs`; this is the
+//! boundary for the upcoming step relocations.
+//!
+//! Step groups (canonical order):
+//!   1. `session_gate`     — provider session capture + readiness gates
+//!   2. `health_sync`      — worker liveness + reconciliation
+//!   3. `delivery`         — message delivery FSM ticks
+//!   4. `runtime_prompts`  — startup / approval / abnormal-exit prompts
+//!   5. `abnormal`         — abnormal-exit detection + classification
+//!   6. `persist`          — durable state persistence at tick end
+
+pub mod abnormal;
+pub mod delivery;
+pub mod health_sync;
+pub mod persist;
+pub mod runtime_prompts;
+pub mod session_gate;
+
+/// Canonical ordering of tick step groups. The orchestrator must invoke
+/// steps in this order so persisted state reflects every earlier step's
+/// outcome.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum TickStepGroup {
+    SessionGate,
+    HealthSync,
+    Delivery,
+    RuntimePrompts,
+    Abnormal,
+    Persist,
+}
+
+impl TickStepGroup {
+    /// Stable label used in event-log and metric fields.
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::SessionGate => "tick.session_gate",
+            Self::HealthSync => "tick.health_sync",
+            Self::Delivery => "tick.delivery",
+            Self::RuntimePrompts => "tick.runtime_prompts",
+            Self::Abnormal => "tick.abnormal",
+            Self::Persist => "tick.persist",
+        }
+    }
+
+    /// Canonical ordering as a const slice — exhaustive over the enum.
+    pub fn ordered() -> &'static [TickStepGroup] {
+        &[
+            TickStepGroup::SessionGate,
+            TickStepGroup::HealthSync,
+            TickStepGroup::Delivery,
+            TickStepGroup::RuntimePrompts,
+            TickStepGroup::Abnormal,
+            TickStepGroup::Persist,
+        ]
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn ordered_groups_cover_every_variant() {
+        let ordered = TickStepGroup::ordered();
+        assert_eq!(ordered.len(), 6);
+        // Persist is last (state writes follow every other step).
+        assert_eq!(*ordered.last().unwrap(), TickStepGroup::Persist);
+        // SessionGate is first (downstream steps depend on it).
+        assert_eq!(*ordered.first().unwrap(), TickStepGroup::SessionGate);
+    }
+
+    #[test]
+    fn labels_are_dotted_paths_under_tick() {
+        for g in TickStepGroup::ordered() {
+            assert!(g.as_str().starts_with("tick."));
+        }
+    }
+}

package/crates/team-agent/src/coordinator/steps/persist.rs

@@ -0,0 +1,4 @@
+//! unit-11 (Stage 4) — coordinator tick `persist` step group.
+//!
+//! Future home for the durable state-persistence step at the end of each
+//! tick (currently inlined in `coordinator/tick.rs`).

package/crates/team-agent/src/coordinator/steps/runtime_prompts.rs

@@ -0,0 +1,4 @@
+//! unit-11 (Stage 4) — coordinator tick `runtime_prompts` step group.
+//!
+//! Future home for the startup / approval / abnormal-exit prompt steps
+//! from `coordinator/tick.rs`.

package/crates/team-agent/src/coordinator/steps/session_gate.rs

@@ -0,0 +1,5 @@
+//! unit-11 (Stage 4) — coordinator tick `session_gate` step group.
+//!
+//! Future home for the provider session-capture + readiness-gate steps
+//! currently inlined in `coordinator/tick.rs`. Boundary established by
+//! unit-11; actual relocation lands in follow-up commits.