@team-agent/installer 0.5.28 → 0.5.29

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

@@ -0,0 +1,222 @@
+//! C1 command registry: one catalog for help visibility, known-command gates,
+//! suggestion candidates, and command-tier governance.
+
+#![allow(dead_code)]
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub(crate) enum CommandTier {
+    Core,
+    Guided,
+    Secondary,
+    DevInternal,
+    CompatHidden,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub(crate) enum CommandCategory {
+    Start,
+    Daily,
+    TeamLifecycle,
+    WorkerLifecycle,
+    GuidedRecovery,
+    Setup,
+    Observe,
+    Dev,
+    Compat,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub(crate) enum CommandKind {
+    Dispatch(DispatchKind),
+    LeaderPassthrough { provider: &'static str },
+    SpecOnlyAlias { alias_of: &'static str },
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub(crate) enum TokenUsage {
+    No,
+    Yes,
+    Conditional,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub(crate) enum DispatchKind {
+    Init,
+    QuickStart,
+    Compile,
+    Send,
+    FallbackSendLeader,
+    FallbackReportResult,
+    AllowPeerTalk,
+    Status,
+    Stop,
+    Shutdown,
+    Restart,
+    RestartAgent,
+    StartAgent,
+    StopAgent,
+    ResetAgent,
+    AddAgent,
+    ForkAgent,
+    RemoveAgent,
+    StuckList,
+    StuckCancel,
+    AcknowledgeIdle,
+    Takeover,
+    ClaimLeader,
+    AttachLeader,
+    AttachAppServerLeader,
+    Identity,
+    Approvals,
+    Inbox,
+    Doctor,
+    Watch,
+    Sessions,
+    Leaders,
+    Validate,
+    InstallSkill,
+    Profile,
+    ValidateResult,
+    Collect,
+    Settle,
+    RepairState,
+    Diagnose,
+    Preflight,
+    WaitReady,
+    E2e,
+    Peek,
+    Coordinator,
+}
+
+pub(crate) const ALL_DISPATCH_KINDS: &[DispatchKind] = &[
+    DispatchKind::Init,
+    DispatchKind::QuickStart,
+    DispatchKind::Compile,
+    DispatchKind::Send,
+    DispatchKind::FallbackSendLeader,
+    DispatchKind::FallbackReportResult,
+    DispatchKind::AllowPeerTalk,
+    DispatchKind::Status,
+    DispatchKind::Stop,
+    DispatchKind::Shutdown,
+    DispatchKind::Restart,
+    DispatchKind::RestartAgent,
+    DispatchKind::StartAgent,
+    DispatchKind::StopAgent,
+    DispatchKind::ResetAgent,
+    DispatchKind::AddAgent,
+    DispatchKind::ForkAgent,
+    DispatchKind::RemoveAgent,
+    DispatchKind::StuckList,
+    DispatchKind::StuckCancel,
+    DispatchKind::AcknowledgeIdle,
+    DispatchKind::Takeover,
+    DispatchKind::ClaimLeader,
+    DispatchKind::AttachLeader,
+    DispatchKind::AttachAppServerLeader,
+    DispatchKind::Identity,
+    DispatchKind::Approvals,
+    DispatchKind::Inbox,
+    DispatchKind::Doctor,
+    DispatchKind::Watch,
+    DispatchKind::Sessions,
+    DispatchKind::Leaders,
+    DispatchKind::Validate,
+    DispatchKind::InstallSkill,
+    DispatchKind::Profile,
+    DispatchKind::ValidateResult,
+    DispatchKind::Collect,
+    DispatchKind::Settle,
+    DispatchKind::RepairState,
+    DispatchKind::Diagnose,
+    DispatchKind::Preflight,
+    DispatchKind::WaitReady,
+    DispatchKind::E2e,
+    DispatchKind::Peek,
+    DispatchKind::Coordinator,
+];
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub(crate) struct GovernanceNote {
+    pub(crate) decision: &'static str,
+    pub(crate) reason: &'static str,
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub(crate) struct CommandSpec {
+    pub(crate) name: &'static str,
+    pub(crate) tier: CommandTier,
+    pub(crate) category: CommandCategory,
+    pub(crate) kind: CommandKind,
+    pub(crate) summary: &'static str,
+    pub(crate) usage: &'static str,
+    pub(crate) default_help: bool,
+    pub(crate) command_help: bool,
+    pub(crate) suggestion_index: bool,
+    pub(crate) token_usage: TokenUsage,
+    pub(crate) alias_of: Option<&'static str>,
+    pub(crate) sunset: Option<&'static str>,
+    pub(crate) action: Option<&'static str>,
+    pub(crate) governance: Option<GovernanceNote>,
+}
+
+#[rustfmt::skip]
+pub(crate) const COMMAND_SPECS: &[CommandSpec] = &[
+    CommandSpec { name: "quick-start", tier: CommandTier::Core, category: CommandCategory::Start, kind: CommandKind::Dispatch(DispatchKind::QuickStart), summary: "start or attach a team from TEAM.md", usage: "usage: team-agent quick-start [TEAMDIR] [--workspace WORKSPACE] [--name NAME] [--team-id TEAM|--team TEAM] [--yes] [--no-display] [--backend tmux|conpty] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, alias_of: None, sunset: None, action: None, governance: None },
+    CommandSpec { name: "send", tier: CommandTier::Core, category: CommandCategory::Daily, kind: CommandKind::Dispatch(DispatchKind::Send), summary: "send a message/task", usage: "usage: team-agent send TARGET MESSAGE... [--workspace WORKSPACE] [--team TEAM] [--targets AGENTS] [--to-name NAME] [--pane PANE] [--task TASK] [--sender SENDER] [--watch-result] [--requires-ack|--no-ack] [--no-wait] [--timeout SECONDS] [--confirm-human] [--message-id ID] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, alias_of: None, sunset: None, action: None, governance: None },
+    CommandSpec { name: "status", tier: CommandTier::Core, category: CommandCategory::Daily, kind: CommandKind::Dispatch(DispatchKind::Status), summary: "show current team status", usage: "usage: team-agent status [AGENT] [--workspace WORKSPACE] [--team TEAM] [--summary|--json] [--detail]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
+    CommandSpec { name: "collect", tier: CommandTier::Core, category: CommandCategory::Daily, kind: CommandKind::Dispatch(DispatchKind::Collect), summary: "collect reported results", usage: "usage: team-agent collect [--workspace WORKSPACE] [--team TEAM] [--result-file FILE] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
+    CommandSpec { name: "restart", tier: CommandTier::Core, category: CommandCategory::TeamLifecycle, kind: CommandKind::Dispatch(DispatchKind::Restart), summary: "restart the selected team", usage: "usage: team-agent restart [WORKSPACE] [--team TEAM] [--allow-fresh] [--session-converge-deadline SECONDS] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, alias_of: None, sunset: None, action: None, governance: None },
+    CommandSpec { name: "shutdown", tier: CommandTier::Core, category: CommandCategory::TeamLifecycle, kind: CommandKind::Dispatch(DispatchKind::Shutdown), summary: "stop the selected team", usage: "usage: team-agent shutdown [--workspace WORKSPACE] [--team TEAM] [--keep-logs] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
+    CommandSpec { name: "add-agent", tier: CommandTier::Core, category: CommandCategory::WorkerLifecycle, kind: CommandKind::Dispatch(DispatchKind::AddAgent), summary: "add a worker", usage: "usage: team-agent add-agent AGENT --role-file FILE [--workspace WORKSPACE] [--team TEAM] [--no-display] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, alias_of: None, sunset: None, action: None, governance: None },
+    CommandSpec { name: "start-agent", tier: CommandTier::Core, category: CommandCategory::WorkerLifecycle, kind: CommandKind::Dispatch(DispatchKind::StartAgent), summary: "start an existing worker", usage: "usage: team-agent start-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--force] [--allow-fresh] [--no-display] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, alias_of: None, sunset: None, action: None, governance: None },
+    CommandSpec { name: "stop-agent", tier: CommandTier::Core, category: CommandCategory::WorkerLifecycle, kind: CommandKind::Dispatch(DispatchKind::StopAgent), summary: "stop a worker", usage: "usage: team-agent stop-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
+    CommandSpec { name: "reset-agent", tier: CommandTier::Core, category: CommandCategory::WorkerLifecycle, kind: CommandKind::Dispatch(DispatchKind::ResetAgent), summary: "reset a worker session", usage: "usage: team-agent reset-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--discard-session] [--no-display] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, alias_of: None, sunset: None, action: None, governance: None },
+    CommandSpec { name: "diagnose", tier: CommandTier::Core, category: CommandCategory::Observe, kind: CommandKind::Dispatch(DispatchKind::Diagnose), summary: "inspect this workspace runtime and suggested repairs", usage: "usage: team-agent diagnose [--workspace WORKSPACE] [--team TEAM] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
+    CommandSpec { name: "claim-leader", tier: CommandTier::Guided, category: CommandCategory::GuidedRecovery, kind: CommandKind::Dispatch(DispatchKind::ClaimLeader), summary: "bind this pane when diagnose reports rebind_required", usage: "usage: team-agent claim-leader [--workspace WORKSPACE] [--team TEAM] [--confirm] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
+    CommandSpec { name: "takeover", tier: CommandTier::Guided, category: CommandCategory::GuidedRecovery, kind: CommandKind::Dispatch(DispatchKind::Takeover), summary: "replace a live leader binding with explicit consent", usage: "usage: team-agent takeover [--workspace WORKSPACE] [--team TEAM] [--confirm] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
+    CommandSpec { name: "attach-leader", tier: CommandTier::Guided, category: CommandCategory::GuidedRecovery, kind: CommandKind::Dispatch(DispatchKind::AttachLeader), summary: "bind an external leader pane", usage: "usage: team-agent attach-leader [--workspace WORKSPACE] [--team TEAM] [--pane PANE] [--provider PROVIDER] [--confirm] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
+
+    CommandSpec { name: "codex", tier: CommandTier::Core, category: CommandCategory::Start, kind: CommandKind::LeaderPassthrough { provider: "codex" }, summary: "launch a Codex leader", usage: "usage: team-agent codex [provider args...]", default_help: false, command_help: true, suggestion_index: true, token_usage: TokenUsage::Yes, alias_of: None, sunset: None, action: None, governance: None },
+    CommandSpec { name: "claude", tier: CommandTier::Core, category: CommandCategory::Start, kind: CommandKind::LeaderPassthrough { provider: "claude" }, summary: "launch a Claude leader", usage: "usage: team-agent claude [provider args...]", default_help: false, command_help: true, suggestion_index: true, token_usage: TokenUsage::Yes, alias_of: None, sunset: None, action: None, governance: None },
+    CommandSpec { name: "copilot", tier: CommandTier::Core, category: CommandCategory::Start, kind: CommandKind::LeaderPassthrough { provider: "copilot" }, summary: "launch a Copilot leader", usage: "usage: team-agent copilot [provider args...]", default_help: false, command_help: true, suggestion_index: true, token_usage: TokenUsage::Yes, alias_of: None, sunset: None, action: None, governance: None },
+
+    CommandSpec { name: "init", tier: CommandTier::CompatHidden, category: CommandCategory::Compat, kind: CommandKind::Dispatch(DispatchKind::Init), summary: "legacy bootstrap command", usage: "usage: team-agent init [--workspace WORKSPACE] [--force] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: Some("quick-start"), sunset: Some("C2"), action: Some("use `team-agent quick-start`"), governance: None },
+    CommandSpec { name: "start", tier: CommandTier::CompatHidden, category: CommandCategory::Compat, kind: CommandKind::SpecOnlyAlias { alias_of: "quick-start" }, summary: "legacy start alias", usage: "usage: team-agent start [TEAMDIR] [--yes] [--fresh] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::Conditional, alias_of: Some("quick-start"), sunset: Some("C2"), action: Some("use `team-agent quick-start` or `team-agent restart`"), governance: None },
+    CommandSpec { name: "stop", tier: CommandTier::CompatHidden, category: CommandCategory::Compat, kind: CommandKind::Dispatch(DispatchKind::Stop), summary: "legacy shutdown alias", usage: "usage: team-agent stop [--workspace WORKSPACE] [--team TEAM] [--keep-logs] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: Some("shutdown"), sunset: Some("C2"), action: Some("use `team-agent shutdown`"), governance: None },
+    CommandSpec { name: "restart-agent", tier: CommandTier::CompatHidden, category: CommandCategory::Compat, kind: CommandKind::Dispatch(DispatchKind::RestartAgent), summary: "legacy reset-agent alias", usage: "usage: team-agent restart-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--discard-session] [--no-display] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::Conditional, alias_of: Some("reset-agent"), sunset: Some("C2"), action: Some("use `team-agent reset-agent`"), governance: None },
+    CommandSpec { name: "fallback-send-leader", tier: CommandTier::CompatHidden, category: CommandCategory::Compat, kind: CommandKind::Dispatch(DispatchKind::FallbackSendLeader), summary: "legacy leader send fallback", usage: "usage: team-agent fallback-send-leader --workspace WORKSPACE --team TEAM --sender AGENT --message-id ID --content TEXT --primary-error ERROR [--task TASK] [--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 send` and `team-agent diagnose`"), governance: None },
+    CommandSpec { name: "fallback-report-result", tier: CommandTier::CompatHidden, category: CommandCategory::Compat, kind: CommandKind::Dispatch(DispatchKind::FallbackReportResult), summary: "legacy report_result fallback", usage: "usage: team-agent fallback-report-result --workspace WORKSPACE --team TEAM --agent-id AGENT --task-id TASK --result-json JSON --primary-error ERROR [--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 collect` or MCP `report_result`"), governance: None },
+    CommandSpec { name: "settle", tier: CommandTier::CompatHidden, category: CommandCategory::Compat, kind: CommandKind::Dispatch(DispatchKind::Settle), summary: "legacy settle helper", usage: "usage: team-agent settle [--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 collect`"), governance: None },
+    CommandSpec { name: "validate-result", tier: CommandTier::CompatHidden, category: CommandCategory::Compat, kind: CommandKind::Dispatch(DispatchKind::ValidateResult), summary: "legacy result validation helper", usage: "usage: team-agent validate-result [ENVELOPE] [--file FILE|--result JSON] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: Some("C2"), action: Some("use report_result validation through normal `team-agent collect` flow"), governance: None },
+    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: "repair-state", tier: CommandTier::Guided, category: CommandCategory::GuidedRecovery, kind: CommandKind::Dispatch(DispatchKind::RepairState), summary: "guided state repair helper", usage: "usage: team-agent repair-state --task TASK --status STATUS [SUMMARY] [--assignee AGENT] [--workspace WORKSPACE] [--team TEAM] [--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: "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: "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 },
+    CommandSpec { name: "fork-agent", tier: CommandTier::Secondary, category: CommandCategory::WorkerLifecycle, kind: CommandKind::Dispatch(DispatchKind::ForkAgent), summary: "fork a worker", usage: "usage: team-agent fork-agent SOURCE_AGENT --as AGENT [--label LABEL] [--workspace WORKSPACE] [--team TEAM] [--no-display] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::Conditional, alias_of: None, sunset: None, action: None, governance: None },
+    CommandSpec { name: "allow-peer-talk", tier: CommandTier::Secondary, category: CommandCategory::Setup, kind: CommandKind::Dispatch(DispatchKind::AllowPeerTalk), summary: "allow direct worker peer talk", usage: "usage: team-agent allow-peer-talk A B [--workspace WORKSPACE] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: Some(GovernanceNote { decision: "secondary", reason: "capability/config surface" }) },
+    CommandSpec { name: "approvals", tier: CommandTier::Secondary, category: CommandCategory::Observe, kind: CommandKind::Dispatch(DispatchKind::Approvals), summary: "inspect provider approval state", usage: "usage: team-agent approvals [AGENT] [--workspace WORKSPACE] [--team TEAM] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: Some(GovernanceNote { decision: "secondary", reason: "approval diagnostics" }) },
+    CommandSpec { name: "profile", tier: CommandTier::Secondary, category: CommandCategory::Setup, kind: CommandKind::Dispatch(DispatchKind::Profile), summary: "manage provider profiles", usage: "usage: team-agent profile COMMAND NAME [--workspace WORKSPACE] [--team TEAM] [--auth-mode MODE] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: Some(GovernanceNote { decision: "secondary", reason: "provider/profile setup" }) },
+    CommandSpec { name: "install-skill", tier: CommandTier::Secondary, category: CommandCategory::Setup, kind: CommandKind::Dispatch(DispatchKind::InstallSkill), summary: "install or uninstall Team Agent skills", usage: "usage: team-agent install-skill (--source DIR | --uninstall) [--target codex|claude|copilot|all] [--dest DIR] [--dry-run] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: Some(GovernanceNote { decision: "secondary", reason: "capability setup" }) },
+    CommandSpec { name: "inbox", tier: CommandTier::Secondary, category: CommandCategory::Observe, kind: CommandKind::Dispatch(DispatchKind::Inbox), summary: "inspect queued messages", usage: "usage: team-agent inbox AGENT [--workspace WORKSPACE] [--team TEAM] [--limit N] [--since CURSOR] [--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: "identity", tier: CommandTier::DevInternal, category: CommandCategory::Dev, kind: CommandKind::Dispatch(DispatchKind::Identity), summary: "inspect identity metadata", usage: "usage: team-agent identity [--workspace WORKSPACE] [--team TEAM] [--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: "watch", tier: CommandTier::DevInternal, category: CommandCategory::Dev, kind: CommandKind::Dispatch(DispatchKind::Watch), summary: "watch event logs", usage: "usage: team-agent watch [--workspace WORKSPACE] [--team TEAM]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
+    CommandSpec { name: "sessions", tier: CommandTier::DevInternal, category: CommandCategory::Dev, kind: CommandKind::Dispatch(DispatchKind::Sessions), summary: "inspect session inventory", usage: "usage: team-agent sessions [--workspace WORKSPACE] [--team TEAM] [--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: "compile", tier: CommandTier::DevInternal, category: CommandCategory::Dev, kind: CommandKind::Dispatch(DispatchKind::Compile), summary: "compile a team spec", usage: "usage: team-agent compile --team TEAM [--out FILE] [--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: "validate", tier: CommandTier::DevInternal, category: CommandCategory::Dev, kind: CommandKind::Dispatch(DispatchKind::Validate), summary: "validate a team spec", usage: "usage: team-agent validate [SPEC] [--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: "preflight", tier: CommandTier::DevInternal, category: CommandCategory::Dev, kind: CommandKind::Dispatch(DispatchKind::Preflight), summary: "run preflight checks", usage: "usage: team-agent preflight [TEAMDIR] [--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: "wait-ready", tier: CommandTier::DevInternal, category: CommandCategory::Dev, kind: CommandKind::Dispatch(DispatchKind::WaitReady), summary: "wait for runtime readiness", usage: "usage: team-agent wait-ready [--workspace WORKSPACE] [--team TEAM] [--timeout SECONDS] [--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: "e2e", tier: CommandTier::DevInternal, category: CommandCategory::Dev, kind: CommandKind::Dispatch(DispatchKind::E2e), summary: "run e2e harness", usage: "usage: team-agent e2e [--workspace WORKSPACE] [--providers LIST] [--real] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::Yes, alias_of: None, sunset: None, action: None, governance: None },
+    CommandSpec { name: "peek", tier: CommandTier::DevInternal, category: CommandCategory::Dev, kind: CommandKind::Dispatch(DispatchKind::Peek), summary: "capture low-level terminal output", usage: "usage: team-agent peek AGENT [--workspace WORKSPACE] [--tail N|--head N] [--search TEXT] [--allow-raw-screen] [--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: "coordinator", tier: CommandTier::DevInternal, category: CommandCategory::Dev, kind: CommandKind::Dispatch(DispatchKind::Coordinator), summary: "run the coordinator daemon", usage: "usage: team-agent coordinator [--workspace WORKSPACE] [--once] [--tick-interval SECONDS]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
+];
+
+pub(crate) fn command_spec(name: &str) -> Option<&'static CommandSpec> {
+    COMMAND_SPECS.iter().find(|spec| spec.name == name)
+}

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

@@ -32,6 +32,17 @@ pub fn agent_summary_counts(agents: &Value, health: &Value) -> SummaryCounts {
         return counts;
     };
     for (agent_id, agent) in agent_map {
+        if let Some(bucket) = stale_agent_bucket(agent) {
+            match bucket {
+                SummaryBucket::Stopped => counts.stopped += 1,
+                SummaryBucket::Unknown => counts.unknown += 1,
+                SummaryBucket::Running
+                | SummaryBucket::Busy
+                | SummaryBucket::Idle
+                | SummaryBucket::Failed => {}
+            }
+            continue;
+        }
         let raw = agent
             .get("status")
             .and_then(Value::as_str)
@@ -53,6 +64,21 @@ pub fn agent_summary_counts(agents: &Value, health: &Value) -> SummaryCounts {
     counts
 }
 
+fn stale_agent_bucket(agent: &Value) -> Option<SummaryBucket> {
+    if agent.get("stale").and_then(Value::as_bool) != Some(true) {
+        return None;
+    }
+    if agent
+        .get("stale_reason")
+        .and_then(Value::as_str)
+        .is_some_and(|reason| !reason.is_empty())
+    {
+        Some(SummaryBucket::Stopped)
+    } else {
+        Some(SummaryBucket::Unknown)
+    }
+}
+
 /// `_interaction_counts`(`commands.py:292-306`):遍历 agents 的 `interacted` 字段。
 pub fn interaction_counts(agents: &Value) -> InteractionCounts {
     let mut counts = InteractionCounts::default();
@@ -165,6 +191,9 @@ fn csv_agent_status(
     agent: &Value,
     health: Option<&serde_json::Map<String, Value>>,
 ) -> &'static str {
+    if stale_agent_bucket(agent).is_some() {
+        return "错误";
+    }
     let raw = agent
         .get("status")
         .and_then(Value::as_str)

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

@@ -34,12 +34,13 @@ use rusqlite::params;
         // backlog>0 才挂 down-hint(anti-nag)。auto-recovery 不做(user 已裁)。
         let coordinator_running = coordinator_status_running(&health);
         let undelivered_backlog = count_undelivered_backlog(&conn, owner_team_id)?;
+        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 runtime_block = build_runtime_status_block(
             coordinator_running,
             undelivered_backlog,
+            !tmux_present,
         );
-        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")
@@ -458,6 +459,9 @@ use rusqlite::params;
                             "stale_reason".to_string(),
                             Value::String(reason.to_string()),
                         );
+                        if !tmux_session_present {
+                            downgrade_stale_agent(&mut enriched);
+                        }
                     }
                     out.insert(agent_id.clone(), Value::Object(enriched));
                 }
@@ -469,6 +473,25 @@ use rusqlite::params;
         Value::Object(out)
     }
 
+    fn downgrade_stale_agent(agent: &mut Map<String, Value>) {
+        let raw = agent
+            .get("status")
+            .and_then(Value::as_str)
+            .unwrap_or("")
+            .to_ascii_lowercase();
+        if matches!(raw.as_str(), "running" | "busy" | "working" | "idle") {
+            agent.insert("status".to_string(), Value::String("stopped".to_string()));
+        }
+        let worker_state = agent
+            .get("worker_state")
+            .and_then(Value::as_str)
+            .unwrap_or("")
+            .to_ascii_uppercase();
+        if matches!(worker_state.as_str(), "RUNNING" | "BUSY" | "PROBABLY_IDLE") {
+            agent.insert("worker_state".to_string(), Value::String("DEAD".to_string()));
+        }
+    }
+
     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 =
@@ -1093,14 +1116,23 @@ use rusqlite::params;
     /// B-5 / 036b N38 — status 出口的 runtime 块:把 coordinator_health 与
     /// undelivered backlog 合体暴露。down-hint 只在【coordinator 不在跑 ∧ 有 backlog】
     /// 两条件同时满足才挂(anti-nag);健康状态下不挂提示。auto-recovery 不做。
-    fn build_runtime_status_block(coordinator_running: bool, undelivered: i64) -> Value {
+    fn build_runtime_status_block(
+        coordinator_running: bool,
+        undelivered: i64,
+        tmux_session_missing: bool,
+    ) -> Value {
         let mut runtime = serde_json::Map::new();
         runtime.insert(
             "coordinator".to_string(),
             json!({"ok": coordinator_running}),
         );
         runtime.insert("undelivered".to_string(), json!(undelivered));
-        if !coordinator_running && undelivered > 0 {
+        if tmux_session_missing {
+            runtime.insert(
+                "hint".to_string(),
+                json!("tmux session missing — run team-agent restart"),
+            );
+        } else if !coordinator_running && undelivered > 0 {
             runtime.insert(
                 "hint".to_string(),
                 json!(format!(

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

@@ -440,21 +440,17 @@ pub fn claim_leader(
         .unwrap_or_default();
     let raw_state = crate::state::persist::load_runtime_state(workspace)?;
     let event_log = crate::event_log::EventLog::new(workspace);
-    // Phase 1d Batch 6: factory tmux channel helpers for grep-visibility.
-    // Tmux-only leader-claim path (caller pane enumeration).
-    let mut targets = crate::transport_factory::tmux_workspace_transport(workspace)
-        .list_targets()
-        .unwrap_or_default();
-    targets.extend(
-        crate::transport_factory::tmux_default_transport()
-            .list_targets()
-            .unwrap_or_default(),
-    );
-    let caller_pane_info = targets
+    let targets = claim_leader_targets(workspace, &raw_state);
+    let caller_candidate = targets
         .iter()
-        .find(|target| target.pane_id.as_str() == caller);
-    let caller_target =
-        caller_pane_info.and_then(|target| claim_target_from_pane_info(workspace, target));
+        .find(|target| target.info.pane_id.as_str() == caller);
+    let caller_pane_info = caller_candidate.map(|target| &target.info);
+    let caller_target = caller_candidate.and_then(|target| {
+        claim_target_from_pane_info(workspace, &target.info).map(|mut claim_target| {
+            claim_target.endpoint = target.endpoint.clone();
+            claim_target
+        })
+    });
     let env_team = std::env::var("TEAM_AGENT_TEAM_ID")
         .ok()
         .filter(|team| !team.is_empty());
@@ -489,7 +485,7 @@ pub fn claim_leader(
     } else {
         raw_state
     };
-    let liveness = AnyPaneLiveness::from_targets(&targets);
+    let liveness = AnyPaneLiveness::from_claim_targets(&targets);
     let result = claim_lease_no_incident_with_target(
         workspace,
         &mut state,
@@ -634,8 +630,23 @@ fn claim_lease_no_incident_with_target(
     let bound_endpoint_matches_caller = bound_endpoint_matches_current_process(state);
     if bound_pane_id.as_deref() == Some(caller_pane.as_str()) && bound_endpoint_matches_caller {
         let current_endpoint = crate::tmux_backend::socket_name_from_tmux_env();
+        let observed_endpoint = caller_target.and_then(|target| target.endpoint.as_deref());
+        let convergence_candidate = observed_endpoint.or(current_endpoint.as_deref());
+        let candidate_source = if observed_endpoint.is_some() {
+            Some("observed_target_endpoint")
+        } else if current_endpoint.is_some() {
+            Some("fallback_tmux_env")
+        } else {
+            None
+        };
         let (mut topology_convergence, converged) =
-            apply_endpoint_convergence(state, team_id, current_endpoint.as_deref(), pre_epoch);
+            apply_endpoint_convergence(
+                state,
+                team_id,
+                convergence_candidate,
+                candidate_source,
+                pre_epoch,
+            );
         if converged {
             write_claim_state(workspace, state, scoped_team, team)?;
             topology_convergence = verify_persisted_topology_convergence(
@@ -796,7 +807,8 @@ fn claim_lease_no_incident_with_target(
     }
     let next_epoch = OwnerEpoch(pre_epoch.0.saturating_add(1));
     let provider = caller_target.map_or_else(|| prior_provider(state), |target| target.provider);
-    let receiver = make_receiver(
+    let observed_endpoint = caller_target.and_then(|target| target.endpoint.clone());
+    let mut receiver = make_receiver(
         provider,
         &non_empty_caller_pane,
         &identity.leader_session_uuid,
@@ -804,10 +816,26 @@ fn claim_lease_no_incident_with_target(
         Discovery::ClaimLeader,
         caller_target.and_then(|target| target.pane_info.clone()),
     );
+    if let Some(endpoint) = observed_endpoint.as_ref() {
+        receiver.tmux_socket = Some(endpoint.clone());
+    }
     let owner = make_owner(provider, &non_empty_caller_pane, &identity, next_epoch);
     write_binding_to_state(state, &receiver, &owner)?;
+    let candidate_source = if observed_endpoint.is_some() {
+        Some("observed_target_endpoint")
+    } else if receiver.tmux_socket.is_some() {
+        Some("fallback_tmux_env")
+    } else {
+        None
+    };
     let (mut topology_convergence, converged) =
-        apply_endpoint_convergence(state, team_id, receiver.tmux_socket.as_deref(), next_epoch);
+        apply_endpoint_convergence(
+            state,
+            team_id,
+            receiver.tmux_socket.as_deref(),
+            candidate_source,
+            next_epoch,
+        );
     write_claim_state(workspace, state, scoped_team, team)?;
     if converged {
         topology_convergence = verify_persisted_topology_convergence(
@@ -884,13 +912,17 @@ fn apply_endpoint_convergence(
     state: &mut Value,
     team_id: &TeamKey,
     candidate_endpoint: Option<&str>,
+    candidate_source: Option<&'static str>,
     owner_epoch: OwnerEpoch,
 ) -> (Option<Value>, bool) {
-    let Some(candidate_endpoint) = candidate_endpoint
+    let explicit_candidate = candidate_endpoint
         .filter(|endpoint| !endpoint.is_empty())
-        .map(str::to_string)
-        .or_else(|| state_tmux_socket_candidate(state, team_id.as_str()))
-    else {
+        .map(str::to_string);
+    let (candidate_endpoint, candidate_source) = if let Some(endpoint) = explicit_candidate {
+        (endpoint, candidate_source.unwrap_or("candidate"))
+    } else if let Some(endpoint) = state_tmux_socket_candidate(state, team_id.as_str()) {
+        (endpoint, "fallback_state")
+    } else {
         return (None, false);
     };
     match crate::topology::endpoint_convergence_decision(
@@ -903,6 +935,7 @@ fn apply_endpoint_convergence(
             Some(json!({
                 "status": "unknown",
                 "new_tmux_endpoint": candidate_endpoint,
+                "candidate_source": candidate_source,
                 "owner_epoch": owner_epoch.0,
             })),
             false,
@@ -910,14 +943,17 @@ fn apply_endpoint_convergence(
         crate::topology::EndpointConvergenceDecision::RefuseLiveOldEndpoint {
             old_endpoint,
             new_endpoint,
+            reason,
         } => (
             Some(json!({
                 "status": "not_converged_old_endpoint_live",
                 "old_tmux_endpoint": old_endpoint,
                 "new_tmux_endpoint": new_endpoint,
+                "reason": reason,
+                "candidate_source": candidate_source,
                 "owner_epoch": owner_epoch.0,
                 "action": format!(
-                    "old tmux endpoint {old_endpoint} is still live; run team-agent diagnose --json and clean that endpoint before retrying restart"
+                    "old tmux endpoint {old_endpoint} still has this team's session or pane tuple; run team-agent diagnose --json before retrying restart"
                 ),
             })),
             false,
@@ -925,12 +961,14 @@ fn apply_endpoint_convergence(
         crate::topology::EndpointConvergenceDecision::Converge {
             old_endpoint,
             new_endpoint,
+            reason,
         } => {
             let metadata = json!({
                 "status": "converged",
                 "old_tmux_endpoint": old_endpoint,
                 "new_tmux_endpoint": new_endpoint,
-                "reason": "old_endpoint_dead",
+                "reason": reason,
+                "candidate_source": candidate_source,
                 "owner_epoch": owner_epoch.0,
             });
             write_endpoint_fields(state, team_id.as_str(), &new_endpoint);
@@ -1175,6 +1213,56 @@ struct LeaderClaimTarget {
     leader_session_uuid: Option<crate::model::ids::LeaderSessionUuid>,
     team_id: Option<String>,
     pane_info: Option<PaneInfo>,
+    endpoint: Option<String>,
+}
+
+#[derive(Clone)]
+struct ClaimLeaderTargetCandidate {
+    info: PaneInfo,
+    endpoint: Option<String>,
+}
+
+fn claim_leader_targets(workspace: &Path, state: &Value) -> Vec<ClaimLeaderTargetCandidate> {
+    let mut targets = Vec::new();
+    for endpoint in state_recorded_tmux_endpoints(state) {
+        let backend = tmux_backend_for_endpoint(&endpoint);
+        let resolved_endpoint = backend.tmux_endpoint();
+        targets.extend(
+            backend
+                .list_targets()
+                .unwrap_or_default()
+                .into_iter()
+                .map(|info| ClaimLeaderTargetCandidate {
+                    info,
+                    endpoint: resolved_endpoint.clone(),
+                }),
+        );
+    }
+    let workspace_backend = crate::transport_factory::tmux_workspace_transport(workspace);
+    let workspace_endpoint = workspace_backend.tmux_endpoint();
+    targets.extend(
+        workspace_backend
+            .list_targets()
+            .unwrap_or_default()
+            .into_iter()
+            .map(|info| ClaimLeaderTargetCandidate {
+                info,
+                endpoint: workspace_endpoint.clone(),
+            }),
+    );
+    let default_backend = crate::transport_factory::tmux_default_transport();
+    let default_endpoint = default_backend.tmux_endpoint();
+    targets.extend(
+        default_backend
+            .list_targets()
+            .unwrap_or_default()
+            .into_iter()
+            .map(|info| ClaimLeaderTargetCandidate {
+                info,
+                endpoint: default_endpoint.clone(),
+            }),
+    );
+    targets
 }
 
 fn claim_target_from_pane_info(workspace: &Path, target: &PaneInfo) -> Option<LeaderClaimTarget> {
@@ -1191,6 +1279,7 @@ fn claim_target_from_pane_info(workspace: &Path, target: &PaneInfo) -> Option<Le
         leader_session_uuid: target_leader_session_uuid(target),
         team_id: target.leader_env.get("TEAM_AGENT_TEAM_ID").filter(|raw| !raw.is_empty()).cloned(),
         pane_info: Some(target.clone()),
+        endpoint: None,
     })
 }
 
@@ -1290,11 +1379,11 @@ struct AnyPaneLiveness {
 }
 
 impl AnyPaneLiveness {
-    fn from_targets(targets: &[PaneInfo]) -> Self {
+    fn from_claim_targets(targets: &[ClaimLeaderTargetCandidate]) -> Self {
         Self {
             live_panes: targets
                 .iter()
-                .map(|target| target.pane_id.as_str().to_string())
+                .map(|target| target.info.pane_id.as_str().to_string())
                 .collect(),
         }
     }
@@ -1677,10 +1766,16 @@ fn save_claim_team_scoped_state(workspace: &Path, state: &Value, target_key: &st
         .map(|_| crate::state::projection::team_state_key(&existing));
     let existing_active_key = existing.get("active_team_key").and_then(Value::as_str);
     let updates_active_team = existing_active_key == Some(target_key);
+    let writes_endpoint_convergence = state
+        .get("topology_convergence")
+        .and_then(|marker| marker.get("status"))
+        .and_then(Value::as_str)
+        == Some("converged");
     let mut merged = if existing_primary_key
         .as_deref()
         .is_none_or(|key| key == target_key)
         || updates_active_team
+        || writes_endpoint_convergence
     {
         value_object(state)
     } else {
@@ -1697,7 +1792,12 @@ fn save_claim_team_scoped_state(workspace: &Path, state: &Value, target_key: &st
     // / coordinator tick / promote sibling. `had_existing_teams` /
     // primary/active key computations are retained as dead writes only
     // via _ binding — they no longer gate any owner promote.
-    let _ = (had_existing_teams, existing_primary_key, existing_active_key);
+    let _ = (
+        had_existing_teams,
+        existing_primary_key,
+        existing_active_key,
+        writes_endpoint_convergence,
+    );
     merged.insert("teams".to_string(), Value::Object(teams));
     crate::state::persist::save_runtime_state(workspace, &Value::Object(merged))?;
     Ok(())