@team-agent/installer 0.5.119 → 0.5.121

package/crates/team-agent/src/mcp_server/wire.rs

@@ -190,17 +190,20 @@ fn run_stdio_loop_inner<R: BufRead, W: Write>(
     report: &mut ServerRunReport,
     marker: &McpServerLifecycleMarker,
 ) -> Result<ServerRunReport, McpError> {
+    let mut initialized = false;
     for line in reader.lines() {
         let line = line?;
         report.requests_read = report.requests_read.saturating_add(1);
-        let (frame, tools_list_success) = handle_stdin_line(tools, &line, report)?;
+        let (frame, response_kind) = handle_stdin_line(tools, &line, report)?;
         if let Some(value) = frame {
             let value = crate::redaction::redact_external_value(&value);
             serde_json::to_writer(&mut *writer, &value)?;
             writer.write_all(b"\n")?;
             writer.flush()?;
-            if tools_list_success {
-                marker.write_tools_list_response_written();
+            match response_kind {
+                ResponseKind::Initialize => initialized = true,
+                ResponseKind::ToolsList => marker.write_tools_list_response_written(initialized),
+                ResponseKind::Other => {}
             }
             report.responses_written = report.responses_written.saturating_add(1);
         }
@@ -209,11 +212,17 @@ fn run_stdio_loop_inner<R: BufRead, W: Write>(
     Ok(report.clone())
 }
 
+enum ResponseKind {
+    Initialize,
+    ToolsList,
+    Other,
+}
+
 fn handle_stdin_line(
     tools: &TeamOrchestratorTools,
     line: &str,
     report: &mut ServerRunReport,
-) -> Result<(Option<Value>, bool), McpError> {
+) -> Result<(Option<Value>, ResponseKind), McpError> {
     let request: Value = match serde_json::from_str(line) {
         Ok(value) => value,
         Err(err) => {
@@ -224,23 +233,28 @@ fn handle_stdin_line(
                     -32700,
                     format!("parse error: {err}"),
                 )),
-                false,
+                ResponseKind::Other,
             ));
         }
     };
     if request.get("jsonrpc").and_then(Value::as_str) == Some("2.0") {
-        let is_tools_list = request.get("method").and_then(Value::as_str) == Some("tools/list");
+        let method = request.get("method").and_then(Value::as_str);
+        let valid_id = request.get("id").is_some_and(|id| id.is_string() || id.is_number());
         match handle_mcp(tools, &request)? {
             Some(response) => {
-                let tools_list_success = is_tools_list && response.error.is_none();
+                let kind = match (method, valid_id && response.error.is_none()) {
+                    (Some("initialize"), true) => ResponseKind::Initialize,
+                    (Some("tools/list"), true) => ResponseKind::ToolsList,
+                    _ => ResponseKind::Other,
+                };
                 if response.error.is_some() {
                     report.error_frames = report.error_frames.saturating_add(1);
                 }
-                Ok((Some(serde_json::to_value(response)?), tools_list_success))
+                Ok((Some(serde_json::to_value(response)?), kind))
             }
             None => {
                 report.notifications_skipped = report.notifications_skipped.saturating_add(1);
-                Ok((None, false))
+                Ok((None, ResponseKind::Other))
             }
         }
     } else {
@@ -251,7 +265,7 @@ fn handle_stdin_line(
                 err.to_envelope()
             }
         };
-        Ok((Some(value), false))
+        Ok((Some(value), ResponseKind::Other))
     }
 }
 
@@ -281,6 +295,7 @@ struct McpServerLifecycleMarker {
     workspace: std::path::PathBuf,
     agent_id: Option<String>,
     owner_team_id: Option<String>,
+    started_at: chrono::DateTime<chrono::Utc>,
     pid: u32,
     ppid: u32,
 }
@@ -291,6 +306,7 @@ impl McpServerLifecycleMarker {
             workspace: workspace.to_path_buf(),
             agent_id: non_empty_env("TEAM_AGENT_ID"),
             owner_team_id: non_empty_env("TEAM_AGENT_OWNER_TEAM_ID"),
+            started_at: chrono::Utc::now(),
             pid: std::process::id(),
             ppid: parent_pid(),
         }
@@ -300,7 +316,7 @@ impl McpServerLifecycleMarker {
         self.write("mcp.server_started", None, None);
     }
 
