feat(sp25): scheduler.reconfigure_scheduler() hot-reload helper

backend/src/cyclone/scheduler.py

@@ -69,6 +69,11 @@ STATUS_SKIPPED = "skipped"
 STATUS_PENDING = "pending"
 
 
+# How long reconfigure_scheduler waits for the in-flight tick to
+# drain before cancelling the old task. Matches Scheduler.stop().
+_DRAIN_TIMEOUT_SECONDS = 30
+
+
 # File types we know how to route. The HCPF set is broader (270/271/
 # 276/277/278/820/834/ENCR) but Cyclone's parser only covers the
 # four below. Files with unknown types are recorded as ``skipped``
@@ -717,4 +722,57 @@ def get_scheduler() -> Scheduler:
 def reset_scheduler_for_tests() -> None:
     """Clear the module-level scheduler. Test-only."""
     global _scheduler
-    _scheduler = None
+    _scheduler = None
+
+
+async def reconfigure_scheduler(
+    sftp_block: SftpBlock,
+    *,
+    poll_interval_seconds: int = 60,
+    sftp_block_name: str = "default",
+) -> Scheduler:
+    """Replace the singleton scheduler; restart if it was running. SP25.
+
+    Called from ``PATCH /api/clearhouse`` so the next scheduler tick
+    uses the new SftpBlock without a process restart.
+
+    Lifecycle:
+        * If the previous scheduler is running, ``stop()`` it (waits
+          up to ``_DRAIN_TIMEOUT_SECONDS`` for the current tick to
+          finish — matches the existing ``Scheduler.stop()`` timeout).
+        * Replace the module-level ``_scheduler`` singleton with a
+          fresh ``Scheduler`` against the new block.
+        * If the previous one was running, ``start()`` the new one.
+
+    Threading: same constraint as ``configure_scheduler`` — must be
+    called from the FastAPI event loop, not a worker thread.
+    """
+    global _scheduler
+    was_running = False
+    if _scheduler is not None:
+        was_running = _scheduler.is_running()
+        if was_running:
+            # Drain the in-flight tick. Scheduler.stop() already
+            # applies the _DRAIN_TIMEOUT_SECONDS timeout internally;
+            # we just await it.
+            await _scheduler.stop()
+    poll = int(
+        os.environ.get("CYCLONE_SCHEDULER_POLL_SECONDS", poll_interval_seconds),
+    )
+    _scheduler = Scheduler(
+        sftp_block,
+        poll_interval_seconds=poll,
+        sftp_block_name=sftp_block_name,
+    )
+    if was_running:
+        await _scheduler.start()
+    log.info(
+        "Scheduler reconfigured",
+        extra={
+            "was_running": was_running,
+            "sftp_block": sftp_block_name,
+            "host": sftp_block.host,
+            "stub": sftp_block.stub,
+        },
+    )
+    return _scheduler