@team-agent/installer 0.5.52 → 0.5.54

package/crates/team-agent/src/provider/tests/copilot_fork.rs

@@ -0,0 +1,191 @@
+use std::path::Path;
+
+use rusqlite::Connection;
+
+#[test]
+#[serial_test::serial(env)]
+fn copilot_fork_copies_isolated_home_and_rekeys_every_session_table() {
+    use crate::provider::adapters::copilot_fork::materialize_copilot_fork;
+    use std::sync::atomic::{AtomicU64, Ordering};
+
+    static COUNTER: AtomicU64 = AtomicU64::new(0);
+    let root = std::env::temp_dir().join(format!(
+        "ta-copilot-fork-{}-{}",
+        std::process::id(),
+        COUNTER.fetch_add(1, Ordering::Relaxed)
+    ));
+    let source_home = root.join("source-home");
+    let workspace = root.join("workspace");
+    std::fs::create_dir_all(&workspace).unwrap();
+    let source = SessionId::new("11111111-2222-4333-8444-555555555555");
+    seed_copilot_fork_fixture(&source_home, source.as_str(), None);
+    let source_events = std::fs::read(
+        source_home
+            .join("session-state")
+            .join(source.as_str())
+            .join("events.jsonl"),
+    )
+    .unwrap();
+    let previous = std::env::var_os("COPILOT_HOME");
+    std::env::set_var("COPILOT_HOME", &source_home);
+
+    let materialized = materialize_copilot_fork(&workspace, "fork-a", &source).unwrap();
+    assert_ne!(materialized.session_id(), &source);
+    assert!(materialized
+        .home()
+        .starts_with(workspace.join(".team/runtime/provider-session-forks/copilot/fork-a")));
+    let new_id = materialized.session_id().as_str();
+    let target_state = materialized.home().join("session-state").join(new_id);
+    assert!(target_state.is_dir());
+    assert_eq!(
+        std::fs::read_to_string(target_state.join("events.jsonl")).unwrap(),
+        format!("{{\"session_id\":\"{new_id}\"}}\n")
+    );
+    let per_session = Connection::open(target_state.join("session.db")).unwrap();
+    let recipient: String = per_session
+        .query_row(
+            "select recipient_session_id from inbox_entries",
+            [],
+            |row| row.get(0),
+        )
+        .unwrap();
+    assert_eq!(recipient, new_id);
+
+    let central = Connection::open(materialized.home().join("session-store.db")).unwrap();
+    assert_eq!(session_count(&central, "sessions", "id", new_id), 1);
+    assert_eq!(
+        session_count(&central, "sessions", "id", source.as_str()),
+        0
+    );
+    for table in [
+        "turns",
+        "checkpoints",
+        "session_files",
+        "session_refs",
+        "forge_trajectory_events",
+        "search_index",
+    ] {
+        assert_eq!(session_count(&central, table, "session_id", new_id), 1);
+        assert_eq!(
+            session_count(&central, table, "session_id", source.as_str()),
+            0
+        );
+    }
+    assert_eq!(
+        std::fs::read(
+            source_home
+                .join("session-state")
+                .join(source.as_str())
+                .join("events.jsonl")
+        )
+        .unwrap(),
+        source_events,
+        "fork must not mutate source backing"
+    );
+
+    restore_env("COPILOT_HOME", previous);
+    let _ = std::fs::remove_dir_all(root);
+}
+
+#[test]
+#[serial_test::serial(env)]
+fn copilot_fork_fails_closed_when_a_required_session_table_is_missing() {
+    let root = std::env::temp_dir().join(format!("ta-copilot-fork-missing-{}", std::process::id()));
+    let source_home = root.join("source-home");
+    let workspace = root.join("workspace");
+    std::fs::create_dir_all(&workspace).unwrap();
+    let source = SessionId::new("aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee");
+    seed_copilot_fork_fixture(&source_home, source.as_str(), Some("session_refs"));
+    let previous = std::env::var_os("COPILOT_HOME");
+    std::env::set_var("COPILOT_HOME", &source_home);
+
+    let error = crate::provider::adapters::copilot_fork::materialize_copilot_fork(
+        &workspace, "fork-b", &source,
+    )
+    .unwrap_err();
+    assert!(error.to_string().contains("session_refs"), "{error}");
+    let managed_parent = workspace.join(".team/runtime/provider-session-forks/copilot/fork-b");
+    assert!(
+        !managed_parent.exists() || std::fs::read_dir(managed_parent).unwrap().next().is_none(),
+        "failed materialization must leave no clone home"
+    );
+
+    restore_env("COPILOT_HOME", previous);
+    let _ = std::fs::remove_dir_all(root);
+}
+
+fn seed_copilot_fork_fixture(home: &Path, source: &str, omitted: Option<&str>) {
+    let state = home.join("session-state").join(source);
+    std::fs::create_dir_all(state.join("checkpoints")).unwrap();
+    std::fs::write(
+        state.join("workspace.yaml"),
+        format!("session_id: {source}\n"),
+    )
+    .unwrap();
+    std::fs::write(
+        state.join("events.jsonl"),
+        format!("{{\"session_id\":\"{source}\"}}\n"),
+    )
+    .unwrap();
+    let session_db = Connection::open(state.join("session.db")).unwrap();
+    session_db
+        .execute_batch(
+            "create table inbox_entries (id text primary key, recipient_session_id text not null);",
+        )
+        .unwrap();
+    session_db
+        .execute("insert into inbox_entries values ('one', ?1)", [source])
+        .unwrap();
+
+    let db = Connection::open(home.join("session-store.db")).unwrap();
+    db.execute_batch(
+        "create table sessions (id text primary key);
+         create table turns (id integer primary key, session_id text not null);
+         create table checkpoints (id integer primary key, session_id text not null);
+         create table session_files (id integer primary key, session_id text not null);
+         create table session_refs (id integer primary key, session_id text not null);
+         create table forge_trajectory_events (id integer primary key, session_id text not null);
+         create virtual table search_index using fts5(content, session_id unindexed);",
+    )
+    .unwrap();
+    db.execute("insert into sessions values (?1)", [source])
+        .unwrap();
+    for table in [
+        "turns",
+        "checkpoints",
+        "session_files",
+        "session_refs",
+        "forge_trajectory_events",
+    ] {
+        if omitted != Some(table) {
+            db.execute(
+                &format!("insert into {table} (session_id) values (?1)"),
+                [source],
+            )
+            .unwrap();
+        } else {
+            db.execute(&format!("drop table {table}"), []).unwrap();
+        }
+    }
+    db.execute(
+        "insert into search_index (content, session_id) values ('x', ?1)",
+        [source],
+    )
+    .unwrap();
+}
+
+fn session_count(conn: &Connection, table: &str, column: &str, id: &str) -> i64 {
+    conn.query_row(
+        &format!("select count(*) from {table} where {column} = ?1"),
+        [id],
+        |row| row.get(0),
+    )
+    .unwrap()
+}
+
+fn restore_env(key: &str, value: Option<std::ffi::OsString>) {
+    match value {
+        Some(value) => std::env::set_var(key, value),
+        None => std::env::remove_var(key),
+    }
+}

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

