@team-agent/installer 0.5.44 → 0.5.45

package/Cargo.lock

@@ -575,7 +575,7 @@ dependencies = [
 
 [[package]]
 name = "team-agent"
-version = "0.5.44"
+version = "0.5.45"
 dependencies = [
  "anyhow",
  "chrono",

package/Cargo.toml

@@ -9,7 +9,7 @@ members = ["crates/team-agent", "crates/win-conpty-phase0", "crates/conpty-trans
 
 [workspace.package]
 edition = "2021"
-version = "0.5.44"
+version = "0.5.45"
 license = "AGPL-3.0"
 rust-version = "1.95"
 

package/crates/team-agent/src/cli/emit.rs

@@ -308,7 +308,24 @@ fn command_help(command: Option<&str>) -> String {
         Some("quick-start") => "usage: team-agent quick-start [TEAMDIR] [--workspace WORKSPACE] [--name NAME] [--team-id TEAM|--team TEAM] [--yes] [--no-display] [--backend tmux|conpty] [--json]\n\ndefaults: display_backend=adaptive; set display_backend: none in TEAM.md or pass --no-display to use one worker window per agent.\n\n--backend selects the worker transport (Phase 1d Batch 2): tmux (default on POSIX; unchanged behavior), conpty (Windows-native ConPTY worker transport; requires the shim binary and Windows host).".to_string(),
         Some("start") => compat_hidden_help("start", "usage: team-agent start [TEAMDIR] [--yes] [--fresh] [--json]"),
         Some("compile") => "usage: team-agent compile --team TEAM [--out FILE] [--json]".to_string(),
-        Some("send") => "usage: team-agent send TARGET MESSAGE... [--workspace WORKSPACE] [--team TEAM] [--targets AGENTS] [--to-name NAME] [--pane PANE] [--task TASK] [--sender SENDER] [--watch-result] [--requires-ack|--no-ack] [--no-wait] [--timeout SECONDS] [--confirm-human] [--message-id ID] [--json]\n\nMVP: name-based cross-workspace addressing assumes trusted local caller; no auth gate.".to_string(),
+        Some("send") => concat!(
+            "usage: team-agent send TARGET MESSAGE... ",
+            "[--workspace WORKSPACE] [--team TEAM] [--targets AGENTS] ",
+            "[--to-name NAME] [--pane PANE] [--task TASK] [--sender SENDER] ",
+            "[--watch-result] [--requires-ack|--no-ack] [--no-wait] ",
+            "[--timeout SECONDS] [--confirm-human] [--message-id ID] [--json]\n\n",
+            "TARGET is a short id scoped by --team; MCP `to` is a short id scoped ",
+            "by the worker's owner team.\n",
+            "--to-name accepts: --to-name AGENT, --to-name TEAM/AGENT, or ",
+            "--to-name WORKSPACE::TEAM/AGENT.\n",
+            "--team scopes only a bare --to-name AGENT; qualified forms keep the ",
+            "scope in the address.\n",
+            "TEAM/AGENT and WORKSPACE::TEAM/AGENT are not valid positional TARGET ",
+            "or MCP `to` values.\n\n",
+            "MVP: name-based cross-workspace addressing assumes trusted local ",
+            "caller; no auth gate."
+        )
+        .to_string(),
         Some("allow-peer-talk") => "usage: team-agent allow-peer-talk A B [--workspace WORKSPACE] [--json]".to_string(),
         Some("status") => "usage: team-agent status [AGENT] [--workspace WORKSPACE] [--team TEAM] [--summary|--json] [--detail]\n\n默认输出: worker,空闲|工作|错误；错误细分走 status --summary".to_string(),
         Some("stop") => compat_hidden_help("stop", "usage: team-agent stop [--workspace WORKSPACE] [--team TEAM] [--keep-logs] [--json]"),
@@ -357,43 +374,33 @@ fn emit_unknown_subcommand_usage(command: &str) -> ExitCode {
     if let Some(suggestion) = nearest_subcommand(command) {
         eprintln!("team-agent: did you mean `{suggestion}`?");
     }
-    ExitCode::Usage
+    // 0.5.45 naming-addressing (RED-6): unknown subcommand exits 1
+    // (Error), aligned with the family of typo refusals throughout
+    // send/named. Pre-0.5.45 mapped to Usage (2) argparse-style; the
+    // shared refusal shape ("typo diagnostic + advisory suggestion +
+    // exit 1") is the invariant callers of `team-agent send` /
+    // `--to-name` also see, so keeping unknown-subcommand at 2 was
+    // internal drift.
+    ExitCode::Error
 }
 
-/// 在已知子命令里找与 `input` 最接近的一个(Levenshtein ≤ 阈值)。无足够接近者 → None。
+/// 在已知子命令里找与 `input` 最接近的一个。0.5.45 naming-addressing
+/// (design §3.2/§4.1) 抽公 shared `model::name_similarity` — 距离
+/// 阈值与排序规则跟 CLI `--to-name` typo suggestion 走同一份纯函数,
+/// 避免两套 fuzzy 逻辑漂移。既有 `statu -> status` 行为保留(RED-6
+/// grep guard + prefix-hit priority)。
 fn nearest_subcommand(input: &str) -> Option<&'static str> {
-    let candidates = COMMAND_SPECS
+    use crate::model::name_similarity::{rank, Candidate};
+    let candidates: Vec<Candidate<&'static str>> = COMMAND_SPECS
         .iter()
         .filter(|spec| spec.suggestion_index)
-        .map(|spec| spec.name);
-    // 阈值随长度放宽,但短词收紧,避免 'x' 误配任何东西。
-    let max_distance = match input.chars().count() {
-        0..=3 => 1,
-        4..=6 => 2,
-        _ => 3,
-    };
-    candidates
-        .map(|c| (c, levenshtein(input, c)))
-        .filter(|(_, d)| *d <= max_distance)
-        .min_by_key(|(_, d)| *d)
-        .map(|(c, _)| c)
-}
-
-/// 标准 Levenshtein 编辑距离(纯函数,无依赖;子命令建议用)。
-fn levenshtein(a: &str, b: &str) -> usize {
-    let a: Vec<char> = a.chars().collect();
-    let b: Vec<char> = b.chars().collect();
-    let mut prev: Vec<usize> = (0..=b.len()).collect();
-    let mut curr = vec![0usize; b.len() + 1];
-    for (i, &ca) in a.iter().enumerate() {
-        curr[0] = i + 1;
-        for (j, &cb) in b.iter().enumerate() {
-            let cost = if ca == cb { 0 } else { 1 };
-            curr[j + 1] = (prev[j + 1] + 1).min(curr[j] + 1).min(prev[j] + cost);
-        }
-        std::mem::swap(&mut prev, &mut curr);
-    }
-    prev[b.len()]
+        .map(|spec| Candidate {
+            match_key: spec.name.to_string(),
+            stable_key: spec.name.to_string(),
+            payload: spec.name,
+        })
+        .collect();
+    rank(input, &candidates).into_iter().next()
 }
 
 fn emit_usage_error(message: &str) {
@@ -2011,6 +2018,10 @@ mod tests {
 
     #[test]
     fn e8_levenshtein_basic() {
+        // 0.5.45 naming-addressing: distance function moved to
+        // `crate::model::name_similarity` (shared with --to-name typo
+        // suggestions). Same math, single source.
+        use crate::model::name_similarity::levenshtein;
         assert_eq!(levenshtein("kitten", "sitting"), 3);
         assert_eq!(levenshtein("status", "status"), 0);
         assert_eq!(levenshtein("statu", "status"), 1);

package/crates/team-agent/src/cli/named_address.rs

@@ -61,6 +61,11 @@ pub(crate) struct NamedAddressError {
     pub requested_team: Option<String>,
     pub available_team_keys: Vec<String>,
     pub suggested_name: Option<String>,
+    /// 0.5.45 naming-addressing (design §3.4, RED-2/RED-3): echo the
+    /// user's original typo so JSON consumers + N38 human can pair
+    /// `requested_name`/`suggested_name` without re-parsing. Absent
+    /// for exact refusals like empty-workspace.
+    pub requested_name: Option<String>,
 }
 
 impl NamedAddressError {
@@ -74,18 +79,149 @@ impl NamedAddressError {
             requested_team: None,
             available_team_keys: Vec::new(),
             suggested_name: None,
+            requested_name: None,
         }
     }
 
     pub(crate) fn n38_message(&self) -> String {
+        // 0.5.45 naming-addressing (design §3.4, RED-3): the N38 first
+        // line embeds the human-readable `message` (which contains
+        // the original typo like `qa-namng`/`btea`) after the reason.
+        // Pre-0.5.45 the line was `Error: <reason>` only; the typo
+        // hid in the JSON-only `error` field, so the human line
+        // couldn't be scanned to recover the original request.
         format!(
-            "Error: {}\nAction: {}\nLog: {}",
+            "Error: {}: {}\nAction: {}\nLog: {}",
             self.kind.as_str(),
+            self.message,
             self.action,
             self.log
         )
     }
 
+    /// 0.5.45 (design §3.4, RED-2 named-team): rank team-scope typo
+    /// against target workspace `teams.*` keys; candidate `name`
+    /// preserves the qualified `team/entity` shape so the copyable
+    /// token in Action can be pasted back into `--to-name` unchanged.
+    fn with_scoped_suggestions_for_team(
+        self,
+        state: &Value,
+        team_typo: &str,
+        entity: &str,
+        parsed: &ParsedNamedAddress,
+    ) -> Self {
+        use crate::model::name_similarity::{rank, Candidate};
+        let candidates: Vec<Candidate<(String, String)>> = state
+            .get("teams")
+            .and_then(Value::as_object)
+            .map(|teams| {
+                teams
+                    .keys()
+                    .map(|team_key| Candidate {
+                        match_key: team_key.clone(),
+                        stable_key: team_key.clone(),
+                        payload: (team_key.clone(), entity.to_string()),
+                    })
+                    .collect()
+            })
+            .unwrap_or_default();
+        let ranked = rank(team_typo, &candidates);
+        let requested_display = parsed.display_name();
+        let candidate_values: Vec<Value> = ranked
+            .iter()
+            .map(|(team_key, entity)| {
+                let name = format!("{team_key}/{entity}");
+                json!({
+                    "name": name,
+                    "team_key": team_key,
+                    "agent_id": entity,
+                    "advisory": true,
+                })
+            })
+            .collect();
+        let best = ranked
+            .first()
+            .map(|(team_key, entity)| format!("{team_key}/{entity}"));
+        self.with_scoped_suggestions(requested_display, candidate_values, best)
+    }
+
+    /// 0.5.45 (design §3.4, RED-2 named-agent): rank agent-scope typo
+    /// against the legal `teams[team].agents` keys.
+    fn with_scoped_suggestions_for_agent(
+        self,
+        team_entry: &Value,
+        team: &str,
+        agent_typo: &str,
+        parsed: &ParsedNamedAddress,
+    ) -> Self {
+        use crate::model::name_similarity::{rank, Candidate};
+        let candidates: Vec<Candidate<String>> = team_entry
+            .get("agents")
+            .and_then(Value::as_object)
+            .map(|agents| {
+                agents
+                    .keys()
+                    .map(|agent_id| Candidate {
+                        match_key: agent_id.clone(),
+                        stable_key: agent_id.clone(),
+                        payload: agent_id.clone(),
+                    })
+                    .collect()
+            })
+            .unwrap_or_default();
+        let ranked = rank(agent_typo, &candidates);
+        let requested_display = parsed.display_name();
+        let candidate_values: Vec<Value> = ranked
+            .iter()
+            .map(|agent_id| {
+                json!({
+                    "name": format!("{team}/{agent_id}"),
+                    "team_key": team,
+                    "agent_id": agent_id,
+                    "advisory": true,
+                })
+            })
+            .collect();
+        let best = ranked
+            .first()
+            .map(|agent_id| format!("{team}/{agent_id}"));
+        self.with_scoped_suggestions(requested_display, candidate_values, best)
+    }
+
+    /// 0.5.45 naming-addressing (design §3.3/§3.4): attach an
+    /// advisory suggestion payload. `requested` is the original typo
+    /// (surfaced verbatim in JSON + N38 Action); `ranked_candidates`
+    /// carry the scope-safe candidate payloads produced by
+    /// `model::name_similarity::rank`. The best candidate populates
+    /// `suggested_name` for convenience; the full list appears as
+    /// `candidates` in the JSON envelope.
+    pub(crate) fn with_scoped_suggestions(
+        mut self,
+        requested: impl Into<String>,
+        ranked_candidates: Vec<Value>,
+        best_copyable: Option<String>,
+    ) -> Self {
+        let requested = requested.into();
+        self.requested_name = Some(requested.clone());
+        self.candidates = ranked_candidates;
+        self.suggested_name = best_copyable.clone();
+        // Rewrite Action so the human line points at the actual
+        // returned candidate (RED-4). Falls back to a status-JSON
+        // hint when no candidate cleared the threshold.
+        if let Some(best) = best_copyable {
+            self.action = format!(
+                "Did you mean `{best}`? Rerun with `--to-name {best}`."
+            );
+        } else {
+            self.action = format!(
+                "No close matches for `{requested}`. \
+                 Run `team-agent status --json` for the current team_key + agent list \
+                 and combine them as `<team>/<agent>` for `--to-name`."
+            );
+        }
+        self
+    }
+
     pub(crate) fn to_json(&self) -> Value {
         let mut obj = serde_json::Map::new();
         obj.insert("ok".to_string(), Value::Bool(false));
@@ -124,6 +260,12 @@ impl NamedAddressError {
                 Value::String(suggested.to_string()),
             );
         }
+        if let Some(requested) = self.requested_name.as_deref() {
+            obj.insert(
+                "requested_name".to_string(),
+                Value::String(requested.to_string()),
+            );
+        }
         Value::Object(obj)
     }
 }
@@ -261,8 +403,20 @@ pub(crate) fn resolve_name_with_workspace_transports(
 pub(crate) fn resolve_name_for_cli(
     sender_workspace: &Path,
     raw_name: &str,
+    bare_team_scope: Option<&str>,
 ) -> Result<(ResolvedNamedAddress, Box<dyn Transport>), NamedAddressError> {
     let parsed = parse_named_address(raw_name)?;
+    // 0.5.45 naming-addressing (design §3.1, RED-1): bare `--to-name`
+    // + explicit `--team` normalizes to `ParsedTarget::TeamEntity`
+    // BEFORE transport selection. Only fires when:
+    //   1. address parsed as bare (no `team/`, no `workspace::`),
+    //   2. caller passed a non-empty `bare_team_scope`.
+    // Qualified addresses keep the scope in the address (design §1
+    // priority: workspace::team/entity > team/entity > bare + --team
+    // > bare workspace-unique). resolve_name_with_transport and the
+    // registry-to-E6 internal helper deliberately pass `None` so
+    // caller-supplied `--team` never overrides a full address.
+    let parsed = normalize_bare_with_team_scope(parsed, bare_team_scope);
     let target_workspace = resolve_workspace(sender_workspace, parsed.workspace.as_deref())?;
     let state = load_state_checked(&target_workspace)?;
     let transport = transport_for_cli_target(&target_workspace, &state, &parsed);
@@ -276,6 +430,34 @@ pub(crate) fn resolve_name_for_cli(
     Ok((resolved, transport))
 }
 
+/// 0.5.45 naming-addressing (design §3.1): apply bare-team scope归一.
+/// Only bare targets with no workspace prefix consume `--team`;
+/// qualified addresses keep the scope embedded in the address.
+fn normalize_bare_with_team_scope(
+    parsed: ParsedNamedAddress,
+    bare_team_scope: Option<&str>,
+) -> ParsedNamedAddress {
+    let Some(scope) = bare_team_scope.map(str::trim).filter(|s| !s.is_empty()) else {
+        return parsed;
+    };
+    if parsed.workspace.is_some() {
+        return parsed;
+    }
+    match parsed.target {
+        ParsedTarget::BareAgent(agent) => ParsedNamedAddress {
+            workspace: parsed.workspace,
+            target: ParsedTarget::TeamEntity {
+                team: scope.to_string(),
+                entity: agent,
+            },
+        },
+        target => ParsedNamedAddress {
+            workspace: parsed.workspace,
+            target,
+        },
+    }
+}
+
 /// E6 wiring helper (`cli::send::maybe_enqueue_offline_leader_mailbox`):
 /// re-parse a `<workspace>::<team>/leader` name and return the resolved
 /// target workspace + canonical team_key so send.rs can enqueue the
@@ -462,12 +644,32 @@ fn resolve_worker(
     parsed: &ParsedNamedAddress,
     transport: &dyn Transport,
 ) -> Result<ResolvedNamedAddress, NamedAddressError> {
-    let team_entry = team_entry(state, team).ok_or_else(|| name_not_resolvable_team(team))?;
-    let agent_entry = team_entry
+    let team_entry = match team_entry(state, team) {
+        Some(entry) => entry,
+        None => {
+            // 0.5.45 naming-addressing (design §3.4, RED-2 named):
+            // typo in team scope. Candidates come from the target
+            // workspace's `teams.*.*` — scope-safe because we're
+            // already inside the requested workspace projection.
+            return Err(name_not_resolvable_team(team)
+                .with_scoped_suggestions_for_team(state, team, agent, parsed));
+        }
+    };
+    let agent_entry = match team_entry
         .get("agents")
         .and_then(Value::as_object)
         .and_then(|agents| agents.get(agent))
-        .ok_or_else(|| name_not_resolvable_agent(team, agent))?;
+    {
+        Some(entry) => entry,
+        None => {
+            // 0.5.45 naming-addressing (design §3.4, RED-2 named):
+            // typo in agent within a legal team. Candidates come from
+            // `teams[team].agents` — scope stays in the requested
+            // team, so sibling teams cannot leak.
+            return Err(name_not_resolvable_agent(team, agent)
+                .with_scoped_suggestions_for_agent(team_entry, team, agent, parsed));
+        }
+    };
     let session = string_field(team_entry, "session_name")
         .ok_or_else(|| name_not_resolvable("team is missing session_name"))?;
     let window = string_field(agent_entry, "window")

package/crates/team-agent/src/cli/send.rs

@@ -55,8 +55,17 @@ pub fn cmd_send(args: &SendArgs) -> Result<CmdResult, CliError> {
                 "--to-name requires a non-empty message".to_string(),
             ));
         }
+        // 0.5.45 naming-addressing (design §3.1, RED-1): thread
+        // `--team` down to resolver so bare `--to-name agent --team T`
+        // scopes to `T` BEFORE workspace scanning. Qualified addresses
+        // (`team/agent`, `workspace::team/agent`) ignore the scope
+        // per §1 priority ladder.
         let (resolved, transport) =
-            match crate::cli::named_address::resolve_name_for_cli(&args.workspace, to_name) {
+            match crate::cli::named_address::resolve_name_for_cli(
+                &args.workspace,
+                to_name,
+                args.team.as_deref(),
+            ) {
                 Ok(resolved) => resolved,
                 Err(error) => {
                     // E6 (0.5.9 offline-mailbox-toname-design §3.1/§6.2): when
@@ -166,6 +175,15 @@ pub fn cmd_send(args: &SendArgs) -> Result<CmdResult, CliError> {
         outcome = observe_initial_delivery_for_watch(&selected, &target, &outcome, &opts)?;
     }
     let mut value = delivery_outcome_json(&outcome, &target, &content, &opts);
+    // 0.5.45 naming-addressing (design §3.5, RED-2/RED-3 positional):
+    // when the refusal reason is `target_not_in_team` AND the target
+    // was a Single non-special short id, attach scope-safe
+    // suggestions ranked from `selected.state.agents` — never from
+    // raw workspace `teams` (design §3.5 & risk table). Zero DB
+    // write / zero inject: the request stays refused, only the JSON
+    // envelope gains `requested_name`/`suggested_name`/`candidates`
+    // and the human `Action` gains a "Did you mean" line.
+    attach_positional_typo_suggestions(&mut value, &target, &selected.state);
     append_loud_ensure_fields(&mut value, coordinator_ensure.as_ref());
     if opts.watch_result && initial_delivery_allows_watch(outcome.status) {
         if let Some(obj) = value.as_object_mut() {
@@ -773,6 +791,67 @@ fn watch_notice_json(target: &MessageTarget, opts: &SendOptions) -> Value {
     })
 }
 
+/// 0.5.45 naming-addressing (design §3.5, RED-2/RED-3 positional):
+/// after `messaging::send_message` refuses with `target_not_in_team`
+/// for a Single non-special short id, attach scope-safe advisory
+/// suggestions to the outbound JSON envelope. Candidate source =
+/// selected team's projected `agents` map (never the raw workspace
+/// `teams`) so sibling teams cannot leak. Zero DB write, zero inject
+/// — the refusal exit code is unchanged.
+fn attach_positional_typo_suggestions(
+    value: &mut Value,
+    target: &MessageTarget,
+    selected_state: &Value,
+) {
+    use crate::model::name_similarity::{rank, Candidate};
+    let requested = match target {
+        MessageTarget::Single(id) if id != "*" && id != "leader" => id.clone(),
+        _ => return,
+    };
+    let Some(obj) = value.as_object_mut() else {
+        return;
+    };
+    if obj.get("reason").and_then(Value::as_str) != Some("target_not_in_team") {
+        return;
+    }
+    let team_key = selected_state
+        .get("active_team_key")
+        .or_else(|| selected_state.get("team_key"))
+        .and_then(Value::as_str)
+        .unwrap_or("");
+    let candidates: Vec<Candidate<String>> = selected_state
+        .get("agents")
+        .and_then(Value::as_object)
+        .map(|agents| {
+            agents
+                .keys()
+                .map(|agent_id| Candidate {
+                    match_key: agent_id.clone(),
+                    stable_key: agent_id.clone(),
+                    payload: agent_id.clone(),
+                })
+                .collect()
+        })
+        .unwrap_or_default();
+    let ranked = rank(&requested, &candidates);
+    let candidate_values: Vec<Value> = ranked
+        .iter()
+        .map(|agent_id| {
+            json!({
+                "name": agent_id,
+                "team_key": team_key,
+                "agent_id": agent_id,
+                "advisory": true,
+            })
+        })
+        .collect();
+    obj.insert("requested_name".to_string(), json!(requested));
+    if let Some(best) = ranked.first() {
+        obj.insert("suggested_name".to_string(), json!(best));
+    }
+    obj.insert("candidates".to_string(), Value::Array(candidate_values));
+}
+
 fn delivery_outcome_json(
     outcome: &DeliveryOutcome,
     target: &MessageTarget,
@@ -973,6 +1052,25 @@ fn send_human_output(value: &Value) -> String {
             parts.push(send_human_field(value, key));
         }
     }
+    // 0.5.45 naming-addressing (design §3.4/§3.5, RED-3 positional):
+    // when the refusal envelope carries a scope-safe suggestion,
+    // surface it verbatim in human output so users can copy the
+    // right short id. `requested_name` echoes the typo, `suggested_
+    // name` is the copyable canonical.
+    if let Some(requested) = value
+        .get("requested_name")
+        .and_then(Value::as_str)
+        .filter(|s| !s.is_empty())
+    {
+        parts.push(format!("requested_name: {requested}"));
+    }
+    if let Some(suggested) = value
+        .get("suggested_name")
+        .and_then(Value::as_str)
+        .filter(|s| !s.is_empty())
+    {
+        parts.push(format!("Did you mean `{suggested}`? suggested_name: {suggested}"));
+    }
     parts.join(" ")
 }
 
@@ -1250,8 +1348,13 @@ pub fn send_to_canonical_leader_target(
     // synthesized `<workspace>::<team_key>/leader` name so live inject +
     // mailbox both go through one code path.
     let to_name = format!("{}::{}/leader", entry.workspace.display(), entry.team_key);
+    // 0.5.45 naming-addressing (design §3.1 / §4.1): internal
+    // registry-to-E6 delegation MUST pass None for bare_team_scope.
+    // The synthesized name above is a full `workspace::team/leader`
+    // form, and the caller's `--team` flag (if any) must not
+    // override the registry's authoritative team_key.
     let (resolved, transport) =
-        match crate::cli::named_address::resolve_name_for_cli(sender_workspace, &to_name) {
+        match crate::cli::named_address::resolve_name_for_cli(sender_workspace, &to_name, None) {
             Ok(r) => r,
             Err(err) => {
                 // Named-address refusal — surface it verbatim but tag as

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

@@ -153,7 +153,7 @@ pub(crate) struct CommandSpec {
 #[rustfmt::skip]
 pub(crate) const COMMAND_SPECS: &[CommandSpec] = &[
     CommandSpec { name: "quick-start", tier: CommandTier::Core, category: CommandCategory::Start, kind: CommandKind::Dispatch(DispatchKind::QuickStart), summary: "start or attach a team from TEAM.md", usage: "usage: team-agent quick-start [TEAMDIR] [--workspace WORKSPACE] [--name NAME] [--team-id TEAM|--team TEAM] [--yes] [--no-display] [--backend tmux|conpty] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, alias_of: None, sunset: None, action: None, governance: None },
-    CommandSpec { name: "send", tier: CommandTier::Core, category: CommandCategory::Daily, kind: CommandKind::Dispatch(DispatchKind::Send), summary: "send a message/task", usage: "usage: team-agent send TARGET MESSAGE... [--workspace WORKSPACE] [--team TEAM] [--targets AGENTS] [--to-name NAME] [--pane PANE] [--task TASK] [--sender SENDER] [--watch-result] [--requires-ack|--no-ack] [--no-wait] [--timeout SECONDS] [--confirm-human] [--message-id ID] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, alias_of: None, sunset: None, action: None, governance: None },
+    CommandSpec { name: "send", tier: CommandTier::Core, category: CommandCategory::Daily, kind: CommandKind::Dispatch(DispatchKind::Send), summary: "send a message/task", usage: "usage: team-agent send TARGET MESSAGE... [--workspace WORKSPACE] [--team TEAM] [--targets AGENTS] [--to-name NAME | --to-name agent | --to-name team/agent | --to-name workspace::team/agent] [--pane PANE] [--task TASK] [--sender SENDER] [--watch-result] [--requires-ack|--no-ack] [--no-wait] [--timeout SECONDS] [--confirm-human] [--message-id ID] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, alias_of: None, sunset: None, action: None, governance: None },
     CommandSpec { name: "status", tier: CommandTier::Core, category: CommandCategory::Daily, kind: CommandKind::Dispatch(DispatchKind::Status), summary: "show current team status", usage: "usage: team-agent status [AGENT] [--workspace WORKSPACE] [--team TEAM] [--summary|--json] [--detail]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
     CommandSpec { name: "collect", tier: CommandTier::Core, category: CommandCategory::Daily, kind: CommandKind::Dispatch(DispatchKind::Collect), summary: "collect reported results", usage: "usage: team-agent collect [--workspace WORKSPACE] [--team TEAM] [--result-file FILE] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
     CommandSpec { name: "restart", tier: CommandTier::Core, category: CommandCategory::TeamLifecycle, kind: CommandKind::Dispatch(DispatchKind::Restart), summary: "restart the selected team", usage: "usage: team-agent restart [WORKSPACE] [--team TEAM] [--allow-fresh] [--session-converge-deadline SECONDS] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, alias_of: None, sunset: None, action: None, governance: None },

package/crates/team-agent/src/cli/tests/run_delegation.rs

@@ -125,12 +125,15 @@ fn run_dispatches_send_to_handler_returns_ok() {
 }
 
 #[test]
-fn run_unknown_subcommand_is_usage() {
-    // An unknown subcommand routes to argparse-style usage (exit 2), never a handler.
+fn run_unknown_subcommand_is_error_not_usage() {
+    // 0.5.45 naming-addressing (RED-6): unknown subcommand exits 1
+    // (Error), aligned with the shared refusal shape used by
+    // `send`/`--to-name` typos. Pre-0.5.45 argparse-style Usage (2)
+    // was internal drift.
     assert_eq!(
         run(&["totally-not-a-subcommand".to_string()], Path::new(".")),
-        ExitCode::Usage,
-        "an unknown subcommand must map to ExitCode::Usage"
+        ExitCode::Error,
+        "unknown subcommand must map to ExitCode::Error (aligned with send/--to-name typo family)"
     );
 }
 

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

@@ -737,24 +737,83 @@ impl TeamOrchestratorTools {
         {
             return None;
         }
-        if let Ok(visible) = self.get_visible_peers() {
-            if visible.peers.iter().any(|peer| peer.as_str() == target) {
-                return None;
-            }
+        // 0.5.45 naming-addressing (design §3.6, RED-2 MCP): compute
+        // the visible peers ONCE and reuse for both exact-match check
+        // AND scope-safe candidate ranking. Peers come from
+        // `get_visible_peers()` (owner-team only) so sibling teams,
+        // host registry, and workspace reverse scans cannot leak.
+        let visible_peers: Vec<String> = self
+            .get_visible_peers()
+            .map(|visible| {
+                visible
+                    .peers
+                    .iter()
+                    .map(|peer| peer.as_str().to_string())
+                    .collect()
+            })
+            .unwrap_or_default();
+        if visible_peers.iter().any(|peer| peer == target) {
+            return None;
         }
-        let hint = "the requested peer is not part of your team; worker-origin MCP cannot widen team scope.";
+        let owner_team_key = owner_team
+            .as_ref()
+            .map(TeamKey::as_str)
+            .unwrap_or("")
+            .to_string();
+        // Rank the typo against owner-scope peers.
+        let ranked = {
+            use crate::model::name_similarity::{rank, Candidate};
+            let candidates: Vec<Candidate<String>> = visible_peers
+                .iter()
+                .map(|peer| Candidate {
+                    match_key: peer.clone(),
+                    stable_key: peer.clone(),
+                    payload: peer.clone(),
+                })
+                .collect();
+            rank(target, &candidates)
+        };
+        let candidate_values: Vec<Value> = ranked
+            .iter()
+            .map(|peer| {
+                serde_json::json!({
+                    "name": peer,
+                    "team_key": owner_team_key,
+                    "agent_id": peer,
+                    "advisory": true,
+                })
+            })
+            .collect();
+        let best = ranked.first().cloned();
+        let hint = if let Some(best) = best.as_deref() {
+            format!(
+                "the requested peer is not in your owner team; did you mean `{best}`?"
+            )
+        } else {
+            "the requested peer is not part of your team; worker-origin MCP cannot widen team scope.".to_string()
+        };
         let _ = EventLog::new(&self.workspace).write(
             "mcp.send_message_refused",
             serde_json::json!({
                 "reason": "peer_not_in_scope",
-                "sender_team_id": owner_team.as_ref().map(TeamKey::as_str).unwrap_or(""),
+                "sender_team_id": owner_team_key,
                 "scope": "team",
-                "hint": hint
+                "hint": hint,
             }),
         );
         let mut extra = serde_json::Map::new();
         extra.insert("status".to_string(), Value::String("refused".to_string()));
-        extra.insert("hint".to_string(), Value::String(hint.to_string()));
+        extra.insert("hint".to_string(), Value::String(hint.clone()));
+        // 0.5.45 naming-addressing (design §3.6, RED-2 MCP): additive
+        // scope-safe suggestions inside the existing ToolError.extra
+        // JSON envelope — no struct/schema change, no event log
+        // widening. Advisory only: `isError=true` and
+        // reason=peer_not_in_scope stay unchanged.
+        extra.insert("requested_name".to_string(), Value::String(target.clone()));
+        if let Some(best) = best {
+            extra.insert("suggested_name".to_string(), Value::String(best));
+        }
+        extra.insert("candidates".to_string(), Value::Array(candidate_values));
         Some(ToolError {
             reason: ToolErrorReason::PeerNotInScope,
             exc_type: "PeerNotInScope".to_string(),

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

@@ -12,6 +12,12 @@
 pub mod enums;
 pub mod errors;
 pub mod ids;
+// 0.5.45 naming-addressing (design §3.2/§4.1): shared pure name
+// similarity ranking helper. crate-private consumer set = cli/emit.rs
+// (subcommand hint), cli/named_address.rs (typo candidates),
+// cli/send.rs (positional adapter), mcp_server/tools.rs (owner-scoped
+// peer suggestions). Never a routing authority — advisory only.
+pub(crate) mod name_similarity;
 pub mod paths;
 pub mod permissions;
 pub mod routing;

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

@@ -0,0 +1,266 @@
+//! 0.5.45 naming-addressing (design §3.2/§4.1) — shared pure name
+//! similarity ranking helper.
+//!
+//! **Pure**: no filesystem reads, no state loads, no terminal
+//! multiplexer calls, no message dispatch. The RED-6 governance guard
+//! scans this file for the forbidden import tokens and rejects any
+//! occurrence.
+//!
+//! **Single source of truth for name-similarity ranking**: consumed by
+//!   - `cli/emit.rs::nearest_subcommand` (unknown top-level subcommand hint),
+//!   - `cli/named_address.rs` (bare/`--to-name` typo candidates),
+//!   - `cli/send.rs` positional adapter (unknown short id in selected team),
+//!   - `mcp_server/tools.rs` owner-scoped peer suggestions.
+//!
+//! **Never a routing authority**: the returned ranking is *advisory
+//! only*. Callers must still exit 1 / `isError=true` / refuse the
+//! request on their original reason; the ranked payload only
+//! populates the additive `requested_name` / `suggested_name` /
+//! `candidates` fields that get echoed back to the user.
+//!
+//! Ranking rules (design §3.2, byte-locked by RED-6):
+//!   1. Comparison keys are trimmed and ASCII-lowercased.
+//!   2. Candidates whose `match_key` prefixes the request outrank
+//!      lower-distance non-prefix candidates.
+//!   3. Otherwise sort by Levenshtein distance.
+//!   4. Threshold widens with request length: `0..=3 → 1`, `4..=6 →
+//!      2`, longer → `3`. Nothing beyond the threshold is returned —
+//!      no "best guess for a far name".
+//!   5. Sort order: `prefix_miss` (bool), `distance`, `stable_key`.
+//!   6. Deduplicate on `stable_key`, then cap at 3 results.
+//!   7. Canonical spelling comes from the candidate `name` payload
+//!      (not the lowercased comparison key) so case is preserved.
+
+#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
+
+use std::collections::BTreeSet;
+
+/// A candidate to rank. `T` is a caller-owned payload returned
+/// verbatim in the ranked output — callers use it to keep whatever
+/// side data (team_key, workspace, etc.) they need to reconstruct
+/// their advisory JSON envelope.
+#[derive(Debug, Clone)]
+pub struct Candidate<T> {
+    /// Comparison key. Callers pass the raw canonical name; this
+    /// function trims + lowercases before comparing.
+    pub match_key: String,
+    /// Stable tie-break key. Typically the same as `match_key`, but
+    /// callers with cross-team or cross-workspace candidates use a
+    /// composite (`team/agent`) so ordering is deterministic across
+    /// otherwise-tied entries.
+    pub stable_key: String,
+    /// Caller-owned payload returned verbatim.
+    pub payload: T,
+}
+
+/// Threshold for accepting a candidate given the request length.
+/// Byte-locked by RED-6: short requests get 1, medium 2, longer 3.
+fn threshold_for_len(len: usize) -> usize {
+    match len {
+        0..=3 => 1,
+        4..=6 => 2,
+        _ => 3,
+    }
+}
+
+/// Rank `candidates` against `request`. Returns up to 3 payloads,
+/// most-similar-first. `<request>` casing does not affect matching,
+/// only comparison; the caller-supplied payload (which carries the
+/// canonical `name`) is what surfaces to the user.
+///
+/// Empty return means "no acceptable candidate" — do NOT re-rank or
+/// synthesize a best-guess elsewhere.
+pub fn rank<T: Clone>(request: &str, candidates: &[Candidate<T>]) -> Vec<T> {
+    let request_key = normalize(request);
+    if request_key.is_empty() {
+        return Vec::new();
+    }
+    let threshold = threshold_for_len(request_key.chars().count());
+    let mut seen: BTreeSet<String> = BTreeSet::new();
+    let mut scored: Vec<(bool, usize, String, T)> = Vec::new();
+    for candidate in candidates {
+        if !seen.insert(candidate.stable_key.clone()) {
+            continue;
+        }
+        let match_key = normalize(&candidate.match_key);
+        if match_key.is_empty() {
+            continue;
+        }
+        let distance = levenshtein(&request_key, &match_key);
+        // Prefix hit means "request is a prefix of candidate" OR
+        // "candidate is a prefix of request" — either direction
+        // beats a same-distance edit anywhere in the middle.
+        let is_prefix = match_key.starts_with(&request_key) || request_key.starts_with(&match_key);
+        // Prefix candidates skip the distance threshold (a 1-char
+        // prefix miss with distance 5 is still a legitimate
+        // completion hint); non-prefix candidates must clear the
+        // threshold.
+        if !is_prefix && distance > threshold {
+            continue;
+        }
+        // Prefix-miss is the primary sort key; sorting bools puts
+        // false (prefix hit) before true (prefix miss).
+        scored.push((
+            !is_prefix,
+            distance,
+            candidate.stable_key.clone(),
+            candidate.payload.clone(),
+        ));
+    }
+    scored.sort_by(|a, b| a.0.cmp(&b.0).then(a.1.cmp(&b.1)).then(a.2.cmp(&b.2)));
+    scored.into_iter().take(3).map(|(_, _, _, p)| p).collect()
+}
+
+/// Convenience wrapper for the common case where callers only need
+/// the single best canonical name (a `String`), not full payloads.
+/// Returns `None` when no candidate clears the threshold.
+pub fn best_name<'a, S: AsRef<str>>(request: &str, candidates: &'a [S]) -> Option<&'a str> {
+    let payloads: Vec<Candidate<&'a str>> = candidates
+        .iter()
+        .map(|c| {
+            let name = c.as_ref();
+            Candidate {
+                match_key: name.to_string(),
+                stable_key: name.to_string(),
+                payload: name,
+            }
+        })
+        .collect();
+    rank(request, &payloads).into_iter().next()
+}
+
+fn normalize(input: &str) -> String {
+    input.trim().to_ascii_lowercase()
+}
+
+/// Standard Levenshtein edit distance. Pure, no dependencies.
+/// Compared strings must already be normalized (trim + lowercase) by
+/// the caller (`rank` does this internally).
+pub fn levenshtein(a: &str, b: &str) -> usize {
+    let a: Vec<char> = a.chars().collect();
+    let b: Vec<char> = b.chars().collect();
+    let mut prev: Vec<usize> = (0..=b.len()).collect();
+    let mut curr = vec![0usize; b.len() + 1];
+    for (i, &ca) in a.iter().enumerate() {
+        curr[0] = i + 1;
+        for (j, &cb) in b.iter().enumerate() {
+            let cost = if ca == cb { 0 } else { 1 };
+            curr[j + 1] = (prev[j + 1] + 1).min(curr[j] + 1).min(prev[j] + cost);
+        }
+        std::mem::swap(&mut prev, &mut curr);
+    }
+    prev[b.len()]
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn c(name: &str) -> Candidate<String> {
+        Candidate {
+            match_key: name.to_string(),
+            stable_key: name.to_string(),
+            payload: name.to_string(),
+        }
+    }
+
+    #[test]
+    fn levenshtein_basic() {
+        assert_eq!(levenshtein("kitten", "sitting"), 3);
+        assert_eq!(levenshtein("", ""), 0);
+        assert_eq!(levenshtein("abc", "abc"), 0);
+        assert_eq!(levenshtein("abc", "abd"), 1);
+    }
+
+    #[test]
+    fn prefix_hit_beats_lower_distance_non_prefix() {
+        // "stat" is a prefix of "status" (distance 2) but "slat" is
+        // distance 1 (mid-word substitution). Prefix wins.
+        let out = rank("stat", &[c("slat"), c("status")]);
+        assert_eq!(out, vec!["status".to_string(), "slat".to_string()]);
+    }
+
+    #[test]
+    fn distance_orders_non_prefix() {
+        let out = rank("btea", &[c("bota"), c("beta")]);
+        assert_eq!(out[0], "beta"); // 1 edit
+        assert_eq!(out[1], "bota"); // 2 edits
+    }
+
+    #[test]
+    fn stable_key_decides_tie() {
+        // Both "beta" and "bota" are distance 2 from "bata".
+        let out = rank("bata", &[c("bota"), c("beta")]);
+        assert_eq!(out, vec!["beta".to_string(), "bota".to_string()]);
+    }
+
+    #[test]
+    fn caps_at_three() {
+        let out = rank("aaaa", &[c("aaab"), c("aaac"), c("aaad"), c("aaae")]);
+        assert_eq!(out.len(), 3);
+        assert_eq!(out, vec!["aaab", "aaac", "aaad"]);
+    }
+
+    #[test]
+    fn case_preserved_in_payload() {
+        // "BTEA" normalized matches "Beta" (distance 1); the
+        // canonical payload preserves original casing.
+        let out = rank("BTEA", &[c("Beta")]);
+        assert_eq!(out, vec!["Beta".to_string()]);
+    }
+
+    #[test]
+    fn far_request_returns_empty() {
+        let out = rank("zzzzzz", &[c("beta")]);
+        assert!(out.is_empty());
+    }
+
+    #[test]
+    fn threshold_widens_with_length() {
+        assert_eq!(threshold_for_len(0), 1);
+        assert_eq!(threshold_for_len(3), 1);
+        assert_eq!(threshold_for_len(4), 2);
+        assert_eq!(threshold_for_len(6), 2);
+        assert_eq!(threshold_for_len(7), 3);
+        assert_eq!(threshold_for_len(20), 3);
+    }
+
+    #[test]
+    fn empty_request_returns_empty() {
+        let out = rank("", &[c("beta")]);
+        assert!(out.is_empty());
+    }
+
+    #[test]
+    fn dedup_on_stable_key() {
+        let out = rank(
+            "beta",
+            &[
+                c("beta"),
+                Candidate {
+                    match_key: "beta".to_string(),
+                    stable_key: "beta".to_string(),
+                    payload: "beta-dup".to_string(),
+                },
+            ],
+        );
+        assert_eq!(out, vec!["beta".to_string()]);
+    }
+
+    #[test]
+    fn best_name_convenience() {
+        assert_eq!(best_name("btea", &["beta", "bota"]), Some("beta"));
+        assert_eq!(best_name("zzzzzz", &["beta"]), None);
+    }
+
+    #[test]
+    fn statu_still_maps_to_status() {
+        // Byte-lock the existing emit.rs behavior: `statu` → `status`
+        // with the shared helper.
+        let out = rank(
+            "statu",
+            &[c("status"), c("send"), c("start"), c("restart")],
+        );
+        assert_eq!(out[0], "status");
+    }
+}

package/package.json

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