@team-agent/installer 0.5.97 → 0.5.99

package/skills/team-agent/references/team-agent-operator.md

@@ -43,7 +43,7 @@ team-agent codex
 team-agent claude
 ```
 
-Pass provider flags after the provider name, for example `team-agent codex --dangerously-bypass-approvals-and-sandbox`. Existing tmux layouts are valid too, including Finder/Ghostty launchers, as long as `team-agent quick-start` is invoked from the leader's current tmux pane. Do not start a real team from a naked terminal that Team Agent cannot address through tmux.
+Pass provider flags after the provider name, for example `team-agent codex --dangerously-bypass-approvals-and-sandbox`. Run `team-agent quick-start` from the leader's current tmux pane. Do not start a real team from a naked terminal that Team Agent cannot address through tmux.
 
 **0.5.66:** leader `--dangerously-*` flags no longer inherit bypass to workers. Per-worker bypass is the role field `dangerously_skip_permissions` (see Permissions).
 
@@ -55,7 +55,7 @@ When the user has been communicating in Chinese throughout the conversation, all
 
 ## Minimal Copy-Paste Team
 
-`dangerously_skip_permissions` is **required** on every role doc (boolean). `TEAM.md` `dangerous_auto_approve` is **not** the 0.5.66 bypass switch (see Permissions). Values under `provider_models:` below are **fill-ins for omitted role `model`**, not a validity catalog (lookup: `team-agent compile --team <dir> --out /tmp/spec.yaml --json` and read the compiled agent `model`).
+`dangerously_skip_permissions` is **required** on every role doc (boolean). `TEAM.md` `dangerous_auto_approve` is **not** the 0.5.66 bypass switch (see Permissions). Values under `provider_models:` below are **fill-ins for omitted role `model`**, not a validity catalog; the values are configuration fallbacks.
 
 ```bash
 mkdir -p .team/current/agents
@@ -98,14 +98,7 @@ team-agent quick-start .team/current
 
 YAML lists must be block style. Use `tools:\n  - fs_read`; do not use `tools: [fs_read, mcp_team]`.
 
-Display choices (set `display_backend:` in `TEAM.md` to opt in):
-
-- `none` (default): headless / no GUI window manager. The team runs entirely in the per-workspace tmux server; this is what the demo above uses.
-- `adaptive`: framework picks an available GUI layout for the local platform.
-- `ghostty_workspace`: one Ghostty window. Workers are shown in tmux tabs/windows, up to 3 side-by-side panes per tab. Four workers become `3 + 1`; eight become `3 + 3 + 2`.
-- `ghostty_window`: one Ghostty window per worker.
-
-**Omitting `display_backend` defaults to `none`** (changed in 0.3.4). Set `display_backend: adaptive` (or one of the explicit ghostty variants) in `TEAM.md` only when the user wants GUI windows.
+Workers always run headlessly in independent windows on the per-workspace tmux server. No GUI display backend is configured in `TEAM.md`.
 
 ## Private Tmux Socket
 
@@ -179,7 +172,7 @@ codex debug models
 
 That command is the Codex catalog. This skill does **not** keep a model id list. If `codex` is not on PATH, the lookup is unavailable; do not invent slugs.
 
-Role docs may omit `model` for non-grok subscription workers; compile then fills from `TEAM.md` `provider_models` or leaves `null` when a profile is present (see compatible_api). **Do not treat those fill-ins as a validity catalog.** **Grok roles cannot omit `model`** — compile fails closed (same `compile --team` command as below).
+Role docs may omit `model` for non-grok subscription workers; compile then fills from `TEAM.md` `provider_models` or leaves `null` when a profile is present (see compatible_api). **Do not treat those fill-ins as a validity catalog.** **Grok roles cannot omit `model`** — the internal compiler fails closed.
 
 Claude: run `claude auth status`; if missing, run `claude auth login`. Team Agent stores Claude worker sessions by passing `--session-id` and resumes with `--resume`.
 Use `provider: claude` or `provider: claude_code` for Claude workers.
@@ -233,15 +226,17 @@ POST {BASE_URL}/v1/chat/completions
 
 Fail = report the HTTP/body. Success = leave the id alone. **Do not substitute a different id.**
 
