@team-agent/installer 0.5.99 → 0.5.101

package/skills/team-agent/SKILL.md

@@ -4,65 +4,36 @@ description: Use only when the user explicitly asks to start, operate, inspect,
 requires_team_agent: ">=0.5.0"
 last_verified_against: "0.5.66"
 ---
-
 # Team Agent
-
 Sealed appliance for someone who just got the CLI. Operator handbook (permissions, models, routing, recovery): `references/team-agent-operator.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` differs from `last_verified_against`, learn from the live CLI before copying examples:
 ```bash
 team-agent --version
 team-agent --help
 team-agent doctor --help
 ```
-
-**Launch** from a tmux-addressable pane: `team-agent claude` or `team-agent codex`, then `team-agent quick-start .team/current`. Do not start a real team from a naked terminal. Workers always run in independent background windows on the workspace-scoped tmux server.
-
+**Launch** from a tmux-addressable pane: `team-agent claude` or `team-agent codex`, then `team-agent quick-start .team/current`. Do not start a real team from a naked terminal; workers use independent background windows on the workspace-scoped tmux server.
 **Operate**
-
-- 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.
-
-**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.
-
+- 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 team to add a worker.
+- Roles: every `agents/*.md` must declare boolean `dangerously_skip_permissions`. Never rewrite user-supplied model ids or read `.env` files.
+- On a structured failure `action`, run that action first, then stop. Do not guess flags. `coordinator.session_missing` is self-healing; re-check `status --json`, do not shutdown.
 The current user-facing agent is the leader (orchestrate only). Workers call `report_result` exactly once. Nested teams: `references/team-in-team.md`.
-
 ## Provider Capability Matrix
-
-Claude / Codex / Copilot / Gemini / fake: `references/team-agent-operator.md`. These two are in the runtime but were missing from that table:
-`quick-start` / `restart` / `claim-leader` JSON is compact by default (`ok`, `status`/`reason`, next action, attach/send, and `readiness.all_workers_spawned`); pass `--detail` only for internal diagnostics.
-
-| Provider | Resume | Turn-state detection | Per-worker model override | Native session fork |
+See `references/team-agent-operator.md` for Claude / Codex / Copilot / Gemini / fake. `quick-start` / `restart` / `claim-leader` JSON is compact by default; pass `--detail` only for internal diagnostics.
+| Provider | Resume | Turn-state detection | Per-worker model override | Team Agent 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).
-
+| `cursor_agent` | yes (`--resume <chatId>`, archive-gated) | no | required on role; same-family catalog id may take effect; unknown id silent-fallback; pane chrome ≠ proof | **no — `CapabilityUnsupported`** |
+| `pi` | yes (exact `--session <backing-path>`, not selector/continue) | Unknown (no JSONL turn-state reader) | yes (role `model` / `effort`, catalog-validated) | yes (full snapshot into separate seat/session; exact backing resume) |
+Grok / `cursor_agent` have no JSONL turn-state reader (classify → Unknown). Pi `fork-agent SOURCE --as TARGET` requires a captured Pi subscription source and reports both session ids plus the target backing path; it does not mutate the source session.
 ## Provider Prep
-
 ### 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 workspace. A second seat (including `add-agent --force` of a different id) 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
-```
-
-Several cursor seats → one workspace directory each. 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.
+Frontmatter: `provider: cursor_agent` (not `cursor`; launcher verb `team-agent cursor`), `auth_mode: subscription`, `name:` required, plus `role:`, `tools:`, and boolean `dangerously_skip_permissions:`. Subscription needs no `profile`.
+`model:` is required. The flag stays on argv; same-family catalog ids can change pane chrome, while unknown ids silent-fallback without warning. Pick a catalog id; after spawn, `capture-pane` once for chrome. The role field and pane chrome do not prove the live model.
+One `cursor_agent` per workspace; a second seat fail-closes because `.cursor/mcp.json` is directory-scoped and overwrites `TEAM_AGENT_ID`. Several Cursor seats need separate workspace directories. Same seat, fresh context: `reset-agent --discard-session`.
+`clone-agent` copies the source role but starts fresh. Runtime role replacement: `clone-agent` → `stop-agent` → `remove-agent --confirm` (deletes `.team/dynamic-role-files/`) → write 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.

package/skills/team-agent/references/recovery-runbook.md

@@ -157,10 +157,10 @@ Resume/repair:
 team-agent restart "$WORKSPACE" --team "$TEAM" --json
 ```
 
