@team-agent/installer 0.5.18 → 0.5.20

package/Cargo.lock

@@ -575,7 +575,7 @@ dependencies = [
 
 [[package]]
 name = "team-agent"
-version = "0.5.18"
+version = "0.5.20"
 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.18"
+version = "0.5.20"
 license = "AGPL-3.0"
 rust-version = "1.95"
 

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

@@ -732,7 +732,8 @@ pub fn cmd_diagnose(args: &DiagnoseArgs) -> Result<CmdResult, CliError> {
                 &selected.run_workspace,
             )),
         };
-    let (issues, suggested_repairs) = diagnose_runtime(&state, backend.as_ref());
+    let (issues, suggested_repairs) =
+        diagnose_runtime_for_workspace(&selected.run_workspace, &state, backend.as_ref());
     let ok = issues.as_array().is_some_and(Vec::is_empty);
     Ok(CmdResult::from_json(
         json!({
@@ -1701,9 +1702,9 @@ pub fn cmd_doctor(args: &DoctorArgs) -> Result<CmdResult, CliError> {
         return Ok(CmdResult::from_json(value, true));
     }
     let value = if matches!(args.gate, Some(DoctorGate::Orphans)) {
-        crate::diagnose::orphans::orphan_gate_json(args.fix, args.confirm)?
+        crate::diagnose::orphans::orphan_gate_json(&args.workspace, args.fix, args.confirm)?
     } else if args.cleanup_orphans {
-        crate::diagnose::orphans::cleanup_orphans_json(args.confirm)?
+        crate::diagnose::orphans::cleanup_orphans_json(&args.workspace, args.confirm)?
     } else if args.fix_schema {
         diagnose_port::fix_schema(&args.workspace)?
     } else {

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

@@ -165,6 +165,125 @@ pub(crate) fn diagnose_runtime(state: &Value, backend: &dyn Transport) -> (Value
     (Value::Array(issues), Value::Array(repairs))
 }
 
+pub(crate) fn diagnose_runtime_for_workspace(
+    workspace: &std::path::Path,
+    state: &Value,
+    backend: &dyn Transport,
+) -> (Value, Value) {
+    let (mut issues, mut repairs) = diagnose_runtime(state, backend);
+    append_coordinator_health_issue(workspace, state, &mut issues, &mut repairs);
+    (issues, repairs)
+}
+
+fn append_coordinator_health_issue(
+    workspace: &std::path::Path,
+    state: &Value,
+    issues: &mut Value,
+    repairs: &mut Value,
+) {
+    let workspace = crate::coordinator::WorkspacePath::new(workspace.to_path_buf());
+    let health = crate::coordinator::coordinator_health(&workspace);
+    let Some(id) = coordinator_issue_id(state, &health) else {
+        return;
+    };
+    if let Some(items) = issues.as_array_mut() {
+        items.push(coordinator_issue_value(id, &health, workspace.as_path()));
+    }
+    if let Some(items) = repairs.as_array_mut() {
+        items.push(coordinator_repair_hint(id, &health));
+    }
+}
+
+fn coordinator_issue_id(
+    state: &Value,
+    health: &crate::coordinator::HealthReport,
+) -> Option<&'static str> {
+    match health.status {
+        crate::coordinator::CoordinatorHealthStatus::Stale
+        | crate::coordinator::CoordinatorHealthStatus::InvalidPid => {
+            Some("coordinator_unavailable")
+        }
+        crate::coordinator::CoordinatorHealthStatus::Running => {
+            if !health.metadata_ok {
+                return match health.metadata_mismatch_reason.as_deref() {
+                    Some(
+                        "binary_identity_missing"
+                        | "binary_version_mismatch"
+                        | "binary_path_mismatch",
+                    ) => Some("coordinator_stale_identity"),
+                    Some(_) | None => Some("coordinator_unavailable"),
+                };
+            }
+            if !health.schema.ok {
+                Some("coordinator_schema_incompatible")
+            } else {
+                None
+            }
+        }
+        crate::coordinator::CoordinatorHealthStatus::Missing => {
+            coordinator_expected(state).then_some("coordinator_unavailable")
+        }
+    }
+}
+
+fn coordinator_issue_value(
+    id: &str,
+    health: &crate::coordinator::HealthReport,
+    workspace: &std::path::Path,
+) -> Value {
+    json!({
+        "id": id,
+        "status": coordinator_status_wire(health.status),
+        "pid": health.pid.map(|pid| pid.get()),
+        "metadata_ok": health.metadata_ok,
+        "metadata_mismatch_reason": health.metadata_mismatch_reason.clone(),
+        "binary_path": health.current_binary_identity.binary_path.clone(),
+        "binary_version": health.current_binary_identity.binary_version.clone(),
+        "schema_ok": health.schema.ok,
+        "coordinator_log": crate::coordinator::coordinator_log_path(
+            &crate::coordinator::WorkspacePath::new(workspace.to_path_buf())
+        )
+        .to_string_lossy()
+        .to_string(),
+    })
+}
+
+fn coordinator_repair_hint(id: &str, _health: &crate::coordinator::HealthReport) -> Value {
+    let hint_action = match id {
+        "coordinator_schema_incompatible" => "team-agent repair-state --schema",
+        _ => "team-agent restart",
+    };
+    json!({
+        "issue": id,
+        "action_required": true,
+        "advisory": true,
+        "broken_class": id,
+        "hint_action": hint_action,
+        "dedupe_key": id,
+        "action": format!("{hint_action} # diagnose only reports coordinator health; it does not start, stop, or rotate the coordinator"),
+    })
+}
+
+fn coordinator_expected(state: &Value) -> bool {
+    state
+        .get("session_name")
+        .and_then(Value::as_str)
+        .is_some_and(|session| !session.is_empty())
+        || state
+            .get("agents")
+            .and_then(Value::as_object)
+            .is_some_and(|agents| !agents.is_empty())
+}
+
+fn coordinator_status_wire(status: crate::coordinator::CoordinatorHealthStatus) -> &'static str {
+    match status {
+        crate::coordinator::CoordinatorHealthStatus::Missing => "missing",
+        crate::coordinator::CoordinatorHealthStatus::InvalidPid => "invalid_pid",
+        crate::coordinator::CoordinatorHealthStatus::Running => "running",
+        crate::coordinator::CoordinatorHealthStatus::Stale => "stale",
+    }
+}
+
 fn topology_repair_hint(issue: &str) -> Value {
     json!({
         "issue": issue,
@@ -246,6 +365,72 @@ mod tests {
         path
     }
 
+    fn coordinator_health_fixture(
+        status: crate::coordinator::CoordinatorHealthStatus,
+        metadata_mismatch_reason: Option<&str>,
+        schema_ok: bool,
+    ) -> crate::coordinator::HealthReport {
+        crate::coordinator::HealthReport {
+            ok: matches!(status, crate::coordinator::CoordinatorHealthStatus::Running)
+                && metadata_mismatch_reason.is_none()
+                && schema_ok,
+            status,
+            pid: Some(crate::coordinator::Pid::new(std::process::id())),
+            metadata: None,
+            metadata_ok: metadata_mismatch_reason.is_none(),
+            metadata_mismatch_reason: metadata_mismatch_reason.map(ToString::to_string),
+            current_binary_identity: crate::coordinator::CoordinatorBinaryIdentity {
+                binary_path: "/current/team-agent".to_string(),
+                binary_version: env!("CARGO_PKG_VERSION").to_string(),
+            },
+            schema: crate::coordinator::SchemaHealth {
+                ok: schema_ok,
+                schema_version: crate::db::schema::SCHEMA_VERSION,
+                error: None,
+                action: None,
+            },
+        }
+    }
+
+    #[test]
+    fn coordinator_issue_id_maps_stale_pid_to_unavailable() {
+        let health = coordinator_health_fixture(
+            crate::coordinator::CoordinatorHealthStatus::Stale,
+            None,
+            true,
+        );
+        assert_eq!(
+            coordinator_issue_id(&json!({"session_name": "team-fixture"}), &health),
+            Some("coordinator_unavailable")
+        );
+    }
+
+    #[test]
+    fn coordinator_issue_id_maps_binary_identity_to_stale_identity() {
+        let health = coordinator_health_fixture(
+            crate::coordinator::CoordinatorHealthStatus::Running,
+            Some("binary_version_mismatch"),
+            true,
+        );
+        assert_eq!(
+            coordinator_issue_id(&json!({"session_name": "team-fixture"}), &health),
+            Some("coordinator_stale_identity")
+        );
+    }
+
+    #[test]
+    fn coordinator_issue_id_maps_schema_failure_to_schema_incompatible() {
+        let health = coordinator_health_fixture(
+            crate::coordinator::CoordinatorHealthStatus::Running,
+            None,
+            false,
+        );
+        assert_eq!(
+            coordinator_issue_id(&json!({"session_name": "team-fixture"}), &health),
+            Some("coordinator_schema_incompatible")
+        );
+    }
+
     #[test]
     fn diagnose_surfaces_codex_session_identity_mismatch() {
         let workspace =

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

@@ -3820,12 +3820,12 @@ pub mod diagnose_port {
     }
 
     /// `orphan_gate(fix, confirm)`(`--gate orphans`)。CI gate。
-    pub fn orphan_gate(fix: bool, confirm: bool) -> Result<Value, CliError> {
-        crate::diagnose::orphans::orphan_gate_json(fix, confirm)
+    pub fn orphan_gate(workspace: &Path, fix: bool, confirm: bool) -> Result<Value, CliError> {
+        crate::diagnose::orphans::orphan_gate_json(workspace, fix, confirm)
     }
     /// `cleanup_orphan_coordinators(confirm)`(`--cleanup-orphans`;dry-run unless `--confirm`)。
-    pub fn cleanup_orphans(confirm: bool) -> Result<Value, CliError> {
-        crate::diagnose::orphans::cleanup_orphans_json(confirm)
+    pub fn cleanup_orphans(workspace: &Path, confirm: bool) -> Result<Value, CliError> {
+        crate::diagnose::orphans::cleanup_orphans_json(workspace, confirm)
     }
     /// `fix_schema_layout`(`--fix-schema`)/`schema_diagnosis`。
     pub fn fix_schema(workspace: &Path) -> Result<Value, CliError> {

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

@@ -269,7 +269,9 @@ use super::*;
     // 530-531 stub {ok:true,fix,confirm,orphans:[]}. Fully deterministic (no subprocess). RED. ─────────
     #[test]
     fn orphan_gate_fix_without_confirm_is_refused_envelope() {
-        let v = diagnose_port::orphan_gate(/*fix=*/ true, /*confirm=*/ false).expect("orphan_gate");
+        let ws = tmp_workspace();
+        let v = diagnose_port::orphan_gate(&ws, /*fix=*/ true, /*confirm=*/ false)
+            .expect("orphan_gate");
         assert_eq!(
             v,
             json!({
@@ -292,7 +294,8 @@ use super::*;
     #[ignore = "real-machine: cleanup_orphans scans machine-wide ta-* tmux/process residue"]
     #[serial_test::file_serial(tmux)]
     fn cleanup_orphans_dryrun_golden_envelope() {
-        let v = diagnose_port::cleanup_orphans(/*confirm=*/ false).expect("cleanup_orphans");
+        let ws = tmp_workspace();
+        let v = diagnose_port::cleanup_orphans(&ws, /*confirm=*/ false).expect("cleanup_orphans");
         let obj = v.as_object().expect("cleanup dict");
         assert_eq!(v["dry_run"], json!(true), "no --confirm => dry_run:true (cleanup_orphan_coordinators)");
         assert_eq!(v["orphans"], json!([]), "golden lists orphans (empty when none)");

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

@@ -8,7 +8,7 @@ use crate::model::enums::Provider;
 use crate::provider::ProviderAdapter;
 
 use super::health::{coordinator_pid_path, write_coordinator_metadata};
-use super::tick::{TickError, TickReport};
+use super::tick::{write_coordinator_heartbeat, TickError, TickReport, HEARTBEAT_STATUS_PANIC};
 use super::types::{
     ErrorLists, MetadataSource, Pid, ProviderRegistry, WorkspacePath, BACKOFF_MAX_SEC,
     DEFAULT_TICK_INTERVAL_SEC,
@@ -86,7 +86,7 @@ pub fn run_daemon(args: DaemonArgs) -> Result<(), DaemonError> {
             // event log shows the reason. This preserves the daemon
             // liveness path while making the failure explicit.
             eprintln!(
-                "coordinator: transport_factory refused ({e}); falling back to tmux workspace for daemon liveness"
+                "[coordinator] transport_factory refused ({e}); falling back to tmux workspace for daemon liveness"
             );
             let sel = crate::tmux_backend::tmux_backend_for_runtime_state_or_workspace(
                 args.workspace.as_path(),
@@ -139,13 +139,87 @@ fn run_daemon_with_coordinator_and_boot_tmux(
     args: &DaemonArgs,
     coordinator: &Coordinator,
     tmux_metadata: Option<DaemonTmuxEndpointMetadata>,
+) -> Result<(), DaemonError> {
+    let pid = Pid::new(std::process::id());
+    let boot_id = daemon_boot_id(pid);
+    match std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+        run_daemon_body_with_panic_marker(args, coordinator, tmux_metadata, pid, &boot_id)
+    })) {
+        Ok(Ok(())) => Ok(()),
+        Ok(Err(error)) => {
+            let reason = if matches!(error, DaemonError::Tick(_)) {
+                "fatal_error"
+            } else {
+                "startup_error"
+            };
+            let _ = write_coordinator_heartbeat(
+                &args.workspace,
+                pid,
+                Some(&boot_id),
+                reason,
+                Some("error"),
+                Some(&error.to_string()),
+                false,
+            );
+            let _ = write_daemon_exit(
+                &EventLog::new(args.workspace.as_path()),
+                &args.workspace,
+                pid,
+                &boot_id,
+                reason,
+                serde_json::json!({"error": error.to_string()}),
+            );
+            Err(error)
+        }
+        Err(payload) => {
+            let panic_payload = panic_payload_message(payload.as_ref());
+            let backtrace = std::backtrace::Backtrace::force_capture().to_string();
+            let _ = write_coordinator_heartbeat(
+                &args.workspace,
+                pid,
+                Some(&boot_id),
+                "panic",
+                Some(HEARTBEAT_STATUS_PANIC),
+                Some(&panic_payload),
+                false,
+            );
+            let _ = write_daemon_exit(
+                &EventLog::new(args.workspace.as_path()),
+                &args.workspace,
+                pid,
+                &boot_id,
+                "panic",
+                serde_json::json!({
+                    "panic_payload": panic_payload.clone(),
+                    "backtrace": backtrace,
+                }),
+            );
+            Err(DaemonError::Panic(panic_payload))
+        }
+    }
+}
+
+fn run_daemon_body_with_panic_marker(
+    args: &DaemonArgs,
+    coordinator: &Coordinator,
+    tmux_metadata: Option<DaemonTmuxEndpointMetadata>,
+    pid: Pid,
+    boot_id: &str,
 ) -> Result<(), DaemonError> {
     let runtime_dir = crate::model::paths::runtime_dir(args.workspace.as_path());
     std::fs::create_dir_all(&runtime_dir)?;
-    let pid = Pid::new(std::process::id());
     std::fs::write(coordinator_pid_path(&args.workspace), pid.to_string())?;
     write_coordinator_metadata(&args.workspace, pid, MetadataSource::Boot)?;
     let binary_identity = crate::coordinator::current_coordinator_binary_identity();
+    let _ = write_coordinator_heartbeat(
+        &args.workspace,
+        pid,
+        Some(boot_id),
+        "boot",
+        None,
+        None,
+        false,
+    );
 
     let event_log = EventLog::new(args.workspace.as_path());
     let mut boot_event = serde_json::json!({
@@ -204,14 +278,14 @@ fn run_daemon_with_coordinator_and_boot_tmux(
                     // Detach so the shim survives beyond this
                     // coordinator instance (F7 core invariant).
                     let _shim_pid = handle.detach();
-                    eprintln!("coordinator: shim ensured (pid={_shim_pid})");
+                    eprintln!("[coordinator] shim ensured (pid={_shim_pid})");
                 }
                 Err(e) => {
                     // Honest degradation: emit the stale-family
                     // event, coord continues without a shim. Tick
                     // loop will surface `mux_unavailable` on any
                     // transport call.
-                    eprintln!("coordinator: shim ensure failed: {e}");
+                    eprintln!("[coordinator] shim ensure failed: {e}");
                     let _ = crate::coordinator::conpty_shim::mark_transport_unavailable(
                         args.workspace.as_path(),
                         &format!("boot_ensure_failed: {e}"),
@@ -231,7 +305,28 @@ fn run_daemon_with_coordinator_and_boot_tmux(
     let initial_ppid = current_ppid();
     let mut consecutive_failures = 0_u32;
     let mut last_failure_signature: Option<String> = None;
+    install_signal_handlers();
     loop {
+        if let Some(signal) = take_signal_stop_request() {
+            let _ = write_coordinator_heartbeat(
+                &args.workspace,
+                pid,
+                Some(boot_id),
+                "signal",
+                Some("stop_requested"),
+                Some(signal),
+                false,
+            );
+            write_daemon_exit(
+                &event_log,
+                &args.workspace,
+                pid,
+                boot_id,
+                "signal",
+                serde_json::json!({"signal": signal}),
+            )?;
+            return Ok(());
+        }
         let ppid_now = current_ppid();
         if super::should_orphan_self_terminate(initial_ppid, ppid_now, &args.workspace) {
             let _ = event_log.write(
@@ -244,8 +339,31 @@ fn run_daemon_with_coordinator_and_boot_tmux(
             );
             break;
         }
+        let _ = write_coordinator_heartbeat(
+            &args.workspace,
+            pid,
+            Some(boot_id),
+            "tick_running",
+            Some("running"),
+            None,
+            false,
+        );
         match run_tick_with_panic_marker(&event_log, || coordinator.tick()) {
             Ok(report) => {
+                let status = if report.stop {
+                    "stop_requested"
+                } else {
+                    "ok"
+                };
+                let _ = write_coordinator_heartbeat(
+                    &args.workspace,
+                    pid,
+                    Some(boot_id),
+                    "tick_finished",
+                    Some(status),
+                    None,
+                    false,
+                );
                 if consecutive_failures > 0 {
                     event_log.write(
                         "coordinator.tick_recovered",
@@ -260,6 +378,20 @@ fn run_daemon_with_coordinator_and_boot_tmux(
                 sleep_seconds(tick_interval);
             }
             Err(err) => {
+                let status = if matches!(err, TickError::Panic(_)) {
+                    HEARTBEAT_STATUS_PANIC
+                } else {
+                    "error"
+                };
+                let _ = write_coordinator_heartbeat(
+                    &args.workspace,
+                    pid,
+                    Some(boot_id),
+                    "tick_finished",
+                    Some(status),
+                    Some(&err.to_string()),
+                    false,
+                );
                 consecutive_failures = consecutive_failures.saturating_add(1);
                 let next_sleep_sec = backoff_sleep_sec(tick_interval, consecutive_failures);
                 // P7-F2 (Python __main__.py:66-89): identical-signature failures emit
@@ -303,10 +435,54 @@ fn run_daemon_with_coordinator_and_boot_tmux(
             }
         }
     }
-    event_log.write("coordinator.exit", serde_json::json!({"stop": true}))?;
+    let _ = write_coordinator_heartbeat(
+        &args.workspace,
+        pid,
+        Some(boot_id),
+        "exit",
+        Some("stop_requested"),
+        None,
+        false,
+    );
+    write_daemon_exit(
+        &event_log,
+        &args.workspace,
+        pid,
+        boot_id,
+        "stop",
+        serde_json::json!({"stop": true}),
+    )?;
     Ok(())
 }
 
+fn write_daemon_exit(
+    event_log: &EventLog,
+    workspace: &WorkspacePath,
+    pid: Pid,
+    boot_id: &str,
+    reason: &str,
+    mut extra: serde_json::Value,
+) -> Result<(), crate::event_log::EventLogError> {
+    let mut event = serde_json::json!({
+        "reason": reason,
+        "pid": pid.get(),
+        "boot_id": boot_id,
+        "workspace": workspace.as_path().to_string_lossy(),
+    });
+    if let (Some(target), Some(extra_obj)) = (event.as_object_mut(), extra.as_object_mut()) {
+        target.extend(std::mem::take(extra_obj));
+    }
+    event_log.write("coordinator.exit", event).map(|_| ())
+}
+
+fn daemon_boot_id(pid: Pid) -> String {
+    format!(
+        "coord_{}_{}",
+        chrono::Utc::now().format("%Y%m%dT%H%M%SZ"),
+        pid.get()
+    )
+}
+
 fn run_tick_with_panic_marker<F>(event_log: &EventLog, tick: F) -> Result<TickReport, TickError>
 where
     F: FnOnce() -> Result<TickReport, TickError>,
@@ -388,6 +564,52 @@ pub enum DaemonError {
     EventLog(#[from] crate::event_log::EventLogError),
     #[error("tick: {0}")]
     Tick(#[from] TickError),
+    #[error("panic: {0}")]
+    Panic(String),
+}
+
+#[cfg(unix)]
+static SIGNAL_STOP_REQUESTED: std::sync::atomic::AtomicBool =
+    std::sync::atomic::AtomicBool::new(false);
+#[cfg(unix)]
+static SIGNAL_STOP_NUMBER: std::sync::atomic::AtomicI32 =
+    std::sync::atomic::AtomicI32::new(0);
+
+#[cfg(unix)]
+extern "C" fn coordinator_signal_handler(signal: libc::c_int) {
+    SIGNAL_STOP_NUMBER.store(signal, std::sync::atomic::Ordering::SeqCst);
+    SIGNAL_STOP_REQUESTED.store(true, std::sync::atomic::Ordering::SeqCst);
+}
+
+#[cfg(unix)]
+fn install_signal_handlers() {
+    unsafe {
+        let handler = coordinator_signal_handler as *const () as libc::sighandler_t;
+        libc::signal(libc::SIGTERM, handler);
+        libc::signal(libc::SIGHUP, handler);
+        libc::signal(libc::SIGINT, handler);
+    }
+}
+
+#[cfg(not(unix))]
+fn install_signal_handlers() {}
+
+#[cfg(unix)]
+fn take_signal_stop_request() -> Option<&'static str> {
+    if !SIGNAL_STOP_REQUESTED.swap(false, std::sync::atomic::Ordering::SeqCst) {
+        return None;
+    }
+    match SIGNAL_STOP_NUMBER.load(std::sync::atomic::Ordering::SeqCst) {
+        libc::SIGTERM => Some("SIGTERM"),
+        libc::SIGHUP => Some("SIGHUP"),
+        libc::SIGINT => Some("SIGINT"),
+        _ => Some("UNKNOWN"),
+    }
+}
+
+#[cfg(not(unix))]
+fn take_signal_stop_request() -> Option<&'static str> {
+    None
 }
 
 #[cfg(test)]

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

@@ -33,6 +33,7 @@ const STARTUP_PROMPT_GRACE_SECS: i64 = 120;
 const RUNTIME_APPROVAL_INITIAL_BACKOFF_SECS: i64 = 30;
 const RUNTIME_APPROVAL_MAX_BACKOFF_SECS: i64 = 300;
 const IDLE_HEALTH_CAPTURE_INTERVAL_SECS: i64 = 60;
+pub(crate) const HEARTBEAT_STATUS_PANIC: &str = "panic";
 
 // ===========================================================================
 // TickReport / TickError(§10:tick(..) -> Result<TickReport, TickError>)
@@ -1420,21 +1421,87 @@ impl TurnStateClassifier for ProviderTurnClassifier {
 /// `coordinator.coordinator_tick_iteration_count` load fine (read-compat, C-P3-3) —
 /// new versions simply stop writing it.
 fn increment_coordinator_tick_iteration_count(workspace: &WorkspacePath) {
-    let path = crate::model::paths::runtime_dir(workspace.as_path()).join("coordinator_tick.json");
-    let next = std::fs::read_to_string(&path)
-        .ok()
-        .and_then(|text| serde_json::from_str::<Value>(&text).ok())
-        .and_then(|value| {
+    let _ = write_coordinator_heartbeat(
+        workspace,
+        Pid::new(std::process::id()),
+        None,
+        "tick_running",
+        Some("running"),
+        None,
+        true,
+    );
+}
+
+pub(crate) fn write_coordinator_heartbeat(
+    workspace: &WorkspacePath,
+    pid: Pid,
+    boot_id: Option<&str>,
+    last_phase: &str,
+    last_tick_status: Option<&str>,
+    last_error: Option<&str>,
+    increment_count: bool,
+) -> std::io::Result<()> {
+    let path = coordinator_heartbeat_path(workspace);
+    let value = read_coordinator_heartbeat_value(&path);
+    let next_count = value
+        .get("coordinator_tick_iteration_count")
+        .and_then(Value::as_u64)
+        .unwrap_or(0)
+        .saturating_add(u64::from(increment_count));
+    let now = chrono::Utc::now().to_rfc3339();
+    let identity = crate::coordinator::current_coordinator_binary_identity();
+    let boot_id = boot_id
+        .map(ToString::to_string)
+        .or_else(|| {
             value
-                .get("coordinator_tick_iteration_count")
-                .and_then(Value::as_u64)
+                .get("boot_id")
+                .and_then(Value::as_str)
+                .map(ToString::to_string)
         })
-        .unwrap_or(0)
-        .saturating_add(1);
-    let _ = std::fs::write(
-        &path,
-        serde_json::json!({"coordinator_tick_iteration_count": next}).to_string(),
-    );
+        .unwrap_or_else(|| format!("coord_unknown_{}", pid.get()));
+    let mut next = serde_json::json!({
+        "coordinator_tick_iteration_count": next_count,
+        "pid": pid.get(),
+        "boot_id": boot_id,
+        "binary_path": identity.binary_path,
+        "binary_version": identity.binary_version,
+        "last_phase": last_phase,
+        "last_tick_status": last_tick_status,
+        "last_error": last_error,
+        "updated_at": now,
+    });
+    if last_phase == "tick_running" {
+        next["last_tick_started_at"] = serde_json::Value::String(now.clone());
+        if let Some(finished) = value.get("last_tick_finished_at").cloned() {
+            next["last_tick_finished_at"] = finished;
+        }
+    } else {
+        if let Some(started) = value.get("last_tick_started_at").cloned() {
+            next["last_tick_started_at"] = started;
+        }
+        next["last_tick_finished_at"] = serde_json::Value::String(chrono::Utc::now().to_rfc3339());
+    }
+    write_coordinator_heartbeat_value(&path, &next)
+}
+
+fn coordinator_heartbeat_path(workspace: &WorkspacePath) -> PathBuf {
+    crate::model::paths::runtime_dir(workspace.as_path()).join("coordinator_tick.json")
+}
+
+fn read_coordinator_heartbeat_value(path: &Path) -> Value {
+    std::fs::read_to_string(path)
+        .ok()
+        .and_then(|text| serde_json::from_str::<Value>(&text).ok())
+        .unwrap_or_else(|| serde_json::json!({}))
+}
+
+fn write_coordinator_heartbeat_value(path: &Path, value: &Value) -> std::io::Result<()> {
+    if let Some(parent) = path.parent() {
+        std::fs::create_dir_all(parent)?;
+    }
+    let tmp = path.with_extension("json.tmp");
+    std::fs::write(&tmp, value.to_string())?;
+    std::fs::rename(tmp, path)
 }
 
 fn idle_node_value(node: &crate::leader::IdleNode) -> Value {

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

@@ -18,10 +18,10 @@ pub fn doctor_gate_blockers(
     let _ = (fix, confirm);
     match gate {
         Some(DoctorGate::Orphans) => {
-            if orphans::has_orphan_residue() {
+            if orphans::has_orphan_residue(workspace) {
                 Ok(vec![Blocker {
                     source: BlockerSource::OrphanCoordinator,
-                    detail: orphans::orphan_blocker_detail(),
+                    detail: orphans::orphan_blocker_detail(workspace),
                 }])
             } else {
                 Ok(Vec::new())

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

@@ -32,9 +32,57 @@ struct OrphanRecord {
 struct ScanReport {
     scanned: usize,
     orphans: Vec<OrphanRecord>,
+    ignored_foreign: Vec<OrphanRecord>,
 }
 
-pub fn orphan_gate_json(fix: bool, confirm: bool) -> Result<Value, CliError> {
+#[derive(Debug, Clone)]
+pub(crate) enum OrphanScanScope {
+    CurrentWorkspace {
+        canonical_current_workspace: PathBuf,
+    },
+}
+
+impl OrphanScanScope {
+    fn current_workspace(workspace: &Path) -> Self {
+        Self::CurrentWorkspace {
+            canonical_current_workspace: canonicalize_workspace(workspace),
+        }
+    }
+}
+
+fn canonicalize_workspace(workspace: &Path) -> PathBuf {
+    std::fs::canonicalize(workspace).unwrap_or_else(|_| workspace.to_path_buf())
+}
+
+fn workspace_matches_scope(scope: &OrphanScanScope, workspace: &Path) -> bool {
+    match scope {
+        OrphanScanScope::CurrentWorkspace {
+            canonical_current_workspace,
+        } => canonicalize_workspace(workspace) == *canonical_current_workspace,
+    }
+}
+
+fn assert_current_workspace_orphan(orphan: &OrphanRecord, scope: &OrphanScanScope) -> bool {
+    orphan
+        .workspace
+        .as_deref()
+        .is_some_and(|workspace| workspace_matches_scope(scope, workspace))
+}
+
+fn foreign_workspace_record(process: ProcessRow, workspace: PathBuf) -> OrphanRecord {
+    OrphanRecord {
+        kind: "coordinator_process",
+        pid: Some(process.pid),
+        session: None,
+        tmux_socket: None,
+        workspace: Some(workspace),
+        reason: OrphanReason::WorkspaceAlive,
+        command: Some(process.command),
+        action: "none",
+    }
+}
+
+pub fn orphan_gate_json(workspace: &Path, fix: bool, confirm: bool) -> Result<Value, CliError> {
     if fix && !confirm {
         return Ok(json!({
             "ok": false,
@@ -44,9 +92,10 @@ pub fn orphan_gate_json(fix: bool, confirm: bool) -> Result<Value, CliError> {
             "action": "re-run with --gate orphans --fix --confirm",
         }));
     }
-    let report = scan_orphans_bounded(false);
+    let scope = OrphanScanScope::current_workspace(workspace);
+    let report = scan_orphans_bounded(&scope, false);
     if report.orphans.is_empty() {
-        return Ok(json!({
+        return Ok(with_ignored_foreign(json!({
             "ok": true,
             "gate": "orphans",
             "status": "passed",
@@ -56,12 +105,12 @@ pub fn orphan_gate_json(fix: bool, confirm: bool) -> Result<Value, CliError> {
             "action_required": false,
             "fix": fix,
             "orphans": [],
-        }));
+        }), &report));
     }
     if fix {
-        return fix_orphans(report);
+        return fix_orphans(&scope, report);
     }
-    Ok(json!({
+    Ok(with_ignored_foreign(json!({
         "ok": false,
         "gate": "orphans",
         "status": "failed",
@@ -71,14 +120,15 @@ pub fn orphan_gate_json(fix: bool, confirm: bool) -> Result<Value, CliError> {
         "action_required": true,
         "fix": false,
         "orphans": orphan_values(&report.orphans),
-    }))
+    }), &report))
 }
 
-pub fn cleanup_orphans_json(confirm: bool) -> Result<Value, CliError> {
-    let report = scan_orphans_bounded(false);
+pub fn cleanup_orphans_json(workspace: &Path, confirm: bool) -> Result<Value, CliError> {
+    let scope = OrphanScanScope::current_workspace(workspace);
+    let report = scan_orphans_bounded(&scope, false);
     if confirm {
         if report.orphans.is_empty() {
-            return Ok(json!({
+            return Ok(with_ignored_foreign(json!({
                 "ok": true,
                 "scanned": report.scanned,
                 "orphans": [],
@@ -86,26 +136,28 @@ pub fn cleanup_orphans_json(confirm: bool) -> Result<Value, CliError> {
                 "scanned_at": chrono::Utc::now().to_rfc3339(),
                 "killed": [],
                 "failed": [],
-            }));
+            }), &report));
         }
-        return cleanup_confirmed(report);
+        return cleanup_confirmed(&scope, report);
     }
-    Ok(json!({
+    Ok(with_ignored_foreign(json!({
         "ok": true,
         "scanned": report.scanned,
         "orphans": orphan_values(&report.orphans),
         "dry_run": true,
         "scanned_at": chrono::Utc::now().to_rfc3339(),
         "action_required": "re-run with --confirm to send SIGTERM",
-    }))
+    }), &report))
 }
 
-pub fn has_orphan_residue() -> bool {
-    !scan_orphans_bounded(false).orphans.is_empty()
+pub fn has_orphan_residue(workspace: &Path) -> bool {
+    let scope = OrphanScanScope::current_workspace(workspace);
+    !scan_orphans_bounded(&scope, false).orphans.is_empty()
 }
 
-pub fn orphan_blocker_detail() -> String {
-    let report = scan_orphans_bounded(false);
+pub fn orphan_blocker_detail(workspace: &Path) -> String {
+    let scope = OrphanScanScope::current_workspace(workspace);
+    let report = scan_orphans_bounded(&scope, false);
     if report.orphans.is_empty() {
         return "no orphan coordinator residue detected".to_string();
     }
@@ -133,10 +185,10 @@ pub fn orphan_blocker_detail() -> String {
         .join("; ")
 }
 
-fn fix_orphans(report: ScanReport) -> Result<Value, CliError> {
-    let cleanup = cleanup_report(report);
-    let residual = scan_orphans(false);
-    Ok(json!({
+fn fix_orphans(scope: &OrphanScanScope, report: ScanReport) -> Result<Value, CliError> {
+    let cleanup = cleanup_report(report, scope);
+    let residual = scan_orphans(scope, false);
+    Ok(with_ignored_foreign(json!({
         "ok": residual.orphans.is_empty() && cleanup.failed.is_empty(),
         "gate": "orphans",
         "status": if residual.orphans.is_empty() && cleanup.failed.is_empty() { "fixed" } else { "failed" },
@@ -148,13 +200,13 @@ fn fix_orphans(report: ScanReport) -> Result<Value, CliError> {
         "orphans": orphan_values(&residual.orphans),
         "killed": cleanup.killed,
         "failed": cleanup.failed,
-    }))
+    }), &residual))
 }
 
-fn cleanup_confirmed(report: ScanReport) -> Result<Value, CliError> {
-    let cleanup = cleanup_report(report);
-    let residual = scan_orphans(false);
-    Ok(json!({
+fn cleanup_confirmed(scope: &OrphanScanScope, report: ScanReport) -> Result<Value, CliError> {
+    let cleanup = cleanup_report(report, scope);
+    let residual = scan_orphans(scope, false);
+    Ok(with_ignored_foreign(json!({
         "ok": residual.orphans.is_empty() && cleanup.failed.is_empty(),
         "scanned": cleanup.scanned,
         "orphans": orphan_values(&residual.orphans),
@@ -162,7 +214,7 @@ fn cleanup_confirmed(report: ScanReport) -> Result<Value, CliError> {
         "scanned_at": chrono::Utc::now().to_rfc3339(),
         "killed": cleanup.killed,
         "failed": cleanup.failed,
-    }))
+    }), &residual))
 }
 
 struct CleanupReport {
@@ -171,11 +223,15 @@ struct CleanupReport {
     failed: Vec<Value>,
 }
 
-fn cleanup_report(report: ScanReport) -> CleanupReport {
+fn cleanup_report(report: ScanReport, scope: &OrphanScanScope) -> CleanupReport {
     let protected = protected_pids();
     let mut killed = Vec::new();
     let mut failed = Vec::new();
     for orphan in &report.orphans {
+        if !assert_current_workspace_orphan(orphan, scope) {
+            failed.push(orphan_value(orphan, "skipped"));
+            continue;
+        }
         if let Some(pid) = orphan.pid {
             if protected.contains(&pid.get()) {
                 failed.push(orphan_value(orphan, "skipped"));
@@ -201,10 +257,11 @@ fn cleanup_report(report: ScanReport) -> CleanupReport {
     }
 }
 
-fn scan_orphans(include_unparsed: bool) -> ScanReport {
+fn scan_orphans(scope: &OrphanScanScope, include_unparsed: bool) -> ScanReport {
     let protected = protected_pids();
     let mut scanned = 0;
     let mut orphans = Vec::new();
+    let mut ignored_foreign = Vec::new();
     for process in coordinator_processes() {
         if protected.contains(&process.pid.get()) {
             continue;
@@ -225,6 +282,10 @@ fn scan_orphans(include_unparsed: bool) -> ScanReport {
             }
             continue;
         };
+        if !workspace_matches_scope(scope, &workspace) {
+            ignored_foreign.push(foreign_workspace_record(process, workspace));
+            continue;
+        }
         if let Some(reason) = classify_workspace_orphan(&workspace, process.pid) {
             orphans.push(OrphanRecord {
                 kind: "coordinator_process",
@@ -238,22 +299,26 @@ fn scan_orphans(include_unparsed: bool) -> ScanReport {
             });
         }
     }
-    for orphan in coordinator_pid_file_orphans() {
+    for orphan in coordinator_pid_file_orphans(scope) {
         scanned += 1;
         orphans.push(orphan);
     }
-    for orphan in tmux_session_orphans() {
+    for orphan in tmux_session_orphans(scope) {
         scanned += 1;
         orphans.push(orphan);
     }
-    for orphan in provider_mcp_process_orphans() {
+    for orphan in provider_mcp_process_orphans(scope) {
         scanned += 1;
         orphans.push(orphan);
     }
-    ScanReport { scanned, orphans }
+    ScanReport {
+        scanned,
+        orphans,
+        ignored_foreign,
+    }
 }
 
-fn coordinator_pid_file_orphans() -> Vec<OrphanRecord> {
+fn coordinator_pid_file_orphans(scope: &OrphanScanScope) -> Vec<OrphanRecord> {
     temp_scan_roots()
         .into_iter()
         .flat_map(|root| match std::fs::read_dir(root) {
@@ -265,6 +330,9 @@ fn coordinator_pid_file_orphans() -> Vec<OrphanRecord> {
             if !workspace.is_dir() || ephemeral_workspace_hint(&workspace).is_none() {
                 return None;
             }
+            if !workspace_matches_scope(scope, &workspace) {
+                return None;
+            }
             let pid_path = crate::model::paths::runtime_dir(&workspace).join("coordinator.pid");
             let pid = read_pid_file(&pid_path)?;
             let workspace_path = WorkspacePath::new(workspace.clone());
@@ -293,7 +361,7 @@ fn coordinator_pid_file_orphans() -> Vec<OrphanRecord> {
         .collect()
 }
 
-fn tmux_session_orphans() -> Vec<OrphanRecord> {
+fn tmux_session_orphans(scope: &OrphanScanScope) -> Vec<OrphanRecord> {
     tmux_socket_names()
         .into_iter()
         .flat_map(|socket| {
@@ -304,6 +372,9 @@ fn tmux_session_orphans() -> Vec<OrphanRecord> {
                     if !is_orphan_marker_workspace(&workspace) {
                         return None;
                     }
+                    if !workspace_matches_scope(scope, &workspace) {
+                        return None;
+                    }
                     let reason = classify_workspace_without_pid(&workspace)?;
                     Some(OrphanRecord {
                         kind: "tmux_session",
@@ -382,7 +453,7 @@ fn tmux_list_panes(socket: &str) -> Vec<TmuxPaneRow> {
         .collect()
 }
 
-fn provider_mcp_process_orphans() -> Vec<OrphanRecord> {
+fn provider_mcp_process_orphans(scope: &OrphanScanScope) -> Vec<OrphanRecord> {
     ps_command_rows()
         .into_iter()
         .filter(|row| is_provider_or_mcp_workspace_command(&row.command))
@@ -391,6 +462,9 @@ fn provider_mcp_process_orphans() -> Vec<OrphanRecord> {
             if !is_orphan_marker_workspace(&workspace) {
                 return None;
             }
+            if !workspace_matches_scope(scope, &workspace) {
+                return None;
+            }
             let reason = classify_workspace_without_pid(&workspace)?;
             Some(OrphanRecord {
                 kind: if process.command.contains("mcp-server") {
@@ -427,16 +501,20 @@ fn read_pid_file(path: &Path) -> Option<Pid> {
     Some(Pid::new(pid))
 }
 
-fn scan_orphans_bounded(include_unparsed: bool) -> ScanReport {
+fn scan_orphans_bounded(scope: &OrphanScanScope, include_unparsed: bool) -> ScanReport {
     let deadline = Instant::now() + Duration::from_millis(800);
     let mut scanned = 0;
     let mut by_key = BTreeMap::new();
+    let mut foreign_by_key = BTreeMap::new();
     loop {
-        let report = scan_orphans(include_unparsed);
+        let report = scan_orphans(scope, include_unparsed);
         scanned = scanned.max(report.scanned);
         for orphan in report.orphans {
             by_key.insert(orphan_key(&orphan), orphan);
         }
+        for orphan in report.ignored_foreign {
+            foreign_by_key.insert(orphan_key(&orphan), orphan);
+        }
         if !by_key.is_empty() || Instant::now() >= deadline {
             break;
         }
@@ -445,6 +523,7 @@ fn scan_orphans_bounded(include_unparsed: bool) -> ScanReport {
     ScanReport {
         scanned,
         orphans: by_key.into_values().collect(),
+        ignored_foreign: foreign_by_key.into_values().collect(),
     }
 }
 
@@ -653,10 +732,23 @@ fn orphan_values(orphans: &[OrphanRecord]) -> Vec<Value> {
         .collect()
 }
 
+fn with_ignored_foreign(mut value: Value, report: &ScanReport) -> Value {
+    if !report.ignored_foreign.is_empty() {
+        value["ignored_foreign"] = Value::Array(
+            report
+                .ignored_foreign
+                .iter()
+                .map(|orphan| orphan_value(orphan, "none"))
+                .collect(),
+        );
+    }
+    value
+}
+
 fn orphan_value(orphan: &OrphanRecord, action: &str) -> Value {
     let mut value = json!({
         "kind": orphan.kind,
-        "reason": reason_key(&orphan.reason),
+        "reason": if action == "none" { "foreign_workspace" } else { reason_key(&orphan.reason) },
         "action": action,
     });
     if let Some(pid) = orphan.pid {

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

@@ -695,6 +695,9 @@ pub enum RestartReport {
     Restarted {
         session_name: SessionName,
         agents: Vec<RestartedAgent>,
+        /// Compatibility field: true means the coordinator requirement is
+        /// satisfied. The structured `coordinator` summary carries started vs
+        /// already-running vs rotated detail.
         coordinator_started: bool,
         coordinator: CoordinatorStartSummary,
         next_actions: Vec<String>,
@@ -706,6 +709,9 @@ pub enum RestartReport {
         session_name: SessionName,
         agents: Vec<RestartedAgent>,
         failed_agents: Vec<RestartFailedAgent>,
+        /// Compatibility field: true means the coordinator requirement is
+        /// satisfied. The structured `coordinator` summary carries started vs
+        /// already-running vs rotated detail.
         coordinator_started: bool,
         coordinator: CoordinatorStartSummary,
         next_actions: Vec<String>,

package/package.json

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