fix(ffi): guard unix sigpipe and add windows pipe/file detect regression

Author: Sakuzy

.github/workflows/windows-winui.yml

@@ -435,6 +435,36 @@ jobs:
       - name: Build CLI core (release, full-cli)
         run: cargo build --bin awmkit-core --features full-cli --release --target x86_64-pc-windows-msvc
 
+      - name: Windows pipe/file detect regression
+        shell: pwsh
+        run: |
+          $coreExe = "target/x86_64-pc-windows-msvc/release/awmkit-core.exe"
+          if (-not (Test-Path $coreExe)) {
+            throw "CLI core binary not found: $coreExe"
+          }
+
+          $ffmpegRuntime = (Resolve-Path "ffmpeg-dist/lib").Path
+          if (-not (Test-Path $ffmpegRuntime)) {
+            throw "Missing FFmpeg runtime directory: $ffmpegRuntime"
+          }
+          $env:PATH = "$ffmpegRuntime;$env:PATH"
+
+          foreach ($input in @("test-audio/sample_wm.wav", "test-audio/multichannel_sample_wm.wav")) {
+            & $coreExe detect $input
+            if ($LASTEXITCODE -ne 0) {
+              throw "Default detect failed for $input (exit=$LASTEXITCODE)"
+            }
+          }
+
+          $env:AWMKIT_DISABLE_PIPE_IO = "1"
+          foreach ($input in @("test-audio/sample_wm.wav", "test-audio/multichannel_sample_wm.wav")) {
+            & $coreExe detect $input
+            if ($LASTEXITCODE -ne 0) {
+              throw "File-mode detect failed for $input (exit=$LASTEXITCODE)"
+            }
+          }
+          Remove-Item Env:AWMKIT_DISABLE_PIPE_IO -ErrorAction SilentlyContinue
+
       - name: Build FFI cdylib (release)
         run: cargo build --lib --features ffi,app,bundled --release --target x86_64-pc-windows-msvc
 

Cargo.lock

@@ -200,6 +200,9 @@ members = ["."]
 [target.'cfg(windows)'.dependencies.windows-dpapi]
 version = "0.1"
 
+[target.'cfg(unix)'.dependencies]
+libc = "0.2"
+
 [dependencies.dirs]
 version = "5.0"
 optional = true

Cargo.toml

@@ -56,6 +56,7 @@ Fix:
 ## 7. Pipe I/O Compatibility (`stdin/stdout`)
 
 Note: runtime now prefers `audiowmark` pipe I/O (`-` as input/output). If the local `audiowmark` build does not support this mode, AWMKit automatically falls back to file I/O.
+In recent builds, Unix `SIGPIPE` is guarded in the FFI path (Swift/ObjC/.NET), so pipe write failures are converted to normal errors and fallback can proceed instead of crashing the host process.
 
 Force-disable pipe mode for troubleshooting:
 
@@ -66,3 +67,4 @@ Recommended checks:
 
 1. Run `awmkit status --doctor` to confirm the active `audiowmark` binary and version.
 2. If failures disappear when pipe mode is disabled, upgrade or replace the `audiowmark` binary first.
+3. `AWMKIT_DISABLE_PIPE_IO=1` changes only the transport strategy, not watermark business semantics.

docs/en-US/troubleshooting/common-issues.md

@@ -56,6 +56,7 @@
 ## 7. 管道 I/O 兼容问题（`stdin/stdout`）
 
 说明：当前默认优先使用 `audiowmark` 管道 I/O（`-` 作为输入/输出）。若本地 `audiowmark` 构建不支持该模式，运行时会自动回退到文件 I/O。  
+在新版中，FFI（Swift/ObjC/.NET）主链已对 Unix `SIGPIPE` 做了防护，管道写入失败会转为普通错误并进入回退，而不是导致宿主进程直接闪退。
 
 手动强制关闭管道模式（便于排查）：
 
@@ -66,3 +67,4 @@
 
 1. 先执行 `awmkit status --doctor` 确认当前 `audiowmark` 来源和版本。
 2. 若出现异常且关闭 pipe 后恢复，优先升级/替换 `audiowmark` 二进制。
+3. `AWMKIT_DISABLE_PIPE_IO=1` 只改变 I/O 通道策略，不改变水印业务语义。

docs/zh-CN/troubleshooting/common-issues.md

@@ -80,6 +80,21 @@ const fn u8_to_c_char(byte: u8) -> c_char {
     i8::from_ne_bytes([byte])
 }
 
+#[cfg(unix)]
+fn ensure_sigpipe_ignored_once() {
+    static ONCE: std::sync::Once = std::sync::Once::new();
+    ONCE.call_once(|| {
+        // FFI host process (Swift/ObjC/.NET) should never be terminated by SIGPIPE.
+        // Convert broken pipe to regular EPIPE so Rust fallback logic can run.
+        unsafe {
+            libc::signal(libc::SIGPIPE, libc::SIG_IGN);
+        }
+    });
+}
+
+#[cfg(not(unix))]
+fn ensure_sigpipe_ignored_once() {}
+
 /// Write UTF-8 string into C buffer with two-step size negotiation.
 ///
 /// # Safety
@@ -520,6 +535,7 @@ impl AWMEmbedEvidenceResult {
 /// 返回的指针需要通过 `awm_audio_free` 释放
 #[no_mangle]
 pub extern "C" fn awm_audio_new() -> *mut AWMAudioHandle {
+    ensure_sigpipe_ignored_once();
     match Audio::new() {
         Ok(audio) => Box::into_raw(Box::new(AWMAudioHandle { inner: audio })),
         Err(_) => ptr::null_mut(),
@@ -535,6 +551,7 @@ pub extern "C" fn awm_audio_new() -> *mut AWMAudioHandle {
 pub unsafe extern "C" fn awm_audio_new_with_binary(
     binary_path: *const c_char,
 ) -> *mut AWMAudioHandle {
+    ensure_sigpipe_ignored_once();
     if binary_path.is_null() {
         return ptr::null_mut();
     }
@@ -2150,3 +2167,14 @@ pub const extern "C" fn awm_channel_layout_channels(layout: AWMChannelLayout) ->
         AWMChannelLayout::Auto => 0,
     }
 }
+
+#[cfg(all(test, unix))]
+mod tests {
+    use super::ensure_sigpipe_ignored_once;
+
+    #[test]
+    fn test_ensure_sigpipe_ignored_once_is_idempotent() {
+        ensure_sigpipe_ignored_once();
+        ensure_sigpipe_ignored_once();
+    }
+}