@team-agent/installer 0.5.71 → 0.5.72

package/crates/team-agent/src/lifecycle/tests/lane_ops.rs

@@ -1846,3 +1846,171 @@ fn lanea_fork_rollback_complete_on_post_spawn_failure() {
     // Golden contract (operations.py:384-394): a post-spawn failure kills the spawned window, restores
     // the old spec text + prior state, and runs cleanup_mcp before re-raising.
 }
+
+#[test]
+fn schema_invalid_pi_role_is_rejected_before_normal_and_force_mutation() {
+    let ws = lanea_ws_agents(json!({
+        "alpha": { "status": "stopped", "provider": "codex", "window": "alpha" },
+        "bravo": { "status": "running", "provider": "codex", "window": "bravo" }
+    }));
+    let tx = LaneTransport::new("team-laneateam", &[]);
+    seed_healthy_coordinator(&ws);
+    let role_dir = ws.join("role-masters");
+    std::fs::create_dir_all(&role_dir).unwrap();
+    let role = role_dir.join("invalid-pi.md");
+    std::fs::write(
+        &role,
+        CHARLIE_ROLE
+            .replace(
+                "provider: codex\nmodel: gpt-5.5",
+                "provider: pi\nmodel: openai-codex/gpt-5.6-sol",
+            )
+            .replace("  - mcp_team", "  - fs_read"),
+    )
+    .unwrap();
+
+    let spec_path = selected_spec_path(&ws);
+    let state_path = crate::state::persist::runtime_state_path(&ws);
+    let event_path = ws.join(".team/logs/events.jsonl");
+    let copied_role = ws.join("agents/charlie.md");
+    let team_state_path = ws.join("team_state.md");
+    let charlie_paths = crate::lifecycle::launch::pi_mcp::pi_seat_paths(
+        &ws,
+        "laneateam",
+        "charlie",
+    );
+    let alpha_paths =
+        crate::lifecycle::launch::pi_mcp::pi_seat_paths(&ws, "laneateam", "alpha");
+    let spec_before = std::fs::read(&spec_path).unwrap();
+    let state_before = std::fs::read(&state_path).unwrap();
+    let role_before = std::fs::read(&role).unwrap();
+    let alpha_before = serde_json::from_slice::<serde_json::Value>(&state_before).unwrap()
+        ["agents"]["alpha"]
+        .clone();
+    for path in [
+        &event_path,
+        &copied_role,
+        &team_state_path,
+        &charlie_paths.wrapper,
+        &charlie_paths.sessions,
+        &alpha_paths.wrapper,
+        &alpha_paths.sessions,
+    ] {
+        assert!(!path.exists(), "precondition: {} must be absent", path.display());
+    }
+
+    let assert_schema_error = |error: crate::lifecycle::LifecycleError| match error {
+        crate::lifecycle::LifecycleError::Compile(message) => {
+            assert!(message.contains("Pi roles require mcp_team"), "{message}");
+        }
+        other => panic!("expected Pi role schema error, got {other:?}"),
+    };
+    let assert_unchanged = |expected_role: &[u8]| {
+        assert_eq!(spec_before, std::fs::read(&spec_path).unwrap());
+        assert_eq!(state_before, std::fs::read(&state_path).unwrap());
+        assert_eq!(expected_role, std::fs::read(&role).unwrap());
+        for path in [
+            &event_path,
+            &copied_role,
+            &team_state_path,
+            &charlie_paths.wrapper,
+            &charlie_paths.sessions,
+            &alpha_paths.wrapper,
+            &alpha_paths.sessions,
+        ] {
+            assert!(!path.exists(), "preflight created {}", path.display());
+        }
+        let state = crate::state::persist::load_runtime_state(&ws).unwrap();
+        assert_eq!(state["agents"]["alpha"], alpha_before);
+        assert!(state["agents"].get("charlie").is_none(), "no reservation row");
+        assert!(tx.spawns().is_empty());
+        assert!(tx.killed().is_empty());
+    };
+
+    let mut normal_calls = 0;
+    let mut normal_discover = |_requested: &str| {
+        normal_calls += 1;
+        Ok(Vec::new())
+    };
+    let normal = crate::lifecycle::add_agent_with_transport_pi_preflight(
+        &ws,
+        &aid("charlie"),
+        &role,
+        false,
+        None,
+        &tx,
+        &mut normal_discover,
+    )
+    .expect_err("invalid Pi schema must fail before reservation");
+    drop(normal_discover);
+    assert_eq!(normal_calls, 0);
+    assert_schema_error(normal);
+    assert_unchanged(&role_before);
+
+    let mut force_calls = 0;
+    let mut force_discover = |_requested: &str| {
+        force_calls += 1;
+        Ok(Vec::new())
+    };
+    let force = crate::lifecycle::add_agent_with_transport_force_pi_preflight(
+        &ws,
+        &aid("alpha"),
+        &role,
+        false,
+        None,
+        true,
+        &tx,
+        &mut force_discover,
+    )
+    .expect_err("invalid Pi replacement schema must fail before old-seat consumption");
+    drop(force_discover);
+    assert_eq!(force_calls, 0);
+    assert_schema_error(force);
+    assert_unchanged(&role_before);
+
+    std::fs::write(
+        &role,
+        CHARLIE_ROLE.replace(
+            "provider: codex\nmodel: gpt-5.5",
+            "provider: pi\nmodel: gpt-5.6-sol",
+        ),
+    )
+    .unwrap();
+    let model_role_before = std::fs::read(&role).unwrap();
+    let assert_model_diagnostic = |error: crate::lifecycle::LifecycleError| match error {
+        crate::lifecycle::LifecycleError::PiModelPreflight {
+            requested,
+            candidates,
+            not_ready,
+            ..
+        } => {
+            assert_eq!(requested, "gpt-5.6-sol");
+            assert_eq!(candidates, vec!["openai-codex/gpt-5.6-sol"]);
+            assert!(!not_ready);
+        }
+        other => panic!("expected typed Pi preflight error, got {other:?}"),
+    };
+    for (force, agent_id) in [(false, "charlie"), (true, "alpha")] {
+        let mut calls = 0;
+        let mut discover = |requested: &str| {
+            calls += 1;
+            assert_eq!(requested, "gpt-5.6-sol");
+            Ok(vec!["openai-codex/gpt-5.6-sol".into()])
+        };
+        let error = crate::lifecycle::add_agent_with_transport_force_pi_preflight(
+            &ws,
+            &aid(agent_id),
+            &role,
+            false,
+            None,
+            force,
+            &tx,
+            &mut discover,
+        )
+        .expect_err("unqualified Pi model must fail before mutation");
+        drop(discover);
+        assert_eq!(calls, 1);
+        assert_model_diagnostic(error);
+        assert_unchanged(&model_role_before);
+    }
+}