-How compile currently wires role `model` vs profile `MODEL` (not a validity list):
+How role `model` and profile `MODEL` are resolved (not a validity list):
+
+The internal compiler preserves a role `model:` when present. If it is omitted, provider/team defaults may fill it; a profile-deferred role may remain `null`. A profile's `MODEL` does not override an explicit role model, and the compiler does not compare the two. Actual profile/provider readiness is checked during launch and preflight, not by a public export command.
+
+For an existing spec file or team directory at `$d`, run the retained validation:
 
 ```bash
-team-agent compile --help
+team-agent validate "$d" --json
 ```
 
-Observed (exit 0): `usage: team-agent compile --team TEAM [--out FILE] [--json]`.
-
-Recreate: `auth_mode: compatible_api` without `profile` → compile exit 1 `profile is required when auth_mode is 'compatible_api'`. Role `model:` set + `profile:` set → compiled agent `model` is the role string; profile `MODEL` is not read at compile. Role omits `model` + `profile:` → compiled `model: null`. Compile does **not** compare the two. Whether launch refuses a mismatch was **not** spawned-verified.
+A file input runs schema structural validation. A team-directory input internally compiles `TEAM.md` and `agents/*.md` and validates role-document completeness. Neither input writes or exports a spec file.
 
 How to check `--auth-mode` literals (the CLI does not print an allow-list on this gauge):
 
@@ -265,7 +260,7 @@ Observed (all exit 0):
 
 ```text
 usage: team-agent restart [WORKSPACE] [--team TEAM] [--allow-fresh] [--session-converge-deadline SECONDS] [--json]
-usage: team-agent add-agent AGENT --role-file FILE [--force] [--workspace WORKSPACE] [--team TEAM] [--no-display] [--json]
+usage: team-agent add-agent AGENT --role-file FILE [--force] [--workspace WORKSPACE] [--team TEAM] [--json]
 usage: team-agent shutdown [--workspace WORKSPACE] [--team TEAM] [--keep-logs] [--json]
 ```
 
@@ -289,26 +284,19 @@ team-agent permission-modes
 
 Observed (exit 1): `invalid choice: 'permission-modes'`.
 
-`team-agent --help` does **not** list `permission_mode`, `TEAM_AGENT_LEADER_BYPASS`, or `dangerous_auto_approve`. Lookup is `team-agent compile` / `team-agent validate` on a throwaway team dir, not a flag enum.
+`team-agent --help` does **not** list `permission_mode`, `TEAM_AGENT_LEADER_BYPASS`, or `dangerous_auto_approve`. Use `team-agent validate "$d" --json` with an existing spec file or team directory; it does not enumerate permission modes.
 
 ### Live control: role `dangerously_skip_permissions`
 
-Required boolean on every role doc. Missing or non-bool fails compile.
+Required boolean on every role doc. Missing or non-bool fails the internal compiler; this is checked again before lifecycle launch.
 
-Recreate:
+For an existing spec file, the retained schema check is:
 
 ```bash
-d=$(mktemp -d) && mkdir -p "$d/agents"
-printf '%s\n' '---' 'name: t' 'objective: t' 'provider: fake' '---' 'x' > "$d/TEAM.md"
-printf '%s\n' '---' 'name: coder' 'role: Worker' 'provider: fake' 'model: fake' 'auth_mode: subscription' 'tools:' '  - mcp_team' '---' 'b' > "$d/agents/coder.md"
-team-agent compile --team "$d" --out /tmp/ta-compile-out.yaml --json
+team-agent validate "$d" --json
 ```
 
-Observed (exit 1): `missing front matter field dangerously_skip_permissions. This field must be declared explicitly; it controls whether the agent launches with permission prompts bypassed.` JSON also includes `"action": "run \`team-agent doctor\` or inspect the log path shown here"`.
-
-Non-bool (`dangerously_skip_permissions: bypass`) observed (exit 1): `front matter field dangerously_skip_permissions must be a boolean.`
-
-Legal values reachable from that error: **boolean `true` or `false`**. No other literals are accepted.
+With a team-directory input, `validate` internally compiles `TEAM.md` and `agents/*.md` and validates role-document completeness; with a file input, it runs schema structural validation. Neither input writes or exports a spec file. The internal compiler rejects non-bool (`dangerously_skip_permissions: bypass`) and accepts only boolean **`true`** or **`false`**.
 
 `true` is the per-worker bypass opt-in. `false` is the default you should copy unless the user explicitly wants prompts skipped.
 
