@team-agent/installer 0.4.7 → 0.4.9

package/Cargo.lock

@@ -566,7 +566,7 @@ dependencies = [
 
 [[package]]
 name = "team-agent"
-version = "0.4.7"
+version = "0.4.9"
 dependencies = [
  "anyhow",
  "chrono",

package/Cargo.toml

@@ -9,7 +9,7 @@ members = ["crates/team-agent"]
 
 [workspace.package]
 edition = "2021"
-version = "0.4.7"
+version = "0.4.9"
 license = "AGPL-3.0"
 rust-version = "1.95"
 

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

@@ -226,6 +226,33 @@ pub fn cmd_status_for_team(args: &StatusArgs, team: Option<&str>) -> Result<CmdR
             "status --summary does not accept an agent argument".to_string(),
         ));
     }
+    // S4QR-001 (0.4.8): selected-team ambiguity gate. status is a selected-team
+    // command: when the workspace has 2+ alive teams and no --team was passed,
+    // refuse instead of silently defaulting to the active team. Uses the same
+    // CommandScope::resolve helper as refuse_if_multi_alive_team_missing_scope
+    // (cli/emit.rs:964-979) so the destructive-command ambiguity gate and the
+    // selected-team-read ambiguity gate share a single source of truth.
+    if team.is_none() {
+        let scope = crate::state::paths::CommandScope::resolve(&args.workspace, None);
+        if scope.is_ambiguous() {
+            let candidates: Vec<String> = scope.candidates().to_vec();
+            let message = format!(
+                "status: workspace has multiple alive teams ({}); pass `--team <key>` to choose one",
+                candidates.join(", ")
+            );
+            if args.json {
+                let payload = serde_json::json!({
+                    "ok": false,
+                    "status": "refused",
+                    "reason": "team_target_ambiguous",
+                    "candidates": candidates,
+                    "message": message,
+                });
+                return Ok(CmdResult::from_json(payload, args.json));
+            }
+            return Err(CliError::Usage(message));
+        }
+    }
     let selected = match crate::state::selector::resolve_active_team(
         &args.workspace,
         team,

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

@@ -33,6 +33,39 @@ pub(crate) fn diagnose_runtime(state: &Value, backend: &dyn Transport) -> (Value
             "issue": "leader_not_attached",
             "action": "attach or claim a leader receiver before sending work",
         }));
