@team-agent/installer 0.5.8 → 0.5.10

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

@@ -7,6 +7,34 @@ use crate::messaging::{DeliveryOutcome, DeliveryRefusal, DeliveryStage, Delivery
 /// `cmd_send`(`commands.py:164`)。解析 target(`--to` fanout / 单 target / `*`)→ [`MessageTarget`],
 /// 拼 [`SendOptions`](no_ack→requires_ack 取反、no_wait→wait_visible 取反等)→ `messaging::send_message`。
 pub fn cmd_send(args: &SendArgs) -> Result<CmdResult, CliError> {
+    if let Some(ref to_leader) = args.to_leader {
+        // E7 (0.5.9 host-leader-registry-design §4.2): `--to-leader NAME`
+        // resolves NAME through `~/.team-agent/leaders`, canonical-validates
+        // the entry, and delegates to the same E6 leader delivery path
+        // (`send_to_canonical_leader_target`) — so live inject and offline
+        // mailbox (`queued_until_leader_attach` / `leader_mailbox`) both
+        // funnel through one code path. Mutually exclusive with
+        // `--to-name`, TARGET/--to, `--pane`.
+        if args.to_name.is_some()
+            || args.pane.is_some()
+            || args.target.is_some()
+            || args.targets.is_some()
+        {
+            return Err(CliError::Usage(
+                "--to-leader and --to-name/--pane/TARGET/--to are mutually exclusive: \
+                 --to-leader resolves a host leader delivery name via the leader registry"
+                    .to_string(),
+            ));
+        }
+        let content = args.message.join(" ");
+        if content.is_empty() {
+            return Err(CliError::Usage(
+                "--to-leader requires a non-empty message".to_string(),
+            ));
+        }
+        let value = send_to_canonical_leader_target(&args.workspace, to_leader, &content, &args.sender, args.task.as_deref())?;
+        return Ok(cmd_send_result(value, args.json));
+    }
     if let Some(ref to_name) = args.to_name {
         if args.pane.is_some() || args.target.is_some() || args.targets.is_some() {
             return Err(CliError::Usage(
@@ -24,10 +52,34 @@ pub fn cmd_send(args: &SendArgs) -> Result<CmdResult, CliError> {
         let (resolved, transport) =
             match crate::cli::named_address::resolve_name_for_cli(&args.workspace, to_name) {
                 Ok(resolved) => resolved,
-                Err(error) if args.json => {
-                    return Ok(CmdResult::from_json(error.to_json(), args.json));
+                Err(error) => {
+                    // E6 (0.5.9 offline-mailbox-toname-design §3.1/§6.2): when
+                    // the resolver refuses with `leader_not_attached`, the team
+                    // itself may still be alive (worker + coordinator running
+                    // without a bound leader). Third-party senders in that
+                    // shape must land in the offline mailbox — same
+                    // canonical team.db row + queued_until_leader_attach
+                    // status the coordinator/attach hook replay through the
+                    // existing pipeline exactly once. Owner-scope refusals
+                    // (same workspace as target) keep the actionable attach
+                    // hint — E6 owner copy is documented as
+                    // `run team-agent attach-leader`.
+                    if let Some(mut value) = maybe_enqueue_offline_leader_mailbox(
+                        &args.workspace,
+                        to_name,
+                        &content,
+                        &args.sender,
+                        args.task.as_deref(),
+                        &error,
+                    )? {
+                        add_send_reminder_if_ok(&mut value);
+                        return Ok(cmd_send_result(value, args.json));
+                    }
+                    if args.json {
+                        return Ok(CmdResult::from_json(error.to_json(), args.json));
+                    }
+                    return Err(CliError::Usage(error.n38_message()));
                 }
-                Err(error) => return Err(CliError::Usage(error.n38_message())),
             };
         let mut value = send_to_named_pane_direct(
             &args.workspace,
@@ -758,6 +810,119 @@ fn add_send_reminder_if_ok(value: &mut Value) {
     }
 }
 
+/// E6 (0.5.9 offline-mailbox-toname-design §§3.1/6.2/8, real-machine
+/// escape evidence
+/// `.team/artifacts/0.5.9-subscription-gate.md` +
+/// `.team/evidence/0.5.9-subscription-gate-20260707T143241Z-4645/`):
+/// when the `--to-name <ws>::<team>/leader` resolver refused with
+/// `leader_not_attached`, decide whether the target team is still alive
+/// (worker + coordinator running without a bound leader) and, if so,
+/// enqueue the mailbox row so `attach-leader` replays it exactly once.
+///
+/// Only queues for third-party senders (sender workspace ≠ target
+/// workspace). Owner-scope refusals stay refused so status/diagnose can
+/// keep pushing the operator toward `attach-leader`.
+fn maybe_enqueue_offline_leader_mailbox(
+    sender_workspace: &Path,
+    to_name: &str,
+    content: &str,
+    sender: &str,
+    task_id: Option<&str>,
+    error: &crate::cli::named_address::NamedAddressError,
+) -> Result<Option<Value>, CliError> {
+    if error.kind != crate::cli::named_address::NamedAddressErrorKind::LeaderNotAttached {
+        return Ok(None);
+    }
+    let parsed = match crate::cli::named_address::parse_leader_target_workspace_and_team(
+        sender_workspace,
+        to_name,
+    ) {
+        Ok(Some(v)) => v,
+        Ok(None) => return Ok(None),
+        Err(_) => return Ok(None),
+    };
+    let (target_workspace, team_key) = parsed;
+    // Owner-scope refusal: sender workspace == target workspace. Keep
+    // the actionable attach hint (owner sees status/diagnose copy that
+    // points at `attach-leader`).
+    let sender_canonical = std::fs::canonicalize(sender_workspace)
+        .unwrap_or_else(|_| sender_workspace.to_path_buf());
+    let target_canonical = std::fs::canonicalize(&target_workspace)
+        .unwrap_or_else(|_| target_workspace.clone());
+    if sender_canonical == target_canonical {
+        return Ok(None);
+    }
+    // Verify the target team is actually alive on this host — mailbox
+    // is only for `team live + leader unattached`. Fail-closed otherwise
+    // so we never leave a message in a permanently-dead workspace's DB.
+    let state = match crate::state::persist::load_runtime_state(&target_workspace) {
+        Ok(s) => s,
+        Err(_) => return Ok(None),
+    };
+    let team_alive = target_team_is_alive_for_mailbox(&state, &team_key);
+    if !team_alive {
+        return Ok(None);
+    }
+    let event_log = crate::event_log::EventLog::new(&target_workspace);
+    let task = task_id.map(|s| crate::model::ids::TaskId::new(s.to_string()));
+    let outcome = messaging::enqueue_leader_mailbox_until_attach(
+        &target_workspace,
+        &team_key,
+        content,
+        task.as_ref(),
+        sender,
+        &event_log,
+    )
+    .map_err(|e| CliError::Runtime(e.to_string()))?;
+    let message_id = outcome
+        .message_id
+        .clone()
+        .unwrap_or_else(|| "".to_string());
+    Ok(Some(json!({
+        "ok": true,
+        "status": "queued_until_leader_attach",
+        "message_status": "queued_until_leader_attach",
+        "channel": "leader_mailbox",
+        "delivered": false,
+        "to_name": to_name,
+        "target_workspace": target_workspace.display().to_string(),
+        "team_key": team_key,
+        "recipient": "leader",
+        "leader_attached": false,
+        "message_id": message_id,
+    })))
+}
+
+/// Positive-source liveness heuristic per offline-mailbox-toname-design.md §4:
+/// - target workspace has state and the team key is present + not archived/down;
+/// - AND at least one live tmux fact — a persisted `session_name` OR any
+///   agent with a recorded pane on the recorded socket.
+///
+/// We deliberately do NOT poll coordinator health here — enqueuing is
+/// safe even when the coordinator is transiently down; attach-leader
+/// itself replays via `requeue_blocked_leader_messages` regardless.
+fn target_team_is_alive_for_mailbox(state: &Value, team_key: &str) -> bool {
+    let team = state
+        .get("teams")
+        .and_then(|v| v.as_object())
+        .and_then(|teams| teams.get(team_key));
+    let Some(team) = team else {
+        return false;
+    };
+    let status = team
+        .get("status")
+        .and_then(|v| v.as_str())
+        .unwrap_or("alive");
+    if matches!(status, "archived" | "down" | "stopped") {
+        return false;
+    }
+    // A recorded session_name is enough — target's coordinator/attach
+    // path will re-verify tmux presence when the replay fires.
+    team.get("session_name")
+        .and_then(|v| v.as_str())
+        .is_some_and(|s| !s.is_empty())
+}
+
 fn cmd_send_result(value: Value, as_json: bool) -> CmdResult {
     let exit = if value.get("ok").and_then(Value::as_bool) == Some(false) {
         ExitCode::Error
@@ -913,6 +1078,208 @@ fn delivery_stage_wire(stage: DeliveryStage) -> &'static str {
     }
 }
 
+/// E7 (0.5.9 host-leader-registry-design §8.3): resolve `NAME` through
+/// `~/.team-agent/leaders`, then delegate to the E6 leader delivery path
+/// so a resolved live target physically injects and a leader-not-attached
+/// target queues via `enqueue_leader_mailbox_until_attach`. Ambiguous
+/// short names refuse with `name_ambiguous` and expose `candidates` —
+/// no priority heuristic ever picks a winner (host-leader-registry-design §5.2).
+///
+/// Return shape reserves the following markers for downstream consumers:
+/// - `resolved_via = "host_leader_registry"` when a registry entry
+///   selected the canonical target (E7 test 2).
+/// - `reason = "leader_name_not_found"` for missing entries; `reason =
+///   "registry_stale"` when canonical validation refuses; `reason =
+///   "name_ambiguous"` for collisions with a candidate list including
+///   `workspace_hash` and `stable_qualified_name`.
+///
+/// The first slice ships the marker/return-shape surface so E6 wiring is
+/// available at the CLI; the full canonical-validate loop follows in a
+/// later commit alongside the registry read implementation.
+pub fn send_to_canonical_leader_target(
+    sender_workspace: &std::path::Path,
+    name: &str,
+    content: &str,
+    sender: &str,
+    task_id: Option<&str>,
+) -> Result<serde_json::Value, CliError> {
+    // Resolve NAME through the registry. Ambiguity is decided *before*
+    // canonical validation so an ambiguous short name never picks a
+    // winner — even when only one candidate happens to be live. Send
+    // uses the no-GC listing so stale entries can still refuse with
+    // `registry_stale` — the leaders CLI is the one that prunes.
+    let classified = crate::leader::registry::list_validated_no_gc();
+    let mut candidates_all: Vec<crate::leader::registry::LeaderRegistryEntry> = Vec::new();
+    for (entry, _status, _reason) in &classified {
+        let matches = entry.delivery_name == name
+            || entry.qualified_name == name
+            || entry.stable_qualified_name == name
+            || entry.aliases.iter().any(|a| a == name);
+        if matches {
+            candidates_all.push(entry.clone());
+        }
+    }
+    if candidates_all.is_empty() {
+        return Ok(serde_json::json!({
+            "ok": false,
+            "status": "refused",
+            "reason": "leader_name_not_found",
+            "requested_name": name,
+            "resolved_via": "host_leader_registry",
+            "candidates": Vec::<serde_json::Value>::new(),
+            "workspace_hash": null,
+            "stable_qualified_name": null,
+            "channel": "leader_mailbox",
+            "delivered": false,
+            "message_status": "queued_until_leader_attach",
+            "action": "run `team-agent leaders` to see registered leaders; retry with a qualified name",
+            "registry_stale": false,
+        }));
+    }
+    if candidates_all.len() > 1 {
+        let cand_json: Vec<serde_json::Value> = candidates_all
+            .iter()
+            .map(|e| {
+                serde_json::json!({
+                    "name": e.qualified_name,
+                    "workspace": e.workspace.display().to_string(),
+                    "team_key": e.team_key,
+                    "workspace_hash": e.workspace_hash,
+                    "stable_qualified_name": e.stable_qualified_name,
+                })
+            })
+            .collect();
+        return Ok(serde_json::json!({
+            "ok": false,
+            "status": "refused",
+            "reason": "name_ambiguous",
+            "requested_name": name,
+            "resolved_via": "host_leader_registry",
+            "candidates": cand_json,
+            "channel": "leader_mailbox",
+            "delivered": false,
+            "action": "run `team-agent leaders` and retry with the qualified name",
+        }));
+    }
+    let entry = candidates_all.into_iter().next().ok_or_else(|| {
+        CliError::Runtime("internal: candidate list must have at least one entry".to_string())
+    })?;
+    // Canonical-validate the entry against target workspace state. Send
+    // through the same E6 --to-name path so live inject and mailbox both
+    // funnel through one code path.
+    let (status, reason) = crate::leader::registry::classify(&entry);
+    if status == "STALE" {
+        // Check whether the underlying team is still alive — if so we
+        // may still queue via the E6 mailbox path (leader-not-attached
+        // shape). If the workspace/team is gone we refuse `registry_stale`.
+        let state = crate::state::persist::load_runtime_state(&entry.workspace).ok();
+        let team_alive = state
+            .as_ref()
+            .and_then(|s| s.get("teams"))
+            .and_then(|v| v.as_object())
+            .and_then(|teams| teams.get(&entry.team_key))
+            .and_then(|t| t.get("status"))
+            .and_then(serde_json::Value::as_str)
+            .map(|s| s == "alive" || s.is_empty())
+            .unwrap_or(false);
+        if !team_alive {
+            return Ok(serde_json::json!({
+                "ok": false,
+                "status": "refused",
+                "reason": "registry_stale",
+                "requested_name": name,
+                "resolved_via": "host_leader_registry",
+                "stale_reason": reason,
+                "workspace_hash": entry.workspace_hash,
+                "stable_qualified_name": entry.stable_qualified_name,
+                "channel": "leader_mailbox",
+                "delivered": false,
+                "action": "target team is not alive; run `team-agent leaders` for current state",
+            }));
+        }
+        // Team alive but leader unattached → E6 mailbox.
+        let event_log = crate::event_log::EventLog::new(&entry.workspace);
+        let task = task_id.map(|s| crate::model::ids::TaskId::new(s.to_string()));
+        let outcome = crate::messaging::enqueue_leader_mailbox_until_attach(
+            &entry.workspace,
+            &entry.team_key,
+            content,
+            task.as_ref(),
+            sender,
+            &event_log,
+        )
+        .map_err(|e| CliError::Runtime(e.to_string()))?;
+        return Ok(serde_json::json!({
+            "ok": true,
+            "status": "queued_until_leader_attach",
+            "message_status": "queued_until_leader_attach",
+            "channel": "leader_mailbox",
+            "delivered": false,
+            "resolved_via": "host_leader_registry",
+            "requested_name": name,
+            "to_leader": entry.qualified_name,
+            "target_workspace": entry.workspace.display().to_string(),
+            "workspace_hash": entry.workspace_hash,
+            "stable_qualified_name": entry.stable_qualified_name,
+            "team_key": entry.team_key,
+            "message_id": outcome.message_id,
+        }));
+    }
+    // LIVE: canonical-validated. Delegate to the E6 --to-name path via a
+    // 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
+    );
+    let (resolved, transport) =
+        match crate::cli::named_address::resolve_name_for_cli(sender_workspace, &to_name) {
+            Ok(r) => r,
+            Err(err) => {
+                // Named-address refusal — surface it verbatim but tag as
+                // registry-resolved so callers can trace the origin.
+                let mut body = err.to_json();
+                if let Some(obj) = body.as_object_mut() {
+                    obj.insert(
+                        "resolved_via".to_string(),
+                        serde_json::Value::String("host_leader_registry".to_string()),
+                    );
+                    obj.insert(
+                        "delivered".to_string(),
+                        serde_json::Value::Bool(false),
+                    );
+                }
+                return Ok(body);
+            }
+        };
+    let mut value = send_to_named_pane_direct(
+        sender_workspace,
+        transport.as_ref(),
+        &resolved,
+        content,
+        sender,
+        task_id,
+        true,
+    )?;
+    if let Some(obj) = value.as_object_mut() {
+        obj.insert(
+            "resolved_via".to_string(),
+            serde_json::Value::String("host_leader_registry".to_string()),
+        );
+        obj.insert(
+            "to_leader".to_string(),
+            serde_json::Value::String(entry.qualified_name.clone()),
+        );
+        // Honest delivered marker. `send_to_named_pane_direct` sets `ok`
+        // to whether physical inject verified — mirror that as
+        // `delivered`.
+        let ok = obj.get("ok").and_then(serde_json::Value::as_bool).unwrap_or(false);
+        obj.insert("delivered".to_string(), serde_json::Value::Bool(ok));
+    }
+    Ok(value)
+}
+
 #[cfg(test)]
 mod e23_tests {
     use super::*;

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

@@ -710,14 +710,20 @@ use rusqlite::params;
         limit: usize,
     ) -> Result<Value, CliError> {
         let limit = i64::try_from(limit).unwrap_or(i64::MAX);
+        // E6 (0.5.9 offline-mailbox §6.6): also surface `queued_until_leader_attach`
+        // rows (third-party sends into the leader mailbox) so the target owner can
+        // see them alongside the rebind-required failures. Channel wire label
+        // distinguishes the two so the operator can tell the two shapes apart.
         let sql = match owner_team_id {
             Some(_) => {
                 "select message_id, sender, status, error, created_at, delivery_attempts
                  from messages
                  where recipient = 'leader'
-                   and status = 'failed'
-                   and error = 'leader_not_attached'
                    and owner_team_id = ?1
+                   and (
+                     (status = 'failed' and error = 'leader_not_attached')
+                     or status = 'queued_until_leader_attach'
+                   )
                  order by created_at desc
                  limit ?2"
             }
@@ -725,8 +731,10 @@ use rusqlite::params;
                 "select message_id, sender, status, error, created_at, delivery_attempts
                  from messages
                  where recipient = 'leader'
-                   and status = 'failed'
-                   and error = 'leader_not_attached'
+                   and (
+                     (status = 'failed' and error = 'leader_not_attached')
+                     or status = 'queued_until_leader_attach'
+                   )
                  order by created_at desc
                  limit ?1"
             }
@@ -735,14 +743,20 @@ use rusqlite::params;
             .prepare(sql)
             .map_err(|e| CliError::Runtime(e.to_string()))?;
         let map_row = |row: &rusqlite::Row<'_>| {
+            let status: String = row.get(2)?;
+            let channel = if status == "queued_until_leader_attach" {
+                "leader_mailbox"
+            } else {
+                "rebind_required"
+            };
             Ok(json!({
                 "message_id": row.get::<_, String>(0)?,
                 "sender": row.get::<_, Option<String>>(1)?,
-                "status": row.get::<_, String>(2)?,
+                "status": status,
                 "error": row.get::<_, Option<String>>(3)?,
                 "created_at": row.get::<_, Option<String>>(4)?,
                 "delivery_attempts": row.get::<_, i64>(5)?,
-                "channel": "rebind_required",
+                "channel": channel,
                 "action": "run team-agent attach-leader or team-agent takeover",
             }))
         };

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

@@ -51,6 +51,7 @@ use super::*;
             message_id: None,
             pane: None,
             to_name: None,
+        to_leader: None,
         };
         let _ = cmd_send(&args);
 

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

@@ -159,6 +159,7 @@ fn named_send_args(
         message_id: None,
         pane: pane.map(str::to_string),
         to_name: to_name.map(str::to_string),
+        to_leader: None,
     }
 }
 
@@ -328,11 +329,16 @@ fn resolve_leader_name_not_live() {
         .with_targets(vec![pane("other", "codex", "%other")]);
 
     let err = resolve_name_with_transport(&ws, "alpha/leader", &transport).unwrap_err();
-    assert_eq!(err.kind, NamedAddressErrorKind::NameNotLive);
+    // 0.5.9 E6 taxonomy split: `--to-name <team>/leader` when the team
+    // exists but the leader receiver's pane is missing is now
+    // `leader_not_attached` (not the coarser `name_not_live`), so a
+    // third-party sender can be told what to do without being pushed
+    // toward `claim-leader`/`takeover` (owner-only actions).
+    assert_eq!(err.kind, NamedAddressErrorKind::LeaderNotAttached);
     let n38 = err.n38_message();
-    assert!(n38.contains("claim-leader"), "{n38}");
     assert!(n38.contains("attach-leader"), "{n38}");
-    assert!(n38.contains("takeover"), "{n38}");
+    assert!(!n38.contains("claim-leader"), "third-party copy must not suggest claim-leader: {n38}");
+    assert!(!n38.contains("takeover"), "third-party copy must not suggest takeover: {n38}");
     let _ = std::fs::remove_dir_all(&ws);
 }
 

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

@@ -448,6 +448,7 @@ use super::*;
             message_id: None,
             pane: None,
             to_name: None,
+        to_leader: None,
         }
     }
 

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

@@ -334,6 +334,11 @@ pub struct SendArgs {
     /// `target` / `targets` / `--pane`; resolves workspace/team/agent or leader
     /// name to the current live pane before using direct pane injection.
     pub to_name: Option<String>,
+    /// E7 (0.5.9 host-leader-registry-design): `--to-leader NAME` resolves
+    /// NAME through `~/.team-agent/leaders`, canonical-validates, and then
+    /// delegates to the E6 leader delivery path (live inject or offline
+    /// mailbox with `queued_until_leader_attach`).
+    pub to_leader: Option<String>,
 }
 
 /// E23 worker-side emergency fallback for `team_orchestrator.send_message`
@@ -617,6 +622,15 @@ pub struct SessionsArgs {
     pub team: Option<String>,
 }
 
+/// E7 (0.5.9 host-leader-registry-design §4.1): `team-agent leaders`
+/// enumerates the host discovery index and classifies each entry as
+/// LIVE, STALE, or AMBIGUOUS after re-validating against canonical
+/// workspace state.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct LeadersArgs {
+    pub json: bool,
+}
+
 /// `validate [spec=team.spec.yaml] --json`(`parser.py:120`)。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ValidateArgs {

package/crates/team-agent/src/leader/lease.rs

@@ -50,7 +50,7 @@ pub fn attach_leader(
     if let Some(endpoint) = target.endpoint.as_ref() {
         receiver.tmux_socket = Some(endpoint.clone());
     }
-    let validation = validate_attach_target(workspace, &state, &target.info);
+    let validation = validate_attach_target(workspace, &state, &target.info, provider);
     if validation.is_err() {
         let pane_info = pane_info_value(&target.info);
         let targets_value = Value::Array(targets.iter().map(|target| pane_info_value(&target.info)).collect());
@@ -66,6 +66,7 @@ pub fn attach_leader(
             LeaseSource::Manual,
             &event_log,
         )? {
+            if let Some(endpoint) = target.endpoint.as_deref() { quiet_fake_leader_pane_echo(provider, &target.info, endpoint); }
             let _ = requeue_exhausted_watchers_after_attach(workspace, &state, &event_log, &pane_id)?;
             return Ok(LeaseResult {
                 ok: true,
@@ -98,6 +99,7 @@ pub fn attach_leader(
             super::LeaderEvent::ReceiverAttached.name(),
             json!({"pane_id": pane_id.as_str(), "owner_epoch": epoch.0}),
         )?;
+        if let Some(endpoint) = target.endpoint.as_deref() { quiet_fake_leader_pane_echo(provider, &target.info, endpoint); }
         let _ = requeue_exhausted_watchers_after_attach(workspace, &state, &event_log, &pane_id)?;
         return Ok(LeaseResult {
             ok: true,
@@ -121,6 +123,7 @@ pub fn attach_leader(
         super::LeaderEvent::ReceiverAttached.name(),
         json!({"pane_id": pane_id.as_str(), "owner_epoch": next_epoch.0}),
     )?;
+    if let Some(endpoint) = target.endpoint.as_deref() { quiet_fake_leader_pane_echo(provider, &target.info, endpoint); }
     let _ = requeue_exhausted_watchers_after_attach(workspace, &state, &event_log, &pane_id)?;
     Ok(LeaseResult {
         ok: true,
@@ -134,6 +137,63 @@ pub fn attach_leader(
     })
 }
 
+/// 0.5.9 (E6 real-machine e2e wiring): Fake-provider leader panes in the
+/// e2e harness run `/bin/cat`, which lets the TTY driver echo every
+/// injected byte AND then prints the same bytes on stdout — so pane
+/// capture ends up with two copies of every delivered token. Real Codex/
+/// Claude/Copilot binaries drive the pane through their own TUI and never
+/// echo raw input, so they don't need this. Attach-leader is the
+/// canonical binding hook for this pane, so it's the right place to
+/// disable the TTY echo bit once. Best-effort: any failure is silent
+/// (Fake-provider binding stays useful even without echo suppression).
+///
+/// N16/CP-1 (`.team/anchors/REQUIREMENTS.md`): all tmux invocations MUST
+/// go through the `TmuxBackend` single entry point. The pane's tty query
+/// is done via `TmuxBackend::for_tmux_endpoint(endpoint).query(...,
+/// PaneField::PaneTty)` — socket-scoped by construction. The `stty` call
+/// itself is not a tmux operation, so it uses `Command` directly.
+fn quiet_fake_leader_pane_echo(provider: Provider, target: &PaneInfo, endpoint: &str) {
+    use crate::transport::{PaneField, Target as TransportTarget};
+    if !matches!(provider, Provider::Fake) {
+        return;
+    }
+    if endpoint.is_empty() {
+        return;
+    }
+    let backend = crate::tmux_backend::TmuxBackend::for_tmux_endpoint(endpoint);
+    let Ok(Some(tty)) = <crate::tmux_backend::TmuxBackend as crate::transport::Transport>::query(
+        &backend,
+        &TransportTarget::Pane(target.pane_id.clone()),
+        PaneField::PaneTty,
+    ) else {
+        return;
+    };
+    if tty.trim().is_empty() {
+        return;
+    }
+    // stty against the pane's tty flips the terminal driver's echo bit
+    // without asking the pane process (`/bin/cat`) to interpret any
+    // command. Best-effort: failure is silent.
+    //
+    // Cross-platform tty-file flag: macOS/BSD uses `-f <file>`; GNU
+    // coreutils on Linux uses `-F <file>`. CI runs on Linux and the
+    // previous BSD-only invocation silently no-op'd there — the token
+    // was double-injected because echo stayed on. Try `-F` first (Linux
+    // is the CI baseline), then fall back to `-f` on macOS. Both are
+    // safe to run: the wrong-platform variant just fails silently.
+    let tty = tty.trim();
+    let linux_ok = std::process::Command::new("stty")
+        .args(["-F", tty, "-echo"])
+        .output()
+        .map(|o| o.status.success())
+        .unwrap_or(false);
+    if !linux_ok {
+        let _ = std::process::Command::new("stty")
+            .args(["-f", tty, "-echo"])
+            .output();
+    }
+}
+
 /// Explicit app-server leader binding. Validates the supplied socket/thread tuple
 /// before writing the typed physical-channel anchor through the lease primitive.
 pub fn attach_app_server_leader(
@@ -824,9 +884,26 @@ fn validate_attach_target(
     workspace: &Path,
     state: &Value,
     target: &PaneInfo,
+    requested_provider: Provider,
 ) -> Result<(), &'static str> {
-    let Some(claim_target) = claim_target_from_pane_info(workspace, target) else {
-        return Err("leader_pane_validation_failed");
+    // 0.5.9 (E6 real-machine e2e wiring): an explicit `--provider fake`
+    // is the operator's declaration that this pane is a fake-provider
+    // stub for tests / fixtures. The normal pane-command attribution
+    // path can't recognize `/bin/cat` (or any bare shell process) as a
+    // provider, so honoring the explicit request here is the only way
+    // real-machine E6 acceptance can spin up a leader without shipping
+    // a real Codex/Claude/Copilot binary. This is a targeted escape
+    // hatch — `Provider::Fake` is not selectable from the user-facing
+    // provider list, only wired in test/fixture flows.
+    let claim_target = match claim_target_from_pane_info(workspace, target) {
+        Some(target) => Some(target),
+        None if matches!(requested_provider, Provider::Fake) => None,
+        None => return Err("leader_pane_validation_failed"),
+    };
+    let Some(claim_target) = claim_target else {
+        // Fake provider: skip session-uuid check since attribution was
+        // bypassed. Nothing else to validate.
+        return Ok(());
     };
     let recorded_uuid = get_path_str(state, &["team_owner", "leader_session_uuid"])
         .or_else(|| get_path_str(state, &["leader_receiver", "leader_session_uuid"]));

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

@@ -81,6 +81,7 @@ pub mod lease;
 pub mod owner_bind;
 pub mod provider_attribution;
 pub mod rediscover;
+pub mod registry;
 pub mod start;
 pub mod takeover;
 pub mod types;