feat(bsk): harden browser file transfer transactions

crates/bsk-cli/src/cli/atomic_output.rs

@@ -0,0 +1,75 @@
+//! Atomic visibility boundary for files received into a same-directory temp.
+
+use std::path::Path;
+
+pub fn commit(temp: &Path, out: &Path, overwrite: bool) -> std::io::Result<()> {
+    if !overwrite {
+        std::fs::hard_link(temp, out)?;
+        std::fs::remove_file(temp)?;
+        return Ok(());
+    }
+    replace(temp, out)
+}
+
+#[cfg(unix)]
+fn replace(temp: &Path, out: &Path) -> std::io::Result<()> {
+    // POSIX rename replaces an existing non-directory destination atomically.
+    std::fs::rename(temp, out)
+}
+
+#[cfg(windows)]
+fn replace(temp: &Path, out: &Path) -> std::io::Result<()> {
+    use std::os::windows::ffi::OsStrExt;
+    use windows_sys::Win32::Storage::FileSystem::{
+        MOVEFILE_REPLACE_EXISTING, MOVEFILE_WRITE_THROUGH, MoveFileExW,
+    };
+
+    let from: Vec<u16> = temp.as_os_str().encode_wide().chain(Some(0)).collect();
+    let to: Vec<u16> = out.as_os_str().encode_wide().chain(Some(0)).collect();
+    // SAFETY: both buffers are NUL-terminated and remain alive for the call.
+    let ok = unsafe {
+        MoveFileExW(
+            from.as_ptr(),
+            to.as_ptr(),
+            MOVEFILE_REPLACE_EXISTING | MOVEFILE_WRITE_THROUGH,
+        )
+    };
+    if ok == 0 {
+        Err(std::io::Error::last_os_error())
+    } else {
+        Ok(())
+    }
+}
+
+#[cfg(not(any(unix, windows)))]
+fn replace(temp: &Path, out: &Path) -> std::io::Result<()> {
+    std::fs::rename(temp, out)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn no_replace_never_overwrites_existing_output() {
+        let dir = tempfile::tempdir().unwrap();
+        let temp = dir.path().join("new.part");
+        let out = dir.path().join("out.bin");
+        std::fs::write(&temp, b"new").unwrap();
+        std::fs::write(&out, b"old").unwrap();
+        assert!(commit(&temp, &out, false).is_err());
+        assert_eq!(std::fs::read(&out).unwrap(), b"old");
+    }
+
+    #[test]
+    fn overwrite_replaces_existing_output_without_predelete() {
+        let dir = tempfile::tempdir().unwrap();
+        let temp = dir.path().join("new.part");
+        let out = dir.path().join("out.bin");
+        std::fs::write(&temp, b"new").unwrap();
+        std::fs::write(&out, b"old").unwrap();
+        commit(&temp, &out, true).unwrap();
+        assert_eq!(std::fs::read(&out).unwrap(), b"new");
+        assert!(!temp.exists());
+    }
+}

crates/bsk-cli/src/cli/download.rs