@@ -29,3 +29,4 @@ include!("tests/classify.rs");
 include!("tests/idle.rs");
 include!("tests/adapter.rs");
 include!("tests/faults.rs");
+include!("tests/copilot_fork.rs");

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

@@ -12,7 +12,9 @@ use std::os::unix::net::UnixListener;
 use std::path::Path;
 use std::sync::{Arc, Mutex};
 
-use super::{CommandOutput, CommandRunner, RealCommandRunner, TmuxBackend};
+use super::{
+    CommandOutput, CommandRunner, RealCommandRunner, TmuxBackend, PANE_BINDING_NONCE_METADATA_KEY,
+};
 use crate::model::enums::PaneLiveness;
 use crate::transport::{
     normalize_capture, tmux_capture_argv, tmux_query_argv, tmux_send_keys_argv, tmux_spawn_argv,
@@ -395,10 +397,7 @@ fn spawn_first_frames_via_new_session_builder_and_parses_pane_id() {
     let pane_inventory = "%3\tteamsess\t0\tw1\t0\t/dev/ttys003\tnode\t1\t/work/dir\t1\t0\t123\n";
     let (be, rec) = backend_with(
         MockResp::Out(ok("")),
-        vec![
-            MockResp::Out(ok("%3\n")),
-            MockResp::Out(ok(pane_inventory)),
-        ],
+        vec![MockResp::Out(ok("%3\n")), MockResp::Out(ok(pane_inventory))],
     );
     let s = SessionName::new("teamsess");
     let w = WindowName::new("w1");
@@ -443,10 +442,7 @@ fn spawn_into_frames_via_new_window_builder() {
     let pane_inventory = "%4\tteamsess\t1\tw2\t0\t/dev/ttys004\tnode\t1\t/work/dir\t1\t0\t124\n";
     let (be, rec) = backend_with(
         MockResp::Out(ok("")),
-        vec![
-            MockResp::Out(ok("%4\n")),
-            MockResp::Out(ok(pane_inventory)),
-        ],
+        vec![MockResp::Out(ok("%4\n")), MockResp::Out(ok(pane_inventory))],
     );
     let s = SessionName::new("teamsess");
     let w = WindowName::new("w2");
@@ -518,10 +514,7 @@ fn spawn_with_command_refuses_and_rolls_back_spawn_pane_owned_by_other_window()
     let pane_inventory = "%5\tteamsess\t1\tw2\t0\t/dev/ttys005\tnode\t1\t/work/dir\t1\t0\t125\n";
     let (be, rec) = backend_with(
         MockResp::Out(ok("")),
-        vec![
-            MockResp::Out(ok("%5\n")),
-            MockResp::Out(ok(pane_inventory)),
-        ],
+        vec![MockResp::Out(ok("%5\n")), MockResp::Out(ok(pane_inventory))],
     );
     let err = be
         .spawn_into(
@@ -1791,9 +1784,9 @@ fn query_single_field_argv_and_nonzero_maps_to_none() {
 // display-message N+1 fallback is gone). leader_env stays the reverse-env real-machine bit.
 #[test]
 fn list_targets_argv_and_parses_tmux_pane_format() {
-    const FMT: &str = "#{pane_id}__TA_FIELD__#{session_name}__TA_FIELD__#{window_index}__TA_FIELD__#{window_name}__TA_FIELD__#{pane_index}__TA_FIELD__#{pane_tty}__TA_FIELD__#{pane_current_command}__TA_FIELD__#{pane_active}__TA_FIELD__#{pane_current_path}__TA_FIELD__#{session_attached}__TA_FIELD__#{pane_in_mode}__TA_FIELD__#{pane_pid}";
-    let stdout = "%7__TA_FIELD__team-x__TA_FIELD__0__TA_FIELD__win0__TA_FIELD__0__TA_FIELD__/dev/ttys003__TA_FIELD__codex__TA_FIELD__1__TA_FIELD__/Users/me/work__TA_FIELD__1__TA_FIELD__0__TA_FIELD__41001\n\
-                      %8__TA_FIELD__team-x__TA_FIELD__1__TA_FIELD__win1__TA_FIELD__0__TA_FIELD__/dev/ttys004__TA_FIELD__node__TA_FIELD__0__TA_FIELD__/Users/me/other__TA_FIELD__0__TA_FIELD__0__TA_FIELD__41002\n";
+    const FMT: &str = "#{pane_id}__TA_FIELD__#{session_name}__TA_FIELD__#{window_index}__TA_FIELD__#{window_name}__TA_FIELD__#{pane_index}__TA_FIELD__#{pane_tty}__TA_FIELD__#{pane_current_command}__TA_FIELD__#{pane_active}__TA_FIELD__#{pane_current_path}__TA_FIELD__#{session_attached}__TA_FIELD__#{pane_in_mode}__TA_FIELD__#{pane_pid}__TA_FIELD__#{@team_agent_pane_binding_nonce}";
+    let stdout = "%7__TA_FIELD__team-x__TA_FIELD__0__TA_FIELD__win0__TA_FIELD__0__TA_FIELD__/dev/ttys003__TA_FIELD__codex__TA_FIELD__1__TA_FIELD__/Users/me/work__TA_FIELD__1__TA_FIELD__0__TA_FIELD__41001__TA_FIELD__nonce-7\n\
+                      %8__TA_FIELD__team-x__TA_FIELD__1__TA_FIELD__win1__TA_FIELD__0__TA_FIELD__/dev/ttys004__TA_FIELD__node__TA_FIELD__0__TA_FIELD__/Users/me/other__TA_FIELD__0__TA_FIELD__0__TA_FIELD__41002__TA_FIELD__\n";
     let (be, rec) = backend_with(MockResp::Out(ok(stdout)), vec![]);
     let panes = be.list_targets().expect("list_targets ok");
     assert_eq!(
@@ -1845,6 +1838,19 @@ fn list_targets_argv_and_parses_tmux_pane_format() {
         Some(41002),
         "field[11] -> pane_pid (second pane)"
     );
+    assert_eq!(
+        p.leader_env
+            .get(PANE_BINDING_NONCE_METADATA_KEY)
+            .map(String::as_str),
+        Some("nonce-7"),
+        "field[12] pane option -> pane-instance binding metadata"
+    );
+    assert!(
+        !panes[1]
+            .leader_env
+            .contains_key(PANE_BINDING_NONCE_METADATA_KEY),
+        "an empty pane option must remain absent"
+    );
 
     // nonzero exit -> empty vec (golden returncode != 0 -> []).
     let (be, _r) = backend_with(
@@ -1859,6 +1865,35 @@ fn list_targets_argv_and_parses_tmux_pane_format() {
     );
 }
 
+#[test]
+fn set_pane_binding_nonce_is_socket_scoped_and_pane_local() {
+    let rec = Arc::new(Mutex::new(Vec::new()));
+    let runner = MockCommandRunner {
+        recorded: Arc::clone(&rec),
+        stdin_recorded: Arc::new(Mutex::new(Vec::new())),
+        queue: Mutex::new(VecDeque::new()),
+        default: MockResp::Out(ok("")),
+    };
+    let be =
+        TmuxBackend::with_runner_for_tmux_endpoint(Box::new(runner), "/tmp/ta-pane-binding.sock");
+    be.set_pane_binding_nonce(&PaneId::new("%7"), "nonce-7")
+        .expect("set pane binding nonce");
+    assert_eq!(
+        rec.lock().unwrap()[0],
+        svec(&[
+            "tmux",
+            "-S",
+            "/tmp/ta-pane-binding.sock",
+            "set-option",
+            "-p",
+            "-t",
+            "%7",
+            "@team_agent_pane_binding_nonce",
+            "nonce-7",
+        ])
+    );
+}
+
 // ── 12. attach_session (TRANSPORT TRIO) — `tmux attach-session -t <s>` -> Attached ──────────────
 // Golden tmux attach is `tmux attach-session -t <session>`; a successful attach -> AttachOutcome::
 // Attached. RED today: attach_session is unimplemented!() -> PANIC. The in-process lock asserts the

package/crates/team-agent/src/tmux_backend.rs

@@ -40,6 +40,9 @@ use crate::transport::{
     TransportError, TurnVerification, WindowName,
 };
 
+pub const PANE_BINDING_NONCE_METADATA_KEY: &str = "TEAM_AGENT_PANE_BINDING_NONCE";
+const TMUX_PANE_BINDING_NONCE_OPTION: &str = "@team_agent_pane_binding_nonce";
+
 /// Result of running an external command — the typed output of the OS edge.
 #[derive(Debug, Clone)]
 pub struct CommandOutput {
@@ -279,6 +282,23 @@ impl TmuxBackend {
         }
     }
 
+    pub(crate) fn set_pane_binding_nonce(
+        &self,
+        pane: &PaneId,
+        nonce: &str,
+    ) -> Result<(), TransportError> {
+        let argv = [
+            "tmux".to_string(),
+            "set-option".to_string(),
+            "-p".to_string(),
+            "-t".to_string(),
+            pane.as_str().to_string(),
+            TMUX_PANE_BINDING_NONCE_OPTION.to_string(),
+            nonce.to_string(),
+        ];
+        self.run_ok(&argv)
+    }
+
     /// Backend with an injected runner (tests: canned/recording tmux output). Shared default socket.
     pub fn with_runner(runner: Box<dyn CommandRunner>) -> Self {
         Self {
@@ -2340,7 +2360,7 @@ impl Transport for TmuxBackend {
         // killing the per-pane display-message N+1 fallback.
         // Use a printable sentinel so the 12-field frame stays explicit in argv/log evidence;
         // `parse_pane_info_line` retains compatibility with legacy tab-delimited output.
-        const TMUX_PANE_FORMAT: &str = "#{pane_id}__TA_FIELD__#{session_name}__TA_FIELD__#{window_index}__TA_FIELD__#{window_name}__TA_FIELD__#{pane_index}__TA_FIELD__#{pane_tty}__TA_FIELD__#{pane_current_command}__TA_FIELD__#{pane_active}__TA_FIELD__#{pane_current_path}__TA_FIELD__#{session_attached}__TA_FIELD__#{pane_in_mode}__TA_FIELD__#{pane_pid}";
+        const TMUX_PANE_FORMAT: &str = "#{pane_id}__TA_FIELD__#{session_name}__TA_FIELD__#{window_index}__TA_FIELD__#{window_name}__TA_FIELD__#{pane_index}__TA_FIELD__#{pane_tty}__TA_FIELD__#{pane_current_command}__TA_FIELD__#{pane_active}__TA_FIELD__#{pane_current_path}__TA_FIELD__#{session_attached}__TA_FIELD__#{pane_in_mode}__TA_FIELD__#{pane_pid}__TA_FIELD__#{@team_agent_pane_binding_nonce}";
         let argv = self.tmux_argv(&[
             "tmux".to_string(),
             "list-panes".to_string(),
@@ -2544,6 +2564,13 @@ fn parse_pane_info_line(line: &str) -> Option<PaneInfo> {
     if fields.len() < 11 {
         return None;
     }
+    let mut leader_env = BTreeMap::new();
+    if let Some(nonce) = fields.get(12).and_then(|raw| non_empty(raw)) {
+        leader_env.insert(
+            PANE_BINDING_NONCE_METADATA_KEY.to_string(),
+            nonce.to_string(),
+        );
+    }
     Some(PaneInfo {
         pane_id: PaneId::new(fields[0]),
         session: SessionName::new(fields[1]),
@@ -2555,7 +2582,7 @@ fn parse_pane_info_line(line: &str) -> Option<PaneInfo> {
         active: fields[7] == "1",
         current_path: non_empty(fields[8]).map(PathBuf::from),
         pane_pid: fields.get(11).and_then(|raw| parse_optional_u32(raw)),
-        leader_env: BTreeMap::new(),
+        leader_env,
     })
 }
 

package/package.json

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

package/schemas/result-envelope.schema.json

@@ -11,6 +11,16 @@
     "agent_id": { "type": "string", "minLength": 1 },
     "status": { "enum": ["success", "blocked", "failed", "partial"] },
     "summary": { "type": "string" },
+    "presentation": {
+      "type": "object",
+      "required": ["sink", "class"],
+      "additionalProperties": false,
+      "properties": {
+        "sink": { "enum": ["leader", "casefile", "silent"] },
+        "class": { "enum": ["message", "progress", "stage_result", "stage_pass", "bounce", "blocking", "final_review", "timeout"] },
+        "case_id": { "type": "string", "minLength": 1 }
+      }
+    },
     "changes": {
       "type": "array",
       "items": {

package/skills/team-agent/SKILL.md

@@ -87,15 +87,15 @@ Use `team-agent attach-leader` / `team-agent claim-leader` to bind the leader pa
 
 | Provider | Resume | Turn-state detection | Per-worker model override | Native session fork |
 |---|---|---|---|---|
-| `claude` / `claude_code` | yes (`--resume <id>`, transcript-verified) | yes (JSONL stream) | yes (role `model` overrides `provider_models`) | yes (`--fork-session` + new `--session-id`) |
+| `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`) | **no — `CapabilityUnsupported`** |
+| `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) |
 | `gemini_cli` | no | no | yes | no |
 | `fake` (testing only) | no | no | n/a | no |
 
 Notes:
 - Per-worker model override means a role-doc `model:` value wins over `TEAM.md` `provider_models.<provider>`; subscription defaults still fill blanks.
-- Copilot's `caps.fork=false` is a hard refusal in 0.3.7 — `team-agent fork-agent` against a Copilot worker returns a structured `CapabilityUnsupported` error instead of falling back to a fresh spawn (honest by design).
+- 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.
 
 ## Provider Prep
@@ -166,6 +166,7 @@ For diagnosis, run `team-agent profile show deepseek --workspace . --json`; neve
 - `quick-start` is only for first-time team creation from role docs. If that team already has runtime state, use `team-agent restart . --team <session_name_or_team_name>` to resume it. If restart cannot recover context, explain the loss and wait for explicit user consent before using `team-agent restart . --allow-fresh`; never reset context through quick-start.
 - If the user explicitly asks a worker to create or operate a nested child team, first read `references/team-in-team.md`. Child teams must use an independent child workspace, never the parent `.team/current`.
 - `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.
+- Advanced orchestration callers may add `--presentation-sink leader|casefile|silent --message-class CLASS [--case-id CASE]`. All sinks remain durable and pullable; `casefile`/`silent` suppress only live leader injection. Missing presentation metadata preserves the normal leader-visible behavior.
 - 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 --json` is compact and context-safe by default; use `team-agent status --detail --json` only for raw runtime-state diagnostics.
@@ -213,10 +214,15 @@ team-agent add-agent reviewer --role-file .team/current/agents/reviewer.md --wor
 Semantic distinction:
 
 - `team-agent add-agent <agent> --role-file <file>` — add a **new** worker not yet in team state.
+- `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 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.
 - `team-agent quick-start <dir>` — first-time team creation from role docs; for existing teams use `restart`, and use `restart --allow-fresh` only after explicit user consent to discard context.
 
+Clone/fork names are always explicit: run concurrent calls with a different `--as` value for each new seat. Fork success includes a verified new `session_id` and independent backing; a tmux window alone is not fork success. Clone success uses the honest `pending_first_turn` state above until first-turn capture, never a fabricated verified tuple. Updating the source role file affects the next clone/fork without requiring a full-team rebuild. Automatic knowledge write-back from a clone/fork into the source role file is not provided.
+
 Removing a worker at runtime is the symmetric `team-agent remove-agent <agent> --workspace . --confirm`.
 
 ## Worker Protocol
@@ -232,6 +238,8 @@ team_orchestrator.send_message(to="*", content="short broadcast")
 team_orchestrator.report_result(summary="short completion", status="success", tests=[{"command":"command","status":"passed"}])
 ```
 
+For typed orchestration traffic, both `send_message` and `report_result` accept `presentation={"sink":"leader|casefile|silent","class":"message|progress|stage_result|stage_pass|bounce|blocking|final_review|timeout","case_id":"optional-case"}`. If the object is present, `sink` and `class` are required and unknown values fail closed. `casefile` and `silent` are durable-only, not deletion. The fixed critical classes `stage_pass`, `bounce`, `blocking`, `final_review`, and `timeout` always appear on the leader screen even when another sink is requested. Routing uses the typed class, never words in the content or summary.
+
 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.