@team-agent/installer 0.5.59 → 0.5.61

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

@@ -151,7 +151,7 @@ pub mod lifecycle_port {
             .attach_session
             .as_ref()
             .map(|name| crate::transport::SessionName::new(name.clone()));
-        let plan = crate::leader::start::leader_start_plan(
+        let prepared = match crate::leader::start::prepare_leader_start_with_nested_attach(
             provider,
             provider_args,
             cwd,
@@ -159,16 +159,29 @@ pub mod lifecycle_port {
             attach.confirm_attach,
             attach_session.as_ref(),
             attach.external_leader,
-        )
-        .map_err(|e| CliError::Runtime(e.to_string()))?;
-        let outcome = crate::leader::start::execute_leader_plan(&plan, cwd)
+            attach.allow_nested_attach,
+        ) {
+            Ok(prepared) => prepared,
+            Err(crate::leader::start::PrepareLeaderStartError::PaneAuthorityRefused(refusal)) => {
+                return Ok(pane_authority_refusal_value(provider, attach, &refusal));
+            }
+            Err(crate::leader::start::PrepareLeaderStartError::Leader(error)) => {
+                return Err(CliError::Runtime(error.to_string()));
+            }
+        };
+        let outcome = crate::leader::start::execute_prepared_leader_start(&prepared, cwd)
             .map_err(|e| CliError::Runtime(e.to_string()))?;
+        let plan = prepared.plan();
         let ok = match outcome.status {
             crate::leader::LeaderLaunchStatus::Exited => outcome.exit_code == Some(0),
             crate::leader::LeaderLaunchStatus::Detached => true,
             crate::leader::LeaderLaunchStatus::NotStarted => false,
         };
-        let leader_attach_command = leader_attach_command_for_plan(cwd, &plan);
+        let leader_attach_command = if outcome.reason.as_deref() == Some("PaneWorkspaceMismatch") {
+            Some("team-agent attach-leader".to_string())
+        } else {
+            leader_attach_command_for_plan(cwd, &plan)
+        };
         Ok(json!({
             "ok": ok,
             "provider": provider,
@@ -187,6 +200,251 @@ pub mod lifecycle_port {
         }))
     }
 
+    fn pane_authority_refusal_value(
+        provider: Provider,
+        attach: &LeaderLauncherArgs,
+        refusal: &crate::model::pane_authority_refusal::PaneAuthorityRefusal,
+    ) -> Value {
+        use crate::model::pane_authority_refusal::{
+            PaneAuthorityRecoveryAction, PaneAuthorityRecoveryHint, PaneAuthorityRefusalFacts,
+            PaneAuthorityRefusalField, ACTION_FIELD, ACTION_REQUIRED_FIELD, HINT_ACTION_FIELD,
+            REASON_FIELD,
+        };
+
+        let mut facts = Map::new();
+        facts.insert(
+            REASON_FIELD.to_string(),
+            Value::String(refusal.reason().as_str().to_string()),
+        );
+        match &refusal.facts {
+            PaneAuthorityRefusalFacts::AmbientTmuxEndpointUnavailable(payload) => {
+                insert_path_fact(
+                    &mut facts,
+                    PaneAuthorityRefusalField::RequestedWorkspace,
+                    &payload.requested_workspace,
+                );
+                insert_unavailable_fact(
+                    &mut facts,
+                    PaneAuthorityRefusalField::Endpoint,
+                    payload.endpoint.availability().as_str(),
+                    payload.endpoint.cause.as_str(),
+                );
+            }
+            PaneAuthorityRefusalFacts::AmbientPaneIdUnavailable(payload) => {
+                insert_path_fact(
+                    &mut facts,
+                    PaneAuthorityRefusalField::RequestedWorkspace,
+                    &payload.requested_workspace,
+                );
+                insert_unavailable_fact(
+                    &mut facts,
+                    PaneAuthorityRefusalField::ObservedPaneId,
+                    payload.observed_pane_id.availability().as_str(),
+                    payload.observed_pane_id.cause.as_str(),
+                );
+                insert_string_fact(
+                    &mut facts,
+                    PaneAuthorityRefusalField::Endpoint,
+                    &payload.endpoint,
+                );
+            }
+            PaneAuthorityRefusalFacts::AmbientPaneWorkspaceUnavailable(payload) => {
+                insert_path_fact(
+                    &mut facts,
+                    PaneAuthorityRefusalField::RequestedWorkspace,
+                    &payload.requested_workspace,
+                );
+                insert_string_fact(
+                    &mut facts,
+                    PaneAuthorityRefusalField::ObservedPaneId,
+                    &payload.observed_pane_id,
+                );
+                insert_unavailable_fact(
+                    &mut facts,
+                    PaneAuthorityRefusalField::ObservedPaneWorkspace,
+                    payload.observed_pane_workspace.availability().as_str(),
+                    payload.observed_pane_workspace.cause.as_str(),
+                );
+                insert_string_fact(
+                    &mut facts,
+                    PaneAuthorityRefusalField::Endpoint,
+                    &payload.endpoint,
+                );
+            }
+            PaneAuthorityRefusalFacts::CallerControllingTtyUnavailable(payload) => {
+                insert_path_fact(
+                    &mut facts,
+                    PaneAuthorityRefusalField::RequestedWorkspace,
+                    &payload.requested_workspace,
+                );
+                insert_string_fact(
+                    &mut facts,
+                    PaneAuthorityRefusalField::ObservedPaneId,
+                    &payload.observed_pane_id,
+                );
+                insert_string_fact(
+                    &mut facts,
+                    PaneAuthorityRefusalField::Endpoint,
+                    &payload.endpoint,
+                );
+                insert_unavailable_fact(
+                    &mut facts,
+                    PaneAuthorityRefusalField::CallerControllingTty,
+                    payload.caller_controlling_tty.availability().as_str(),
+                    payload.caller_controlling_tty.cause.as_str(),
+                );
+            }
+            PaneAuthorityRefusalFacts::ObservedPaneTtyUnavailable(payload) => {
+                insert_path_fact(
+                    &mut facts,
+                    PaneAuthorityRefusalField::RequestedWorkspace,
+                    &payload.requested_workspace,
+                );
+                insert_string_fact(
+                    &mut facts,
+                    PaneAuthorityRefusalField::ObservedPaneId,
+                    &payload.observed_pane_id,
+                );
+                insert_string_fact(
+                    &mut facts,
+                    PaneAuthorityRefusalField::Endpoint,
+                    &payload.endpoint,
+                );
+                insert_unavailable_fact(
+                    &mut facts,
+                    PaneAuthorityRefusalField::ObservedPaneTty,
+                    payload.observed_pane_tty.availability().as_str(),
+                    payload.observed_pane_tty.cause.as_str(),
+                );
+            }
+            PaneAuthorityRefusalFacts::PaneTtyMismatch(payload) => {
+                insert_path_fact(
+                    &mut facts,
+                    PaneAuthorityRefusalField::RequestedWorkspace,
+                    &payload.requested_workspace,
+                );
+                insert_string_fact(
+                    &mut facts,
+                    PaneAuthorityRefusalField::ObservedPaneId,
+                    &payload.observed_pane_id,
+                );
+                insert_string_fact(
+                    &mut facts,
+                    PaneAuthorityRefusalField::Endpoint,
+                    &payload.endpoint,
+                );
+                facts.insert(
+                    PaneAuthorityRefusalField::CallerControllingTty
+                        .as_str()
+                        .to_string(),
+                    Value::from(payload.caller_controlling_tty),
+                );
+                facts.insert(
+                    PaneAuthorityRefusalField::ObservedPaneTty
+                        .as_str()
+                        .to_string(),
+                    Value::from(payload.observed_pane_tty),
+                );
+            }
+            PaneAuthorityRefusalFacts::PaneWorkspaceMismatch(payload) => {
+                insert_path_fact(
+                    &mut facts,
+                    PaneAuthorityRefusalField::RequestedWorkspace,
+                    &payload.requested_workspace,
+                );
+                insert_string_fact(
+                    &mut facts,
+                    PaneAuthorityRefusalField::ObservedPaneId,
+                    &payload.observed_pane_id,
+                );
+                insert_path_fact(
+                    &mut facts,
+                    PaneAuthorityRefusalField::ObservedPaneWorkspace,
+                    &payload.observed_pane_workspace,
+                );
+                insert_string_fact(
+                    &mut facts,
+                    PaneAuthorityRefusalField::Endpoint,
+                    &payload.endpoint,
+                );
+            }
+        }
+
+        let hint_action = match refusal.recovery.hint_action {
+            PaneAuthorityRecoveryHint::AttachLeader => "team-agent attach-leader",
+        };
+        let action = match refusal.recovery.action {
+            PaneAuthorityRecoveryAction::OpenTerminalOutsideCurrentTmuxPaneOrAttachFromMatchingPane => {
+                "open a new terminal window outside the current tmux/pane, confirm TMUX and \
+                 TMUX_PANE are absent, change directory to the requested workspace, and restart \
+                 the leader; alternatively enter the matching workspace pane and run \
+                 `team-agent attach-leader`"
+            }
+        };
+        facts.insert(
+            ACTION_REQUIRED_FIELD.to_string(),
+            Value::Bool(refusal.recovery.action_required),
+        );
+        facts.insert(
+            HINT_ACTION_FIELD.to_string(),
+            Value::String(hint_action.to_string()),
+        );
+        facts.insert(ACTION_FIELD.to_string(), Value::String(action.to_string()));
+
+        let mut value = json!({
+            "ok": false,
+            "provider": provider,
+            "mode": "exec_provider",
+            "leader_topology": if attach.external_leader { "external" } else { "managed" },
+            "is_external_leader": attach.external_leader,
+            "leader_window": null,
+            "leader_attach_command": hint_action,
+            "status": "not_started",
+            "exit_code": null,
+            "attach_existing": attach.attach_existing,
+            "confirm_attach": attach.confirm_attach,
+            "attach_session": attach.attach_session,
+            "session_name": null,
+        });
+        if let Some(object) = value.as_object_mut() {
+            object.extend(facts);
+        }
+        value
+    }
+
+    fn insert_path_fact(
+        facts: &mut Map<String, Value>,
+        field: crate::model::pane_authority_refusal::PaneAuthorityRefusalField,
+        value: &Path,
+    ) {
+        insert_string_fact(facts, field, &value.to_string_lossy());
+    }
+
+    fn insert_string_fact(
+        facts: &mut Map<String, Value>,
+        field: crate::model::pane_authority_refusal::PaneAuthorityRefusalField,
+        value: &str,
+    ) {
+        facts.insert(field.as_str().to_string(), Value::String(value.to_string()));
+    }
+
+    fn insert_unavailable_fact(
+        facts: &mut Map<String, Value>,
+        field: crate::model::pane_authority_refusal::PaneAuthorityRefusalField,
+        availability: &str,
+        cause: &str,
+    ) {
+        use crate::model::pane_authority_refusal::{AVAILABILITY_FIELD, CAUSE_FIELD};
+
+        let mut value = Map::new();
+        value.insert(
+            AVAILABILITY_FIELD.to_string(),
+            Value::String(availability.to_string()),
+        );
+        value.insert(CAUSE_FIELD.to_string(), Value::String(cause.to_string()));
+        facts.insert(field.as_str().to_string(), Value::Object(value));
+    }
+
     pub(crate) fn leader_attach_command_for_plan(
         cwd: &Path,
         plan: &crate::leader::LeaderStartPlan,

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

@@ -54,6 +54,10 @@ pub(crate) struct NamedAddressError {
     pub action: String,
     pub log: String,
     pub candidates: Vec<Value>,
+    /// A typed live-channel refusal retained separately from the broader
+    /// address error (for example `PaneWorkspaceMismatch` while the address
+    /// remains a leader-not-attached refusal).
+    pub channel_reason: Option<String>,
     // E6: when the caller supplied a `<team>/leader` name that isn't a runtime
     // team_key, echo the requested value + the canonical alternatives so
     // spec/display-name confusion is visibly diagnosed. Empty for other
@@ -76,6 +80,7 @@ impl NamedAddressError {
             action: "inspect team-agent status and use an explicit workspace/team name".to_string(),
             log: "named-address resolver refused before injection".to_string(),
             candidates: Vec::new(),
+            channel_reason: None,
             requested_team: None,
             available_team_keys: Vec::new(),
             suggested_name: None,
@@ -237,6 +242,12 @@ impl NamedAddressError {
             "candidates".to_string(),
             Value::Array(self.candidates.clone()),
         );
+        if let Some(channel_reason) = self.channel_reason.as_deref() {
+            obj.insert(
+                "channel_reason".to_string(),
+                Value::String(channel_reason.to_string()),
+            );
+        }
         if let Some(requested) = self.requested_team.as_deref() {
             obj.insert(
                 "requested_team".to_string(),
@@ -987,7 +998,13 @@ fn resolve_leader(
                 window,
                 socket,
             );
-            err.log = format!("{} channel_unbound={reason:?}", err.log);
+            if matches!(
+                &reason,
+                crate::messaging::LeaderChannelUnbound::PaneWorkspaceMismatch(_)
+            ) {
+                err.channel_reason = Some(reason.reason_code().to_string());
+            }
+            err.log = format!("{} channel_unbound={}", err.log, reason.reason_code());
             err.candidates =
                 leader_advisory_candidates(state, team, transport, "state_recorded_socket");
             Err(err)

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

@@ -169,6 +169,7 @@ pub(super) fn cmd_send_result(value: Value, as_json: bool) -> CmdResult {
             output: CmdOutput::Human(send_human_output(&value)),
             exit,
             as_json: false,
+            preserve_json_order: false,
         }
     }
 }
@@ -312,6 +313,7 @@ pub(super) fn delivery_refusal_wire(reason: DeliveryRefusal) -> &'static str {
         DeliveryRefusal::TmuxTargetMissing => "tmux_target_missing",
         DeliveryRefusal::MessageAlreadyClaimed => "message_already_claimed",
         DeliveryRefusal::LeaderNotAttached => "leader_not_attached",
+        DeliveryRefusal::PaneWorkspaceMismatch => "PaneWorkspaceMismatch",
         DeliveryRefusal::CoordinatorUnavailable => "coordinator_unavailable",
         DeliveryRefusal::NoCallerPane => "no_caller_pane",
         DeliveryRefusal::TeamOwnerMismatch => "team_owner_mismatch",

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

@@ -76,6 +76,7 @@ pub(crate) enum DispatchKind {
     InstallSkill,
     Profile,
     Collect,
+    Results,
     Diagnose,
     Preflight,
     WaitReady,
@@ -120,6 +121,7 @@ pub(crate) const ALL_DISPATCH_KINDS: &[DispatchKind] = &[
     DispatchKind::InstallSkill,
     DispatchKind::Profile,
     DispatchKind::Collect,
+    DispatchKind::Results,
     DispatchKind::Diagnose,
     DispatchKind::Preflight,
     DispatchKind::WaitReady,
@@ -155,9 +157,10 @@ 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: "persist a message for an in-team short name or fully-qualified logical recipient", usage: "usage: team-agent send TO MESSAGE... [--workspace WORKSPACE] [--team TEAM] [--presentation-sink leader|casefile|silent --message-class CLASS [--case-id CASE]] [--json]\nTO forms are co-equal: an in-team short name (for example `team-agent send reviewer \"Review\"`) or `<workspace>::<team>/<agent>`.", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, alias_of: None, sunset: Some("next compatibility release"), action: Some("use positional logical TO and the returned message id"), governance: None },
+    CommandSpec { name: "send", tier: CommandTier::Core, category: CommandCategory::Daily, kind: CommandKind::Dispatch(DispatchKind::Send), summary: "persist a message for an in-team short name or fully-qualified logical recipient", usage: "usage: team-agent send TO MESSAGE... [--workspace WORKSPACE] [--team TEAM] [--mailbox] [--json]\nTO forms are co-equal: an in-team short name (for example `team-agent send reviewer \"Review\"`) or `<workspace>::<team>/<agent>`.", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, alias_of: None, sunset: Some("next compatibility release"), action: Some("use positional logical TO and the returned message id"), 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: "results", tier: CommandTier::Core, category: CommandCategory::Daily, kind: CommandKind::Dispatch(DispatchKind::Results), summary: "read reported results for a case", usage: "usage: team-agent results --case CASE_ID [--workspace WORKSPACE] [--team TEAM] [--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 },
     CommandSpec { name: "shutdown", tier: CommandTier::Core, category: CommandCategory::TeamLifecycle, kind: CommandKind::Dispatch(DispatchKind::Shutdown), summary: "stop the selected team", usage: "usage: team-agent shutdown [--workspace WORKSPACE] [--team TEAM] [--keep-logs] [--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: "add-agent", tier: CommandTier::Core, category: CommandCategory::WorkerLifecycle, kind: CommandKind::Dispatch(DispatchKind::AddAgent), summary: "add or force-recreate a worker", usage: "usage: team-agent add-agent AGENT --role-file FILE [--force] [--workspace WORKSPACE] [--team TEAM] [--no-display] [--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/status_port/store.rs

@@ -393,12 +393,16 @@ pub(super) fn count_undelivered_backlog(
     conn: &rusqlite::Connection,
     owner_team_id: Option<&str>,
 ) -> Result<i64, CliError> {
-    // Backlog statuses chosen to mirror what `deliver_pending` would pick up.
+    // Delivery debt is broader than requeue eligibility: a physically injected
+    // row awaiting a future receipt remains undelivered even though it must not
+    // be claimed or injected again.
     let sql = match owner_team_id {
             Some(_) => "select count(*) from messages
-                       where owner_team_id = ?1 and status in ('accepted','pending','queued','queued_until_trust')",
+                       where owner_team_id = ?1 and status in
+                       ('accepted','pending','queued','queued_until_trust','injected_awaiting_receipt')",
             None => "select count(*) from messages
-                     where status in ('accepted','pending','queued','queued_until_trust')",
+                     where status in
+                     ('accepted','pending','queued','queued_until_trust','injected_awaiting_receipt')",
         };
     let count: i64 = match owner_team_id {
         Some(team) => conn

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

@@ -135,6 +135,17 @@ fn assert_kind(
     assert!(n38.contains("Log: "), "{n38}");
 }
 
+fn assert_broad_leader_not_attached(err: NamedAddressError) {
+    assert_eq!(err.kind, NamedAddressErrorKind::LeaderNotAttached);
+    assert_eq!(err.channel_reason, None);
+    let value = err.to_json();
+    assert_eq!(value["reason"], json!("leader_not_attached"));
+    assert!(
+        value.get("channel_reason").is_none(),
+        "broad refusal must not expose a typed channel reason: {value}"
+    );
+}
+
 fn named_send_args(
     ws: &Path,
     to_name: Option<&str>,
@@ -372,6 +383,60 @@ fn resolve_leader_name_not_live() {
     let _ = std::fs::remove_dir_all(&ws);
 }
 
+#[test]
+fn resolve_leader_receiver_not_attached_stays_broad() {
+    let ws = named_ws("leader-receiver-not-attached");
+    let mut team = leader_team("alpha-session", "%leader", "/tmp/leader.sock");
+    team["leader_receiver"]["status"] = json!("rebind_required");
+    seed_state(
+        &ws,
+        state_with_teams(json!({
+            "alpha": team
+        })),
+    );
+    let transport = OfflineTransport::new()
+        .with_tmux_endpoint("/tmp/leader.sock")
+        .with_targets(vec![pane("alpha-session-leader", "codex", "%leader")]);
+
+    let err = resolve_name_with_transport(&ws, "alpha/leader", &transport).unwrap_err();
+    assert_broad_leader_not_attached(err);
+    let _ = std::fs::remove_dir_all(&ws);
+}
+
+#[test]
+fn resolve_leader_pane_not_live_stays_broad() {
+    let ws = named_ws("leader-pane-not-live");
+    seed_state(
+        &ws,
+        state_with_teams(json!({
+            "alpha": leader_team("alpha-session", "%missing", "/tmp/leader.sock")
+        })),
+    );
+    let transport = OfflineTransport::new().with_tmux_endpoint("/tmp/leader.sock");
+
+    let err = resolve_name_with_transport(&ws, "alpha/leader", &transport).unwrap_err();
+    assert_broad_leader_not_attached(err);
+    let _ = std::fs::remove_dir_all(&ws);
+}
+
+#[test]
+fn resolve_leader_probe_failure_stays_broad() {
+    let ws = named_ws("leader-probe-failed");
+    seed_state(
+        &ws,
+        state_with_teams(json!({
+            "alpha": leader_team("alpha-session", "%leader", "/tmp/leader.sock")
+        })),
+    );
+    let transport = OfflineTransport::new()
+        .with_tmux_endpoint("/tmp/leader.sock")
+        .with_list_targets_error("injected leader pane probe failure");
+
+    let err = resolve_name_with_transport(&ws, "alpha/leader", &transport).unwrap_err();
+    assert_broad_leader_not_attached(err);
+    let _ = std::fs::remove_dir_all(&ws);
+}
+
 #[test]
 fn resolve_leader_name_after_rebind() {
     let ws = named_ws("leader-rebind");

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

@@ -107,6 +107,10 @@ impl CliError {
             payload.action = String::from(
                 "move the Team Agent launcher flag before `--`; only provider flags belong after `--`",
             );
+        } else if error.contains("managed launcher refuses a different ambient tmux server") {
+            payload.action = String::from(
+                "leave the current tmux client and retry, or pass `--allow-nested-attach` before `--` to opt in to a nested managed attach",
+            );
         }
         payload
     }
@@ -160,6 +164,8 @@ pub struct CmdResult {
     pub exit: ExitCode,
     /// `--json` 旗标(决定 `emit` 与 inbox 摘要落 stderr vs stdout,`parser.py:505-506`)。
     pub as_json: bool,
+    /// Preserve nested object insertion order for byte-faithful stored envelopes.
+    pub preserve_json_order: bool,
 }
 
 impl CmdResult {
@@ -174,6 +180,20 @@ impl CmdResult {
             output: CmdOutput::Json(value),
             exit,
             as_json,
+            preserve_json_order: false,
+        }
+    }
+    pub fn from_ordered_json(value: Value) -> Self {
+        let exit = if value.get("ok").and_then(Value::as_bool) == Some(false) {
+            ExitCode::Error
+        } else {
+            ExitCode::Ok
+        };
+        Self {
+            output: CmdOutput::Json(value),
+            exit,
+            as_json: true,
+            preserve_json_order: true,
         }
     }
     pub fn human(text: impl Into<String>) -> Self {
@@ -181,6 +201,7 @@ impl CmdResult {
             output: CmdOutput::Human(text.into()),
             exit: ExitCode::Ok,
             as_json: false,
+            preserve_json_order: false,
         }
     }
     pub fn none() -> Self {
@@ -188,6 +209,7 @@ impl CmdResult {
             output: CmdOutput::None,
             exit: ExitCode::Ok,
             as_json: false,
+            preserve_json_order: false,
         }
     }
 }
@@ -210,6 +232,8 @@ pub struct LeaderLauncherArgs {
     pub attach_session: Option<String>,
     /// 0.3.16 topology opt-out: keep the old external/current-pane leader launcher path.
     pub external_leader: bool,
+    /// N41 explicit opt-in for attaching a managed leader from another tmux server.
+    pub allow_nested_attach: bool,
 }
 
 // =============================================================================
@@ -643,6 +667,15 @@ pub struct CollectArgs {
     pub team: Option<String>,
 }
 
+/// Read-only lookup of all stored result envelopes for one case.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ResultsArgs {
+    pub case_id: String,
+    pub workspace: PathBuf,
+    pub team: Option<String>,
+    pub json: bool,
+}
+
 /// `diagnose`(`parser.py:298`) runtime health report, distinct from `doctor`.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct DiagnoseArgs {

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

@@ -0,0 +1,53 @@
+//! Official communication modes shared by configuration and projection consumers.
+
+/// The complete product-supported communication-mode catalog.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CommunicationMode {
+    LeaderCentric,
+    Orchestrated,
+}
+
+const LEADER_CENTRIC_RUNTIME_CONTRACT: &str = r#"# Team Agent communication contract: leader_centric
+
+- Progress, blockers, questions: team_orchestrator.send_message(to='leader', content='...')
+
+When you receive a message from the leader or a teammate, you MUST respond
+through MCP tools. Writing a reply in your terminal does nothing — the sender
+will never see it."#;
+
+const ORCHESTRATED_RUNTIME_CONTRACT: &str = r#"# Team Agent communication contract: orchestrated
+
+- Send progress only through the declared channel for the assigned task.
+- Respond to task-related messages through Team Agent MCP tools.
+- A pure ACK, unrelated status, or non-task message does not require a response."#;
+
+impl CommunicationMode {
+    pub const ALL: &[Self] = &[Self::LeaderCentric, Self::Orchestrated];
+
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::LeaderCentric => "leader_centric",
+            Self::Orchestrated => "orchestrated",
+        }
+    }
+
+    pub fn parse(value: &str) -> Option<Self> {
+        Self::ALL
+            .iter()
+            .copied()
+            .find(|mode| mode.as_str() == value)
+    }
+
+    pub const fn runtime_contract(self) -> &'static str {
+        match self {
+            Self::LeaderCentric => LEADER_CENTRIC_RUNTIME_CONTRACT,
+            Self::Orchestrated => ORCHESTRATED_RUNTIME_CONTRACT,
+        }
+    }
+}
+
+impl Default for CommunicationMode {
+    fn default() -> Self {
+        Self::LeaderCentric
+    }
+}