@team-agent/installer 0.5.44 → 0.5.46

package/crates/team-agent/src/lifecycle/restart/rebuild.rs

@@ -428,6 +428,18 @@ fn restart_with_selected_team_and_transport(
     let live_worker_session_deferred_teardown =
         session_live_or_default(transport, &session_name, false)
             && !collect_live_agents_from_state(&state).is_empty();
+    let same_role_cohort_targets =
+        same_role_cohort_targets_from_decisions(&state, spec_workspace, &plan.decisions);
+    let pre_spawn_pane_ids = if live_worker_session_deferred_teardown {
+        transport
+            .list_targets()
+            .map_err(|error| LifecycleError::Transport(error.to_string()))?
+            .into_iter()
+            .map(|pane| pane.pane_id.as_str().to_string())
+            .collect::<std::collections::BTreeSet<_>>()
+    } else {
+        std::collections::BTreeSet::new()
+    };
     if session_live_or_default(transport, &session_name, false)
         && !live_worker_session_deferred_teardown
     {
@@ -779,6 +791,46 @@ fn restart_with_selected_team_and_transport(
         );
     }
     // END_B5_RESTART_ISOLATION_LOOP
+    if live_worker_session_deferred_teardown {
+        let successful_agent_ids = successful_agents
+            .iter()
+            .map(|agent| agent.agent_id.as_str())
+            .collect::<std::collections::BTreeSet<_>>();
+        let old_successful_targets = same_role_cohort_targets
+            .iter()
+            .filter(|target| successful_agent_ids.contains(target.agent_id.as_str()))
+            .cloned()
+            .collect::<Vec<_>>();
+        let successful_targets =
+            same_role_cohort_targets_from_decisions(&state, spec_workspace, &successful_agents);
+        let actual_spawn_panes = actual_successful_restart_spawn_panes(
+            transport,
+            &session_name,
+            &successful_targets,
+            &pre_spawn_pane_ids,
+        )?;
+        if let Some(error) =
+            actual_restart_spawn_binding_error(&successful_targets, &actual_spawn_panes)
+        {
+            cleanup_actual_restart_spawns(transport, &actual_spawn_panes);
+            return Err(LifecycleError::RequirementUnmet(error));
+        }
+        if let Err(error) =
+            retire_expected_same_role_cohorts(transport, "restart", &old_successful_targets)
+        {
+            cleanup_actual_restart_spawns(transport, &actual_spawn_panes);
+            return Err(LifecycleError::RequirementUnmet(error));
+        }
+        if let Some(error) = same_role_cohort_exactly_one_error(
+            transport,
+            &session_name,
+            "restart",
+            &successful_targets,
+        ) {
+            cleanup_actual_restart_spawns(transport, &actual_spawn_panes);
+            return Err(LifecycleError::RequirementUnmet(error));
+        }
+    }
     let mut topology_authority_agent_ids = successful_agents
         .iter()
         .map(|agent| agent.agent_id.as_str().to_string())
@@ -2090,6 +2142,122 @@ fn mark_fake_harness_agent_respawned(
     agent.insert("owner_team_id".to_string(), serde_json::json!(team_key));
 }
 
+fn same_role_cohort_targets_from_decisions(
+    state: &serde_json::Value,
+    spec_workspace: &Path,
+    agents: &[RestartedAgent],
+) -> Vec<SameRoleCohortTarget> {
+    let mut targets = Vec::new();
+    for restarted in agents {
+        let agent_id = &restarted.agent_id;
+        let raw_agent = state
+            .get("agents")
+            .and_then(|agents| agents.get(agent_id.as_str()));
+        let effective_agent = raw_agent.map(|agent| {
+            rehydrate_agent_command_context_from_spec(spec_workspace, agent_id, agent)
+        });
+        if effective_agent
+            .as_ref()
+            .and_then(|agent| agent.get("provider"))
+            .and_then(serde_json::Value::as_str)
+            .is_some_and(|provider| provider.eq_ignore_ascii_case("fake"))
+        {
+            continue;
+        }
+        let window = raw_agent
+            .and_then(|agent| agent.get("window"))
+            .and_then(serde_json::Value::as_str)
+            .filter(|value| !value.is_empty())
+            .unwrap_or_else(|| agent_id.as_str());
+        if is_per_agent_cohort_window(window, agent_id) {
+            let expected_pane_id = raw_agent
+                .and_then(|agent| agent.get("pane_id"))
+                .and_then(serde_json::Value::as_str)
+                .filter(|value| !value.is_empty());
+            targets.push(
+                SameRoleCohortTarget::new(agent_id, window).with_expected_pane_id(expected_pane_id),
+            );
+        }
+    }
+    targets
+}
+
+fn actual_successful_restart_spawn_panes(
+    transport: &dyn crate::transport::Transport,
+    session_name: &SessionName,
+    targets: &[SameRoleCohortTarget],
+    pre_spawn_pane_ids: &std::collections::BTreeSet<String>,
+) -> Result<Vec<crate::transport::PaneInfo>, LifecycleError> {
+    let windows = targets
+        .iter()
+        .map(|target| target.window.as_str())
+        .collect::<std::collections::BTreeSet<_>>();
+    let panes = transport
+        .list_targets()
+        .map_err(|error| LifecycleError::Transport(error.to_string()))?
+        .into_iter()
+        .filter(|pane| !pre_spawn_pane_ids.contains(pane.pane_id.as_str()))
+        .filter(|pane| pane.session.as_str() == session_name.as_str())
+        .filter(|pane| {
+            pane.window_name
+                .as_ref()
+                .is_some_and(|window| windows.contains(window.as_str()))
+        })
+        .filter(|pane| {
+            transport
+                .liveness(&pane.pane_id)
+                .is_ok_and(|state| state == crate::transport::PaneLiveness::Live)
+        })
+        .collect();
+    Ok(panes)
+}
+
+fn actual_restart_spawn_binding_error(
+    targets: &[SameRoleCohortTarget],
+    actual_spawn_panes: &[crate::transport::PaneInfo],
+) -> Option<String> {
+    let mut mismatches = Vec::new();
+    for target in targets {
+        let observed = actual_spawn_panes
+            .iter()
+            .filter(|pane| {
+                pane.window_name
+                    .as_ref()
+                    .is_some_and(|window| window.as_str() == target.window)
+            })
+            .map(|pane| pane.pane_id.as_str().to_string())
+            .collect::<Vec<_>>();
+        if observed.len() != 1
+            || target.expected_pane_id.as_deref() != observed.first().map(String::as_str)
+        {
+            mismatches.push(format!(
+                "{}:window={}:expected_pane={}:actual_spawn_panes=[{}]",
+                target.agent_id,
+                target.window,
+                target.expected_pane_id.as_deref().unwrap_or("<missing>"),
+                observed.join(",")
+            ));
+        }
+    }
+    if mismatches.is_empty() {
+        None
+    } else {
+        Some(format!(
+            "restart refused: spawn identity/binding mismatch; {}",
+            mismatches.join("; ")
+        ))
+    }
+}
+
+fn cleanup_actual_restart_spawns(
+    transport: &dyn crate::transport::Transport,
+    actual_spawn_panes: &[crate::transport::PaneInfo],
+) {
+    for pane in actual_spawn_panes {
+        let _ = transport.kill_pane(&pane.pane_id);
+    }
+}
+
 fn write_fake_harness_spawn_argv_event(
     workspace: &Path,
     decision: &RestartedAgent,

package/crates/team-agent/src/lifecycle/tests/agent_ops.rs

@@ -402,6 +402,11 @@ case "$*" in
     ;;
 esac
 case "$*" in
+  *"new-window "*|*"new-session "*)
+    : > "$spawned_marker"
+    printf '%%9288\n'
+    exit 0
+    ;;
   *"display-message -p -t $pane #{pane_id}"*)
     if [ -f "$killed_marker" ]; then
       echo "can't find pane: $pane" >&2
