@team-agent/installer 0.4.0 → 0.4.2

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

@@ -93,9 +93,9 @@ fn dispatch(command: &str, args: &[String], cwd: &Path) -> Result<ExitCode, CliE
         }
         "status" => cmd_status_for_team(&status_args(args, cwd), parse_args(args).team.as_deref())
             .map(emit_result),
-        "stop" => cmd_shutdown(&shutdown_args(args, cwd)).map(emit_result),
-        "shutdown" => cmd_shutdown(&shutdown_args(args, cwd)).map(emit_result),
-        "restart" => cmd_restart(&restart_args(args, cwd)).map(emit_result),
+        "stop" => cmd_shutdown(&shutdown_args(args, cwd)?).map(emit_result),
+        "shutdown" => cmd_shutdown(&shutdown_args(args, cwd)?).map(emit_result),
+        "restart" => cmd_restart(&restart_args(args, cwd)?).map(emit_result),
         "restart-agent" => cmd_reset_agent(&reset_agent_args(args, cwd)?).map(emit_result),
         "start-agent" => cmd_start_agent(&start_agent_args(args, cwd)?).map(emit_result),
         "stop-agent" => cmd_stop_agent(&stop_agent_args(args, cwd)?).map(emit_result),
@@ -127,7 +127,7 @@ fn dispatch(command: &str, args: &[String], cwd: &Path) -> Result<ExitCode, CliE
         }
         "validate-result" => cmd_validate_result(&validate_result_args(args)?).map(emit_result),
         "collect" => {
-            cmd_collect_for_team(&collect_args(args, cwd), parse_args(args).team.as_deref())
+            cmd_collect_for_team(&collect_args(args, cwd)?, parse_args(args).team.as_deref())
                 .map(emit_result)
         }
         "settle" => cmd_settle(&settle_args(args, cwd)).map(emit_result),
@@ -215,7 +215,7 @@ fn command_help(command: Option<&str>) -> String {
             )
         }
         Some("init") => "usage: team-agent init [--workspace WORKSPACE] [--force] [--json]".to_string(),
-        Some("quick-start") => "usage: team-agent quick-start [TEAMDIR] [--workspace WORKSPACE] [--name NAME] [--team-id TEAM|--team TEAM] [--yes] [--fresh] [--no-display] [--json]\n\ndefaults: display_backend=adaptive; set display_backend: none in TEAM.md or pass --no-display to use one worker window per agent.".to_string(),
+        Some("quick-start") => "usage: team-agent quick-start [TEAMDIR] [--workspace WORKSPACE] [--name NAME] [--team-id TEAM|--team TEAM] [--yes] [--no-display] [--json]\n\ndefaults: display_backend=adaptive; set display_backend: none in TEAM.md or pass --no-display to use one worker window per agent.".to_string(),
         Some("start") => "usage: team-agent start [TEAMDIR] [--yes] [--fresh] [--json]".to_string(),
         Some("compile") => "usage: team-agent compile --team TEAM [--out FILE] [--json]".to_string(),
         Some("send") => "usage: team-agent send TARGET MESSAGE... [--workspace WORKSPACE] [--team TEAM] [--targets AGENTS] [--task TASK] [--sender SENDER] [--watch-result] [--requires-ack|--no-ack] [--no-wait] [--timeout SECONDS] [--confirm-human] [--message-id ID] [--json]".to_string(),
@@ -234,28 +234,28 @@ fn command_help(command: Option<&str>) -> 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(),
         Some("purge-agent") => "usage: team-agent purge-agent AGENT [--workspace WORKSPACE] [--team TEAM] [--force] [--json]".to_string(),
-        Some("stuck-list") => "usage: team-agent stuck-list [--workspace WORKSPACE] [--json]".to_string(),
+        Some("stuck-list") => "usage: team-agent stuck-list [--workspace WORKSPACE] [--team TEAM] [--json]".to_string(),
         Some("stuck-cancel") => "usage: team-agent stuck-cancel AGENT [--workspace WORKSPACE] [--alert-type stuck|idle_fallback|cross_worker_deadlock|all] [--json]".to_string(),
         Some("acknowledge-idle") => "usage: team-agent acknowledge-idle [--workspace WORKSPACE] [--team TEAM] [--json]".to_string(),
         Some("takeover") => "usage: team-agent takeover [--workspace WORKSPACE] [--team TEAM] [--confirm] [--json]".to_string(),
         Some("claim-leader") => "usage: team-agent claim-leader [--workspace WORKSPACE] [--team TEAM] [--confirm] [--json]".to_string(),
         Some("attach-leader") => "usage: team-agent attach-leader [--workspace WORKSPACE] [--team TEAM] [--pane PANE] [--provider PROVIDER] [--confirm] [--json]".to_string(),
         Some("identity") => "usage: team-agent identity [--workspace WORKSPACE] [--team TEAM] [--json]".to_string(),
