@team-agent/installer 0.5.100 → 0.5.101

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

@@ -82,6 +82,7 @@ mod pi_command_red;
 mod pi_compiler_red;
 mod pi_dual_entry_red;
 mod pi_executable_mcp_red;
+mod pi_fork_session_inheritance_red;
 mod pi_lifecycle_doctor_red;
 mod pi_session_delivery_red;
 mod quick_start_worker_readiness_red;

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

@@ -605,8 +605,8 @@ pub struct AddAgentReport {
     pub role_file: PathBuf,
 }
 
-/// `fork_agent(...)` 结果(`operations.py:402`)。native session fork(provider 须
-/// supports_session_fork ∧ auth_mode!=compatible_api)。
+/// `fork_agent(...)` 结果。Pi 的 snapshot fork 附带可审计的 source/target backing 细节；
+/// 已支持的其他 provider 保持既有报告字段。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ForkAgentReport {
     pub source_agent_id: AgentId,
@@ -614,6 +614,14 @@ pub struct ForkAgentReport {
     pub env: AgentActionEnvelope,
     pub session_id: Option<SessionId>,
     pub backing_state: ForkBackingState,
+    pub pi_fork: Option<PiForkDetails>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PiForkDetails {
+    pub source_session_id: SessionId,
+    pub session_id: SessionId,
+    pub backing_path: RolloutPath,
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]

package/crates/team-agent/src/model/spec.rs

@@ -406,6 +406,7 @@ fn check_agent(agent: &Yaml, path: &str, errors: &mut Vec<String>) {
     ];
     let allowed = &[
         "id",
+        "label",
         "role",
         "provider",
         "model",

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

@@ -132,6 +132,8 @@ pub enum CaptureVia {
     FsWatch,
     FsMtimeFallback,
     FsRepair,
+    SessionScan,
+    ForkSnapshot,
 }
 
 /// attribution confidence(doc §56)。bug-085 fallback 固定 `Low`。

package/crates/team-agent/src/state/persist.rs

@@ -232,6 +232,7 @@ pub fn save_runtime_state(workspace: &Path, state: &Value) -> Result<(), StateEr
         &[],
         None,
         None,
+        false,
     )
 }
 
@@ -251,6 +252,7 @@ pub(crate) fn save_runtime_state_with_receiver_authority(
         &[],
         Some(receiver_team_key),
         exact_owner_seed_to_clear,
+        false,
     )
 }
 
@@ -289,6 +291,7 @@ pub(crate) fn save_runtime_state_with_lifecycle_topology_authority(
         agent_ids,
         None,
         None,
+        false,
     )
 }
 
@@ -309,6 +312,7 @@ pub(crate) fn save_runtime_state_with_lifecycle_topology_authority_and_capture_b
         topology_agent_ids,
         None,
         None,
+        false,
     )
 }
 
@@ -327,6 +331,7 @@ pub(crate) fn save_runtime_state_with_deleted_agents(
         &[],
         None,
         None,
+        true,
     )
 }
 
@@ -346,6 +351,7 @@ pub(crate) fn save_runtime_state_with_team_tombstoned_agents(
         &[],
         None,
         None,
+        false,
     )
 }
 
@@ -365,6 +371,7 @@ pub(crate) fn save_runtime_state_with_team_tombstone_lifecycle_topology_authorit
         agent_ids,
         None,
         None,
+        false,
     )
 }
 
@@ -378,6 +385,7 @@ fn save_runtime_state_with_merge_options(
     topology_update_agent_ids: &[&str],
     receiver_update_team_key: Option<&str>,
     exact_owner_seed_to_clear: Option<&Value>,
+    preserve_latest_fork_targets: bool,
 ) -> Result<(), StateError> {
     persist_runtime_state_with_merge_options_and_expected(
         workspace,
@@ -392,6 +400,7 @@ fn save_runtime_state_with_merge_options(
         None,
         None,
         None,
+        preserve_latest_fork_targets,
     )
 }
 
@@ -415,6 +424,7 @@ pub(crate) fn save_runtime_state_with_receiver_authority_and_expected(
         Some((expected_owner, expected_receiver)),
         None,
         None,
+        false,
     )
 }
 