package/crates/team-agent/src/lifecycle/tests/launch_spawn.rs

@@ -375,6 +375,215 @@ fn quick_start_invalid_role_doc_surfaces_real_compile_error() {
     );
 }
 
+#[test]
+fn quick_start_absent_or_empty_roles_preserves_compile_outcome_without_pi_preflight_mutation() {
+    for (label, create_agents, expected) in [
+        ("absent", false, "missing agents directory"),
+        ("empty", true, "no role docs found"),
+    ] {
+        let team = temp_ws().join(format!("teamdir-{label}"));
+        std::fs::create_dir_all(&team).unwrap();
+        std::fs::write(team.join("TEAM.md"), QS_TEAM_MD).unwrap();
+        if create_agents {
+            std::fs::create_dir(team.join("agents")).unwrap();
+        }
+        let workspace = crate::model::paths::team_workspace(&team).unwrap();
+        let team_md_before = std::fs::read(team.join("TEAM.md")).unwrap();
+        let absent_paths = [
+            team.join("team.spec.yaml"),
+            crate::state::persist::runtime_state_path(&workspace),
+            crate::model::paths::runtime_spec_path(&workspace, "quickteam"),
+            workspace.join("team_state.md"),
+            workspace.join(".team/logs/events.jsonl"),
+            workspace.join(".team/runtime/team.db"),
+        ];
+        for path in &absent_paths {
+            assert!(!path.exists(), "precondition: {} must be absent", path.display());
+        }
+
+        let transport = OfflineTransport::new();
+        let mut calls = 0;
+        let mut discover = |_requested: &str| {
+            calls += 1;
+            Ok(Vec::new())
+        };
+        let error = quick_start_with_transport_in_workspace_with_display_pi_preflight(
+            &workspace,
+            &team,
+            None,
+            true,
+            None,
+            &transport,
+            true,
+            &mut discover,
+        )
+        .expect_err("an empty role input must preserve the existing compile outcome");
+        drop(discover);
+        assert_eq!(calls, 0, "{label} role input must not invoke Pi discovery");
+        match error {
+            LifecycleError::Compile(message) => {
+                assert!(message.contains(expected), "{label}: {message}");
+            }
+            other => panic!("{label}: expected existing compile outcome, got {other:?}"),
+        }
+        assert_eq!(team_md_before, std::fs::read(team.join("TEAM.md")).unwrap());
+        for path in &absent_paths {
+            assert!(!path.exists(), "{label} role input created {}", path.display());
+        }
+        assert!(transport.calls().is_empty(), "{label}: no transport mutation");
+        assert!(transport.spawn_records().is_empty(), "{label}: no spawn");
+    }
+}
+
+#[test]
+fn quick_start_injected_pi_preflight_is_typed_and_mutation_free() {
+    let role_doc = QS_VALID_ROLE.replace(
+        "provider: codex\nmodel: gpt-5.5",
+        "provider: pi\nmodel: gpt-5.6-sol",
+    );
+    let team = quick_start_team_dir(&role_doc);
+    let workspace = crate::model::paths::team_workspace(&team).unwrap();
+    let role_path = team.join("agents/implementer.md");
+    let team_md_path = team.join("TEAM.md");
+    let local_spec_path = team.join("team.spec.yaml");
+    let runtime_state_path = crate::state::persist::runtime_state_path(&workspace);
+    let runtime_spec_path = crate::model::paths::runtime_spec_path(&workspace, "quickteam");
+    let pi_paths = crate::lifecycle::launch::pi_mcp::pi_seat_paths(
+        &workspace,
+        "quickteam",
+        "implementer",
+    );
+    let role_before = std::fs::read(&role_path).unwrap();
+    let team_md_before = std::fs::read(&team_md_path).unwrap();
+    for path in [
+        &local_spec_path,
+        &runtime_state_path,
+        &runtime_spec_path,
+        &pi_paths.wrapper,
+        &pi_paths.sessions,
+    ] {
+        assert!(!path.exists(), "precondition: {} must be absent", path.display());
+    }
+
+    let transport = OfflineTransport::new();
+    let mut calls = 0;
+    let mut discover = |requested: &str| {
+        calls += 1;
+        assert_eq!(requested, "gpt-5.6-sol");
+        Ok(vec!["openai-codex/gpt-5.6-sol".into()])
+    };
+    let error = quick_start_with_transport_in_workspace_with_display_pi_preflight(
+        &workspace,
+        &team,
+        None,
+        true,
+        None,
+        &transport,
+        true,
+        &mut discover,
+    )
+    .expect_err("unqualified Pi role must fail before quick-start mutation");
+    drop(discover);
+    assert_eq!(calls, 1);
+    match error {
+        LifecycleError::PiModelPreflight {
+            requested,
+            candidates,
+            action,
+            not_ready,
+        } => {
+            assert_eq!(requested, "gpt-5.6-sol");
+            assert_eq!(candidates, vec!["openai-codex/gpt-5.6-sol"]);
+            assert_eq!(
+                action,
+                "copy a candidate into the role, or run `team-agent models --provider pi --search gpt-5.6-sol`"
+            );
+            assert!(!not_ready);
+        }
+        other => panic!("expected typed Pi preflight error, got {other:?}"),
+    }
+    assert_eq!(role_before, std::fs::read(&role_path).unwrap());
+    assert_eq!(team_md_before, std::fs::read(&team_md_path).unwrap());
+    for path in [
+        &local_spec_path,
+        &runtime_state_path,
+        &runtime_spec_path,
+        &pi_paths.wrapper,
+        &pi_paths.sessions,
+    ] {
+        assert!(!path.exists(), "quick-start preflight created {}", path.display());
+    }
+    assert!(transport.calls().is_empty(), "no transport calls before preflight rejection");
+    assert!(transport.spawn_records().is_empty());
+}
+
+#[test]
+fn quick_start_schema_invalid_pi_role_is_mutation_free() {
+    let role_doc = QS_VALID_ROLE
+        .replace(
+            "provider: codex\nmodel: gpt-5.5",
+            "provider: pi\nmodel: openai-codex/gpt-5.6-sol",
+        )
+        .replace("  - mcp_team", "  - fs_read");
+    let team = quick_start_team_dir(&role_doc);
+    let workspace = crate::model::paths::team_workspace(&team).unwrap();
+    let role_path = team.join("agents/implementer.md");
+    let team_md_path = team.join("TEAM.md");
+    let role_before = std::fs::read(&role_path).unwrap();
+    let team_md_before = std::fs::read(&team_md_path).unwrap();
+    let pi_paths = crate::lifecycle::launch::pi_mcp::pi_seat_paths(
+        &workspace,
+        "quickteam",
+        "implementer",
+    );
+    let absent_paths = [
+        team.join("team.spec.yaml"),
+        crate::state::persist::runtime_state_path(&workspace),
+        crate::model::paths::runtime_spec_path(&workspace, "quickteam"),
+        workspace.join("team_state.md"),
+        workspace.join(".team/logs/events.jsonl"),
+        workspace.join(".team/runtime/team.db"),
+        pi_paths.wrapper,
+        pi_paths.sessions,
+    ];
+    for path in &absent_paths {
+        assert!(!path.exists(), "precondition: {} must be absent", path.display());
+    }
+
+    let transport = OfflineTransport::new();
+    let mut calls = 0;
+    let mut discover = |_requested: &str| {
+        calls += 1;
+        Ok(Vec::new())
+    };
+    let error = quick_start_with_transport_in_workspace_with_display_pi_preflight(
+        &workspace,
+        &team,
+        None,
+        true,
+        None,
+        &transport,
+        true,
+        &mut discover,
+    )
+    .expect_err("invalid Pi schema must fail before quick-start mutation");
+    drop(discover);
+    assert_eq!(calls, 0, "qualified models must not invoke discovery");
+    match error {
+        LifecycleError::Compile(message) => {
+            assert!(message.contains("Pi roles require mcp_team"), "{message}");
+        }
+        other => panic!("expected Pi role schema error, got {other:?}"),
+    }
+    assert_eq!(role_before, std::fs::read(&role_path).unwrap());
+    assert_eq!(team_md_before, std::fs::read(&team_md_path).unwrap());
+    for path in &absent_paths {
+        assert!(!path.exists(), "schema preflight created {}", path.display());
+    }
+    assert!(transport.calls().is_empty(), "no transport calls before schema rejection");
+    assert!(transport.spawn_records().is_empty());
+}
+
 // P0 — launch (dry_run) over a real compiled spec must resolve the REAL route/permission plan
 // (no spawn) — NOT the hardcoded RequirementUnmet stub. Golden: launch/core.py dry_run resolves
 // routing + permissions without starting any process.

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

