@team-agent/installer 0.1.0

package/schemas/team.schema.json

@@ -0,0 +1,241 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://teamspec.local/schemas/team.schema.json",
+  "title": "TeamSpec Agent Mode team.spec.yaml",
+  "type": "object",
+  "required": ["version", "team", "leader", "agents", "routing", "communication", "runtime", "context", "tasks"],
+  "additionalProperties": false,
+  "properties": {
+    "version": { "const": 1 },
+    "team": {
+      "type": "object",
+      "required": ["name", "mode", "objective", "workspace"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "mode": { "enum": ["supervisor_worker", "swarm_limited"] },
+        "objective": { "type": "string", "minLength": 1 },
+        "workspace": { "type": "string", "minLength": 1 }
+      }
+    },
+    "leader": { "$ref": "#/$defs/leader" },
+    "agents": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/agent" }
+    },
+    "routing": {
+      "type": "object",
+      "required": ["default_assignee", "rules"],
+      "additionalProperties": false,
+      "properties": {
+        "default_assignee": { "type": "string" },
+        "rules": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/routingRule" }
+        }
+      }
+    },
+    "communication": {
+      "type": "object",
+      "required": ["protocol", "topology", "worker_to_worker", "ack_timeout_sec", "result_format", "message_store"],
+      "additionalProperties": false,
+      "properties": {
+        "protocol": { "enum": ["mcp_inbox", "file_bus"] },
+        "topology": { "enum": ["leader_centered"] },
+        "worker_to_worker": { "type": "boolean" },
+        "ack_timeout_sec": { "type": "integer", "minimum": 1 },
+        "result_format": { "const": "result_envelope_v1" },
+        "message_store": {
+          "type": "object",
+          "required": ["sqlite", "mirror_files"],
+          "additionalProperties": false,
+          "properties": {
+            "sqlite": { "type": "string" },
+            "mirror_files": { "type": "string" }
+          }
+        }
+      }
+    },
+    "runtime": {
+      "type": "object",
+      "required": ["backend", "display_backend", "session_name", "auto_launch", "require_user_approval_before_launch", "max_active_agents", "startup_order"],
+      "additionalProperties": false,
+      "properties": {
+        "backend": { "enum": ["tmux", "pty"] },
+        "display_backend": { "enum": ["none", "tmux_attach", "iterm", "ghostty"] },
+        "session_name": { "type": "string", "minLength": 1 },
+        "auto_launch": { "type": "boolean" },
+        "require_user_approval_before_launch": { "type": "boolean" },
+        "dangerous_auto_approve": { "type": "boolean" },
+        "max_active_agents": { "type": "integer", "minimum": 1 },
+        "startup_order": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "context": {
+      "type": "object",
+      "required": ["state_file", "artifact_dir", "log_dir", "summarization"],
+      "additionalProperties": false,
+      "properties": {
+        "state_file": { "type": "string" },
+        "artifact_dir": { "type": "string" },
+        "log_dir": { "type": "string" },
+        "summarization": {
+          "type": "object",
+          "required": ["worker_full_logs", "state_update"],
+          "additionalProperties": false,
+          "properties": {
+            "worker_full_logs": { "enum": ["retain_outside_leader_context"] },
+            "state_update": { "enum": ["after_each_result", "manual"] }
+          }
+        }
+      }
+    },
+    "tasks": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/task" }
+    }
+  },
+  "$defs": {
+    "leader": {
+      "type": "object",
+      "required": ["id", "role", "provider", "model", "tools", "context_policy"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "role": { "type": "string", "minLength": 1 },
+        "provider": { "type": "string", "minLength": 1 },
+        "model": { "type": ["string", "null"] },
+        "tools": { "$ref": "#/$defs/tools" },
+        "context_policy": {
+          "type": "object",
+          "required": ["keep_user_thread", "receive_worker_outputs", "max_worker_result_tokens"],
+          "additionalProperties": false,
+          "properties": {
+            "keep_user_thread": { "type": "boolean" },
+            "receive_worker_outputs": { "enum": ["summary_only", "structured_only", "full_on_request"] },
+            "max_worker_result_tokens": { "type": "integer", "minimum": 1 }
+          }
+        }
+      }
+    },
+    "agent": {
+      "type": "object",
+      "required": ["id", "role", "provider", "model", "working_directory", "system_prompt", "tools", "permission_mode", "preferred_for", "avoid_for", "output_contract"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "role": { "type": "string", "minLength": 1 },
+        "provider": { "type": "string", "minLength": 1 },
+        "model": { "type": ["string", "null"] },
+        "auth_mode": { "enum": ["subscription", "official_api", "compatible_api"] },
+        "profile": { "type": "string", "minLength": 1 },
+        "credential_ref": { "type": "string", "minLength": 1 },
+        "working_directory": { "type": "string", "minLength": 1 },
+        "paused": { "type": "boolean" },
+        "system_prompt": {
+          "type": "object",
+          "required": ["inline", "file"],
+          "additionalProperties": false,
+          "properties": {
+            "inline": { "type": ["string", "null"] },
+            "file": { "type": ["string", "null"] }
+          }
+        },
+        "tools": { "$ref": "#/$defs/tools" },
+        "permission_mode": { "enum": ["restricted", "ask", "trusted"] },
+        "preferred_for": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "avoid_for": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "output_contract": {
+          "type": "object",
+          "required": ["format", "required_fields"],
+          "additionalProperties": false,
+          "properties": {
+            "format": { "const": "result_envelope_v1" },
+            "required_fields": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "routingRule": {
+      "type": "object",
+      "required": ["id", "assign_to", "priority"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string" },
+        "when": { "type": "string" },
+        "match": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "type": { "$ref": "#/$defs/stringOrList" },
+            "files": { "$ref": "#/$defs/stringOrList" },
+            "risk": { "$ref": "#/$defs/stringOrList" },
+            "requires_tools": { "$ref": "#/$defs/stringOrList" }
+          }
+        },
+        "assign_to": { "type": "string" },
+        "priority": { "type": "integer" }
+      },
+      "anyOf": [
+        { "required": ["when"] },
+        { "required": ["match"] }
+      ]
+    },
+    "task": {
+      "type": "object",
+      "required": ["id", "title", "type", "assignee", "deps", "acceptance", "status"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "title": { "type": "string", "minLength": 1 },
+        "description": { "type": "string" },
+        "type": { "type": "string", "minLength": 1 },
+        "assignee": { "type": ["string", "null"] },
+        "deps": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "acceptance": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "status": { "enum": ["pending", "ready", "running", "blocked", "needs_retry", "done", "failed", "cancelled"] },
+        "requires_tools": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "files": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "risk": { "enum": ["low", "medium", "high"] },
+        "retry_limit": { "type": "integer", "minimum": 0 },
+        "human_confirmation": { "type": "boolean" }
+      }
+    },
+    "tools": {
+      "type": "array",
+      "items": { "type": "string" },
+      "uniqueItems": true
+    },
+    "stringOrList": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "array", "items": { "type": "string" } }
+      ]
+    }
+  }
+}