-        Some("approvals") => "usage: team-agent approvals [AGENT] [--workspace WORKSPACE] [--json]".to_string(),
-        Some("inbox") => "usage: team-agent inbox AGENT [--workspace WORKSPACE] [--limit N] [--since CURSOR] [--json]".to_string(),
+        Some("approvals") => "usage: team-agent approvals [AGENT] [--workspace WORKSPACE] [--team TEAM] [--json]".to_string(),
+        Some("inbox") => "usage: team-agent inbox AGENT [--workspace WORKSPACE] [--team TEAM] [--limit N] [--since CURSOR] [--json]".to_string(),
         Some("doctor") => "usage: team-agent doctor [SPEC] [--workspace WORKSPACE] [--team TEAM] [--gate orphans|comms] [--comms] [--fix] [--fix-schema] [--cleanup-orphans] [--confirm] [--json]".to_string(),
         Some("watch") => "usage: team-agent watch [--workspace WORKSPACE] [--team TEAM]".to_string(),
-        Some("sessions") => "usage: team-agent sessions [--workspace WORKSPACE] [--json]".to_string(),
+        Some("sessions") => "usage: team-agent sessions [--workspace WORKSPACE] [--team TEAM] [--json]".to_string(),
         Some("validate") => "usage: team-agent validate [SPEC] [--json]".to_string(),
         Some("install-skill") => "usage: team-agent install-skill (--source DIR | --uninstall) [--target codex|claude|copilot|all] [--dest DIR] [--dry-run] [--json]".to_string(),
         Some("profile") => "usage: team-agent profile COMMAND NAME [--workspace WORKSPACE] [--team TEAM] [--auth-mode MODE] [--json]".to_string(),
         Some("validate-result") => "usage: team-agent validate-result [ENVELOPE] [--file FILE|--result JSON] [--json]".to_string(),
         Some("collect") => "usage: team-agent collect [--workspace WORKSPACE] [--team TEAM] [--result-file FILE] [--json]".to_string(),
         Some("settle") => "usage: team-agent settle [--workspace WORKSPACE] [--team TEAM] [--json]".to_string(),
-        Some("repair-state") => "usage: team-agent repair-state --task TASK --status STATUS [SUMMARY] [--assignee AGENT] [--workspace WORKSPACE] [--json]".to_string(),
-        Some("diagnose") => "usage: team-agent diagnose [--workspace WORKSPACE] [--json]".to_string(),
+        Some("repair-state") => "usage: team-agent repair-state --task TASK --status STATUS [SUMMARY] [--assignee AGENT] [--workspace WORKSPACE] [--team TEAM] [--json]".to_string(),
+        Some("diagnose") => "usage: team-agent diagnose [--workspace WORKSPACE] [--team TEAM] [--json]".to_string(),
         Some("preflight") => "usage: team-agent preflight [TEAMDIR] [--json]".to_string(),
-        Some("wait-ready") => "usage: team-agent wait-ready [--workspace WORKSPACE] [--timeout SECONDS] [--json]".to_string(),
+        Some("wait-ready") => "usage: team-agent wait-ready [--workspace WORKSPACE] [--team TEAM] [--timeout SECONDS] [--json]".to_string(),
         Some("e2e") => "usage: team-agent e2e [--workspace WORKSPACE] [--providers LIST] [--real] [--json]".to_string(),
         Some("peek") => "usage: team-agent peek AGENT [--workspace WORKSPACE] [--tail N|--head N] [--search TEXT] [--allow-raw-screen] [--json]".to_string(),
         Some("coordinator") => "usage: team-agent coordinator [--workspace WORKSPACE] [--once] [--tick-interval SECONDS]".to_string(),
