@team-agent/installer 0.5.119 → 0.5.121

package/Cargo.lock

@@ -727,7 +727,7 @@ dependencies = [
 
 [[package]]
 name = "team-agent"
-version = "0.5.119"
+version = "0.5.121"
 dependencies = [
  "anyhow",
  "chrono",

package/Cargo.toml

@@ -11,7 +11,7 @@ exclude = ["crates/team-agent-contract"]
 
 [workspace.package]
 edition = "2021"
-version = "0.5.119"
+version = "0.5.121"
 license = "AGPL-3.0"
 rust-version = "1.95"
 

package/README.md

@@ -20,7 +20,7 @@ Then:
 - Teammates message each other directly (frontend asks backend for the API schema — no need to go through you)
 - You only talk to the lead; the lead reports progress and only escalates when there's a real decision
 
-No config files. No new UI to learn. If you can chat with Claude, you can run a team.
+No new dashboard or orchestration language: the Leader prepares team files from your approved plan. If you can chat with Claude, you can run a team.
 
 ## Install
 
@@ -36,6 +36,51 @@ team-agent claude
 
 Two steps. Everything else happens in the conversation.
 
+## Everyday CLI: start, stop, restart
+
+Check the selected binary with `team-agent start --help` and `team-agent team --help`. If these are missing, obtain an authorized supporting build; a version string alone is not a feature guarantee. Lifecycle commands run in the authorized native **Leader's tool context**, not an ordinary worker's pane.
+
+The Leader prepares `TEAM.md` and `agents/*.md` once, recording the user's provider and boolean permission-bypass choices. For example:
+
+```text
+.team/current/
+  TEAM.md
+  agents/reviewer.md
+```
+
+With that complete source, operate on an explicit workspace/team:
+
+```sh
+team-agent start --from .team/current --workspace . --team project-team
+team-agent start --workspace . --team project-team
+team-agent send reviewer "Review the change and report the main risk" --workspace . --team project-team
+team-agent inbox leader --workspace . --team project-team -n 3
+team-agent stop reviewer --workspace . --team project-team
+team-agent start reviewer --workspace . --team project-team
+team-agent restart reviewer --workspace . --team project-team
+team-agent stop --workspace . --team project-team --json
+team-agent start --workspace . --team project-team
+team-agent team restart --workspace . --team project-team --json
+```
+
+| Command | Intent and boundary |
+|---|---|
+| `start` | Create once from complete configuration; later activate the selected non-paused roster. Verified live/drift-free instances stay unchanged |
+| `start AGENT` | Wake a stopped seat, prove a live no-op, or add a RoleOnly seat from its complete file. A new ID needs explicit provider/bypass decisions |
+| `stop [AGENT]` | Stop one agent or the selected team, retaining saved associations; team stop reports owned residuals |
+| `restart AGENT` | Preflight, confirmed stop, then start that agent; no implicit role patches or reset |
+| `team restart` | Deliberate team restart; preserve explicitly stopped/paused seats |
+| `team status` / `status` | Read the concise node projection; diagnose with `doctor` |
+| `agent add/remove/reset/clone/fork` | Explicit operations with their original confirmation/capability gates; reset requires `--discard-session`, fork requires `--as NEW_ID` |
+
+New agent/team restart defaults to `--session auto`: resume when proven, otherwise only an existing legal fresh fallback. **Auto is not a promise of preserved memory.** For strict recovery use `team-agent team restart --session preserve --workspace . --team project-team`; known unavailable continuation refuses before stopping. Unknown or partial outcomes are not permission to reset or retry blindly. `--dry-run` on start/restart has no lifecycle effects, and no eligible targets is a nonzero refusal.
+
+No-op does not synchronize changed role bodies/settings or prove business readiness. Stop before applying worker changes. A queued send is not the reply. Verify actual results and, after final `stop`, empty scoped residual resources; never clean up sibling teams or shared servers. Team sources use `--from DIR`/explicit paths; `reviewer.v2` is an agent ID, and `agent restart ID` disambiguates a same-named directory. Native unsupported capabilities remain refusals; `--in-place` fork is not implemented.
+
+### Compatibility bridges
+
+Existing automation may keep `quick-start`, `shutdown` and suffixed `*-agent` commands. They remain supported but are not the daily instructions above. Old bare/explicit-path `restart` retains preserve/default receipts; new `team restart` defaults to auto. Legacy single-seat start refuses a live seat, whereas new start can prove a no-op: do not mechanically rename scripts or assume byte-identical JSON. See the [operation skill](skills/team-agent/SKILL.md) and [operator reference](skills/team-agent/references/team-agent-operator.md).
+
 ## What you can say
 
 Team building and management is all natural language. Some real examples:

package/README.zh.md

@@ -20,7 +20,7 @@
 - 队友之间直接互发消息对齐(前端问后端要接口定义,不用经过你)
 - 你只跟队长说话,队长汇总进度、有分歧才来问你
 
-整个过程没有配置文件,没有新的界面要学。会跟 Claude 聊天,就会带团队。
+不用学习新的编排界面或语言：队长按你批准的方案准备团队文件。会跟 Claude 聊天，就会带团队。
 
 ## 安装
 
@@ -36,6 +36,51 @@ team-agent claude
 
 就这两步。后面发生的一切都在对话里。
 
+## 日常 CLI：start、stop、restart
+
+先核对实际二进制的 `team-agent start --help` 与 `team-agent team --help`。缺少这些入口时，应取得经授权的支持版本，不能仅凭版本号断定功能存在。生命周期命令由合法原生 **Leader 的工具上下文**执行，普通 Worker 不能据此升权。
+
+队长一次性准备 `TEAM.md` 与 `agents/*.md`，明确记录用户选择的 Provider 和布尔型权限绕过策略，例如：
+
+```text
+.team/current/
+  TEAM.md
+  agents/reviewer.md
+```
+
+配置完整后，显式选定工作区和团队：
+
+```sh
+team-agent start --from .team/current --workspace . --team project-team
+team-agent start --workspace . --team project-team
+team-agent send reviewer "检查修改并回报主要风险" --workspace . --team project-team
+team-agent inbox leader --workspace . --team project-team -n 3
+team-agent stop reviewer --workspace . --team project-team
+team-agent start reviewer --workspace . --team project-team
+team-agent restart reviewer --workspace . --team project-team
+team-agent stop --workspace . --team project-team --json
+team-agent start --workspace . --team project-team
+team-agent team restart --workspace . --team project-team --json
+```
+
+| 命令 | 意图与边界 |
+|---|---|
+| `start` | 完整配置首次建队；后续激活所选非 paused 席位；已确证存活且无配置漂移的实例保持不变 |
+| `start AGENT` | 唤醒停止席位、确证存活 no-op，或从完整角色文件加入 RoleOnly 席位；全新 ID 必须明确 Provider/bypass |
+| `stop [AGENT]` | 停单席或所选整队，保留会话关联；整队停止返回自有残留报告 |
+| `restart AGENT` | 先预检、确认停止后再启动该席位；不偷偷改角色或 reset |
+| `team restart` | 明确重启整队，保留显式停止和 paused 席位 |
+| `team status` / `status` | 读取简要节点投影；深入诊断用 `doctor` |
+| `agent add/remove/reset/clone/fork` | 保留原确认/能力门禁；reset 要求 `--discard-session`，fork 要求 `--as NEW_ID` |
+
+新单席/整队重启默认 `--session auto`：有确证就续接，否则仅允许原引擎支持的合法 fresh。**auto 不是记忆不丢失的保证。** 严格恢复用 `team-agent team restart --session preserve --workspace . --team project-team`；已知无法续接时停止前拒绝。unknown/partial 不是 reset 或盲目重试许可。start/restart 的 `--dry-run` 不产生生命周期效果；没有可操作目标时非零拒绝，不伪报启动成功。
+
+no-op 不表示角色正文/参数修改已生效，也不表示业务就绪；修改运行席位前先 stop。消息已排队不是回包。最终 stop 后核验所选团队残留为空，不能清理兄弟团队或共享服务器。团队目录用 `--from DIR`/明确路径选择；`reviewer.v2` 仍是节点 ID，同名目录歧义用 `agent restart ID` 消除。原生 Provider 不支持的能力必须拒绝，fork 的 `--in-place` 尚未实现。
+
+### 旧命令仅作兼容桥接
+
+既有自动化仍可保留 `quick-start`、`shutdown` 与 `*-agent`，但新日常指引采用上面的直觉命令。旧裸/显式路径 `restart` 保持 preserve 默认和原回执；新 `team restart` 默认 auto。旧单席 start 拒绝运行节点，新 start 可以确证 no-op：不要机械改名脚本或假设 JSON 逐字节等价。详见[操作 Skill](skills/team-agent/SKILL.md)与[操作参考](skills/team-agent/references/team-agent-operator.md)。
+
 ## 你可以说什么
 
 组队和管队全是自然语言,举几个真实的例子:

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

@@ -724,6 +724,11 @@ fn unified_default_doctor_report(args: &DoctorArgs, mut value: Value) -> Value {
                 );
                 merge_report_array(&mut value, "issues", &issues);
                 merge_report_array(&mut value, "suggested_repairs", &repairs);
+                let brief = crate::cli::status_port::status_brief_scoped(
+                    &selected.run_workspace, &state, None,
+                );
+                let observations = brief["nodes"].as_array().into_iter().flatten()
+                    .filter(|node| node.get("observation_reason").is_some()).cloned().collect::<Vec<_>>();
                 let run_workspace = selected.run_workspace.to_string_lossy().to_string();
                 runtime = json!({
                     "status": "present",
@@ -733,6 +738,7 @@ fn unified_default_doctor_report(args: &DoctorArgs, mut value: Value) -> Value {
                     "session_name": state.get("session_name").cloned().unwrap_or(Value::Null),
                     "leader_receiver": state.get("leader_receiver").cloned().unwrap_or(Value::Null),
                     "agent_count": state.get("agents").and_then(Value::as_object).map_or(0, serde_json::Map::len),
+                    "observations": observations,
                     "message_count": count_dir_entries(&selected.run_workspace.join(".team").join("messages")),
                     "result_count": count_dir_entries(&selected.run_workspace.join(".team").join("results")),
                 });
@@ -740,6 +746,11 @@ fn unified_default_doctor_report(args: &DoctorArgs, mut value: Value) -> Value {
         }
         Err(error) => {
             runtime["status"] = Value::String("unresolved".to_string());
+            runtime["observation_reason"] = json!("runtime_selection_failed");
+            runtime["next_action"] = json!(format!(
+                "team-agent status --workspace {} --team {} --json; verify the intended workspace/team selector before lifecycle changes",
+                shell_quote(&requested_workspace), shell_quote(team_key),
+            ));
             append_issue_repair(
                 &mut value,
                 "runtime_selection_failed",

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

@@ -0,0 +1,401 @@
+//! Pure control-argument grammar. Native/route payloads keep their own parsers.
+use super::CliError;
+use std::collections::BTreeSet;
+
+#[derive(Clone, Copy)]
+enum ValueKind {
+    Switch,
+    Token,
+    Path,
+    Payload,
+    Query,
+    Count,
+    Seconds,
+    PositiveSeconds,
+    Choice(&'static [&'static str]),
+    FoldedChoice(&'static [&'static str]),
+}
+use ValueKind::*;
+
+struct Schema {
+    flags: &'static [(&'static str, ValueKind)],
+    max_positionals: usize,
+    workspace: bool,
+    team: bool,
+}
+
+fn schema(command: &str) -> Option<Schema> {
+    let (flags, max_positionals): (&'static [(&'static str, ValueKind)], usize) = match command {
+        "intent-start" | "start" => (
+            &[
+                ("--from", Path),
+                ("--session", Choice(&["auto", "preserve"])),
+                ("--dry-run", Switch),
+                ("--allow-fresh", Switch),
+                ("--provider", Token),
+                ("--model", Token),
+                ("--effort", Token),
+                ("--bypass", Choice(&["true", "false"])),
+                ("--prompt", Payload),
+                ("--profile", Token),
+                ("--role-file", Path),
+            ],
+            1,
+        ),
+        "intent-stop" | "stop" => (&[], 1),
+        "intent-restart" => (
+            &[
+                ("--session", Choice(&["auto", "preserve"])),
+                ("--dry-run", Switch),
+                ("--allow-fresh", Switch),
+                ("--session-converge-deadline", Seconds),
+                ("--detail", Switch),
+            ],
+            1,
+        ),
+        "quick-start" => (
+            &[
+                ("--name", Token),
+                ("--team-id", Token),
+                ("--yes", Switch),
+                ("--backend", FoldedChoice(&["tmux", "conpty"])),
+                ("--detail", Switch),
+                ("--no-display", Switch),
+            ],
+            1,
+        ),
+        "send" => (
+            &[
+                ("--targets", Token),
+                ("--pane", Token),
+                ("--to-name", Token),
+                ("--to-leader", Token),
+                ("--mailbox", Switch),
+                (
+                    "--presentation-sink",
+                    Choice(&["leader", "casefile", "silent"]),
+                ),
+                ("--message-class", Token),
+                ("--case-id", Token),
+                ("--task", Token),
+                ("--watch-result", Switch),
+                ("--requires-ack", Switch),
+                ("--no-ack", Switch),
+                ("--no-wait", Switch),
+                ("--timeout", Seconds),
+                ("--confirm-human", Switch),
+                ("--message-id", Token),
+            ],
+            usize::MAX,
+        ),
+        "status" => (&[("--detail", Switch), ("--summary", Switch)], 1),
+        "models" => (&[("--provider", Token), ("--search", Query)], usize::MAX),
+        "inbox" => (&[("--limit", Count)], 1),
+        "shutdown" => (&[("--keep-logs", Switch)], 0),
+        "restart" => (
+            &[
+                ("--allow-fresh", Switch),
+                ("--session-converge-deadline", Seconds),
+                ("--detail", Switch),
+                ("--no-display", Switch),
+            ],
+            1,
+        ),
+        "start-agent" | "add-agent" => (
+            &[
+                ("--provider", Token),
+                ("--model", Token),
+                ("--effort", Token),
+                ("--bypass", Choice(&["true", "false"])),
+                ("--prompt", Payload),
+                ("--profile", Token),
+                ("--role-file", Path),
+                ("--force", Switch),
+                ("--allow-fresh", Switch),
+            ],
+            1,
+        ),
+        "stop-agent" | "approvals" => (&[], 1),
+        "reset-agent" => (&[("--discard-session", Switch)], 1),
+        "clone-agent" | "fork-agent" => (&[("--as", Token), ("--label", Token)], 1),
+        "remove-agent" => (
+            &[
+                ("--from-spec", Switch),
+                ("--confirm", Switch),
+                ("--force", Switch),
+            ],
+            1,
+        ),
+        "doctor" => (
+            &[
+                ("--gate", Token), // Preserve the doctor's typed unknown_gate refusal.
+                ("--comms", Switch),
+                ("--fix", Switch),
+                ("--fix-schema", Switch),
+                ("--cleanup-orphans", Switch),
+                ("--confirm", Switch),
+            ],
+            1,
+        ),
+        "leaders" => (
+            &[
+                ("--all", Switch),
+                ("--stale", Switch),
+                ("--prune", Switch),
+                ("--dry-run", Switch),
+                ("--search", Token),
+            ],
+            1,
+        ),
+        "profile" => (
+            &[
+                ("--auth-mode", Token),
+                ("--proxy-mode", Choice(&["direct", "inherit"])),
+            ],
+            2,
+        ),
+        "install-skill" => (
+            &[
+                ("--target", Choice(&["all", "codex", "claude", "copilot"])),
+                ("--source", Path),
+                ("--dest", Path),
+                ("--uninstall", Switch),
+                ("--dry-run", Switch),
+            ],
+            0,
+        ),
+        "claim-leader" => (&[("--confirm", Switch), ("--detail", Switch)], 0),
+        "takeover" => (&[("--confirm", Switch)], 0),
+        "attach-leader" => (
+            &[
+                ("--pane", Token),
+                ("--provider", Token),
+                ("--confirm", Switch),
+            ],
+            0,
+        ),
+        "attach-app-server-leader" => (&[("--socket", Path), ("--thread-id", Token)], 0),
+        "wait" => (&[("--task", Token)], 0),
+        "coordinator" => (
+            &[("--once", Switch), ("--tick-interval", PositiveSeconds)],
+            0,
+        ),
+        "kiro" => (&[], 0),
+        _ => return None,
+    };
+    Some(Schema {
+        flags,
+        max_positionals,
+        workspace: !matches!(command, "models" | "leaders" | "install-skill" | "kiro"),
+        team: !matches!(
+            command,
+            "models" | "leaders" | "install-skill" | "kiro" | "wait" | "quick-start"
+        ),
+    })
+}
+
+fn canonical_flag<'a>(command: &str, flag: &'a str) -> &'a str {
+    match (command, flag) {
+        (_, "-h") => "--help",
+        ("inbox", "-n") => "--limit",
+        ("quick-start", "--team") => "--team-id",
+        ("send", "--target" | "--to") => "--targets",
+        _ => flag,
+    }
+}
+
+fn option(schema: &Schema, command: &str, flag: &str) -> Option<ValueKind> {
+    match flag {
+        "--help" | "--json" | "--no-display" => Some(Switch),
+        "--workspace" if schema.workspace => Some(Path),
+        "--team" if schema.team => Some(Token),
+        "--role-file" if command == "start-agent" => None,
+        "--allow-fresh" if command == "add-agent" => None,
+        _ => schema
+            .flags
+            .iter()
+            .find(|(name, _)| *name == flag)
+            .map(|(_, kind)| *kind),
+    }
+}
+
+fn valid_value(kind: ValueKind, value: &str) -> bool {
+    if value.trim().is_empty() {
+        return matches!(kind, Query);
+    }
+    match kind {
+        Count => value.parse::<usize>().is_ok(),
+        Seconds | PositiveSeconds => value.parse::<f64>().is_ok_and(|number| {
+            number.is_finite()
+                && number >= 0.0
+                && number <= u64::MAX as f64 / 1000.0
+                && (!matches!(kind, PositiveSeconds) || number > 0.0)
+        }),
+        Choice(values) => values.contains(&value),
+        FoldedChoice(values) => values.contains(&value.trim().to_ascii_lowercase().as_str()),
+        _ => true,
+    }
+}
+
+pub(super) struct CheckedArgs {
+    pub(super) tokens: Vec<String>,
+    pub(super) help: bool,
+}
+
+/// Validate only control tokens. Values retain everything after the first '='.
+/// A free --help wins before filesystem/owner checks; a consumed/literal one never does.
+pub(super) fn parse(command: &str, args: &[String]) -> Result<CheckedArgs, CliError> {
+    let schema = schema(command)
+        .ok_or_else(|| CliError::Usage(format!("no argument schema for {command}")))?;
+    let mut tokens = Vec::new();
+    let mut seen = BTreeSet::new();
+    let mut positionals = 0usize;
+    let mut error = None;
+    let mut help = false;
+    let mut i = 0;
+    while i < args.len() {
+        let raw = &args[i];
+        if raw == "--" {
+            positionals += args.len() - i - 1;
+            tokens.extend_from_slice(&args[i..]);
+            break;
+        }
+        if !raw.starts_with('-') {
+            positionals += 1;
+            tokens.push(raw.clone());
+            i += 1;
+            continue;
+        }
+        let (key, inline) = raw
+            .split_once('=')
+            .map_or((raw.as_str(), None), |(key, value)| (key, Some(value)));
+        let flag = canonical_flag(command, key);
+        let Some(kind) = option(&schema, command, flag) else {
+            error.get_or_insert_with(|| format!("unknown option for {command}: {key}"));
+            i += 1;
+            continue;
+        };
+        if flag == "--help" && inline.is_none() {
+            help = true;
+        }
+        if !seen.insert(flag.to_string()) {
+            error.get_or_insert_with(|| format!("duplicate option: {flag}"));
+        }
+        if matches!(kind, Switch) {
+            if inline.is_some() {
+                error.get_or_insert_with(|| format!("{flag} does not take a value"));
+            }
+            // Explicit historical compatibility flag, never inferred from an unknown
+            // option and never removed from a consumed or post-delimiter payload.
+            if flag != "--no-display" {
+                tokens.push(flag.to_string());
+            }
+        } else {
+            let value = if let Some(value) = inline {
+                Some(value)
+            } else {
+                args.get(i + 1)
+                    .filter(|value| matches!(kind, Payload | Query) || !value.starts_with('-'))
+                    .map(|value| {
+                        i += 1;
+                        value.as_str()
+                    })
+            };
+            match value {
+                Some(value) if valid_value(kind, value) => tokens.push(format!("{flag}={value}")),
+                Some(_) => {
+                    error.get_or_insert_with(|| format!("invalid value for {flag}"));
+                }
+                None => {
+                    error.get_or_insert_with(|| format!("missing value for {flag}"));
+                }
+            }
+        }
+        i += 1;
+    }
+    if help {
+        return Ok(CheckedArgs { tokens, help });
+    }
+    if positionals > schema.max_positionals {
+        error.get_or_insert_with(|| format!("too many positional arguments for {command}"));
+    }
+    for pair in [
+        ["--detail", "--summary"],
+        ["--all", "--stale"],
+        ["--requires-ack", "--no-ack"],
+    ] {
+        if pair.iter().all(|flag| seen.contains(*flag)) {
+            error.get_or_insert_with(|| format!("{} conflicts with {}", pair[0], pair[1]));
+        }
+    }
+    if command == "send"
+        && ["--targets", "--pane", "--to-name", "--to-leader"]
+            .iter()
+            .filter(|flag| seen.contains(**flag))
+            .count()
+            > 1
+    {
+        error.get_or_insert_with(|| "choose one recipient addressing mode".to_string());
+    }
+    if command == "start-agent" && seen.contains("--force") {
+        error = Some("start-agent does not support --force; use stop-agent AGENT followed by start-agent AGENT for a safe restart".to_string());
+    }
+    if let Some(error) = error {
+        return Err(CliError::Usage(error));
+    }
+    Ok(CheckedArgs { tokens, help })
+}
+
+/// Rendering switches must not be inferred from a consumed value or literal payload.
+pub(super) fn has_flag(command: &str, args: &[String], needle: &str) -> bool {
+    if matches!(command, "team" | "agent") {
+        if let Some((operation, args)) = args.split_first() {
+            let command = match operation.as_str() {
+                "start" => "intent-start",
+                "stop" => "intent-stop",
+                "restart" => "intent-restart",
+                "status" if command == "team" => "status",
+                "add" => "add-agent",
+                "remove" => "remove-agent",
+                "reset" => "reset-agent",
+                "clone" => "clone-agent",
+                "fork" => "fork-agent",
+                _ => return false,
+            };
+            return has_flag(command, args, needle);
+        }
+    }
+    let Some(schema) = schema(command) else {
+        // Dedicated native parsers retain their pre-delimiter rendering switch.
+        return args
+            .iter()
+            .take_while(|arg| arg.as_str() != "--")
+            .any(|arg| arg == needle);
+    };
+    let mut i = 0;
+    while i < args.len() {
+        let raw = &args[i];
+        if raw == "--" {
+            break;
+        }
+        let (key, inline) = raw
+            .split_once('=')
+            .map_or((raw.as_str(), None), |(key, value)| (key, Some(value)));
+        let flag = canonical_flag(command, key);
+        if flag == needle && inline.is_none() {
+            return true;
+        }
+        if let Some(kind) = option(&schema, command, flag) {
+            if !matches!(kind, Switch) && inline.is_none() {
+                if args
+                    .get(i + 1)
+                    .is_some_and(|value| matches!(kind, Payload | Query) || !value.starts_with('-'))
+                {
+                    i += 1;
+                }
+            }
+        }
+        i += 1;
+    }
+    false
+}