@team-agent/installer 0.5.114 → 0.5.116

package/crates/team-agent/src/contract_runtime/workspace.rs

@@ -0,0 +1,228 @@
+//! Stable per-seat primary cwd outside project Git ancestry. Provider-specific
+//! project access remains explicit; private MCP files never overwrite a shared
+//! project or another seat's config, and old cwd incarnations are not migrated.
+use std::io::{Read, Write};
+use std::os::unix::fs::{DirBuilderExt, MetadataExt, OpenOptionsExt};
+use std::path::Path;
+
+use serde::{Deserialize, Serialize};
+use team_agent_contract::contract::{session::CwdIdentity, types::SeatId};
+use team_agent_contract::host::process::resolve_cwd;
+
+use super::backend::{root_for, BackendError, Binding};
+
+#[derive(Serialize, Deserialize)]
+#[serde(deny_unknown_fields)]
+struct CwdRecord {
+    version: u32,
+    seat: SeatId,
+    cwd: CwdIdentity,
+}
+
+/// Requires an already owned framework root. Existing unrecorded directories
+/// are refused, not adopted. A replaced inode or any symlink is a hard error.
+pub(super) fn prepare(binding: &Binding, seat: &SeatId) -> Result<CwdIdentity, BackendError> {
+    let root = root_for(&binding.workspace.path, &binding.scope);
+    validate_directory(&root)?;
+    let parent = binding.transport_root.join("workspaces");
+    let path = parent.join(seat.as_str());
+    let record_path = root.join(format!("cwd-{}.json", seat.as_str()));
+    match std::fs::symlink_metadata(&record_path) {
+        Ok(metadata) => {
+            if !metadata.is_file() || metadata.file_type().is_symlink() {
+                return Err(BackendError::Metadata);
+            }
+            let mut file = std::fs::OpenOptions::new().read(true)
+                .custom_flags(libc::O_NOFOLLOW | libc::O_CLOEXEC).open(&record_path)?;
+            let opened = file.metadata()?;
+            if opened.dev() != metadata.dev() || opened.ino() != metadata.ino() {
+                return Err(BackendError::Metadata);
+            }
+            let mut bytes = Vec::new();
+            Read::by_ref(&mut file).take(65537).read_to_end(&mut bytes)?;
+            if bytes.len() > 65536 {
+                return Err(BackendError::Metadata);
+            }
+            let record: CwdRecord = serde_json::from_slice(&bytes).map_err(|_| BackendError::Metadata)?;
+            // Old sessions stay pinned to their original project-local cwd.
+            // Only new allocations move outside Git; never relocate a resume.
+            let expected = match record.version {
+                1 => root.join("workspaces").join(seat.as_str()),
+                2 => {
+                    validate_directory(&binding.transport_root)?;
+                    reject_git_ancestors(&binding.transport_root)?;
+                    path.clone()
+                }
+                _ => return Err(BackendError::Metadata),
+            };
+            if record.seat != *seat || record.cwd.path != expected {
+                return Err(BackendError::Metadata);
+            }
+            validate_directory(expected.parent().ok_or(BackendError::Metadata)?)?;
+            validate_directory(&expected)?;
+            if resolve_cwd(&expected)? != record.cwd {
+                return Err(BackendError::Metadata);
+            }
+            return Ok(record.cwd);
+        }
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
+        Err(error) => return Err(error.into()),
+    }
+    validate_directory(&binding.transport_root)?;
+    reject_git_ancestors(&binding.transport_root)?;
+    match std::fs::symlink_metadata(&parent) {
+        Ok(_) => validate_directory(&parent)?,
+        Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
+            std::fs::DirBuilder::new().mode(0o700).create(&parent)?;
+        }
+        Err(error) => return Err(error.into()),
+    }
+    // Exclusive create is deliberate: missing record + existing path is not
+    // enough evidence that this framework owns the previous incarnation.
+    std::fs::DirBuilder::new().mode(0o700).create(&path)?;
+    validate_directory(&path)?;
+    let cwd = resolve_cwd(&path)?;
+    let record = CwdRecord { version: 2, seat: seat.clone(), cwd: cwd.clone() };
+    let bytes = serde_json::to_vec(&record).map_err(|_| BackendError::Metadata)?;
+    let mut file = std::fs::OpenOptions::new().write(true).create_new(true)
+        .mode(0o600).custom_flags(libc::O_NOFOLLOW | libc::O_CLOEXEC).open(record_path)?;
+    file.write_all(&bytes)?;
+    file.sync_all()?;
+    Ok(cwd)
+}
+
+// Metadata only: handle both ordinary .git directories and worktree .git files;
+// never read Git config, credentials, execute hooks, or assume /tmp is non-Git.
+fn reject_git_ancestors(path: &Path) -> Result<(), BackendError> {
+    for ancestor in path.ancestors() {
+        match std::fs::symlink_metadata(ancestor.join(".git")) {
+            Ok(_) => return Err(BackendError::Metadata),
+            Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
+            Err(error) => return Err(error.into()),
+        }
+    }
+    Ok(())
+}
+
+fn validate_directory(path: &Path) -> Result<(), BackendError> {
+    let metadata = std::fs::symlink_metadata(path)?;
+    if !metadata.is_dir() || metadata.file_type().is_symlink() || path.canonicalize()? != path
+        || metadata.uid() != unsafe { libc::geteuid() } || metadata.mode() & 0o077 != 0
+    {
+        return Err(BackendError::Metadata);
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::path::PathBuf;
+    use std::sync::atomic::{AtomicU64, Ordering};
+    use team_agent_contract::contract::types::{Digest, ScopeId};
+
+    static SEQUENCE: AtomicU64 = AtomicU64::new(0);
+    struct Fixture { path: PathBuf, binding: Binding }
+    impl Fixture {
+        fn new() -> Self {
+            let path = std::env::temp_dir().canonicalize().unwrap().join(format!(
+                "contract-cwd-{}-{}-{}", std::process::id(),
+                std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos(),
+                SEQUENCE.fetch_add(1, Ordering::Relaxed),
+            ));
+            std::fs::DirBuilder::new().mode(0o700).create(&path).unwrap();
+            let binding = Binding {
+                version: 1, workspace: resolve_cwd(&path).unwrap(), team: "test".into(),
+                scope: ScopeId::new("cwd-test").unwrap(), endpoint: "framework:cwd-test".into(),
+                candidate: "/controlled/candidate".into(), candidate_sha256: Digest([1; 32]),
+                tmux: "/controlled/tmux".into(), transport_root: path.with_extension("transport"),
+            };
+            std::fs::DirBuilder::new().mode(0o700).create(&binding.transport_root).unwrap();
+            let root = root_for(&path, &binding.scope);
+            std::fs::create_dir_all(root.parent().unwrap()).unwrap();
+            std::fs::DirBuilder::new().mode(0o700).create(&root).unwrap();
+            Self { path, binding }
+        }
+    }
+    impl Drop for Fixture {
+        fn drop(&mut self) {
+            let _ = std::fs::remove_dir_all(&self.path);
+            let _ = std::fs::remove_dir_all(&self.binding.transport_root);
+        }
+    }
+
+    #[test]
+    fn stable_cwd_is_reused_and_distinct_seats_do_not_share_a_primary() {
+        let f = Fixture::new();
+        let a = SeatId::new("a").unwrap();
+        let b = SeatId::new("b").unwrap();
+        let first = prepare(&f.binding, &a).unwrap();
+        assert_eq!(prepare(&f.binding, &a).unwrap(), first);
+        let second = prepare(&f.binding, &b).unwrap();
+        assert_ne!(first.path, second.path);
+        assert_ne!(first.identity, second.identity);
+        assert!(!f.path.join(".cursor").exists());
+    }
+
+    #[test]
+    fn replaced_inode_or_symlink_is_not_adopted_on_resume() {
+        let f = Fixture::new();
+        let seat = SeatId::new("worker").unwrap();
+        let original = prepare(&f.binding, &seat).unwrap();
+        let retained = original.path.with_extension("old");
+        std::fs::rename(&original.path, &retained).unwrap();
+        std::fs::DirBuilder::new().mode(0o700).create(&original.path).unwrap();
+        assert!(prepare(&f.binding, &seat).is_err());
+        std::fs::remove_dir(&original.path).unwrap();
+        std::os::unix::fs::symlink(&retained, &original.path).unwrap();
+        assert!(prepare(&f.binding, &seat).is_err());
+    }
+
+    #[test]
+    fn unrecorded_existing_directory_is_not_claimed() {
+        let f = Fixture::new();
+        let root = root_for(&f.path, &f.binding.scope);
+        let parent = f.binding.transport_root.join("workspaces");
+        std::fs::DirBuilder::new().mode(0o700).create(&parent).unwrap();
+        std::fs::DirBuilder::new().mode(0o700).create(parent.join("worker")).unwrap();
+        assert!(prepare(&f.binding, &SeatId::new("worker").unwrap()).is_err());
+        assert!(!root.join("cwd-worker.json").exists());
+    }
+
+    #[test]
+    fn new_primary_is_outside_project_git_ancestors() {
+        let f = Fixture::new();
+        std::fs::create_dir(f.path.join(".git")).unwrap();
+        let cwd = prepare(&f.binding, &SeatId::new("worker").unwrap()).unwrap();
+        assert!(cwd.path.starts_with(&f.binding.transport_root));
+        assert!(!cwd.path.starts_with(&f.path));
+        reject_git_ancestors(&cwd.path).unwrap();
+    }
+
+    #[test]
+    fn existing_version_one_cwd_is_not_migrated() {
+        let f = Fixture::new();
+        let seat = SeatId::new("worker").unwrap();
+        let root = root_for(&f.path, &f.binding.scope);
+        let parent = root.join("workspaces");
+        let path = parent.join(seat.as_str());
+        std::fs::DirBuilder::new().mode(0o700).create(&parent).unwrap();
+        std::fs::DirBuilder::new().mode(0o700).create(&path).unwrap();
+        let cwd = resolve_cwd(&path).unwrap();
+        let record = CwdRecord { version: 1, seat: seat.clone(), cwd: cwd.clone() };
+        std::fs::write(root.join("cwd-worker.json"), serde_json::to_vec(&record).unwrap()).unwrap();
+        assert_eq!(prepare(&f.binding, &seat).unwrap(), cwd);
+        assert!(!f.binding.transport_root.join("workspaces").exists());
+    }
+
+    #[test]
+    fn git_directory_or_worktree_file_on_transport_ancestor_is_refused() {
+        let f = Fixture::new();
+        let marker = f.binding.transport_root.join(".git");
+        std::fs::write(&marker, b"gitdir: controlled-marker").unwrap();
+        assert!(prepare(&f.binding, &SeatId::new("worker").unwrap()).is_err());
+        std::fs::remove_file(&marker).unwrap();
+        std::fs::create_dir(&marker).unwrap();
+        assert!(prepare(&f.binding, &SeatId::new("worker").unwrap()).is_err());
+    }
+}

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

@@ -2140,10 +2140,8 @@ fn persist_exec_provider_leader_binding(
             "active_team_key".to_string(),
             serde_json::json!(identity.team_id.as_str()),
         );
-        obj.insert(
-            "session_name".to_string(),
-            serde_json::json!(target.session.as_str()),
-        );
+        // The ambient session identifies the leader receiver, not workers.
+        // Leave any existing worker session untouched, including unknown state.
         obj.insert("tmux_endpoint".to_string(), serde_json::json!(socket));
         obj.insert("tmux_socket".to_string(), serde_json::json!(socket));
         obj.insert(
@@ -3062,7 +3060,8 @@ mod tests {
         execute_leader_plan_after_ambient_authority, format_launcher_failure,
         handle_exec_provider_startup_prompts, is_interactive_shell_basename,
         lock_down_window_rename, managed_client_argv, managed_leader_window_from_occupied,
-        persist_managed_leader_binding, push_bounded_stderr, shlex_quote,
+        persist_exec_provider_leader_binding, persist_managed_leader_binding,
+        push_bounded_stderr, shlex_quote,
         write_window_rename_lockdown_event, ManagedClientAttachMode, VerifiedAmbientPaneAuthority,
         LEADER_STDERR_LIMIT,
     };
@@ -3495,6 +3494,95 @@ mod tests {
         let _ = std::fs::remove_dir_all(&workspace);
     }
 
+    fn exec_binding_fixture(workspace: &Path) -> (LeaderStartPlan, VerifiedAmbientPaneAuthority) {
+        let identity = LeaderIdentity {
+            leader_session_uuid: LeaderSessionUuid::derive(
+                "fp", &workspace.to_string_lossy(), "tester", "current",
+            ).unwrap(),
+            leader_session_uuid_source: LeaderSessionUuidSource::Derived,
+            machine_fingerprint: "fp".into(), workspace_abspath: workspace.into(),
+            os_user: "tester".into(), team_id: TeamKey::new("current"),
+        };
+        let plan = LeaderStartPlan {
+            mode: LeaderStartMode::ExecProvider, provider: Provider::Pi,
+            workspace: workspace.into(), socket: LeaderLaunchSocket::Workspace,
+            session_name: None, argv: vec![], provider_argv: vec!["pi".into()],
+            leader_prompt: None, session_capture: None, leader_window: None,
+            is_external_leader: false, leader_env: BTreeMap::new(),
+            identity: Some(identity), detached: false,
+        };
+        let authority = VerifiedAmbientPaneAuthority {
+            pane_id: PaneId::new("%77"),
+            observed: PaneInfo {
+                pane_id: PaneId::new("%77"), session: SessionName::new("cursor-gate-leader"),
+                window_index: Some(0), window_name: Some(WindowName::new("pi")),
+                pane_index: Some(0), tty: Some("/dev/ttys077".into()),
+                current_command: Some("pi".into()), current_path: Some(workspace.into()),
+                active: true, pane_pid: None, leader_env: BTreeMap::new(),
+            },
+            endpoint: "/private/tmp/fixture-exec-leader.sock".into(),
+            tmux: "/private/tmp/fixture-exec-leader.sock,123,0".into(),
+        };
+        (plan, authority)
+    }
+
+    fn exec_binding_workspace() -> std::path::PathBuf {
+        let workspace = std::env::temp_dir().join(format!("ta-exec-bootstrap-{}-{}",
+            std::process::id(), std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos()));
+        std::fs::create_dir(&workspace).unwrap();
+        workspace
+    }
+
+    #[test]
+    fn exec_provider_non_prefixed_receiver_produces_fresh_quick_start_bootstrap() {
+        let workspace = exec_binding_workspace();
+        let (plan, authority) = exec_binding_fixture(&workspace);
+        persist_exec_provider_leader_binding(&plan, &workspace, &authority, false).unwrap();
+        let state = crate::state::persist::load_runtime_state(&workspace).unwrap();
+        let before = state.clone();
+        assert!(state["session_name"].is_null());
+        assert!(state["teams"]["current"]["session_name"].is_null());
+        assert_eq!(state["teams"]["current"]["leader_receiver"]["session_name"], "cursor-gate-leader");
+        assert!(!crate::lifecycle::launch::quick_start_has_runtime_for_test(&state, "current"));
+        assert_eq!(state, before);
+        std::fs::remove_dir_all(workspace).unwrap();
+    }
+
+    #[test]
+    fn exec_provider_preserves_existing_workers_and_never_clears_runtime_markers() {
+        for status in ["running", "stopped", "unknown"] {
+            let workspace = exec_binding_workspace();
+            let (plan, authority) = exec_binding_fixture(&workspace);
+            let path = crate::state::persist::runtime_state_path(&workspace);
+            std::fs::create_dir_all(path.parent().unwrap()).unwrap();
+            std::fs::write(&path, serde_json::json!({
+                "active_team_key":"current", "session_name":"team-existing-workers",
+                "spec_path":"/fixture/spec.yml", "team_dir":"/fixture/roles",
+                "agents":{"worker":{"agent_id":"worker","provider":"pi","status":status}},
+                "tasks":[{"task_id":"existing-task"}],
+            }).to_string()).unwrap();
+            persist_exec_provider_leader_binding(&plan, &workspace, &authority, false).unwrap();
+            let state = crate::state::persist::load_runtime_state(&workspace).unwrap();
+            for row in [&state, &state["teams"]["current"]] {
+                assert_eq!(row["session_name"], "team-existing-workers");
+                assert_eq!(row["agents"]["worker"]["status"], status);
+                assert_eq!(row["spec_path"], "/fixture/spec.yml");
+                assert_eq!(row["team_dir"], "/fixture/roles");
+                assert_eq!(row["tasks"][0]["task_id"], "existing-task");
+            }
+            // Ownership writers update only the canonical team record, not the
+            // legacy root view that retains the existing worker runtime.
+            assert_eq!(
+                state["teams"]["current"]["leader_receiver"]["session_name"],
+                "cursor-gate-leader"
+            );
+            assert!(state["leader_receiver"].is_null());
+            assert!(crate::lifecycle::launch::quick_start_has_runtime_for_test(&state, "current"));
+            std::fs::remove_dir_all(workspace).unwrap();
+        }
+    }
+
     #[test]
     #[serial_test::serial(env)]
     fn default_exec_provider_persists_current_pane_binding_before_provider_exec() {

package/crates/team-agent/src/lifecycle/launch/quick_start.rs

@@ -120,7 +120,12 @@ impl FreshQuickStartLeaderBindingOps for RuntimeFreshQuickStartLeaderBindingOps<
     }
 
     fn tmux_endpoint(&mut self) -> Option<String> {
-        self.transport.tmux_endpoint()
+        // Bind the endpoint we use to observe the caller, not the worker server.
+        let caller_transport = caller_read_transport();
+        caller_transport
+            .as_deref()
+            .unwrap_or(self.transport)
+            .tmux_endpoint()
     }
 
     fn observe_command(&mut self, pane: &PaneId) -> Option<String> {
@@ -3128,6 +3133,99 @@ mod fresh_quick_start_leader_binding_tests {
         })
     }
 
+    #[cfg(unix)]
+    #[test]
+    #[serial_test::serial(env)]
+    fn runtime_binding_endpoint_matches_caller_socket_without_redirecting_workers() {
+        let hermetic = HermeticTestEnv::enter("runtime-caller-endpoint");
+        let workspace = hermetic.root();
+        let caller_socket = workspace.join("leader.sock");
+        // Select the real caller-read backend without depending on a host tmux
+        // server. This marker is not evidence of pane liveness.
+        std::fs::write(&caller_socket, "fixture endpoint; no tmux server").unwrap();
+        let caller_endpoint = caller_socket.to_str().unwrap();
+        let tmux = hermetic.with_env("TMUX", &format!("{caller_endpoint},1,0"));
+        let _pane = hermetic.with_env("TMUX_PANE", "%0");
+        let worker_endpoint = "ta-fixture-workers";
+        let transport = OfflineTransport::new()
+            .with_tmux_endpoint(worker_endpoint)
+            .with_pane_current_command("%0", "pi");
+        let mut ops = RuntimeFreshQuickStartLeaderBindingOps {
+            transport: &transport,
+            last_failure_reason: None,
+            cas_conflict: false,
+            applied_grant: None,
+            registry_receipt: None,
+            frozen_owner: None,
+            frozen_receiver: None,
+            nonce_writer: None,
+        };
+        let endpoint = ops.tmux_endpoint().unwrap();
+        assert_eq!(endpoint, caller_endpoint);
+        assert_eq!(
+            caller_read_transport().unwrap().tmux_endpoint().as_deref(),
+            Some(endpoint.as_str())
+        );
+        assert_eq!(transport.tmux_endpoint().as_deref(), Some(worker_endpoint));
+        let state = native_persisted_binding(workspace, caller_endpoint);
+        let before = state.clone();
+        assert!(persisted_binding_matches_verified_pane(
+            &state,
+            workspace,
+            &PaneId::new("%0"),
+            Provider::Pi,
+            Some(&endpoint),
+        ));
+        assert_eq!(state, before);
+        drop(tmux);
+        assert!(caller_read_transport().is_none());
+        assert_eq!(ops.tmux_endpoint().as_deref(), Some(worker_endpoint));
+    }
+
+    #[cfg(unix)]
+    #[test]
+    #[serial_test::serial(env)]
+    fn runtime_binding_endpoint_rejects_foreign_socket_with_same_pane_identity() {
+        let hermetic = HermeticTestEnv::enter("runtime-foreign-endpoint");
+        let workspace = hermetic.root();
+        let caller_socket = workspace.join("leader.sock");
+        std::fs::write(&caller_socket, "fixture endpoint; no tmux server").unwrap();
+        let caller_endpoint = caller_socket.to_str().unwrap();
+        let _tmux = hermetic.with_env("TMUX", &format!("{caller_endpoint},1,0"));
+        let _pane = hermetic.with_env("TMUX_PANE", "%0");
+        let worker_endpoint = "ta-fixture-workers";
+        let transport = OfflineTransport::new()
+            .with_tmux_endpoint(worker_endpoint)
+            .with_pane_current_command("%0", "pi");
+        let mut ops = RuntimeFreshQuickStartLeaderBindingOps {
+            transport: &transport,
+            last_failure_reason: None,
+            cas_conflict: false,
+            applied_grant: None,
+            registry_receipt: None,
+            frozen_owner: None,
+            frozen_receiver: None,
+            nonce_writer: None,
+        };
+        let endpoint = ops.tmux_endpoint().unwrap();
+        assert_eq!(endpoint, caller_endpoint);
+        let foreign_socket = workspace.join("foreign").join("leader.sock");
+        for socket in [worker_endpoint, foreign_socket.to_str().unwrap()] {
+            let state = native_persisted_binding(workspace, socket);
+            let before = state.clone();
+            // Both servers may have %0; the shared owner/provider/UUID/epoch
+            // cannot make a foreign endpoint authoritative.
+            assert!(!persisted_binding_matches_verified_pane(
+                &state,
+                workspace,
+                &PaneId::new("%0"),
+                Provider::Pi,
+                Some(&endpoint),
+            ));
+            assert_eq!(state, before);
+        }
+    }
+
     #[cfg(unix)]
     #[test]
     #[serial_test::serial(env)]

package/crates/team-agent/src/lifecycle/launch/state_projection.rs

@@ -120,15 +120,13 @@ pub(super) fn persist_spawn_agent_state(
             continue;
         };
         #[cfg(unix)]
-        if agent
+        if let Some(descriptor) = agent
             .get("provider")
             .and_then(Value::as_str)
-            .is_some_and(|provider| {
-                crate::contract_runtime::registry::descriptor(provider).is_some()
-            })
+            .and_then(crate::contract_runtime::registry::descriptor)
         {
             let projected = if agent_is_paused(agent) {
-                serde_json::json!({"agent_id":id,"provider":"kiro","runtime_family":"contract","status":"paused","pane_id":null})
+                serde_json::json!({"agent_id":id,"provider":descriptor.identity.id,"runtime_family":"contract","status":"paused","paused":true,"contract_instance":null,"pane_id":null})
             } else {
                 crate::contract_runtime::framework::project_seat(workspace, &team_id, id)
                     .map_err(|error| LifecycleError::StatePersist(error.to_string()))?

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

@@ -383,6 +383,12 @@ pub use worker_env::{apply_cursor_subscription_proxy_env, CursorProxyPresence};
 
 mod identity;
 pub(super) use identity::*;
+
+// Test-only seam for the real leader producer -> unchanged bootstrap classifier.
+#[cfg(test)]
+pub(crate) fn quick_start_has_runtime_for_test(state: &serde_json::Value, team: &str) -> bool {
+    identity::runtime_state_has_quick_start_team(state, team)
+}
 pub(crate) use identity::{
     extend_worker_env_unset_for_effort, provider_effort_event_if_dropped,
     provider_effort_event_if_dropped_json, provider_effort_event_payload,

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

@@ -307,6 +307,7 @@ pub(crate) fn start_agent_at_paths(
             &window,
             noop_pane.as_ref(),
         )?;
+        state["agents"][agent_id.as_str()]["explicit_stop"] = serde_json::Value::Bool(false);
         let team_key = restart_projection_team_key(&state, team);
         save_restart_projected_state(workspace, &mut state, &team_key, &[agent_id.as_str()])?;
         if let Ok(spec) = load_team_spec(spec_workspace) {
@@ -1258,6 +1259,7 @@ pub(super) fn stop_agent_at_paths(
         let _ = write_stop_drain_event(workspace, agent_id, &target_str, &drain_evidence);
     }
     mark_agent_stopped(&mut state, agent_id, agent, &window)?;
+    state["agents"][agent_id.as_str()]["explicit_stop"] = serde_json::Value::Bool(true);
     let team_key = restart_projection_team_key(&state, team);
     // golden operations.py:95: save_team_scoped_state (team projection) — NOT a raw save, so a
     // multi-team workspace keeps the other teams' persisted runtime state instead of being clobbered.
@@ -1380,6 +1382,7 @@ pub(super) fn mark_agent_started(
         }
     }
     agent.insert("status".to_string(), serde_json::json!("running"));
+    agent.insert("explicit_stop".to_string(), serde_json::Value::Bool(false));
     agent.insert("agent_id".to_string(), serde_json::json!(agent_id.as_str()));
     agent.insert("window".to_string(), serde_json::json!(window));
     agent.insert(
@@ -1741,6 +1744,7 @@ fn reset_agent_at_paths(
         .and_then(serde_json::Value::as_object_mut)
     {
         obj.insert("spawn_epoch".to_string(), serde_json::json!(new_epoch));
+        obj.insert("explicit_stop".to_string(), serde_json::Value::Bool(false));
     }
     let team_key = restart_projection_team_key(&state, team);
     sync_restart_team_projections(&mut state, &team_key);