@@ -495,6 +495,14 @@ pub enum LifecycleError {
     /// 编译 spec / role doc 失败(`compile_team`/`compile_role_doc_agent`)。
     #[error("spec compile failed: {0}")]
     Compile(String),
+    /// Pi model/schema admission failed before lifecycle reservation or writes.
+    #[error("pi model preflight failed: {requested}")]
+    PiModelPreflight {
+        requested: String,
+        candidates: Vec<String>,
+        action: String,
+        not_ready: bool,
+    },
     /// provider 命令构造 / resume 不可用(`ResumeUnavailable`)。
     #[error("provider error: {0}")]
     Provider(String),

package/npm/check-skill-links.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/** Resolve local Markdown links and optionally validate package/installed inventories. */
+import fs from "node:fs";
+import path from "node:path";
+
+const args = process.argv.slice(2);
+const value = (name) => { const i = args.indexOf(name); return i < 0 ? null : args[i + 1]; };
+const rootArg = value("--root") ?? "skills/team-agent";
+const root = path.resolve(rootArg);
+const installedArg = value("--installed");
+const inventoryArg = value("--inventory");
+const markdownLink = /!?(?:\[[^\]]*\])\(([^)]+)\)/g;
+const files = [];
+const fail = (message) => { throw new Error(message); };
+const real = (file) => { try { return fs.realpathSync.native(file); } catch (error) { fail(`cannot resolve ${file}: ${error.message}`); } };
+const rootReal = real(root);
+const inside = (candidate, base = rootReal) => candidate === base || candidate.startsWith(`${base}${path.sep}`);
+const lexicalInside = (candidate, base = root) => candidate === base || candidate.startsWith(`${base}${path.sep}`);
+
+function walk(dir, boundary = rootReal) {
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)); }
+  catch (error) { fail(`cannot read ${dir}: ${error.message}`); }
+  for (const entry of entries) {
+    const file = path.join(dir, entry.name);
+    const fileReal = real(file);
+    if (!inside(fileReal, boundary)) fail(`${file}: realpath escapes tree`);
+    if (entry.isDirectory()) walk(file, boundary);
+    else if (entry.isFile() && file.endsWith(".md")) files.push(file);
+  }
+}
+function normalizeFragment(fragment) {
+  return decodeURIComponent(fragment).toLowerCase().trim().replace(/<[^>]+>/g, "")
+    .replace(/[`*_~]/g, "").replace(/[^\p{L}\p{N} -]/gu, "").replace(/\s+/g, "-");
+}
+function anchors(text) {
+  const found = new Set();
+  const used = new Map();
+  const add = (value) => {
+    const base = normalizeFragment(value); if (!base) return;
+    const n = used.get(base) ?? 0; used.set(base, n + 1); found.add(n ? `${base}-${n}` : base);
+  };
+  for (const m of text.matchAll(/^(?: {0,3})#{1,6}\s+(.+?)\s*#*\s*$/gm) ) add(m[1]);
+  for (const m of text.matchAll(/^(?: {0,3})([^\n#]+)\n(?:=+|-+)\s*$/gm)) add(m[1]);
+  for (const m of text.matchAll(/<(?:a|[^>]+)\s+[^>]*(?:id|name)=["']([^"']+)["'][^>]*>/gi)) add(m[1]);
+  return found;
+}
+function checkTree(dir, baseRoot, baseReal) {
+  files.length = 0; walk(dir, baseReal);
+  const errors = [];
+  for (const file of [...files].sort()) {
+    const text = fs.readFileSync(file, "utf8");
+    const known = anchors(text);
+    for (const match of text.matchAll(markdownLink)) {
+      const href = match[1].trim();
+      if (!href || /^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(href)) continue;
+      const hash = href.indexOf("#");
+      const rawPath = hash < 0 ? href : href.slice(0, hash);
+      const fragment = hash < 0 ? "" : href.slice(hash + 1).split("?", 1)[0];
+      const target = rawPath ? path.resolve(path.dirname(file), rawPath) : file;
+      if (!lexicalInside(target, baseRoot)) { errors.push(`${file}: lexical target escapes tree: ${href}`); continue; }
+      const targetReal = real(target);
+      if (!inside(targetReal, baseReal)) { errors.push(`${file}: realpath target escapes tree: ${href}`); continue; }
+      if (!fs.statSync(targetReal).isFile()) { errors.push(`${file}: target is not a file: ${href}`); continue; }
+      if (fragment && targetReal.endsWith(".md")) {
+        const targetAnchors = targetReal === real(file) ? known : anchors(fs.readFileSync(targetReal, "utf8"));
+        if (!targetAnchors.has(normalizeFragment(fragment))) errors.push(`${file}: missing fragment: ${href}`);
+      }
+    }
+  }
+  if (errors.length) fail(errors.sort().join("\n"));
+  return [...files].sort().length;
+}
+const count = checkTree(root, root, rootReal);
+if (inventoryArg) {
+  const inventory = path.resolve(inventoryArg);
+  for (const relative of fs.readFileSync(inventory, "utf8").split(/\r?\n/).filter(Boolean).sort()) {
+    if (path.isAbsolute(relative)) fail(`inventory path must be relative: ${relative}`);
+    const candidate = path.resolve(root, relative);
+    if (!lexicalInside(candidate)) fail(`inventory path escapes tree: ${relative}`);
+    const candidateReal = real(candidate);
+    if (!inside(candidateReal)) fail(`inventory realpath escapes tree: ${relative}`);
+  }
+}
+if (installedArg) {
+  const installed = path.resolve(installedArg); console.log(`checked ${checkTree(installed, installed, real(installed))} Markdown files in ${installed}`);
+}
+console.log(`checked ${count} Markdown files in ${root}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-agent/installer",
-  "version": "0.5.71",
+  "version": "0.5.72",
   "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.71",
-    "@team-agent/cli-darwin-x64": "0.5.71",
-    "@team-agent/cli-linux-x64": "0.5.71"
+    "@team-agent/cli-darwin-arm64": "0.5.72",
+    "@team-agent/cli-darwin-x64": "0.5.72",
+    "@team-agent/cli-linux-x64": "0.5.72"
   },
   "scripts": {
     "postinstall": "node npm/bincheck.mjs",
@@ -33,6 +33,7 @@
   "files": [
     "npm/bincheck.mjs",
     "npm/install.mjs",
+    "npm/check-skill-links.mjs",
     "skills",
     "templates",
     "examples",

package/skills/team-agent/SKILL.md

@@ -2,14 +2,14 @@
 name: team-agent
 description: Use only when the user explicitly asks to start, operate, inspect, shutdown, or restart a Team Agent team. Treat the team-agent CLI as a sealed appliance.
 requires_team_agent: ">=0.5.0"
-last_verified_against: "0.5.71"
+last_verified_against: "0.5.72"
 ---
 
 # Team Agent
 
-Sealed appliance for someone who just got the CLI. Operator handbook (permissions, models, routing, recovery): `docs/reference/team-agent-operator.md`.
+Use this skill only for Team Agent operation. The detailed operator handbook (permissions, models, routing, and recovery) is in [the operator reference](references/team-agent-operator.md). Nested teams have a separate [nested-team reference](references/team-in-team.md).
 
-If `team-agent --version` does not match `last_verified_against`, do not copy examples as current truth. Learn from the live CLI:
+If `team-agent --version` does not match `last_verified_against`, inspect the live CLI before copying examples:
 
 ```bash
 team-agent --version
@@ -17,55 +17,21 @@ team-agent --help
 team-agent doctor --help
 ```
 
-**Operate**
+## Pi TeamMate startup
 
-- Dispatch: `team-agent send TO MESSAGE` (positional TO; `--watch-result` is deprecated). After success, do not poll with `sleep` / `status` / `inbox` / `collect`.
-  TO has two co-equal logical forms: an **in-team short name** (`team-agent send reviewer "..."`) and a fully qualified `<workspace>::<team>/<agent>`. Use the qualified form across workspaces.
-- Inspect: `team-agent status` / `status --json`. `ok: true` plus `ready: false` is not a crash.
-- Lifecycle: `restart .` resumes a stopped team; `add-agent NAME --role-file FILE` adds or `--force` recreates one worker; `shutdown --workspace .` stops. Do not shutdown the whole team to add a worker.
-- Roles: every `agents/*.md` must declare boolean `dangerously_skip_permissions`. Never rewrite a user-supplied model id. Never read `.env` files.
+For a Pi worker, use this existing three-step flow:
 
-**On failure:** if the CLI prints a structured `action`, run that `action` first, then stop. Do not guess flags. `coordinator.session_missing` is a self-healing transient — re-check `status --json`; do not shutdown because of it.
+1. Discover exact model ids: `team-agent models --provider pi` (add `--search TEXT` when useful).
+2. Use the existing lifecycle command that matches the actual state: `team-agent quick-start` for a new team, `team-agent add-agent NAME --role-file FILE` for a new worker, or `team-agent start-agent NAME` for a missing worker.
+3. Send work through the canonical route: `team-agent send AGENT MESSAGE`.
 
-The current user-facing agent is the leader (orchestrate only). Workers call `report_result` exactly once. Nested teams: `skills/team-agent/references/team-in-team.md`.
+Pi roles preserve the direct Pi login, model defaults, extensions/plugins, skills, context, trust, and tools. Team Agent adds only per-seat identity/session isolation. `model` and `effort` are optional explicit pass-throughs. Use the shared role schema, a block-style `tools` list containing `mcp_team`, and the required boolean `dangerously_skip_permissions`.
 
-## Provider Capability Matrix
+## Operate
 
-Claude / Codex / Copilot / Gemini / fake: `docs/reference/team-agent-operator.md`. These two are in the runtime but were missing from that table:
+- Send: `team-agent send TO MESSAGE` using an in-team short name or fully qualified `<workspace>::<team>/<agent>`; these are co-equal positional TO forms. For example, `team-agent send reviewer "..."` uses an in-team short name. Do not poll after success.
+- Inspect: `team-agent status` or `team-agent status --json`; `ok: true` with `ready: false` is not a crash.
+- On a structured failure with an `action`, run that action first, then stop. Never guess flags.
+- Never rewrite a user-supplied model id or read `.env` files.
 
-| Provider | Resume | Turn-state detection | Per-worker model override | Native session fork |
-|---|---|---|---|---|
-| `grok` | yes (`--resume <id>`, archive-gated) | no | yes (role `model` required) | yes (`--fork-session` + new `--session-id`) |
-| `cursor_agent` | yes (argv `--resume <chatId>`, archive-gated) | no | required on role; same-family catalog id can take effect; unknown id silent-fallback; pane chrome ≠ proven live | **no — `CapabilityUnsupported`** |
-
-Grok / `cursor_agent` have no JSONL turn-state reader (classify → Unknown).
-
-## Provider Prep
-
-### Pi TeamMate roles
-
-Use the standard role schema with `provider: pi`, a block-style `tools` list containing `mcp_team`, and the required boolean `dangerously_skip_permissions`. That role boolean is the only bypass setting; `TEAM.md` `dangerous_auto_approve` is compatibility input, not a second user-facing switch.
-
-Pi TeamMates keep the same login, model, extensions/plugins, skills, context files, project trust, and tools as a direct `pi` run on that machine. Team Agent only appends the role contract, a per-seat Team MCP registration, and per-seat session storage; do not duplicate those direct Pi settings in the role. `model` and `effort` remain optional compatibility overrides, and explicit values are passed through.
-
-### Cursor provider notes
-
-Frontmatter: `provider: cursor_agent` (not `cursor`; launcher verb is `team-agent cursor`), `auth_mode: subscription`, `name:` required (omit → `missing front matter field name`). Also required: `role:`, `tools:`, `dangerously_skip_permissions:` (bool). Subscription needs no `profile`.
-
-`model:` is required (omit compile-fails; blocks a silent builtin `sonnet-4-thinking`). The flag stays on argv. Same-family catalog ids can change pane chrome. An id not in that provider's catalog silent-falls back (landing not stable; no events/stderr/pane warning). Pick names from the catalog; after spawn, `capture-pane` once for chrome. Do not treat the role field or pane chrome as proof of the live model.
-
-One `cursor_agent` per **provider-config overlay** under `<workspace>/.team/runtime/provider-config/<id>/cursor`. Same workspace may run multiple cursor seats; each writes `TEAM_AGENT_ID` into that project's `.cursor/mcp.json`. Spawn points `--workspace` there and `--add-dir` at the real workspace. `HOME` stays the user home. If isolation is off or cannot be materialized, adding a second seat still fail-closes:
-
-```
-error: cursor_agent seat already occupies this workspace
-reason: <workspace>/.cursor/mcp.json is directory-scoped; a second seat overwrites TEAM_AGENT_ID (last-writer)
-action: do not add another CursorAgent in this workspace until per-seat MCP identity is isolated
-```
-
-Do not share `<workspace>/.cursor/mcp.json` for team_orchestrator identity. Same seat, fresh context → `reset-agent --discard-session`.
-
-`clone-agent` copies the source role (provider unchanged). Runtime add: `clone-agent` → `stop-agent` → `remove-agent --confirm` (deletes `.team/dynamic-role-files/`) → write the role file → `add-agent --role-file` → dispatch.
-
-- Restart emits `--resume <chatId>` when `store.db`/`meta.json` exist; the gate does not read chat text. Persist anything that must survive restart.
-- Delivery sends one Enter; a second Enter interrupts the turn.
-- After spawn, the pane footer should show `Cursor Agent v<version>`. Do not use `strings` to probe the binary.
+Workers report completion through `mcp_team` and call `report_result` exactly once.

package/skills/team-agent/command-coverage.json

@@ -3,7 +3,7 @@
   "authority": {
     "kind": "normative_handbook_plus_live_help",
     "handbook": {
-      "path": "docs/reference/team-agent-operator.md",
+      "path": "skills/team-agent/references/team-agent-operator.md",
       "start_marker": "<!-- command-coverage:normative-start -->",
       "end_marker": "<!-- command-coverage:normative-end -->"
     },
@@ -336,6 +336,13 @@
       "owner": "runtime-owner:messaging",
       "plan": "Execute the compact-skill positional send smoke with representative target and message tokens, then bind delivery truth."
     },
+    {
+      "command": "team-agent send AGENT MESSAGE",
+      "bucket": "declared_gap",
+      "covered": false,
+      "owner": "runtime-owner:messaging",
+      "plan": "Execute a representative positional send with explicit agent and message tokens, then bind recipient and delivery truth."
+    },
     {
       "command": "team-agent send reviewer \"...\"",
       "bucket": "declared_gap",