@@ -613,7 +613,6 @@ struct ParsedArgs {
     team: Option<String>,
     json: bool,
     yes: bool,
-    fresh: bool,
     name: Option<String>,
     team_id: Option<String>,
     targets: Option<String>,
@@ -685,7 +684,6 @@ fn parse_args(args: &[String]) -> ParsedArgs {
             "--team" => parsed.team = next_arg(args, &mut i),
             "--json" => parsed.json = true,
             "--yes" => parsed.yes = true,
-            "--fresh" => parsed.fresh = true,
             "--name" => parsed.name = next_arg(args, &mut i),
             "--team-id" => parsed.team_id = next_arg(args, &mut i),
             "--targets" | "--target" | "--to" => parsed.targets = next_arg(args, &mut i),
@@ -804,6 +802,13 @@ fn required_pos(parsed: &ParsedArgs, index: usize, name: &str) -> Result<String,
 }
 
 fn quick_start_args(args: &[String], cwd: &Path) -> Result<QuickStartArgs, CliError> {
+    if has_arg(args, "--fresh") {
+        return Err(CliError::Usage(
+            "quick-start no longer accepts --fresh. Reset semantics moved to \
+             `team-agent restart --allow-fresh`, which requires explicit user \
+             confirmation.".to_string(),
+        ));
+    }
     let parsed = parse_args(args);
     let workspace = workspace(&parsed, cwd);
     let agents_dir = parsed
@@ -822,7 +827,6 @@ fn quick_start_args(args: &[String], cwd: &Path) -> Result<QuickStartArgs, CliEr
         name: parsed.name,
         team_id: parsed.team_id.or(parsed.team),
         yes: parsed.yes,
-        fresh: parsed.fresh,
         no_display: parsed.no_display,
         json: parsed.json,
     })
@@ -949,6 +953,31 @@ fn fallback_report_result_args(
     })
 }
 
+/// Stage 4 of identity-boundary unified plan (architect direction
+/// 2026-06-24, .team/artifacts/identity-boundary-unified-plan.md §2 Stage
+/// 4): destructive command ambiguity gate. When the workspace has 2+
+/// alive teams and the caller did not pass `--team`, refuse with a
+/// usage error listing the candidates so the operator picks explicitly.
+/// Single-team workspaces (the 0.4.x baseline) are unaffected — the
+/// `CommandScope::resolve` helper returns `Resolved` and this function
+/// is a no-op.
+fn refuse_if_multi_alive_team_missing_scope(
+    command: &str,
+    workspace: &Path,
+    requested_team: Option<&str>,
+) -> Result<(), CliError> {
+    let scope = crate::state::paths::CommandScope::resolve(workspace, requested_team);
+    if scope.is_ambiguous() {
+        let candidates = scope.candidates().join(", ");
+        return Err(CliError::Usage(format!(
+            "{command}: workspace has multiple alive teams ({candidates}); \
+             pass `--team <key>` to choose one (refusing to default to any \
+             single team — Stage 4 identity-boundary contract)"
+        )));
+    }
+    Ok(())
+}
+
 fn allow_peer_talk_args(args: &[String], cwd: &Path) -> Result<AllowPeerTalkArgs, CliError> {
     let parsed = parse_args(args);
     Ok(AllowPeerTalkArgs {
@@ -956,6 +985,7 @@ fn allow_peer_talk_args(args: &[String], cwd: &Path) -> Result<AllowPeerTalkArgs
         b: required_pos(&parsed, 1, "b")?,
         workspace: workspace(&parsed, cwd),
         json: parsed.json,
+        team: parsed.team,
     })
 }
 
@@ -967,6 +997,7 @@ fn status_args(args: &[String], cwd: &Path) -> StatusArgs {
         detail: parsed.detail,
         summary: parsed.summary,
         json: parsed.json,
+        team: parsed.team,
     }
 }
 
@@ -984,6 +1015,7 @@ fn approvals_args(args: &[String], cwd: &Path) -> ApprovalsArgs {
         agent: parsed.positionals.first().cloned(),
         workspace: workspace(&parsed, cwd),
         json: parsed.json,
+        team: parsed.team,
     }
 }
 
