refactor(cuda): decompose CustomStorage helper

agent/Dockerfile

@@ -49,7 +49,11 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 WORKDIR /workspace
 
 COPY cmd/cuda-checkpoint-helper/main.cpp ./cmd/cuda-checkpoint-helper/main.cpp
+COPY cmd/cuda-checkpoint-helper/cuda_operation.cpp ./cmd/cuda-checkpoint-helper/cuda_operation.cpp
+COPY cmd/cuda-checkpoint-helper/cuda_operation.h ./cmd/cuda-checkpoint-helper/cuda_operation.h
 COPY cmd/cuda-checkpoint-helper/cuda_checkpoint_compat.h ./cmd/cuda-checkpoint-helper/cuda_checkpoint_compat.h
+COPY cmd/cuda-checkpoint-helper/daemon_server.cpp ./cmd/cuda-checkpoint-helper/daemon_server.cpp
+COPY cmd/cuda-checkpoint-helper/daemon_server.h ./cmd/cuda-checkpoint-helper/daemon_server.h
 COPY cmd/cuda-checkpoint-helper/daemon_protocol.cpp ./cmd/cuda-checkpoint-helper/daemon_protocol.cpp
 COPY cmd/cuda-checkpoint-helper/daemon_protocol.h ./cmd/cuda-checkpoint-helper/daemon_protocol.h
 COPY cmd/cuda-checkpoint-helper/daemon_protocol_test.cpp ./cmd/cuda-checkpoint-helper/daemon_protocol_test.cpp
@@ -64,13 +68,19 @@ COPY cmd/cuda-checkpoint-helper/transfer_cancellation.h ./cmd/cuda-checkpoint-he
 COPY cmd/cuda-checkpoint-helper/transfer_engine.h ./cmd/cuda-checkpoint-helper/transfer_engine.h
 COPY cmd/cuda-checkpoint-helper/transfer_engine_test.cpp ./cmd/cuda-checkpoint-helper/transfer_engine_test.cpp
 COPY cmd/cuda-checkpoint-helper/transfer_backend_unavailable.cpp ./cmd/cuda-checkpoint-helper/transfer_backend_unavailable.cpp
+COPY cmd/cuda-checkpoint-helper/transfer_scheduler.cpp ./cmd/cuda-checkpoint-helper/transfer_scheduler.cpp
+COPY cmd/cuda-checkpoint-helper/transfer_scheduler.h ./cmd/cuda-checkpoint-helper/transfer_scheduler.h
+COPY cmd/cuda-checkpoint-helper/transfer_scheduler_test.cpp ./cmd/cuda-checkpoint-helper/transfer_scheduler_test.cpp
 
 RUN g++ -std=c++20 -O2 -Wall -Wextra -Werror -pthread \
       -o /cuda-checkpoint-helper-no-transfer-adapter \
       ./cmd/cuda-checkpoint-helper/main.cpp \
+      ./cmd/cuda-checkpoint-helper/cuda_operation.cpp \
+      ./cmd/cuda-checkpoint-helper/daemon_server.cpp \
       ./cmd/cuda-checkpoint-helper/daemon_protocol.cpp \
       ./cmd/cuda-checkpoint-helper/storage_manifest.cpp \
       ./cmd/cuda-checkpoint-helper/transfer_config.cpp \
+      ./cmd/cuda-checkpoint-helper/transfer_scheduler.cpp \
       ./cmd/cuda-checkpoint-helper/transfer_backend_unavailable.cpp \
       -I/usr/local/cuda/include \
       -L/usr/local/cuda/lib64/stubs \
@@ -102,6 +112,14 @@ RUN g++ -std=c++20 -O2 -Wall -Wextra -Werror \
       ./cmd/cuda-checkpoint-helper/transfer_engine_test.cpp \
     && /cuda-checkpoint-helper-transfer-cancellation-test
 
+RUN g++ -std=c++20 -O2 -Wall -Wextra -Werror -pthread \
+      -I/usr/local/cuda/include \
+      -o /cuda-checkpoint-helper-transfer-scheduler-test \
+      ./cmd/cuda-checkpoint-helper/transfer_scheduler.cpp \
+      ./cmd/cuda-checkpoint-helper/transfer_backend_unavailable.cpp \
+      ./cmd/cuda-checkpoint-helper/transfer_scheduler_test.cpp \
+    && /cuda-checkpoint-helper-transfer-scheduler-test
+
 # =============================================================================
 # Stage: Go base - Common setup for Go builds
 # =============================================================================
@@ -227,7 +245,11 @@ WORKDIR /workspace
 
 COPY --from=nixl-builder /nixl-install/usr/local /usr/local
 COPY cmd/cuda-checkpoint-helper/main.cpp ./cmd/cuda-checkpoint-helper/main.cpp
+COPY cmd/cuda-checkpoint-helper/cuda_operation.cpp ./cmd/cuda-checkpoint-helper/cuda_operation.cpp
+COPY cmd/cuda-checkpoint-helper/cuda_operation.h ./cmd/cuda-checkpoint-helper/cuda_operation.h
 COPY cmd/cuda-checkpoint-helper/cuda_checkpoint_compat.h ./cmd/cuda-checkpoint-helper/cuda_checkpoint_compat.h
