@team-agent/installer 0.5.2 → 0.5.3

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

@@ -559,25 +559,17 @@ pub(super) fn drain_old_pane_and_pid(
     })
 }
 
-/// Best-effort liveness probe for a pid. Returns true if the pid exists
-/// on Unix (signal 0). On other platforms, returns true conservatively.
+/// Best-effort liveness probe for a pid.
+///
+/// 0.5.x Windows portability Batch 3: routes through
+/// `crate::platform::process::pid_is_alive`. Unix uses `kill(pid, 0)`
+/// with the `EPERM = Live` branch preserved byte-for-byte; Windows
+/// uses `OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION)` +
+/// `GetExitCodeProcess` (STILL_ACTIVE = Live). The legacy non-Unix
+/// `true` fallback (which broke drain by reporting every pid alive)
+/// is gone.
 pub(super) fn pid_is_alive(pid: u32) -> bool {
-    #[cfg(unix)]
-    {
-        // SAFETY: kill(pid, 0) checks if pid exists without sending a signal.
-        let ret = unsafe { libc::kill(pid as i32, 0) };
-        if ret == 0 {
-            return true;
-        }
-        // EPERM also means the process exists (we just can't signal it).
-        let err = std::io::Error::last_os_error();
-        matches!(err.raw_os_error(), Some(libc::EPERM))
-    }
-    #[cfg(not(unix))]
-    {
-        let _ = pid;
-        true
-    }
+    crate::platform::process::pid_is_alive(pid)
 }
 
 /// Read state.agents[agent_id].pane_pid (u32) from the runtime state.

package/crates/team-agent/src/lifecycle/tests/agent_ops.rs

@@ -287,6 +287,7 @@ impl Drop for EnvVarGuard {
     }
 }
 
