@team-agent/installer 0.5.65 → 0.5.68

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

@@ -1,3 +1,13 @@
+//! ---
+//! purpose: 冷启、add/clone/fork 入口拼装
+//! contract:
+//!   provides:
+//!     - name: fork_agent
+//!       what: 成员分身入口，grok 走窗口内命令
+//! boundary:
+//!   - 不读 provider 会话落盘
+//! maturity: wired
+//! ---
 //!
 //! lifecycle::launch —— 冷启 / quick-start / 危险审批探测 + add/fork / plan 起步与推进。
 
@@ -18,6 +28,16 @@ use super::*;
 
 // ── lifecycle::launch —— 冷启 / quick-start / 危险审批探测 ──────────────────
 
+/// ---
+/// purpose: 冷启全队的默认入口，按 spec 所在目录绑定 per-team tmux socket 后转 launch_with_transport
+/// params:
+///   spec_path: 已编译 spec 的路径，其父目录即 team 目录
+///   dry_run: 只出路由与权限，不 spawn 也不落盘
+///   auto_approve: 当前为 no-op
+///   skip_profile_smoke: 当前为 no-op
+/// returns: LaunchReport
+/// errors: 透传 launch_with_transport 的错误
+/// ---
 ///
 /// `launch(spec_path, dry_run, auto_approve, skip_profile_smoke)`(`launch/core.py:29`)。
 /// 冷启全队:路由 tasks、resolve 权限/危险审批门、session 冲突检查(冲突 →
@@ -42,6 +62,13 @@ pub fn launch(
     )
 }
 
+/// ---
+/// purpose: 由 spec 路径推出 workspace，再转 launch_with_transport_in_workspace
+/// params:
+///   transport: 已绑定 team socket 的 transport
+/// returns: LaunchReport
+/// errors: 透传 launch_with_transport_in_workspace 的错误
+/// ---
 pub(crate) fn launch_with_transport(
     spec_path: &Path,
     dry_run: bool,
@@ -61,6 +88,17 @@ pub(crate) fn launch_with_transport(
     )
 }
 
