@team-agent/installer 0.2.10 → 0.3.0

package/crates/team-agent/src/coordinator/tests/basics.rs

@@ -0,0 +1,262 @@
+use super::*;
+
+// ═════════════════════════════════════════════════════════════════════════
+// GROUP A — typed-enum / event byte-lock (committed model derive; GREEN baseline)
+// 这些钉死 serde 契约,确保 events.jsonl 字节不漂移(§3/§22)。
+// ═════════════════════════════════════════════════════════════════════════
+
+#[test]
+fn protocol_version_is_two() {
+    // metadata.py:13 COORDINATOR_PROTOCOL_VERSION = 2
+    assert_eq!(PROTOCOL_VERSION, 2);
+}
+
+#[test]
+fn default_tick_interval_is_five_seconds() {
+    // __main__.py:101 DEFAULT_TICK_INTERVAL_SEC = 5.0 (Gap 36c)
+    assert_eq!(DEFAULT_TICK_INTERVAL_SEC, 5.0);
+    assert_eq!(BACKOFF_MAX_SEC, 60.0);
+}
+
+#[test]
+fn rotation_marker_is_byte_exact() {
+    // watch.py:22 — byte-for-byte (note the U+2014 em dash).
+    assert_eq!(
+        ROTATION_MARKER,
+        "[watch] log rotated; archived segment events.jsonl.1 not replayed — historical replay deferred to a future --replay flag"
+    );
+}
+
+#[test]
+fn status_enums_serialize_to_exact_python_strings() {
+    let cases: &[(String, &str)] = &[
+        (serde_json::to_string(&CoordinatorHealthStatus::Missing).unwrap(), "\"missing\""),
+        (serde_json::to_string(&CoordinatorHealthStatus::InvalidPid).unwrap(), "\"invalid_pid\""),
+        (serde_json::to_string(&CoordinatorHealthStatus::Running).unwrap(), "\"running\""),
+        (serde_json::to_string(&CoordinatorHealthStatus::Stale).unwrap(), "\"stale\""),
+        (serde_json::to_string(&StartOutcome::AlreadyRunning).unwrap(), "\"already_running\""),
+        (serde_json::to_string(&StartOutcome::RestartIncompatibleStopFailed).unwrap(), "\"restart_incompatible_stop_failed\""),
+        (serde_json::to_string(&StartOutcome::SchemaIncompatible).unwrap(), "\"schema_incompatible\""),
+        (serde_json::to_string(&StartOutcome::Started).unwrap(), "\"started\""),
+        (serde_json::to_string(&StopOutcome::Missing).unwrap(), "\"missing\""),
+        (serde_json::to_string(&StopOutcome::InvalidPidRemoved).unwrap(), "\"invalid_pid_removed\""),
+        (serde_json::to_string(&StopOutcome::KillFailed).unwrap(), "\"kill_failed\""),
+        (serde_json::to_string(&StopOutcome::Stopped).unwrap(), "\"stopped\""),
+        (serde_json::to_string(&TickStopReason::TmuxSessionMissing).unwrap(), "\"tmux_session_missing\""),
+        (serde_json::to_string(&TickStopReason::PersistenceDegraded).unwrap(), "\"persistence_degraded\""),
+        (serde_json::to_string(&MetadataSource::Boot).unwrap(), "\"boot\""),
+        (serde_json::to_string(&MetadataSource::Start).unwrap(), "\"start\""),
+        (serde_json::to_string(&AbnormalDecision::Skip).unwrap(), "\"skip\""),
+        (serde_json::to_string(&AbnormalDecision::NotifyBlacklist).unwrap(), "\"notify_blacklist\""),
+        (serde_json::to_string(&AbnormalDecision::NotifyDefault).unwrap(), "\"notify_default\""),
+        (serde_json::to_string(&WholeTeamGoneClass::Alive).unwrap(), "\"alive\""),
+        (serde_json::to_string(&WholeTeamGoneClass::CleanShutdown).unwrap(), "\"clean_shutdown\""),
+        (serde_json::to_string(&WholeTeamGoneClass::RestartInProgress).unwrap(), "\"restart_in_progress\""),
+        (serde_json::to_string(&WholeTeamGoneClass::UnexpectedExit).unwrap(), "\"unexpected_exit\""),
+    ];
+    for (got, want) in cases {
+        assert_eq!(got, want);
+    }
+}
+
+#[test]
+fn coordinator_event_tags_are_byte_stable() {
+    // 逐一钉 events.jsonl tag(events.py 稳定契约)。
+    let pid = Pid(4242);
+    let cases: Vec<(CoordinatorEvent, &str)> = vec![
+        (CoordinatorEvent::Boot { workspace: "/w".into(), once: true }, "coordinator.boot"),
+        (CoordinatorEvent::Started { pid, log: "/l".into() }, "coordinator.started"),
+        (CoordinatorEvent::Stopped { pid }, "coordinator.stopped"),
+        (CoordinatorEvent::Exit { stop: true }, "coordinator.exit"),
+        (CoordinatorEvent::SessionMissing { session: "s".into() }, "coordinator.session_missing"),
+        (
+            CoordinatorEvent::OrphanSelfTerminate { initial_ppid: 9, current_ppid: 1, workspace: "/w".into() },
+            "coordinator.orphan_self_terminate",
+        ),
+        (
+            CoordinatorEvent::TickError { error: "boom".into(), exc_type: "OSError".into(), consecutive_failures: 1, next_sleep_sec: 5.0 },
+            "coordinator.tick_error",
+        ),
+        (
+            CoordinatorEvent::TickErrorSuppressed { consecutive_failures: 2, next_sleep_sec: 10.0 },
+            "coordinator.tick_error.suppressed",
+        ),
+        (CoordinatorEvent::TickRecovered { consecutive_failures: 3 }, "coordinator.tick_recovered"),
+        (
+            CoordinatorEvent::RestartIncompatible { pid: Some(pid), expected_protocol: 2, expected_schema: 3 },
+            "coordinator.restart_incompatible",
+        ),
+        (
+            CoordinatorEvent::RestartIncompatibleStopFailed { pid: Some(pid) },
+            "coordinator.restart_incompatible_stop_failed",
+        ),
+        (
+            CoordinatorEvent::SchemaIncompatible { table: Some("messages".into()), missing_columns: vec!["owner_team_id".into()] },
+            "coordinator.schema_incompatible",
+        ),
+        (
+            CoordinatorEvent::IdleTakeoverUnknownPersistent {
+                node_id: "w1".into(),
+                provider: Some(Provider::Codex),
+                auth_mode: None,
+                consecutive_ticks: 60,
+                rollout_path: None,
+            },
+            "idle_takeover.unknown_persistent",
+        ),
+        (
+            CoordinatorEvent::AbnormalNotify { signature: "sig".into(), turn_id: None, decision: AbnormalDecision::NotifyDefault },
+            "abnormal.notify",
+        ),
+        (
+            CoordinatorEvent::AbnormalWholeTeamGone { classification: WholeTeamGoneClass::UnexpectedExit },
+            "abnormal.whole_team_gone",
+        ),
+        (CoordinatorEvent::LeaderNotificationLogPruned { removed: 7 }, "leader_notification.log_pruned"),
+        (CoordinatorEvent::LeaderNotificationPruneFailed { error: "io".into() }, "leader_notification.prune_failed"),
+        (
+            CoordinatorEvent::RuntimeStateSaveFailed { phase: "tick_end".into(), error: "replace".into(), exc_type: "OSError".into() },
+            "runtime.state.save_failed",
+        ),
+    ];
+    for (evt, want_tag) in &cases {
+        let json = serde_json::to_value(evt).unwrap();
+        assert_eq!(json["event"], *want_tag, "tag mismatch for {want_tag}");
+    }
+}
+
+#[test]
+fn tick_error_event_carries_exact_python_fields() {
+    // __main__.py:69-74 — error / exc_type / consecutive_failures / next_sleep_sec.
+    let evt = CoordinatorEvent::TickError {
+        error: "os.replace failed".into(),
+        exc_type: "OSError".into(),
+        consecutive_failures: 4,
+        next_sleep_sec: 40.0,
+    };
+    let json = serde_json::to_value(&evt).unwrap();
+    assert_eq!(json["event"], "coordinator.tick_error");
+    assert_eq!(json["error"], "os.replace failed");
+    assert_eq!(json["exc_type"], "OSError");
+    assert_eq!(json["consecutive_failures"], 4);
+    assert_eq!(json["next_sleep_sec"], 40.0);
+}
+
+#[test]
+fn unknown_persistent_event_provider_none_is_null_not_missing() {
+    // lifecycle.py:407 rollout_path=node.get(...) — None 漏穿堵死(bug-085):
+    // provider/rollout_path 缺失序列化为 JSON null,绝不省略键。
+    let evt = CoordinatorEvent::IdleTakeoverUnknownPersistent {
+        node_id: "w7".into(),
+        provider: None,
+        auth_mode: None,
+        consecutive_ticks: 72,
+        rollout_path: None,
+    };
+    let json = serde_json::to_value(&evt).unwrap();
+    assert_eq!(json["event"], "idle_takeover.unknown_persistent");
+    assert_eq!(json["node_id"], "w7");
+    assert!(json.get("provider").is_some(), "provider key MUST be present (None→null)");
+    assert!(json["provider"].is_null(), "provider None → JSON null");
+    assert!(json.get("auth_mode").is_some(), "auth_mode key MUST be present");
+    assert!(json["auth_mode"].is_null(), "auth_mode None → JSON null");
+    assert!(json.get("rollout_path").is_some(), "rollout_path key MUST be present");
+    assert!(json["rollout_path"].is_null());
+    assert_eq!(json["consecutive_ticks"], 72);
+}
+
+#[test]
+fn coordinator_metadata_json_field_names_are_stable() {
+    // metadata.py:50-57 — 稳定 coordinator.json 契约。
+    let m = meta(123, PROTOCOL_VERSION, GOLDEN_SCHEMA_VERSION);
+    let json = serde_json::to_value(&m).unwrap();
+    assert_eq!(json["pid"], 123);
+    assert_eq!(json["protocol_version"], 2);
+    assert_eq!(json["message_store_schema_version"], 3);
+    assert_eq!(json["source"], "boot");
+    assert_eq!(json["updated_at"], "2026-06-02T00:00:00+00:00");
+}
+
+// ═════════════════════════════════════════════════════════════════════════
+// GROUP B — pure functions (backoff / orphan / metadata_ok) — RED via unimplemented!()
+// ═════════════════════════════════════════════════════════════════════════
+
+#[test]
+fn backoff_sequence_is_5_10_20_40_60_60() {
+    // __main__.py:65 min(interval * 2^min(failures-1, 5), 60.0). interval=5.0.
+    // Golden (probe): [5, 10, 20, 40, 60, 60, 60, ...].
+    assert_eq!(backoff_sleep_sec(5.0, 1), 5.0);
+    assert_eq!(backoff_sleep_sec(5.0, 2), 10.0);
+    assert_eq!(backoff_sleep_sec(5.0, 3), 20.0);
+    assert_eq!(backoff_sleep_sec(5.0, 4), 40.0);
+    assert_eq!(backoff_sleep_sec(5.0, 5), 60.0);
+    assert_eq!(backoff_sleep_sec(5.0, 6), 60.0);
+    assert_eq!(backoff_sleep_sec(5.0, 9), 60.0);
+}
+
+#[test]
+fn backoff_caps_at_60_even_with_large_interval() {
+    // min(.., 60.0) — interval 30 → 30,60,(cap)60...
+    assert_eq!(backoff_sleep_sec(30.0, 1), 30.0);
+    assert_eq!(backoff_sleep_sec(30.0, 2), 60.0);
+    assert_eq!(backoff_sleep_sec(30.0, 7), 60.0);
+}
+
+#[test]
+fn orphan_self_terminate_requires_all_three_conditions() {
+    // __main__.py:52 — current_ppid != initial_ppid ∧ current_ppid == 1 ∧ !workspace.exists().
+    let missing = WorkspacePath::new("/tmp/team-agent-NONEXISTENT-coord-orphan-xyz");
+    // 全三成立 → true.
+    assert!(should_orphan_self_terminate(9000, 1, &missing));
+    // ppid 未变(== initial)→ false,即便 ppid==1 且 workspace 不存在。
+    assert!(!should_orphan_self_terminate(1, 1, &missing));
+    // ppid != 1(被正常 supervisor 收养)→ false。
+    assert!(!should_orphan_self_terminate(9000, 4242, &missing));
+}
+
+#[test]
+fn orphan_self_terminate_false_when_workspace_exists() {
+    // workspace 仍在磁盘 → 绝不自杀,即便 ppid 变成 1(card §91)。
+    let alive = WorkspacePath::new("/tmp"); // /tmp 存在
+    assert!(!should_orphan_self_terminate(9000, 1, &alive));
+}
+
+#[test]
+fn metadata_ok_requires_all_three_to_match() {
+    // metadata.py:37-43 — pid ∧ protocol_version==2 ∧ schema_version==3.
+    let good = meta(555, PROTOCOL_VERSION, GOLDEN_SCHEMA_VERSION);
+    assert!(coordinator_metadata_ok(Some(&good), Pid(555)));
+    // pid 不符 → false。
+    assert!(!coordinator_metadata_ok(Some(&good), Pid(999)));
+    // protocol_version 不符(bump 触发 restart_incompatible)→ false。
+    let bad_proto = meta(555, 1, GOLDEN_SCHEMA_VERSION);
+    assert!(!coordinator_metadata_ok(Some(&bad_proto), Pid(555)));
+    // schema_version 不符 → false(不可静默继续旧 schema 写库,card §89)。
+    let bad_schema = meta(555, PROTOCOL_VERSION, 2);
+    assert!(!coordinator_metadata_ok(Some(&bad_schema), Pid(555)));
+}
+
+#[test]
+fn metadata_ok_none_is_false() {
+    // metadata.py:38 — bool(metadata and ...) — None → False.
+    assert!(!coordinator_metadata_ok(None, Pid(1)));
+}
+
+// ═════════════════════════════════════════════════════════════════════════
+// GROUP C — paths (paths.py) — RED
+// ═════════════════════════════════════════════════════════════════════════
+
+#[test]
+fn coordinator_paths_end_with_expected_filenames() {
+    // paths.py:8-17 — runtime_dir(ws)/coordinator.{pid,json,log}.
+    let w = ws();
+    assert!(coordinator_pid_path(&w).ends_with("coordinator.pid"));
+    assert!(coordinator_meta_path(&w).ends_with("coordinator.json"));
+    assert!(coordinator_log_path(&w).ends_with("coordinator.log"));
+}
+
+// NOTE: schema_health / health / start / stop / tick are `&self` methods on
+// `Coordinator`. They are NO LONGER deferred: `Coordinator::for_test` (a #[cfg(test)]
+// constructor) + the local `MockTransport` (all ~15 Transport methods stubbed, recording
+// calls) + `MockRegistry` give a fully constructible Coordinator. Their behavior contracts
+// are ASSERTED in GROUP I/J below (RED via the unimplemented production bodies).

