@team-agent/installer 0.5.115 → 0.5.117

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

@@ -4,21 +4,33 @@ use std::collections::BTreeMap;
 use std::path::PathBuf;
 use team_agent_contract::contract::{
     descriptor::{PromptCarrier, ProviderDescriptor, ToolNaming},
+    types::InstanceIdentity,
     hooks::{PlanHook, ProviderHooks},
     plan::{LaunchPlan, ResolvedLaunch},
     types::{ContractError, Support},
 };
 use team_agent_contract::kiro::{self, KiroAdapter, KIRO_DESCRIPTOR};
 use team_agent_contract::providers::cursor::{self, CursorAdapter, CURSOR_DESCRIPTOR};
-use team_agent_contract::runtime::{delivery::ControlDefinition, native_panel::NativePanelPolicy};
+use team_agent_contract::providers::grok_build::{self, GrokAdapter, GROK_BUILD_DESCRIPTOR};
+use team_agent_contract::runtime::{
+    delivery::{ControlDefinition, StartupDefinition},
+    native_panel::{NativePanelPolicy, SessionPanelPolicy},
+};
+
+const DESCRIPTORS: &[&ProviderDescriptor] = &[&KIRO_DESCRIPTOR, &CURSOR_DESCRIPTOR, &GROK_BUILD_DESCRIPTOR];
 
-const DESCRIPTORS: &[&ProviderDescriptor] = &[&KIRO_DESCRIPTOR, &CURSOR_DESCRIPTOR];
+#[derive(Clone)]
+pub enum NativeRuntime {
+    Cursor(cursor::native::RuntimeInstallation),
+    GrokBuild(grok_build::native::RuntimeInstallation),
+}
 
 /// Leaf selection stays here; the framework, lifecycle and outbox remain shared.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 pub(super) enum NativeProvider {
     Kiro,
     Cursor,
+    GrokBuild,
 }
 
 impl NativeProvider {
@@ -26,19 +38,21 @@ impl NativeProvider {
         match self {
             Self::Kiro => &KIRO_DESCRIPTOR,
             Self::Cursor => &CURSOR_DESCRIPTOR,
+            Self::GrokBuild => &GROK_BUILD_DESCRIPTOR,
         }
     }
 
     pub fn action_budget(self) -> std::time::Duration {
         // Kiro's existing budget is unchanged; Cursor's measured cold-ready
         // path needs a larger finite bound, not an unbounded readiness wait.
-        std::time::Duration::from_secs(match self { Self::Kiro => 30, Self::Cursor => 90 })
+        std::time::Duration::from_secs(match self { Self::Kiro => 30, Self::Cursor | Self::GrokBuild => 90 })
     }
 
     pub fn controls(self) -> &'static [ControlDefinition] {
         match self {
             Self::Kiro => kiro::interaction::CONTROLS,
             Self::Cursor => cursor::interaction::CONTROLS,
+            Self::GrokBuild => grok_build::interaction::CONTROLS,
         }
     }
 
@@ -48,10 +62,24 @@ impl NativeProvider {
         matches!(self.descriptor().prompt.carrier, Support::Supported(PromptCarrier::RuntimeBridge))
     }
 
-    /// Cursor has no measured neutral TUI tools panel. Its protocol binding
-    /// must come from the separately fenced native tool-roundtrip ledger.
+    /// These providers use the separately fenced native tool-roundtrip ledger,
+    /// never a guessed neutral tools panel or another provider's inspector.
     pub fn uses_tool_roundtrips(self) -> bool {
-        matches!(self, Self::Cursor)
+        matches!(self, Self::Cursor | Self::GrokBuild)
+    }
+
+    pub fn startup(self) -> Option<&'static StartupDefinition> {
+        match self {
+            Self::GrokBuild => Some(&grok_build::interaction::STARTUP),
+            Self::Kiro | Self::Cursor => None,
+        }
+    }
+
+    pub fn session_panel(self) -> Option<&'static SessionPanelPolicy> {
+        match self {
+            Self::GrokBuild => Some(&grok_build::interaction::SESSION_PANEL),
+            Self::Kiro | Self::Cursor => None,
+        }
     }
 
     pub fn tool_panel(self) -> Result<&'static NativePanelPolicy, ContractError> {
@@ -61,9 +89,20 @@ impl NativeProvider {
                 field: "Cursor native Team-tool inspector",
                 reason: cursor::UNVERIFIED,
             }),
