@team-agent/installer 0.5.118 → 0.5.120

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

@@ -0,0 +1,166 @@
+//! Independent watchdog receipts. Registration is unconditional; key authority is not.
+
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+
+use crate::model::enums::Provider;
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct EnterRescueContext {
+    pub message_id: String,
+    pub owner_team_id: String,
+    pub recipient: String,
+    pub payload_sha256: String,
+    pub target: Option<EnterRescueTarget>,
+    pub proof: Option<EnterRescueProof>,
+}
+
+impl EnterRescueContext {
+    pub fn marker(&self) -> String {
+        format!("[team-agent-token:{}]", self.message_id)
+    }
+
+    /// Binds an opaque-paste receipt to this message and this original carrier.
+    pub fn scope_sha256(&self) -> Option<String> {
+        let bytes = serde_json::to_vec(&(
+            &self.message_id,
+            &self.owner_team_id,
+            &self.recipient,
+            &self.payload_sha256,
+            &self.target,
+        ))
+        .ok()?;
+        Some(format!("{:x}", Sha256::digest(bytes)))
+    }
+
+    pub fn valid_proof(&self) -> bool {
+        self.proof.as_ref().is_some_and(|proof| {
+            proof.valid()
+                && proof.owned_capsule.as_ref().is_none_or(|capsule| {
+                    capsule.valid() && self.scope_sha256().as_ref() == Some(&capsule.scope_sha256)
+                })
+        })
+    }
+
+    pub fn valid_message(&self) -> bool {
+        self.message_id.starts_with("msg_")
+            && self
+                .message_id
+                .bytes()
+                .all(|b| b.is_ascii_alphanumeric() || b == b'_')
+            && !self.owner_team_id.is_empty()
+            && !self.recipient.is_empty()
+            && self.recipient != "leader"
+            && valid_digest(&self.payload_sha256)
+    }
+}
+
+/// `selected` records canonical original routing, not a late adoption of a pane.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct EnterRescueTarget {
+    pub provider: Provider,
+    pub endpoint: String,
+    pub pane_id: String,
+    pub pane_pid: u32,
+    pub pane_height: u32,
+    pub carrier_birth: String,
+    pub binding_nonce: String,
+    pub session: String,
+    pub window: String,
+}
+
+impl EnterRescueTarget {
+    pub fn selected(
+        provider: Provider,
+        pane_id: String,
+        pane_pid: u32,
+        session: String,
+        window: String,
+    ) -> Self {
+        Self {
+            provider,
+            pane_id,
+            pane_pid,
+            session,
+            window,
+            endpoint: String::new(),
+            pane_height: 0,
+            carrier_birth: String::new(),
+            binding_nonce: String::new(),
+        }
+    }
+
+    pub fn same_selection(&self, other: &Self) -> bool {
+        self.provider == other.provider
+            && self.pane_id == other.pane_id
+            && self.pane_pid == other.pane_pid
+            && self.session == other.session
+            && self.window == other.window
+    }
+
+    pub fn bound(&self) -> bool {
+        std::path::Path::new(&self.endpoint).is_absolute()
+            && self.pane_id.starts_with('%')
+            && self.pane_pid > 1
+            && self.pane_height >= 10
+            && !self.carrier_birth.is_empty()
+            && !self.binding_nonce.is_empty()
+            && !self.session.is_empty()
+            && !self.window.is_empty()
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct EnterRescueProof {
+    pub ui_identity: String,
+    pub footer_sha256: String,
+    pub visible_marker: bool,
+    pub transcript_marker_absent: bool,
+    pub owned_capsule: Option<OwnedCapsule>,
+}
+
+impl EnterRescueProof {
+    pub fn valid(&self) -> bool {
+        !self.ui_identity.is_empty()
+            && valid_digest(&self.footer_sha256)
+            && (self.visible_marker || self.owned_capsule.as_ref().is_some_and(OwnedCapsule::valid))
+    }
+}
+
+/// Only a prior empty-baseline/single-owned-paste transition may create this.
+/// Snapshotting a visible capsule label alone never creates ownership.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct OwnedCapsule {
+    pub scope_sha256: String,
+    pub label: String,
+    pub baseline_sha256: String,
+    pub baseline_capsules: Vec<String>,
+    pub observed_after_owned_paste: bool,
+}
+
+impl OwnedCapsule {
+    pub fn valid(&self) -> bool {
+        self.observed_after_owned_paste
+            && valid_digest(&self.scope_sha256)
+            && !self.label.is_empty()
+            && self.label.len() <= 80
+            && valid_digest(&self.baseline_sha256)
+            && !self.baseline_capsules.contains(&self.label)
+    }
+}
+
+fn valid_digest(value: &str) -> bool {
+    value.len() == 64 && value.bytes().all(|b| b.is_ascii_hexdigit())
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum EnterRescueOutcome {
+    Consumed,
+    NoEffect {
+        reason: &'static str,
+        reobserve: bool,
+    },
+    Entered {
+        accepted: bool,
+    },
+}

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

@@ -131,7 +131,7 @@ pub(crate) fn record_evidence(evidence: &NativeInputEvidence) {
 }
 
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub(crate) struct InputFrame {
+pub struct InputFrame {
     pub composer: String,
     pub transcript: String,
     pub identity: String,
@@ -195,6 +195,10 @@ fn input_digest(text: &str) -> String {
     format!("{:x}", Sha256::digest(text.as_bytes()))
 }
 
+pub(crate) fn supports_input_observation(provider: Provider) -> bool {
+    matches!(provider, Provider::Pi | Provider::CursorAgent)
+}
+
 pub(crate) fn inspect_input(
     provider: Provider,
     text: &str,

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

@@ -57,6 +57,8 @@ struct OfflineState {
     /// answer keyed by pane id. Used by leader provider health tests.
     pane_current_commands: BTreeMap<String, String>,
     session_owner: Option<super::SessionOwner>,
+    native_input_observation: Option<super::native_input::InputFrame>,
+    native_input_error: Option<String>,
 }
 
 impl Default for OfflineState {
@@ -85,6 +87,8 @@ impl Default for OfflineState {
             capture_ranges: Vec::new(),
             pane_current_commands: BTreeMap::new(),
             session_owner: None,
+            native_input_observation: None,
+            native_input_error: None,
         }
     }
 }
@@ -95,6 +99,16 @@ pub struct OfflineTransport {
 }
 
 impl OfflineTransport {
+    pub fn with_native_input_observation(self, frame: super::native_input::InputFrame) -> Self {
+        self.with_state(|state| state.native_input_observation = Some(frame));
+        self
+    }
+
+    pub fn with_native_input_error(self, reason: &str) -> Self {
+        self.with_state(|state| state.native_input_error = Some(reason.into()));
+        self
+    }
+
     pub fn new() -> Self {
         Self::default()
     }
@@ -434,6 +448,17 @@ impl OfflineTransport {
 }
 
 impl Transport for OfflineTransport {
+    fn observe_native_input(
+        &self,
+        _target: &Target,
+        _provider: crate::model::enums::Provider,
+    ) -> Result<Option<super::native_input::InputFrame>, TransportError> {
+        self.with_state(|state| match &state.native_input_error {
+            Some(reason) => Err(TransportError::NativeInputNotReady { reason: reason.clone() }),
+            None => Ok(state.native_input_observation.clone()),
+        })
+    }
+
     fn kind(&self) -> BackendKind {
         BackendKind::Tmux
     }

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

@@ -67,6 +67,7 @@ use std::path::{Path, PathBuf};
 use serde::{Deserialize, Serialize};
 use thiserror::Error;
 
+pub mod enter_rescue;
 pub mod native_input;
 
 #[cfg(test)]
@@ -989,6 +990,39 @@ pub trait Transport: Send + Sync {
         Ok(report)
     }
 
+    /// Observation only; None means this backend/provider has no native parser.
+    /// An implemented parser with an incomplete frame returns an error, not absence.
+    fn observe_native_input(
+        &self,
+        _target: &Target,
+        _provider: crate::model::enums::Provider,
+    ) -> Result<Option<native_input::InputFrame>, TransportError> {
+        Ok(None)
+    }
+
+    /// Snapshot the original attempted target without submitting or adopting a capsule.
+    fn snapshot_enter_rescue(
+        &self,
+        _target: &Target,
+        context: &enter_rescue::EnterRescueContext,
+        _rendered_payload: &str,
+    ) -> Result<enter_rescue::EnterRescueContext, TransportError> {
+        Ok(context.clone())
+    }
+
+    /// Independent delayed Enter-only watchdog, not native-input admission.
+    fn rescue_enter_guarded(
+        &self,
+        _context: &enter_rescue::EnterRescueContext,
+        _authorize: &dyn Fn() -> bool,
+        _observer: Option<&dyn SubmitObserver>,
+    ) -> Result<enter_rescue::EnterRescueOutcome, TransportError> {
+        Ok(enter_rescue::EnterRescueOutcome::NoEffect {
+            reason: "unsupported_backend",
+            reobserve: false,
+        })
+    }
+
     /// Enter-only recovery; unsupported backends have an explicit zero-effect refusal.
     fn rescue_enter(&self, _evidence: &native_input::NativeInputEvidence, _authorize: &dyn Fn() -> bool, _observer: Option<&dyn SubmitObserver>)
         -> Result<native_input::EnterRescueOutcome, TransportError>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-agent/installer",
-  "version": "0.5.118",
+  "version": "0.5.120",
   "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.118",
-    "@team-agent/cli-darwin-x64": "0.5.118",
-    "@team-agent/cli-linux-x64": "0.5.118"
+    "@team-agent/cli-darwin-arm64": "0.5.120",
+    "@team-agent/cli-darwin-x64": "0.5.120",
+    "@team-agent/cli-linux-x64": "0.5.120"
   },
   "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.