@@ -15,6 +15,7 @@ use bsk_protocol::tools::{
 use clap::Args;
 use uuid::Uuid;
 
+use crate::cli::atomic_output;
 use crate::cli::ensure_daemon::ensure_daemon;
 use crate::cli::error::{CliError, Format};
 use crate::cli::interaction::split_target;
@@ -56,6 +57,7 @@ pub fn dispatch(args: DownloadArgs, format: Format) -> Result<(), CliError> {
         tab_id: args.tab_id,
         timeout_ms: Some(args.timeout),
         browser_relative_dir: None,
+        max_byte_size: None,
     };
     let reply: DownloadResult = crate::cli::business_rpc::call(
         info.sock_path.clone(),
@@ -130,22 +132,8 @@ fn write_transfer(sock: &Path, id: &str, out: &Path, overwrite: bool) -> Result<
         }
         file.sync_all().map_err(|e| CliError::Local(e.into()))?;
         drop(file);
-        if !overwrite {
-            std::fs::hard_link(&temp, out)
-                .with_context(|| format!("commit download without overwriting {}", out.display()))
-                .map_err(CliError::Local)?;
-            std::fs::remove_file(&temp)
-                .with_context(|| format!("remove temporary download {}", temp.display()))
-                .map_err(CliError::Local)?;
-            return Ok(());
-        }
-        if out.exists() {
-            std::fs::remove_file(out)
-                .with_context(|| format!("replace existing output {}", out.display()))
-                .map_err(CliError::Local)?;
-        }
-        std::fs::rename(&temp, out)
-            .with_context(|| format!("commit download to {}", out.display()))
+        atomic_output::commit(&temp, out, overwrite)
+            .with_context(|| format!("atomically commit download to {}", out.display()))
             .map_err(CliError::Local)
     })();
     if result.is_err() {

crates/bsk-cli/src/cli/mod.rs

@@ -2,6 +2,7 @@
 
 use std::time::Duration;
 
+mod atomic_output;
 pub mod browser_wait;
 pub mod browsers;
 pub mod business_rpc;

crates/bsk-cli/src/cli/render_error.rs

@@ -53,6 +53,8 @@ pub mod reason {
     pub const FILE_INPUT_NOT_ACTIVATED: &str = "file_input_not_activated";
     pub const SET_FILE_INPUT_FAILED: &str = "set_file_input_failed";
     pub const DOWNLOAD_CAPTURE_FAILED: &str = "download_capture_failed";
+    pub const TRANSFER_OUTCOME_UNKNOWN: &str = "transfer_outcome_unknown";
+    pub const TRANSFER_TIMEOUT: &str = "transfer_timeout";
     pub const SESSION_BUSY: &str = crate::rpc_reason::SESSION_BUSY;
     pub const RECORD_START_PAGE_UNREACHABLE: &str = "record_start_page_unreachable";
 }
@@ -201,6 +203,20 @@ pub fn info_for_error(code: ErrorCode, data: Option<&serde_json::Value>) -> Rend
         return base;
     };
     match (code, reason) {
+        (_, reason::TRANSFER_OUTCOME_UNKNOWN) => RenderInfo {
+            summary: "the file transfer outcome could not be confirmed",
+            hint: Some(
+                "do not retry the transfer: the browser may already have applied it; inspect the page or stop safely",
+            ),
+            exit_code: base.exit_code,
+        },
+        (ErrorCode::Timeout, reason::TRANSFER_TIMEOUT) => RenderInfo {
+            summary: "the file transfer timed out after browser dispatch",
+            hint: Some(
+                "do not retry when effect_state is unknown or committed; inspect the page before taking another action",
+            ),
+            exit_code: base.exit_code,
+        },
         (ErrorCode::PermissionDenied, reason::ELEMENT_NOT_VISIBLE) => RenderInfo {
             summary: "target element has no visible geometry",
             hint: Some(
@@ -474,6 +490,15 @@ mod tests {
         let download = serde_json::json!({ "reason": reason::DOWNLOAD_CAPTURE_FAILED });
         let info = info_for_error(ErrorCode::CdpFailed, Some(&download));
         assert!(info.summary.contains("download could not be attributed"));
+
+        let unknown = serde_json::json!({ "reason": reason::TRANSFER_OUTCOME_UNKNOWN });
+        let info = info_for_error(ErrorCode::ProtocolError, Some(&unknown));
+        assert!(info.summary.contains("outcome could not be confirmed"));
+        assert!(info.hint.unwrap().contains("do not retry"));
+
+        let timeout = serde_json::json!({ "reason": reason::TRANSFER_TIMEOUT });
+        let info = info_for_error(ErrorCode::Timeout, Some(&timeout));
+        assert!(info.summary.contains("timed out after browser dispatch"));
     }
 
     #[test]

crates/bsk-cli/src/cli/upload.rs

@@ -49,38 +49,43 @@ pub fn dispatch(args: UploadArgs, format: Format) -> Result<(), CliError> {
     let info = ensure_daemon().context("ensure daemon is running")?;
     let (ref_, selector) = split_target(args.target, args.ref_, args.selector)?;
     let mut staged = Vec::new();
-    let result = (|| {
-        for path in &args.files {
-            staged.push(stage_file(&info.sock_path, &args.session, path)?);
-        }
-        let params = UploadParams {
-            session_id: args.session,
-            ref_,
-            selector,
-            tab_id: args.tab_id,
-            files: staged
-                .iter()
-                .map(|(id, name)| UploadFile {
-                    transfer_id: id.clone(),
-                    name: name.clone(),
-                    staged_path: None,
-                })
-                .collect(),
-            timeout_ms: Some(args.timeout),
-        };
-        crate::cli::business_rpc::call::<_, UploadResult>(
-            info.sock_path.clone(),
-            "upload",
-            Method::ToolUpload,
-            Some(params),
-            ipc_timeout(args.timeout),
-        )
-    })();
-    if result.is_err() {
-        for (id, _) in &staged {
-            let _ = release(&info.sock_path, id);
+    for path in &args.files {
+        match stage_file(&info.sock_path, &args.session, path) {
+            Ok(file) => staged.push(file),
+            Err(err) => {
+                for (id, _) in &staged {
+                    let _ = release(&info.sock_path, id);
+                }
+                return Err(err);
+            }
         }
     }
+    let params = UploadParams {
+        session_id: args.session,
+        ref_,
+        selector,
+        tab_id: args.tab_id,
+        files: staged
+            .iter()
+            .map(|(id, name)| UploadFile {
+                transfer_id: id.clone(),
+                name: name.clone(),
+                staged_path: None,
+            })
+            .collect(),
+        timeout_ms: Some(args.timeout),
+    };
+    let result = crate::cli::business_rpc::call::<_, UploadResult>(
+        info.sock_path.clone(),
+        "upload",
+        Method::ToolUpload,
+        Some(params),
+        ipc_timeout(args.timeout),
+    );
+    // Once tool.upload is dispatched, staging ownership belongs to the
+    // session. A transport timeout cannot prove that Chrome did not attach
+    // the file, so releasing here could invalidate a late successful attach.
+    // Session teardown remains the single cleanup boundary after dispatch.
     let reply = result?;
     match format {
         Format::Json => println!("{}", serde_json::to_string_pretty(&reply).unwrap()),