@team-agent/installer 0.5.52 → 0.5.54

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

@@ -33,6 +33,7 @@ pub fn tools_contract() -> Vec<Value> {
         McpTool::StopAgent,
         McpTool::ResetAgent,
         McpTool::AddAgent,
+        McpTool::CloneAgent,
         McpTool::ForkAgent,
         McpTool::RequestHuman,
         McpTool::StuckList,
@@ -368,16 +369,20 @@ fn python_repr(value: &str) -> String {
 fn tool_contract(tool: McpTool) -> Value {
     let (description, required) = match tool {
         McpTool::SendMessage => (
-            "Send a message to a teammate, the leader, or '*' for all other team members. Provide only target and content; Team Agent fills sender, task id, ack policy, and delivery metadata.",
+            "Send a message to a teammate, the leader, or '*' for all other team members. Team Agent fills identity and delivery metadata; optional presentation routing is durable and never drops the message.",
             vec!["to", "content"],
         ),
         McpTool::AssignTask => ("Assign or update a task in the team graph and deliver it to its assignee.", vec!["task"]),
-        McpTool::ReportResult => ("Report task completion with a result envelope.", Vec::new()),
+        McpTool::ReportResult => (
+            "Report task completion with a durable result envelope. Optional presentation routing controls live leader display, not persistence.",
+            Vec::new(),
+        ),
         McpTool::UpdateState => ("Append a note to team state and rewrite team_state.md.", vec!["note"]),
         McpTool::GetTeamStatus => ("Return machine-readable team status.", Vec::new()),
         McpTool::StopAgent => ("Stop a running worker.", vec!["agent_id"]),
         McpTool::ResetAgent => ("Reset one worker to a fresh session.", vec!["agent_id", "discard_session"]),
         McpTool::AddAgent => ("Add a first-class worker from a role file.", vec!["new_agent_id", "role_file_path"]),
+        McpTool::CloneAgent => ("Clone a worker role into a fresh provider session.", vec!["source_agent_id", "as_agent_id"]),
         McpTool::ForkAgent => ("Fork a running worker.", vec!["source_agent_id", "as_agent_id"]),
         McpTool::RequestHuman => ("Ask the leader or user for human input.", vec!["question"]),
         McpTool::StuckList => ("List manually suppressed idle alerts.", Vec::new()),
@@ -417,6 +422,11 @@ fn tool_properties(tool: McpTool) -> serde_json::Map<String, Value> {
                 string_property("Target agent id, 'leader', or '*' for broadcast."),
             );
             insert_property(&mut properties, "content", string_property("Message body."));
+            insert_property(
+                &mut properties,
+                "presentation",
+                presentation_property("Optional durable presentation routing."),
+            );
         }
         McpTool::ReportResult => {
             insert_property(
@@ -465,6 +475,11 @@ fn tool_properties(tool: McpTool) -> serde_json::Map<String, Value> {
                 "agent_id",
                 string_property("Optional reporting agent id override."),
             );
+            insert_property(
+                &mut properties,
+                "presentation",
+                presentation_property("Optional durable presentation routing."),
+            );
         }
         McpTool::UpdateState => {
             insert_property(
@@ -522,6 +537,23 @@ fn tool_properties(tool: McpTool) -> serde_json::Map<String, Value> {
                 string_property("Optional display label."),
             );
         }
+        McpTool::CloneAgent => {
+            insert_property(
+                &mut properties,
+                "source_agent_id",
+                string_property("Agent id to clone from."),
+            );
+            insert_property(
+                &mut properties,
+                "as_agent_id",
+                string_property("Agent id for the cloned worker."),
+            );
+            insert_property(
+                &mut properties,
+                "label",
+                string_property("Optional display label."),
+            );
+        }
         McpTool::RequestHuman => {
             insert_property(
                 &mut properties,
@@ -571,6 +603,23 @@ fn object_property(description: &str) -> Value {
     serde_json::json!({"type": "object", "description": description, "additionalProperties": true})
 }
 
+fn presentation_property(description: &str) -> Value {
+    serde_json::json!({
+        "type": "object",
+        "description": description,
+        "properties": {
+            "sink": {"type": "string", "enum": ["leader", "casefile", "silent"]},
+            "class": {"type": "string", "enum": [
+                "message", "progress", "stage_result", "stage_pass", "bounce",
+                "blocking", "final_review", "timeout"
+            ]},
+            "case_id": {"type": "string"}
+        },
+        "required": ["sink", "class"],
+        "additionalProperties": false
+    })
+}
+
 fn array_property(description: &str) -> Value {
     serde_json::json!({"type": "array", "description": description, "items": {"type": "object", "additionalProperties": true}})
 }
@@ -591,12 +640,13 @@ pub(crate) fn dispatch_tool(
         McpTool::SendMessage => {
             let target = message_target_from_value(args.get("to"));
             let content = args.get("content").and_then(Value::as_str).unwrap_or("");
-            let outcome = tools.send_message(
+            let outcome = tools.send_message_with_presentation(
                 &target,
                 content,
                 None,
                 None,
                 None,
+                args.get("presentation"),
             )?;
             match outcome {
                 SendOutcome::WorkerAccepted { .. } => Ok(ToolOk {
@@ -605,7 +655,7 @@ pub(crate) fn dispatch_tool(
                 SendOutcome::Direct(ok) => Ok(ok),
             }
         }
-        McpTool::ReportResult => tools.report_result(
+        McpTool::ReportResult => tools.report_result_with_presentation(
             args.get("envelope"),
             args.get("summary").and_then(Value::as_str),
             // cr verdict (T3-1 refined): an unknown status literal normalizes to
@@ -637,6 +687,7 @@ pub(crate) fn dispatch_tool(
                 .map(Vec::as_slice),
             args.get("task_id").and_then(Value::as_str),
             args.get("agent_id").and_then(Value::as_str),
+            args.get("presentation"),
         ),
         McpTool::UpdateState => {
             tools.update_state(args.get("note").and_then(Value::as_str).unwrap_or(""))
@@ -668,6 +719,15 @@ pub(crate) fn dispatch_tool(
                 .unwrap_or(""),
             args.get("label").and_then(Value::as_str),
         ),
+        McpTool::CloneAgent => tools.clone_agent(
+            args.get("source_agent_id")
+                .and_then(Value::as_str)
+                .unwrap_or(""),
+            args.get("as_agent_id")
+                .and_then(Value::as_str)
+                .unwrap_or(""),
+            args.get("label").and_then(Value::as_str),
+        ),
         McpTool::RequestHuman => tools.request_human(
             args.get("question").and_then(Value::as_str).unwrap_or(""),
             args.get("task_id").and_then(Value::as_str),
@@ -695,6 +755,7 @@ fn scope_ceiling_tool(tool: McpTool) -> bool {
             | McpTool::GetTeamStatus
             | McpTool::StopAgent
             | McpTool::ResetAgent
+            | McpTool::CloneAgent
             | McpTool::ForkAgent
     )
 }

package/crates/team-agent/src/messaging/delivery.rs

@@ -57,6 +57,7 @@ pub fn deliver_stored_message(
         requires_ack,
         None,
         super::InitialDisposition::Accepted,
+        None,
     )?
     else {
         unreachable!("internal delivery does not accept caller-supplied ids")
@@ -1828,6 +1829,7 @@ pub fn deliver_pending_messages(
     let store = MessageStore::open(workspace)?;
     let message_ids = {
         let conn = crate::db::schema::open_db(store.db_path())?;
+        // `stored_only` is intentionally absent: C6 chose durable presentation without C5.
         let mut stmt = conn.prepare(
             "select message_id from messages
              where status in (

package/crates/team-agent/src/messaging/helpers.rs

@@ -25,6 +25,7 @@ static RESULT_COUNTER: AtomicU64 = AtomicU64::new(0);
 pub(crate) fn status_wire(status: DeliveryStatus) -> &'static str {
     match status {
         DeliveryStatus::Delivered => "delivered",
+        DeliveryStatus::StoredOnly => "stored_only",
         DeliveryStatus::Failed => "failed",
         DeliveryStatus::Queued => "queued",
         DeliveryStatus::Blocked => "blocked",

package/crates/team-agent/src/messaging/leader_channel.rs

@@ -101,6 +101,7 @@ pub fn resolve_live_leader_channel(
         .current_path
         .as_deref()
         .is_some_and(|path| !path_is_in_workspace(path, workspace))
+        && !explicit_claim_authority_matches(workspace, receiver, &observed)
     {
         return LeaderChannelResolution::Unbound(LeaderChannelUnbound::PaneWorkspaceMismatch);
     }
@@ -113,14 +114,40 @@ pub fn resolve_live_leader_channel(
     }))
 }
 
-fn path_is_in_workspace(path: &Path, workspace: &Path) -> bool {
-    let path = path.canonicalize().unwrap_or_else(|_| path.to_path_buf());
-    let workspace = workspace
-        .canonicalize()
-        .unwrap_or_else(|_| workspace.to_path_buf());
+fn explicit_claim_authority_matches(
+    workspace: &Path,
+    receiver: &Value,
+    observed: &PaneInfo,
+) -> bool {
+    if string_field(receiver, "scope_authority") != Some("explicit_claim") {
+        return false;
+    }
+    let Some(authorized_workspace) = string_field(receiver, "authorized_team_workspace") else {
+        return false;
+    };
+    if canonical_path(Path::new(authorized_workspace)) != canonical_path(workspace) {
+        return false;
+    }
+    let Some(recorded_nonce) = string_field(receiver, "binding_nonce") else {
+        return false;
+    };
+    observed
+        .leader_env
+        .get(crate::tmux_backend::PANE_BINDING_NONCE_METADATA_KEY)
+        .filter(|nonce| !nonce.is_empty())
+        .is_some_and(|live_nonce| live_nonce == recorded_nonce)
+}
+
+pub(crate) fn path_is_in_workspace(path: &Path, workspace: &Path) -> bool {
+    let path = canonical_path(path);
+    let workspace = canonical_path(workspace);
     path == workspace || path.starts_with(workspace)
 }
 
+fn canonical_path(path: &Path) -> std::path::PathBuf {
+    path.canonicalize().unwrap_or_else(|_| path.to_path_buf())
+}
+
 fn receiver_transport_conflicts(receiver: &Value) -> bool {
     let mode = receiver.get("mode").and_then(Value::as_str);
     let transport_kind = receiver.get("transport_kind").and_then(Value::as_str);

package/crates/team-agent/src/messaging/leader_receiver.rs

@@ -14,6 +14,7 @@ use crate::transport::{
 
 use super::helpers::MessageStatusShadow;
 use super::persist::persist_internal_send;
+use super::presentation::PresentationDecision;
 use super::{
     DeliveryOutcome, DeliveryRefusal, DeliveryStage, DeliveryStatus, InitialDisposition,
     InternalSendKind, MessagingError, PersistResolution,
@@ -69,6 +70,35 @@ pub fn send_to_leader_receiver_with_message_id(
     result_id: Option<&str>,
     requested_message_id: Option<&str>,
     event_log: &EventLog,
+) -> Result<DeliveryOutcome, MessagingError> {
+    send_to_leader_receiver_with_presentation(
+        workspace,
+        state,
+        leader_id,
+        content,
+        task_id,
+        sender,
+        requires_ack,
+        result_id,
+        requested_message_id,
+        &PresentationDecision::default(),
+        event_log,
+    )
+}
+
+#[allow(clippy::too_many_arguments)]
+pub fn send_to_leader_receiver_with_presentation(
+    workspace: &Path,
+    state: &serde_json::Value,
+    leader_id: &str,
+    content: &str,
+    task_id: Option<&TaskId>,
+    sender: &str,
+    requires_ack: bool,
+    result_id: Option<&str>,
+    requested_message_id: Option<&str>,
+    presentation: &PresentationDecision,
+    event_log: &EventLog,
 ) -> Result<DeliveryOutcome, MessagingError> {
     let store = MessageStore::open(workspace)?;
     let owner_team = active_team_key(workspace, state);
@@ -90,6 +120,7 @@ pub fn send_to_leader_receiver_with_message_id(
         false,
         requested_message_id,
         InitialDisposition::Accepted,
+        Some(presentation),
     )? {
         PersistResolution::Duplicate(requested) => {
             return Ok(DeliveryOutcome {
@@ -258,8 +289,7 @@ pub fn deliver_to_leader_fallback_pane(
         attempt_payload.clone(),
     )?;
 
-    let Some(pane_id) = pane_id.filter(|pane| !pane.is_empty() && pane != "__team_agent_unbound__")
-    else {
+    let Some(receiver) = leader_receiver_record(state) else {
         let failed = serde_json::json!({
             "message_id": message_id,
             "result_id": result_id,
@@ -267,7 +297,7 @@ pub fn deliver_to_leader_fallback_pane(
             "pane_id": null,
             "primary_error": primary_error,
             "delivered_via": "fallback_pane",
-            "reason": "no_bound_pane",
+            "reason": "no_bound_receiver",
         });
         event_log.write("leader_receiver.fallback_pane_failed", failed)?;
         return Ok(DeliveryOutcome {
@@ -283,7 +313,6 @@ pub fn deliver_to_leader_fallback_pane(
     };
 
     let rendered = render_fallback_pane_message(content, message_id, primary_error);
-    let target = Target::Pane(PaneId::new(&pane_id));
     let payload = InjectPayload::Text(rendered);
     // 0.5.5 gate054 cross-team notify boundary: when the leader receiver
     // has a recorded `tmux_socket` (canonical), that socket is a HARD
@@ -301,25 +330,63 @@ pub fn deliver_to_leader_fallback_pane(
     // stays pending in the store, coordinator surfaces the pending
     // notification via status/monitor, and no cross-server injection is
     // attempted.
-    let inject_result: Result<InjectReport, TransportError> = match leader_tmux_socket(state) {
-        Some(socket) => {
-            let backend = crate::transport_factory::tmux_endpoint_transport(socket);
-            backend.inject(&target, &payload, Key::Enter, true)
-        }
-        None => {
-            // No socket recorded → legacy (pre-0.5) shape where the receiver
-            // was implicitly bound to the workspace-canonical tmux server.
-            // Keep the workspace→default chain here (single team assumption)
-            // but never mix it with a recorded-socket team.
-            let backend = crate::transport_factory::tmux_workspace_transport(workspace);
-            backend
-                .inject(&target, &payload, Key::Enter, true)
-                .or_else(|_| {
-                    let backend = crate::transport_factory::tmux_default_transport();
-                    backend.inject(&target, &payload, Key::Enter, true)
-                })
+    let socket_bound = leader_tmux_socket(state).is_some();
+    let transports: Vec<Box<dyn Transport>> = match leader_tmux_socket(state) {
+        Some(socket) => vec![Box::new(crate::transport_factory::tmux_endpoint_transport(
+            socket,
+        ))],
+        None => vec![
+            Box::new(crate::transport_factory::tmux_workspace_transport(
+                workspace,
+            )),
+            Box::new(crate::transport_factory::tmux_default_transport()),
+        ],
+    };
+    let mut resolved = None;
+    let mut refusal = "leader channel unavailable".to_string();
+    for transport in transports {
+        match super::leader_channel::resolve_live_leader_channel(
+            workspace,
+            receiver,
+            transport.as_ref(),
+        ) {
+            super::leader_channel::LeaderChannelResolution::Live(
+                super::leader_channel::LiveLeaderChannel::DirectTmux(channel),
+            ) => {
+                resolved = Some((transport, channel));
+                break;
+            }
+            other => refusal = format!("{other:?}"),
         }
+    }
+    let Some((transport, channel)) = resolved else {
+        event_log.write(
+            "leader_receiver.fallback_pane_failed",
+            serde_json::json!({
+                "message_id": message_id,
+                "result_id": result_id,
+                "owner_team_id": owner_team_id,
+                "pane_id": pane_id,
+                "primary_error": primary_error,
+                "delivered_via": "fallback_pane",
+                "socket_bound": socket_bound,
+                "reason": refusal,
+            }),
+        )?;
+        return Ok(DeliveryOutcome {
+            ok: false,
+            status: DeliveryStatus::Blocked,
+            message_status: MessageStatusShadow("blocked".to_string()),
+            message_id: Some(message_id.to_string()),
+            verification: Some("run team-agent claim-leader or team-agent takeover".to_string()),
+            stage: None,
+            reason: Some(DeliveryRefusal::LeaderNotAttached),
+            channel: Some("rebind_required".to_string()),
+        });
     };
+    let target = Target::Pane(PaneId::new(channel.pane_id));
+    let inject_result: Result<InjectReport, TransportError> =
+        transport.inject(&target, &payload, Key::Enter, true);
 
     match inject_result {
         Ok(report) => {
@@ -486,6 +553,17 @@ fn leader_record_field<'a>(state: &'a Value, field: &str) -> Option<&'a Value> {
         .or_else(|| receiver_or_owner_field(state, "team_owner", field))
 }
 
+fn leader_receiver_record(state: &Value) -> Option<&Value> {
+    state.get("leader_receiver").or_else(|| {
+        let active = state.get("active_team_key").and_then(Value::as_str)?;
+        state
+            .get("teams")
+            .and_then(Value::as_object)
+            .and_then(|teams| teams.get(active))
+            .and_then(|team| team.get("leader_receiver"))
+    })
+}
+
 fn owner_epoch_i64(state: &Value) -> Option<i64> {
     owner_epoch(state).and_then(|epoch| i64::try_from(epoch).ok())
 }
@@ -596,6 +674,7 @@ pub fn enqueue_leader_mailbox_until_attach(
         false,
         None,
         InitialDisposition::QueuedUntilLeaderAttach,
+        None,
     )?
     else {
         unreachable!("offline mailbox does not accept caller-supplied ids")

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

@@ -68,6 +68,7 @@ pub mod leader_channel;
 pub mod leader_receiver;
 pub mod peers;
 pub mod persist;
+pub mod presentation;
 pub mod results;
 pub mod scheduler;
 pub mod selftest;
@@ -94,7 +95,7 @@ pub use leader_channel::{
 pub use leader_receiver::{
     deliver_to_leader_fallback_pane, enqueue_leader_mailbox_until_attach,
     mirror_peer_message_to_leader, send_to_leader_receiver,
-    send_to_leader_receiver_with_message_id,
+    send_to_leader_receiver_with_message_id, send_to_leader_receiver_with_presentation,
 };
 pub use peers::allow_peer_talk;
 pub use persist::{

package/crates/team-agent/src/messaging/persist.rs

@@ -5,6 +5,7 @@ use std::path::{Path, PathBuf};
 use crate::db::message_store::{MessageRowStatus, MessageStore, PersistMessageInput};
 use crate::model::ids::{AgentId, TaskId, TeamKey};
 
+use super::presentation::PresentationDecision;
 use super::send::TrustedSender;
 use super::MessagingError;
 
@@ -64,6 +65,7 @@ impl DeliveryBlocker {
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum InitialDisposition {
     Accepted,
+    StoredOnly,
     QueuedUntilLeaderAttach,
     Blocked(DeliveryBlocker),
 }
@@ -72,6 +74,7 @@ impl InitialDisposition {
     fn row_status(self) -> MessageRowStatus {
         match self {
             Self::Accepted => MessageRowStatus::Accepted,
+            Self::StoredOnly => MessageRowStatus::StoredOnly,
             Self::QueuedUntilLeaderAttach => MessageRowStatus::QueuedUntilLeaderAttach,
             Self::Blocked(DeliveryBlocker::CoordinatorUnavailable) => {
                 MessageRowStatus::QueuedCoordinatorUnavailable
@@ -82,7 +85,7 @@ impl InitialDisposition {
     fn error(self) -> Option<&'static str> {
         match self {
             Self::Blocked(blocker) => Some(blocker.as_str()),
-            Self::Accepted | Self::QueuedUntilLeaderAttach => None,
+            Self::Accepted | Self::StoredOnly | Self::QueuedUntilLeaderAttach => None,
         }
     }
 }
@@ -100,6 +103,7 @@ pub struct ResolvedSendIntent {
     pub requires_ack: bool,
     pub requested_message_id: Option<String>,
     pub initial_disposition: InitialDisposition,
+    pub presentation: PresentationDecision,
 }
 
 impl ResolvedSendIntent {
@@ -128,6 +132,7 @@ impl ResolvedSendIntent {
             requires_ack,
             requested_message_id,
             initial_disposition: InitialDisposition::Accepted,
+            presentation: PresentationDecision::default(),
         }
     }
 }
@@ -158,6 +163,7 @@ pub fn persist_resolved_send(
         }
     }
     let status = intent.initial_disposition.row_status();
+    let presentation = serde_json::to_string(&intent.presentation)?;
     let message_id = store.persist_message(PersistMessageInput {
         message_id: intent.requested_message_id.as_deref(),
         owner_team_id: intent.owner_team_id.as_ref().map(TeamKey::as_str),
@@ -168,6 +174,7 @@ pub fn persist_resolved_send(
         requires_ack: intent.requires_ack,
         status,
         content: &intent.content,
+        presentation: &presentation,
         error: intent.initial_disposition.error(),
     })?;
     Ok(PersistResolution::Persisted(PersistedSend {
@@ -177,7 +184,9 @@ pub fn persist_resolved_send(
         row_status: status,
         blocker: match intent.initial_disposition {
             InitialDisposition::Blocked(blocker) => Some(blocker),
-            InitialDisposition::Accepted | InitialDisposition::QueuedUntilLeaderAttach => None,
+            InitialDisposition::Accepted
+            | InitialDisposition::StoredOnly
+            | InitialDisposition::QueuedUntilLeaderAttach => None,
         },
     }))
 }
@@ -195,6 +204,7 @@ pub(crate) fn persist_internal_send(
     requires_ack: bool,
     requested_message_id: Option<&str>,
     initial_disposition: InitialDisposition,
+    presentation: Option<&PresentationDecision>,
 ) -> Result<PersistResolution, MessagingError> {
     let mut intent = ResolvedSendIntent::accepted(
         SendOrigin::Internal(kind),
@@ -209,6 +219,9 @@ pub(crate) fn persist_internal_send(
         requested_message_id.map(ToOwned::to_owned),
     );
     intent.initial_disposition = initial_disposition;
+    if let Some(presentation) = presentation {
+        intent.presentation = presentation.clone();
+    }
     persist_resolved_send(&intent)
 }
 
@@ -266,6 +279,59 @@ mod tests {
         assert_eq!(error.as_deref(), Some("coordinator_unavailable"));
     }
 
+    #[test]
+    fn stored_only_persists_requested_presentation_without_delivery_eligibility() {
+        let workspace = workspace("stored-only");
+        let mut intent = ResolvedSendIntent::accepted(
+            SendOrigin::Mcp,
+            &workspace,
+            Some(TeamKey::new("team-a")),
+            LogicalRecipient::Leader,
+            TrustedSender::from_runtime_identity(AgentId::new("worker_a")),
+            None,
+            "stage evidence",
+            None,
+            false,
+            None,
+        );
+        intent.initial_disposition = InitialDisposition::StoredOnly;
+        intent.presentation = super::super::presentation::decide_presentation(
+            &super::super::presentation::PresentationRequest {
+                sink: super::super::presentation::PresentationSink::Casefile,
+                class: super::super::presentation::PresentationClass::StageResult,
+                case_id: Some("case-7".to_string()),
+            },
+            super::super::presentation::PresentationSource::Send,
+        );
+        let PersistResolution::Persisted(persisted) = persist_resolved_send(&intent).unwrap()
+        else {
+            panic!("fresh intent must persist")
+        };
+        assert_eq!(persisted.row_status, MessageRowStatus::StoredOnly);
+        let store = MessageStore::open(&workspace).unwrap();
+        let connection = crate::db::schema::open_db(store.db_path()).unwrap();
+        let (status, presentation): (String, String) = connection
+            .query_row(
+                "select status, presentation from messages where message_id = ?1",
+                [&persisted.message_id],
+                |row| Ok((row.get(0)?, row.get(1)?)),
+            )
+            .unwrap();
+        assert_eq!(status, "stored_only");
+        assert_eq!(
+            serde_json::from_str::<serde_json::Value>(&presentation).unwrap(),
+            serde_json::json!({
+                "sink": "casefile",
+                "class": "stage_result",
+                "case_id": "case-7",
+                "requested_sink": "casefile",
+                "effective_sink": "casefile",
+                "policy_reason": "requested_sink:casefile",
+                "policy_version": "team-presentation-v1"
+            })
+        );
+    }
+
     #[test]
     fn production_row_creation_is_owned_by_persisted_primitive() {
         for (name, source) in [