package/crates/team-agent/src/coordinator/tests/daemon.rs

@@ -0,0 +1,323 @@
+use super::*;
+
+// ═════════════════════════════════════════════════════════════════════════
+// (B) coordinator daemon — health gate + idempotent start_coordinator + --once daemon boot.
+// coordinator_health / start_coordinator are unimplemented!() skeletons (panic today = RED). Golden
+// coordinator/lifecycle.py:28-121. HARD: no in-process test spawns a real daemon — the spawn /
+// multi-tick / real-Coordinator paths are #[ignore] real-machine.
+// ═════════════════════════════════════════════════════════════════════════
+
+/// A unique workspace with the db schema created (so coordinator_health's schema_ok can be true) and
+/// the runtime dir present (so coordinator.pid / coordinator.json writes land).
+fn daemon_ws() -> (WorkspacePath, std::path::PathBuf) {
+    use std::sync::atomic::{AtomicU64, Ordering};
+    static N: AtomicU64 = AtomicU64::new(0);
+    let dir = std::env::temp_dir().join(format!("ta-rs-daemon-{}-{}", std::process::id(), N.fetch_add(1, Ordering::Relaxed)));
+    std::fs::create_dir_all(crate::model::paths::runtime_dir(&dir)).unwrap();
+    let _ = crate::message_store::MessageStore::open(&dir).unwrap(); // create the schema (schema_ok)
+    (WorkspacePath::new(dir.clone()), dir)
+}
+
+// coordinator_health (lifecycle.py:28-46): pid_path missing -> ok:false / status missing.
+#[test]
+fn coordinator_health_missing_pid_is_not_ok() {
+    let (wp, _dir) = daemon_ws();
+    let h = coordinator_health(&wp);
+    assert!(!h.ok, "no coordinator.pid -> not healthy");
+    assert_eq!(h.status, CoordinatorHealthStatus::Missing);
+}
+
+// coordinator_health: pid running (this process) + metadata pid/protocol/schema all match -> healthy.
+#[test]
+fn coordinator_health_running_with_matching_metadata_is_ok() {
+    let (wp, _dir) = daemon_ws();
+    let me = Pid(std::process::id());
+    write_coordinator_metadata(&wp, me, MetadataSource::Boot).unwrap();
+    std::fs::write(coordinator_pid_path(&wp), me.0.to_string()).unwrap();
+    let h = coordinator_health(&wp);
+    assert_eq!(h.status, CoordinatorHealthStatus::Running, "a live pid -> status running");
+    assert!(h.metadata_ok, "pid+protocol+schema all match -> metadata_ok");
+    assert!(h.ok, "running ∧ metadata_ok ∧ schema_ok -> healthy");
+}
+
+// coordinator_health: a pid that is NOT running -> ok:false / status stale (stale != missing).
+#[test]
+fn coordinator_health_dead_pid_is_stale_not_ok() {
+    let (wp, _dir) = daemon_ws();
+    let dead = Pid(4_000_000); // far above the macOS/Linux pid ceiling -> kill(pid,0)=ESRCH -> not running
+    write_coordinator_metadata(&wp, dead, MetadataSource::Boot).unwrap();
+    std::fs::write(coordinator_pid_path(&wp), dead.0.to_string()).unwrap();
+    let h = coordinator_health(&wp);
+    assert_eq!(h.status, CoordinatorHealthStatus::Stale, "a dead pid -> status stale");
+    assert!(!h.ok, "a stale daemon is not healthy");
+}
+
+// start_coordinator (lifecycle.py:49-54) IDEMPOTENT: already-healthy -> AlreadyRunning no-op, NO spawn.
+#[test]
+fn start_coordinator_when_healthy_is_already_running_no_spawn() {
+    let (wp, _dir) = daemon_ws();
+    let me = Pid(std::process::id());
+    write_coordinator_metadata(&wp, me, MetadataSource::Boot).unwrap();
+    std::fs::write(coordinator_pid_path(&wp), me.0.to_string()).unwrap();
+    let report = start_coordinator(&wp).expect("start_coordinator");
+    assert_eq!(report.status, StartOutcome::AlreadyRunning, "a healthy coordinator -> AlreadyRunning (no spawn)");
+    assert!(report.ok);
+    assert_eq!(report.pid, Some(me));
+}
+
+// start_coordinator: a fresh workspace DECIDES Started. The actual `team-agent coordinator` daemon
+// subprocess spawn is the real-machine boundary (#[ignore]).
+#[test]
+#[ignore = "real-machine: start_coordinator spawns the `team-agent coordinator` daemon subprocess"]
+fn start_coordinator_fresh_workspace_decides_started() {
+    let (wp, _dir) = daemon_ws();
+    let report = start_coordinator(&wp).expect("start_coordinator");
+    assert_eq!(report.status, StartOutcome::Started);
+    assert!(report.ok && report.pid.is_some());
+}
+
+// run_daemon --once: writes the boot pid/metadata + runs exactly one tick + returns Ok. run_daemon
+// constructs a real Coordinator (TmuxBackend) internally with NO injection seam, so a single tick
+// would touch real tmux — #[ignore] real-machine until a run_daemon_with_coordinator(args, coord) seam
+// (mirroring lifecycle::launch_with_transport) exists. SURFACED to the leader.
+#[test]
+#[ignore = "real-machine: run_daemon builds a real Coordinator (TmuxBackend); needs a \
+            run_daemon_with_coordinator(args, coord) seam (mirror launch_with_transport) for OS-safe \
+            single-tick testing"]
+fn run_daemon_once_writes_boot_metadata_and_returns_ok() {
+    let (wp, dir) = daemon_ws();
+    crate::state::persist::save_runtime_state(&dir, &serde_json::json!({"session_name": "team-x", "agents": {}})).unwrap();
+    let r = run_daemon(DaemonArgs { workspace: wp.clone(), once: true, tick_interval_sec: None });
+    assert!(r.is_ok(), "run_daemon --once must return Ok; got {r:?}");
+    assert!(coordinator_meta_path(&wp).exists(), "run_daemon must write the coordinator boot metadata");
+}
+
+// ═════════════════════════════════════════════════════════════════════════
+// HOST-B P1 — coordinator transient-session race (timeout-tolerated vs definitive-stop fork).
+//
+// GOLDEN (truth source, settle by it):
+//   - terminal.py:12-13   run_cmd(args, timeout=timeout, check=False)
+//   - runtime.py:1010-14  _tmux_session_exists -> run_cmd(["tmux","has-session","-t",s], timeout=5);
+//                         return proc.returncode == 0
+//   - lifecycle.py:276-9  if session_name and not _tmux_session_exists(name):
+//                             emit coordinator.session_missing; return {ok:False, stop:True,
+//                             reason:"tmux_session_missing"}        # stops on the FIRST definitive miss
+//   - __main__.py:60-97   a tick that RAISES (`except Exception`) -> exponential backoff + retry +
+//                         (on the next clean tick) coordinator.tick_recovered  [TOLERATED];
+//                         a tick that returns stop -> break (then coordinator.exit).
+//
+// THE CRUX: golden's ONLY tolerance for a transient session-missing is the 5s subprocess timeout.
+//   - SLOW/HUNG has-session (>5s) -> subprocess.TimeoutExpired -> daemon `except` -> backoff + retry
+//     (server recovers -> next tick fine). In Rust the timeout surfaces from RealCommandRunner as
+//     io::ErrorKind::TimedOut -> TmuxBackend::has_session maps it to a TransportError (NOT Ok(false))
+//     -> Coordinator::tick() returns Err (a TOLERATED error the daemon backs off on).
+//   - FAST DEFINITIVE non-zero (session genuinely gone) -> returncode != 0 -> has_session=false ->
+//     tick() returns Ok{stop:true, reason:tmux_session_missing}. A genuine miss MUST still stop.
+//   NO grace-window, NO K-consecutive counting: slow=tolerated(retry), genuine-fast-miss=stop.
+//
+// These three are REGRESSION-LOCKS, not REDs: the tick/backend mapping (`?` propagation) and the
+// daemon backoff/recover loop are ALREADY correct today. The actual gap is purely in
+// RealCommandRunner::run lacking the 5s timeout (the #[ignore] real-machine RED lives in
+// tmux_backend.rs::real_command_runner_enforces_golden_5s_timeout_on_hang). These locks guard the
+// tick/daemon semantics from regressing when the porter adds that timeout seam.
+// ═════════════════════════════════════════════════════════════════════════
+
+/// A staged tmux `CommandRunner` for the transient-session-race fork. Each `run` pops the next
+/// staged step (then repeats `last`): `Timeout` models a >5s hung has-session that the golden 5s
+/// subprocess timeout converts into `io::ErrorKind::TimedOut`; `Exit(success)` models a definitive
+/// tmux exit (`success=false` => session genuinely gone). Records every argv it is asked to run so a
+/// test can assert the probe was exactly `tmux has-session -t <s>`.
+#[derive(Clone)]
+enum RunnerStep {
+    /// >5s hang -> RealCommandRunner returns Err(TimedOut) (golden subprocess.TimeoutExpired).
+    Timeout,
+    /// fast definitive tmux exit; `false` => returncode!=0 => session genuinely gone.
+    Exit(bool),
+}
+
+struct StagedTmuxRunner {
+    steps: std::sync::Mutex<std::collections::VecDeque<RunnerStep>>,
+    last: RunnerStep,
+    seen: std::sync::Arc<std::sync::Mutex<Vec<Vec<String>>>>,
+}
+
+impl crate::tmux_backend::CommandRunner for StagedTmuxRunner {
+    fn run(&self, argv: &[String]) -> Result<crate::tmux_backend::CommandOutput, std::io::Error> {
+        self.seen.lock().unwrap().push(argv.to_vec());
+        let step = self
+            .steps
+            .lock()
+            .unwrap()
+            .pop_front()
+            .unwrap_or_else(|| self.last.clone());
+        match step {
+            RunnerStep::Timeout => Err(std::io::Error::new(
+                std::io::ErrorKind::TimedOut,
+                "tmux has-session exceeded the golden 5s timeout (subprocess.TimeoutExpired analog)",
+            )),
+            RunnerStep::Exit(success) => Ok(crate::tmux_backend::CommandOutput {
+                success,
+                code: Some(if success { 0 } else { 1 }),
+                stdout: String::new(),
+                stderr: if success { String::new() } else { "can't find session".to_string() },
+            }),
+        }
+    }
+}
+
+/// Build a real `Coordinator` over a real `TmuxBackend` whose OS edge is the staged runner above,
+/// seeding a TRUTHY `session_name` so the tmux-session gate actually runs. Returns
+/// `(coord, workspace_dir, recorded_argv)`. The workspace + schema mirror `daemon_ws`.
+fn coord_over_staged_tmux(
+    session_name: &str,
+    steps: Vec<RunnerStep>,
+    last: RunnerStep,
+) -> (
+    Coordinator,
+    std::path::PathBuf,
+    std::sync::Arc<std::sync::Mutex<Vec<Vec<String>>>>,
+) {
+    use std::sync::atomic::{AtomicU64, Ordering};
+    static N: AtomicU64 = AtomicU64::new(0);
+    let dir = std::env::temp_dir().join(format!(
+        "ta-rs-coord-session-race-{}-{}",
+        std::process::id(),
+        N.fetch_add(1, Ordering::Relaxed)
+    ));
+    std::fs::create_dir_all(crate::model::paths::runtime_dir(&dir)).unwrap();
+    let _ = crate::message_store::MessageStore::open(&dir).unwrap(); // create the schema
+    crate::state::persist::save_runtime_state(
+        &dir,
+        &serde_json::json!({ "session_name": session_name }),
+    )
+    .unwrap();
+    let seen = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
+    let runner = StagedTmuxRunner {
+        steps: std::sync::Mutex::new(steps.into_iter().collect()),
+        last,
+        seen: std::sync::Arc::clone(&seen),
+    };
+    let backend = crate::tmux_backend::TmuxBackend::with_runner(Box::new(runner));
+    let reg: Box<dyn ProviderRegistry> = Box::new(MockRegistry::new(&[], &[]));
+    let coord = Coordinator::for_test(
+        WorkspacePath::new(dir.clone()),
+        reg,
+        Box::new(backend),
+        None,
+        None,
+    );
+    (coord, dir, seen)
+}
+
+// ── 2(a) tick TOLERATES a has-session TIMEOUT as Err (NOT a definitive miss) — LOCK ───────────────
+#[test]
+fn tick_tolerates_has_session_timeout_as_transport_err_not_session_missing() {
+    // A has-session that times out (>5s) surfaces as io::ErrorKind::TimedOut from RealCommandRunner.
+    // TmuxBackend::has_session maps the runner io::Error to a TransportError (NOT Ok(false)), and
+    // Coordinator::tick() propagates it via `?` as TickError::Transport — a TOLERATED error the
+    // daemon backs off on. It must NEVER be read as Ok{stop:true, reason:tmux_session_missing}.
+    // LOCK (already GREEN via `?` propagation): guards this from regressing when the 5s timeout seam
+    // is added to RealCommandRunner.
+    let (coord, _dir, seen) =
+        coord_over_staged_tmux("team-spine", vec![RunnerStep::Timeout], RunnerStep::Timeout);
+    let err = coord.tick().expect_err(
+        "a has-session TIMEOUT is a tolerated transport Err (daemon backs off), NOT a definitive \
+         session-missing stop",
+    );
+    assert!(
+        matches!(err, TickError::Transport(_)),
+        "a transient has-session timeout must surface as TickError::Transport (tolerated/backoff); got {err:?}"
+    );
+    let calls = seen.lock().unwrap().clone();
+    assert_eq!(
+        calls.len(),
+        1,
+        "tick must short-circuit at the gate on a has-session error (exactly one probe); got {calls:?}"
+    );
+    assert_eq!(
+        calls[0],
+        vec![
+            "tmux".to_string(),
+            "has-session".to_string(),
+            "-t".to_string(),
+            "team-spine".to_string(),
+        ],
+        "the tolerated error must come from the golden `tmux has-session -t <s>` probe"
+    );
+}
+
+// ── 2(b) a FAST DEFINITIVE has-session miss STILL stops — LOCK (byte-parity) ──────────────────────
+#[test]
+fn tick_genuine_fast_session_miss_still_stops() {
+    // lifecycle.py:277-279 — a FAST definitive non-zero has-session (returncode != 0 => session
+    // genuinely gone) => {ok:false, stop:true, reason:tmux_session_missing}. The OTHER side of the
+    // fork from the timeout case: a definitive miss MUST still stop the daemon. LOCK (already GREEN):
+    // guards the genuine-miss stop from being swallowed when the timeout tolerance is added.
+    let (coord, _dir, _seen) =
+        coord_over_staged_tmux("team-spine", vec![RunnerStep::Exit(false)], RunnerStep::Exit(false));
+    let report = coord
+        .tick()
+        .expect("a definitive miss is a typed stop report, not an Err");
+    assert!(!report.ok, "a definitive session miss => ok=false");
+    assert!(
+        report.stop,
+        "a FAST definitive has-session miss still stops the daemon (byte-parity, lifecycle.py:279)"
+    );
+    assert_eq!(
+        report.reason,
+        Some(TickStopReason::TmuxSessionMissing),
+        "reason=tmux_session_missing"
+    );
+}
+
+// ── 3. daemon TOLERATES a transient tick Err: backoff + recover, NO exit on the error — LOCK ──────
+#[test]
+fn run_daemon_backs_off_on_transient_tick_err_then_recovers_without_exiting() {
+    // __main__.py:60-97 — a tick that RAISES is caught, logged as coordinator.tick_error, and the
+    // loop BACKS OFF + retries (it does NOT break/exit on the error); the next clean tick logs
+    // coordinator.tick_recovered. Here: tick #1's has-session TIMES OUT (TimedOut -> tick Err ->
+    // tolerated), tick #2's has-session is a definitive miss (-> Ok{stop:true} -> the loop breaks on
+    // the GENUINE stop, after recovering). The healthy daemon must NOT be torn down by the transient
+    // timeout. LOCK (the daemon backoff loop is already wired): guards the tolerate+recover path.
+    let (coord, dir, _seen) = coord_over_staged_tmux(
+        "team-spine",
+        vec![RunnerStep::Timeout, RunnerStep::Exit(false)],
+        RunnerStep::Exit(false),
+    );
+    let args = DaemonArgs {
+        workspace: WorkspacePath::new(dir.clone()),
+        once: false,
+        tick_interval_sec: Some(0.01), // tiny backoff so the test is fast
+    };
+    let result = run_daemon_with_coordinator(&args, &coord);
+    assert!(
+        result.is_ok(),
+        "a single transient has-session timeout must NOT abort the daemon; got {result:?}"
+    );
+    let events = read_event_log_dir(&dir);
+    let tags: Vec<&str> = events
+        .iter()
+        .filter_map(|e| e.get("event").and_then(|v| v.as_str()))
+        .collect();
+    let err_idx = tags
+        .iter()
+        .position(|t| *t == "coordinator.tick_error")
+        .unwrap_or_else(|| panic!("a transient tick Err must log coordinator.tick_error; got {tags:?}"));
+    let rec_idx = tags
+        .iter()
+        .position(|t| *t == "coordinator.tick_recovered")
+        .unwrap_or_else(|| panic!("the recovering Ok tick must log coordinator.tick_recovered; got {tags:?}"));
+    let exit_idx = tags
+        .iter()
+        .position(|t| *t == "coordinator.exit")
+        .unwrap_or_else(|| panic!("the daemon must log coordinator.exit once it stops; got {tags:?}"));
+    assert!(
+        err_idx < rec_idx,
+        "tick_recovered must FOLLOW tick_error (backoff then recover); got {tags:?}"
+    );
+    assert!(
+        rec_idx < exit_idx,
+        "the daemon must NOT exit on the transient error — coordinator.exit appears only AFTER \
+         recovery + the genuine stop; got {tags:?}"
+    );
+}