+#[cfg(unix)]
 struct TmuxShim {
     log: std::path::PathBuf,
     _path: EnvVarGuard,
@@ -297,6 +298,7 @@ struct TmuxShim {
     _real_tmux: EnvVarGuard,
 }
 
+#[cfg(unix)]
 fn install_e27_tmux_shim(expected_endpoint: &str, session_name: &str) -> TmuxShim {
     use std::os::unix::fs::PermissionsExt;
 
@@ -441,6 +443,9 @@ fn assert_only_expected_socket_used(log: &std::path::Path, expected_endpoint: &s
     }
 }
 
+// 0.5.x Windows portability Batch 5: E27 tests use a shell-script
+// tmux shim + Unix socket paths. Unix-only.
+#[cfg(unix)]
 #[test]
 #[serial_test::serial(env)]
 fn e27_stop_agent_uses_attached_explicit_state_socket() {
@@ -461,6 +466,7 @@ fn e27_stop_agent_uses_attached_explicit_state_socket() {
     );
 }
 
+#[cfg(unix)]
 #[test]
 #[serial_test::serial(env)]
 fn e27_reset_agent_uses_attached_explicit_state_socket_for_stop_and_spawn() {
@@ -491,6 +497,7 @@ fn e27_reset_agent_uses_attached_explicit_state_socket_for_stop_and_spawn() {
     );
 }
 
+#[cfg(unix)]
 #[test]
 #[serial_test::serial(env)]
 fn e27_stop_agent_expands_short_state_socket_name() {

package/crates/team-agent/src/mcp_server/wire.rs

@@ -314,14 +314,13 @@ fn non_empty_env(key: &str) -> Option<String> {
         .filter(|value| !value.is_empty())
 }
 
-#[cfg(unix)]
+// 0.5.x Windows portability Batch 3: parent-pid probe routes through
+// `crate::platform::process::current_parent_pid`. Unix uses
+// `libc::getppid`; Windows uses Toolhelp32Snapshot. Both return
+// `Option<u32>`; the legacy `0` fallback (which would have silently
+// degraded MCP metadata + orphan detection on Windows) is gone.
 fn parent_pid() -> u32 {
-    u32::try_from(unsafe { libc::getppid() }).unwrap_or(0)
-}
-
-#[cfg(not(unix))]
-fn parent_pid() -> u32 {
-    0
+    crate::platform::process::current_parent_pid().unwrap_or(0)
 }
 
 fn error_response_value(id: RpcId, code: i64, message: String) -> Value {

package/crates/team-agent/src/messaging/tests/runtime.rs

@@ -1932,6 +1932,9 @@ fn app_server_state(
     })
 }
 
+// 0.5.x Windows portability Batch 5: FakeAppServer uses Unix domain
+// sockets — Unix-only.
+#[cfg(unix)]
 #[test]
 fn app_server_leader_delivery_marks_delivered_without_tmux_transport() {
     let ws = tmp_ws("appdeliver");
@@ -1984,6 +1987,7 @@ fn app_server_leader_delivery_marks_delivered_without_tmux_transport() {
     );
 }
 
+#[cfg(unix)]
 #[test]
 fn app_server_leader_delivery_stale_tuple_fails_closed_with_event() {
     let ws = tmp_ws("appstale");
@@ -2076,6 +2080,7 @@ fn app_server_leader_delivery_fails_closed_on_mode_transport_conflict() {
     );
 }
 
+#[cfg(unix)]
 #[test]
 fn app_server_leader_busy_is_retryable_and_does_not_steer() {
     let ws = tmp_ws("appbusy");

package/crates/team-agent/src/packaging/tests.rs

@@ -222,12 +222,47 @@ fn linux_aarch64_is_native() {
 }
 
 #[test]
-fn windows_x8664_is_native_per_transport_design() {
-    // skeleton:203/211 — Windows 原生一等 (WezTerm/ConPTY,非 tmux)。
-    // 不是 Unsupported,不是 RequiresWslTmux — 是 Native.
-    assert_eq!(
-        platform_support(ReleaseTarget::WindowsX8664),
-        PlatformSupport::Native
+fn windows_x8664_is_preview_compile_only_during_batch_0_to_5() {
+    // 0.5.x Windows portability CR C-1 (P0):
+    // Windows previously claimed `PlatformSupport::Native` but
+    // `cargo check --target x86_64-pc-windows-msvc` was RED — the
+    // Unix-only `std::os::unix` / `libc::pid_t` calls in
+    // tmux_backend/coordinator/lifecycle/packaging never compiled on
+    // Windows. Claiming Native was a MUST-NOT-13 假绿承诺 (user
+    // installs and immediately hits build failures).
+    //
+    // This test locks the honest downgrade in place until Batch 6/7
+    // real-machine gates pass. Promoting Windows back to `Native`
+    // requires:
+    //   1. Batch 6 fake-provider smoke on the SSH host (design §Batch 6)
+    //   2. Batch 7 real-machine subscription serial (CR §C-5)
+    // Both flip this test to `assert PlatformSupport::Native` in a
+    // deliberate PR — no silent regen.
+    //
+    // Truth source: `.team/artifacts/0.5.x-windows-portability-cr-verdict.md` §C-1.
+    match platform_support(ReleaseTarget::WindowsX8664) {
+        PlatformSupport::PreviewCompileOnly { preview_gate, note } => {
+            assert_eq!(preview_gate, "compile_gate");
+            assert!(note.contains("compile_gate") || note.contains("cargo check"));
+        }
+        other => panic!(
+            "Windows must stay `PreviewCompileOnly` while the compile gate is RED; \
+             promoting back to `Native` requires Batch 6 + Batch 7 real-machine gates. \
+             Got {other:?}"
+        ),
+    }
+}
+
+#[test]
+fn windows_x8664_is_not_native_yet_c1_hard_lock() {
+    // Belt-and-braces companion for the above — a distinct assertion
+    // that fires clearly if a future refactor of `PlatformSupport`
+    // changes variant names.
+    let support = platform_support(ReleaseTarget::WindowsX8664);
+    assert_ne!(
+        support,
+        PlatformSupport::Native,
+        "CR C-1: Windows must NOT be Native until Batch 6/7 gates pass"
     );
 }
 

package/crates/team-agent/src/packaging/types.rs

@@ -162,13 +162,27 @@ pub enum ReleaseTarget {
 }
 
 /// 平台支持等级(§8:如实声明,不假装兼容)。
+///
+/// 0.5.x Windows portability CR C-1 (P0) 引入 `PreviewCompileOnly`:
+/// Windows 目前 `cargo check --target x86_64-pc-windows-msvc` **仍红**
+/// (三处 non-Unix fallback + platform 层未接入 + Batch 1-4 未完成);
+/// 保持 `Native` 会构成 MUST-NOT-13 假绿承诺 → 用户装 Windows 二进制
+/// 会真报错。降级为 `PreviewCompileOnly` 明示"当前 Windows 尚未通过
+/// 编译门,Batch 6/7 真机订阅测通过前不承诺 Native"。
+/// Truth source: `.team/artifacts/0.5.x-windows-portability-cr-verdict.md` §C-1。
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case", tag = "level")]
 pub enum PlatformSupport {
-    /// 原生一等(macOS/Linux tmux;Windows WezTerm/ConPTY,见 transport-backend-design.md)。
+    /// 原生一等(macOS/Linux tmux)。
     Native,
     /// 需 WSL + tmux backend(显式标要求,不假装原生)。
     RequiresWslTmux { note: String },
+    /// Windows 移植进行中,`cargo check` 仍红或 Batch 6/7 真机订阅测未过。
+    /// 用户不应期待可运行的 `.exe`;`preview_gate` 字段说明当前挡位
+    /// (`compile_gate` = Batch 0-4 编译门,`fake_provider_smoke` = Batch 6,
+    /// `subscription_realmachine` = Batch 7)。
+    /// 该档位不承诺可用,仅承诺"正在移植 + 每 Batch 有 CI 编译门追踪"。
+    PreviewCompileOnly { preview_gate: String, note: String },
     /// 当前 release 矩阵不覆盖。
     Unsupported { reason: String },
 }
@@ -179,8 +193,22 @@ pub fn platform_support(target: ReleaseTarget) -> PlatformSupport {
         ReleaseTarget::MacosAarch64
         | ReleaseTarget::MacosX8664
         | ReleaseTarget::LinuxX8664
-        | ReleaseTarget::LinuxAarch64
-        | ReleaseTarget::WindowsX8664 => PlatformSupport::Native,
+        | ReleaseTarget::LinuxAarch64 => PlatformSupport::Native,
+        // 0.5.x Windows portability CR C-1 (P0):
+        // `cargo check --target x86_64-pc-windows-msvc` 是当前挡位;
+        // Batch 6 fake-provider smoke + Batch 7 真机订阅测通过后
+        // 才升回 `Native`。历史 tag 期间 Windows 曾声明为 Native 但
+        // 从未通过编译门,构成 MUST-NOT-13 假绿承诺 → 本 batch 降级。
+        ReleaseTarget::WindowsX8664 => PlatformSupport::PreviewCompileOnly {
+            preview_gate: "compile_gate".to_string(),
+            note: "Windows native port in progress; `cargo check --target x86_64-pc-windows-msvc` \
+                   is the current gate. See \
+                   `.team/artifacts/0.5.x-windows-portability-survey-design.md` §Batch 0-6 \
+                   and CR verdict §C-1 for burn-down status. Promote back to `Native` only \
+                   after Batch 6 (fake-provider smoke) + Batch 7 (subscription real-machine) \
+                   pass on the SSH host."
+                .to_string(),
+        },
     }
 }
 

package/crates/team-agent/src/platform/argv.rs

@@ -0,0 +1,324 @@
+//! Process argv / environ probe.
+//!
+//! ## Batch 4 real implementation (leader msg_0689a63a9e40)
+//!
+//! Batch 4 promotes this module from a Batch 0 signature-only
+//! scaffold to a **byte-preserving migration** of the process ancestry
+//! + argv/env probes used by:
+//!
+//! - `lifecycle/launch.rs::process_ancestry_argv` +
+//!   `process_argv_tokens` + `process_parent_pid` — the
+//!   `dangerous_auto_approve` inheritance chain (0.5.0 caller-identity
+//!   钉输入 is exactly this test surface).
+//! - `leader/provider_attribution.rs::process_command_line` +
+//!   `process_environment` — leader provider attribution.
+//!
+//! ## Platform matrix
+//!
+//! - **Linux**: `/proc/<pid>/cmdline` (NUL-separated argv) and
+//!   `/proc/<pid>/environ` (NUL-separated KEY=VALUE).
+//! - **macOS**: `sysctl(KERN_PROCARGS2)` for argv; environ not
+//!   currently probed (matches the pre-batch behavior).
+//! - **non-Linux non-macOS Unix**: `ps -p <pid> -o command=` for argv.
+//! - **Windows**: `NtQueryInformationProcess` + PEB is intrusive; for
+//!   Batch 4 we return `None` for both `argv_tokens` and
+//!   `environ_text` (design §Batch 4 Verification anchor: "unknown
+//!   argv must never infer elevated approval; keep worker permission
+//!   at provider default or require explicit user consent"). This is
+//!   the honest "we don't know" branch — callers already treat
+//!   `None` as "no elevation inherited", so Windows leaders default
+//!   to safe (non-dangerous) approval mode.
+//!
+//! ## CR C-3 anchor
+//!
+//! The `Option::None` return on Windows deliberately keeps worker
+//! permission at provider default. Design §Batch 4 Verification: "the
+//! safe direction is to avoid elevation, not to assume bypass" —
+//! `detect_dangerous_approval` in `lifecycle/launch.rs` already
+//! iterates `process_ancestry_argv(...)` and defaults to
+//! `disabled_dangerous_approval()` when it finds no matching flag,
+//! so a Windows probe returning `None` on every step lands on the
+//! same disabled default. **This is intentional**: leaking a
+//! bypass via unknown argv would be a MUST-NOT-13 假绿 failure.
+
+/// Return the argv tokens for `pid`, or `None` if unavailable on
+/// this platform.
+///
+/// - Linux: `/proc/<pid>/cmdline` NUL-separated (byte-preserving
+///   migration of `lifecycle/launch.rs:3648-3656`).
+/// - macOS: `sysctl(KERN_PROCARGS2)` (migration of
+///   `lifecycle/launch.rs:3659-3711`).
+/// - Other Unix: `ps -p <pid> -o command=` split on whitespace
+///   (migration of `lifecycle/launch.rs:3714-3729`).
+/// - Windows: `None` (design §Batch 4 conservative fallback — never
+///   infer elevated approval from unknown argv).
+pub fn argv_tokens(pid: u32) -> Option<Vec<String>> {
+    #[cfg(target_os = "linux")]
+    {
+        argv_tokens_linux(pid)
+    }
+    #[cfg(target_os = "macos")]
+    {
+        argv_tokens_macos(pid)
+    }
+    #[cfg(all(unix, not(any(target_os = "linux", target_os = "macos"))))]
+    {
+        argv_tokens_ps_fallback(pid)
+    }
+    #[cfg(windows)]
+    {
+        let _ = pid;
+        None
+    }
+}
+
+/// Return the environ text (NUL-joined) for `pid`, or `None`.
+///
+/// - Linux: `/proc/<pid>/environ` verbatim (migration of
+///   `leader/provider_attribution.rs:113-115`).
+/// - Other platforms: `None` (matches the pre-batch
+///   `#[cfg(not(target_os="linux"))]` stub in
+///   `leader/provider_attribution.rs:135-139`).
+pub fn environ_text(pid: u32) -> Option<String> {
+    #[cfg(target_os = "linux")]
+    {
+        environ_text_linux(pid)
+    }
+    #[cfg(not(target_os = "linux"))]
+    {
+        let _ = pid;
+        None
+    }
+}
+
+/// Return the parent PID of `pid`, or `None` if unavailable.
+///
+/// Byte-preserving migration of `lifecycle/launch.rs::process_parent_pid`:
+/// - Unix: `ps -p <pid> -o ppid=` parsed as u32.
+/// - Windows: Toolhelp32 snapshot walked for the entry matching
+///   `pid`. Same technique as `platform::process::current_parent_pid`.
+pub fn parent_pid(pid: u32) -> Option<u32> {
+    #[cfg(unix)]
+    {
+        parent_pid_unix(pid)
+    }
+    #[cfg(windows)]
+    {
+        parent_pid_windows(pid)
+    }
+    #[cfg(not(any(unix, windows)))]
+    {
+        let _ = pid;
+        None
+    }
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Linux implementation.
+// ─────────────────────────────────────────────────────────────────────
+
+#[cfg(target_os = "linux")]
+fn argv_tokens_linux(pid: u32) -> Option<Vec<String>> {
+    let bytes = std::fs::read(format!("/proc/{pid}/cmdline")).ok()?;
+    let argv_tokens = String::from_utf8_lossy(&bytes)
+        .split('\0')
+        .filter(|token| !token.is_empty())
+        .map(str::to_string)
+        .collect::<Vec<_>>();
+    (!argv_tokens.is_empty()).then_some(argv_tokens)
+}
+
+#[cfg(target_os = "linux")]
+fn environ_text_linux(pid: u32) -> Option<String> {
+    String::from_utf8(std::fs::read(format!("/proc/{pid}/environ")).ok()?).ok()
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// macOS implementation.
+// ─────────────────────────────────────────────────────────────────────
+
+#[cfg(target_os = "macos")]
+fn argv_tokens_macos(pid: u32) -> Option<Vec<String>> {
+    use std::mem::size_of;
+    let mut mib = [
+        libc::CTL_KERN,
+        libc::KERN_PROCARGS2,
+        i32::try_from(pid).ok()?,
+    ];
+    let mut size = 0usize;
+    let rc = unsafe {
+        libc::sysctl(
+            mib.as_mut_ptr(),
+            mib.len() as u32,
+            std::ptr::null_mut(),
+            &mut size,
+            std::ptr::null_mut(),
+            0,
+        )
+    };
+    if rc != 0 || size <= size_of::<libc::c_int>() {
+        return None;
+    }
+    let mut buf = vec![0u8; size];
+    let rc = unsafe {
+        libc::sysctl(
+            mib.as_mut_ptr(),
+            mib.len() as u32,
+            buf.as_mut_ptr().cast(),
+            &mut size,
+            std::ptr::null_mut(),
+            0,
+        )
+    };
+    if rc != 0 || size <= size_of::<libc::c_int>() {
+        return None;
+    }
+    let argc = i32::from_ne_bytes(buf.get(..size_of::<libc::c_int>())?.try_into().ok()?) as usize;
+    let mut offset = size_of::<libc::c_int>();
+    while offset < size && buf[offset] != 0 {
+        offset += 1;
+    }
+    while offset < size && buf[offset] == 0 {
+        offset += 1;
+    }
+    let raw = String::from_utf8_lossy(&buf[offset..size]);
+    let argv_tokens = raw
+        .split('\0')
+        .filter(|token| !token.is_empty())
+        .take(argc)
+        .map(str::to_string)
+        .collect::<Vec<_>>();
+    (!argv_tokens.is_empty()).then_some(argv_tokens)
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Generic Unix fallback (`ps -p <pid> -o ...`).
+// ─────────────────────────────────────────────────────────────────────
+
+#[cfg(all(unix, not(any(target_os = "linux", target_os = "macos"))))]
+fn argv_tokens_ps_fallback(pid: u32) -> Option<Vec<String>> {
+    let output = std::process::Command::new("ps")
+        .args(["-p", &pid.to_string(), "-o", "command="])
+        .output()
+        .ok()?;
+    if !output.status.success() {
+        return None;
+    }
+    let text = String::from_utf8_lossy(&output.stdout);
+    let argv_tokens = text
+        .split_whitespace()
+        .filter(|token| !token.is_empty())
+        .map(str::to_string)
+        .collect::<Vec<_>>();
+    (!argv_tokens.is_empty()).then_some(argv_tokens)
+}
+
+#[cfg(unix)]
+fn parent_pid_unix(pid: u32) -> Option<u32> {
+    let output = std::process::Command::new("ps")
+        .args(["-p", &pid.to_string(), "-o", "ppid="])
+        .output()
+        .ok()?;
+    if !output.status.success() {
+        return None;
+    }
+    String::from_utf8_lossy(&output.stdout)
+        .trim()
+        .parse::<u32>()
+        .ok()
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Windows implementation.
+// ─────────────────────────────────────────────────────────────────────
+
+#[cfg(windows)]
+fn parent_pid_windows(pid: u32) -> Option<u32> {
+    use windows::Win32::System::Diagnostics::ToolHelp::{
+        CreateToolhelp32Snapshot, Process32FirstW, Process32NextW, PROCESSENTRY32W,
+        TH32CS_SNAPPROCESS,
+    };
+    let snapshot = unsafe { CreateToolhelp32Snapshot(TH32CS_SNAPPROCESS, 0) }.ok()?;
+    let mut entry = PROCESSENTRY32W {
+        dwSize: std::mem::size_of::<PROCESSENTRY32W>() as u32,
+        ..Default::default()
+    };
+    let mut result = unsafe { Process32FirstW(snapshot, &mut entry) };
+    while result.is_ok() {
+        if entry.th32ProcessID == pid {
+            let ppid = entry.th32ParentProcessID;
+            unsafe {
+                let _ = windows::Win32::Foundation::CloseHandle(snapshot);
+            }
+            return Some(ppid);
+        }
+        result = unsafe { Process32NextW(snapshot, &mut entry) };
+    }
+    unsafe {
+        let _ = windows::Win32::Foundation::CloseHandle(snapshot);
+    }
+    None
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// Tests.
+// ─────────────────────────────────────────────────────────────────────
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn argv_tokens_returns_some_for_own_pid_on_unix_or_none_on_windows() {
+        // Byte-preserving migration of the ancestry probe. On Unix
+        // this must return a non-empty argv for our own process (test
+        // binary). On Windows the honest `None` return is intentional:
+        // callers see the "no elevation inherited" default branch,
+        // which is safer than reading unknown argv (CR C-3 anchor).
+        let my = std::process::id();
+        let argv = argv_tokens(my);
+        #[cfg(unix)]
+        {
+            let argv = argv.expect("unix must return Some argv for own pid");
+            assert!(!argv.is_empty());
+            // At least argv[0] should look like a test binary path.
+            let argv0 = &argv[0];
+            assert!(!argv0.is_empty());
+        }
+        #[cfg(windows)]
+        {
+            // Windows conservative fallback: None, so
+            // `detect_dangerous_approval` defaults to disabled.
+            assert!(argv.is_none());
+        }
+    }
+
+    #[test]
+    fn parent_pid_returns_some_on_both_platforms() {
+        // Batch 4: parent_pid via `ps -o ppid=` (unix) or Toolhelp32
+        // (windows) — both must resolve our own ppid.
+        let my = std::process::id();
+        let ppid = parent_pid(my);
+        assert!(ppid.is_some(), "parent_pid must resolve own pid on both unix and windows");
+        assert!(ppid.unwrap() > 0);
+    }
+
+    #[test]
+    fn environ_text_linux_only_returns_something_for_own_pid() {
+        // The environ probe is Linux-only by design (matches
+        // `leader/provider_attribution.rs:113-115`). Other platforms
+        // honestly return None; callers already treat that as
+        // "no env-based attribution".
+        let my = std::process::id();
+        let env = environ_text(my);
+        #[cfg(target_os = "linux")]
+        {
+            let env = env.expect("linux must return Some environ");
+            assert!(env.contains('='));
+        }
+        #[cfg(not(target_os = "linux"))]
+        {
+            assert!(env.is_none());
+        }
+    }
+}

package/crates/team-agent/src/platform/errors.rs

@@ -0,0 +1,95 @@
+//! Retryable OS error classifier + human-readable os_error_name.
+//!
+//! Batch 0 signature only. Batch 2 migrates the raw
+//! `libc::{EACCES, EPERM, EBUSY, ENOSPC}` matching in
+//! `state/persist.rs::retryable_replace_error` onto these helpers so
+//! Windows sees the same classification via
+//! `io::ErrorKind` + raw-code mapping.
+
+use std::io;
+
+/// True when the OS error is a transient replace failure worth
+/// retrying (EACCES on Windows during antivirus scan, EBUSY on
+/// mounted filesystems, etc.). Batch 2 wires the callsite.
+#[allow(dead_code)]
+pub fn retryable_replace_error(error: &io::Error) -> bool {
+    // Batch 2 will migrate `state/persist.rs::retryable_replace_error`
+    // here. Batch 0 provides the signature only.
+    #[cfg(unix)]
+    {
+        matches!(
+            error.raw_os_error(),
+            Some(c)
+                if c == libc::EACCES
+                    || c == libc::EPERM
+                    || c == libc::EBUSY
+                    || c == libc::ENOSPC
+        )
+    }
+    #[cfg(not(unix))]
+    {
+        // Windows: retryable on sharing violation / access denied
+        // during antivirus scans. Map by `io::ErrorKind` so we don't
+        // depend on `windows-sys` raw codes at this layer.
+        matches!(
+            error.kind(),
+            io::ErrorKind::PermissionDenied | io::ErrorKind::WouldBlock
+        )
+    }
+}
+
+/// Human-readable name for a raw OS error code — used in diagnostics
+/// so operators see `EACCES` instead of `13`.
+#[allow(dead_code)]
+pub fn os_error_name(error: &io::Error) -> Option<&'static str> {
+    #[cfg(unix)]
+    {
+        match error.raw_os_error()? {
+            c if c == libc::EACCES => Some("EACCES"),
+            c if c == libc::EPERM => Some("EPERM"),
+            c if c == libc::EBUSY => Some("EBUSY"),
+            c if c == libc::ENOSPC => Some("ENOSPC"),
+            c if c == libc::EWOULDBLOCK => Some("EWOULDBLOCK"),
+            c if c == libc::ESRCH => Some("ESRCH"),
+            _ => None,
+        }
+    }
+    #[cfg(not(unix))]
+    {
+        // Batch 2 will map ERROR_ACCESS_DENIED / ERROR_SHARING_VIOLATION
+        // / ERROR_LOCK_VIOLATION here. Batch 0 leaves the mapping to
+        // `io::Error::kind()`.
+        let _ = error;
+        None
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn retryable_replace_error_matches_eacces_on_unix() {
+        #[cfg(unix)]
+        {
+            let err = io::Error::from_raw_os_error(libc::EACCES);
+            assert!(retryable_replace_error(&err));
+        }
+    }
+
+    #[test]
+    fn retryable_replace_error_rejects_random_error() {
+        // A generic "not found" is not a replace-race condition.
+        let err = io::Error::from(io::ErrorKind::NotFound);
+        assert!(!retryable_replace_error(&err));
+    }
+
+    #[test]
+    fn os_error_name_returns_stable_wire_string_on_unix() {
+        #[cfg(unix)]
+        {
+            let err = io::Error::from_raw_os_error(libc::EACCES);
+            assert_eq!(os_error_name(&err), Some("EACCES"));
+        }
+    }
+}