@team-agent/installer 0.5.82 → 0.5.83

package/Cargo.lock

@@ -581,7 +581,7 @@ dependencies = [
 
 [[package]]
 name = "team-agent"
-version = "0.5.82"
+version = "0.5.83"
 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.82"
+version = "0.5.83"
 license = "AGPL-3.0"
 rust-version = "1.95"
 

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

@@ -218,7 +218,7 @@ fn dispatch(command: &str, args: &[String], cwd: &Path) -> Result<ExitCode, CliE
         // resolve short/qualified/hash-qualified names to a canonical
         // (workspace, team_key) tuple and delegates to the E6 named-leader
         // delivery path — no separate route authority.
-        "leaders" => cmd_leaders(&leaders_args(args, cwd)).map(emit_result),
+        "leaders" => cmd_leaders(&leaders_args(args, cwd)?).map(emit_result),
         "models" => cmd_models(&models_args(args)?).map(emit_result),
         "validate" => cmd_validate(&validate_args(args, cwd)).map(emit_result),
         "install-skill" => cmd_install_skill(&install_skill_args(args)?).map(emit_result),
@@ -324,7 +324,15 @@ pub(crate) fn default_help() -> String {
     append_help_section(
         &mut out,
         "Core",
-        &["quick-start", "send", "status", "collect", "results", "models"],
+        &[
+            "quick-start",
+            "send",
+            "status",
+            "collect",
+            "results",
+            "models",
+            "leaders",
+        ],
     );
     append_help_section(
         &mut out,
@@ -411,6 +419,7 @@ fn command_help(command: Option<&str>) -> String {
         Some("allow-peer-talk") => "usage: team-agent allow-peer-talk A B [--workspace WORKSPACE] [--json]".to_string(),
         Some("status") => "usage: team-agent status [AGENT] [--workspace WORKSPACE] [--team TEAM] [--summary|--json] [--detail]\n\n输出七字段：name/provider/runtime_status/activity/health/session_name/tmux_command；人读与 --json 使用同一投影。缺少可靠定位或 nodeprobe 证据时显示 unknown；tmux_command 可复制到对应目标。--summary/--detail 仅保留兼容性，不增加诊断字段。".to_string(),
         Some("models") => "usage: team-agent models --provider pi [--search TEXT] [--json]\n\nPrints models.v1 exact role_model entries; each entry includes current=true|false. Catalog readiness is reported as auth=ok|not_ready with auth_basis=catalog_visibility.".to_string(),
+        Some("leaders") => "usage: team-agent leaders [QUERY|--search TEXT] [--all|--stale] [--json] | --prune [--dry-run] [--json]\n\nLists LIVE leaders by default. Use --all to include retained STALE entries, --stale to inspect only STALE entries, QUERY or --search TEXT to match workspace/team/name fields, and --prune to remove only entries proven terminal by canonical state. --dry-run is valid only with --prune.".to_string(),
         Some("stop") => compat_hidden_help("stop", "usage: team-agent stop [--workspace WORKSPACE] [--team TEAM] [--keep-logs] [--json]"),
         Some("shutdown") => "usage: team-agent shutdown [--workspace WORKSPACE] [--team TEAM] [--keep-logs] [--json]".to_string(),
         Some("restart") => "usage: team-agent restart [WORKSPACE] [--team TEAM] [--allow-fresh] [--session-converge-deadline SECONDS] [--json] [--detail]".to_string(),
@@ -1683,9 +1692,109 @@ fn sessions_args(args: &[String], cwd: &Path) -> SessionsArgs {
     }
 }
 
-fn leaders_args(args: &[String], _cwd: &Path) -> LeadersArgs {
-    let parsed = parse_args(args);
-    LeadersArgs { json: parsed.json }
+fn leaders_args(args: &[String], _cwd: &Path) -> Result<LeadersArgs, CliError> {
+    let mut view = None;
+    let mut query = None;
+    let mut prune = false;
+    let mut dry_run = false;
+    let mut json = false;
+    let mut i = 0usize;
+    while i < args.len() {
+        let arg = &args[i];
+        match arg.as_str() {
+            "--json" => json = true,
+            "--all" => {
+                if view.replace(LeadersView::All).is_some() {
+                    return Err(CliError::Usage(
+                        "leaders accepts only one of --all or --stale".to_string(),
+                    ));
+                }
+            }
+            "--stale" => {
+                if view.replace(LeadersView::Stale).is_some() {
+                    return Err(CliError::Usage(
+                        "leaders accepts only one of --all or --stale".to_string(),
+                    ));
+                }
+            }
+            "--prune" => {
+                if prune {
+                    return Err(CliError::Usage(
+                        "leaders accepts --prune at most once".to_string(),
+                    ));
+                }
+                prune = true;
+            }
+            "--dry-run" => dry_run = true,
+            "--search" => {
+                let Some(value) = args.get(i.saturating_add(1)) else {
+                    return Err(CliError::Usage(
+                        "leaders --search requires TEXT".to_string(),
+                    ));
+                };
+                if value.starts_with('-') {
+                    return Err(CliError::Usage(
+                        "leaders --search requires TEXT".to_string(),
+                    ));
+                }
+                i = i.saturating_add(1);
+                if query.replace(value.clone()).is_some() {
+                    return Err(CliError::Usage(
+                        "leaders accepts only one QUERY or --search TEXT".to_string(),
+                    ));
+                }
+            }
+            value if value.starts_with("--search=") => {
+                let value = value.trim_start_matches("--search=").to_string();
+                if query.replace(value).is_some() {
+                    return Err(CliError::Usage(
+                        "leaders accepts only one QUERY or --search TEXT".to_string(),
+                    ));
+                }
+            }
+            value if value.starts_with('-') => {
+                return Err(CliError::Usage(format!(
+                    "unknown leaders argument: {value}"
+                )))
+            }
+            value => {
+                if query.replace(value.to_string()).is_some() {
+                    return Err(CliError::Usage(
+                        "leaders accepts only one QUERY or --search TEXT".to_string(),
+                    ));
+                }
+            }
+        }
+        i = i.saturating_add(1);
+    }
+    if query
+        .as_deref()
+        .is_some_and(|value| value.trim().is_empty())
+    {
+        return Err(CliError::Usage("leaders QUERY cannot be blank".to_string()));
+    }
+    if prune && view.is_some() {
+        return Err(CliError::Usage(
+            "leaders --prune cannot be combined with --all or --stale".to_string(),
+        ));
+    }
+    if prune && query.is_some() {
+        return Err(CliError::Usage(
+            "leaders --prune cannot be combined with QUERY or --search".to_string(),
+        ));
+    }
+    if dry_run && !prune {
+        return Err(CliError::Usage(
+            "leaders --dry-run requires --prune".to_string(),
+        ));
+    }
+    Ok(LeadersArgs {
+        view: view.unwrap_or(LeadersView::Live),
+        query,
+        prune,
+        dry_run,
+        json,
+    })
 }
 
 fn validate_args(args: &[String], cwd: &Path) -> ValidateArgs {
@@ -1935,6 +2044,37 @@ mod tests {
             .collect()
     }
 
+    #[test]
+    fn leaders_parser_supports_views_and_search() {
+        let parsed = leaders_args(
+            &cli_argv(&["--all", "--search", "Wiki", "--json"]),
+            Path::new("."),
+        )
+        .unwrap();
+        assert_eq!(parsed.view, LeadersView::All);
+        assert_eq!(parsed.query.as_deref(), Some("Wiki"));
+        assert!(!parsed.prune);
+        assert!(!parsed.dry_run);
+        assert!(parsed.json);
+    }
+
+    #[test]
+    fn leaders_parser_rejects_invalid_search_and_prune_combinations() {
+        for args in [
+            cli_argv(&["one", "two"]),
+            cli_argv(&["one", "--search", "two"]),
+            cli_argv(&["--search", "   "]),
+            cli_argv(&["--dry-run"]),
+            cli_argv(&["--prune", "--stale"]),
+            cli_argv(&["--prune", "--search", "x"]),
+        ] {
+            assert!(
+                leaders_args(&args, Path::new(".")).is_err(),
+                "args={args:?}"
+            );
+        }
+    }
+
     #[test]
     fn command_specs_have_unique_names_and_valid_aliases() {
         let mut names = std::collections::BTreeSet::new();
@@ -2031,6 +2171,16 @@ mod tests {
         }
     }
 
+    #[test]
+    fn leaders_help_publishes_selectors_and_prune() {
+        let help = command_help(Some("leaders"));
+        assert!(help.contains("--all"));
+        assert!(help.contains("--stale"));
+        assert!(help.contains("--search TEXT"));
+        assert!(help.contains("--prune"));
+        assert!(help.contains("--dry-run"));
+    }
+
     #[test]
     fn compat_hidden_help_has_sunset_action() {
         for command in ["stop", "restart-agent", "start", "init"] {

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

@@ -1,220 +1,357 @@
-//! ---
-//! purpose: `team-agent leaders` 发现面。人读默认面按节点列出 workspace 全路径、
-//!   team/leader、可复制 `team-agent send '<ws>::<team>/leader' '<消息>'`。
-//! contract:
-//!   provides:
-//!     - name: cmd_leaders
-//!       what: --json 保持 E7 字段(含 hash/send_hint); 默认 stdout 只有三要素、不含 hash/channel/pane id
-//! boundary:
-//!   - 不改 send 解析; 不把 --json 字段从默认面漏出去
-//!   - Leaders-only; worker 行仍缺席
-//! ---
+//! `team-agent leaders` host-level discovery and registry maintenance.
 //!
-//! E7 (0.5.9 host-leader-registry-design §4.1): `team-agent leaders` command.
-//!
-//! Enumerates entries under `~/.team-agent/leaders`, re-validates each
-//! against the target workspace's canonical runtime state, and emits a
-//! LIVE / STALE / AMBIGUOUS classification. Leaders-only — worker rows,
-//! task rows, and result rows are deliberately absent from the output.
-//!
-//! The command is a **discovery** surface, not a route authority. Callers
-//! that consume `send_hint` must still re-validate via
-//! `named_address::resolve_name_for_cli` before delivery — this file only
-//! reports what registry sees now.
+//! Listing is read-only: it validates the derived registry index without
+//! deleting entries. Explicit `--prune` is the only path that removes entries.
+//! The command is a discovery surface, not a route authority; send callers
+//! continue to re-validate through the named-address resolver.
+
+use std::collections::BTreeMap;
 
-use super::{types::LeadersArgs, CliError, CmdResult};
 use serde_json::{json, Value};
 
+use super::{
+    types::{LeadersArgs, LeadersView},
+    CliError, CmdResult, ExitCode,
+};
+use crate::leader::registry::{LeaderRegistryEntry, RegistryPruneItem, RegistryPruneReport};
+
+#[derive(Debug, Clone)]
+struct LeaderRow {
+    entry: LeaderRegistryEntry,
+    status: &'static str,
+    stale_reason: Option<String>,
+    send_hint: String,
+}
+
+/// E7 CLI entry point.
 ///
-/// E7 CLI entry point (E7 test 2 marker: `cmd_leaders`).
-///
-/// Reads registry entries, canonical-validates each, and groups by
-/// delivery_name to classify each as LIVE / STALE / AMBIGUOUS. Terminal
-/// stale entries (canonical workspace/team gone) are pruned as GC side
-/// effect. Leader-detached-but-team-alive stays visible as STALE so the
-/// operator can decide.
+/// The default view contains only canonical-live entries. `--all` preserves
+/// live and retained stale entries, while `--stale` selects only stale rows.
+/// None of the listing views mutates the host registry.
 pub fn cmd_leaders(args: &LeadersArgs) -> Result<CmdResult, CliError> {
     let dir = crate::leader::registry::registry_dir()
         .map(|p| p.display().to_string())
         .unwrap_or_else(|| "~/.team-agent/leaders".to_string());
-    let classified = crate::leader::registry::list_validated_with_gc();
-    let mut name_counts: std::collections::HashMap<String, Vec<Value>> =
-        std::collections::HashMap::new();
-    for (entry, _status, _reason) in &classified {
-        name_counts
-            .entry(entry.delivery_name.clone())
-            .or_default()
-            .push(json!({
-                "name": entry.qualified_name,
-                "workspace": entry.workspace.display().to_string(),
-                "team_key": entry.team_key,
-                "workspace_hash": entry.workspace_hash,
-                "stable_qualified_name": entry.stable_qualified_name,
-            }));
+    if args.prune {
+        return cmd_prune(args, &dir);
     }
-    let ambiguous_map: std::collections::HashMap<String, Vec<Value>> = name_counts
-        .iter()
-        .filter(|(_, list)| list.len() > 1)
-        .map(|(k, v)| (k.clone(), v.clone()))
-        .collect();
-    let mut leaders: Vec<Value> = Vec::new();
-    for (entry, status, reason) in &classified {
-        let final_status = if ambiguous_map.contains_key(&entry.delivery_name) {
-            "AMBIGUOUS"
-        } else {
-            *status
-        };
-        let send_hint = format!(
-            "team-agent send --to-leader {} MESSAGE",
-            entry.qualified_name
-        );
-        leaders.push(json!({
-            "name": entry.delivery_name,
-            "delivery_name": entry.delivery_name,
-            "qualified_name": entry.qualified_name,
-            "stable_qualified_name": entry.stable_qualified_name,
-            "workspace": entry.workspace.display().to_string(),
-            "workspace_hash": entry.workspace_hash,
-            "workspace_short": entry.workspace_short,
-            "team_key": entry.team_key,
-            "transport_kind": entry.transport_kind,
-            "owner_epoch": entry.owner_epoch,
-            "status": final_status,
-            "stale_reason": reason.clone(),
-            "send_hint": send_hint,
-        }));
+
+    let mut classified = crate::leader::registry::list_validated_no_gc();
+    classified.sort_by(|left, right| {
+        left.0
+            .workspace
+            .cmp(&right.0.workspace)
+            .then_with(|| left.0.team_key.cmp(&right.0.team_key))
+    });
+    let mut active_candidates: BTreeMap<String, Vec<Value>> = BTreeMap::new();
+    for (entry, status, _) in &classified {
+        if *status == "LIVE" {
+            active_candidates
+                .entry(entry.delivery_name.clone())
+                .or_default()
+                .push(candidate_json(entry));
+        }
     }
-    let ambiguous_names: Vec<Value> = ambiguous_map
-        .into_iter()
+    let ambiguous_names = active_candidates
+        .iter()
+        .filter(|(_, candidates)| candidates.len() > 1)
         .map(|(name, candidates)| {
             json!({
                 "name": name,
                 "candidates": candidates,
             })
         })
-        .collect();
+        .collect::<Vec<_>>();
+
+    let rows = classified
+        .into_iter()
+        .map(|(entry, status, reason)| {
+            let ambiguous = status == "LIVE"
+                && active_candidates
+                    .get(&entry.delivery_name)
+                    .is_some_and(|candidates| candidates.len() > 1);
+            let status = if ambiguous { "AMBIGUOUS" } else { status };
+            let stale_reason = if ambiguous {
+                Some(crate::leader::registry::REASON_AMBIGUOUS.to_string())
+            } else {
+                reason
+            };
+            let send_hint = if status == "STALE" {
+                "-".to_string()
+            } else {
+                send_hint(&entry)
+            };
+            LeaderRow {
+                entry,
+                status,
+                stale_reason,
+                send_hint,
+            }
+        })
+        .collect::<Vec<_>>();
+    let rows = filter_rows(rows, args.view, args.query.as_deref());
+
+    let leaders = rows.iter().map(row_json).collect::<Vec<_>>();
     let value = json!({
         "ok": true,
         "registry_dir": dir,
         "leaders": leaders,
-        "ambiguous_names": ambiguous_names,
-        // Status vocabulary pinned by E7 RED: LIVE / STALE / AMBIGUOUS.
-        // "stale_reason" is null for LIVE and carries a machine-readable
-        // reason for STALE/AMBIGUOUS entries.
+        "ambiguous_names": if matches!(args.view, LeadersView::Stale) {
+            Vec::<Value>::new()
+        } else {
+            ambiguous_names
+        },
         "status_wire_values": ["LIVE", "STALE", "AMBIGUOUS"],
     });
     if args.json {
         return Ok(CmdResult::from_json(value, true));
     }
-    let rows: Vec<(String, String)> = classified
-        .iter()
-        .map(|(entry, _, _)| {
-            (
-                entry.workspace.display().to_string(),
-                entry.team_key.clone(),
-            )
+    Ok(CmdResult::human(format_leaders_human(&rows, args.view)))
+}
+
+fn candidate_json(entry: &LeaderRegistryEntry) -> Value {
+    json!({
+        "name": entry.qualified_name,
+        "workspace": entry.workspace.display().to_string(),
+        "team_key": entry.team_key,
+        "workspace_hash": entry.workspace_hash,
+        "stable_qualified_name": entry.stable_qualified_name,
+    })
+}
+
+fn send_hint(entry: &LeaderRegistryEntry) -> String {
+    let to = format!("{}::{}/leader", entry.workspace.display(), entry.team_key);
+    format!(
+        "team-agent send {} {}",
+        quote_cli_arg(&to),
+        quote_cli_arg("消息")
+    )
+}
+
+fn row_json(row: &LeaderRow) -> Value {
+    json!({
+        "name": row.entry.delivery_name,
+        "delivery_name": row.entry.delivery_name,
+        "qualified_name": row.entry.qualified_name,
+        "stable_qualified_name": row.entry.stable_qualified_name,
+        "workspace": row.entry.workspace.display().to_string(),
+        "workspace_hash": row.entry.workspace_hash,
+        "workspace_short": row.entry.workspace_short,
+        "team_key": row.entry.team_key,
+        "transport_kind": row.entry.transport_kind,
+        "owner_epoch": row.entry.owner_epoch,
+        "status": row.status,
+        "stale_reason": row.stale_reason,
+        "send_hint": row.send_hint,
+    })
+}
+
+fn filter_rows(rows: Vec<LeaderRow>, view: LeadersView, query: Option<&str>) -> Vec<LeaderRow> {
+    let query = query.map(str::to_lowercase);
+    rows.into_iter()
+        .filter(|row| match view {
+            LeadersView::Live => row.status == "LIVE" || row.status == "AMBIGUOUS",
+            LeadersView::All => true,
+            LeadersView::Stale => row.status == "STALE",
         })
-        .collect();
-    Ok(CmdResult::human(format_leaders_human(&rows)))
+        .filter(|row| {
+            let Some(query) = query.as_deref() else {
+                return true;
+            };
+            [
+                row.entry.workspace.display().to_string(),
+                row.entry.team_key.clone(),
+                row.entry.qualified_name.clone(),
+                row.entry.delivery_name.clone(),
+            ]
+            .iter()
+            .any(|field| field.to_lowercase().contains(query))
+        })
+        .collect()
 }
 
 fn quote_cli_arg(raw: &str) -> String {
-    if !raw.contains('\'') {
-        format!("'{raw}'")
-    } else {
-        format!("\"{}\"", raw.replace('\\', "\\\\").replace('"', "\\\""))
-    }
+    // POSIX single-quoted strings are literal except for the quote itself;
+    // split and escape quotes rather than falling back to unsafe double quotes.
+    format!("'{}'", raw.replace('\'', "'\\''"))
 }
 
-/// Default human face: workspace path, `<team>/leader`, copyable send line.
-fn format_leaders_human(rows: &[(String, String)]) -> String {
+/// Human face: status, complete workspace path, canonical team key, and a
+/// copyable SEND command. Tabs keep paths and commands intact without a table
+/// dependency or truncation.
+fn format_leaders_human(rows: &[LeaderRow], view: LeadersView) -> String {
     if rows.is_empty() {
-        return "no registered leaders\n".to_string();
+        return match view {
+            LeadersView::Live => "no live leaders\n".to_string(),
+            LeadersView::All => "no registered leaders\n".to_string(),
+            LeadersView::Stale => "no stale leaders\n".to_string(),
+        };
     }
-    let mut out = String::new();
-    for (workspace, team_key) in rows {
-        let role = format!("{team_key}/leader");
-        let to = format!("{workspace}::{role}");
-        out.push_str(workspace);
-        out.push('\n');
-        out.push_str(&role);
-        out.push('\n');
-        out.push_str("team-agent send ");
-        out.push_str(&quote_cli_arg(&to));
-        out.push(' ');
-        out.push_str(&quote_cli_arg("消息"));
+    let mut out = String::from("STATUS\tWORKSPACE\tTEAM\tSEND\n");
+    for row in rows {
+        out.push_str(row.status);
+        out.push('\t');
+        out.push_str(&row.entry.workspace.display().to_string());
+        out.push('\t');
+        out.push_str(&row.entry.team_key);
+        out.push('\t');
+        out.push_str(&row.send_hint);
         out.push('\n');
     }
     out
 }
 
+fn prune_item_json(item: &RegistryPruneItem) -> Value {
+    json!({
+        "workspace": item.workspace.display().to_string(),
+        "team_key": item.team_key,
+        "reason": item.reason,
+    })
+}
+
+fn prune_json(report: &RegistryPruneReport) -> Value {
+    json!({
+        "dry_run": report.dry_run,
+        "candidates": report.candidates.iter().map(prune_item_json).collect::<Vec<_>>(),
+        "removed": report.removed.iter().map(prune_item_json).collect::<Vec<_>>(),
+        "kept": report.kept.iter().map(prune_item_json).collect::<Vec<_>>(),
+        "skipped": report.skipped.iter().map(prune_item_json).collect::<Vec<_>>(),
+        "errors": report.errors.iter().map(prune_item_json).collect::<Vec<_>>(),
+    })
+}
+
+fn format_prune_human(report: &RegistryPruneReport) -> String {
+    let mut out = format!("dry-run: {}\n", report.dry_run);
+    for (label, items) in [
+        ("candidates", &report.candidates),
+        ("removed", &report.removed),
+        ("kept", &report.kept),
+        ("skipped", &report.skipped),
+        ("errors", &report.errors),
+    ] {
+        out.push_str(&format!("{label}: {}\n", items.len()));
+        for item in items {
+            out.push_str("  ");
+            out.push_str(&item.workspace.display().to_string());
+            out.push_str("::");
+            out.push_str(&item.team_key);
+            out.push_str(" [");
+            out.push_str(&item.reason);
+            out.push_str("]\n");
+        }
+    }
+    out
+}
+
+fn cmd_prune(args: &LeadersArgs, dir: &str) -> Result<CmdResult, CliError> {
+    let report = crate::leader::registry::prune_registry(args.dry_run);
+    let value = json!({
+        "ok": report.errors.is_empty(),
+        "registry_dir": dir,
+        "prune": prune_json(&report),
+    });
+    if args.json {
+        return Ok(CmdResult::from_json(value, true));
+    }
+    let mut result = CmdResult::human(format_prune_human(&report));
+    if !report.errors.is_empty() {
+        result.exit = ExitCode::Error;
+    }
+    Ok(result)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
 
-    fn sample_human() -> String {
-        format_leaders_human(&[
-            (
-                "/Volumes/nvme/Projects/讨论team-agent".to_string(),
-                "wiki-team".to_string(),
-            ),
-            (
-                "/Users/alauda/Documents/code/agent前沿探索/多agent协作".to_string(),
-                "refactor-maintainability".to_string(),
+    fn row(workspace: &str, team: &str, status: &'static str, send_hint: &str) -> LeaderRow {
+        LeaderRow {
+            entry: LeaderRegistryEntry {
+                schema_version: crate::leader::registry::REGISTRY_SCHEMA_VERSION,
+                delivery_name: team.to_string(),
+                qualified_name: format!("workspace/{team}"),
+                stable_qualified_name: format!("hash/{team}"),
+                aliases: Vec::new(),
+                workspace: workspace.into(),
+                workspace_hash: "hash".to_string(),
+                workspace_short: "workspace".to_string(),
+                team_key: team.to_string(),
+                transport_kind: "direct_tmux".to_string(),
+                channel: Value::Null,
+                owner_epoch: 1,
+                attached_at: String::new(),
+                updated_at: String::new(),
+                source: "test".to_string(),
+                status: "attached".to_string(),
+            },
+            status,
+            stale_reason: (status == "STALE").then(|| "leader_pane_dead".to_string()),
+            send_hint: send_hint.to_string(),
+        }
+    }
+
+    #[test]
+    fn leaders_human_is_a_status_table_and_stale_has_no_send() {
+        let rows = vec![
+            row(
+                "/Volumes/nvme/Projects/讨论team-agent",
+                "wiki-team",
+                "LIVE",
+                "send-live",
             ),
-        ])
+            row("/Users/alauda/stale", "old-team", "STALE", "-"),
+        ];
+        let out = format_leaders_human(&rows, LeadersView::All);
+        assert!(out.starts_with("STATUS\tWORKSPACE\tTEAM\tSEND\n"));
+        assert!(out.contains("LIVE\t/Volumes/nvme/Projects/讨论team-agent\twiki-team\tsend-live\n"));
+        assert!(out.contains("STALE\t/Users/alauda/stale\told-team\t-\n"));
     }
 
     #[test]
-    fn leaders_human_lists_workspace_team_role_and_copyable_send() {
-        let out = sample_human();
-        assert!(
-            out.contains("team-agent send '/"),
-            "A: copyable send TO must start with absolute workspace path; got {out:?}"
-        );
-        assert!(
-            out.contains("::wiki-team/leader'"),
-            "B: send TO must contain ::<team>/<role>; got {out:?}"
-        );
-        assert!(
-            out.contains(
-                "team-agent send '/Volumes/nvme/Projects/讨论team-agent::wiki-team/leader' '消息'"
+    fn stale_rows_are_filtered_from_live_view() {
+        let rows = vec![
+            row("/live", "live", "LIVE", "send"),
+            row("/stale", "stale", "STALE", "-"),
+        ];
+        let rows = filter_rows(rows, LeadersView::Live, None);
+        assert_eq!(rows.len(), 1);
+        assert_eq!(rows[0].entry.team_key, "live");
+    }
+
+    #[test]
+    fn quote_cli_arg_escapes_single_quotes_without_shell_expansion() {
+        assert_eq!(quote_cli_arg("a'b $HOME `date`"), "'a'\\''b $HOME `date`'");
+    }
+
+    #[test]
+    fn search_matches_selected_fields_case_insensitively() {
+        let rows = vec![
+            row(
+                "/Volumes/nvme/Projects/讨论team-agent",
+                "Wiki-Team",
+                "LIVE",
+                "send",
             ),
-            "C: complete copyable send line; got {out:?}"
-        );
-        assert!(out.contains("/Volumes/nvme/Projects/讨论team-agent\nwiki-team/leader\n"));
-        assert!(out.contains(
-            "/Users/alauda/Documents/code/agent前沿探索/多agent协作\nrefactor-maintainability/leader\n"
-        ));
-        assert!(out.contains(
-            "team-agent send '/Users/alauda/Documents/code/agent前沿探索/多agent协作::refactor-maintainability/leader' '消息'"
-        ));
+            row("/Users/alauda/stale", "old-team", "STALE", "-"),
+        ];
+        let rows = filter_rows(rows, LeadersView::All, Some("WIKI-"));
+        assert_eq!(rows.len(), 1);
+        assert_eq!(rows[0].entry.team_key, "Wiki-Team");
     }
 
     #[test]
-    fn leaders_human_omits_hash_channel_and_pane_id_fields() {
-        let out = sample_human();
-        for noise in [
-            "workspace_hash",
-            "stable_qualified_name",
-            "channel_id",
-            "\"channel\":",
-            "pane_id",
-        ] {
-            assert!(
-                !out.contains(noise),
-                "D: default surface must not print {noise}; got {out:?}"
-            );
-        }
-        let empty = format_leaders_human(&[]);
-        for noise in [
-            "workspace_hash",
-            "stable_qualified_name",
-            "channel_id",
-            "\"channel\":",
-            "pane_id",
-        ] {
-            assert!(!empty.contains(noise), "empty surface leaked {noise}");
-        }
+    fn empty_view_names_are_explicit() {
+        assert_eq!(
+            format_leaders_human(&[], LeadersView::Live),
+            "no live leaders\n"
+        );
+        assert_eq!(
+            format_leaders_human(&[], LeadersView::Stale),
+            "no stale leaders\n"
+        );
+        assert_eq!(
+            format_leaders_human(&[], LeadersView::All),
+            "no registered leaders\n"
+        );
     }
 }

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

@@ -198,7 +198,7 @@ pub(crate) const COMMAND_SPECS: &[CommandSpec] = &[
     CommandSpec { name: "stuck-list", tier: CommandTier::CompatHidden, category: CommandCategory::Compat, kind: CommandKind::Dispatch(DispatchKind::StuckList), summary: "legacy stuck alert listing", usage: "usage: team-agent stuck-list [--workspace WORKSPACE] [--team TEAM] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: Some("C2"), action: Some("use `team-agent diagnose`"), governance: None },
     CommandSpec { name: "stuck-cancel", tier: CommandTier::CompatHidden, category: CommandCategory::Compat, kind: CommandKind::Dispatch(DispatchKind::StuckCancel), summary: "legacy stuck alert suppression", usage: "usage: team-agent stuck-cancel AGENT [--workspace WORKSPACE] [--alert-type stuck|idle_fallback|cross_worker_deadlock|all] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: Some("C2"), action: Some("use the concrete notification action or `team-agent diagnose`"), governance: None },
     CommandSpec { name: "acknowledge-idle", tier: CommandTier::CompatHidden, category: CommandCategory::Compat, kind: CommandKind::Dispatch(DispatchKind::AcknowledgeIdle), summary: "legacy idle acknowledgement", usage: "usage: team-agent acknowledge-idle [--workspace WORKSPACE] [--team TEAM] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: Some("C2"), action: Some("use the concrete idle notification action or `team-agent diagnose`"), governance: None },
-    CommandSpec { name: "leaders", tier: CommandTier::Secondary, category: CommandCategory::Observe, kind: CommandKind::Dispatch(DispatchKind::Leaders), summary: "inspect registered host leaders", usage: "usage: team-agent leaders [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
+    CommandSpec { name: "leaders", tier: CommandTier::Secondary, category: CommandCategory::Observe, kind: CommandKind::Dispatch(DispatchKind::Leaders), summary: "list live, stale, or ambiguous host leaders", usage: "usage: team-agent leaders [QUERY|--search TEXT] [--all|--stale] [--json] | --prune [--dry-run] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
     CommandSpec { name: "doctor", tier: CommandTier::Secondary, category: CommandCategory::Setup, kind: CommandKind::Dispatch(DispatchKind::Doctor), summary: "run host maintenance checks", usage: "usage: team-agent doctor [SPEC] [--workspace WORKSPACE] [--team TEAM] [--gate orphans|comms] [--comms] [--fix] [--fix-schema] [--cleanup-orphans] [--confirm] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
     CommandSpec { name: "attach-app-server-leader", tier: CommandTier::Guided, category: CommandCategory::GuidedRecovery, kind: CommandKind::Dispatch(DispatchKind::AttachAppServerLeader), summary: "bind an app-server leader receiver", usage: "usage: team-agent attach-app-server-leader [--workspace WORKSPACE] [--team TEAM] --socket unix:///path.sock --thread-id THREAD_ID [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
     CommandSpec { name: "remove-agent", tier: CommandTier::Secondary, category: CommandCategory::WorkerLifecycle, kind: CommandKind::Dispatch(DispatchKind::RemoveAgent), summary: "remove a worker", usage: "usage: team-agent remove-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--from-spec] [--confirm] [--force] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },

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

@@ -639,8 +639,19 @@ pub struct SessionsArgs {
 /// enumerates the host discovery index and classifies each entry as
 /// LIVE, STALE, or AMBIGUOUS after re-validating against canonical
 /// workspace state.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum LeadersView {
+    Live,
+    All,
+    Stale,
+}
+
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct LeadersArgs {
+    pub view: LeadersView,
+    pub query: Option<String>,
+    pub prune: bool,
+    pub dry_run: bool,
     pub json: bool,
 }
 

package/crates/team-agent/src/leader/registry.rs

@@ -367,8 +367,8 @@ pub fn restore_entry_if_current_matches(
         if receipt.path.parent() != Some(dir) {
             return Err(RegistryRollbackError::InvalidReceipt);
         }
-        let current = std::fs::read(&receipt.path)
-            .map_err(|_| RegistryRollbackError::ReadFailed)?;
+        let current =
+            std::fs::read(&receipt.path).map_err(|_| RegistryRollbackError::ReadFailed)?;
         if current != receipt.bytes {
             return Ok(RegistryRollback::Superseded);
         }
@@ -377,33 +377,117 @@ pub fn restore_entry_if_current_matches(
                 Ok(RegistryRollback::Restored)
             }
             Some(_) => Err(RegistryRollbackError::RestoreFailed),
-            None if std::fs::remove_file(&receipt.path).is_ok() => {
-                Ok(RegistryRollback::Restored)
-            }
+            None if std::fs::remove_file(&receipt.path).is_ok() => Ok(RegistryRollback::Restored),
             None => Err(RegistryRollbackError::DeleteFailed),
         }
     })
 }
 
-fn remove_entry_if_matches(path: &Path, expected: &LeaderRegistryEntry) -> bool {
-    with_registry_lock(|_| {
-        let Ok(bytes) = std::fs::read(path) else {
-            return false;
-        };
-        let Ok(current) = serde_json::from_slice::<LeaderRegistryEntry>(&bytes) else {
-            return false;
-        };
-        current == *expected && std::fs::remove_file(path).is_ok()
-    })
-    .unwrap_or(false)
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RegistryPruneItem {
+    pub workspace: PathBuf,
+    pub team_key: String,
+    pub reason: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct RegistryPruneReport {
+    pub dry_run: bool,
+    pub candidates: Vec<RegistryPruneItem>,
+    pub removed: Vec<RegistryPruneItem>,
+    pub kept: Vec<RegistryPruneItem>,
+    pub skipped: Vec<RegistryPruneItem>,
+    pub errors: Vec<RegistryPruneItem>,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+enum PruneAttempt {
+    Removed,
+    Skipped(&'static str),
+    Error,
+}
+
+fn prune_item(entry: &LeaderRegistryEntry, reason: impl Into<String>) -> RegistryPruneItem {
+    RegistryPruneItem {
+        workspace: entry.workspace.clone(),
+        team_key: entry.team_key.clone(),
+        reason: reason.into(),
+    }
+}
+
+fn prune_reason_from_state(entry: &LeaderRegistryEntry, state: &Value) -> Option<&'static str> {
+    let (status, reason) = classify_loaded(entry, state);
+    if status != "STALE" {
+        return None;
+    }
+    match reason.as_deref() {
+        Some("team_key_not_found") => Some("team_key_not_found"),
+        Some("team_not_alive") => Some("team_not_alive"),
+        _ => None,
+    }
+}
+
+fn prune_reason(
+    entry: &LeaderRegistryEntry,
+    status: &str,
+    reason: Option<&str>,
+) -> Option<&'static str> {
+    if status != "STALE" || !crate::state::persist::runtime_state_path(&entry.workspace).is_file() {
+        // A missing state file is unavailable rather than proof that the
+        // workspace was retired. Only an existing, readable canonical state
+        // can authorize the team-key cleanup below.
+        return None;
+    }
+    match reason {
+        Some("team_key_not_found") => Some("team_key_not_found"),
+        Some("team_not_alive") => Some("team_not_alive"),
+        _ => None,
+    }
+}
+
+fn prune_entry_if_current(
+    path: &Path,
+    expected: &LeaderRegistryEntry,
+    snapshot: &[u8],
+) -> PruneAttempt {
+    let result = crate::state::persist::with_runtime_state_lock_without_migrations(
+        &expected.workspace,
+        |state| {
+            let Some(state) = state.as_ref() else {
+                return PruneAttempt::Skipped("canonical_state_unavailable");
+            };
+            // Lock ordering is canonical state -> host registry. The state
+            // remains unchanged while the exact registry bytes are checked.
+            with_registry_lock(|_| {
+                let Ok(bytes) = std::fs::read(path) else {
+                    return PruneAttempt::Skipped("registry_entry_missing");
+                };
+                if bytes != snapshot {
+                    return PruneAttempt::Skipped("registry_entry_changed");
+                }
+                let Ok(current) = serde_json::from_slice::<LeaderRegistryEntry>(&bytes) else {
+                    return PruneAttempt::Skipped("registry_entry_changed");
+                };
+                if current != *expected {
+                    return PruneAttempt::Skipped("registry_entry_changed");
+                }
+                if prune_reason_from_state(&current, state).is_none() {
+                    return PruneAttempt::Skipped("canonical_state_changed");
+                }
+                if std::fs::remove_file(path).is_ok() {
+                    PruneAttempt::Removed
+                } else {
+                    PruneAttempt::Error
+                }
+            })
+            .unwrap_or(PruneAttempt::Skipped("registry_lock_unavailable"))
+        },
+    );
+    result.unwrap_or(PruneAttempt::Skipped("canonical_state_unavailable"))
 }
 
 fn replace_entry_bytes_locked(path: &Path, bytes: &[u8]) -> bool {
-    let tmp = path.with_extension(format!(
-        "rollback-{}-{}",
-        std::process::id(),
-        rand_suffix()
-    ));
+    let tmp = path.with_extension(format!("rollback-{}-{}", std::process::id(), rand_suffix()));
     if std::fs::write(&tmp, bytes).is_err() {
         let _ = std::fs::remove_file(&tmp);
         return false;
@@ -497,7 +581,7 @@ pub fn unregister_entry(workspace: &Path, team_key: &str) -> Option<PathBuf> {
 /// registry is a derived discovery index and unreadable files are the
 /// "STALE / UNREADABLE" dirty class rather than an error.
 #[must_use]
-fn read_all_entries() -> Vec<(PathBuf, LeaderRegistryEntry)> {
+fn read_all_entries_with_bytes() -> Vec<(PathBuf, LeaderRegistryEntry, Vec<u8>)> {
     let Some(dir) = registry_dir() else {
         return Vec::new();
     };
@@ -517,18 +601,26 @@ fn read_all_entries() -> Vec<(PathBuf, LeaderRegistryEntry)> {
         if path.extension().and_then(|s| s.to_str()) != Some("json") {
             continue;
         }
-        let Ok(text) = std::fs::read_to_string(&path) else {
+        let Ok(bytes) = std::fs::read(&path) else {
             continue;
         };
-        let Ok(entry) = serde_json::from_str::<LeaderRegistryEntry>(&text) else {
+        let Ok(entry) = serde_json::from_slice::<LeaderRegistryEntry>(&bytes) else {
             continue;
         };
-        out.push((path, entry));
+        out.push((path, entry, bytes));
     }
     out.sort_by(|a, b| a.0.cmp(&b.0));
     out
 }
 
+#[must_use]
+fn read_all_entries() -> Vec<(PathBuf, LeaderRegistryEntry)> {
+    read_all_entries_with_bytes()
+        .into_iter()
+        .map(|(path, entry, _bytes)| (path, entry))
+        .collect()
+}
+
 /// Validate a registry entry against its canonical workspace state.
 /// Returns the wire status label — LIVE when canonical `leader_receiver`
 /// matches, STALE otherwise. This is the pruning gate for GC and the
@@ -538,11 +630,17 @@ pub fn classify(entry: &LeaderRegistryEntry) -> (&'static str, Option<String>) {
     let Ok(state) = crate::state::persist::load_runtime_state(&entry.workspace) else {
         return ("STALE", Some("workspace_no_state".to_string()));
     };
-    let team = state
-        .get("teams")
-        .and_then(|v| v.as_object())
-        .and_then(|teams| teams.get(&entry.team_key));
-    let team = match team {
+    classify_loaded(entry, &state)
+}
+
+fn classify_loaded(entry: &LeaderRegistryEntry, state: &Value) -> (&'static str, Option<String>) {
+    // A missing or malformed `teams` root is an unavailable/legacy state,
+    // not proof that this registry entry's team was retired. Keep it out of
+    // the prune candidate set unless a valid map was independently found.
+    let Some(teams) = state.get("teams").and_then(Value::as_object) else {
+        return ("STALE", Some("teams_invalid".to_string()));
+    };
+    let team = match teams.get(&entry.team_key) {
         Some(t) => t,
         None => return ("STALE", Some("team_key_not_found".to_string())),
     };
@@ -599,47 +697,57 @@ fn tmux_pane_live(socket: &str, pane_id: &str) -> bool {
     }
 }
 
-/// Read all entries, classify each, and prune terminal-stale entries
-/// (`workspace_no_state`, `team_key_not_found`). Live entries are never
-/// touched. Returns the surviving (LIVE + STALE-not-yet-pruned) entries
-/// classified for the `leaders` command output.
-///
-/// Design §14 step 6: "Successful scoped shutdown removes matching registry
-/// entry. Failed/degraded shutdown leaves entry STALE, not deleted."
-/// The pruning here is the GC arm — it only removes entries whose
-/// canonical workspace/team has no state at all, i.e. the target has been
-/// permanently removed. Leader-detached-but-team-alive stays STALE and
-/// visible so the operator can decide.
+/// Explicitly prune only entries whose readable canonical state proves that
+/// the team is gone or terminal. Dead panes, old epochs, unattached leaders,
+/// missing/unreadable state, and probe failures remain untouched.
 #[must_use]
-pub fn list_validated_with_gc() -> Vec<(LeaderRegistryEntry, &'static str, Option<String>)> {
-    let mut out = Vec::new();
-    for (path, entry) in read_all_entries() {
-        let (status, reason) = classify(&entry);
-        // Terminal stale reasons that indicate the entry can never be
-        // useful again: canonical workspace/team gone, or the leader
-        // binding has been fully released (no receiver at all). These
-        // are safe to prune; leader-attached-with-dead-pane and
-        // epoch-mismatch stay visible so the operator can see them.
-        if status == "STALE"
-            && reason.as_deref().is_some_and(|r| {
-                r == "workspace_no_state"
-                    || r == "team_key_not_found"
-                    || r == "leader_not_attached"
-                    || r == "team_not_alive"
-            })
-        {
-            let _ = remove_entry_if_matches(&path, &entry);
+pub fn prune_registry(dry_run: bool) -> RegistryPruneReport {
+    let mut report = RegistryPruneReport {
+        dry_run,
+        candidates: Vec::new(),
+        removed: Vec::new(),
+        kept: Vec::new(),
+        skipped: Vec::new(),
+        errors: Vec::new(),
+    };
+    let mut registry_lock_unavailable = false;
+    for (path, entry, snapshot) in read_all_entries_with_bytes() {
+        let (status, classified_reason) = classify(&entry);
+        let reason = prune_reason(&entry, status, classified_reason.as_deref());
+        let kept_reason = classified_reason.as_deref().unwrap_or("LIVE");
+        let Some(reason) = reason else {
+            report.kept.push(prune_item(&entry, kept_reason));
+            continue;
+        };
+        let candidate = prune_item(&entry, reason);
+        report.candidates.push(candidate.clone());
+        if dry_run {
+            continue;
+        }
+        if registry_lock_unavailable {
+            report
+                .skipped
+                .push(prune_item(&entry, "registry_lock_unavailable"));
             continue;
         }
-        out.push((entry, status, reason));
+        match prune_entry_if_current(&path, &entry, &snapshot) {
+            PruneAttempt::Removed => report.removed.push(candidate),
+            PruneAttempt::Skipped(reason) => {
+                if reason == "registry_lock_unavailable" {
+                    registry_lock_unavailable = true;
+                }
+                report.skipped.push(prune_item(&entry, reason));
+            }
+            PruneAttempt::Error => report.errors.push(prune_item(&entry, "remove_failed")),
+        }
     }
-    out
+    report
 }
 
-/// Same as `list_validated_with_gc` but preserves all entries. `send
-/// --to-leader` needs to see stale entries so it can refuse with
+/// Read all entries and classify each without mutating the derived index.
+/// `send --to-leader` needs to see stale entries so it can refuse with
 /// `registry_stale` (and never silently fall through to
-/// `leader_name_not_found` just because GC ran first).
+/// `leader_name_not_found` just because a listing ran first).
 #[must_use]
 pub fn list_validated_no_gc() -> Vec<(LeaderRegistryEntry, &'static str, Option<String>)> {
     read_all_entries()
@@ -650,3 +758,126 @@ pub fn list_validated_no_gc() -> Vec<(LeaderRegistryEntry, &'static str, Option<
         })
         .collect()
 }
+
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::expect_used, clippy::panic, clippy::unwrap_used)]
+
+    use super::*;
+    use serde_json::json;
+    use serial_test::serial;
+    use std::sync::atomic::{AtomicU64, Ordering};
+
+    static TEST_SEQ: AtomicU64 = AtomicU64::new(0);
+
+    struct HomeGuard(Option<std::ffi::OsString>);
+
+    impl Drop for HomeGuard {
+        fn drop(&mut self) {
+            if let Some(home) = self.0.take() {
+                std::env::set_var("HOME", home);
+            } else {
+                std::env::remove_var("HOME");
+            }
+        }
+    }
+
+    fn test_home(label: &str) -> (HomeGuard, PathBuf, PathBuf) {
+        let n = TEST_SEQ.fetch_add(1, Ordering::Relaxed);
+        let home =
+            std::env::temp_dir().join(format!("ta-registry-{label}-{}-{n}", std::process::id()));
+        let workspace = home.join("workspace");
+        std::fs::create_dir_all(&workspace).expect("create workspace");
+        let previous = std::env::var_os("HOME");
+        std::env::set_var("HOME", &home);
+        (HomeGuard(previous), home, workspace)
+    }
+
+    fn write_state(workspace: &Path, state: Value) {
+        let path = crate::state::persist::runtime_state_path(workspace);
+        std::fs::create_dir_all(path.parent().expect("runtime parent")).expect("create runtime");
+        std::fs::write(
+            path,
+            serde_json::to_vec_pretty(&state).expect("serialize state"),
+        )
+        .expect("write state");
+    }
+
+    fn entry(workspace: &Path, team_key: &str) -> LeaderRegistryEntry {
+        build_entry(
+            workspace,
+            team_key,
+            "direct_tmux",
+            json!({"pane_id": "%fixture"}),
+            1,
+            "test",
+            "2026-09-16T00:00:00Z".to_string(),
+        )
+    }
+
+    #[test]
+    #[serial]
+    fn prune_removes_team_proven_terminal() {
+        let (_home_guard, _home, workspace) = test_home("terminal");
+        write_state(
+            &workspace,
+            json!({"teams": {"retired": {"status": "stopped"}}}),
+        );
+        let registered = entry(&workspace, "retired");
+        let path = write_entry_best_effort(&registered).expect("register terminal team");
+
+        let report = prune_registry(false);
+        assert_eq!(report.candidates.len(), 1);
+        assert_eq!(report.removed.len(), 1);
+        assert!(report.skipped.is_empty());
+        assert!(!path.exists(), "terminal registry entry must be removed");
+    }
+
+    #[test]
+    #[serial]
+    fn prune_removes_missing_key_only_from_valid_teams_map() {
+        let (_home_guard, _home, workspace) = test_home("missing-key");
+        write_state(&workspace, json!({"teams": {"other": {"status": "alive"}}}));
+        let registered = entry(&workspace, "gone");
+        let path = write_entry_best_effort(&registered).expect("register missing team");
+
+        let report = prune_registry(false);
+        assert_eq!(report.removed.len(), 1);
+        assert!(
+            !path.exists(),
+            "missing key in valid teams map is removable"
+        );
+    }
+
+    #[test]
+    #[serial]
+    fn prune_keeps_null_nonobject_and_legacy_teams_shapes() {
+        for (label, state) in [
+            ("null", json!({"teams": null})),
+            ("array", json!({"teams": []})),
+            ("string", json!({"teams": "legacy"})),
+            (
+                "single",
+                json!({"team_key": "retired", "status": "stopped"}),
+            ),
+        ] {
+            let (_home_guard, _home, workspace) = test_home(label);
+            write_state(&workspace, state);
+            let registered = entry(&workspace, "retired");
+            let path = write_entry_best_effort(&registered).expect("register malformed state");
+
+            let report = prune_registry(false);
+            assert!(
+                report.candidates.is_empty(),
+                "malformed shape became candidate: {label}"
+            );
+            assert_eq!(
+                report.kept.len(),
+                1,
+                "malformed shape must be retained: {label}"
+            );
+            assert_eq!(report.kept[0].reason, "teams_invalid");
+            assert!(path.exists(), "malformed state entry must remain: {label}");
+        }
+    }
+}

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

@@ -1706,12 +1706,35 @@ pub(crate) fn load_runtime_state_without_migrations(workspace: &Path) -> Result<
     Ok(state)
 }
 
+/// Run a read-only callback while holding the canonical `state-save` lock.
+/// Unlike `load_runtime_state`, this helper performs no migration, cache
+/// update, or write. A missing state file is represented as `None` so callers
+/// can conservatively retain derived indexes during workspace unavailability.
+pub(crate) fn with_runtime_state_lock_without_migrations<T>(
+    workspace: &Path,
+    callback: impl FnOnce(Option<Value>) -> T,
+) -> Result<T, StateError> {
+    let path = runtime_state_path(workspace);
+    if !path.exists() {
+        return Ok(callback(None));
+    }
+    let _lock = RuntimeLock::acquire(workspace, "state-save", 2.0)?;
+    let state = match std::fs::read_to_string(&path) {
+        Ok(text) => Some(serde_json::from_str::<Value>(&text)?),
+        Err(error) if error.kind() == io::ErrorKind::NotFound => None,
+        Err(error) => return Err(error.into()),
+    };
+    Ok(callback(state))
+}
+
 pub(crate) fn save_runtime_state_without_migrations(
     workspace: &Path,
     state: &Value,
 ) -> Result<(), StateError> {
     let path = runtime_state_path(workspace);
-    let _lock = RuntimeLock::acquire(workspace, "state-save-raw", 2.0)?;
+    // Raw writers share the canonical lock so readers/pruners cannot race
+    // a restore write through a parallel lock namespace.
+    let _lock = RuntimeLock::acquire(workspace, "state-save", 2.0)?;
     if let Some(parent) = path.parent() {
         std::fs::create_dir_all(parent)?;
     }
@@ -3546,4 +3569,30 @@ mod tests {
             2,
         );
     }
+
+    #[test]
+    fn state_save_lock_serializes_raw_writer_and_prune_reader() {
+        let ws = temp_ws();
+        save_runtime_state(&ws, &json!({"teams": {"fresh": {}}})).unwrap();
+        let lock = RuntimeLock::acquire(&ws, "state-save", 2.0).unwrap();
+
+        let writer_ws = ws.clone();
+        let writer = std::thread::spawn(move || {
+            save_runtime_state_without_migrations(&writer_ws, &json!({"teams": {"fresh": {}}}))
+        });
+        std::thread::sleep(Duration::from_millis(100));
+        assert!(!writer.is_finished(), "raw writer must share state-save lock");
+        drop(lock);
+        writer.join().unwrap().unwrap();
+
+        let lock = RuntimeLock::acquire(&ws, "state-save", 2.0).unwrap();
+        let reader_ws = ws.clone();
+        let reader = std::thread::spawn(move || {
+            with_runtime_state_lock_without_migrations(&reader_ws, |state| state.is_some())
+        });
+        std::thread::sleep(Duration::from_millis(100));
+        assert!(!reader.is_finished(), "prune reader must use state-save lock");
+        drop(lock);
+        assert!(reader.join().unwrap().unwrap());
+    }
 }

package/package.json

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