@@ -995,6 +1027,7 @@ fn inbox_args(args: &[String], cwd: &Path) -> Result<InboxArgs, CliError> {
         limit: parsed.limit.unwrap_or(20),
         since: parsed.since,
         json: parsed.json,
+        team: parsed.team,
     })
 }
 
@@ -1042,29 +1075,33 @@ fn identity_args(args: &[String], cwd: &Path) -> IdentityArgs {
     }
 }
 
-fn shutdown_args(args: &[String], cwd: &Path) -> ShutdownArgs {
+fn shutdown_args(args: &[String], cwd: &Path) -> Result<ShutdownArgs, CliError> {
     let parsed = parse_args(args);
-    ShutdownArgs {
-        workspace: workspace(&parsed, cwd),
+    let workspace = workspace(&parsed, cwd);
+    refuse_if_multi_alive_team_missing_scope("shutdown", &workspace, parsed.team.as_deref())?;
+    Ok(ShutdownArgs {
+        workspace,
         team: parsed.team,
         keep_logs: parsed.keep_logs,
         json: parsed.json,
-    }
+    })
 }
 
-fn restart_args(args: &[String], cwd: &Path) -> RestartArgs {
+fn restart_args(args: &[String], cwd: &Path) -> Result<RestartArgs, CliError> {
     let parsed = parse_args(args);
-    RestartArgs {
-        workspace: parsed
-            .positionals
-            .first()
-            .map(PathBuf::from)
-            .unwrap_or_else(|| workspace(&parsed, cwd)),
+    let workspace = parsed
+        .positionals
+        .first()
+        .map(PathBuf::from)
+        .unwrap_or_else(|| workspace(&parsed, cwd));
+    refuse_if_multi_alive_team_missing_scope("restart", &workspace, parsed.team.as_deref())?;
+    Ok(RestartArgs {
+        workspace,
         team: parsed.team,
         allow_fresh: parsed.allow_fresh,
         session_converge_deadline_ms: parsed.session_converge_deadline_ms,
         json: parsed.json,
-    }
+    })
 }
 
 fn start_agent_args(args: &[String], cwd: &Path) -> Result<StartAgentArgs, CliError> {
@@ -1092,9 +1129,11 @@ fn stop_agent_args(args: &[String], cwd: &Path) -> Result<StopAgentArgs, CliErro
 
 fn reset_agent_args(args: &[String], cwd: &Path) -> Result<ResetAgentArgs, CliError> {
     let parsed = parse_args(args);
+    let workspace = workspace(&parsed, cwd);
+    refuse_if_multi_alive_team_missing_scope("reset-agent", &workspace, parsed.team.as_deref())?;
     Ok(ResetAgentArgs {
         agent: required_pos(&parsed, 0, "agent")?,
-        workspace: workspace(&parsed, cwd),
+        workspace,
         team: parsed.team,
         discard_session: parsed.discard_session,
         no_display: parsed.no_display,
@@ -1133,9 +1172,11 @@ fn fork_agent_args(args: &[String], cwd: &Path) -> Result<ForkAgentArgs, CliErro
 
 fn remove_agent_args(args: &[String], cwd: &Path) -> Result<RemoveAgentArgs, CliError> {
     let parsed = parse_args(args);
+    let workspace = workspace(&parsed, cwd);
+    refuse_if_multi_alive_team_missing_scope("remove-agent", &workspace, parsed.team.as_deref())?;
     Ok(RemoveAgentArgs {
         agent: required_pos(&parsed, 0, "agent")?,
-        workspace: workspace(&parsed, cwd),
+        workspace,
         team: parsed.team,
         from_spec: parsed.from_spec,
         confirm: parsed.confirm,
@@ -1149,16 +1190,24 @@ fn stuck_list_args(args: &[String], cwd: &Path) -> StuckListArgs {
     StuckListArgs {
         workspace: workspace(&parsed, cwd),
         json: parsed.json,
+        team: parsed.team,
     }
 }
 
 fn stuck_cancel_args(args: &[String], cwd: &Path) -> Result<StuckCancelArgs, CliError> {
     let parsed = parse_args(args);
+    let workspace = workspace(&parsed, cwd);
+    refuse_if_multi_alive_team_missing_scope(
+        "stuck-cancel",
+        &workspace,
+        parsed.team.as_deref(),
+    )?;
     Ok(StuckCancelArgs {
         agent: required_pos(&parsed, 0, "agent")?,
-        workspace: workspace(&parsed, cwd),
+        workspace,
         alert_type: alert_type(parsed.alert_type.as_deref())?,
         json: parsed.json,
+        team: parsed.team,
     })
 }
 
@@ -1212,6 +1261,7 @@ fn sessions_args(args: &[String], cwd: &Path) -> SessionsArgs {
     SessionsArgs {
         workspace: workspace(&parsed, cwd),
         json: parsed.json,
+        team: parsed.team,
     }
 }
 
@@ -1250,13 +1300,16 @@ fn validate_result_args(args: &[String]) -> Result<ValidateResultArgs, CliError>
     })
 }
 
-fn collect_args(args: &[String], cwd: &Path) -> CollectArgs {
+fn collect_args(args: &[String], cwd: &Path) -> Result<CollectArgs, CliError> {
     let parsed = parse_args(args);
-    CollectArgs {
-        workspace: workspace(&parsed, cwd),
+    let workspace = workspace(&parsed, cwd);
+    refuse_if_multi_alive_team_missing_scope("collect", &workspace, parsed.team.as_deref())?;
+    Ok(CollectArgs {
+        workspace,
         result_file: parsed.result_file,
         json: parsed.json,
-    }
+        team: parsed.team,
+    })
 }
 
 fn settle_args(args: &[String], cwd: &Path) -> SettleArgs {
@@ -1270,8 +1323,10 @@ fn settle_args(args: &[String], cwd: &Path) -> SettleArgs {
 
 fn repair_state_args(args: &[String], cwd: &Path) -> Result<RepairStateArgs, CliError> {
     let parsed = parse_args(args);
+    let workspace = workspace(&parsed, cwd);
+    refuse_if_multi_alive_team_missing_scope("repair-state", &workspace, parsed.team.as_deref())?;
     Ok(RepairStateArgs {
-        workspace: workspace(&parsed, cwd),
+        workspace,
         task_id: parsed
             .task
             .ok_or_else(|| CliError::Usage("missing --task".to_string()))?,
@@ -1281,6 +1336,7 @@ fn repair_state_args(args: &[String], cwd: &Path) -> Result<RepairStateArgs, Cli
             .ok_or_else(|| CliError::Usage("missing --status".to_string()))?,
         summary: option_value(args, "--summary").or_else(|| parsed.positionals.first().cloned()),
         json: parsed.json,
+        team: parsed.team,
     })
 }
 
@@ -1308,6 +1364,7 @@ fn diagnose_args(args: &[String], cwd: &Path) -> DiagnoseArgs {
     DiagnoseArgs {
         workspace: workspace(&parsed, cwd),
         json: parsed.json,
+        team: parsed.team,
     }
 }
 
@@ -1331,6 +1388,7 @@ fn wait_ready_args(args: &[String], cwd: &Path) -> WaitReadyArgs {
         workspace: workspace(&parsed, cwd),
         timeout: parsed.timeout.unwrap_or(60.0),
         json: parsed.json,
+        team: parsed.team,
     }
 }
 
@@ -1529,7 +1587,7 @@ mod tests {
         for (command, flags) in [
             (
                 "quick-start",
-                &["--workspace", "--team-id", "--yes", "--fresh", "--json"][..],
+                &["--workspace", "--team-id", "--yes", "--json"][..],
             ),
             (
                 "send",
@@ -1638,11 +1696,19 @@ mod tests {
                 "collect",
                 &["--workspace", "--team", "--result-file", "--json"][..],
             ),
+            ("stuck-list", &["--workspace", "--team", "--json"][..]),
+            ("approvals", &["--workspace", "--team", "--json"][..]),
+            (
+                "inbox",
+                &["--workspace", "--team", "--limit", "--since", "--json"][..],
+            ),
+            ("sessions", &["--workspace", "--team", "--json"][..]),
             (
                 "repair-state",
-                &["--task", "--status", "--assignee", "--workspace", "--json"][..],
+                &["--task", "--status", "--assignee", "--workspace", "--team", "--json"][..],
             ),
-            ("wait-ready", &["--workspace", "--timeout", "--json"][..]),
+            ("diagnose", &["--workspace", "--team", "--json"][..]),
+            ("wait-ready", &["--workspace", "--team", "--timeout", "--json"][..]),
             (
                 "peek",
                 &[
@@ -1667,6 +1733,10 @@ mod tests {
                 );
             }
         }
+        assert!(
+            !command_help(Some("quick-start")).contains("--fresh"),
+            "quick-start help must not advertise removed reset semantics"
+        );
     }
 
     #[test]
@@ -1724,4 +1794,197 @@ mod tests {
         assert_eq!(levenshtein("status", "status"), 0);
         assert_eq!(levenshtein("statu", "status"), 1);
     }
+
+    // ─── Stage 4: multi-team ambiguity refusal for destructive commands ───
+
+    fn seed_two_alive_teams_in(ws: &std::path::Path) {
+        crate::state::persist::save_runtime_state(
+            ws,
+            &serde_json::json!({
+                "teams": {
+                    "alpha": {"status": "alive"},
+                    "beta": {"status": "alive"},
+                },
+            }),
+        )
+        .unwrap();
+    }
+
+    #[test]
+    fn refuse_helper_passes_on_single_alive_team() {
+        let ws = tmp_workspace();
+        crate::state::persist::save_runtime_state(
+            &ws,
+            &serde_json::json!({"teams": {"alpha": {"status": "alive"}}}),
+        )
+        .unwrap();
+        assert!(
+            refuse_if_multi_alive_team_missing_scope("stuck-cancel", &ws, None).is_ok(),
+            "single-alive-team workspace must not trigger the ambiguity refusal"
+        );
+    }
+
+    #[test]
+    fn refuse_helper_passes_when_explicit_team_provided_even_in_multi_alive() {
+        let ws = tmp_workspace();
+        seed_two_alive_teams_in(&ws);
+        assert!(
+            refuse_if_multi_alive_team_missing_scope("collect", &ws, Some("alpha")).is_ok(),
+            "explicit --team alpha must bypass the ambiguity gate"
+        );
+    }
+
+    #[test]
+    fn refuse_helper_refuses_when_multi_alive_team_and_no_explicit_team() {
+        let ws = tmp_workspace();
+        seed_two_alive_teams_in(&ws);
+        let err = refuse_if_multi_alive_team_missing_scope("repair-state", &ws, None)
+            .expect_err("multi-alive-team must refuse without --team");
+        let message = err.to_string();
+        assert!(
+            message.contains("multiple alive teams"),
+            "refusal must name the ambiguity; got: {message}"
+        );
+        assert!(
+            message.contains("alpha") && message.contains("beta"),
+            "refusal must list candidate teams; got: {message}"
+        );
+        assert!(
+            message.contains("repair-state"),
+            "refusal must name the command for diagnostic clarity; got: {message}"
+        );
+    }
+
+    #[test]
+    fn stuck_cancel_args_builder_refuses_on_multi_alive_team() {
+        let ws = tmp_workspace();
+        seed_two_alive_teams_in(&ws);
+        let argv = cli_argv(&[
+            "worker_a",
+            "--workspace",
+            &ws.to_string_lossy(),
+        ]);
+        let err = stuck_cancel_args(&argv, &ws).expect_err("must refuse");
+        assert!(
+            err.to_string().contains("multiple alive teams"),
+            "stuck-cancel args builder must surface the refusal; got: {err}"
+        );
+    }
+
+    #[test]
+    fn collect_args_builder_refuses_on_multi_alive_team() {
+        let ws = tmp_workspace();
+        seed_two_alive_teams_in(&ws);
+        let argv = cli_argv(&["--workspace", &ws.to_string_lossy()]);
+        let err = collect_args(&argv, &ws).expect_err("must refuse");
+        assert!(
+            err.to_string().contains("multiple alive teams"),
+            "collect args builder must surface the refusal; got: {err}"
+        );
+    }
+
+    #[test]
+    fn repair_state_args_builder_refuses_on_multi_alive_team_before_task_validation() {
+        let ws = tmp_workspace();
+        seed_two_alive_teams_in(&ws);
+        // The ambiguity gate must fire BEFORE `--task` / `--status` validation
+        // so the operator sees the multi-team confusion before any other
+        // usage error.
+        let argv = cli_argv(&["--workspace", &ws.to_string_lossy()]);
+        let err = repair_state_args(&argv, &ws).expect_err("must refuse");
+        let message = err.to_string();
+        assert!(
+            message.contains("multiple alive teams"),
+            "ambiguity gate must precede --task/--status validation; got: {message}"
+        );
+    }
+
+    #[test]
+    fn shutdown_args_builder_refuses_on_multi_alive_team() {
+        let ws = tmp_workspace();
+        seed_two_alive_teams_in(&ws);
+        let argv = cli_argv(&["--workspace", &ws.to_string_lossy()]);
+        let err = shutdown_args(&argv, &ws).expect_err("must refuse");
+        assert!(
+            err.to_string().contains("multiple alive teams"),
+            "shutdown args builder must surface the refusal; got: {err}"
+        );
+    }
+
+    #[test]
+    fn restart_args_builder_refuses_on_multi_alive_team() {
+        let ws = tmp_workspace();
+        seed_two_alive_teams_in(&ws);
+        let argv = cli_argv(&[&ws.to_string_lossy()]);
+        let err = restart_args(&argv, &ws).expect_err("must refuse");
+        assert!(
+            err.to_string().contains("multiple alive teams"),
+            "restart args builder must surface the refusal; got: {err}"
+        );
+    }
+
+    #[test]
+    fn reset_agent_args_builder_refuses_on_multi_alive_team_before_agent_validation() {
+        let ws = tmp_workspace();
+        seed_two_alive_teams_in(&ws);
+        let argv = cli_argv(&["--workspace", &ws.to_string_lossy()]);
+        let err = reset_agent_args(&argv, &ws).expect_err("must refuse");
+        assert!(
+            err.to_string().contains("multiple alive teams"),
+            "reset-agent args builder must surface the refusal; got: {err}"
+        );
+    }
+
+    #[test]
+    fn remove_agent_args_builder_refuses_on_multi_alive_team_before_agent_validation() {
+        let ws = tmp_workspace();
+        seed_two_alive_teams_in(&ws);
+        let argv = cli_argv(&["--workspace", &ws.to_string_lossy()]);
+        let err = remove_agent_args(&argv, &ws).expect_err("must refuse");
+        assert!(
+            err.to_string().contains("multiple alive teams"),
+            "remove-agent args builder must surface the refusal; got: {err}"
+        );
+    }
+
+    // ──────────── Stage QR: quick-start/restart separation ────────────
+    // Design doc: .team/artifacts/quickstart-restart-separation-design.md
+
+    #[test]
+    fn quick_start_refuses_fresh_flag_with_restart_guidance() {
+        // QR contract: `--fresh` is gone from quick-start. The flag is
+        // not advertised or carried in QuickStartArgs, but scripts that
+        // still pass it get a clear redirect to restart --allow-fresh.
+        let ws = tmp_workspace();
+        let argv = cli_argv(&[
+            "--workspace",
+            &ws.to_string_lossy(),
+            "--fresh",
+        ]);
+        let err = quick_start_args(&argv, &ws).expect_err("must refuse --fresh");
+        let message = err.to_string();
+        assert!(
+            message.contains("no longer accepts --fresh"),
+            "QR: refusal must say --fresh is gone; got: {message}"
+        );
+        assert!(
+            message.contains("restart --allow-fresh"),
+            "QR: refusal must redirect to `restart --allow-fresh`; got: {message}"
+        );
+    }
+
+    #[test]
+    fn quick_start_without_fresh_flag_still_builds_args() {
+        // Without --fresh, args build normally (the initial-creation path).
+        let ws = tmp_workspace();
+        let argv = cli_argv(&[
+            "--workspace",
+            &ws.to_string_lossy(),
+        ]);
+        let args = quick_start_args(&argv, &ws).expect("must build");
+        assert_eq!(args.workspace, ws);
+        // No `fresh` field anymore — the struct must compile and round-trip
+        // without it.
+        let _ = args.no_display;
+    }
 }

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

@@ -117,7 +117,6 @@ pub mod lifecycle_port {
         name: Option<&str>,
         team_id: Option<&str>,
         yes: bool,
-        fresh: bool,
         open_display: bool,
     ) -> Result<Value, CliError> {
         match crate::lifecycle::quick_start_in_workspace_with_display(
@@ -125,7 +124,6 @@ pub mod lifecycle_port {
             agents_dir,
             name,
             yes,
-            fresh,
             team_id,
             open_display,
         ) {
@@ -3745,18 +3743,13 @@ pub mod leader_port {
     }
 
     fn team_owner_value(state: &Value, team_id: &TeamKey) -> Option<Value> {
-        state
-            .get("teams")
-            .and_then(|teams| teams.get(team_id.as_str()))
-            .and_then(|team| team.get("team_owner"))
-            .cloned()
-            .or_else(|| {
-                if crate::state::projection::team_state_key(state) == team_id.as_str() {
-                    state.get("team_owner").cloned()
-                } else {
-                    None
-                }
-            })
+        // Stage 2 (identity-boundary unified plan, architect direction
+        // 2026-06-23): route through the ownership repository so all owner
+        // reads see the same precedence (teams.<key> > top-level when
+        // team_state_key matches). The repository preserves the pre-Stage-2
+        // semantics of this helper and adds an `OwnershipSource` tag that
+        // diagnose/status surfaces can consume in later stages.
+        crate::state::ownership::read_owner_value(state, team_id.as_str()).cloned()
     }
 
     fn family_a_owner_value(

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

@@ -265,6 +265,16 @@ use rusqlite::params;
     pub fn approvals(workspace: &Path, agent: Option<&str>, as_json: bool) -> Result<Value, CliError> {
         let _ = as_json;
         let state = read_runtime_state(workspace);
+        approvals_scoped(workspace, &state, agent, as_json)
+    }
+
+    pub fn approvals_scoped(
+        workspace: &Path,
+        state: &Value,
+        agent: Option<&str>,
+        as_json: bool,
+    ) -> Result<Value, CliError> {
+        let _ = as_json;
         let session = state.get("session_name").and_then(Value::as_str).filter(|s| !s.is_empty());
         let mut approvals = Vec::new();
         if let (Some(session), Some(agents)) = (session, state.get("agents").and_then(Value::as_object)) {
@@ -333,12 +343,13 @@ use rusqlite::params;
         limit: usize,
         since: Option<&str>,
         as_json: bool,
+        owner_team_id: Option<&str>,
     ) -> Result<Value, CliError> {
         let _ = as_json;
         let store = crate::message_store::MessageStore::open(workspace)
             .map_err(|e| CliError::Runtime(e.to_string()))?;
         let mut messages = store
-            .inbox(agent, limit, None)
+            .inbox(agent, limit, owner_team_id)
             .map_err(|e| CliError::Runtime(e.to_string()))?;
         if let Some(cutoff) = since.and_then(parse_rfc3339) {
             messages.retain(|message| {

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

@@ -455,11 +455,13 @@ latest result: none";
         let payload = err.to_payload(Path::new("/tmp/cli-error-123.log"), "quick-start");
         assert_eq!(payload.reason.as_deref(), Some("tmux_session_name_conflict"));
         assert_eq!(payload.session_name.as_deref(), Some("my-team"));
-        // E8 (N38): quick-start 撞已有 runtime 引导到 restart(resume),明确 --fresh 会丢上下文。
+        // E8 (N38): quick-start 撞已有 runtime 引导到 restart(resume);
+        // context reset is only through restart --allow-fresh with explicit consent.
         assert_eq!(
             payload.action,
             "tmux session `my-team` already exists. It may be your own existing team. \
-To resume it use `team-agent restart` (NOT --fresh, which discards context). \
+To resume it use `team-agent restart`. \
+If recovery is impossible, use `team-agent restart --allow-fresh` only after explicit context-loss consent. \
 Only if you want a separate team, change `name:` in TEAM.md and run quick-start again. \
 Never terminate existing tmux sessions from quick-start."
         );
@@ -635,6 +637,7 @@ Truncated: more fallback entries available; run team-agent inbox leader";
             detail: false,
             summary: true,
             json: true,
+            team: None,
         };
         let err = cmd_status(&args).unwrap_err();
         assert!(
@@ -652,6 +655,7 @@ Truncated: more fallback entries available; run team-agent inbox leader";
             detail: false,
             summary: true,
             json: false,
+            team: None,
         };
         let err = cmd_status(&args).unwrap_err();
         assert!(