+    } else {
+        // 0.4.x (CR R2 P0): leader provider health reconciliation. The
+        // leader_receiver may be marked `attached` (pane addressable) but the
+        // provider process has exited — pane fell back to shell with the exit
+        // marker. Distinguish `leader_provider_exited` from `attached` so
+        // status/diagnose surfaces the real state.
+        if let Some((pane_id, provider_label)) = leader_pane_and_provider(state) {
+            let health = crate::leader::leader_provider_health(
+                backend,
+                &crate::transport::PaneId::new(pane_id),
+                &provider_label,
+            );
+            match health {
+                crate::leader::LeaderProviderHealth::ProviderExited => {
+                    issues.push(json!("leader_provider_exited"));
+                    repairs.push(json!({
+                        "issue": "leader_provider_exited",
+                        "action": format!(
+                            "leader pane fell back to shell — provider `{provider_label}` exited; \
+                             relaunch with `team-agent {provider_label}` to restart the provider"
+                        ),
+                    }));
+                }
+                crate::leader::LeaderProviderHealth::Unreachable => {
+                    issues.push(json!("leader_provider_unreachable"));
+                    repairs.push(json!({
+                        "issue": "leader_provider_unreachable",
+                        "action": "leader pane is dead — relaunch the leader",
+                    }));
+                }
+                crate::leader::LeaderProviderHealth::Alive => {}
+            }
+        }
     }
 
     if let Some(session_name) = state.get("session_name").and_then(Value::as_str).filter(|s| !s.is_empty()) {
@@ -62,6 +95,25 @@ pub(crate) fn diagnose_runtime(state: &Value, backend: &dyn Transport) -> (Value
     (Value::Array(issues), Value::Array(repairs))
 }
 
+/// 0.4.x (CR R2): pull (pane_id, provider_label) from leader_receiver. Used
+/// by `leader_provider_health` reconcile in diagnose. Returns None when the
+/// leader is not attached or any field is missing.
+fn leader_pane_and_provider(state: &Value) -> Option<(String, String)> {
+    let receiver = state.get("leader_receiver")?;
+    let pane_id = receiver
+        .get("pane_id")
+        .and_then(Value::as_str)
+        .filter(|s| !s.is_empty())?
+        .to_string();
+    let provider = receiver
+        .get("provider")
+        .and_then(Value::as_str)
+        .filter(|s| !s.is_empty())
+        .unwrap_or("claude")
+        .to_string();
+    Some((pane_id, provider))
+}
+
 fn leader_receiver_attached(state: &Value) -> bool {
     let Some(receiver) = state.get("leader_receiver") else {
         return false;

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

@@ -1685,6 +1685,16 @@ pub mod lifecycle_port {
     /// matching cannot reap the leader — including when ANOTHER team's bare shutdown
     /// runs, where the leader is never in the invoker's ancestry.
     ///
+    /// 0.4.x (CR R3): leader shell wrapper interaction. The leader pane's
+    /// controlling process is the `sh -lc "...; exec ${SHELL} -l"` that
+    /// runs Claude as a CHILD. When Claude exits and the shell wrapper falls
+    /// back via `exec ${SHELL} -l`, the controlling PID is REPLACED in-place
+    /// by the interactive shell (same pane_pid). Because this function
+    /// protects by `pane.pane_pid` (Source 1 & 2), the fallback interactive
+    /// shell is already covered by the same protection set — shutdown will
+    /// NOT treat the fallback shell as a stray process. Verified by the
+    /// `leader_fallback_shell_protected_when_provider_exited` test.
+    ///
     /// Two leader-pane sources(N39 双来源,真机 grounded):
     /// 1. **Session prefix**: tmux session starts with `team-agent-leader-`(契约 grounded;
     ///    覆盖 LeaderStartMode::NewTmuxSession / AttachExisting).

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

@@ -448,16 +448,57 @@ fn ensure_managed_leader_pane(
                 });
             }
         }
+        // 0.4.x (CR C-1 + C-2): leader env_unset reuses the worker
+        // provider_env_unsets (single source of truth) + spawn through the
+        // leader shell wrapper so provider exit returns to a shell, not
+        // `[exited]`.
+        let env_unset = leader_env_unset_for_provider(plan.provider);
+        let provider_label = provider_command_name(plan.provider);
         transport
-            .spawn_into(session, window, &plan.provider_argv, workspace, &plan.leader_env)
+            .spawn_into_with_leader_shell_wrapper(
+                session,
+                window,
+                &plan.provider_argv,
+                workspace,
+                &plan.leader_env,
+                &env_unset,
+                provider_label,
+            )
             .map_err(|error| LeaderError::Start(error.to_string()))
     } else {
+        let env_unset = leader_env_unset_for_provider(plan.provider);
+        let provider_label = provider_command_name(plan.provider);
         transport
-            .spawn_first(session, window, &plan.provider_argv, workspace, &plan.leader_env)
+            .spawn_first_with_leader_shell_wrapper(
+                session,
+                window,
+                &plan.provider_argv,
+                workspace,
+                &plan.leader_env,
+                &env_unset,
+                provider_label,
+            )
             .map_err(|error| LeaderError::Start(error.to_string()))
     }
 }
 
+/// 0.4.x (CR C-1): leader provider env-unset list — SINGLE SOURCE OF TRUTH
+/// reused from worker spawn (`profile_launch::provider_env_unsets`).
+/// Audit grep guard: this function MUST be the only place in
+/// `crates/team-agent/src/leader/` that constructs a Claude/Codex/Copilot
+/// env-unset list. Any new code path that needs it must call this function
+/// or the underlying `provider_env_unsets`. Use `AuthMode::Subscription` —
+/// the leader is the user's interactive provider, never CompatibleApi/
+/// OfficialApi which are worker-only auth modes today.
+pub fn leader_env_unset_for_provider(provider: Provider) -> Vec<String> {
+    crate::lifecycle::profile_launch::provider_env_unsets(
+        provider,
+        crate::model::enums::AuthMode::Subscription,
+    )
+    .into_iter()
+    .collect()
+}
+
 fn ensure_managed_provider_live_after_attach(
     transport: &dyn Transport,
     spawned: &SpawnResult,
@@ -478,6 +519,117 @@ fn ensure_managed_provider_live_after_attach(
     )))
 }
 