+COPY cmd/cuda-checkpoint-helper/daemon_server.cpp ./cmd/cuda-checkpoint-helper/daemon_server.cpp
+COPY cmd/cuda-checkpoint-helper/daemon_server.h ./cmd/cuda-checkpoint-helper/daemon_server.h
 COPY cmd/cuda-checkpoint-helper/daemon_protocol.cpp ./cmd/cuda-checkpoint-helper/daemon_protocol.cpp
 COPY cmd/cuda-checkpoint-helper/daemon_protocol.h ./cmd/cuda-checkpoint-helper/daemon_protocol.h
 COPY cmd/cuda-checkpoint-helper/daemon_protocol_test.cpp ./cmd/cuda-checkpoint-helper/daemon_protocol_test.cpp
@@ -242,14 +264,21 @@ COPY cmd/cuda-checkpoint-helper/transfer_cancellation.h ./cmd/cuda-checkpoint-he
 COPY cmd/cuda-checkpoint-helper/transfer_engine.cpp ./cmd/cuda-checkpoint-helper/transfer_engine.cpp
 COPY cmd/cuda-checkpoint-helper/transfer_engine.h ./cmd/cuda-checkpoint-helper/transfer_engine.h
 COPY cmd/cuda-checkpoint-helper/transfer_engine_test.cpp ./cmd/cuda-checkpoint-helper/transfer_engine_test.cpp
+COPY cmd/cuda-checkpoint-helper/transfer_scheduler.cpp ./cmd/cuda-checkpoint-helper/transfer_scheduler.cpp
+COPY cmd/cuda-checkpoint-helper/transfer_scheduler.h ./cmd/cuda-checkpoint-helper/transfer_scheduler.h
+COPY cmd/cuda-checkpoint-helper/transfer_backend_unavailable.cpp ./cmd/cuda-checkpoint-helper/transfer_backend_unavailable.cpp
+COPY cmd/cuda-checkpoint-helper/transfer_scheduler_test.cpp ./cmd/cuda-checkpoint-helper/transfer_scheduler_test.cpp
 COPY cmd/ns-bind-mount/main.c ./cmd/ns-bind-mount/main.c
 
 RUN g++ -std=c++20 -O2 -Wall -Wextra -Werror -pthread -o /cuda-checkpoint-helper \
     ./cmd/cuda-checkpoint-helper/main.cpp \
+    ./cmd/cuda-checkpoint-helper/cuda_operation.cpp \
+    ./cmd/cuda-checkpoint-helper/daemon_server.cpp \
     ./cmd/cuda-checkpoint-helper/daemon_protocol.cpp \
     ./cmd/cuda-checkpoint-helper/storage_manifest.cpp \
     ./cmd/cuda-checkpoint-helper/transfer_config.cpp \
     ./cmd/cuda-checkpoint-helper/transfer_engine.cpp \
+    ./cmd/cuda-checkpoint-helper/transfer_scheduler.cpp \
     -I/usr/local/cuda/include \
     -I/usr/local/include \
     -L/usr/local/cuda/lib64/stubs \
@@ -281,6 +310,14 @@ RUN g++ -std=c++20 -O2 -Wall -Wextra -Werror \
       ./cmd/cuda-checkpoint-helper/transfer_engine_test.cpp \
     && /cuda-checkpoint-helper-transfer-cancellation-test
 
+RUN g++ -std=c++20 -O2 -Wall -Wextra -Werror -pthread \
+      -I/usr/local/cuda/include \
+      -o /cuda-checkpoint-helper-transfer-scheduler-test \
+      ./cmd/cuda-checkpoint-helper/transfer_scheduler.cpp \
+      ./cmd/cuda-checkpoint-helper/transfer_backend_unavailable.cpp \
+      ./cmd/cuda-checkpoint-helper/transfer_scheduler_test.cpp \
+    && /cuda-checkpoint-helper-transfer-scheduler-test
+
 # ns-bind-mount bind-mounts the snapshot binaries into a target container's mount
 # namespace. It needs no CUDA headers, only mount_setattr (Linux 5.12+).
 RUN gcc -O2 -Wall -Wextra -o /ns-bind-mount ./cmd/ns-bind-mount/main.c

agent/cmd/cuda-checkpoint-helper/README.md

@@ -34,6 +34,22 @@ A PageBroker GPU engine may reuse the CUDA operation and transfer behavior
 without adopting this socket protocol. Conversely, Snapshot's local path may
 provide a transfer adapter without changing the workload lifecycle.
 
+## Source ownership
+
+- `main.cpp` parses the helper CLI and dispatches daemon, health, and restore
+  target-discovery commands.
+- `daemon_server.*` owns Unix socket setup, request serving, health, and
+  shutdown.
+- `cuda_operation.*` owns CUDA initialization, target identity checks, driver
+  operations, CustomStorage completion, and retained primary-context lifetime.
+- `transfer_scheduler.*` owns per-extent worker lifetime, the shared
+  deadline, sibling cancellation, and result aggregation.
+- `transfer_engine.*` is the link-time artifact transfer adapter used by the
+  Snapshot-local NIXL POSIX implementation.
+
+These are internal ownership boundaries. They do not add another protocol or
+change the request, response, manifest, or transfer configuration contracts.
+
 ## Running
 
 The Snapshot integration configures one privileged helper beside each node