-For a single worker where the leader has explicitly selected that worker:
+A single-worker clean-context reset is not a resume operation. Only after the user explicitly approves discarding that worker's session, use:
 
 ```bash
-team-agent restart-agent "$AGENT_ID" --workspace "$WORKSPACE" --team "$TEAM" --json
+team-agent reset-agent "$AGENT_ID" --workspace "$WORKSPACE" --team "$TEAM" --discard-session --json
 ```
 
 Validate:

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

@@ -122,11 +122,12 @@ Run `claim-leader` only from the **leader** pane. From a worker pane it refuses
 
 ## Provider Capability Matrix
 
-| Provider | Resume | Turn-state detection | Per-worker model override | Native session fork |
+| Provider | Resume | Turn-state detection | Per-worker model override | Team Agent fork |
 |---|---|---|---|---|
 | `claude` / `claude_code` | yes (`--resume <id>`, transcript-verified) | yes (JSONL stream) | yes (role `model` overrides `provider_models`) | yes (snapshot copy + only `--resume <snapshot-id>`) |
 | `codex` | yes (`codex resume <id>`, session-store-verified) | yes (turn JSONL) | yes (role `model`) | yes (`codex fork`) |
 | `copilot` | yes (`copilot --resume <id|name>`, sqlite `sessions` row) | not yet (phase 1: `provider.classify.unsupported` event) | yes (role `model`) | yes (isolated `COPILOT_HOME` store fork) |
+| `pi` | yes (exact `--session <backing-path>`, not selector/continue) | Unknown (no JSONL turn-state reader) | yes (role `model` / `effort`, catalog-validated) | yes (full snapshot into separate seat/session; exact backing resume) |
 | `gemini_cli` | no | no | yes | no |
 | `fake` (testing only) | no | no | n/a | no |
 
@@ -134,6 +135,7 @@ Notes:
 - Per-worker model override means a role-doc `model:` value wins over `TEAM.md` `provider_models.<provider>` at **compile** time; subscription defaults still fill blanks when there is no profile-deferred null.
 - Copilot fork copies the source session into an isolated `COPILOT_HOME` and rekeys its SQLite session references atomically. Missing or incomplete backing fails closed; it never falls back to a fresh spawn.
 - Copilot phase-1 idle/turn detection is intentionally Unknown; tick emits a single explicit `provider.classify.unsupported` event per state change (P4 dedup), never a silent default.
+- `pi` `fork-agent SOURCE --as TARGET` requires a captured Pi subscription source. It copies the complete JSONL history into a distinct target session with a new id and exact `--session <path>` resume; it does not alter the source file or fall back to a fresh session.
 
 ## Provider Prep
 
@@ -567,7 +569,7 @@ Semantic distinction:
 - `team-agent add-agent <agent> --role-file <file>` — add a **new** worker not yet in team state.
 - `team-agent add-agent <agent> --role-file <file> --force` — force-recreate that worker from the role file.
 - `team-agent clone-agent <source> --as <new>` — reread the source worker's latest role file and start a fresh provider seat. It never copies conversation context. Success is initially honest `capture_state: pending_first_turn` with `session_id`, `new_session_id`, and `backing_path` all null; after the first turn, canonical capture changes the state to `captured` and fills the backing tuple.
-- `team-agent fork-agent <source> --as <new>` — reread the same latest role file and create a distinct, verified provider session that forks the source context. If the provider backing cannot be verified, the command fails and rolls back instead of silently cloning fresh.
+- `team-agent fork-agent <source> --as <new>` — reread the source's latest role file and create a distinct provider session carrying its context. Pi subscription forks a verified full snapshot into a separate target seat/backing and reports source id, target id, and backing path; supported non-Pi providers keep their existing fork behavior. Unverified backing fails closed instead of silently cloning fresh.
 - `team-agent start-agent <agent>` — (re)launch a worker that **already exists** in team state but whose window is missing.
 - `team-agent reset-agent <agent> --discard-session` — keep the same seat and deliberately start it with fresh context.
 - `team-agent restart .` — resume a fully **stopped** team from stored worker sessions.

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

@@ -112,12 +112,6 @@ For an existing worker that should restart with a blank provider context, the le
 team-agent reset-agent "$AGENT_ID" --workspace "$WORKSPACE" --team "$TEAM" --discard-session --json
 ```
 
-or the equivalent restart form:
-
-```bash
-team-agent restart-agent "$AGENT_ID" --workspace "$WORKSPACE" --team "$TEAM" --discard-session --json
-```
-
 Use this only when the user intentionally wants a clean context. For incident recovery, follow `recovery-runbook.md`, where context-preserving repair comes first.
 
 ## Framework Gaps To Track