+/// 0.4.x (CR C-3 P0): leader provider health reconciliation. The default
+/// `liveness()` check only proves the pane is ADDRESSABLE via tmux — it
+/// returns `Live` even when the provider has exited and the wrapper shell
+/// fell back to an interactive shell. This function distinguishes
+/// `provider_alive` from `provider_exited` by:
+///   1. Reading `pane_current_command` (tmux `#{pane_current_command}`).
+///   2. If the current command matches the expected provider binary (or
+///      one of its known aliases), report `Alive`.
+///   3. If the current command is an interactive shell AND the pane
+///      content contains the exit marker `[team-agent] <provider> exited`
+///      (emitted by `leader_shell_wrapper_command`), report
+///      `ProviderExited`.
+///   4. Otherwise (Unknown shell, no marker), report `Alive` as the
+///      conservative default — avoid false-positive exit alarms.
+///
+/// Note: when the leader shell wrapper is used (CR C-2), a provider exit
+/// leaves the pane as `<SHELL:-/bin/zsh>` with the exit marker in
+/// scrollback. Pre-wrapper code that hit `exec claude` would have left the
+/// pane as `[exited]` and `liveness()` would have returned `Dead`. The new
+/// failure mode requires this richer health check to surface
+/// `leader_provider_exited` as a distinct status.
+pub fn leader_provider_health(
+    transport: &dyn Transport,
+    pane_id: &PaneId,
+    expected_provider_label: &str,
+) -> LeaderProviderHealth {
+    use crate::transport::{CaptureRange, PaneField, Target};
+    let liveness = transport.liveness(pane_id).ok();
+    if matches!(liveness, Some(PaneLiveness::Dead)) {
+        return LeaderProviderHealth::Unreachable;
+    }
+    let target = Target::Pane(pane_id.clone());
+    let current_command = transport
+        .query(&target, PaneField::PaneCurrentCommand)
+        .ok()
+        .flatten()
+        .map(|s| s.trim().to_lowercase())
+        .unwrap_or_default();
+    if !current_command.is_empty()
+        && (current_command == expected_provider_label
+            || current_command.contains(expected_provider_label))
+    {
+        return LeaderProviderHealth::Alive;
+    }
+    // Current command is NOT the provider — likely fell back to shell.
+    let is_shell = is_interactive_shell_basename(&current_command);
+    if is_shell {
+        // CR R6: marker text from single-source `leader_provider_exit_marker`
+        // so the wrapper printf and the health-check substring cannot drift.
+        let exit_marker_substr =
+            crate::tmux_backend::leader_provider_exit_marker(expected_provider_label);
+        if let Ok(cap) = transport.capture(&target, CaptureRange::Tail(200)) {
+            if cap.text.contains(&exit_marker_substr) {
+                return LeaderProviderHealth::ProviderExited;
+            }
+        }
+    }
+    // Conservative default — pane addressable, but couldn't positively
+    // confirm provider exit. Treat as Alive.
+    LeaderProviderHealth::Alive
+}
+
+/// Health status reported by [`leader_provider_health`].
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum LeaderProviderHealth {
+    /// Provider process appears to be the pane's current command.
+    Alive,
+    /// Pane has fallen back to a shell with the exit marker present —
+    /// provider has exited.
+    ProviderExited,
+    /// Pane is dead / unaddressable.
+    Unreachable,
+}
+
+/// 0.4.x (CR R6 + R3): single-source interactive-shell detection.
+/// Used by:
+///   - `leader_provider_health` to decide "pane fell back to shell"
+///   - shutdown logic to recognise a leader pane in fallback-shell mode
+///     as still owned by the leader (not stray).
+///
+/// Matches by basename (case-insensitive) — `pane_current_command` returns
+/// the basename of the running binary. Conservative whitelist of POSIX +
+/// common interactive shells; missing entries here are false negatives
+/// (shell looks like provider absent → health says Alive) which is the
+/// safe default per the CR R6 conservative-Alive rule.
+pub fn is_interactive_shell_basename(name: &str) -> bool {
+    let trimmed = name.trim().to_ascii_lowercase();
+    let basename = std::path::Path::new(&trimmed)
+        .file_name()
+        .and_then(|s| s.to_str())
+        .unwrap_or(&trimmed);
+    matches!(
+        basename,
+        "zsh"
+            | "bash"
+            | "sh"
+            | "fish"
+            | "dash"
+            | "ksh"
+            | "tcsh"
+            | "csh"
+            | "ash"
+            | "mksh"
+            | "yash"
+            | "elvish"
+            | "nu"
+            | "nushell"
+            | "xonsh"
+    )
+}
+
 fn managed_spawned_pane_in_targets(transport: &dyn Transport, spawned: &SpawnResult) -> bool {
     transport
         .list_targets()
@@ -785,13 +937,35 @@ fn run_leader_argv(
             "leader launch argv is empty".to_string(),
         ));
     };
