@team-agent/installer 0.5.6 → 0.5.8

package/Cargo.lock

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

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

@@ -18,28 +18,34 @@ pub(crate) fn diagnose_runtime(state: &Value, backend: &dyn Transport) -> (Value
             Ok(true) => {}
             Ok(false) => {
                 issues.push(json!("tmux_session_missing"));
-                repairs.push(json!({
-                    "issue": "tmux_session_missing",
-                    "action": format!("restart or relaunch tmux session `{session_name}`"),
-                }));
+                repairs.push(recovery_hint(
+                    session_name,
+                    "tmux_session_missing",
+                    "team-agent restart",
+                ));
             }
             Err(error) => {
                 issues.push(json!("tmux_session_missing"));
-                repairs.push(json!({
-                    "issue": "tmux_session_missing",
-                    "action": format!("restart or relaunch tmux session `{session_name}`"),
-                    "reason": error.to_string(),
-                }));
+                let mut hint =
+                    recovery_hint(session_name, "tmux_session_missing", "team-agent restart");
+                if let Some(obj) = hint.as_object_mut() {
+                    obj.insert("reason".to_string(), Value::String(error.to_string()));
+                }
+                repairs.push(hint);
             }
         }
     }
 
     if !leader_receiver_attached(state) {
         issues.push(json!("leader_not_attached"));
-        repairs.push(json!({
-            "issue": "leader_not_attached",
-            "action": "attach or claim a leader receiver before sending work",
-        }));
+        repairs.push(recovery_hint(
+            state
+                .get("session_name")
+                .and_then(Value::as_str)
+                .unwrap_or("unknown"),
+            "leader_not_attached",
+            "team-agent attach-leader",
+        ));
     } else {
         // 0.4.x (CR R2 P0): leader provider health reconciliation. The
         // leader_receiver may be marked `attached` (pane addressable) but the
@@ -57,6 +63,11 @@ pub(crate) fn diagnose_runtime(state: &Value, backend: &dyn Transport) -> (Value
                     issues.push(json!("leader_provider_exited"));
                     repairs.push(json!({
                         "issue": "leader_provider_exited",
+                        "action_required": true,
+                        "advisory": true,
+                        "broken_class": "leader_provider_exited",
+                        "hint_action": "team-agent restart",
+                        "dedupe_key": "leader_provider_exited",
                         "action": format!(
                             "leader pane fell back to shell — provider `{provider_label}` exited; \
                              relaunch with `team-agent {provider_label}` to restart the provider"
@@ -65,10 +76,14 @@ pub(crate) fn diagnose_runtime(state: &Value, backend: &dyn Transport) -> (Value
                 }
                 crate::leader::LeaderProviderHealth::Unreachable => {
                     issues.push(json!("leader_provider_unreachable"));
-                    repairs.push(json!({
-                        "issue": "leader_provider_unreachable",
-                        "action": "leader pane is dead — relaunch the leader",
-                    }));
+                    repairs.push(recovery_hint(
+                        state
+                            .get("session_name")
+                            .and_then(Value::as_str)
+                            .unwrap_or("unknown"),
+                        "leader_provider_unreachable",
+                        "team-agent claim-leader",
+                    ));
                 }
                 crate::leader::LeaderProviderHealth::Alive => {}
             }
@@ -179,6 +194,20 @@ fn leader_receiver_attached(state: &Value) -> bool {
     mode_direct && status_attached && pane_present
 }
 
+fn recovery_hint(team: &str, broken_class: &str, hint_action: &str) -> Value {
+    json!({
+        "issue": broken_class,
+        "action_required": true,
+        "advisory": true,
+        "broken_class": broken_class,
+        "hint_action": hint_action,
+        "dedupe_key": format!("{team}:{broken_class}"),
+        "action": format!(
+            "{hint_action} # alternatives: team-agent restart; team-agent claim-leader; team-agent quick-start; team-agent attach-leader"
+        ),
+    })
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

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

@@ -2314,12 +2314,29 @@ pub mod lifecycle_port {
         force: bool,
         team: Option<&str>,
     ) -> Result<Value, CliError> {
+        let agent_id = crate::model::ids::AgentId::new(agent);
+        match crate::lifecycle::remove_agent_flag_requirements(workspace, &agent_id, team) {
+            Ok(requirements) => {
+                if !remove_agent_missing_flags(from_spec, confirm, force, &requirements).is_empty() {
+                    return Ok(remove_agent_flag_refusal(
+                        workspace,
+                        agent,
+                        team,
+                        from_spec,
+                        confirm,
+                        force,
+                        &requirements,
+                    ));
+                }
+            }
+            Err(error) if confirm => return Ok(error_value(error)),
+            Err(_) => {}
+        }
         if !confirm {
             return Ok(
                 json!({"ok": false, "agent_id": agent, "error": "remove-agent requires --confirm"}),
             );
         }
-        let agent_id = crate::model::ids::AgentId::new(agent);
         match crate::lifecycle::remove_agent(workspace, &agent_id, from_spec, force, team) {
             Ok(report @ crate::lifecycle::RemoveAgentOutcome::Removed { .. }) => Ok(json!({
                 "ok": true,
@@ -2343,9 +2360,121 @@ pub mod lifecycle_port {
                 "error": "agent is running; remove-agent requires --force",
                 "action": "rerun with --force to stop and remove the running agent",
             })),
+            Ok(crate::lifecycle::RemoveAgentOutcome::RefusedRequiredFlags { .. }) => Ok(json!({
+                "ok": false,
+                "agent_id": agent,
+                "status": "refused",
+                "reason": "remove_agent_flags_required",
+                "error": "remove-agent required flags changed; rerun the command from the latest refusal",
+            })),
             Err(e) => Ok(error_value(e)),
         }
     }
+
+    fn remove_agent_flag_refusal(
+        workspace: &Path,
+        agent: &str,
+        team: Option<&str>,
+        from_spec: bool,
+        confirm: bool,
+        force: bool,
+        requirements: &crate::lifecycle::RemoveAgentFlagRequirements,
+    ) -> Value {
+        let required_flags = remove_agent_required_flags(requirements);
+        let missing_flags = remove_agent_missing_flags(from_spec, confirm, force, requirements);
+        let reason = if missing_flags.len() == 1 {
+            match missing_flags[0] {
+                "--confirm" => "confirm_required",
+                "--from-spec" => "from_spec_confirm_required",
+                "--force" => "force_required",
+                _ => "remove_agent_flags_required",
+            }
+        } else {
+            "remove_agent_flags_required"
+        };
+        let command = remove_agent_command(workspace, agent, team, &required_flags);
+        let required = required_flags.join(" ");
+        json!({
+            "ok": false,
+            "agent_id": agent,
+            "status": "refused",
+            "reason": reason,
+            "error": format!("remove-agent requires {required} for this agent"),
+            "action": format!("rerun: {command}"),
+            "command": command,
+            "missing_flags": missing_flags,
+            "required_flags": required_flags,
+            "state": {
+                "from_spec_required": requirements.from_spec_required,
+                "running": requirements.force_required,
+                "has_session": requirements.has_session,
+            },
+        })
+    }
+
+    fn remove_agent_missing_flags(
+        from_spec: bool,
+        confirm: bool,
+        force: bool,
+        requirements: &crate::lifecycle::RemoveAgentFlagRequirements,
+    ) -> Vec<&'static str> {
+        remove_agent_required_flags(requirements)
+            .into_iter()
+            .filter(|flag| match *flag {
+                "--from-spec" => !from_spec,
+                "--confirm" => !confirm,
+                "--force" => !force,
+                _ => false,
+            })
+            .collect()
+    }
+
+    fn remove_agent_required_flags(
+        requirements: &crate::lifecycle::RemoveAgentFlagRequirements,
+    ) -> Vec<&'static str> {
+        let mut flags = Vec::new();
+        if requirements.from_spec_required {
+            flags.push("--from-spec");
+        }
+        flags.push("--confirm");
+        if requirements.force_required {
+            flags.push("--force");
+        }
+        flags
+    }
+
+    fn remove_agent_command(
+        workspace: &Path,
+        agent: &str,
+        team: Option<&str>,
+        required_flags: &[&str],
+    ) -> String {
+        let mut parts = vec![
+            "team-agent".to_string(),
+            "remove-agent".to_string(),
+            shell_arg(agent),
+            "--workspace".to_string(),
+            shell_arg(&workspace.to_string_lossy()),
+        ];
+        if let Some(team) = team {
+            parts.push("--team".to_string());
+            parts.push(shell_arg(team));
+        }
+        parts.extend(required_flags.iter().map(|flag| (*flag).to_string()));
+        parts.join(" ")
+    }
+
+    fn shell_arg(raw: &str) -> String {
+        if !raw.is_empty()
+            && raw
+                .bytes()
+                .all(|b| b.is_ascii_alphanumeric() || matches!(b, b'/' | b'.' | b'_' | b'-' | b':'))
+        {
+            raw.to_string()
+        } else {
+            format!("'{}'", raw.replace('\'', "'\\''"))
+        }
+    }
     /// `runtime.acknowledge_idle`(`cmd_acknowledge_idle`)。
     pub fn acknowledge_idle(workspace: &Path, team: Option<&str>) -> Result<Value, CliError> {
         let mut state = crate::state::persist::load_runtime_state(workspace)

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

@@ -531,6 +531,55 @@ fn resolve_bare_agent(
     }
 }
 
+/// Phase-DX E3 (plan §4 / CR supplements A/B/C, P0 red lines #1 & #6):
+/// build advisory diagnostic candidates for a failed `--to-name leader`
+/// resolution. The candidate list is deliberately shaped to be **read by
+/// humans**, not consumed as route authority: every entry carries
+/// `advisory: true` and a `source` tag identifying where it was observed.
+///
+/// Candidate source rules:
+/// - The transport passed in is already scoped by [`transport_for_cli_target`]
+///   to the team's recorded `leader_receiver.tmux_socket` (or the workspace
+///   default when no socket was recorded), so `transport.list_targets()`
+///   enumerates only that endpoint. We do NOT scan other tmux sockets or
+///   fall back to reverse-authority tmux-session discovery.
+/// - `pane_id` fields are copied verbatim from `list_targets`. `session` is
+///   the tmux session, and `socket` records the tmux endpoint the candidate
+///   was seen on (whichever the scoped transport reports).
+///
+/// Callers must never treat any candidate as authoritative; MUST-NOT-12 stays
+/// intact — resolver refusal is still the outcome even when candidates fire.
+fn leader_advisory_candidates(
+    state: &Value,
+    team: &str,
+    transport: &dyn Transport,
+    source: &str,
+) -> Vec<Value> {
+    let socket = team_entry(state, team)
+        .and_then(|entry| entry.get("leader_receiver"))
+        .or_else(|| state.get("leader_receiver"))
+        .and_then(|receiver| string_field(receiver, "tmux_socket"))
+        .map(str::to_string)
+        .or_else(|| transport.tmux_endpoint());
+    let targets = match transport.list_targets() {
+        Ok(targets) => targets,
+        Err(_) => return Vec::new(),
+    };
+    targets
+        .into_iter()
+        .map(|pane| {
+            json!({
+                "pane_id": pane.pane_id.as_str(),
+                "session": pane.session.as_str(),
+                "window": pane.window_name.as_ref().map(|w| w.as_str()),
+                "socket": socket,
+                "source": source,
+                "advisory": json!(true),
+            })
+        })
+        .collect()
+}
+
 fn resolve_leader(
     sender_workspace: &Path,
     target_workspace: &Path,
@@ -544,7 +593,12 @@ fn resolve_leader(
     } else {
         state.get("leader_receiver")
     }
-    .ok_or_else(|| name_not_live_leader(team, None, None, None, transport.tmux_endpoint()))?;
+    .ok_or_else(|| {
+        let mut err = name_not_live_leader(team, None, None, None, transport.tmux_endpoint());
+        err.candidates =
+            leader_advisory_candidates(state, team, transport, "state_recorded_socket");
+        err
+    })?;
     if let Some((mode, transport_kind)) = receiver_transport_conflict(receiver) {
         let mut err = NamedAddressError::new(
             NamedAddressErrorKind::NameNotLive,
@@ -569,7 +623,13 @@ fn resolve_leader(
     }
     let pane_id = string_field(receiver, "pane_id")
         .filter(|pane| !pane.is_empty())
-        .ok_or_else(|| name_not_live_leader(team, None, None, None, transport.tmux_endpoint()))?;
+        .ok_or_else(|| {
+            let mut err =
+                name_not_live_leader(team, None, None, None, transport.tmux_endpoint());
+            err.candidates =
+                leader_advisory_candidates(state, team, transport, "state_recorded_socket");
+            err
+        })?;
     let session = string_field(receiver, "session_name");
     let window = string_field(receiver, "window_name");
     let socket = string_field(receiver, "tmux_socket")
@@ -599,13 +659,13 @@ fn resolve_leader(
             agent_status: None,
             warning: None,
         }),
-        0 => Err(name_not_live_leader(
-            team,
-            Some(pane_id),
-            session,
-            window,
-            socket,
-        )),
+        0 => {
+            let mut err =
+                name_not_live_leader(team, Some(pane_id), session, window, socket);
+            err.candidates =
+                leader_advisory_candidates(state, team, transport, "state_recorded_socket");
+            Err(err)
+        }
         _ => Err(name_ambiguous(
             "multiple live panes matched leader_receiver pane id",
             matches

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

@@ -39,7 +39,7 @@ pub fn cmd_send(args: &SendArgs) -> Result<CmdResult, CliError> {
             args.json,
         )?;
         add_send_reminder_if_ok(&mut value);
-        return Ok(CmdResult::from_json(value, args.json));
+        return Ok(cmd_send_result(value, args.json));
     }
     // F1 (0.3.26, cross-team send): --pane <pane_id> direct targeting.
     // Mutually exclusive with target / --to (agent-name routing).
@@ -68,7 +68,7 @@ pub fn cmd_send(args: &SendArgs) -> Result<CmdResult, CliError> {
             args.json,
         )?;
         add_send_reminder_if_ok(&mut value);
-        return Ok(CmdResult::from_json(value, args.json));
+        return Ok(cmd_send_result(value, args.json));
     }
     let selected = crate::state::selector::resolve_active_team(
         &args.workspace,
@@ -88,7 +88,7 @@ pub fn cmd_send(args: &SendArgs) -> Result<CmdResult, CliError> {
     if let Some(amb) =
         routing_ambiguous_value(&selected.run_workspace, args, &target, &content, &opts)
     {
-        return Ok(CmdResult::from_json(amb, args.json));
+        return Ok(cmd_send_result(amb, args.json));
     }
     let mut outcome = messaging::send_message(&selected.run_workspace, &target, &content, &opts)?;
     if opts.watch_result {
@@ -101,7 +101,7 @@ pub fn cmd_send(args: &SendArgs) -> Result<CmdResult, CliError> {
         }
     }
     add_send_reminder_if_ok(&mut value);
-    Ok(CmdResult::from_json(value, args.json))
+    Ok(cmd_send_result(value, args.json))
 }
 
 /// F1 (0.3.26): direct pane-id send — bypasses agent-name routing + team
@@ -752,8 +752,98 @@ fn add_send_reminder_if_ok(value: &mut Value) {
     if value.get("ok").and_then(Value::as_bool) != Some(true) {
         return;
     }
+    let reminder = send_reminder_for_value(value);
     if let Some(obj) = value.as_object_mut() {
-        obj.insert("reminder".to_string(), json!(crate::cli::SEND_REMINDER));
+        obj.insert("reminder".to_string(), json!(reminder));
+    }
+}
+
+fn cmd_send_result(value: Value, as_json: bool) -> CmdResult {
+    let exit = if value.get("ok").and_then(Value::as_bool) == Some(false) {
+        ExitCode::Error
+    } else {
+        ExitCode::Ok
+    };
+    if as_json {
+        CmdResult::from_json(value, true)
+    } else {
+        CmdResult {
+            output: CmdOutput::Human(send_human_output(&value)),
+            exit,
+            as_json: false,
+        }
+    }
+}
+
+fn send_human_output(value: &Value) -> String {
+    let mut parts = vec![
+        send_human_field(value, "ok"),
+        format!("status: {}", send_human_status(value)),
+        send_human_field(value, "message_id"),
+        format!("target: {}", send_human_target(value)),
+    ];
+    for key in ["verification", "stage", "reason", "channel"] {
+        if !value.get(key).is_none_or(Value::is_null) {
+            parts.push(send_human_field(value, key));
+        }
+    }
+    parts.join(" ")
+}
+
+fn send_human_field(value: &Value, key: &str) -> String {
+    let rendered = value
+        .get(key)
+        .map(send_human_value)
+        .unwrap_or_else(|| "None".to_string());
+    format!("{key}: {rendered}")
+}
+
+fn send_human_target(value: &Value) -> String {
+    ["target", "agent_id", "pane_id", "to_name"]
+        .iter()
+        .find_map(|key| value.get(*key).filter(|v| !v.is_null()))
+        .map(send_human_value)
+        .unwrap_or_else(|| "None".to_string())
+}
+
+fn send_human_status(value: &Value) -> String {
+    value
+        .get("status")
+        .map(send_human_value)
+        .unwrap_or_else(|| {
+            if value.get("ok").and_then(Value::as_bool) == Some(true) {
+                "delivered".to_string()
+            } else {
+                "failed".to_string()
+            }
+        })
+}
+
+fn send_human_value(value: &Value) -> String {
+    let text = match value {
+        Value::Null => "None".to_string(),
+        Value::Bool(true) => "True".to_string(),
+        Value::Bool(false) => "False".to_string(),
+        Value::Number(n) => n.to_string(),
+        Value::String(s) => s.clone(),
+        Value::Array(_) | Value::Object(_) => {
+            serde_json::to_string(value).unwrap_or_else(|_| "None".to_string())
+        }
+    };
+    text.replace(['\r', '\n'], " ")
+}
+
+fn send_reminder_for_value(value: &Value) -> &'static str {
+    let delivered = value.get("delivered").and_then(Value::as_bool);
+    let status = value.get("status").and_then(Value::as_str);
+    let delivery_status = value.get("delivery_status").and_then(Value::as_str);
+    if delivered == Some(false)
+        || matches!(status, Some("queued"))
+        || matches!(delivery_status, Some("pending"))
+    {
+        "Message queued; coordinator will notify when the worker receives it. Do not poll the worker terminal with capture-pane."
+    } else {
+        crate::cli::SEND_REMINDER
     }
 }
 

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

@@ -38,7 +38,9 @@ use rusqlite::params;
             coordinator_running,
             undelivered_backlog,
         );
-        let agents = enrich_agents(state.get("agents"));
+        let session_name = state.get("session_name").cloned().unwrap_or(Value::Null);
+        let tmux_present = tmux_session_present(workspace, state, session_name.as_str());
+        let agents = enrich_agents(state.get("agents"), tmux_present);
         let tasks = state
             .get("tasks")
             .cloned()
@@ -47,7 +49,6 @@ use rusqlite::params;
             .get("leader_receiver")
             .cloned()
             .unwrap_or_else(|| json!({}));
-        let session_name = state.get("session_name").cloned().unwrap_or(Value::Null);
         let is_external_leader = crate::state::projection::state_is_external_leader(state);
         let leader_topology = if is_external_leader { "external" } else { "managed" };
         let leader_attach_command = if is_external_leader {
@@ -70,7 +71,6 @@ use rusqlite::params;
                 )
             })
         };
-        let tmux_present = tmux_session_present(workspace, state, session_name.as_str());
         let mut readiness_state = state.clone();
         if let Some(obj) = readiness_state.as_object_mut() {
             obj.insert("tmux_session_present".to_string(), serde_json::json!(tmux_present));
@@ -437,7 +437,7 @@ use rusqlite::params;
             .to_string()
     }
 
-    fn enrich_agents(agents: Option<&Value>) -> Value {
+    fn enrich_agents(agents: Option<&Value>, tmux_session_present: bool) -> Value {
         let Some(Value::Object(input)) = agents else {
             return json!({});
         };
@@ -450,6 +450,15 @@ use rusqlite::params;
                         "interacted".to_string(),
                         Value::String(interacted_marker(obj.get("first_send_at"))),
                     );
+                    if let Some(reason) =
+                        stale_reason_for_agent(&Value::Object(obj.clone()), tmux_session_present)
+                    {
+                        enriched.insert("stale".to_string(), Value::Bool(true));
+                        enriched.insert(
+                            "stale_reason".to_string(),
+                            Value::String(reason.to_string()),
+                        );
+                    }
                     out.insert(agent_id.clone(), Value::Object(enriched));
                 }
                 _ => {
@@ -460,6 +469,53 @@ use rusqlite::params;
         Value::Object(out)
     }
 
+    fn stale_reason_for_agent(agent: &Value, tmux_session_present: bool) -> Option<&'static str> {
+        let pane_dead = !tmux_session_present && agent_has_pane_fact(agent);
+        let process_dead =
+            agent_process_dead(agent) || (!tmux_session_present && agent_has_process_fact(agent));
+        match (pane_dead, process_dead) {
+            (true, true) => Some("both"),
+            (false, true) => Some("process_dead"),
+            (true, false) => Some("pane_dead"),
+            (false, false) => None,
+        }
+    }
+
+    fn agent_has_pane_fact(agent: &Value) -> bool {
+        ["pane_id", "window", "window_name"].iter().any(|key| {
+            agent
+                .get(*key)
+                .and_then(Value::as_str)
+                .is_some_and(|value| !value.is_empty())
+        })
+    }
+
+    fn agent_has_process_fact(agent: &Value) -> bool {
+        agent.get("pid").and_then(Value::as_i64).is_some()
+            || agent.get("process_started").and_then(Value::as_bool) == Some(true)
+            || agent.get("provider_process_dead").and_then(Value::as_bool).is_some()
+            || agent.get("process_liveness").and_then(Value::as_str).is_some()
+    }
+
+    fn agent_process_dead(agent: &Value) -> bool {
+        if agent.get("provider_process_dead").and_then(Value::as_bool) == Some(true) {
+            return true;
+        }
+        ["process_liveness", "worker_state"].iter().any(|key| {
+            agent
+                .get(*key)
+                .and_then(Value::as_str)
+                .is_some_and(is_dead_process_state)
+        })
+    }
+
+    fn is_dead_process_state(value: &str) -> bool {
+        matches!(
+            value,
+            "dead" | "missing" | "stopped" | "exited" | "terminated"
+        )
+    }
+
     fn interacted_marker(value: Option<&Value>) -> String {
         let Some(raw) = value.and_then(Value::as_str) else {
             return "never".to_string();
@@ -846,7 +902,15 @@ use rusqlite::params;
         // 0.4.x Phase 1: add `worker_state` (canonical 5-state product
         // surface). `activity` is preserved alongside as the deprecated
         // legacy classifier output (CR R3 same-source contract).
-        for key in ["status", "provider", "worker_state", "activity", "last_output_at"] {
+        for key in [
+            "status",
+            "provider",
+            "worker_state",
+            "activity",
+            "last_output_at",
+            "stale",
+            "stale_reason",
+        ] {
             if let Some(value) = input.get(key) {
                 out.insert(key.to_string(), value.clone());
             }
@@ -964,10 +1028,35 @@ use rusqlite::params;
             );
             insert_optional_string(&mut item, "last_output_at", row.get(2).map_err(|e| CliError::Runtime(e.to_string()))?);
             insert_optional_i64(&mut item, "context_usage_pct", row.get(3).map_err(|e| CliError::Runtime(e.to_string()))?);
-            insert_optional_string(&mut item, "current_task_id", row.get(4).map_err(|e| CliError::Runtime(e.to_string()))?);
+            let current_task_id: Option<String> =
+                row.get(4).map_err(|e| CliError::Runtime(e.to_string()))?;
+            let has_current_task = current_task_id.is_some();
+            insert_optional_string(&mut item, "current_task_id", current_task_id);
+            let updated_at: String =
+                row.get(5).map_err(|e| CliError::Runtime(e.to_string()))?;
+            // Phase-DX E2 (plan §4 / CR supplement A): expose the last agent_health
+            // observation timestamp as `health_updated_at` alongside the legacy
+            // `updated_at` alias. Two names for one column keep old scrapers working
+            // while surfacing the semantic (heartbeat, not row bookkeeping).
+            item.insert("updated_at".to_string(), json!(updated_at.clone()));
+            item.insert("health_updated_at".to_string(), json!(updated_at));
+            // Phase-DX E2 (CR P0 red line #6, supplements A/B): current_task is a
+            // best-effort *display* field until A1 makes task FSM authoritative.
+            // The structured source/confidence markers stop downstream code from
+            // treating agent_health.current_task_id as authority. `current_task_source`
+            // records where the display value came from (only "health" today —
+            // Phase-DX never merges state tasks into this projection); the
+            // `current_task_confidence` enum stays "best_effort" for the whole
+            // Phase-DX slice (A1 will later flip it to "authoritative" when the
+            // task FSM lands). Field is written unconditionally so consumers can
+            // switch on it even when `current_task_id` is null.
+            item.insert(
+                "current_task_source".to_string(),
+                json!(if has_current_task { "health" } else { "none" }),
+            );
             item.insert(
-                "updated_at".to_string(),
-                json!(row.get::<_, String>(5).map_err(|e| CliError::Runtime(e.to_string()))?),
+                "current_task_confidence".to_string(),
+                json!("best_effort"),
             );
             insert_optional_string(&mut item, "owner_team_id", row.get(6).map_err(|e| CliError::Runtime(e.to_string()))?);
             out.insert(agent_id, Value::Object(item));