@team-agent/installer 0.4.1 → 0.4.2

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

@@ -0,0 +1,358 @@
+//! Stage 0 of the identity-boundary unified plan (architect direction
+//! 2026-06-23): `TeamScope` + `TeamRuntimePaths` foundation.
+//!
+//! This module is **pure additive** — it does NOT change existing on-disk
+//! paths or behaviour. It introduces a shared vocabulary that Stage 2 (owner
+//! repository), Stage 5 (per-team runtime state), and Stage 6 (per-team
+//! coordinator) will all consume, so that no later stage has to hand-build
+//! `.team/runtime/<team_key>/...` paths or guess the canonical team_key from
+//! a display name.
+//!
+//! Canonical rules:
+//! - `team_key` is the IDENTITY of a team within a workspace. Display name
+//!   (`team_dir.file_name()`) is NOT identity — two `agentX` dirs under
+//!   different parents must end up with different team_keys.
+//! - For the foundation slice, `TeamScope::new(team_key)` accepts whatever
+//!   the caller already resolved (state/selector + state/persist already do
+//!   this work). Slug/hash promotion to global uniqueness lands in Stage 5.
+//! - `TeamRuntimePaths` is the SINGLE place where the
+//!   `.team/runtime/<team_key>/` layout is constructed. Anywhere downstream
+//!   code today hand-joins `runtime_dir(ws).join(team_key).join(...)` it
+//!   should migrate to call a method on `TeamRuntimePaths` in a later stage.
+//!
+//! Single-team behaviour: unchanged. The foundation does not move data, does
+//! not introduce new files, and is invoked by zero existing call sites yet.
+
+use std::path::{Path, PathBuf};
+
+use crate::model::paths::{runtime_dir, runtime_spec_path};
+use crate::state::persist::load_runtime_state;
+use crate::state::projection::team_state_candidates;
+
+/// The identity of a team within a workspace. Carries the *workspace root*
+/// and the *canonical team_key* (the directory name that state/selector
+/// resolves; see `runtime_spec_path(workspace, team_key)`).
+///
+/// `TeamScope` is the input to `TeamRuntimePaths`. It deliberately does not
+/// store a display name — display name is a UX label, not an identity.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct TeamScope {
+    workspace: PathBuf,
+    team_key: String,
+}
+
+impl TeamScope {
+    /// Construct a TeamScope from an already-resolved workspace + team_key.
+    /// Callers that have a display name must resolve it through the existing
+    /// `state::selector` machinery first; this constructor refuses an empty
+    /// team_key because that would silently fall through to the workspace
+    /// root (the exact ambiguity Stage 5 is trying to eliminate).
+    pub fn new(workspace: impl Into<PathBuf>, team_key: impl Into<String>) -> Option<Self> {
+        let team_key = team_key.into();
+        if team_key.is_empty() {
+            return None;
+        }
+        Some(Self {
+            workspace: workspace.into(),
+            team_key,
+        })
+    }
+
+    pub fn workspace(&self) -> &Path {
+        &self.workspace
+    }
+
+    pub fn team_key(&self) -> &str {
+        &self.team_key
+    }
+
+    /// Convenience: derive the path helper from this scope.
+    pub fn paths(&self) -> TeamRuntimePaths {
+        TeamRuntimePaths::for_scope(self)
+    }
+}
+
+/// Single source of `.team/runtime/<team_key>/...` path construction.
+///
+/// Stage 2 (owner repository), Stage 5 (per-team state), Stage 6 (per-team
+/// coordinator), and Stage 7 (per-team tmux socket) will all migrate from
+/// hand-built paths to `TeamRuntimePaths`. Today nothing reads from these
+/// methods yet — the foundation just owns the layout decision so when later
+/// stages start writing `.team/runtime/<team_key>/state.json` (Stage 5) or
+/// `.team/runtime/<team_key>/coordinator.pid` (Stage 6), there is exactly
+/// one place to change the layout.
+#[derive(Debug, Clone)]
+pub struct TeamRuntimePaths {
+    workspace: PathBuf,
+    team_key: String,
+}
+
+impl TeamRuntimePaths {
+    pub fn new(workspace: impl Into<PathBuf>, team_key: impl Into<String>) -> Self {
+        Self {
+            workspace: workspace.into(),
+            team_key: team_key.into(),
+        }
+    }
+
+    pub fn for_scope(scope: &TeamScope) -> Self {
+        Self::new(scope.workspace().to_path_buf(), scope.team_key().to_string())
+    }
+
+    pub fn workspace(&self) -> &Path {
+        &self.workspace
+    }
+
+    pub fn team_key(&self) -> &str {
+        &self.team_key
+    }
+
+    /// `.team/runtime/<team_key>/` — the team's runtime directory. Today this
+    /// already exists (runtime_spec lives under it). Stage 5 will start
+    /// writing `state.json` here too.
+    pub fn team_dir(&self) -> PathBuf {
+        runtime_dir(&self.workspace).join(&self.team_key)
+    }
+
+    /// `.team/runtime/<team_key>/team.spec.yaml` — runtime spec. Mirrors the
+    /// existing `runtime_spec_path` helper; provided here so downstream
+    /// callers don't need to import two layout APIs.
+    pub fn spec_path(&self) -> PathBuf {
+        runtime_spec_path(&self.workspace, &self.team_key)
+    }
+
+    /// `.team/runtime/<team_key>/state.json` — the canonical per-team state
+    /// path that Stage 5 will start writing. Not used by Stage 0 product
+    /// code; callers must continue using `runtime_state_path` until Stage 5
+    /// migrates the truth source.
+    pub fn state_path(&self) -> PathBuf {
+        self.team_dir().join("state.json")
+    }
+
+    /// `.team/runtime/<team_key>/coordinator.pid` — Stage 6 sidecar location.
+    pub fn coordinator_pid_path(&self) -> PathBuf {
+        self.team_dir().join("coordinator.pid")
+    }
+
+    /// `.team/runtime/<team_key>/coordinator.log` — Stage 6 sidecar location.
+    pub fn coordinator_log_path(&self) -> PathBuf {
+        self.team_dir().join("coordinator.log")
+    }
+}
+
+/// Stage 4 of identity-boundary unified plan (architect direction
+/// 2026-06-24, .team/artifacts/identity-boundary-unified-plan.md §2 Stage
+/// 4): the CLI ambiguity gate for destructive commands. Pre-Stage-4 a
+/// bare `shutdown` / `restart` / `reset-agent` / etc. on a workspace with
+/// two alive teams silently picked the first one — exactly the
+/// "active_team_key as destructive command authority" anti-pattern §4 不可改项
+/// rejects. `CommandScope` makes this state explicit.
+///
+/// Usage from CLI dispatch:
+///     let scope = CommandScope::resolve(workspace, args.team.as_deref());
+///     scope.require_unambiguous_for_destructive(&workspace)?;
+///
+/// For single-team workspaces (the 0.4.x baseline) `Unambiguous` is
+/// returned and the gate is a no-op. For two+ alive teams the gate
+/// refuses with a `MissingTeamScope` error listing the candidates.
+#[derive(Debug, Clone)]
+pub enum CommandScope {
+    /// Caller passed `--team X` explicitly (or there's only one alive team
+    /// and we resolved it). Carries the canonical team_key.
+    Resolved(String),
+    /// No `--team` and multiple alive teams. Destructive commands MUST
+    /// refuse with this list of candidates so the operator chooses
+    /// explicitly. Read-only commands may still proceed (their scope is
+    /// "all teams" by default).
+    Ambiguous(Vec<String>),
+    /// No `--team` and no teams alive yet (fresh workspace) — bare
+    /// commands fall through to legacy single-team behaviour.
+    EmptyWorkspace,
+}
+
+impl CommandScope {
+    /// Resolve the CLI's `--team` argument against the workspace state.
+    /// On any I/O error the empty case is returned — destructive commands
+    /// will run their own selector and surface the real error.
+    pub fn resolve(workspace: &Path, requested_team: Option<&str>) -> Self {
+        if let Some(team) = requested_team.filter(|t| !t.is_empty()) {
+            return Self::Resolved(team.to_string());
+        }
+        let Ok(state) = load_runtime_state(workspace) else {
+            return Self::EmptyWorkspace;
+        };
+        let alive = team_state_candidates(&state);
+        match alive.len() {
+            0 => Self::EmptyWorkspace,
+            1 => Self::Resolved(
+                alive.keys().next().cloned().unwrap_or_default(),
+            ),
+            _ => {
+                let mut keys: Vec<String> = alive.keys().cloned().collect();
+                keys.sort();
+                Self::Ambiguous(keys)
+            }
+        }
+    }
+
+    /// Convert to an `Option<String>` for backward compatibility with
+    /// existing `args.team.as_deref()` call sites.
+    pub fn team_key(&self) -> Option<&str> {
+        match self {
+            Self::Resolved(key) => Some(key.as_str()),
+            _ => None,
+        }
+    }
+
+    /// True iff there are 2+ alive teams and no explicit `--team`.
+    pub fn is_ambiguous(&self) -> bool {
+        matches!(self, Self::Ambiguous(_))
+    }
+
+    /// The candidate list when ambiguous; empty otherwise.
+    pub fn candidates(&self) -> &[String] {
+        match self {
+            Self::Ambiguous(keys) => keys,
+            _ => &[],
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn team_scope_refuses_empty_team_key() {
+        assert!(TeamScope::new(PathBuf::from("/ws"), "").is_none());
+    }
+
+    #[test]
+    fn team_scope_accepts_workspace_and_team_key() {
+        let scope = TeamScope::new(PathBuf::from("/ws"), "alpha").unwrap();
+        assert_eq!(scope.workspace(), Path::new("/ws"));
+        assert_eq!(scope.team_key(), "alpha");
+    }
+
+    #[test]
+    fn team_runtime_paths_layout_matches_existing_runtime_dir_layout() {
+        let paths = TeamRuntimePaths::new(PathBuf::from("/ws/proj"), "alpha");
+        assert_eq!(paths.team_dir(), PathBuf::from("/ws/proj/.team/runtime/alpha"));
+        assert_eq!(
+            paths.spec_path(),
+            PathBuf::from("/ws/proj/.team/runtime/alpha/team.spec.yaml")
+        );
+        assert_eq!(
+            paths.state_path(),
+            PathBuf::from("/ws/proj/.team/runtime/alpha/state.json")
+        );
+        assert_eq!(
+            paths.coordinator_pid_path(),
+            PathBuf::from("/ws/proj/.team/runtime/alpha/coordinator.pid")
+        );
+    }
+
+    #[test]
+    fn two_different_team_keys_in_same_workspace_get_different_paths() {
+        let alpha = TeamRuntimePaths::new(PathBuf::from("/ws"), "alpha");
+        let beta = TeamRuntimePaths::new(PathBuf::from("/ws"), "beta");
+        assert_ne!(alpha.team_dir(), beta.team_dir());
+        assert_ne!(alpha.state_path(), beta.state_path());
+        assert_ne!(alpha.coordinator_pid_path(), beta.coordinator_pid_path());
+    }
+
+    #[test]
+    fn team_scope_to_paths_round_trip() {
+        let scope = TeamScope::new(PathBuf::from("/ws"), "alpha").unwrap();
+        let paths = scope.paths();
+        assert_eq!(paths.workspace(), scope.workspace());
+        assert_eq!(paths.team_key(), scope.team_key());
+    }
+
+    // ─────────────── Stage 4: CommandScope tests ───────────────
+
+    fn tmp_workspace(label: &str) -> PathBuf {
+        let n = std::time::SystemTime::now()
+            .duration_since(std::time::UNIX_EPOCH)
+            .map(|d| d.as_nanos())
+            .unwrap_or(0);
+        let ws = std::env::temp_dir().join(format!(
+            "ta_cmdscope_{}_{}_{}",
+            label,
+            std::process::id(),
+            n
+        ));
+        std::fs::create_dir_all(&ws).unwrap();
+        ws
+    }
+
+    #[test]
+    fn command_scope_explicit_team_always_wins() {
+        let ws = tmp_workspace("explicit");
+        let scope = CommandScope::resolve(&ws, Some("alpha"));
+        assert_eq!(scope.team_key(), Some("alpha"));
+        assert!(!scope.is_ambiguous());
+    }
+
+    #[test]
+    fn command_scope_empty_workspace_falls_through() {
+        let ws = tmp_workspace("empty");
+        // No state file written.
+        let scope = CommandScope::resolve(&ws, None);
+        assert!(scope.team_key().is_none());
+        assert!(!scope.is_ambiguous());
+        assert!(matches!(scope, CommandScope::EmptyWorkspace));
+    }
+
+    #[test]
+    fn command_scope_single_alive_team_resolves_automatically() {
+        let ws = tmp_workspace("single");
+        crate::state::persist::save_runtime_state(
+            &ws,
+            &serde_json::json!({
+                "teams": {"alpha": {"status": "alive"}},
+            }),
+        )
+        .unwrap();
+        let scope = CommandScope::resolve(&ws, None);
+        assert_eq!(scope.team_key(), Some("alpha"));
+        assert!(!scope.is_ambiguous());
+    }
+
+    #[test]
+    fn command_scope_two_alive_teams_no_explicit_team_is_ambiguous() {
+        let ws = tmp_workspace("multi");
+        crate::state::persist::save_runtime_state(
+            &ws,
+            &serde_json::json!({
+                "teams": {
+                    "alpha": {"status": "alive"},
+                    "beta": {"status": "alive"},
+                },
+            }),
+        )
+        .unwrap();
+        let scope = CommandScope::resolve(&ws, None);
+        assert!(scope.is_ambiguous());
+        assert_eq!(scope.candidates(), &["alpha".to_string(), "beta".to_string()]);
+    }
+
+    #[test]
+    fn command_scope_archived_team_does_not_count_as_alive() {
+        let ws = tmp_workspace("archived");
+        crate::state::persist::save_runtime_state(
+            &ws,
+            &serde_json::json!({
+                "teams": {
+                    "alpha": {"status": "alive"},
+                    "beta": {"archived_at": "2026-06-01T00:00:00Z"},
+                },
+            }),
+        )
+        .unwrap();
+        let scope = CommandScope::resolve(&ws, None);
+        // Only alpha counts → not ambiguous, resolves to alpha.
+        assert_eq!(scope.team_key(), Some("alpha"));
+        assert!(!scope.is_ambiguous());
+    }
+}

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

@@ -204,14 +204,22 @@ fn save_runtime_state_with_merge_exceptions(
     skip_capture_backfill_agent_ids: &[&str],
 ) -> Result<(), StateError> {
     let path = runtime_state_path(workspace);
-    if cache_equals(&path, state) {
-        return Ok(());
-    }
     // Python `state.py:497`:先对入参 state 跑 `_migrate_state_identity`(就地填缺失 leader uuid)。
     // 我们 `&Value` 不可变 → 克隆后迁移,后续比较/写入/缓存/self-heal 全走 `migrated`。
     // 该步**不**包 try/except → 错误 propagate(对齐 Python)。
     let mut migrated = state.clone();
     migrate_state_identity(&mut migrated, &SystemEnv, workspace)?;
+    // Stage 3 save-output canonical-aware strip (architect direction
+    // 2026-06-24, .team/artifacts/stage3-save-strip-fix.md): when the
+    // state carries a canonical `teams.<active>.team_owner` record, drop
+    // the legacy top-level `team_owner / leader_receiver / owner_epoch`
+    // before any cache comparison. The pre-fix order ran a `cache_equals`
+    // check against the RAW (pre-strip) state at the function entry — if
+    // disk and cache were already in the dual-source (post-restart /
+    // post-shutdown) shape, the early return would skip the cleanup
+    // entirely. Moving migrate+strip ahead of every cache_equals makes
+    // the canonical-only shape the cache invariant for new writes.
+    crate::state::ownership::strip_top_level_ownership_if_canonical_present(&mut migrated);
     if cache_equals(&path, &migrated) {
         return Ok(());
     }
@@ -224,6 +232,14 @@ fn save_runtime_state_with_merge_exceptions(
             if let Ok(mut existing) = serde_json::from_str::<Value>(&text) {
                 normalize_agent_session_state(&mut existing);
                 let _ = migrate_state_identity(&mut existing, &SystemEnv, workspace);
+                // Stage 3 save-output strip applied to `existing` too so
+                // the equality comparison is between two canonical-only
+                // shapes. Without this, a pre-fix dual-source disk state
+                // would never match the post-fix canonical-only `migrated`
+                // and would force a spurious rewrite on every save.
+                crate::state::ownership::strip_top_level_ownership_if_canonical_present(
+                    &mut existing,
+                );
                 if existing == migrated {
                     cache_set(&path, &migrated);
                     return Ok(());
@@ -257,6 +273,12 @@ fn save_runtime_state_with_merge_exceptions(
             &skip_capture_backfill,
         );
     }
+    // Stage 3 save-output strip second pass (defence-in-depth): after the
+    // `preserve_latest_roster_entries` lock-held merge, a future addition
+    // to the preserve path could re-introduce root owner fields from the
+    // on-disk latest. Re-strip here so the serialized payload is always
+    // canonical-only when a canonical teams.<key>.team_owner is present.
+    crate::state::ownership::strip_top_level_ownership_if_canonical_present(&mut migrated);
     // 字节对拍 Python json.dumps(indent=2, ensure_ascii=False)(无尾换行)。
     let payload = serde_json::to_string_pretty(&migrated)?;
     let delays = [0.05_f64, 0.2, 0.5];
@@ -331,7 +353,16 @@ fn preserve_latest_roster_entries(
             skip_top_level_capture_backfill,
             skip_capture_backfill_agent_ids,
         );
-        preserve_latest_ownership_fields(incoming, latest);
+        // Stage 3c (identity-boundary unified plan, architect direction
+        // 2026-06-23): top-level owner copy-back removed. Pre-3c this
+        // copied legacy `state.{team_owner, leader_receiver, owner_epoch}`
+        // from disk's latest back into the incoming save — the persist-side
+        // mirror of the projection promote that 3b removed. With Stage 3a's
+        // write_owner funneling all owner mutations and 3b's projection
+        // cleanup, top-level owner truth is no longer authoritative; the
+        // teams.<key> entry-scoped preservation at :370 remains so legacy
+        // teams.<key>.team_owner entries still survive a save that omits
+        // them.
     }
 
     if projection_matches {
@@ -381,7 +412,14 @@ fn preserve_latest_roster_entries(
                     should_skip_capture_backfill(Some(active_team), skip_capture_backfill_team_key),
                     skip_capture_backfill_agent_ids,
                 );
-                preserve_latest_ownership_fields(incoming_entry, latest);
+                // Stage 3c (identity-boundary unified plan, architect direction
+                // 2026-06-23): top-level → teams.<active> owner cross-promote
+                // removed. This was the persist-side mirror of the projection
+                // copy-back (3b) and a quiet migration path that let stale
+                // top-level owner re-seed teams.<active>. With write_owner
+                // (3a) producing both top-level and teams.<key> directly,
+                // this auto-promotion is redundant and reintroduces the dual
+                // source the unified plan eliminates.
             }
         }
     }

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

@@ -317,17 +317,25 @@ pub fn project_top_level_view(state: &Value, team_key: &str) -> Value {
         .get("teams")
         .and_then(Value::as_object)
         .is_some_and(|teams| !teams.is_empty());
-    // owner binding is team-scoped: never borrow another team's top-level binding.
+    // Stage 3b (identity-boundary unified plan, architect direction 2026-06-23):
+    // remove the top-level owner promote. Pre-3b, when `teams.<key>` lacked
+    // an owner entry the projection promoted the legacy top-level
+    // `state.team_owner` into the projected view — that's the
+    // "copy-back/promotion" the architect §Stage 3 calls out as the
+    // dual-source bug origin (stale top-level owner could be served to
+    // callers of a different team's projection). Now only the canonical
+    // teams.<key> branch promotes; callers needing the legacy top-level
+    // path must go through `state::ownership::read_owner_for_team` whose
+    // precedence rule applies the migration-precedence semantics
+    // explicitly (architect §3: teams > top-level only when
+    // team_state_key matches).
     if let Some(v) = entry_obj.get("team_owner") {
         p.insert("team_owner".to_string(), v.clone());
-    } else if !has_team_entries && state.get("team_owner").is_some_and(|v| !v.is_null()) {
-        p.insert("team_owner".to_string(), state["team_owner"].clone());
     }
     if let Some(v) = entry_obj.get("leader_receiver") {
         p.insert("leader_receiver".to_string(), v.clone());
-    } else if !has_team_entries && state.get("leader_receiver").is_some_and(|v| !v.is_null()) {
-        p.insert("leader_receiver".to_string(), state["leader_receiver"].clone());
     }
+    let _ = has_team_entries; // silence unused warning; kept for clarity.
     // coordinator:仅顶层有 key 时 setdefault(投影里没有才插)。
     if state.as_object().is_some_and(|o| o.contains_key("coordinator")) && !p.contains_key("coordinator") {
         p.insert("coordinator".to_string(), state["coordinator"].clone());

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

@@ -502,6 +502,18 @@ pub(crate) fn attach_command_for_workspace(
     ))
 }
 
+pub(crate) fn attach_command_for_session(
+    workspace: &Path,
+    session_name: &SessionName,
+) -> Option<String> {
+    let socket_path = socket_path_for_workspace(workspace)?;
+    Some(format!(
+        "tmux -S {} attach -t {}",
+        socket_path.display(),
+        session_name.as_str()
+    ))
+}
+
 /// Bug #7 (prerelease 0.4.0 gate review §6): when the runtime state carries a
 /// persisted `tmux_endpoint` / `tmux_socket` (e.g. `/private/tmp/tmux-501/default`),
 /// the attach command MUST point at THAT endpoint, not the workspace-hash

package/package.json

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

package/skills/team-agent/SKILL.md

@@ -157,7 +157,7 @@ For diagnosis, run `team-agent profile show deepseek --workspace . --json`; neve
 - For real workers, `quick-start` requires a current tmux leader pane. If it says the leader must run inside tmux, restart the leader with `team-agent codex`/`team-agent claude` or use an existing tmux-managed layout, then run quick-start again.
 - Quick-start generated files stay inside the selected team directory, for example `.team/current/` or `.team/alpha/`; do not create or expect root `team.spec.yaml` or `team_state.md`.
 - Use `team-agent quick-start ./roles --team-id alpha` to create a second generated team under `.team/alpha/`, or pass an existing team directory directly such as `team-agent quick-start .team/alpha`.
-- `quick-start` is for fresh startup from role docs. If stored worker context already exists for that runtime session, follow the returned `team-agent restart . --team <session>` action to resume it. Use `--fresh` only when the user explicitly accepts new blank worker contexts.
+- `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.
 - 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.
@@ -181,7 +181,7 @@ Use `team-agent start-agent <agent_id> --workspace .` only as a narrow repair wh
 
 ## Adding A New Worker At Runtime
 
-To add a new worker to a running team, write the role doc and run **one command** — do not shutdown/restart, do not regenerate the compiled spec, do not `quick-start --fresh`:
+To add a new worker to a running team, write the role doc and run **one command** — do not shutdown/restart, do not regenerate the compiled spec, and do not quick-start an existing team:
 
 ```bash
 cat > .team/current/agents/reviewer.md <<'EOF'
@@ -209,7 +209,7 @@ Semantic distinction:
 - `team-agent add-agent <agent> --role-file <file>` — add a **new** worker not yet in team state.
 - `team-agent start-agent <agent>` — (re)launch a worker that **already exists** in team state but whose window is missing.
 - `team-agent restart .` — resume a fully **stopped** team from stored worker sessions.
-- `team-agent quick-start <dir>` — **fresh** team startup from role docs; `--fresh` is reserved for the user explicitly accepting brand-new blank worker contexts.
+- `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.
 
 Removing a worker at runtime is the symmetric `team-agent remove-agent <agent> --workspace . --confirm`.