-    fn write_tools_list_response_written(&self) {
+    fn write_tools_list_response_written(&self, initialized: bool) {
         let _ = EventLog::new(&self.workspace).write(
             "mcp.tools_list_response_written",
             serde_json::json!({
@@ -313,8 +329,17 @@ impl McpServerLifecycleMarker {
                 "ppid": self.ppid,
                 "spawn_epoch": null,
                 "spawn_epoch_source": "unavailable",
+                "initialize_response_flushed": initialized,
             }),
         );
+        #[cfg(unix)]
+        if initialized {
+            if let (Some(owner), Some(agent)) = (&self.owner_team_id, &self.agent_id) {
+                if let Err(reason) = super::readiness::publish(&self.workspace, owner, agent, self.started_at) {
+                    self.write("mcp.handshake_receipt_failed", Some(reason), None);
+                }
+            }
+        }
     }
 
     fn write_exit(&self, reason: &str, error: Option<&str>) {
@@ -725,6 +750,66 @@ mod e23_lifecycle_marker_tests {
         let _ = std::fs::remove_dir_all(&ws);
     }
 
+    #[cfg(unix)]
+    fn run_bound_handshake<W: Write>(ws: &Path, input: &str, writer: &mut W) -> Result<ServerRunReport, McpError> {
+        let marker = McpServerLifecycleMarker {
+            workspace: ws.to_path_buf(), agent_id: Some("worker".into()),
+            owner_team_id: Some("owner".into()), started_at: chrono::Utc::now(),
+            pid: std::process::id(), ppid: parent_pid(),
+        };
+        run_stdio_loop_inner(&TeamOrchestratorTools::new(ws), std::io::Cursor::new(input.as_bytes()),
+            writer, &mut ServerRunReport::default(), &marker)
+    }
+
+    #[cfg(unix)]
+    fn handshake_receipts(ws: &Path) -> usize {
+        std::fs::read_dir(ws.join(".team/runtime/mcp-handshakes"))
+            .map(|files| files.filter_map(Result::ok)
+                .filter(|file| file.path().extension().is_some_and(|ext| ext == "json")).count())
+            .unwrap_or(0)
+    }
+
+    #[test]
+    #[cfg(unix)]
+    fn stdio_handshake_receipt_requires_initialize_and_tools_list_flush() {
+        let initialize = r#"{"jsonrpc":"2.0","id":1,"method":"initialize"}"#;
+        let tools = r#"{"jsonrpc":"2.0","id":2,"method":"tools/list"}"#;
+        let invalid_initialize = r#"{"jsonrpc":"2.0","method":"initialize"}"#;
+        let invalid_tools = r#"{"jsonrpc":"2.0","method":"tools/list"}"#;
+        for (tag, requests, expected) in [
+            ("init-only", vec![initialize], 0),
+            ("list-only", vec![tools], 0),
+            ("invalid-init", vec![invalid_initialize, tools], 0),
+            ("invalid-list", vec![initialize, invalid_tools], 0),
+            ("ready", vec![initialize, tools], 1),
+        ] {
+            let ws = marker_ws(tag);
+            let mut output = Vec::new();
+            run_bound_handshake(&ws, &(requests.join("\n") + "\n"), &mut output).unwrap();
+            assert_eq!(handshake_receipts(&ws), expected, "{tag}");
+            let _ = std::fs::remove_dir_all(ws);
+        }
+    }
+
+    #[test]
+    #[cfg(unix)]
+    fn stdio_failed_tools_list_flush_cannot_publish_a_handshake() {
+        struct FailSecondFlush(usize);
+        impl Write for FailSecondFlush {
+            fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> { Ok(buf.len()) }
+            fn flush(&mut self) -> std::io::Result<()> {
+                self.0 += 1;
+                if self.0 == 2 { Err(std::io::Error::other("controlled tools/list flush failure")) }
+                else { Ok(()) }
+            }
+        }
+        let ws = marker_ws("handshake-flush-failure");
+        let input = "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\"}\n{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\"}\n";
+        assert!(run_bound_handshake(&ws, input, &mut FailSecondFlush(0)).is_err());
+        assert_eq!(handshake_receipts(&ws), 0);
+        let _ = std::fs::remove_dir_all(ws);
+    }
+
     #[test]
     fn stdio_loop_writes_started_and_stdin_eof_exit_markers() {
         let ws = marker_ws("eof");

package/crates/team-agent/src/messaging/delivery.rs

@@ -302,6 +302,49 @@ fn prepare_message_state(
     Ok(Ok(prepared))
 }
 
+#[cfg(unix)]
+fn mcp_handshake_pending_outcome(
+    store: &MessageStore,
+    event_log: &EventLog,
+    message_id: &str,
+    attempt: u32,
+    reason: &str,
+) -> Result<DeliveryOutcome, MessagingError> {
+    // No paste/key has occurred. Only this exact claim may be released; a
+    // concurrent cancellation or newer delivery must never be overwritten.
+    if !store.release_delivery_before_input(message_id, attempt, reason)? {
+        return Ok(DeliveryOutcome {
+            ok: false,
+            status: DeliveryStatus::Refused,
+            message_status: MessageStatusShadow("target_resolved".to_string()),
+            message_id: Some(message_id.to_string()),
+            verification: None,
+            stage: None,
+            reason: Some(DeliveryRefusal::MessageAlreadyClaimed),
+            channel: None,
+            ack_forced_off: false,
+            turn_verification: None,
+        });
+    }
+    event_log.write("delivery.deferred_mcp_handshake", serde_json::json!({
+        "message_id": message_id,
+        "reason": reason,
+        "effect": "none",
+    }))?;
+    Ok(DeliveryOutcome {
+        ok: false,
+        status: DeliveryStatus::Degraded,
+        message_status: MessageStatusShadow("target_resolved".to_string()),
+        message_id: Some(message_id.to_string()),
+        verification: Some(reason.to_string()),
+        stage: None,
+        reason: None,
+        channel: None,
+        ack_forced_off: false,
+        turn_verification: None,
+    })
+}
+
 fn deliver_prepared_message(
     workspace: &Path,
     store: &MessageStore,
@@ -642,6 +685,25 @@ fn deliver_prepared_message(
             turn_verification: None,
         });
     }
+    // Startup control must remain reachable before protocol admission: some
+    // clients cannot initialize MCP until their trust prompt is answered.
+    // No business input is allowed before the current tools/list flush. A
+    // readiness-only refusal releases this exact claim without spending an
+    // input attempt; it never holds a pane-input lock or sleeps for startup.
+    #[cfg(unix)]
+    {
+        let admission = crate::mcp_server::readiness::preflight(
+            workspace, canonical_owner_team_id.as_deref(), &message.recipient, state,
+        ).and_then(|admission| {
+            if let Some(admission) = admission.as_ref() {
+                crate::mcp_server::readiness::revalidate(admission, &target, &live_targets)?;
+            }
+            Ok(())
+        });
+        if let Err(reason) = admission {
+            return mcp_handshake_pending_outcome(store, event_log, message_id, attempt, reason);
+        }
+    }
     let rendered = render_message(
         &message.sender,
         message.task_id.as_deref(),

package/crates/team-agent/src/messaging/tests/dup_inject.rs

@@ -28,6 +28,44 @@ use crate::transport::{
     TurnVerification, WindowName,
 };
 
+#[test]
+#[cfg(unix)]
+fn eager_mcp_waits_without_spending_input_attempts_then_delivers_the_same_message() {
+    let mut case = WorkerCase::new("mcp-handshake", "cursor_agent");
+    let carrier = crate::mcp_server::readiness::test_carrier_pid().unwrap();
+    let config = case.workspace.join(".team/runtime/mcp/w1.json");
+    std::fs::create_dir_all(config.parent().unwrap()).unwrap();
+    std::fs::write(&config, serde_json::to_vec(&serde_json::json!({
+        "mcpServers": {"team_orchestrator": {
+            "command": std::env::current_exe().unwrap().canonicalize().unwrap(),
+            "env": {"TEAM_AGENT_WORKSPACE": case.workspace, "TEAM_AGENT_ID": "w1", "TEAM_AGENT_OWNER_TEAM_ID": "dup-team"}
+        }}
+    })).unwrap()).unwrap();
+    case.state["team_key"] = serde_json::json!("dup-team");
+    case.state["agents"]["w1"]["mcp_config"] = serde_json::json!(config);
+    case.state["agents"]["w1"]["pane_pid"] = serde_json::json!(carrier);
+    case.state["agents"]["w1"]["spawned_at"] = serde_json::json!((chrono::Utc::now() - chrono::Duration::seconds(10)).to_rfc3339());
+    case.state["teams"] = serde_json::json!({"dup-team": case.state.clone()});
+    crate::state::persist::save_runtime_state(&case.workspace, &case.state).unwrap();
+    let transport = RecordingTransport { carrier: Some(carrier), ..RecordingTransport::new("") };
+    let message_id = case.store.create_message(None, "leader", "w1", "handshake canary", None, false, Some("dup-team")).unwrap();
+    for _ in 0..3 {
+        let outcome = deliver_pending_message(&case.workspace, &case.store, &transport,
+            &message_id, &case.event_log, &case.state).unwrap();
+        assert!(!outcome.ok);
+        assert!(outcome.verification.as_deref().unwrap().starts_with("mcp_handshake_"));
+        assert_eq!(transport.inject_count(), 0);
+    }
+    let connection = rusqlite::Connection::open(case.store.db_path()).unwrap();
+    let attempts: i64 = connection.query_row("select delivery_attempts from messages where message_id=?1", [&message_id], |row| row.get(0)).unwrap();
+    assert_eq!(attempts, 0, "waiting is not a physical delivery attempt");
+    crate::mcp_server::readiness::publish(&case.workspace, "dup-team", "w1", chrono::Utc::now()).unwrap();
+    let outcome = deliver_pending_message(&case.workspace, &case.store, &transport,
+        &message_id, &case.event_log, &case.state).unwrap();
+    assert_eq!(outcome.message_id.as_deref(), Some(message_id.as_str()));
+    assert_eq!(transport.inject_count(), 1, "same queued row proceeds after the real receipt");
+}
+
 #[test]
 fn error_retry_claim_is_single_winner_across_two_delivers() {
     let case = WorkerCase::new("claim-gate", "fake");
@@ -273,6 +311,7 @@ fn poison_state_file(workspace: &Path) {
 struct RecordingTransport {
     injects: Arc<AtomicUsize>,
     capture: Arc<Mutex<String>>,
+    carrier: Option<u32>,
 }
 
 impl RecordingTransport {
@@ -280,6 +319,7 @@ impl RecordingTransport {
         Self {
             injects: Arc::new(AtomicUsize::new(0)),
             capture: Arc::new(Mutex::new(capture.to_string())),
+            carrier: None,
         }
     }
 
@@ -370,7 +410,7 @@ impl Transport for RecordingTransport {
             current_command: Some("sleep".to_string()),
             current_path: None,
             active: true,
-            pane_pid: None,
+            pane_pid: self.carrier,
             leader_env: BTreeMap::new(),
         }])
     }

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

@@ -214,6 +214,13 @@ pub trait ProviderAdapter {
     /// compatible_api 走 `ensure_compatible_claude_mcp_config`)。
     fn mcp_config(&self, auth_mode: AuthMode) -> Result<McpConfig, ProviderError>;
 
+    /// Eager stdio clients must publish their initial MCP handshake before input.
+    /// Pi owns admission in its runtime registry hooks; Fake has no MCP client.
+    /// The process-stamp receipt port is currently POSIX-only, not a Windows claim.
+    fn requires_worker_mcp_handshake(&self) -> bool {
+        cfg!(unix) && !matches!(self.provider(), Provider::Fake | Provider::Pi)
+    }
+
     /// 安装 MCP server。gemini 写全局 `~/.gemini/settings.json` 并备份/还原
     /// (`gemini.py:40-78`)——有副作用 I/O,失败可还原 → Result。
     fn install_mcp(&self, config: &McpConfig) -> Result<(), ProviderError>;

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

@@ -2217,6 +2217,43 @@ fn kill_session_and_kill_window_argv() {
     );
 }
 
+#[test]
+fn issue336_session_listing_accepts_tab_and_literal_escape_without_rewriting_names() {
+    for separator in ["\t", "\\t"] {
+        let (backend, calls) = backend_with(
+            MockResp::Out(ok("")),
+            vec![
+                MockResp::Out(ok(&format!("%7{separator}worker\\tname\n"))),
+                MockResp::Out(ok("%8\n")),
+            ],
+        );
+        backend.preserve_session_before_stop(
+            &SessionName::new("sess"),
+            &[Target::SessionWindow {
+                session: SessionName::new("sess"),
+                window: WindowName::new("worker\\tname"),
+            }],
+        ).unwrap();
+        assert_eq!(calls.lock().unwrap().len(), 4, "separator={separator:?}");
+    }
+}
+
+#[test]
+fn issue336_escaped_listing_keeps_survivors_and_malformed_rows_fail_closed() {
+    let (backend, calls) = backend_with(MockResp::Out(ok("%7\\tworker\n%8\\tleader\n")), vec![]);
+    backend.preserve_session_before_stop(
+        &SessionName::new("sess"), &[Target::Pane(PaneId::new("%7"))],
+    ).unwrap();
+    assert_eq!(calls.lock().unwrap().len(), 1);
+    for row in ["%7 worker", "%7", ""] {
+        let (backend, calls) = backend_with(MockResp::Out(ok(row)), vec![]);
+        assert!(backend.preserve_session_before_stop(
+            &SessionName::new("sess"), &[Target::Pane(PaneId::new("%7"))],
+        ).is_err());
+        assert_eq!(calls.lock().unwrap().len(), 1);
+    }
+}
+
 #[test]
 fn stop_session_preservation_creates_processless_anchor_by_exact_pane_id() {
     let (be, rec) = backend_with(

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

@@ -4201,13 +4201,20 @@ impl Transport for TmuxBackend {
             return Err(subprocess_error(list_argv, output));
         }
         for line in output.stdout.lines() {
-            let Some((pane, window)) = line.split_once('\t') else {
+            // Some tmux/runner combinations return the literal escape. Split
+            // only the first column boundary; window names are not unescaped.
+            let separator = line.find('\t').map(|at| (at, 1)).into_iter()
+                .chain(line.find("\\t").map(|at| (at, 2)))
+                .min_by_key(|(at, _)| *at);
+            let Some((at, width)) = separator else {
                 return Err(TransportError::Subprocess {
                     argv: list_argv,
                     code: output.code,
                     stderr: "tmux returned an invalid session pane listing".to_string(),
                 });
             };
+            let (pane, rest) = line.split_at(at);
+            let window = &rest[width..];
             if !targets.iter().any(|target| match target {
                 Target::Pane(id) => id.as_str() == pane,
                 Target::SessionWindow {

package/package.json

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

package/skills/team-agent/SKILL.md

@@ -5,27 +5,30 @@ requires_team_agent: ">=0.5.0"
 ---
 # Team Agent
 
-The current assistant is the **leader**. Workers use separate role files and report through Team Agent. Start from a tmux-addressable terminal or supported agent pane, in the workspace root (the parent of the team directory).
+Use the authorized **Leader's** native tool context for lifecycle operations. Workers report through their team-scoped MCP tools; loading this skill does not promote a worker to Leader. Operate in the workspace root, not inside another team's role directory.
 
-## Decide before creating a team
+## Check the actual CLI
+
+Check `team-agent --version`, `team-agent start --help` and `team-agent team --help` before using this guide. It requires the intuitive `start`, `stop`, `team` and `agent` surface. A version string or this skill's compatibility floor is not proof those commands exist. If missing, ask for an authorized installation of a supporting build; do not silently switch binaries, rewrite bindings or fall back to an old creation recipe.
+
+## User decisions come first
 
 **The user decides each worker's provider and permission bypass. Do not silently choose Pi, true, or false.** Reuse an explicit user policy when it covers the worker; otherwise explain the choices and ask before starting.
 
-Use existing resources rather than establishing new accounts: `team-agent doctor --workspace . --json` reports discovered tools, but installed does not mean authenticated and an absent entry or unknown auth is not proof of unavailability. For providers supported by `models`, use `team-agent models --provider NAME` to check exact model IDs. Do not inspect credentials, automatically log in, or silently substitute a provider after a failed probe.
+Use existing resources rather than establishing accounts. `team-agent doctor --workspace . --json` reports discovered tools; installed is not authenticated, and an unknown probe is not proof of unavailability. Use `team-agent models --provider NAME` where supported for exact model IDs. Do not inspect credentials, automatically log in, or silently substitute providers.
 
-| Choice | What to explain |
+| Choice | Explain |
 |---|---|
-| Pi | One Agent tool can use several model catalogs; explicit models require a qualified ID such as `openai-codex/gpt-6-luna` |
-| Codex | The user's existing Codex workflow, native tools, permissions and resumable sessions |
-| Claude / Claude Code | The user's existing Claude workflow, models, native tools and session behavior |
-| Bypass `true` | Fewer permission interruptions, but broader automatic execution authority |
-| Bypass `false` | Keep the selected tool's native permissions; human confirmation may interrupt unattended work |
+| Pi | Several model catalogs; an explicit model needs a qualified ID such as `openai-codex/gpt-6-luna` |
+| Codex / Claude / other native CLIs | The user's existing workflow, native permissions, model catalog and supported session capabilities |
+| Bypass `true` | Fewer interruptions, broader automatic authority |
+| Bypass `false` | Native permissions remain; human confirmation may interrupt unattended work |
 
-False is **not** a read-only or sandbox guarantee. Native permission capabilities differ between tools. Suggest combinations based on the user's installed tools, subscriptions and task: for example, an explicitly chosen Codex implementer and Claude reviewer, or two Pi workers when those are the available resources. Different workers may use different providers; an existing worker cannot change provider.
+False is **not** a read-only or sandbox guarantee. Different workers may use different providers; an existing worker cannot change provider. Do not invent a model or effort when the user left it unset.
 
-## Create and start
+## Prepare once, start every day
 
-Keep the goal in `TEAM.md` and each worker's instructions in `agents/*.md`. The filename stem is the worker's in-team short name.
+Keep the goal in `TEAM.md` and each worker's instructions in `agents/*.md`. The filename stem is the worker's in-team short name:
 
 ```text
 .team/current/
@@ -33,7 +36,7 @@ Keep the goal in `TEAM.md` and each worker's instructions in `agents/*.md`. The
   agents/reviewer.md
 ```
 
-For a **new plan**, record the user's two decisions in every role. This example assumes the user selected Pi and bypass false; it is not a default:
+Record provider and boolean bypass in every new role. This example assumes the user explicitly chose Pi and bypass false; it is not a default:
 
 ```markdown
 ---
@@ -43,43 +46,58 @@ dangerously_skip_permissions: false
 Review the change and report concrete regression risks.
 ```
 
+From the authorized Leader context, select the intended workspace/team:
+
 ```sh
-team-agent quick-start .team/current
-team-agent send reviewer "Review this change"
-team-agent inbox reviewer -n 3
+team-agent start --from .team/current --workspace . --team project-team
+team-agent start --workspace . --team project-team
+team-agent send reviewer "Review this change" --workspace . --team project-team
+team-agent inbox leader --workspace . --team project-team -n 3
 ```
 
-Traditional file-based quick-start/compile behavior remains supported, including legacy minimal role documents; no conversion to CLI-created roles is required. Legacy interpretation is not permission to silently choose settings for a new user plan. Model and effort may remain unset; preserve the existing file compiler's native/default interpretation rather than inventing a model or effort.
+The first `start` creates a complete configured team through the original creation path. Later `start` keeps physically verified, drift-free live seats unchanged and starts stopped non-paused seats, including explicitly stopped seats. It is not a reset. Missing configuration, ambiguous scope or unknown physical identity is a refusal, not permission to overwrite state. `--dry-run` plans without lifecycle effects; final locked admission is still deferred.
+
+Accepted/queued send is **not** the worker's answer. Wait for a natural reply/result. `ok: true` with pending readiness is not business readiness. A live no-op does not synchronize edited role bodies or apply changed launch settings.
 
-To add a **new** seat to an existing team, provider and bypass must be explicitly defined in the CLI or role file. A complete traditional role file needs no repeated flags. If both sources define a field, equal values are accepted and **conflicting values are rejected before any write or startup**:
+## Stop, wake and restart
 
 ```sh
-# These values must be the user's choices, not inferred defaults.
-team-agent add-agent analyst --provider pi --bypass true --prompt "Analyze the proposed change"
-# auditor.md already contains the user's provider and bypass decisions.
-team-agent add-agent auditor --role-file /absolute/path/to/auditor.md
+team-agent stop reviewer --workspace . --team project-team
+team-agent start reviewer --workspace . --team project-team
+team-agent restart reviewer --workspace . --team project-team
+team-agent stop --workspace . --team project-team --json
+team-agent start --workspace . --team project-team
+team-agent team restart --workspace . --team project-team --json
 ```
 
-Add creates and immediately starts the seat. Ordinary add rejects an occupied ID, including stopped seats. Disaster recovery has one explicit exception: `add-agent ID --role-file FILE --force` may reuse the existing force-recreate lifecycle only when the registered old pane is positively confirmed dead and no live target cohort exists. A live seat or unknown/missing death proof is refused; force is not a routine configuration-update shortcut. External role files are imported into the team's `agents/ID.md` and left untouched. A file already at that path is used in place, without copying itself.
+| Intent | Rule |
+|---|---|
+| `start AGENT` | Wake a stopped registered seat; verified live/no-drift is a no-op. A RoleOnly seat can be added from its complete role file |
+| `start` | Explicitly activate the selected non-paused roster; do not use it unless that activation is authorized |
+| `stop AGENT` / `stop` | Retain saved session associations; whole-team stop also checks scoped residual resources |
+| `restart AGENT` / `team restart` | Default `--session auto`: resume when proven, otherwise only the original legal fresh fallback. **Auto does not guarantee preserved memory** |
+| `--session preserve` | Require available continuation evidence; refuse before stopping when continuation is known unavailable |
+
+Team restart preserves explicitly stopped and paused seats; use `start` when intentionally waking the roster. Paused seats are not implicitly unpaused. A same-named directory makes `restart ID` ambiguous: use `agent restart ID`. `reviewer.v2` remains an agent ID; choose a team source with `--from DIR`, `team start DIR` or an explicit path such as `./roles`.
+
+For strict recovery, prefer `team-agent team restart --session preserve --workspace . --team project-team`. Do not convert a refusal or partial/unknown replacement into reset, force or blind retry. Inspect `status`/`doctor` in the same scope first. Native unsupported capabilities remain refusals, never a legacy fallback.
 
-## Change and start an existing worker
+## Add or change one worker
 
-**Stop first if it is running.** Start never implicitly kills or restarts a running worker:
+With the user's provider/bypass choices, `start` unifies adding an absent seat and waking an existing one:
 
 ```sh
-team-agent stop-agent reviewer
-team-agent start-agent reviewer --effort high --bypass true
-team-agent stop-agent reviewer
-team-agent start-agent reviewer --prompt "Review only regression risks; do not change product code"
+team-agent start auditor --role-file /absolute/path/to/auditor.md
+team-agent start analyst --provider pi --bypass false --prompt "Analyze the proposed change"
+team-agent stop reviewer
+team-agent start reviewer --effort high --bypass false
 ```
 
-Start updates the same role file and recompiles it before normal startup. Omitted options preserve the file's values and body; `--prompt` replaces the permanent role body, not a one-time task message. `--bypass true` and `--bypass false` are explicit values, not bare switches. Model, effort and an existing profile can also be set. Direct file edits followed by start use the same reload path.
+The Pi/false example above still requires the user's explicit choices. File/CLI conflicts are rejected before writing or startup. Omitted settings/body are preserved; `--prompt` replaces the permanent role body, not a one-time task. Stop a running worker before changing settings or instructions. Provider changes are refused. Startup failure restores role/spec bytes and reports failure, not an applied update.
 
-A different `--provider`, including a manually edited role provider, is rejected before launch. A matching provider is allowed. Create a separate ID to use a different engine. If startup fails, the role file and runtime spec are restored to their pre-command contents; the command reports failure, not an applied update.
+Use `agent add/remove/reset/clone/fork` only for those explicit operations. Reset needs intentional approval and `--discard-session`; fork requires `--as NEW_ID`, and `--in-place` is not supported. See [the operator reference](references/team-agent-operator.md) for capability, profile, force and import boundaries. Never put secrets in role text or copy authentication from another directory.
 
-Profiles keep provider authentication, endpoints and custom-model settings local. Imported roles use this team's/workspace's `profiles`, never the original external directory. Prepare a named profile locally through the public profile commands; do not search for or copy external credentials. Never put secrets in `TEAM.md` or a role file. See [the operator reference](references/team-agent-operator.md) for existing profile and field details. Supported metadata also includes `agent_id` (legacy `name`), `role`, `auth_mode`, and `communication_mode`; old `tools`, `permission_mode`, and `label` keys do not configure a worker.
-
-## Global native CLI argv (optional)
+## Optional native CLI argv routing
 
 Default OFF; no workspace or provider login is needed to manage routes:
 
@@ -93,29 +111,28 @@ team-agent route clear pi
 team-agent route disable
 ```
 
-`set` replaces one mapping, `add` appends without deduplication, `clear` removes it;
-none changes the switch. `enable`/`disable` preserve mappings in `~/.team-agent/argv-routing.json`.
-`TEAM_AGENT_CLI_ARGV_ROUTING` overrides the switch: `1/true/on`, `0/false/off` (case-insensitive,
-trimmed); invalid values disable routing. Check `persisted_enabled`, `effective_enabled` and
-`override_status` rather than assuming `enable` defeats an environment OFF.
+`set` replaces one mapping, `add` appends without deduplication, `clear` removes it; none changes the switch. `enable`/`disable` preserve mappings in `~/.team-agent/argv-routing.json`. `TEAM_AGENT_CLI_ARGV_ROUTING` overrides the switch: `1/true/on`, `0/false/off` (case-insensitive, trimmed); invalid values disable routing. Check `persisted_enabled`, `effective_enabled` and `override_status`.
 
-Keys: `claude`, `codex`, `copilot`, `gemini_cli`, `grok`, `cursor_agent`, `pi`.
-Claude/Claude Code share `claude`; aliases `claude_code/claude-code`, `agent/cursor` are accepted.
-The first `--` ends control parsing: subsequent tokens, including `--help`, `--json`, empty strings
-and `{workspace}`, are literal data. Tokens go after the executable and before its original tail;
-there is no shell expansion. Do not route secrets or override framework-managed session/MCP/permission flags.
+Keys: `claude`, `codex`, `copilot`, `gemini_cli`, `grok`, `cursor_agent`, `pi`. Claude/Claude Code share `claude`; aliases `claude_code/claude-code`, `agent/cursor` are accepted. Everything after the first `--`, including `--help`, `--json`, empty strings and `{workspace}`, is literal argv. No shell expansion. Do not route secrets or override framework-managed session/MCP/permission flags.
 
-The current mapping affects the next actual Leader/worker spawn (also restart, single-seat start/reset,
-add/clone, Pi new-seat fork and remove rollback), not running/attached processes, dry-run or helper probes.
-Enabled bad configuration prevents native spawn; an emergency environment OFF avoids reading it,
-while `route disable` will not overwrite a broken file. Pi `--mode rpc` does not provide an RPC host
-or change the existing Team Agent transport.
+Mappings affect the next actual native spawn, not running/attached processes, dry-run or helper probes. Invalid enabled configuration refuses spawn; an emergency environment OFF avoids reading it, while `route disable` will not overwrite a broken file. Pi `--mode rpc` does not provide an RPC host or replace Team Agent's transport.
 
-## Inspect and stop
+## Observe, communicate and clean up
 
-Use `team-agent status --json` for readiness and the installed command's `--help` for syntax. `ok: true` with `ready: false` means the team is not ready; follow the reported action. Accepted/queued send is not the worker's reply: wait for a natural response or result. Use `<workspace>::<team>/<agent>` when a fully qualified recipient is needed.
+Use `team-agent status --json` (or `team status`) for the concise node projection and `doctor` for diagnosis; `--detail` does not restore old internal status dumps. Use `<workspace>::<team>/<agent>` for an explicitly qualified logical recipient, or the in-team short name. Workers have exactly `send_message`, `report_result` and optional `get_team_status`; lifecycle stays on the authorized CLI. Read [nested teams](references/team-in-team.md) only when explicitly requested and [recovery](references/recovery-runbook.md) for incidents.
 
-Worker MCP provides `send_message`, `report_result`, and `get_team_status`. Lifecycle actions remain on the authorized CLI. See [nested teams](references/team-in-team.md) only when needed. Stop the selected team with `team-agent shutdown --workspace .` when authorized.
+Finish with `team-agent stop --workspace . --team project-team --json` when authorized. Check the actual scoped residual report; exit0 alone is not proof of zero resources. Do not kill shared servers or touch sibling workspaces.
 
----
-This skill is a concise public guide. Do not infer a tested version from package metadata; verify the installed CLI with `team-agent --version` when version-specific behavior matters.
+## Compatibility bridges, not the daily workflow
+
+Old commands remain available for existing scripts; their output/defaults are not silently rewritten:
+
+| Compatibility entry | Preferred daily surface |
+|---|---|
+| `quick-start` | `start --from TEAMDIR` for creation and later `start` for activation |
+| `shutdown` | `stop` / `team stop` |
+| `add-agent` / `start-agent` / `stop-agent` | `agent add` for strict add, or `start AGENT` / `stop AGENT` |
+| `remove-agent` / `reset-agent` / `clone-agent` / `fork-agent` | The corresponding `agent` operation |
+| Bare or explicit-path `restart` | Frozen preserve bridge; deliberate `team restart` defaults to auto |
+
+These are not all byte-equivalent aliases: legacy single-seat start refuses a running seat, while new start can prove a no-op. Do not mechanically rename automation, assume unsupported provider capabilities, or infer deployment from package metadata.