fix: add SIGINT signal handler for reliable Ctrl+C experiment abort (#1504)

* fix: add SIGINT signal handler for reliable Ctrl+C experiment abort

sys.excepthook alone cannot reliably catch KeyboardInterrupt when the
main thread is blocked in C extensions (NumPy/PyTorch). Register a
signal.SIGINT handler as an additional safety net to ensure experiments
are always marked as "aborted" on Ctrl+C.

Fixes #1329

* fix: correct SIGINT handler chaining for SIG_IGN case

When the original handler was SIG_IGN, the handler incorrectly raised
KeyboardInterrupt instead of silently returning. Simplify the logic to
explicitly handle SIG_IGN, callable handlers, and SIG_DFL separately.
Add test for SIG_IGN scenario.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Call saved original excepthook and update tests

Invoke the saved original excepthook (self._sys_origin_excepthook) instead of directly calling sys.__excepthook__, and make the KeyboardInterrupt log message clearer ("aborting run..."). Update unit tests to set and assert against the saved hook, rename tests for clarity, and add coverage to ensure an outer framework's hook is used (and the builtin is not called) as well as that internal errors still result in calling the saved hook.

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Kang Li <79990647+SAKURA-CAT@users.noreply.github.com>

Author: 3 people

swanlab/sdk/internal/run/__init__.py

@@ -9,6 +9,7 @@
 """
 
 import atexit
+import signal
 import sys
 import threading
 import traceback
@@ -145,6 +146,10 @@ def __init__(self, ctx: RunContext):
         self._sys_origin_excepthook = sys.excepthook
         atexit.register(self._atexit_cleanup)
         sys.excepthook = self._excepthook
+        # 注册 SIGINT handler，确保 Ctrl+C 能可靠地将实验标记为 aborted
+        # sys.excepthook 在主线程阻塞于 C 扩展时可能无法触发
+        self._original_sigint_handler = signal.getsignal(signal.SIGINT)
+        signal.signal(signal.SIGINT, self._sigint_handler)
         # 绑定日志文件，运行正式开始
         if self._ctx.config.settings.mode != "disabled":
             log.bindfile(self._ctx.debug_dir)
@@ -153,6 +158,26 @@ def __init__(self, ctx: RunContext):
     # 私有钩子
     # ----------------------------------
 
+    def _sigint_handler(self, signum: int, frame: Any) -> None:
+        """SIGINT handler：确保 Ctrl+C 能可靠地将实验标记为 aborted。
+
+        sys.excepthook 依赖 Python 层面抛出 KeyboardInterrupt，但当主线程
+        阻塞在 C 扩展（NumPy/PyTorch 等）时，KeyboardInterrupt 可能无法
+        正常传播到 excepthook。此 handler 作为额外防线，在信号层直接处理。
+        """
+        if self._state == "running":
+            console.info("KeyboardInterrupt by user")
+            self.finish(state="aborted", error="KeyboardInterrupt")
+        # 恢复原始 handler 并重新发送信号，让进程正常终止
+        signal.signal(signal.SIGINT, self._original_sigint_handler)
+        if self._original_sigint_handler is signal.SIG_IGN:
+            return  # Signal was ignored, do nothing.
+        if callable(self._original_sigint_handler):
+            self._original_sigint_handler(signum, frame)
+        else:
+            # The default handler (SIG_DFL) raises KeyboardInterrupt.
+            raise KeyboardInterrupt
+
     def _atexit_cleanup(self) -> None:
         """程序正常退出时自动结束当前运行"""
         if self._state != "running":
@@ -172,7 +197,7 @@ def _excepthook(
                 return
             state: FinishType = "crashed"
             if tp is KeyboardInterrupt:
-                console.info("KeyboardInterrupt by user")
+                console.info("KeyboardInterrupt by user, aborting run...")
                 state = "aborted"
             else:
                 console.info("Error happened while training")
@@ -181,7 +206,7 @@ def _excepthook(
         except Exception as e:
             console.error(f"SwanLab failed to handle excepthook: {e}")
         finally:
-            sys.__excepthook__(tp, val, tb)
+            self._sys_origin_excepthook(tp, val, tb)
 
     def _cleanup(self):
         """
@@ -191,6 +216,7 @@ def _cleanup(self):
         console.debug("Cleanup system hook...")
         atexit.unregister(self._atexit_cleanup)
         sys.excepthook = self._sys_origin_excepthook
+        signal.signal(signal.SIGINT, self._original_sigint_handler)
         # 清理全局运行实例
         console.debug("Cleanup global instance...")
         clear_run()

tests/unit/sdk/internal/run/test_finish_hook.py

@@ -2,13 +2,16 @@
 @author: cunyue
 @file: test_finish_hook.py
 @time: 2026/3/14
-@description: 测试 SwanLabRun._atexit_cleanup / _excepthook 的单元行为（均 mock 依赖，不启动真实 Run）
+@description: 测试 SwanLabRun._atexit_cleanup / _excepthook / _sigint_handler 的单元行为（均 mock 依赖，不启动真实 Run）
 """
 
+import signal
 import sys
 import threading
 from unittest.mock import ANY, MagicMock, patch
 
+import pytest
+
 from swanlab.sdk.internal.run import SwanLabRun
 
 
@@ -49,42 +52,90 @@ class TestExcepthook:
     def test_keyboard_interrupt_calls_aborted(self):
         """KeyboardInterrupt → finish(state='aborted', ...)"""
         run = _make_mock_run()
-        with patch("sys.__excepthook__"):
-            tp, val, tb = _make_exc_info(KeyboardInterrupt())
-            SwanLabRun._excepthook(run, tp, val, tb)
+        run._sys_origin_excepthook = MagicMock()
+        tp, val, tb = _make_exc_info(KeyboardInterrupt())
+        SwanLabRun._excepthook(run, tp, val, tb)
         run.finish.assert_called_once_with(state="aborted", error=ANY)
 
     def test_generic_exception_calls_crashed(self):
         """普通异常 → finish(state='crashed')，error 包含完整 traceback"""
         run = _make_mock_run()
-        with patch("sys.__excepthook__"):
-            tp, val, tb = _make_exc_info(RuntimeError("boom"))
-            SwanLabRun._excepthook(run, tp, val, tb)
+        run._sys_origin_excepthook = MagicMock()
+        tp, val, tb = _make_exc_info(RuntimeError("boom"))
+        SwanLabRun._excepthook(run, tp, val, tb)
         call_kwargs = run.finish.call_args.kwargs
         assert call_kwargs["state"] == "crashed"
         assert "boom" in call_kwargs["error"]
 
     def test_no_op_when_not_running(self):
         """_state != 'running' 时不调用 finish"""
         run = _make_mock_run(state="success")
-        with patch("sys.__excepthook__"):
-            tp, val, tb = _make_exc_info(RuntimeError("no run"))
-            SwanLabRun._excepthook(run, tp, val, tb)
+        run._sys_origin_excepthook = MagicMock()
+        tp, val, tb = _make_exc_info(RuntimeError("no run"))
+        SwanLabRun._excepthook(run, tp, val, tb)
         run.finish.assert_not_called()
 
-    def test_always_calls_original_excepthook(self):
-        """无论是否有活跃 Run，sys.__excepthook__ 必须被调用一次"""
+    def test_always_calls_saved_origin_excepthook(self):
+        """无论是否有活跃 Run，始终调用注册时保存的原始 hook，而非 sys.__excepthook__"""
         run = _make_mock_run(state="success")
-        with patch("sys.__excepthook__") as mock_original:
-            tp, val, tb = _make_exc_info(RuntimeError("test"))
+        saved_hook = MagicMock()
+        run._sys_origin_excepthook = saved_hook
+        tp, val, tb = _make_exc_info(RuntimeError("test"))
+        SwanLabRun._excepthook(run, tp, val, tb)
+        saved_hook.assert_called_once_with(tp, val, tb)
+
+    def test_calls_saved_hook_not_builtin(self):
+        """当外层框架替换了 sys.excepthook 时，调用保存的外层 hook，而非内置默认 hook"""
+        run = _make_mock_run()
+        outer_framework_hook = MagicMock()
+        run._sys_origin_excepthook = outer_framework_hook
+        tp, val, tb = _make_exc_info(RuntimeError("outer"))
+        with patch("sys.__excepthook__") as mock_builtin:
             SwanLabRun._excepthook(run, tp, val, tb)
-            mock_original.assert_called_once_with(tp, val, tb)
+        outer_framework_hook.assert_called_once_with(tp, val, tb)
+        mock_builtin.assert_not_called()
 
     def test_internal_error_doesnt_crash(self):
-        """excepthook 内部出错时不向上抛出，仍调用 sys.__excepthook__"""
+        """excepthook 内部出错时不向上抛出，仍调用保存的原始 hook"""
         run = _make_mock_run()
         run.finish.side_effect = Exception("internal boom")
-        with patch("sys.__excepthook__") as mock_original:
-            tp, val, tb = _make_exc_info(RuntimeError("outer"))
-            SwanLabRun._excepthook(run, tp, val, tb)
-            mock_original.assert_called_once_with(tp, val, tb)
+        saved_hook = MagicMock()
+        run._sys_origin_excepthook = saved_hook
+        tp, val, tb = _make_exc_info(RuntimeError("outer"))
+        SwanLabRun._excepthook(run, tp, val, tb)
+        saved_hook.assert_called_once_with(tp, val, tb)
+
+
+class TestSigintHandler:
+    def test_calls_finish_aborted_when_running(self):
+        """SIGINT handler 在实验运行中应调用 finish(state='aborted')"""
+        run = _make_mock_run()
+        run._original_sigint_handler = signal.SIG_DFL
+        with pytest.raises(KeyboardInterrupt):
+            SwanLabRun._sigint_handler(run, signal.SIGINT, None)
+        run.finish.assert_called_once_with(state="aborted", error="KeyboardInterrupt")
+
+    def test_no_op_when_not_running(self):
+        """_state != 'running' 时不调用 finish，仍抛出 KeyboardInterrupt"""
+        run = _make_mock_run(state="success")
+        run._original_sigint_handler = signal.SIG_DFL
+        with pytest.raises(KeyboardInterrupt):
+            SwanLabRun._sigint_handler(run, signal.SIGINT, None)
+        run.finish.assert_not_called()
+
+    def test_calls_original_callable_handler(self):
+        """如果原始 handler 是 callable，应调用它而非 raise KeyboardInterrupt"""
+        run = _make_mock_run()
+        original = MagicMock()
+        run._original_sigint_handler = original
+        SwanLabRun._sigint_handler(run, signal.SIGINT, None)
+        run.finish.assert_called_once_with(state="aborted", error="KeyboardInterrupt")
+        original.assert_called_once_with(signal.SIGINT, None)
+
+    def test_sig_ign_does_nothing(self):
+        """如果原始 handler 是 SIG_IGN，应静默返回，不抛出 KeyboardInterrupt"""
+        run = _make_mock_run()
+        run._original_sigint_handler = signal.SIG_IGN
+        # Should not raise
+        SwanLabRun._sigint_handler(run, signal.SIGINT, None)
+        run.finish.assert_called_once_with(state="aborted", error="KeyboardInterrupt")