+            Self::GrokBuild => Err(ContractError::Unverified {
+                field: "Grok Build native Team-tool inspector",
+                reason: grok_build::UNVERIFIED,
+            }),
         }
     }
 
+    pub fn server_key_for(self, identity: &InstanceIdentity) -> Result<String, ContractError> {
+        if self == Self::GrokBuild {
+            return Ok(grok_build::server_key(identity));
+        }
+        Ok(self.server_key()?.into())
+    }
+
     pub fn server_key(self) -> Result<&'static str, ContractError> {
         match self.descriptor().tool_names.naming.require("tool naming")? {
             ToolNaming::StaticServer { key } => Ok(key),
@@ -84,6 +123,9 @@ impl NativeProvider {
             Self::Cursor => CursorAdapter::new(cursor::McpStdio {
                 executable, arguments, environment,
             }).map(NativeAdapter::Cursor),
+            Self::GrokBuild => GrokAdapter::new(grok_build::McpStdio {
+                executable, arguments, environment,
+            }).map(NativeAdapter::GrokBuild),
         }
     }
 }
@@ -91,13 +133,14 @@ impl NativeProvider {
 pub(super) enum NativeAdapter {
     Kiro(KiroAdapter),
     Cursor(CursorAdapter),
+    GrokBuild(GrokAdapter),
 }
 
 impl NativeAdapter {
     pub fn with_launch_context(
         self,
         project: PathBuf,
-        runtime: Option<cursor::native::RuntimeInstallation>,
+        runtime: Option<NativeRuntime>,
     ) -> Result<Self, ContractError> {
         match self {
             Self::Kiro(adapter) if runtime.is_none() => Ok(Self::Kiro(adapter)),
@@ -105,7 +148,16 @@ impl NativeAdapter {
             Self::Cursor(adapter) => {
                 let adapter = adapter.with_project(project)?;
                 Ok(Self::Cursor(match runtime {
-                    Some(runtime) => adapter.with_runtime(runtime),
+                    Some(NativeRuntime::Cursor(runtime)) => adapter.with_runtime(runtime),
+                    Some(_) => return Err(ContractError::Mismatch("native runtime provider")),
+                    None => adapter,
+                }))
+            }
+            Self::GrokBuild(adapter) => {
+                let adapter = adapter.with_project(project)?;
+                Ok(Self::GrokBuild(match runtime {
+                    Some(NativeRuntime::GrokBuild(runtime)) => adapter.with_runtime(runtime),
+                    Some(_) => return Err(ContractError::Mismatch("native runtime provider")),
                     None => adapter,
                 }))
             }
@@ -116,6 +168,7 @@ impl NativeAdapter {
         match self {
             Self::Kiro(adapter) => adapter.hooks(),
             Self::Cursor(adapter) => adapter.hooks(),
+            Self::GrokBuild(adapter) => adapter.hooks(),
         }
     }
 
@@ -123,6 +176,7 @@ impl NativeAdapter {
         match self {
             Self::Kiro(adapter) => adapter.plan(request),
             Self::Cursor(adapter) => adapter.plan(request),
+            Self::GrokBuild(adapter) => adapter.plan(request),
         }
     }
 }
@@ -132,6 +186,7 @@ pub(super) fn provider(key: &str) -> Result<NativeProvider, ContractError> {
     match descriptor.identity.id {
         "kiro" => Ok(NativeProvider::Kiro),
         "cursor" => Ok(NativeProvider::Cursor),
+        "grok_build" => Ok(NativeProvider::GrokBuild),
         _ => Err(ContractError::Invalid("contract provider dispatcher")),
     }
 }
@@ -168,11 +223,15 @@ mod tests {
     fn canonical_cursor_does_not_reclassify_legacy_names() {
         assert_eq!(provider("cursor").unwrap(), NativeProvider::Cursor);
         assert_eq!(provider("kiro").unwrap(), NativeProvider::Kiro);
-        for legacy in ["cursor_agent", "agent", "pi", "codex"] {
+        for legacy in ["cursor_agent", "agent", "pi", "codex", "grok"] {
             assert!(descriptor(legacy).is_none());
             assert!(!recognizes(legacy));
             assert!(provider(legacy).is_err());
         }
+        assert_eq!(provider("grok_build").unwrap(), NativeProvider::GrokBuild);
+        assert!(recognizes(" Grok_Build "));
+        assert!(descriptor("Grok_Build").is_none());
+        assert!(GROK_BUILD_DESCRIPTOR.identity.aliases.is_empty());
         assert!(recognizes(" Cursor "));
         assert!(descriptor("Cursor").is_none());
         for descriptor in descriptors() {
@@ -180,6 +239,24 @@ mod tests {
         }
     }
 
+    #[test]
+    fn grok_server_key_is_generation_bound_and_has_no_inspector_fallback() {
+        use team_agent_contract::contract::types::{Generation, InstanceId, ScopeId, SeatId};
+        let mut identity = InstanceIdentity {
+            scope: ScopeId::new("scope").unwrap(), seat: SeatId::new("worker").unwrap(),
+            instance: InstanceId::new("instance").unwrap(), generation: Generation(1),
+        };
+        let first = NativeProvider::GrokBuild.server_key_for(&identity).unwrap();
+        assert_eq!(first, grok_build::server_key(&identity));
+        identity.generation = Generation(2);
+        assert_ne!(first, NativeProvider::GrokBuild.server_key_for(&identity).unwrap());
+        assert!(NativeProvider::GrokBuild.server_key().is_err());
+        assert!(NativeProvider::GrokBuild.tool_panel().is_err());
+        assert!(NativeProvider::GrokBuild.startup().is_some());
+        assert!(NativeProvider::GrokBuild.session_panel().is_some());
+        assert!(NativeProvider::GrokBuild.uses_tool_roundtrips());
+    }
+
     #[test]
     fn cursor_has_no_kiro_control_or_tool_inspector_fallback() {
         assert!(NativeProvider::Cursor.controls().is_empty());

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

@@ -1,5 +1,6 @@
-//! Stable per-seat primary cwd. The project stays an additional directory;
-//! private MCP files never overwrite a shared project or another seat's config.
+//! 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;
@@ -23,7 +24,7 @@ struct CwdRecord {
 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 = root.join("workspaces");
+    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) {
@@ -43,12 +44,23 @@ pub(super) fn prepare(binding: &Binding, seat: &SeatId) -> Result<CwdIdentity, B
                 return Err(BackendError::Metadata);
             }
             let record: CwdRecord = serde_json::from_slice(&bytes).map_err(|_| BackendError::Metadata)?;
-            if record.version != 1 || record.seat != *seat || record.cwd.path != path {
+            // 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(&parent)?;
-            validate_directory(&path)?;
-            if resolve_cwd(&path)? != record.cwd {
+            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);
@@ -56,6 +68,8 @@ pub(super) fn prepare(binding: &Binding, seat: &SeatId) -> Result<CwdIdentity, B
         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 => {
@@ -68,7 +82,7 @@ pub(super) fn prepare(binding: &Binding, seat: &SeatId) -> Result<CwdIdentity, B
     std::fs::DirBuilder::new().mode(0o700).create(&path)?;
     validate_directory(&path)?;
     let cwd = resolve_cwd(&path)?;
-    let record = CwdRecord { version: 1, seat: seat.clone(), cwd: cwd.clone() };
+    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)?;
@@ -77,6 +91,19 @@ pub(super) fn prepare(binding: &Binding, seat: &SeatId) -> Result<CwdIdentity, B
     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
@@ -108,8 +135,9 @@ mod tests {
                 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.join("transport"),
+                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();
@@ -117,7 +145,10 @@ mod tests {
         }
     }
     impl Drop for Fixture {
-        fn drop(&mut self) { let _ = std::fs::remove_dir_all(&self.path); }
+        fn drop(&mut self) {
+            let _ = std::fs::remove_dir_all(&self.path);
+            let _ = std::fs::remove_dir_all(&self.binding.transport_root);
+        }
     }
 
     #[test]
@@ -151,10 +182,47 @@ mod tests {
     fn unrecorded_existing_directory_is_not_claimed() {
         let f = Fixture::new();
         let root = root_for(&f.path, &f.binding.scope);
-        let parent = root.join("workspaces");
+        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/lease.rs

@@ -4,8 +4,6 @@
 
 use std::collections::BTreeSet;
 use std::path::{Path, PathBuf};
-use std::sync::atomic::{AtomicU64, Ordering};
-use std::time::{SystemTime, UNIX_EPOCH};
 
 use serde_json::{json, Value};
 use sha2::{Digest, Sha256};
@@ -1837,22 +1835,7 @@ fn canonical_workspace(workspace: &Path) -> PathBuf {
 }
 
 fn next_pane_binding_nonce(workspace: &Path, endpoint: &str, pane: &PaneId) -> String {
-    static COUNTER: AtomicU64 = AtomicU64::new(0);
-    let nanos = SystemTime::now()
-        .duration_since(UNIX_EPOCH)
-        .map_or(0, |duration| duration.as_nanos());
-    let counter = COUNTER.fetch_add(1, Ordering::Relaxed);
-    let material = format!(
-        "{}\0{endpoint}\0{}\0{}\0{nanos}\0{counter}",
-        canonical_workspace(workspace).display(),
-        pane.as_str(),
-        std::process::id(),
-    );
-    let digest = Sha256::digest(material.as_bytes());
-    digest[..16]
-        .iter()
-        .map(|byte| format!("{byte:02x}"))
-        .collect()
+    crate::tmux_backend::next_pane_binding_nonce(workspace, endpoint, pane)
 }
 
 fn pane_binding_nonce_for_claim(

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

@@ -36,6 +36,7 @@ pub(crate) struct PaneInputLockRequest<'a> {
 
 pub(crate) struct PaneInputLockGuard {
     file: Option<std::fs::File>,
+    guard_gate: Option<std::fs::File>,
 }
 
 /// ---
@@ -54,18 +55,58 @@ pub(crate) fn acquire_or_proceed(request: PaneInputLockRequest<'_>) -> Option<Pa
         // No workspace (some unit backends): nothing to lock against. Not an alarm.
         return None;
     };
-    acquire_file_lock(workspace, &request, timeout)
+    acquire_file_lock(workspace, &request, timeout, "proceed")
+}
+
+/// Every legacy writer holds shared admission through its whole operation,
+/// even when its ordinary 200ms lock times out. Required guards hold exclusive
+/// admission, so neither can enter while the other is already writing.
+pub(crate) fn acquire_for_write(request: PaneInputLockRequest<'_>) -> Result<Option<PaneInputLockGuard>, ()> {
+    if request.workspace.is_none() { return Ok(None); }
+    let gate = acquire_guard_gate(&request, false)?;
+    let mut guard = acquire_or_proceed(request).unwrap_or(PaneInputLockGuard { file: None, guard_gate: None });
+    guard.guard_gate = Some(gate);
+    Ok(Some(guard))
+}
+
+fn acquire_guard_gate(request: &PaneInputLockRequest<'_>, exclusive: bool) -> Result<std::fs::File, ()> {
+    let opened = (|| -> std::io::Result<std::fs::File> {
+        let workspace = request.workspace.ok_or_else(|| std::io::Error::other("workspace missing"))?;
+        let path = pane_input_lock_path(workspace, request.target_key).with_extension("guard");
+        if let Some(parent) = path.parent() { std::fs::create_dir_all(parent)?; }
+        let file = std::fs::OpenOptions::new().create(true).read(true).write(true).truncate(false).open(path)?;
+        let result = if exclusive { file.try_lock() } else { file.try_lock_shared() };
+        result.map_err(|error| match error {
+            std::fs::TryLockError::WouldBlock => std::io::Error::from(std::io::ErrorKind::WouldBlock),
+            std::fs::TryLockError::Error(error) => error,
+        })?;
+        Ok(file)
+    })();
+    opened.map_err(|_| emit_timeout_alarm(request, PANE_INPUT_LOCK_TIMEOUT, Duration::ZERO, "guard_gate", "refuse"))
+}
+
+/// Guarded native input must never treat a missing/contended lock as permission.
+pub(crate) fn acquire_required(request: PaneInputLockRequest<'_>) -> Option<PaneInputLockGuard> {
+    let Some(workspace) = request.workspace else {
+        emit_timeout_alarm(&request, PANE_INPUT_LOCK_TIMEOUT, Duration::ZERO, "workspace_missing", "refuse");
+        return None;
+    };
+    let gate = acquire_guard_gate(&request, true).ok()?;
+    let mut guard = acquire_file_lock(workspace, &request, PANE_INPUT_LOCK_TIMEOUT, "refuse")?;
+    guard.guard_gate = Some(gate);
+    Some(guard)
 }
 
 fn acquire_file_lock(
     workspace: &Path,
     request: &PaneInputLockRequest<'_>,
     timeout: Duration,
+    disposition: &str,
 ) -> Option<PaneInputLockGuard> {
     let path = pane_input_lock_path(workspace, request.target_key);
     if let Some(parent) = path.parent() {
         if std::fs::create_dir_all(parent).is_err() {
-            emit_timeout_alarm(request, timeout, Duration::ZERO, "lock_dir");
+            emit_timeout_alarm(request, timeout, Duration::ZERO, "lock_dir", disposition);
             return None;
         }
     }
@@ -78,7 +119,7 @@ fn acquire_file_lock(
     {
         Ok(file) => file,
         Err(_) => {
-            emit_timeout_alarm(request, timeout, Duration::ZERO, "lock_open");
+            emit_timeout_alarm(request, timeout, Duration::ZERO, "lock_open", disposition);
             return None;
         }
     };
@@ -86,17 +127,17 @@ fn acquire_file_lock(
     loop {
         match crate::platform::file_lock::try_lock_once_nonblocking(&file) {
             Ok(true) => {
-                return Some(PaneInputLockGuard { file: Some(file) });
+                return Some(PaneInputLockGuard { file: Some(file), guard_gate: None });
             }
             Ok(false) => {}
             Err(_) => {
-                emit_timeout_alarm(request, timeout, started.elapsed(), "lock_io");
+                emit_timeout_alarm(request, timeout, started.elapsed(), "lock_io", disposition);
                 return None;
             }
         }
         let elapsed = started.elapsed();
         if elapsed >= timeout {
-            emit_timeout_alarm(request, timeout, elapsed, "timeout");
+            emit_timeout_alarm(request, timeout, elapsed, "timeout", disposition);
             return None;
         }
         std::thread::sleep(std::cmp::min(
@@ -127,10 +168,11 @@ fn emit_timeout_alarm(
     timeout: Duration,
     waited: Duration,
     reason: &str,
+    disposition: &str,
 ) {
     // A5 watches this exact token on stderr. Commenting this line must turn A5 red.
     eprintln!(
-        "{PANE_INPUT_LOCK_TIMEOUT_EVENT} target={} operation={} waited_ms={} timeout_ms={} reason={reason} proceeding",
+        "{PANE_INPUT_LOCK_TIMEOUT_EVENT} target={} operation={} waited_ms={} timeout_ms={} reason={reason} disposition={disposition}",
         request.target_key,
         request.operation,
         waited.as_millis(),
@@ -146,7 +188,7 @@ fn emit_timeout_alarm(
                 "waited_ms": waited.as_millis() as u64,
                 "timeout_ms": timeout.as_millis() as u64,
                 "reason": reason,
-                "disposition": "proceed",
+                "disposition": disposition,
             }),
         );
     }
@@ -157,5 +199,41 @@ impl Drop for PaneInputLockGuard {
         if let Some(file) = self.file.take() {
             let _ = crate::platform::file_lock::unlock(&file);
         }
+        if let Some(gate) = self.guard_gate.take() { let _ = gate.unlock(); }
+    }
+}
+
+#[cfg(test)]
+mod required_tests {
+    #![allow(clippy::unwrap_used)]
+    use super::*;
+
+    #[test]
+    fn required_pane_input_lock_missing_workspace_refuses() {
+        assert!(acquire_required(PaneInputLockRequest { workspace: None, target_key: "%1", operation: "fixture" }).is_none());
+    }
+
+    #[test]
+    fn required_pane_input_lock_contention_refuses_and_drop_releases_same_key() {
+        let workspace = std::env::temp_dir().join(format!("ta-required-pane-lock-{}", std::process::id()));
+        std::fs::create_dir(&workspace).unwrap();
+        let request = || PaneInputLockRequest { workspace: Some(workspace.as_path()), target_key: "%1", operation: "fixture" };
+        let held = acquire_required(request()).unwrap();
+        assert!(acquire_required(request()).is_none());
+        let events = std::fs::read_to_string(workspace.join(".team/logs/events.jsonl")).unwrap();
+        assert!(events.lines().filter_map(|line| serde_json::from_str::<serde_json::Value>(line).ok())
+            .any(|row| row.to_string().contains("\"disposition\":\"refuse\"")));
+        drop(held);
+        drop(acquire_required(request()).unwrap());
+        // Preserve the old timeout/proceed policy, but hold reader admission
+        // through that unheld-main-lock writer so no required guard crosses it.
+        let first_writer = acquire_for_write(request()).unwrap().unwrap();
+        let timed_out_writer = acquire_for_write(request()).unwrap().unwrap();
+        assert!(timed_out_writer.file.is_none());
+        drop(first_writer);
+        assert!(acquire_required(request()).is_none());
+        drop(timed_out_writer);
+        drop(acquire_required(request()).unwrap());
+        std::fs::remove_dir_all(workspace).unwrap();
     }
 }

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);