@@ -438,6 +448,7 @@ pub(crate) fn save_runtime_state_with_exact_owner_receiver_cleanup(
         None,
         Some((team_key, expected_owner, expected_receiver)),
         None,
+        false,
     )
 }
 
@@ -469,6 +480,7 @@ pub(crate) fn save_runtime_state_with_exact_owner_receiver_restore(
             previous_owner,
             previous_receiver,
         )),
+        false,
     )
 }
 
@@ -485,6 +497,7 @@ fn persist_runtime_state_with_merge_options_and_expected(
     expected_owner_receiver: Option<(&Value, &Value)>,
     exact_owner_receiver_to_clear: Option<(&str, &Value, &Value)>,
     exact_owner_receiver_to_restore: Option<(&str, &Value, &Value, &Value, &Value)>,
+    preserve_latest_fork_targets: bool,
 ) -> Result<(), StateError> {
     let path = runtime_state_path(workspace);
     // Python `state.py:497`:先对入参 state 跑 `_migrate_state_identity`(就地填缺失 leader uuid)。
@@ -585,7 +598,7 @@ fn persist_runtime_state_with_merge_options_and_expected(
             .filter(|team_key| !team_key.is_empty())
             .map(str::to_string)
             .collect::<BTreeSet<_>>();
-        apply_persist_merge_contract(
+        apply_persist_merge_contract_with_fork_target_preservation(
             &mut migrated,
             latest,
             &deleted,
@@ -596,6 +609,7 @@ fn persist_runtime_state_with_merge_options_and_expected(
             receiver_update_team_key.zip(exact_owner_seed_to_clear),
             exact_owner_receiver_to_clear,
             exact_owner_receiver_to_restore,
+            preserve_latest_fork_targets,
         )?;
     }
     super::abnormal_watch::compact_after_merge(&mut migrated, latest.as_ref(), deleted_agent_ids);
@@ -707,6 +721,34 @@ fn apply_persist_merge_contract(
     exact_owner_seed_to_clear: Option<(&str, &Value)>,
     exact_owner_receiver_to_clear: Option<(&str, &Value, &Value)>,
     exact_owner_receiver_to_restore: Option<(&str, &Value, &Value, &Value, &Value)>,
+) -> Result<(), StateError> {
+    apply_persist_merge_contract_with_fork_target_preservation(
+        incoming,
+        latest,
+        deleted_agent_ids,
+        skip_capture_backfill_team_key,
+        skip_capture_backfill_agent_ids,
+        topology_updates,
+        receiver_updates,
+        exact_owner_seed_to_clear,
+        exact_owner_receiver_to_clear,
+        exact_owner_receiver_to_restore,
+        false,
+    )
+}
+
+fn apply_persist_merge_contract_with_fork_target_preservation(
+    incoming: &mut Value,
+    latest: &Value,
+    deleted_agent_ids: &BTreeSet<String>,
+    skip_capture_backfill_team_key: Option<&str>,
+    skip_capture_backfill_agent_ids: &BTreeSet<String>,
+    topology_updates: &BTreeSet<(String, String)>,
+    receiver_updates: &BTreeSet<String>,
+    exact_owner_seed_to_clear: Option<(&str, &Value)>,
+    exact_owner_receiver_to_clear: Option<(&str, &Value, &Value)>,
+    exact_owner_receiver_to_restore: Option<(&str, &Value, &Value, &Value, &Value)>,
+    preserve_latest_fork_targets: bool,
 ) -> Result<(), StateError> {
     // A0/R1: the projection gate only guards the TOP-LEVEL passes (top-level agents and
     // the top-level<->active-team cross projections depend on which team is active); the
@@ -740,6 +782,7 @@ fn apply_persist_merge_contract(
             skip_capture_backfill_agent_ids,
             &topology_update_agent_ids,
             None,
+            preserve_latest_fork_targets,
         )?;
         // Stage 3c (identity-boundary unified plan, architect direction
         // 2026-06-23): top-level owner copy-back removed. Pre-3c this
@@ -818,6 +861,7 @@ fn apply_persist_merge_contract(
                 skip_capture_backfill_agent_ids,
                 &topology_update_agent_ids,
                 team_alive,
+                preserve_latest_fork_targets,
             )?;
             preserve_latest_ownership_fields(
                 incoming_entry,
@@ -1196,6 +1240,7 @@ fn merge_agent_projection(
     //   the merge must NOT protect stale topology so a live sibling's write
     //   can go through.
     team_alive: Option<bool>,
+    preserve_latest_fork_targets: bool,
 ) -> Result<(), StateError> {
     let Some(incoming_agents) = incoming_agents else {
         return Ok(());
@@ -1212,8 +1257,17 @@ fn merge_agent_projection(
         }
         let tombstoned_for_projection =
             skip_capture_backfill && skip_capture_backfill_agent_ids.contains(agent_id);
+        let fork_target = preserve_latest_fork_targets
+            && latest_agent
+                .get("forked_from")
+                .and_then(Value::as_str)
+                .is_some_and(|source| !source.is_empty());
         match incoming_map.entry(agent_id.clone()) {
             serde_json::map::Entry::Vacant(slot) => {
+                if fork_target {
+                    slot.insert(latest_agent.clone());
+                    continue;
+                }
                 if topology_update_agent_ids.contains(agent_id) {
                     continue;
                 }
@@ -1244,7 +1298,9 @@ fn merge_agent_projection(
                 if !tombstoned_for_projection && !topology_update_agent_ids.contains(agent_id) {
                     let fields = topology_conflict_fields(existing.get(), latest_agent, team_alive);
                     if !fields.is_empty() {
-                        if !topology_update_agent_ids.is_empty()
+                        if fork_target {
+                            preserve_latest_topology(existing.get_mut(), latest_agent);
+                        } else if !topology_update_agent_ids.is_empty()
                             && lifecycle_peer_snapshot_is_stale(existing.get(), latest_agent)
                         {
                             // A lifecycle writer may have loaded a complete

package/crates/team-agent/src/state/projection.rs

@@ -972,7 +972,11 @@ fn save_team_scoped_state_with_merge_options(
             );
         }
         if tombstoned_agent_ids.is_empty() {
-            return save_runtime_state_with_deleted_agents(workspace, &merged, deleted_agent_ids);
+            return save_runtime_state_with_deleted_agents(
+                workspace,
+                &merged,
+                deleted_agent_ids,
+            );
         }
         return save_runtime_state_with_team_tombstoned_agents(
             workspace,

package/crates/team-agent/src/state/repository.rs

@@ -128,6 +128,9 @@ impl<'a> StateRepository<'a> {
     /// forward call to the same legacy helper family that the caller used
     /// before S1a; the intent selects the family, not the merge semantics.
     pub fn save(&self, intent: StateWriteIntent<'_>, state: &Value) -> Result<(), StateError> {
+        if let StateWriteIntent::CoordinatorTick { team_key } = &intent {
+            return self.save_coordinator_tick(team_key, state);
+        }
         route_direct(self.workspace, intent, state)
     }
 
@@ -149,8 +152,8 @@ impl<'a> StateRepository<'a> {
         route_reapply(self.workspace, intent, state, reapply)
     }
 
-    /// Commit a task/note delta once against latest under state-save. Return
-    /// the committed Team view for callers that produce Markdown afterwards.
+    /// Commit a bounded Team delta once against latest under state-save.
+    /// Return the committed Team view for callers that produce Markdown afterwards.
     pub fn commit<F>(&self, intent: StateWriteIntent<'_>, update: F) -> Result<Value, StateError>
     where
         F: FnOnce(&mut Value),
@@ -163,7 +166,12 @@ impl<'a> StateRepository<'a> {
             StateWriteIntent::McpAssignTask { .. } => None,
             StateWriteIntent::McpUpdateStateNote { team_key } => team_key,
             StateWriteIntent::ResultCollection { owner_team_id } => owner_team_id,
-            _ => return Err(StateError::SaveFailed("intent does not accept a task/note delta".into())),
+            StateWriteIntent::ForkAgent { team_key, .. } => Some(team_key),
+            _ => {
+                return Err(StateError::SaveFailed(
+                    "intent does not accept a bounded Team delta".into(),
+                ))
+            }
         };
         let committed = super::persist::update_runtime_state(self.workspace, |latest| {
             let mut selected = bounded_team_view(latest, team_key)?;
@@ -176,6 +184,64 @@ impl<'a> StateRepository<'a> {
         bounded_team_view(&committed, team_key)
     }
 
+    /// Atomically replace only the fork target row in the selected team.
+    pub(crate) fn commit_fork_agent(
+        &self,
+        intent: StateWriteIntent<'_>,
+        target_row: &Value,
+    ) -> Result<(), StateError> {
+        let (team_key, agent_id) = match &intent {
+            StateWriteIntent::ForkAgent {
+                team_key,
+                agent_id,
+            } => (*team_key, *agent_id),
+            _ => {
+                return Err(StateError::SaveFailed(
+                    "fork target delta requires ForkAgent intent".into(),
+                ))
+            }
+        };
+        let target_row = target_row.clone();
+        let mut found = false;
+        self.commit(
+            StateWriteIntent::ForkAgent { team_key, agent_id },
+            |selected| {
+                if let Some(row) = selected
+                    .get_mut("agents")
+                    .and_then(Value::as_object_mut)
+                    .and_then(|agents| agents.get_mut(agent_id))
+                {
+                    *row = target_row;
+                    found = true;
+                }
+            },
+        )?;
+        if found {
+            Ok(())
+        } else {
+            Err(StateError::SaveFailed(
+                "ForkAgent target row is missing from selected team".into(),
+            ))
+        }
+    }
+
+    fn save_coordinator_tick(&self, team_key: &str, state: &Value) -> Result<(), StateError> {
+        let incoming = state.clone();
+        super::persist::update_runtime_state(self.workspace, |latest| {
+            let mut incoming_team = bounded_team_view(&incoming, Some(team_key))?;
+            let latest_team = bounded_team_view(latest, Some(team_key))?;
+            preserve_latest_fork_rows(&mut incoming_team, &latest_team);
+            let mut checked =
+                super::projection::merge_committed_team(latest, &incoming_team, team_key);
+            super::persist::merge_ordinary_state(&mut checked, latest)?;
+            let checked = bounded_team_view(&checked, Some(team_key))?;
+            Ok(super::projection::merge_committed_team(
+                latest, &checked, team_key,
+            ))
+        })?;
+        Ok(())
+    }
+
     /// Fence the sampled incarnation with the existing persist guards, then
     /// commit only this tick's agent observations and coordinator bookkeeping.
     pub fn commit_observations(
@@ -201,6 +267,7 @@ impl<'a> StateRepository<'a> {
                     ));
                 }
                 let mut checked = observed.clone();
+                preserve_latest_fork_rows(&mut checked, latest);
                 super::persist::merge_ordinary_state(&mut checked, latest)?;
                 if !legacy_single_team_state(&checked)
                     || sampled_identity != legacy_team_identity(&checked)
@@ -222,7 +289,13 @@ impl<'a> StateRepository<'a> {
                 }
                 return Ok(selected);
             }
-            let mut checked = super::projection::merge_committed_team(latest, observed, team_key);
+            let mut observed_with_delta = observed.clone();
+            sync_team_observation_delta(before, &mut observed_with_delta, team_key);
+            let mut observed_team = bounded_team_view(&observed_with_delta, Some(team_key))?;
+            let latest_team = bounded_team_view(latest, Some(team_key))?;
+            preserve_latest_fork_rows(&mut observed_team, &latest_team);
+            let mut checked =
+                super::projection::merge_committed_team(latest, &observed_team, team_key);
             super::persist::merge_ordinary_state(&mut checked, latest)?;
             let checked = bounded_team_view(&checked, Some(team_key))?;
             let mut selected = bounded_team_view(latest, Some(team_key))?;
@@ -231,12 +304,32 @@ impl<'a> StateRepository<'a> {
                     apply_observation_delta(&before[field], &checked[field], &mut selected[field]);
                 }
             }
+            sync_team_observation_delta(before, &mut selected, team_key);
             Ok(super::projection::merge_committed_team(latest, &selected, team_key))
         })?;
         Ok(())
     }
 }
 
+// Coordinator observations do not own fork-target lifecycle rows.
+fn preserve_latest_fork_rows(incoming: &mut Value, latest: &Value) {
+    let Some(latest_agents) = latest.get("agents").and_then(Value::as_object) else {
+        return;
+    };
+    let Some(incoming_agents) = incoming.get_mut("agents").and_then(Value::as_object_mut) else {
+        return;
+    };
+    for (agent_id, latest_agent) in latest_agents {
+        if latest_agent
+            .get("forked_from")
+            .and_then(Value::as_str)
+            .is_some_and(|source| !source.is_empty())
+        {
+            incoming_agents.insert(agent_id.clone(), latest_agent.clone());
+        }
+    }
+}
+
 fn legacy_single_team_state(state: &Value) -> bool {
     match state.get("teams") {
         None => true,
@@ -292,6 +385,34 @@ fn apply_observation_delta(before: &Value, observed: &Value, latest: &mut Value)
     }
 }
 
+// The coordinator observes a projected team view, while its nested `teams`
+// snapshot remains stale. Carry only observation deltas back to the canonical
+// team entry before `bounded_team_view` projects it again.
+fn sync_team_observation_delta(before: &Value, observed: &mut Value, team_key: &str) {
+    for field in ["agents", "coordinator"] {
+        let before_value = before.get(field).cloned().unwrap_or(Value::Null);
+        let observed_value = observed.get(field).cloned().unwrap_or(Value::Null);
+        if before_value == observed_value {
+            continue;
+        }
+        let Some(team_entry) = observed
+            .get_mut("teams")
+            .and_then(Value::as_object_mut)
+            .and_then(|teams| teams.get_mut(team_key))
+            .and_then(Value::as_object_mut)
+        else {
+            continue;
+        };
+        if field == "coordinator" && !team_entry.contains_key(field) {
+            team_entry.insert(field.to_string(), serde_json::json!({}));
+        }
+        let slot = team_entry
+            .entry(field.to_string())
+            .or_insert_with(|| before_value.clone());
+        apply_observation_delta(&before_value, &observed_value, slot);
+    }
+}
+
 /// Closed semantic catalog of workspace state writes. Every allowlisted
 /// callsite maps to exactly one variant, and there is intentionally no
 /// generic escape bucket. Any new state write must earn its own variant so

package/crates/team-agent/src/transport/test_support.rs

@@ -360,7 +360,20 @@ impl OfflineTransport {
             if kind == "spawn_first" && !state.session_absent_after_spawn_first {
                 state.session_present = true;
             }
-            let pane_index = state.spawns.len().saturating_sub(1);
+            let mut pane_index = state.spawns.len().saturating_sub(1);
+            // Existing sessions reserve `%0` for the already-running pane.
+            if kind == "spawn_into" {
+                pane_index = pane_index.max(1);
+            }
+            while state.pane_presence.contains_key(&format!("%{pane_index}"))
+                || state
+                    .targets
+                    .iter()
+                    .chain(state.target_snapshots.iter().flatten())
+                    .any(|target| target.pane_id.as_str() == format!("%{pane_index}"))
+            {
+                pane_index = pane_index.saturating_add(1);
+            }
             state
                 .pane_presence
                 .insert(format!("%{pane_index}"), state.spawned_panes_addressable);
@@ -541,10 +554,17 @@ impl Transport for OfflineTransport {
             });
         }
         Ok(self.with_state(|state| {
-            state
+            let targets = state
                 .target_snapshots
                 .pop_front()
-                .unwrap_or_else(|| state.targets.clone())
+                .unwrap_or_else(|| state.targets.clone());
+            for target in &targets {
+                state
+                    .pane_presence
+                    .entry(target.pane_id.as_str().to_string())
+                    .or_insert(true);
+            }
+            targets
         }))
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-agent/installer",
-  "version": "0.5.100",
+  "version": "0.5.101",
   "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.100",
-    "@team-agent/cli-darwin-x64": "0.5.100",
-    "@team-agent/cli-linux-x64": "0.5.100"
+    "@team-agent/cli-darwin-arm64": "0.5.101",
+    "@team-agent/cli-darwin-x64": "0.5.101",
+    "@team-agent/cli-linux-x64": "0.5.101"
   },
   "scripts": {
     "postinstall": "node npm/bincheck.mjs",

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/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.