@team-agent/installer 0.5.52 → 0.5.54

package/Cargo.lock

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

package/Cargo.toml

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

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

@@ -876,8 +876,10 @@ fn fake_shutdown(workspace: &Path) -> Result<Value, CliError> {
             }
         }
     }
-    crate::state::repository::StateRepository::new(workspace)
-        .save(crate::state::repository::StateWriteIntent::FakeE2eSeed, &state)?;
+    crate::state::repository::StateRepository::new(workspace).save(
+        crate::state::repository::StateWriteIntent::FakeE2eSeed,
+        &state,
+    )?;
     Ok(json!({
         "ok": true,
         "session_name": state.get("session_name").cloned().unwrap_or(Value::Null),
@@ -1375,6 +1377,20 @@ pub fn cmd_fork_agent(args: &ForkAgentArgs) -> Result<CmdResult, CliError> {
     ))
 }
 
+pub fn cmd_clone_agent(args: &CloneAgentArgs) -> Result<CmdResult, CliError> {
+    Ok(CmdResult::from_json(
+        lifecycle_port::clone_agent(
+            &args.workspace,
+            &args.source_agent,
+            &args.as_agent,
+            args.label.as_deref(),
+            !args.no_display,
+            args.team.as_deref(),
+        )?,
+        args.json,
+    ))
+}
+
 /// `cmd_remove_agent`(`commands.py:394`)。
 pub fn cmd_remove_agent(args: &RemoveAgentArgs) -> Result<CmdResult, CliError> {
     Ok(CmdResult::from_json(

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

@@ -115,6 +115,7 @@ fn dispatch(command: &str, args: &[String], cwd: &Path) -> Result<ExitCode, CliE
         "stop-agent" => cmd_stop_agent(&stop_agent_args(args, cwd)?).map(emit_result),
         "reset-agent" => cmd_reset_agent(&reset_agent_args(args, cwd)?).map(emit_result),
         "add-agent" => cmd_add_agent(&add_agent_args(args, cwd)?).map(emit_result),
+        "clone-agent" => cmd_clone_agent(&clone_agent_args(args, cwd)?).map(emit_result),
         "fork-agent" => cmd_fork_agent(&fork_agent_args(args, cwd)?).map(emit_result),
         "remove-agent" => cmd_remove_agent(&remove_agent_args(args, cwd)?).map(emit_result),
         "stuck-list" => cmd_stuck_list(&stuck_list_args(args, cwd)).map(emit_result),
@@ -316,8 +317,11 @@ fn command_help(command: Option<&str>) -> String {
         Some("compile") => "usage: team-agent compile --team TEAM [--out FILE] [--json]".to_string(),
         Some("send") => concat!(
             "usage: team-agent send TO MESSAGE... ",
-            "[--workspace WORKSPACE] [--team TEAM] [--json]\n\n",
-            "TO is a logical recipient; send returns after the message is persisted."
+            "[--workspace WORKSPACE] [--team TEAM] ",
+            "[--presentation-sink leader|casefile|silent --message-class CLASS [--case-id CASE]] ",
+            "[--json]\n\n",
+            "TO is a logical recipient; send returns after the message is persisted. ",
+            "Presentation changes live display only; every sink remains durable."
         )
         .to_string(),
         Some("allow-peer-talk") => "usage: team-agent allow-peer-talk A B [--workspace WORKSPACE] [--json]".to_string(),
@@ -330,6 +334,7 @@ fn command_help(command: Option<&str>) -> String {
         Some("start-agent") => "usage: team-agent start-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--force] [--allow-fresh] [--no-display] [--json]".to_string(),
         Some("stop-agent") => "usage: team-agent stop-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--json]".to_string(),
         Some("add-agent") => "usage: team-agent add-agent AGENT --role-file FILE [--force] [--workspace WORKSPACE] [--team TEAM] [--no-display] [--json]".to_string(),
+        Some("clone-agent") => "usage: team-agent clone-agent SOURCE_AGENT --as AGENT [--label LABEL] [--workspace WORKSPACE] [--team TEAM] [--no-display] [--json]".to_string(),
         Some("fork-agent") => "usage: team-agent fork-agent SOURCE_AGENT --as AGENT [--label LABEL] [--workspace WORKSPACE] [--team TEAM] [--no-display] [--json]".to_string(),
         Some("remove-agent") => "usage: team-agent remove-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--from-spec] [--confirm] [--force] [--json]".to_string(),
         // 0.5.26 (§7.6): removed from help; dispatch was never wired.
@@ -773,6 +778,9 @@ struct ParsedArgs {
     socket: Option<String>,
     thread_id: Option<String>,
     message_id: Option<String>,
+    presentation_sink: Option<String>,
+    message_class: Option<String>,
+    case_id: Option<String>,
     content: Option<String>,
     primary_error: Option<String>,
     agent_id: Option<String>,
@@ -863,6 +871,9 @@ fn parse_args(args: &[String]) -> ParsedArgs {
             "--socket" => parsed.socket = next_arg(args, &mut i),
             "--thread-id" => parsed.thread_id = next_arg(args, &mut i),
             "--message-id" => parsed.message_id = next_arg(args, &mut i),
+            "--presentation-sink" => parsed.presentation_sink = next_arg(args, &mut i),
+            "--message-class" => parsed.message_class = next_arg(args, &mut i),
+            "--case-id" => parsed.case_id = next_arg(args, &mut i),
             "--content" => parsed.content = next_arg(args, &mut i),
             "--primary-error" => parsed.primary_error = next_arg(args, &mut i),
             "--result-json" => parsed.result_json = next_arg(args, &mut i),
@@ -879,6 +890,17 @@ fn parse_args(args: &[String]) -> ParsedArgs {
             other if other.starts_with("--to-leader=") => {
                 parsed.to_leader = Some(other.trim_start_matches("--to-leader=").to_string());
             }
+            other if other.starts_with("--presentation-sink=") => {
+                parsed.presentation_sink =
+                    Some(other.trim_start_matches("--presentation-sink=").to_string());
+            }
+            other if other.starts_with("--message-class=") => {
+                parsed.message_class =
+                    Some(other.trim_start_matches("--message-class=").to_string());
+            }
+            other if other.starts_with("--case-id=") => {
+                parsed.case_id = Some(other.trim_start_matches("--case-id=").to_string());
+            }
             other if other.starts_with("--provider=") => {
                 parsed.provider = Some(other.trim_start_matches("--provider=").to_string());
             }
@@ -1027,6 +1049,23 @@ fn send_args(args: &[String], cwd: &Path) -> Result<SendArgs, CliError> {
     };
     let message_start = usize::from(target.is_some());
     let workspace = workspace(&parsed, cwd);
+    let presentation_value = if parsed.presentation_sink.is_some()
+        || parsed.message_class.is_some()
+        || parsed.case_id.is_some()
+    {
+        Some(serde_json::json!({
+            "sink": parsed.presentation_sink.clone(),
+            "class": parsed.message_class.clone(),
+            "case_id": parsed.case_id.clone(),
+        }))
+    } else {
+        None
+    };
+    let (presentation, presentation_error) =
+        crate::messaging::presentation::normalize_presentation(presentation_value.as_ref());
+    if let Some(error) = presentation_error {
+        return Err(CliError::Usage(format!("invalid presentation: {error}")));
+    }
     Ok(SendArgs {
         target,
         message: parsed
@@ -1047,6 +1086,7 @@ fn send_args(args: &[String], cwd: &Path) -> Result<SendArgs, CliError> {
         confirm_human: false,
         json: parsed.json,
         message_id: None,
+        presentation,
         pane: parsed.pane.clone(),
         to_name: parsed.to_name.clone(),
         to_leader: parsed.to_leader.clone(),
@@ -1109,11 +1149,22 @@ fn validate_send_flags(args: &[String]) -> Result<(), CliError> {
         "--timeout",
         "--confirm-human",
         "--message-id",
+        "--presentation-sink",
+        "--message-class",
+        "--case-id",
         "--json",
         "-h",
         "--help",
     ];
-    const ALLOWED_PREFIXES: &[&str] = &["--team=", "--pane=", "--to-name=", "--to-leader="];
+    const ALLOWED_PREFIXES: &[&str] = &[
+        "--team=",
+        "--pane=",
+        "--to-name=",
+        "--to-leader=",
+        "--presentation-sink=",
+        "--message-class=",
+        "--case-id=",
+    ];
     if let Some(flag) = args.iter().find(|arg| {
         arg.starts_with('-')
             && !ALLOWED.contains(&arg.as_str())
@@ -1366,6 +1417,21 @@ fn fork_agent_args(args: &[String], cwd: &Path) -> Result<ForkAgentArgs, CliErro
     })
 }
 
+fn clone_agent_args(args: &[String], cwd: &Path) -> Result<CloneAgentArgs, CliError> {
+    let parsed = parse_args(args);
+    Ok(CloneAgentArgs {
+        source_agent: required_pos(&parsed, 0, "source_agent")?,
+        workspace: workspace(&parsed, cwd),
+        team: parsed.team,
+        as_agent: parsed
+            .as_agent
+            .ok_or_else(|| CliError::Usage("missing --as".to_string()))?,
+        label: parsed.label,
+        no_display: parsed.no_display,
+        json: parsed.json,
+    })
+}
+
 fn remove_agent_args(args: &[String], cwd: &Path) -> Result<RemoveAgentArgs, CliError> {
     let parsed = parse_args(args);
     let workspace = workspace(&parsed, cwd);
@@ -1998,6 +2064,48 @@ mod tests {
         let _ = std::fs::remove_dir_all(&cwd);
     }
 
+    #[test]
+    fn send_presentation_flags_map_to_the_typed_request() {
+        let cwd = tmp_workspace();
+        let args = send_args(
+            &cli_argv(&[
+                "leader",
+                "progress",
+                "--presentation-sink",
+                "casefile",
+                "--message-class",
+                "progress",
+                "--case-id",
+                "case-9",
+            ]),
+            &cwd,
+        )
+        .unwrap();
+        assert_eq!(
+            args.presentation.sink,
+            crate::messaging::presentation::PresentationSink::Casefile
+        );
+        assert_eq!(
+            args.presentation.class,
+            crate::messaging::presentation::PresentationClass::Progress
+        );
+        assert_eq!(args.presentation.case_id.as_deref(), Some("case-9"));
+    }
+
+    #[test]
+    fn send_presentation_flags_fail_closed_when_incomplete() {
+        let cwd = tmp_workspace();
+        let error = send_args(
+            &cli_argv(&["leader", "progress", "--presentation-sink", "casefile"]),
+            &cwd,
+        )
+        .unwrap_err();
+        assert!(matches!(
+            error,
+            CliError::Usage(message) if message == "invalid presentation: missing_class"
+        ));
+    }
+
     #[test]
     fn send_to_name_positionals_are_message_not_target() {
         let cwd = tmp_workspace();

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

@@ -374,6 +374,19 @@ pub mod lifecycle_port {
                     );
                     let mut error = None;
                     for session in &sessions {
+                        let targets = vec![session.as_str().to_string()];
+                        if let Err(audit_error) = crate::kill_audit::pre_kill_audit(
+                            event_log,
+                            transport,
+                            "shutdown.shared_socket_individual",
+                            crate::kill_audit::KILL_SESSION,
+                            &targets,
+                        ) {
+                            error.get_or_insert_with(|| {
+                                format!("pre-kill audit failed: {audit_error}")
+                            });
+                            continue;
+                        }
                         if let Err(err) = transport.kill_session(session) {
                             if !tmux_absent_error(&err.to_string()) {
                                 error.get_or_insert_with(|| err.to_string());
@@ -386,7 +399,20 @@ pub mod lifecycle_port {
                         error,
                     };
                 }
-                let error = transport.kill_server().err().map(|error| error.to_string());
+                let targets = sessions
+                    .iter()
+                    .map(|session| session.as_str().to_string())
+                    .collect::<Vec<_>>();
+                let error = match crate::kill_audit::pre_kill_audit(
+                    event_log,
+                    transport,
+                    "shutdown.exclusive_socket",
+                    crate::kill_audit::KILL_SERVER,
+                    &targets,
+                ) {
+                    Ok(()) => transport.kill_server().err().map(|error| error.to_string()),
+                    Err(error) => Some(format!("pre-kill audit failed: {error}")),
+                };
                 ShutdownSocketCleanup {
                     killed_sessions: sessions,
                     spared_sessions: Vec::new(),
@@ -406,6 +432,18 @@ pub mod lifecycle_port {
                 }
                 let mut error = None;
                 for session in &to_kill {
+                    let targets = vec![session.as_str().to_string()];
+                    if let Err(audit_error) = crate::kill_audit::pre_kill_audit(
+                        event_log,
+                        transport,
+                        "shutdown.selected_session",
+                        crate::kill_audit::KILL_SESSION,
+                        &targets,
+                    ) {
+                        error
+                            .get_or_insert_with(|| format!("pre-kill audit failed: {audit_error}"));
+                        continue;
+                    }
                     if let Err(err) = transport.kill_session(session) {
                         if !tmux_absent_error(&err.to_string()) {
                             error.get_or_insert_with(|| err.to_string());
@@ -421,6 +459,59 @@ pub mod lifecycle_port {
         }
     }
 
+    #[cfg(test)]
+    mod kill_audit_tests {
+        use std::collections::BTreeMap;
+
+        use super::*;
+        use crate::transport::test_support::OfflineTransport;
+        use crate::transport::{PaneId, PaneInfo, SessionName};
+
+        #[test]
+        fn audit_write_failure_skips_destructive_kill() {
+            let root =
+                std::env::temp_dir().join(format!("ta-kill-audit-fail-{}", std::process::id()));
+            let blocked_parent = root.join("not-a-directory");
+            std::fs::create_dir_all(&root).unwrap();
+            std::fs::write(&blocked_parent, b"file").unwrap();
+            let event_log = crate::event_log::EventLog::at(blocked_parent.join("events.jsonl"));
+            let session = SessionName::new("team-audit-fail");
+            let transport = OfflineTransport::new()
+                .with_session_present(true)
+                .with_targets(vec![PaneInfo {
+                    pane_id: PaneId::new("%1"),
+                    session: session.clone(),
+                    window_index: Some(0),
+                    window_name: None,
+                    pane_index: Some(0),
+                    tty: None,
+                    current_command: None,
+                    current_path: None,
+                    active: true,
+                    pane_pid: None,
+                    leader_env: BTreeMap::new(),
+                }]);
+            let cleanup = bare_shutdown_socket_cleanup(
+                &transport,
+                &json!({
+                    "is_external_leader": true,
+                    "tmux_socket_source": "leader_env",
+                }),
+                &event_log,
+            );
+
+            assert!(
+                !transport.calls().contains(&"kill_session"),
+                "an unaudited destructive call must not execute"
+            );
+            assert!(cleanup
+                .error
+                .as_deref()
+                .is_some_and(|error| error.contains("pre-kill audit failed")));
+            let _ = std::fs::remove_dir_all(root);
+        }
+    }
+
     fn state_uses_external_leader(state: &Value) -> bool {
         crate::state::projection::state_is_external_leader(state)
     }
@@ -501,6 +592,17 @@ pub mod lifecycle_port {
                 );
                 continue;
             }
+            let targets = vec![session.as_str().to_string()];
+            if let Err(audit_error) = crate::kill_audit::pre_kill_audit(
+                event_log,
+                transport,
+                "shutdown.managed_worker_session",
+                crate::kill_audit::KILL_SESSION,
+                &targets,
+            ) {
+                error.get_or_insert_with(|| format!("pre-kill audit failed: {audit_error}"));
+                continue;
+            }
             if let Err(err) = transport.kill_session(session) {
                 if !tmux_absent_error(&err.to_string()) {
                     error.get_or_insert_with(|| err.to_string());
@@ -598,6 +700,16 @@ pub mod lifecycle_port {
             );
             return cleanup;
         }
+        if let Err(error) = crate::kill_audit::pre_kill_audit(
+            event_log,
+            transport,
+            "shutdown.empty_owned_endpoint",
+            crate::kill_audit::KILL_SERVER,
+            &[],
+        ) {
+            cleanup.error = Some(format!("pre-kill audit failed: {error}"));
+            return cleanup;
+        }
         if let Err(error) = transport.kill_server() {
             cleanup.error = Some(error.to_string());
         }
@@ -748,11 +860,24 @@ pub mod lifecycle_port {
                 let _ =
                     crate::lifecycle::display::close_team_display_backends(&run_workspace, session);
             } else {
-                push_unique_session(&mut killed_sessions, session.clone());
-                if let Err(error) = transport.kill_session(session) {
-                    if !tmux_absent_error(&error.to_string()) {
+                let targets = vec![session.as_str().to_string()];
+                let event_log = crate::event_log::EventLog::new(&run_workspace);
+                if let Err(error) = crate::kill_audit::pre_kill_audit(
+                    &event_log,
+                    transport,
+                    "shutdown.team_session",
+                    crate::kill_audit::KILL_SESSION,
+                    &targets,
+                ) {
+                    kill_error = Some(format!("pre-kill audit failed: {error}"));
+                } else if let Err(error) = transport.kill_session(session) {
+                    if tmux_absent_error(&error.to_string()) {
+                        push_unique_session(&mut killed_sessions, session.clone());
+                    } else {
                         kill_error = Some(error.to_string());
                     }
+                } else {
+                    push_unique_session(&mut killed_sessions, session.clone());
                 }
                 let _ =
                     crate::lifecycle::display::close_team_display_backends(&run_workspace, session);
@@ -2357,10 +2482,36 @@ pub mod lifecycle_port {
                 "ok": true,
                 "source_agent_id": report.source_agent_id.as_str(),
                 "new_agent_id": report.new_agent_id.as_str(),
+                "session_id": report.session_id.as_ref().map(|session| session.as_str()),
+                "new_session_id": report.session_id.as_ref().map(|session| session.as_str()),
             })),
             Err(e) => Ok(error_value(e)),
         }
     }
+    pub fn clone_agent(
+        workspace: &Path,
+        source_agent: &str,
+        as_agent_id: &str,
+        label: Option<&str>,
+        open_display: bool,
+        team: Option<&str>,
+    ) -> Result<Value, CliError> {
+        let source = crate::model::ids::AgentId::new(source_agent);
+        let dest = crate::model::ids::AgentId::new(as_agent_id);
+        match crate::lifecycle::clone_agent(workspace, &source, &dest, label, open_display, team) {
+            Ok(report) => Ok(json!({
+                "ok": true,
+                "status": "cloned",
+                "source_agent_id": report.source_agent_id.as_str(),
+                "new_agent_id": report.new_agent_id.as_str(),
+                "session_id": report.session_id.as_ref().map(|session| session.as_str()),
+                "new_session_id": report.session_id.as_ref().map(|session| session.as_str()),
+                "backing_path": report.backing_path.as_ref().map(|path| path.to_string_lossy()),
+                "backing_state": report.backing_state,
+            })),
+            Err(error) => Ok(error_value(error)),
+        }
+    }
     /// `runtime.remove_agent`(`cmd_remove_agent`;`--from-spec` 须配 `--confirm`)。
     pub fn remove_agent(
         workspace: &Path,

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

@@ -25,6 +25,7 @@ pub fn send_options_from_args(args: &SendArgs) -> SendOptions {
         watch_result: args.watch_result,
         team: args.team.as_ref().map(|s| TeamKey::new(s.clone())),
         message_id: args.message_id.clone(),
+        presentation: args.presentation.clone(),
         ..SendOptions::default()
     }
 }

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

@@ -285,6 +285,7 @@ pub(super) fn first_target(target: &MessageTarget) -> String {
 pub(super) fn delivery_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/cli/send.rs

@@ -169,6 +169,7 @@ pub fn send_to_canonical_leader_target(
         confirm_human: false,
         json: true,
         message_id: None,
+        presentation: crate::messaging::presentation::PresentationRequest::default(),
         pane: None,
         to_name: None,
         to_leader: None,

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

@@ -55,6 +55,7 @@ pub(crate) enum DispatchKind {
     StopAgent,
     ResetAgent,
     AddAgent,
+    CloneAgent,
     ForkAgent,
     RemoveAgent,
     StuckList,
@@ -98,6 +99,7 @@ pub(crate) const ALL_DISPATCH_KINDS: &[DispatchKind] = &[
     DispatchKind::StopAgent,
     DispatchKind::ResetAgent,
     DispatchKind::AddAgent,
+    DispatchKind::CloneAgent,
     DispatchKind::ForkAgent,
     DispatchKind::RemoveAgent,
     DispatchKind::StuckList,
@@ -153,7 +155,7 @@ pub(crate) struct CommandSpec {
 #[rustfmt::skip]
 pub(crate) const COMMAND_SPECS: &[CommandSpec] = &[
     CommandSpec { name: "quick-start", tier: CommandTier::Core, category: CommandCategory::Start, kind: CommandKind::Dispatch(DispatchKind::QuickStart), summary: "start or attach a team from TEAM.md", usage: "usage: team-agent quick-start [TEAMDIR] [--workspace WORKSPACE] [--name NAME] [--team-id TEAM|--team TEAM] [--yes] [--no-display] [--backend tmux|conpty] [--json]", default_help: true, command_help: true, suggestion_index: true, token_usage: TokenUsage::Conditional, alias_of: None, sunset: None, action: None, governance: None },
-    CommandSpec { name: "send", tier: CommandTier::Core, category: CommandCategory::Daily, kind: CommandKind::Dispatch(DispatchKind::Send), summary: "persist a message for a logical recipient", usage: "usage: team-agent send TO MESSAGE... [--workspace WORKSPACE] [--team TEAM] [--json]", 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 a 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]", 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: "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 },
@@ -183,6 +185,7 @@ pub(crate) const COMMAND_SPECS: &[CommandSpec] = &[
     CommandSpec { name: "attach-app-server-leader", tier: CommandTier::Guided, category: CommandCategory::GuidedRecovery, kind: CommandKind::Dispatch(DispatchKind::AttachAppServerLeader), summary: "bind an app-server leader receiver", usage: "usage: team-agent attach-app-server-leader [--workspace WORKSPACE] [--team TEAM] --socket unix:///path.sock --thread-id THREAD_ID [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
     CommandSpec { name: "remove-agent", tier: CommandTier::Secondary, category: CommandCategory::WorkerLifecycle, kind: CommandKind::Dispatch(DispatchKind::RemoveAgent), summary: "remove a worker", usage: "usage: team-agent remove-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--from-spec] [--confirm] [--force] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: None },
     CommandSpec { name: "fork-agent", tier: CommandTier::Secondary, category: CommandCategory::WorkerLifecycle, kind: CommandKind::Dispatch(DispatchKind::ForkAgent), summary: "fork a worker", usage: "usage: team-agent fork-agent SOURCE_AGENT --as AGENT [--label LABEL] [--workspace WORKSPACE] [--team TEAM] [--no-display] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::Conditional, alias_of: None, sunset: None, action: None, governance: None },
+    CommandSpec { name: "clone-agent", tier: CommandTier::Secondary, category: CommandCategory::WorkerLifecycle, kind: CommandKind::Dispatch(DispatchKind::CloneAgent), summary: "clone a worker role into a fresh session", usage: "usage: team-agent clone-agent SOURCE_AGENT --as AGENT [--label LABEL] [--workspace WORKSPACE] [--team TEAM] [--no-display] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::Conditional, alias_of: None, sunset: None, action: None, governance: None },
     CommandSpec { name: "allow-peer-talk", tier: CommandTier::Secondary, category: CommandCategory::Setup, kind: CommandKind::Dispatch(DispatchKind::AllowPeerTalk), summary: "allow direct worker peer talk", usage: "usage: team-agent allow-peer-talk A B [--workspace WORKSPACE] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: Some(GovernanceNote { decision: "secondary", reason: "capability/config surface" }) },
     CommandSpec { name: "approvals", tier: CommandTier::Secondary, category: CommandCategory::Observe, kind: CommandKind::Dispatch(DispatchKind::Approvals), summary: "inspect provider approval state", usage: "usage: team-agent approvals [AGENT] [--workspace WORKSPACE] [--team TEAM] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: Some(GovernanceNote { decision: "secondary", reason: "approval diagnostics" }) },
     CommandSpec { name: "profile", tier: CommandTier::Secondary, category: CommandCategory::Setup, kind: CommandKind::Dispatch(DispatchKind::Profile), summary: "manage provider profiles", usage: "usage: team-agent profile COMMAND NAME [--workspace WORKSPACE] [--team TEAM] [--auth-mode MODE] [--json]", default_help: false, command_help: true, suggestion_index: false, token_usage: TokenUsage::No, alias_of: None, sunset: None, action: None, governance: Some(GovernanceNote { decision: "secondary", reason: "provider/profile setup" }) },

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

@@ -361,7 +361,7 @@ fn cleanup_orphans_dryrun_golden_envelope() {
 // ── fix_schema: golden fix_schema_layout diagnosis envelope (schema_migration.py:258) ─────────────
 // {ok,status,db_path,schema_version,user_version,layout_diffs,recommended_action,would_backup_path,
 // fixed,rebuilds}. RUST mod.rs:538-540 stub {ok,fixed:false}. db_path/would_backup_path are
-// path/clock-derived; lock the deterministic fields. SCHEMA_VERSION==3. RED. ─────────────────────
+// path/clock-derived; lock the deterministic fields against the canonical SCHEMA_VERSION. ────────
 #[test]
 fn fix_schema_golden_layout_diagnosis_envelope() {
     let ws = tmp_workspace();
@@ -370,8 +370,8 @@ fn fix_schema_golden_layout_diagnosis_envelope() {
     assert_eq!(v["status"], json!("missing"), "missing db: status missing");
     assert_eq!(
         v["schema_version"],
-        json!(3),
-        "golden schema_version == SCHEMA_VERSION (3)"
+        json!(crate::db::schema::SCHEMA_VERSION),
+        "golden schema_version == canonical SCHEMA_VERSION"
     );
     assert_eq!(v["user_version"], json!(0), "missing db user_version == 0");
     assert_eq!(

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

@@ -49,6 +49,7 @@ fn cli_send_persists_real_message_row() {
         confirm_human: false,
         json: true,
         message_id: None,
+        presentation: crate::messaging::presentation::PresentationRequest::default(),
         pane: None,
         to_name: None,
         to_leader: None,

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

@@ -157,6 +157,7 @@ fn named_send_args(
         confirm_human: false,
         json: true,
         message_id: None,
+        presentation: crate::messaging::presentation::PresentationRequest::default(),
         pane: pane.map(str::to_string),
         to_name: to_name.map(str::to_string),
         to_leader: None,

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

@@ -468,6 +468,7 @@ fn send_args_fixture() -> SendArgs {
         confirm_human: false,
         json: false,
         message_id: None,
+        presentation: crate::messaging::presentation::PresentationRequest::default(),
         pane: None,
         to_name: None,
         to_leader: None,

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

@@ -323,6 +323,7 @@ pub struct SendArgs {
     /// When set, the store insert uses this id verbatim; a repeat with the same
     /// id returns a `Duplicate` refusal instead of creating a second row.
     pub message_id: Option<String>,
+    pub presentation: crate::messaging::presentation::PresentationRequest,
     /// Deprecated compatibility input. Public send refuses pane identity and
     /// requires a logical recipient so persistence always precedes delivery.
     pub pane: Option<String>,
@@ -514,6 +515,17 @@ pub struct ForkAgentArgs {
     pub json: bool,
 }
 
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct CloneAgentArgs {
+    pub source_agent: String,
+    pub workspace: PathBuf,
+    pub team: Option<String>,
+    pub as_agent: String,
+    pub label: Option<String>,
+    pub no_display: bool,
+    pub json: bool,
+}
+
 /// `remove-agent`(`parser.py:414`)。`--from-spec` 须配 `--confirm`。
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct RemoveAgentArgs {

package/crates/team-agent/src/coordinator/tests/basics.rs

@@ -365,16 +365,16 @@ fn orphan_self_terminate_false_when_workspace_exists() {
 
 #[test]
 fn metadata_ok_requires_all_three_to_match() {
-    // metadata.py:37-43 — pid ∧ protocol_version==2 ∧ schema_version==3.
-    let good = meta(555, PROTOCOL_VERSION, GOLDEN_SCHEMA_VERSION);
+    // metadata.py:37-43 — pid, protocol version, and current message schema all match.
+    let good = meta(555, PROTOCOL_VERSION, crate::db::schema::SCHEMA_VERSION);
     assert!(coordinator_metadata_ok(Some(&good), Pid(555)));
     // pid 不符 → false。
     assert!(!coordinator_metadata_ok(Some(&good), Pid(999)));
     // protocol_version 不符(bump 触发 restart_incompatible)→ false。
-    let bad_proto = meta(555, 1, GOLDEN_SCHEMA_VERSION);
+    let bad_proto = meta(555, 1, crate::db::schema::SCHEMA_VERSION);
     assert!(!coordinator_metadata_ok(Some(&bad_proto), Pid(555)));
     // schema_version 不符 → false(不可静默继续旧 schema 写库,card §89)。
-    let bad_schema = meta(555, PROTOCOL_VERSION, 2);
+    let bad_schema = meta(555, PROTOCOL_VERSION, crate::db::schema::SCHEMA_VERSION - 1);
     assert!(!coordinator_metadata_ok(Some(&bad_schema), Pid(555)));
 }