-    let mut child = Command::new(program)
+    // 0.4.x regression fix (env-leak scenario 1, in-tmux ExecProvider path):
+    // the managed-tmux path got the provider env-unset block via the shell
+    // wrapper (cb9c217), but the ExecProvider in-tmux path here is a direct
+    // Command::spawn().wait() — it inherits the parent process's full env
+    // including any CLAUDE_CODE_SESSION_ID / CLAUDE_CODE_CHILD_SESSION /
+    // CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS / CLAUDE_CODE_ENTRYPOINT /
+    // CLAUDE_CODE_EXECPATH / CLAUDECODE that the launching shell carries.
+    // Apply the SAME env-unset list used by the managed path (CR R6 single
+    // source: profile_launch::provider_env_unsets via
+    // leader_env_unset_for_provider).
+    let env_unset = leader_env_unset_for_provider(plan.provider);
+    let mut command = Command::new(program);
+    command
         .args(argv.iter().skip(1))
-        .envs(env)
         .stdin(Stdio::inherit())
         .stdout(Stdio::inherit())
-        .stderr(Stdio::inherit())
-        .spawn()?;
+        .stderr(Stdio::inherit());
+    // 0.4.x order fix: env_remove MUST run AFTER envs(). The `env` map comes
+    // from `merged_exec_env` which seeds with `std::env::vars().collect()` —
+    // calling `.envs(env)` re-adds every inherited CLAUDE_CODE_* the launching
+    // shell carried, overwriting any prior env_remove. By removing AFTER the
+    // bulk envs() call, the final Command env table has the leak keys
+    // structurally absent. Verified by the regression grep guard that the
+    // env_remove call appears AFTER `command.envs(env)`.
+    command.envs(env);
+    for key in &env_unset {
+        command.env_remove(key);
+    }
+    let mut child = command.spawn()?;
     if plan.mode == LeaderStartMode::ExecProvider {
         spawn_exec_provider_startup_prompt_handler(plan.provider, workspace.to_path_buf());
     }

package/crates/team-agent/src/lifecycle/profile_launch.rs

@@ -415,10 +415,41 @@ fn provider_env_exports(
     exports
 }
 