@@ -410,11 +415,6 @@ case "$*" in
     printf '%s\n' "$pane"
     exit 0
     ;;
-  *"display-message -p -t $session:alpha #{pane_id}"*)
-    : > "$spawned_marker"
-    printf '%%9288\n'
-    exit 0
-    ;;
   *"list-windows -t $session -F #{window_name}"*)
     exit 0
     ;;
@@ -873,8 +873,8 @@ fn reset_agent_stop_not_proven_grep_guard_hard_gate_wired() {
         "reset_agent_at_paths must emit reset_agent.stop_not_proven via the writer"
     );
     assert!(
-        contents.contains("if !agent_is_paused && !stop.stopped"),
-        "gate must run only when stop.stopped=false (the dangerous case)"
+        contents.contains("if !agent_is_paused {"),
+        "gate must run after stop for every non-paused reset, including stop.stopped=true residue"
     );
     assert!(
         contents.contains("list_same_role_panes") && contents.contains("is_per_agent_window"),

package/crates/team-agent/src/lifecycle/tests/phase_b_contracts.rs

@@ -744,7 +744,7 @@ impl Transport for BRealTransport {
         if matches!(self.mode, BRealMode::Misowned) {
             targets.push(pane_info("team-phaseb", "w2", "%5", 502));
         }
-        if matches!(self.mode, BRealMode::Owned) {
+        if matches!(self.mode, BRealMode::Owned) && !self.spawns.lock().unwrap().is_empty() {
             targets.push(pane_info("team-phaseb", "w1", "%10", 501));
         }
         Ok(targets)

package/crates/team-agent/src/lifecycle/tests/phase_golden.rs

@@ -553,6 +553,9 @@ fn normalize_value(value: Value, ctx: &mut NormalizeCtx, key: Option<&str>) -> V
             let sorted = map.into_iter().collect::<BTreeMap<_, _>>();
             let mut out = Map::new();
             for (child_key, child) in sorted {
+                if matches!(child_key.as_str(), "model_source" | "provider_source") {
+                    continue;
+                }
                 out.insert(
                     child_key.clone(),
                     normalize_value(child, ctx, Some(child_key.as_str())),

package/crates/team-agent/src/lifecycle/types.rs

@@ -632,6 +632,9 @@ pub enum ResetAgentOutcome {
         discarded_session_id: Option<SessionId>,
         session_id: Option<SessionId>,
         new_session_id: Option<SessionId>,
+        capture_state: String,
+        reset_proof: String,
+        weak_reset_warning: Option<String>,
     },
     /// 未传 discard_session → 拒绝(不丢上下文的误用保护)。
     Refused { reason: ResetRefusal },

package/crates/team-agent/src/mcp_server/lifecycle_tools/agent_ops.rs

@@ -67,6 +67,9 @@ pub(crate) fn reset_agent(
             discarded_session_id,
             session_id,
             new_session_id,
+            capture_state,
+            reset_proof,
+            weak_reset_warning,
         } => Ok(ToolOk {
             fields: object_fields(serde_json::json!({
                 "ok": true,
@@ -78,6 +81,13 @@ pub(crate) fn reset_agent(
                 "discarded_session_id": discarded_session_id.as_ref().map(|id| id.as_str()),
                 "session_id": session_id.as_ref().map(|id| id.as_str()),
                 "new_session_id": new_session_id.as_ref().map(|id| id.as_str()),
+                "capture_state": match capture_state.as_str() {
+                    "captured" => "captured",
+                    "attribution_ambiguous" => "attribution_ambiguous",
+                    _ => "transcript_missing",
+                },
+                "reset_proof": if reset_proof == "weak" { "weak" } else { "strong" },
+                "weak_reset_warning": weak_reset_warning,
             })),
         }),
         ResetAgentOutcome::Refused { reason } => Ok(ToolOk {

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");
+    }
+}