+/// ---
+/// purpose: 冷启全队的实体实现，编译 spec、检查 session 冲突、按序 spawn、落 state、出报告
+/// params:
+///   workspace: run workspace 根，事件与 state 都落在这里
+///   spec_path: 已编译 spec 的路径
+///   dry_run: 为真时不 spawn 不落盘，started 为空
+///   auto_approve: 未使用
+///   skip_profile_smoke: 未使用
+/// returns: LaunchReport，其中 leader_receiver_attached 恒 false、session_capture_incomplete_agents 恒空
+/// errors: spec 不存在或解析失败返回 Compile，tmux session 已存在返回 SessionConflict，spawn 与落 state 的错误透传
+/// ---
 pub fn launch_with_transport_in_workspace(
     workspace: &Path,
     spec_path: &Path,
@@ -70,8 +108,9 @@ pub fn launch_with_transport_in_workspace(
     transport: &dyn Transport,
 ) -> Result<LaunchReport, LifecycleError> {
     let _ = skip_profile_smoke;
-    // 0.5.38 (`.team/artifacts/startup-latency-locate.md` §5): launch.phase
-    // timer with monotonic `elapsed_ms` for latency triage.
+    let _ = auto_approve; // 0.5.66: bypass 单源后无 runtime.dangerous_auto_approve,`--yes` 为 no-op。
+                          // 0.5.38 (`.team/artifacts/startup-latency-locate.md` §5): launch.phase
+                          // timer with monotonic `elapsed_ms` for latency triage.
     let phase_timer = crate::lifecycle::restart::RestartPhaseTimer::start();
     if !spec_path.exists() {
         return Err(LifecycleError::Compile(format!(
@@ -82,14 +121,12 @@ pub fn launch_with_transport_in_workspace(
     let text = std::fs::read_to_string(spec_path)
         .map_err(|e| LifecycleError::Compile(format!("{}: {e}", spec_path.display())))?;
     let spec = yaml::loads(&text).map_err(|e| LifecycleError::Compile(e.to_string()))?;
+    // 0.5.66 §3.2 跨 workspace 兼容警示:leader argv 带 bypass flag 但当前团队
+    // 所有角色都未声明 dangerously_skip_permissions=true → 写 warning 事件不阻塞。
+    // TODO(0.6.0): remove(0.6.0 彻底删源头 A 后此警示无意义)。
+    emit_dangerous_flag_no_role_declared_warning(workspace, &spec);
     phase_timer.emit(workspace, "launch.phase", "compile_spec");
     let session_name = spec_session_name(&spec);
-    let safety = effective_runtime_config(&spec)?;
-    if safety.enabled && !safety.inherited && !auto_approve && !dry_run {
-        return Err(LifecycleError::DangerousApprovalRequired(
-            "runtime dangerous_auto_approve is enabled".to_string(),
-        ));
-    }
     if !dry_run && transport_has_session(transport, &session_name) {
         return Err(LifecycleError::SessionConflict(format!(
             "tmux session already exists: {}",
@@ -103,20 +140,12 @@ pub fn launch_with_transport_in_workspace(
             raw: serde_json::json!({"source": "compiled_spec"}),
         })
         .collect::<Vec<_>>();
-    write_launch_permission_audit(workspace, &safety)?;
     let routes = spec_routes(&spec);
     let started = if dry_run {
         Vec::new()
     } else {
         phase_timer.emit(workspace, "launch.phase", "spawn_all");
-        let started = spawn_agents(
-            workspace,
-            spec_path,
-            &spec,
-            &session_name,
-            &safety,
-            transport,
-        )?;
+        let started = spawn_agents(workspace, spec_path, &spec, &session_name, transport)?;
         persist_spawn_agent_state(
             workspace,
             spec_path,
@@ -124,7 +153,6 @@ pub fn launch_with_transport_in_workspace(
             &session_name,
             transport,
             &started,
-            &safety,
         )?;
         // 0.5.38: per-worker timing tags (source="launch") so operators can
         // trace which worker's spawn dominates wall time. Zeros for now on
@@ -181,16 +209,54 @@ pub fn launch_with_transport_in_workspace(
         tmux_endpoint: transport.tmux_endpoint(),
         routes,
         permissions,
-        safety,
         leader_receiver_attached: false,
         session_capture_incomplete_agents: Vec::new(),
     })
 }
 
+/// 0.5.66 §3.2 跨 workspace 升级警示(仅警示,不做行为决策)。
+/// leader argv 含 bypass flag、但当前 spec 所有 agent 都未声明
+/// `dangerously_skip_permissions=true` → 写 `dangerously_flag_present_but_no_role_declared`。
+///
+/// TODO(0.6.0): remove(0.6.0 删源头 A 后此警示无意义)。
+fn emit_dangerous_flag_no_role_declared_warning(workspace: &Path, spec: &Value) {
+    let argv: Vec<String> = std::env::args().collect();
+    emit_dangerous_flag_no_role_declared_warning_with_argv(workspace, spec, &argv);
+}
+
+/// 带显式 argv 的可测版。
+fn emit_dangerous_flag_no_role_declared_warning_with_argv(
+    workspace: &Path,
+    spec: &Value,
+    argv: &[String],
+) {
+    if crate::provider::bypass_flags::detect_bypass_flag_in_argv(argv).is_none() {
+        return;
+    }
+    let any_role_declared = spec_agent_values(spec).iter().any(|agent| {
+        matches!(
+            agent.get("dangerously_skip_permissions"),
+            Some(Value::Bool(true))
+        )
+    });
+    if any_role_declared {
+        return;
+    }
+    let _ = crate::event_log::EventLog::new(workspace).write(
+        "dangerously_flag_present_but_no_role_declared",
+        serde_json::json!({
+            "message": "leader process carries a bypass flag but no role in this team declares \
+                       dangerously_skip_permissions=true; bypass no longer inherits to workers \
+                       (0.5.66 single-source). Declare the field per role to opt in.",
+        }),
+    );
+}
+
 mod plan;
 pub(crate) use plan::{handle_report_result, start_plan};
 
 pub mod spawn;
+pub(crate) use spawn::agent_id_spec_source_path;
 pub(super) use spawn::*;
 
 mod layout;
@@ -221,22 +287,43 @@ pub(crate) use leader_context::{
 
 mod agent_state;
 pub(super) use agent_state::*;
-pub(crate) use agent_state::{effective_approval_policy, persist_effective_approval_policy};
+pub(crate) use agent_state::{
+    effective_approval_policy, persist_effective_approval_policy,
+    persist_effective_approval_policy_from_agent,
+};
+
+mod grok_per_seat;
+pub(crate) use grok_per_seat::{
+    is_per_seat_env_key, non_per_seat_env_in_tables, per_seat_keys_in_toml,
+    strip_per_seat_keys_from_toml,
+};
 
 mod mcp_config;
+pub use mcp_config::apply_grok_mcp_overlay;
 pub(super) use mcp_config::*;
 pub(crate) use mcp_config::{
-    point_native_mcp_config_at_file, resolve_mcp_config, write_worker_mcp_config,
+    ensure_grok_login_and_folder_trust, grok_shared_cwd_error, point_native_mcp_config_at_file,
+    reconcile_grok_toml_per_seat_keys, resolve_mcp_config, write_worker_mcp_config,
     write_worker_mcp_config_for_provider,
 };
 
+mod cursor_mcp;
+pub use cursor_mcp::{
+    apply_cursor_mcp_overlay, apply_cursor_workspace_physical_path, cursor_mcp_enable_argv,
+    enable_cursor_workspace_mcp, physical_workspace_path, refuse_second_cursor_occupant,
+};
+
+mod cursor_create_chat;
+
 mod worker_env;
 pub(super) use worker_env::*;
 pub(crate) use worker_env::{
-    apply_copilot_instructions_overlay, apply_mcp_auto_approval_env, apply_profile_launch_env,
+    apply_copilot_instructions_overlay, apply_cursor_agent_rules_overlay,
+    apply_mcp_auto_approval_env, apply_profile_launch_env, auth_mode_env_value,
     fill_spawn_placeholders, fill_spawn_placeholders_full, inherited_env_with_team_overrides,
     persist_command_plan_state, spawn_timestamp,
 };
+pub use worker_env::{apply_cursor_subscription_proxy_env, CursorProxyPresence};
 
 mod identity;
 pub(super) use identity::*;
@@ -263,17 +350,9 @@ pub(crate) use quick_start_transport::{
 };
 
 pub mod readiness;
-pub(crate) use readiness::launched_team_receiver_is_attached;
+pub use readiness::launched_team_receiver_is_attached;
 pub(super) use readiness::*;
 
-mod approval;
-pub use approval::detect_dangerous_approval;
-use approval::{
-    binary_matches_provider, binary_name, dangerous_leader_flags,
-    detect_dangerous_approval_in_argv, disabled_dangerous_approval, process_ancestry_argv,
-    process_argv_tokens, process_parent_pid,
-};
-
 mod add_agent;
 pub(super) use add_agent::*;
 pub use add_agent::{add_agent, add_agent_force};
@@ -284,19 +363,12 @@ pub(crate) use add_agent_state::inject_agent_into_spec;
 pub(super) use add_agent_state::*;
 
 mod fork_agent;
-pub use fork_agent::fork_agent_with_transport;
 pub(super) use fork_agent::*;
+pub use fork_agent::{fork_agent_with_transport, in_window_fork, in_window_fork_command};
 
 mod fork_entry;
 pub use fork_entry::fork_agent;
 
-mod fork_state;
-pub(super) use fork_state::*;
-
-mod fork_finalize;
-pub(super) use fork_finalize::*;
-pub(crate) use fork_finalize::{finalize_pending_fork_capture, ContextForkFinalized};
-
 mod role_source;
 pub(super) use role_source::*;
 
@@ -308,15 +380,109 @@ pub(super) use ownership::*;
 pub(crate) use ownership::{ensure_owner_allowed, ensure_owner_allowed_for_state, state_path};
 
 pub mod spec_state;
+pub use spec_state::worker_session_name_pub;
 pub(crate) use spec_state::{
-    effective_runtime_config, effective_runtime_config_for_worker_spawn,
-    override_spec_session_name, override_spec_workspace, spec_agent_id_set, write_spec_atomic,
+    effective_runtime_config_for_worker_spawn, effective_runtime_config_for_worker_spawn_json,
 };
 use spec_state::{
     env_nonempty, has_positive_caller_leader_env, initial_runtime_state,
     override_spec_display_backend, override_spec_runtime_str,
     seed_launched_owner_from_caller_with_provider_lookup, seed_launched_owner_from_env,
     spec_agent_values, spec_agents, spec_default_assignee, spec_routes, spec_session_name,
-    spec_tasks_json, team_workspace, write_launch_permission_audit, yaml_value_to_json,
+    spec_tasks_json, team_workspace, yaml_value_to_json,
 };
-pub use spec_state::worker_session_name_pub;
+pub(crate) use spec_state::{
+    override_spec_session_name, override_spec_workspace, spec_agent_id_set, write_spec_atomic,
+};
+
+#[cfg(test)]
+mod tests {
+    #![allow(clippy::unwrap_used)]
+    use super::*;
+
+    // 0.5.66 §4.1 test_leader_flag_present_but_no_role_true_writes_warning_event:
+    // leader argv 带 bypass flag + 无角色声明 true → 写 warning 事件。
+    #[test]
+    fn test_leader_flag_present_but_no_role_true_writes_warning_event() {
+        let ws =
+            std::env::temp_dir().join(format!("ta-bypass-warning-test-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&ws);
+        std::fs::create_dir_all(&ws).unwrap();
+        let spec = yaml::loads(
+            "version: 1\nteam: {}\nleader: {}\nagents:\n  - id: a\n    role: r\n    provider: fake\n    dangerously_skip_permissions: false\n",
+        )
+        .unwrap();
+        let argv = vec![
+            "team-agent".to_string(),
+            "--dangerously-skip-permissions".to_string(),
+        ];
+        emit_dangerous_flag_no_role_declared_warning_with_argv(&ws, &spec, &argv);
+        let events = crate::event_log::EventLog::new(&ws).tail(0).unwrap();
+        assert!(
+            events.iter().any(|event| {
+                event.get("event").and_then(serde_json::Value::as_str)
+                    == Some("dangerously_flag_present_but_no_role_declared")
+            }),
+            "leader flag + no role declared must write the warning event; events={events:?}"
+        );
+        let _ = std::fs::remove_dir_all(&ws);
+    }
+
+    // 0.5.66 §4.1 同测试的反向:有角色声明 true → 不写 warning。
+    #[test]
+    fn test_leader_flag_present_but_role_declared_no_warning() {
+        let ws = std::env::temp_dir().join(format!(
+            "ta-bypass-warning-none-test-{}",
+            std::process::id()
+        ));
+        let _ = std::fs::remove_dir_all(&ws);
+        std::fs::create_dir_all(&ws).unwrap();
+        let spec = yaml::loads(
+            "version: 1\nteam: {}\nleader: {}\nagents:\n  - id: a\n    role: r\n    provider: fake\n    dangerously_skip_permissions: true\n",
+        )
+        .unwrap();
+        let argv = vec![
+            "team-agent".to_string(),
+            "--dangerously-skip-permissions".to_string(),
+        ];
+        emit_dangerous_flag_no_role_declared_warning_with_argv(&ws, &spec, &argv);
+        let events = crate::event_log::EventLog::new(&ws).tail(0).unwrap();
+        assert!(
+            !events.iter().any(|event| {
+                event.get("event").and_then(serde_json::Value::as_str)
+                    == Some("dangerously_flag_present_but_no_role_declared")
+            }),
+            "role declared true must suppress the warning; events={events:?}"
+        );
+        let _ = std::fs::remove_dir_all(&ws);
+    }
+
+    #[test]
+    fn team_agent_force_flag_does_not_look_like_bypass() {
+        let ws =
+            std::env::temp_dir().join(format!("ta-bypass-force-not-bypass-{}", std::process::id()));
+        let _ = std::fs::remove_dir_all(&ws);
+        std::fs::create_dir_all(&ws).unwrap();
+        let spec = yaml::loads(
+            "version: 1\nteam: {}\nleader: {}\nagents:\n  - id: a\n    role: r\n    provider: fake\n    dangerously_skip_permissions: false\n",
+        )
+        .unwrap();
+        let argv = vec![
+            "team-agent".to_string(),
+            "remove-agent".to_string(),
+            "x".to_string(),
+            "--confirm".to_string(),
+            "--force".to_string(),
+        ];
+        emit_dangerous_flag_no_role_declared_warning_with_argv(&ws, &spec, &argv);
+        let events = crate::event_log::EventLog::new(&ws).tail(0).unwrap();
+        assert!(
+            !events.iter().any(|event| {
+                event.get("event").and_then(serde_json::Value::as_str)
+                    == Some("dangerously_flag_present_but_no_role_declared")
+            }),
+            "team-agent --force must not emit bypass warning; events={events:?}"
+        );
+        let _ = std::fs::remove_dir_all(&ws);
+    }
+}

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

@@ -1,3 +1,22 @@
+//! ---
+//! purpose: workspace 级 agent-lifecycle 互斥锁，让同一 workspace 的席位增删起停串行
+//! contract:
+//!   provides:
+//!     - name: acquire_agent_lifecycle_lock
+//!       what: 轮询抢锁，成功返回持有到 Drop 的 guard，超时返回 LifecycleLockTimeout
+//!     - name: agent_lifecycle_lock_path
+//!       what: 给出该 workspace 的锁文件路径
+//!   depends:
+//!     - crate::platform::file_lock
+//!     - crate::event_log::EventLog
+//!     - crate::model::paths
+//! boundary:
+//!   - 不锁 pane 输入通道，那是 pane_input_lock
+//!   - 不做跨 workspace 互斥，锁作用域就是一个 workspace
+//!   - 拿不到锁只超时报错，不强抢也不清理他人锁文件
+//!   - 锁文件内容只作观测用，不作为持有权判据
+//! maturity: wired
+//! ---
 use std::io::{Seek, Write};
 use std::path::{Path, PathBuf};
 use std::time::{Duration, Instant};
@@ -17,10 +36,16 @@ pub(crate) struct LifecycleLockRequest<'a> {
 }
 
 pub(crate) struct LifecycleLockGuard {
-    #[allow(dead_code)]
     file: std::fs::File,
 }
 
+/// ---
+/// purpose: 抢 workspace 级 agent-lifecycle 锁，默认 30 秒超时、5 秒起写 lock_held_long 事件
+/// params:
+///   request: 携带 workspace、操作名与可选 team/agent，仅用于锁元数据与事件
+/// returns: 持有锁的 guard，Drop 时解锁
+/// errors: 建目录或打开锁文件失败返回 StatePersist，等待超时返回 LifecycleLockTimeout
+/// ---
 pub(crate) fn acquire_agent_lifecycle_lock(
     request: LifecycleLockRequest<'_>,
 ) -> Result<LifecycleLockGuard, LifecycleError> {
@@ -35,6 +60,14 @@ pub(crate) fn acquire_agent_lifecycle_lock(
     )
 }
 
+/// ---
+/// purpose: 以显式超时与告警阈值抢同一把锁，仅测试构建可见
+/// params:
+///   timeout: 放弃等待的上限
+///   held_long: 超过它写一次 lock_held_long 事件
+/// returns: 持有锁的 guard
+/// errors: 同 acquire_agent_lifecycle_lock
+/// ---
 #[cfg(test)]
 pub(crate) fn acquire_agent_lifecycle_lock_for_test(
     request: LifecycleLockRequest<'_>,
@@ -55,6 +88,10 @@ pub(crate) struct LifecycleLockDeadlineOverrideGuard {
     previous: Option<(Duration, Duration)>,
 }
 
+/// ---
+/// purpose: 线程内改写默认锁超时与告警阈值，仅测试构建可见
+/// returns: guard，Drop 时恢复上一次的取值
+/// ---
 #[cfg(test)]
 pub(crate) fn override_agent_lifecycle_lock_deadlines_for_test(
     timeout: Duration,
@@ -145,6 +182,10 @@ fn acquire_agent_lifecycle_lock_with_deadlines(
     }
 }
 
+/// ---
+/// purpose: 给出该 workspace 的 agent-lifecycle 锁文件路径
+/// returns: runtime 目录下的 agent-lifecycle.lock
+/// ---
 pub(crate) fn agent_lifecycle_lock_path(workspace: &Path) -> PathBuf {
     crate::model::paths::runtime_dir(workspace).join(format!("{AGENT_LIFECYCLE_LOCK_NAME}.lock"))
 }

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

@@ -1,3 +1,13 @@
+//! ---
+//! purpose: team 进程级生命周期编排（起停加减 clone/fork）
+//! contract:
+//!   provides:
+//!     - name: launch
+//!       what: 冷启与成员生命周期入口
+//! boundary:
+//!   - 不拥有物理注入，只调用 transport
+//! maturity: wired
+//! ---
 //!
 //! step 13 · lifecycle — team 进程级生命周期编排器(ROUND-0.5 骨架)。
 //!
@@ -46,6 +56,7 @@ pub mod display;
 pub mod helpers;
 pub mod launch;
 pub(crate) mod lock;
+pub(crate) mod pane_input_lock;
 pub(crate) mod profile_launch;
 pub(crate) mod profile_smoke;
 pub mod restart;

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

@@ -0,0 +1,161 @@
+//! ---
+//! purpose: pane 输入通道互斥锁，让同一 pane 上的写入串行化
+//! contract:
+//!   provides:
+//!     - name: acquire_or_proceed
+//!       what: 取到锁则持有到 Drop；超时或锁不可用则告警后放行，不无限等待
+//!   depends:
+//!     - crate::platform::file_lock
+//!     - crate::event_log::EventLog
+//! boundary:
+//!   - 不锁席位生命周期（那是 lock.rs）
+//!   - 不重粘文本、不加自动兜底重投；重试只重按回车由既有 inject 路径负责
+//!   - 不在投递层发明临时持有态
+//! maturity: wired
+//! ---
+
+use std::path::{Path, PathBuf};
+use std::time::{Duration, Instant};
+
+use crate::event_log::EventLog;
+use crate::model::paths::runtime_dir;
+
+/// Hard upper bound for waiting on the pane input lock. Constant, not a magic number in a loop.
+pub(crate) const PANE_INPUT_LOCK_TIMEOUT: Duration = Duration::from_millis(200);
+
+pub(crate) const PANE_INPUT_LOCK_NAME: &str = "pane-input";
+
+/// Event / stderr token. A5 greps this exact string.
+pub(crate) const PANE_INPUT_LOCK_TIMEOUT_EVENT: &str = "pane_input_lock.timeout";
+
+pub(crate) struct PaneInputLockRequest<'a> {
+    pub workspace: Option<&'a Path>,
+    pub target_key: &'a str,
+    pub operation: &'static str,
+}
+
+pub(crate) struct PaneInputLockGuard {
+    file: Option<std::fs::File>,
+}
+
+/// ---
+/// purpose: 取 pane 输入锁；拿不到或超时则告警后放行，绝不无限等待
+/// params:
+///   request: 携带可选 workspace、目标 pane 键与操作名
+/// returns: Some 表示已持锁，None 表示无 workspace 可锁或已超时放行
+/// ---
+/// Acquire the pane lock or proceed after the hard timeout.
+///
+/// On timeout / lock I/O failure: emit [`PANE_INPUT_LOCK_TIMEOUT_EVENT`] (stderr + events.jsonl)
+/// and return `None` so the caller still writes. Relief messages must not wait forever.
+pub(crate) fn acquire_or_proceed(request: PaneInputLockRequest<'_>) -> Option<PaneInputLockGuard> {
+    let timeout = PANE_INPUT_LOCK_TIMEOUT;
+    let Some(workspace) = request.workspace else {
+        // No workspace (some unit backends): nothing to lock against. Not an alarm.
+        return None;
+    };
+    acquire_file_lock(workspace, &request, timeout)
+}
+
+fn acquire_file_lock(
+    workspace: &Path,
+    request: &PaneInputLockRequest<'_>,
+    timeout: Duration,
+) -> 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");
+            return None;
+        }
+    }
+    let file = match std::fs::OpenOptions::new()
+        .create(true)
+        .read(true)
+        .write(true)
+        .truncate(false)
+        .open(&path)
+    {
+        Ok(file) => file,
+        Err(_) => {
+            emit_timeout_alarm(request, timeout, Duration::ZERO, "lock_open");
+            return None;
+        }
+    };
+    let started = Instant::now();
+    loop {
+        match crate::platform::file_lock::try_lock_once_nonblocking(&file) {
+            Ok(true) => {
+                return Some(PaneInputLockGuard { file: Some(file) });
+            }
+            Ok(false) => {}
+            Err(_) => {
+                emit_timeout_alarm(request, timeout, started.elapsed(), "lock_io");
+                return None;
+            }
+        }
+        let elapsed = started.elapsed();
+        if elapsed >= timeout {
+            emit_timeout_alarm(request, timeout, elapsed, "timeout");
+            return None;
+        }
+        std::thread::sleep(std::cmp::min(
+            Duration::from_millis(10),
+            timeout.saturating_sub(elapsed),
+        ));
+    }
+}
+
+fn pane_input_lock_path(workspace: &Path, target_key: &str) -> PathBuf {
+    let safe: String = target_key
+        .chars()
+        .map(|c| {
+            if c.is_ascii_alphanumeric() {
+                c
+            } else {
+                '_'
+            }
+        })
+        .collect();
+    runtime_dir(workspace)
+        .join(PANE_INPUT_LOCK_NAME)
+        .join(format!("{safe}.lock"))
+}
+
+fn emit_timeout_alarm(
+    request: &PaneInputLockRequest<'_>,
+    timeout: Duration,
+    waited: Duration,
+    reason: &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",
+        request.target_key,
+        request.operation,
+        waited.as_millis(),
+        timeout.as_millis()
+    );
+    if let Some(workspace) = request.workspace {
+        let _ = EventLog::new(workspace).write(
+            PANE_INPUT_LOCK_TIMEOUT_EVENT,
+            serde_json::json!({
+                "lock_name": PANE_INPUT_LOCK_NAME,
+                "target": request.target_key,
+                "operation": request.operation,
+                "waited_ms": waited.as_millis() as u64,
+                "timeout_ms": timeout.as_millis() as u64,
+                "reason": reason,
+                "disposition": "proceed",
+            }),
+        );
+    }
+}
+
+impl Drop for PaneInputLockGuard {
+    fn drop(&mut self) {
+        if let Some(file) = self.file.take() {
+            let _ = crate::platform::file_lock::unlock(&file);
+        }
+    }
+}