package/scripts/install.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import argparse
+import glob
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Install local team-agent wrapper commands")
+    parser.add_argument("--prefix", default=str(Path.home() / ".local"), help="Install prefix; bin/ is created under it")
+    parser.add_argument("--python", help="Python executable to embed in wrappers; defaults to TEAM_AGENT_PYTHON, python3, then python")
+    args = parser.parse_args()
+    repo = Path(__file__).resolve().parents[1]
+    python = _resolve_python(args.python)
+    bin_dir = Path(args.prefix) / "bin"
+    bin_dir.mkdir(parents=True, exist_ok=True)
+    _write_wrapper(bin_dir / "team-agent", repo, "team_agent", python)
+    _write_wrapper(bin_dir / "team_orchestrator", repo, "team_agent.mcp_server", python)
+    _write_wrapper(bin_dir / "team-agent-coordinator", repo, "team_agent.coordinator", python)
+    print(f"installed: {bin_dir / 'team-agent'}")
+    print(f"installed: {bin_dir / 'team_orchestrator'}")
+    print(f"installed: {bin_dir / 'team-agent-coordinator'}")
+    print(f"python: {python}")
+    print(f"ensure PATH contains: {bin_dir}")
+
+
+def _resolve_python(explicit: str | None) -> str:
+    candidates = _python_candidates(explicit)
+    for candidate in candidates:
+        if not candidate:
+            continue
+        resolved = shutil.which(candidate) if os.path.basename(candidate) == candidate else candidate
+        if not resolved:
+            continue
+        proc = subprocess.run(
+            [
+                resolved,
+                "-c",
+                "import sys; raise SystemExit(0 if sys.version_info >= (3, 10) else 1)",
+            ],
+            text=True,
+            capture_output=True,
+            check=False,
+        )
+        if proc.returncode == 0:
+            return resolved
+    raise SystemExit("No usable Python >= 3.10 found. Set TEAM_AGENT_PYTHON or pass --python.")
+
+
+def _python_candidates(explicit: str | None) -> list[str]:
+    candidates = [
+        explicit,
+        os.environ.get("TEAM_AGENT_PYTHON"),
+        "python3",
+        "python",
+        "/opt/homebrew/bin/python3",
+        "/usr/local/bin/python3",
+        "/usr/bin/python3",
+        "/opt/homebrew/opt/python@3/bin/python3",
+        "/usr/local/opt/python@3/bin/python3",
+    ]
+    candidates.extend(glob.glob("/opt/homebrew/opt/python@*/bin/python3*"))
+    candidates.extend(glob.glob("/usr/local/opt/python@*/bin/python3*"))
+    seen: set[str] = set()
+    result: list[str] = []
+    for item in candidates:
+        if not item or item in seen:
+            continue
+        seen.add(item)
+        result.append(item)
+    return result
+
+
+def _write_wrapper(path: Path, repo: Path, module: str, python: str) -> None:
+    path.write_text(
+        "#!/usr/bin/env sh\n"
+        f'PYTHON_BIN="${{TEAM_AGENT_PYTHON:-{python}}}"\n'
+        f'PYTHONPATH="{repo / "src"}" exec "$PYTHON_BIN" -m {module} "$@"\n',
+        encoding="utf-8",
+    )
+    path.chmod(path.stat().st_mode | 0o755)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/run_regression_tests.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+REGRESSION_TESTS = [
+    "tests.run_tests.RuntimeTests.test_send_default_timeout_reports_submitted_unverified",
+    "tests.run_tests.RuntimeTests.test_worker_delivery_retries_paste_until_message_ready",
+    "tests.run_tests.RuntimeTests.test_worker_pasted_content_prompt_retries_enter_until_submitted",
+    "tests.run_tests.RuntimeTests.test_worker_pasted_content_prompt_reports_unverified_when_enter_does_not_submit",
+    "tests.run_tests.RuntimeTests.test_delivery_claim_prevents_duplicate_worker_injection",
+    "tests.run_tests.RuntimeTests.test_approvals_returns_structured_prompt_without_terminal_page",
+    "tests.run_tests.RuntimeTests.test_coordinator_auto_approves_internal_mcp_prompt_with_retry_verification",
+    "tests.run_tests.RuntimeTests.test_coordinator_auto_approves_claude_internal_mcp_prompt",
+    "tests.run_tests.RuntimeTests.test_stale_approval_prompt_in_scrollback_is_not_current_approval",
+    "tests.run_tests.RuntimeTests.test_ghostty_display_session_is_linked_and_window_selected",
+    "tests.run_tests.RuntimeTests.test_shutdown_closes_ghostty_display_session_before_base_session_without_pid",
+    "tests.run_tests.RuntimeTests.test_restart_resumes_known_sessions_and_fresh_spawns_missing_sessions",
+    "tests.run_tests.RuntimeTests.test_restart_first_resume_exit_fallback_recreates_session_and_opens_display",
+    "tests.run_tests.RuntimeTests.test_start_agent_repairs_missing_worker_window_without_restart",
+    "tests.run_tests.RuntimeTests.test_start_agent_falls_back_to_fresh_when_resume_window_exits",
+    "tests.run_tests.RuntimeTests.test_broadcast_sends_only_to_current_team_and_excludes_sender",
+    "tests.run_tests.RuntimeTests.test_status_and_collect_expose_uncollected_report_result",
+    "tests.run_tests.RuntimeTests.test_report_result_queues_leader_notification_without_blocking_mcp",
+    "tests.run_tests.RuntimeTests.test_mcp_send_message_accepts_thin_args_and_returns_compact_result",
+    "tests.run_tests.RuntimeTests.test_mcp_send_message_accepts_broadcast_target",
+    "tests.run_tests.RuntimeTests.test_mcp_send_message_without_env_infers_worker_before_leader_send",
+    "tests.run_tests.RuntimeTests.test_mcp_report_result_without_env_infers_task_and_agent",
+    "tests.run_tests.RuntimeTests.test_mcp_report_result_normalizes_common_loose_shapes",
+    "tests.run_tests.RuntimeTests.test_compile_system_prompt_prepends_teammate_runtime_contract",
+    "tests.run_tests.RuntimeTests.test_codex_default_command_avoids_dangerous_bypass",
+    "tests.run_tests.RuntimeTests.test_launch_inherits_leader_dangerous_permissions_in_dry_run",
+    "tests.run_tests.RuntimeTests.test_launch_passes_inherited_dangerous_permissions_to_worker_runtime",
+    "tests.run_tests.RuntimeTests.test_restart_passes_inherited_dangerous_permissions_to_resume_and_fresh_workers",
+    "tests.run_tests.RuntimeTests.test_quick_start_refuses_to_overwrite_existing_context_without_fresh",
+    "tests.run_tests.RuntimeTests.test_quick_start_team_id_stores_loose_docs_outside_current",
+    "tests.run_tests.RuntimeTests.test_start_writes_compiled_spec_inside_selected_team_dir",
+    "tests.run_tests.RuntimeTests.test_preflight_uses_selected_team_profile_dir_not_current",
+    "tests.run_tests.RuntimeTests.test_restart_requires_team_selector_when_multiple_snapshots_exist",
+    "tests.run_tests.RuntimeTests.test_leader_start_plan_creates_tmux_session_outside_tmux_and_passes_args",
+    "tests.run_tests.RuntimeTests.test_leader_start_plan_inside_tmux_execs_provider_in_current_pane",
+    "tests.run_tests.RuntimeTests.test_launch_requires_current_tmux_leader_for_real_workers",
+    "tests.run_tests.RuntimeTests.test_resolve_leader_scans_workspace_when_tool_shell_has_wrong_tmux_client",
+    "tests.run_tests.RuntimeTests.test_resolve_leader_reports_ambiguous_workspace_panes",
+    "tests.run_tests.CliContractTests.test_leader_commands_pass_provider_flags_without_argparse_consuming_them",
+    "tests.run_tests.CliContractTests.test_npx_installer_installs_runtime_wrappers_and_skills",
+    "tests.run_tests.CliContractTests.test_skill_blackbox_lint",
+]
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Run the fixed Team Agent regression asset.")
+    parser.add_argument("--iterations", type=int, default=1, help="repeat the regression batch N times")
+    parser.add_argument("--list", action="store_true", help="print the selected unittest ids and exit")
+    args = parser.parse_args()
+    if args.iterations < 1:
+        parser.error("--iterations must be >= 1")
+    if args.list:
+        print("\n".join(REGRESSION_TESTS))
+        return 0
+
+    repo = Path(__file__).resolve().parents[1]
+    env = os.environ.copy()
+    env["PYTHONPATH"] = str(repo / "src") + os.pathsep + env.get("PYTHONPATH", "")
+    for index in range(1, args.iterations + 1):
+        print(f"[team-agent-regression] iteration {index}/{args.iterations}", flush=True)
+        proc = subprocess.run([sys.executable, "-m", "unittest", *REGRESSION_TESTS], cwd=repo, env=env, check=False)
+        if proc.returncode != 0:
+            return proc.returncode
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/team-agent/SKILL.md