@@ -345,7 +333,7 @@ What the sources actually do (reader can re-open these files):
 | `required_dangerously_skip_permissions` | `crates/team-agent/src/compiler.rs` | Compile **requires** role `dangerously_skip_permissions` bool. This is the 0.5.66 worker bypass source. |
 | `resolved_tool_strings_for_command` | `crates/team-agent/src/lifecycle/worker_command_context.rs` | `true` appends tool sentinel `dangerous_auto_approve`; comment: no longer consumes team/runtime/leader `DangerousApproval`. |
 | `provider_bypass_flag` | `crates/team-agent/src/provider/bypass_flags.rs` | **唯一权威**: role `dangerously_skip_permissions: true` decides whether to add a provider bypass argv flag. Maps provider → flag string only. |
-| spec allowed key `permission_mode` | `crates/team-agent/src/model/spec.rs` | Historical; **not consumed** by compiler (comment: 0.5.66 起不再被 compiler 消费). CLI compile of `permission_mode: bypass` and `permission_mode: not-a-mode` both `ok: true` with the key absent from spec. |
+| spec allowed key `permission_mode` | `crates/team-agent/src/model/spec.rs` | Historical; **not consumed** by compiler (comment: 0.5.66 起不再被 compiler 消费); the key is absent from the compiled agent spec. |
 | `apply_mcp_auto_approval_env` | `crates/team-agent/src/lifecycle/launch/worker_env.rs` | Writes `TEAM_AGENT_LEADER_BYPASS` `1`/`0` from `DangerousApproval` when source is `LeaderProcess`. Separate from compile. |
 | `worker_spawn_env` test | `crates/team-agent/src/layout/worker_env.rs` | **Strips** inherited `TEAM_AGENT_LEADER_BYPASS` from parent env. |
 | `claude_dangerous_auto_approve` (and siblings) | `crates/team-agent/src/provider/adapters/*.rs` | Adapters look for tool name `dangerous_auto_approve`, not `TEAM.md`. |
@@ -462,7 +450,7 @@ On success, `send --json` includes `message_id`. The deprecation warning itself
 - `team-agent start-agent coder --workspace .` repairs one missing worker window without interrupting other workers.
 - `team-agent doctor` checks local dependencies and provider auth hints.
 - `team-agent results --case CASE_ID` reads reported results for a case.
-- `team-agent compile` / `team-agent validate` are hidden from top-level `--help` but `--help` on those verbs works; use them to check role docs without launching.
+- `team-agent validate` is hidden from top-level `--help` but `--help` on the verb works; use it to check an existing spec without launching.
 
 <!-- command-coverage:normative-start -->
 ### Normative command inventory
@@ -620,16 +608,13 @@ For any non-zero `team-agent` exit, report the command, exit code, last about 20
 
 **If the error JSON/text includes a structured `action` field, run that `action` first.** This rule does not expire with skill versions.
 
-Reproduce a structured `action` (missing `dangerously_skip_permissions` → compile JSON):
+For an existing spec file or team directory, use the retained validation:
 
 ```bash
-d=$(mktemp -d) && mkdir -p "$d/agents"
-printf '%s\n' '---' 'name: t' 'objective: t' 'provider: fake' '---' 'x' > "$d/TEAM.md"
-printf '%s\n' '---' 'name: coder' 'role: Worker' 'provider: fake' 'model: fake' 'auth_mode: subscription' 'tools:' '  - mcp_team' '---' 'b' > "$d/agents/coder.md"
-team-agent compile --team "$d" --out /tmp/ta-failure-rules-compile.yaml --json
+team-agent validate "$d" --json
 ```
 