-fn provider_env_unsets(provider: Provider, auth_mode: AuthMode) -> BTreeSet<String> {
+/// 0.4.x (CR C-1): exposed as `pub(crate)` so the leader launcher
+/// (leader/start.rs) can reuse the SAME Claude/Codex/Copilot env-unset set
+/// used by worker spawn. Single source of truth — adding a new provider env
+/// var to clean up means changing this one function. Audit grep guard in
+/// `crates/team-agent/src/leader/start.rs::leader_env_unset_for_provider`
+/// confirms the leader path imports from here and does not maintain its own
+/// duplicate list.
+pub(crate) fn provider_env_unsets(provider: Provider, auth_mode: AuthMode) -> BTreeSet<String> {
     let mut unsets = BTreeSet::new();
     match provider {
         Provider::Claude | Provider::ClaudeCode => {
+            // E57 (0.3.27 P0): unset CLAUDE_CODE_SESSION_ID inherited from the
+            // leader's environment. When a Claude leader spawns a Claude worker,
+            // the worker inherits the leader's CLAUDE_CODE_SESSION_ID; Claude
+            // Code then routes the worker's transcript to the leader's session
+            // file (~/.claude/projects/<hash>/<leader-session-uuid>.jsonl),
+            // corrupting attribution and transcripts. Always unset so Claude
+            // Code generates a fresh session id per worker.
+            //
+            // S1-CAPTURE (0.4.x P0): also unset the rest of the Claude Code
+            // child/team env block. These variables make the spawned process
+            // believe it is a CHILD of the parent Claude (CLAUDE_CODE_CHILD_SESSION),
+            // a TEAM member (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS), or otherwise
+            // inherit the parent's invocation identity (ENTRYPOINT / EXECPATH /
+            // CLAUDECODE marker). Without unsetting these, a Claude worker
+            // spawned from a Claude leader is not an INDEPENDENT process — it
+            // joins the leader's session tree and its transcript / state /
+            // billing are attributed to the leader. CLAUDE_EFFORT is preserved
+            // (effort preference does not affect session attribution).
+            unsets.insert("CLAUDE_CODE_SESSION_ID".to_string());
+            unsets.insert("CLAUDE_CODE_CHILD_SESSION".to_string());
+            unsets.insert("CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS".to_string());
+            unsets.insert("CLAUDE_CODE_ENTRYPOINT".to_string());
+            unsets.insert("CLAUDE_CODE_EXECPATH".to_string());
+            unsets.insert("CLAUDECODE".to_string());
             if auth_mode == AuthMode::CompatibleApi {
                 unsets.insert("ANTHROPIC_API_KEY".to_string());
             }

package/crates/team-agent/src/lifecycle/restart/agent.rs

@@ -208,7 +208,7 @@ pub(crate) fn start_agent_at_paths(
         None,
         Some(resolved_team_key.as_str()),
     )?;
-    mark_agent_started(&mut state, agent_id, &spawn_window, &spawn, transport, &safety)?;
+    mark_agent_started(&mut state, agent_id, &spawn_window, &spawn, transport, &safety, start_mode)?;
     // **0.3.24 add-agent socket drift fix**: keep `state.tmux_endpoint` /
     // `state.tmux_socket` synchronized with the transport actually used for the
     // spawn. Without this, add-agent / fork-agent could spawn to a socket that
@@ -700,6 +700,7 @@ fn mark_agent_started(
     spawn: &SpawnedAgentWindow,
     transport: &dyn crate::transport::Transport,
     safety: &DangerousApproval,
+    start_mode: StartMode,
 ) -> Result<(), LifecycleError> {
     let Some(agent) = state
         .get_mut("agents")
@@ -712,6 +713,31 @@ fn mark_agent_started(
             agent_id
         )));
     };
+    // S1-CAPTURE-001 (0.4.8, CR M3 provider-agnostic): on a Fresh /
+    // FreshAfterMissingRollout start, the prior session's authoritative
+    // capture tuple MUST be cleared before persist_command_plan_state
+    // writes the new _pending_session_id. Otherwise old session_id +
+    // rollout_path coexist with new _pending_session_id and
+    // agent_session_complete returns true on the stale tuple — capture
+    // never re-binds to the new process, and any delivered token lands
+    // in the old transcript (the leader/unassigned mis-attribution seen
+    // in the gate evidence). This applies to all providers that resume:
+    // codex, claude, copilot. Reset_agent --discard-session already does
+    // this at common.rs:1144-1188; here we mirror it for start-agent /
+    // restart-agent fresh paths so the fresh-tuple invariant is global.
+    if matches!(start_mode, StartMode::Fresh | StartMode::FreshAfterMissingRollout) {
+        for field in [
+            "session_id",
+            "rollout_path",
+            "captured_at",
+            "captured_via",
+            "attribution_confidence",
+            "capture_state",
+            "attribution_ambiguous",
+        ] {
+            agent.remove(field);
+        }
+    }
     agent.insert("status".to_string(), serde_json::json!("running"));
     agent.insert("agent_id".to_string(), serde_json::json!(agent_id.as_str()));
     agent.insert("window".to_string(), serde_json::json!(window));

package/crates/team-agent/src/lifecycle/restart/common.rs

@@ -895,10 +895,25 @@ pub(crate) fn restart_required_missing_session_agent_ids(state: &serde_json::Val
                 .get("status")
                 .and_then(|value| value.as_str())
                 .is_some_and(|status| status == "running");
-            // E6 层2 (C2): required-missing 谓词只看 session_id 有无 + 是否在跑。
-            // pane 绑定 / first_send_at 在 gate 时刻天然可空(自启动 worker leader 从未发消息),
-            // 不能作判据 —— 否则真丢上下文的 null-session worker 被漏判,走静默 fresh。
-            missing_session_id && is_running
+            // E6 层2 (C2) + RESTART-RESUME-001 (0.4.8): required-missing
+            // predicate gates on session_id absence + running, but ALSO
+            // skips never-captured workers (no session_id AND no context
+            // signals at all). A never-captured worker has nothing to
+            // lose by fresh-start, so it must not block convergence and
+            // burn the capture deadline. This matches the selection-stage
+            // partial-resume semantic in
+            // selection.rs::classify_resume_decision (never_captured →
+            // FreshStart without --allow-fresh).
+            //
+            // The "has context to preserve" signal is the shared
+            // restart_agent_has_context_to_preserve helper: first_send_at
+            // (leader→worker delivery), last_result_at (MCP report path
+            // that may skip first_send_at), or task_prompt_delivered.
+            // Only context-bearing null-session workers continue to
+            // require convergence (so we never silently drop context).
+            missing_session_id
+                && is_running
+                && !super::selection::restart_agent_never_captured(agent, None)
         })
         .collect::<Vec<_>>();
     missing.sort();

package/crates/team-agent/src/lifecycle/restart/rebuild.rs

@@ -1361,11 +1361,29 @@ fn mark_agent_respawned(
     // Claude family clear path uniformly. The Copilot scanner
     // (provider/adapter.rs:1217-1228) already gates expected-id with a
     // sqlite point-check, so no truth is lost.
+    // S1-CAPTURE-001 (0.4.8): on Fresh / FreshAfterMissingRollout, clear the
+    // FULL prior-session authoritative capture tuple — not just session_id.
+    // Mirrors mark_agent_started (restart/agent.rs:728-740) so the rebuild path
+    // (multi-agent restart) and the single-agent start path enforce the same
+    // fresh-tuple invariant. Without this, save_restart_state's persist
+    // backfill can revive the stale rollout_path/captured_at/capture_state
+    // tuple from latest, defeating the fresh-tuple guarantee and leaving
+    // delivered tokens in the old transcript (leader/unassigned mis-attrib).
     if matches!(
         restart_mode,
         StartMode::Fresh | StartMode::FreshAfterMissingRollout
     ) {
-        agent.insert("session_id".to_string(), serde_json::Value::Null);
+        for field in [
+            "session_id",
+            "rollout_path",
+            "captured_at",
+            "captured_via",
+            "attribution_confidence",
+            "capture_state",
+            "attribution_ambiguous",
+        ] {
+            agent.remove(field);
+        }
     }
     crate::lifecycle::launch::persist_command_plan_state(agent, &spawn.plan, &spawn.profile_launch);
     persist_effective_approval_policy_for_restart(agent, safety);

package/crates/team-agent/src/lifecycle/restart/selection.rs

@@ -53,6 +53,57 @@ pub fn classify_first_send_at(raw: &serde_json::Value) -> FirstSendAtState {
     }
 }
 
+/// RESTART-RESUME-001 (0.4.8): true if the agent has any signal of prior
+/// interaction whose context would be lost by silent fresh-start. Checks
+/// `first_send_at` (leader→worker delivery), `last_result_at` (worker
+/// report_result), and `task_prompt_delivered` (MCP-only worker first task).
+/// Used by both the selection-stage never-captured decision and the
+/// pre-selection convergence missing-set predicate so the two layers share
+/// a single "needs context preservation" semantic.
+///
+/// CR M2 callers (must stay in sync):
+///   * lifecycle/restart/selection.rs (never_captured branch, classify_resume_decision)
+///   * lifecycle/restart/common.rs::restart_required_missing_session_agent_ids
+pub(crate) fn restart_agent_has_context_to_preserve(agent: &serde_json::Value) -> bool {
+    let has_valid_first_send_at = matches!(
+        classify_first_send_at(agent.get("first_send_at").unwrap_or(&serde_json::Value::Null)),
+        FirstSendAtState::Valid
+    );
+    if has_valid_first_send_at {
+        return true;
+    }
+    let has_last_result_at = agent
+        .get("last_result_at")
+        .and_then(serde_json::Value::as_str)
+        .is_some_and(|s| !s.is_empty());
+    if has_last_result_at {
+        return true;
+    }
+    agent
+        .get("task_prompt_delivered")
+        .and_then(serde_json::Value::as_bool)
+        .unwrap_or(false)
+}
+
+/// RESTART-RESUME-001: an agent is "never-captured" when its session_id is
+/// absent AND there is no context to preserve. Such an agent is safe to
+/// auto-fresh without `--allow-fresh` and should NOT be required to capture
+/// a transcript before restart proceeds.
+pub(crate) fn restart_agent_never_captured(
+    agent: &serde_json::Value,
+    session_id: Option<&str>,
+) -> bool {
+    let session_present = session_id.is_some_and(|s| !s.is_empty())
+        || agent
+            .get("session_id")
+            .and_then(serde_json::Value::as_str)
+            .is_some_and(|s| !s.is_empty());
+    if session_present {
+        return false;
+    }
+    !restart_agent_has_context_to_preserve(agent)
+}
+
 fn is_python_fromisoformat_like(raw: &str) -> bool {
     if raw.is_empty() {
         return false;
@@ -221,25 +272,25 @@ pub(crate) fn classify_restart_plan_with_resume_validation(
                 }
                 _ => (true, Vec::new()),
             };
-        // 0.4.7 partial-resume: when a worker has NEVER been captured (no
-        // session_id AND first_send_at is Absent), it is structurally
-        // non-resumable — there is no context to lose, so auto-fresh is
-        // safe even without --allow-fresh. This prevents a single
-        // never-captured role (e.g. MCP-only worker that the leader never
-        // messaged) from blocking restart of the other 6 roles that DO
-        // have complete resume tuples.
+        // 0.4.7 partial-resume + RESTART-RESUME-001 (0.4.8): when a worker
+        // has NEVER been captured (no session_id AND no context-bearing
+        // signal at all), it is structurally non-resumable — there is no
+        // context to lose, so auto-fresh is safe even without --allow-fresh.
         //
-        // The "never_captured" predicate is the conjunction:
-        //   * session_id is None (no provider session bound), AND
-        //   * first_send_at is Absent (leader has never injected a
-        //     message — so we never armed the capture path either).
+        // The "never_captured" predicate is now the shared
+        // restart_agent_never_captured(): session_id absent AND none of
+        // first_send_at(Valid) / last_result_at / task_prompt_delivered.
+        // This matches the pre-selection convergence semantic in
+        // common.rs::restart_required_missing_session_agent_ids so both
+        // layers refuse / auto-fresh in unison.
         //
-        // If session_id is None but first_send_at is Valid, that's the
-        // "received message but session not captured" bug state — keep
-        // the Refuse so we never silently drop context (architect rule:
-        // "绝不静默 fresh").
+        // If session_id is None but ANY context signal exists, that's the
+        // "received message/result but session not captured" bug state —
+        // keep the Refuse so we never silently drop context (architect
+        // rule: "绝不静默 fresh").
+        let _ = first_send_at_state; // retained for the Corrupt branch above
         let never_captured =
-            session_id.is_none() && matches!(first_send_at_state, FirstSendAtState::Absent);
+            restart_agent_never_captured(agent, session_id.as_ref().map(|s| s.as_str()));
         let decision = if session_id.is_some() && provider_can_resume && resume_backing_exists {
             ResumeDecision::Resume
         } else if session_id.is_some() && allow_fresh {

package/crates/team-agent/src/lifecycle/restart.rs

@@ -35,6 +35,7 @@ mod team_state;
 pub use agent::{reset_agent, reset_agent_with_transport, start_agent, start_agent_with_transport, stop_agent, stop_agent_with_transport};
 pub(crate) use agent::start_agent_at_paths;
 pub(crate) use common::refresh_missing_provider_sessions;
+pub(crate) use common::restart_required_missing_session_agent_ids;
 // 0.3.24 add-agent socket drift fix: state-aware tmux resolver shared with
 // `lifecycle::launch::add_agent` / `fork_agent` so all three (restart / add / fork)
 // route to the SAME tmux socket the live team uses.