@@ -0,0 +1,173 @@
+---
+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.
+---
+
+# Team Agent
+
+Use this skill only for Team Agent operation. The leader is the current user-facing agent; do not create a `leader` worker. Worker role docs live in `<workspace>/agents/`; `TEAM.md` lives at `<workspace>/TEAM.md`.
+
+## Leader Requirement
+
+Real Team Agent teams require the current leader to run inside a tmux-managed pane. Prefer the short launchers:
+
+```bash
+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.
+
+## Minimal Copy-Paste Team
+
+```bash
+mkdir -p .team/current/agents
+cat > .team/current/TEAM.md <<'EOF'
+---
+name: demo-team
+objective: One worker handles bounded tasks and reports through Team Agent MCP.
+dangerous_auto_approve: false
+display_backend: ghostty_window
+fast: false
+provider_models:
+  codex: gpt-5.5
+  claude: claude-sonnet-4-6
+  claude_code: claude-sonnet-4-6
+---
+
+Team config only. This is not a worker role.
+EOF
+cat > .team/current/agents/coder.md <<'EOF'
+---
+name: coder
+role: Implementation Worker
+provider: codex
+auth_mode: subscription
+profile: codex-default
+tools:
+  - fs_read
+  - fs_list
+  - fs_write
+  - execute_bash
+  - mcp_team
+  - provider_builtin
+---
+
+Handle one bounded task at a time. Send progress to leader only when needed. Final completion must call report_result exactly once; MCP fills task ids and result envelope fields.
+EOF
+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]`.
+Omitting `display_backend` defaults to `ghostty_window`; set `display_backend: none` only for headless/CI runs.
+
+## Provider Prep
+
+Codex: run `codex login` first. Optional `~/.codex/config.toml` profile:
+
+```toml
+[profiles.team-agent]
+model = "gpt-5.5"
+approval_policy = "on-request"
+sandbox_mode = "workspace-write"
+```
+
+Use exact provider model ids, not display names. For Codex workers, the model must match a `slug` from `codex debug models`; for example use `gpt-5.3-codex-spark`, not `GPT-5.3-Codex-Spark`.
+Role docs may omit `model` for subscription workers. Team Agent fills subscription defaults from `TEAM.md` `provider_models`, then built-in provider defaults (`codex: gpt-5.5`, `claude/claude_code: claude-sonnet-4-6`). Use role-level `model` only for intentional per-worker overrides.
+
+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.
+
+If the current leader process was started with `claude --dangerously-skip-permissions` or `codex --dangerously-bypass-approvals-and-sandbox`, Team Agent inherits that permission mode for worker launch, restart, and single-agent repair.
+Role `profile` values are secret-safe references. Do not put API keys in role docs or `TEAM.md`.
+Never read raw provider profile files into model context. Do not use `Read`, `cat`, `sed`, `grep`, editors, or screenshots on `.team/current/profiles/*.env` or `.team/runtime/provider-env/*.env`. Those files may contain live API keys. Use only `team-agent profile show <name> --workspace . --json` or `team-agent profile doctor <name> --workspace . --json` for redacted diagnostics; if a value is missing, ask the human user to edit the local profile file.
+When the user asks for a third-party or compatible API, do not ask them to paste keys into the chat. Generate a local blank profile instead, for example:
+
+```bash
+team-agent profile init deepseek --auth-mode compatible_api --workspace .
+```
+
+Tell the user to fill `.team/current/profiles/deepseek.env` locally:
+
+```env
+AUTH_MODE=compatible_api
+PROFILE_NAME=deepseek
+BASE_URL=
+API_KEY=
+MODEL=
+```
+
+Then reference only `auth_mode: compatible_api` and `profile: deepseek` in role docs. Do not invent or duplicate a role `model` when the profile already has `MODEL=`; if both places define a model they must match exactly. Team Agent loads the profile automatically during quick-start, launch, restart, and start-agent. Compatible API workers inherit the current shell proxy/CA environment by default. Claude compatible API workers use Team Agent managed `CLAUDE_CONFIG_DIR` so user-level Claude subscription settings cannot re-inject Anthropic proxy variables into third-party API sessions. If quick-start reports an ambient proxy blocker, do not silently unset proxy for the whole team; tell the user to choose one path: fix that proxy for `BASE_URL`, put `HTTPS_PROXY=`/`HTTP_PROXY=` in the profile, or put `PROXY_MODE=direct` in the profile to bypass proxy only for that worker. Subscription workers keep their native provider settings and environment. Startup runs a redacted smoke check for compatible API profiles before worker windows are created, so a bad URL/key/model or proxy/base URL connectivity failure is reported to the leader command instead of producing idle workers.
+For diagnosis, run `team-agent profile show deepseek --workspace . --json`; never open the `.env` file to check whether `API_KEY` or `MODEL` is filled.
+
+## Commands
+
+- `team-agent codex ...` starts or attaches a tmux-managed Codex leader in the current directory; arguments after `codex` pass through to Codex.
+- `team-agent claude ...` starts or attaches a tmux-managed Claude leader in the current directory; arguments after `claude` pass through to Claude.
+- `team-agent quick-start .team/current` starts workers from `TEAM.md` and `agents/*.md`. When it prints `ready:` and `ready_signal`, startup is complete; do not run sleep/status/wait loops afterward unless diagnosing a failure.
+- For real workers, `quick-start` requires a current tmux leader pane. If it says the leader must run inside tmux, restart the leader with `team-agent codex`/`team-agent claude` or use an existing tmux-managed layout, then run quick-start again.
+- Quick-start generated files stay inside the selected team directory, for example `.team/current/` or `.team/alpha/`; do not create or expect root `team.spec.yaml` or `team_state.md`.
+- Use `team-agent quick-start ./roles --team-id alpha` to create a second generated team under `.team/alpha/`, or pass an existing team directory directly such as `team-agent quick-start .team/alpha`.
+- `quick-start` is for fresh startup from role docs. If stored worker context already exists for that runtime session, follow the returned `team-agent restart . --team <session>` action to resume it. Use `--fresh` only when the user explicitly accepts new blank worker contexts.
+- `team-agent send --watch-result coder "Do the bounded task"` sends a direct worker message, returns after delivery, and lets the coordinator collect/report completion asynchronously.
+- After `send --watch-result` succeeds, do not run `sleep`, `status`, `inbox`, or `collect` polling loops unless the user explicitly asks for diagnosis; the coordinator will notify the leader when the result arrives.
+- `team-agent send --task task_initial "Start"` routes by task.
+- `team-agent status` shows team, worker health, result-store counts, `session_id`, `captured_via`, and attribution confidence.
+- `team-agent status coder` shows one worker.
+- `team-agent approvals [coder]` shows structured pending approval prompts without copying worker terminal pages.
+- `team-agent inbox coder` shows message history only. Final results are not in inbox.
+- `team-agent shutdown --workspace . --keep-logs` stops the tmux session after a final session capture attempt.
+- `team-agent restart .` restarts a stopped team from stored worker sessions. If one workspace has multiple restartable teams, use `team-agent restart . --team <session_name_or_team_name>`.
+- `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.
+
+## Restart Semantics
+
+`restart` takes one workspace argument. It preserves each worker's original provider. If a verified provider session exists, the worker resumes (`codex resume <id>` or `claude --resume <id>`). Claude sessions are considered resumable only after the provider has written a project transcript for that session; a freshly opened blank Claude window is not recorded as recovered context. If the stored id is stale, the runtime first tries to repair it from verified transcript history. If a stored session cannot be verified or repaired, restart fails closed instead of silently losing context; use `team-agent restart . --allow-fresh` only when the user explicitly accepts a fresh worker context. If multiple stopped teams in the same workspace have restart context, plain `team-agent restart .` fails and lists candidates; rerun with `--team <session_name_or_team_name>`. If no prior session id exists, that worker starts fresh and the event log records `restart.fresh_spawn`. Claude resume must run from the original cwd and the same provider transcript root; Team Agent stores `spawn_cwd` and compatible-API `claude_projects_root` for that.
+
+Startup trust prompts are handled by the runtime/coordinator with bounded probes; do not wait on raw worker screens or manually press Enter for routine startup trust prompts.
+
+Use `team-agent start-agent <agent_id> --workspace .` only as a narrow repair when one worker window is missing after launch/restart/display failure. It preserves the worker provider, resumes from `session_id` when available, starts fresh when there is no prior session id, and does not restart the rest of the team. If an existing session id cannot resume, it fails closed unless the user explicitly passes `--allow-fresh`. To change the team, edit role docs and start a new team or regenerate the compiled spec.
+
+## Worker Protocol
+
+Workers do not run nested Team Agent teams. Workers only provide the target and content for progress, and a short completion summary at the end:
+
+```text
+team_orchestrator.send_message(to="leader", content="short progress or blocker")
+# to another teammate:
+team_orchestrator.send_message(to="<agent_id>", content="short coordination note")
+# to every other team member:
+team_orchestrator.send_message(to="*", content="short broadcast")
+team_orchestrator.report_result(summary="short completion", status="success", tests=[{"command":"command","status":"passed"}])
+```
+
+Do not pass `sender`, `task_id`, `requires_ack`, `schema_version`, or `agent_id` unless doing a low-level compatibility diagnostic. The MCP runtime fills those fields and keeps delivery metadata in runtime state and event logs. If provider env loses the worker id, MCP infers it from active task/message state and falls back to an explicit `unknown` sender instead of treating the worker as leader.
+
+Message targets are team-scoped. Use `leader`, another teammate agent id, or `*` for all other team members. The runtime excludes the sender from `*` broadcasts and never scans unrelated terminal windows for recipients.
+
+`report_result` stores final completion and immediately attempts a leader notification through the verified/fallback delivery path. `team-agent collect` remains the authoritative state-update path. Do not wait for final results through `team-agent inbox`, message ack counts, or repeated plain status polling. `acknowledged_count` only means prior task messages were acknowledged by the worker; it is not a missing-result signal.
+For normal leader dispatch, prefer `team-agent send --watch-result ...`; when it returns a registered watcher notice, the framework will notify the leader at completion.
+
+For long processes, workers must write logs, keep a pid, provide a health check, and stop after a bounded number of retries. QA/reviewer roles must stay within their authorized files and stop on service unavailable, approval prompts, or repeated startup failure.
+
+## Failure Rules
+
+For any non-zero `team-agent` exit, report the command, exit code, last about 20 stderr lines, and affected task or agent when known. Then stop and wait for the user.
+
+Do not retry with changed flags. Do not inspect source code or private runtime state. Do not operate tmux directly except when the user asks for a manual diagnostic. Do not answer provider approval prompts for the user.
+
+If `quick-start` reports `tmux session already exists`, treat it as a team-name collision. The existing session may be an active team; do not terminate it and do not suggest `shutdown` as the normal fix. Change `name:` in `TEAM.md` so the next launch uses a different tmux session name, then run `team-agent quick-start .team/current` again.
+
+Known Team Agent control-plane MCP prompts such as `team_orchestrator.report_result` and `team_orchestrator.send_message` are handled by the coordinator. It uses session-scoped approval, verifies the prompt cleared, retries boundedly, and logs the result. Do not ask the user to approve those routine internal prompts.
+
+When `status` still shows `AWAITING_APPROVAL`, run `team-agent approvals <agent_id>`, show the structured prompt summary and choices, ask the user to decide, and wait.
+
+Do not inspect raw worker terminal output during normal operation. Use `team-agent status`, `team-agent approvals`, `team-agent inbox`, `team-agent collect`, and event logs instead. Raw-screen diagnostics are outside this skill's normal workflow, require explicit user authorization, and are guarded by the CLI; use them only as a one-shot bounded diagnostic, never as a routine workflow step.
+
+For "worker reported but leader cannot see completion":
+
+1. Run `team-agent collect` once; this is the final-result intake path.
+2. If no result is collected, inspect `team-agent status --json` field `results`. `uncollected > 0` means the result is already accepted by MCP and waiting in the result store.
+3. Check `.team/logs/events.jsonl` for `mcp.report_result` and `collect.result` before sending another prompt to the worker.
+4. Do not loop on `team-agent inbox` or ack/status counts; that burns context and cannot consume final results.

package/src/team_agent/__init__.py

@@ -0,0 +1,3 @@
+"""TeamSpec Agent Mode runtime."""
+
+__version__ = "0.1.0"

package/src/team_agent/__main__.py

@@ -0,0 +1,5 @@
+from team_agent.cli import main
+
+
+if __name__ == "__main__":
+    main()