-Observed (exit 1): JSON includes `"ok": false` and `"action": "run \`team-agent doctor\` or inspect the log path shown here"`, plus `missing front matter field dangerously_skip_permissions`. Prefer the `action` over guessing flags.
+A validation failure may include a structured `action`; prefer that action over guessing flags.
 
 `coordinator.session_missing` is a self-healing transient: run `team-agent status --json`, if `ready` is true (or workers show `running`) continue; do not shutdown and wait.
 
@@ -637,7 +622,7 @@ Observed (exit 1): JSON includes `"ok": false` and `"action": "run \`team-agent
 
 Examples of `action` observed on this gauge:
 
-- compile/add-agent usage failure: `"action": "run \`team-agent doctor\` or inspect the log path shown here"`
+- add-agent usage failure: `"action": "run \`team-agent doctor\` or inspect the log path shown here"`
 - send with no runtime: `"action": "Run team-agent quick-start/restart in the target workspace, or choose a workspace that has .team/runtime/state.json"`
 - `claim-leader` from a worker pane: `"action": "pane %21 is registered as worker developer-d108; run claim-leader from the leader's own pane, not a worker pane"` (exit 1, `ok: false`, `reason: caller_not_leader_shaped`)
 

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

@@ -1,192 +0,0 @@
-use super::*;
-
-fn compile_team_dir(tag: &str) -> std::path::PathBuf {
-    let team = tmp_workspace().join(tag);
-    std::fs::create_dir_all(team.join("agents")).unwrap();
-    std::fs::write(
-        team.join("TEAM.md"),
-        "---\nname: compileteam\nobjective: Compile probe.\nprovider: fake\n---\n\nCompile team.\n",
-    )
-    .unwrap();
-    std::fs::write(
-        team.join("agents").join("worker.md"),
-        "---\nname: worker\nrole: Worker\nprovider: fake\nmodel: fake\ntools:\n  - mcp_team\ndangerously_skip_permissions: false\n---\n\nWorker role.\n",
-    )
-    .unwrap();
-    team
-}
-
-fn compile_team_dir_with_owner_team_id(tag: &str) -> std::path::PathBuf {
-    let team = compile_team_dir(tag);
-    std::fs::write(
-        team.join("TEAM.md"),
-        "---\nname: compileteam\nobjective: Compile probe.\nprovider: fake\nowner_team_id: user-set-owner\n---\n\nCompile team.\n",
-    )
-    .unwrap();
-    team
-}
-
-#[test]
-fn cmd_compile_json_and_human_match_golden_shape_and_writes_out() {
-    let team = compile_team_dir("compile-ok");
-    let out = team.parent().unwrap().join("out.yaml");
-    let args = CompileArgs {
-        team: team.clone(),
-        out: out.clone(),
-        json: true,
-    };
-
-    let result = cmd_compile(&args).expect("compile");
-    assert_eq!(result.exit, ExitCode::Ok);
-    assert!(
-        out.exists(),
-        "compile must write the compiled spec to --out"
-    );
-    assert!(
-        std::fs::read_to_string(&out)
-            .unwrap()
-            .contains("version: 1"),
-        "compiled out file must contain the spec YAML"
-    );
-
-    let json_text = emit(&result.output, true).unwrap();
-    let expected_json = format!(
-        "{{\n  \"agents\": [\n    \"worker\"\n  ],\n  \"ok\": true,\n  \"out\": \"{}\",\n  \"team_dir\": \"{}\"\n}}",
-        out.to_string_lossy(),
-        team.to_string_lossy()
-    );
-    assert_eq!(
-        json_text, expected_json,
-        "golden --json is sorted pretty JSON"
-    );
-
-    let human_text = emit(&result.output, false).unwrap();
-    let expected_human = format!(
-        "ok: True\nteam_dir: {}\nout: {}\nagents: [\"worker\"]",
-        team.to_string_lossy(),
-        out.to_string_lossy()
-    );
-    assert_eq!(
-        human_text, expected_human,
-        "golden human output preserves cmd_compile insertion order"
-    );
-}
-
-#[test]
-fn cmd_compile_ignores_user_owner_team_id_and_emits_warning_event() {
-    let team = compile_team_dir_with_owner_team_id("compile-ignored-owner");
-    let workspace = team.parent().unwrap().to_path_buf();
-    let out = workspace.join("ignored-owner-out.yaml");
-    let args = CompileArgs {
-        team: team.clone(),
-        out: out.clone(),
-        json: true,
-    };
-
-    let result = cmd_compile(&args).expect("compile");
-    assert_eq!(result.exit, ExitCode::Ok);
-    let compiled = std::fs::read_to_string(&out).unwrap();
-    assert!(
-        !compiled.contains("owner_team_id"),
-        "user-set owner_team_id must not be compiled into team.spec.yaml"
-    );
-    let events = crate::event_log::EventLog::new(&workspace).tail(0).unwrap();
-    let event = events
-        .iter()
-        .find(|event| {
-            event.get("event").and_then(serde_json::Value::as_str) == Some("spec.field_ignored")
-        })
-        .expect("owner_team_id warning event");
-    assert_eq!(
-        event.get("field").and_then(serde_json::Value::as_str),
-        Some("owner_team_id")
-    );
-    assert_eq!(
-        event.get("value").and_then(serde_json::Value::as_str),
-        Some("user-set-owner")
-    );
-    assert_eq!(
-        event.get("action").and_then(serde_json::Value::as_str),
-        Some("remove owner_team_id from TEAM.md")
-    );
-}
-
-#[test]
-fn cmd_compile_without_owner_team_id_emits_no_ignored_field_event() {
-    let team = compile_team_dir("compile-no-ignored-owner");
-    let workspace = team.parent().unwrap().to_path_buf();
-    let out = workspace.join("no-ignored-owner-out.yaml");
-    let args = CompileArgs {
-        team: team.clone(),
-        out,
-        json: true,
-    };
-
-    let result = cmd_compile(&args).expect("compile");
-    assert_eq!(result.exit, ExitCode::Ok);
-    let events = crate::event_log::EventLog::new(&workspace).tail(0).unwrap();
-    assert!(
-        events.iter().all(|event| {
-            event.get("event").and_then(serde_json::Value::as_str) != Some("spec.field_ignored")
-        }),
-        "TEAM.md without owner_team_id must not emit ignored-field warning"
-    );
-}
-
-#[test]
-fn run_dispatches_compile_and_error_path_exits_error() {
-    let team = compile_team_dir("compile-dispatch");
-    let out = team.parent().unwrap().join("dispatch.yaml");
-    let argv = vec![
-        "compile".to_string(),
-        "--team".to_string(),
-        team.to_string_lossy().to_string(),
-        "--out".to_string(),
-        out.to_string_lossy().to_string(),
-        "--json".to_string(),
-    ];
-    assert_eq!(run(&argv, team.parent().unwrap()), ExitCode::Ok);
-    assert!(
-        out.exists(),
-        "dispatch compile must route to cmd_compile and write --out"
-    );
-
-    let bad = tmp_workspace().join("compile-bad");
-    std::fs::create_dir_all(bad.join("agents")).unwrap();
-    std::fs::write(
-        bad.join("TEAM.md"),
-        "---\nname: badteam\nobjective: Bad.\nprovider: fake\n---\n",
-    )
-    .unwrap();
-    std::fs::write(
-        bad.join("agents").join("broken.md"),
-        "---\nname: broken\nrole: Broken\nmodel: fake\n---\n",
-    )
-    .unwrap();
-    let bad_out = bad.parent().unwrap().join("bad.yaml");
-    let bad_args = CompileArgs {
-        team: bad.clone(),
-        out: bad_out.clone(),
-        json: true,
-    };
-    let err = cmd_compile(&bad_args).unwrap_err().to_string();
-    assert!(
-        err.contains("missing front matter field provider"),
-        "got {err}"
-    );
-    assert_eq!(
-        run(
-            &[
-                "compile".to_string(),
-                "--team".to_string(),
-                bad.to_string_lossy().to_string(),
-                "--out".to_string(),
-                bad_out.to_string_lossy().to_string(),
-                "--json".to_string(),
-            ],
-            bad.parent().unwrap(),
-        ),
-        ExitCode::Error,
-        "invalid compile input must exit 1, not fall through as an unknown subcommand"
-    );
-}