Persistent cron rotation starts a new chat, preserving the old one (#167)

Rotation used to reset the SDK context in place: every context epoch piled
into one endless cron:{job_id} chat, and since the chat view only loads the
most recent messages, pre-rotation history was effectively invisible.

Now each persistent job runs in a generation chat (cron:{job_id}:{ts})
tracked via channel_sessions. Rotation retires the current chat untouched
(history, usage, and run-log links preserved; browsable like any session),
cancels its pending wakeups, stamps/retitles it, and mints a fresh chat for
subsequent runs. Legacy stable-id sessions are adopted on first run so
existing installs keep their context.

Author: pufit

docs/cron.md

@@ -84,7 +84,8 @@ prompt definition.
 | `model` | string | no | Override model (default: `agent.cron_model`) |
 | `target` | string | no | Delivery channel (default: `telegram`) |
 | `session_mode` | string | no | `isolated` (new session per run), `persistent` (reuse context), or `main` |
-| `context_rotate_hours` | int | no | Hours before persistent context resets (default: 24, 0 = never) |
+| `context_rotate_hours` | int | no | Hours before a persistent job rotates to a fresh chat (default: 24, 0 = never). The old chat is preserved |
+| `context_rotate_at` | string | no | Time of day to rotate (e.g. `"04:00"`, in the configured timezone). Overrides the hours-based rotation |
 | `reminder_mode` | bool | no | Persistent only: send short reminder instead of full prompt on subsequent runs (default: false) |
 | `catchup` | bool | no | Fire once on startup if the job missed a run while the server was down (default: true) |
 | `enabled` | bool | no | Whether the job is active (default: true) |
@@ -250,11 +251,16 @@ Each run creates a fresh session (`cron:{job_id}:{timestamp}`). The agent has no
 
 ### Persistent
 
-Jobs with `session_mode: persistent` maintain SDK conversation context across runs:
+Jobs with `session_mode: persistent` maintain SDK conversation context across runs. Each job owns a **generation chat** — one session that is reused run after run until rotation:
 
-- **First trigger**: Creates a fresh session (`cron:{job_id}`) and runs the prompt.
-- **Subsequent triggers**: Resumes the same SDK session and sends the prompt as a new message. The agent sees all prior runs in-context.
-- **Context rotation**: Every `context_rotate_hours` (default: 24), the context is reset. Old messages remain in the database and are searchable via memU, but the agent starts with a clean slate.
+- **First trigger**: Creates a fresh generation session (`cron:{job_id}:{timestamp}`) and runs the prompt.
+- **Subsequent triggers**: Resumes the same SDK session and sends the prompt as a new message. The agent sees all prior runs of this generation in-context.
+- **Context rotation**: Every `context_rotate_hours` (default: 24) — or daily at `context_rotate_at` — the current chat is **retired and a brand-new chat is started**. The old chat is preserved exactly as it was: it keeps its full message history, stays browsable (and resumable) in the UI like any other session, and ages out via the normal session archival policy. Retiring also indexes the old context into memU, cancels the old session's pending wakeups (so a retired thread can't resurrect itself alongside the new one), and retitles it with its end date (`Cron: {job_id} (until 2026-07-05)`).
+
+> **Upgrade note.** Installs that predate generation chats used the stable id
+> `cron:{job_id}`. That session is adopted as the current generation on the
+> first run after upgrading — its SDK context carries over seamlessly — and
+> moves to the generation scheme on its next rotation.
 
 This is useful for jobs that benefit from accumulated context:
 - Monitoring jobs that track changes over time
@@ -263,6 +269,10 @@ This is useful for jobs that benefit from accumulated context:
 
 Between runs, the SDK client subprocess is freed (no resource leak). On the next trigger, the SDK resumes the session from its stored state.
 
+Rotation can also be forced from the Cron page ("Rotate") or via
+`POST /api/cron/jobs/{job_id}/rotate` — same behavior: the current chat is
+preserved and the next run starts in a fresh one.
+
 #### Reminder Mode
 
 Persistent jobs with `reminder_mode: true` avoid resending the full prompt on every trigger. Instead:

nerve/agent/engine.py

@@ -3484,11 +3484,12 @@ async def _teardown_oneshot_client(
         skips live-background-task sessions for the same reason).
 
         ``keepalive_if_bg`` MUST be False for runs whose ``session_id`` is
-        reused across runs (``run_persistent_cron``'s stable ``cron:{job_id}``):
-        parking such a client would let the NEXT scheduled run reuse the same
-        client/conversation while the prior run's background task is still in
-        flight, interleaving the two. Keep-alive is only safe for the
-        unique-per-run isolated paths (``run_cron`` / ``run_hook``).
+        reused across runs (``run_persistent_cron``'s generation session,
+        reused until context rotation): parking such a client would let the
+        NEXT scheduled run reuse the same client/conversation while the
+        prior run's background task is still in flight, interleaving the
+        two. Keep-alive is only safe for the unique-per-run isolated paths
+        (``run_cron`` / ``run_hook``).
         """
         # Optimistic check: a task that settles between the watcher's last drain
         # and here still reads as live, parking a client whose work is actually
@@ -3540,19 +3541,24 @@ async def run_persistent_cron(
         job_id: str,
         prompt: str,
         model: str | None = None,
+        session_id: str | None = None,
     ) -> str:
         """Run a persistent cron job that maintains context across runs.
 
-        Uses a stable session_id (cron:{job_id}) so the SDK resumes
-        conversation context on subsequent triggers.  The client is discarded
-        after each run to free the subprocess (sdk_session_id is preserved for
-        the next resume). Unlike the isolated one-shot paths it does NOT keep
-        the client alive for a live background task: the stable session is
-        reused by the next run, which would collide with the parked task — so a
-        persistent-cron background task that outlives its run is not resumed
-        (use an isolated cron for long background work).
+        The caller (CronService) resolves which generation chat session the
+        job currently owns and passes it as ``session_id`` — reusing it run
+        after run so the SDK resumes conversation context, and minting a
+        fresh session on context rotation (the old chat is preserved). When
+        no ``session_id`` is given, falls back to the legacy stable id
+        ``cron:{job_id}``. The client is discarded after each run to free
+        the subprocess (sdk_session_id is preserved for the next resume).
+        Unlike the isolated one-shot paths it does NOT keep the client alive
+        for a live background task: the session is reused by the next run,
+        which would collide with the parked task — so a persistent-cron
+        background task that outlives its run is not resumed (use an
+        isolated cron for long background work).
         """
-        session_id = f"cron:{job_id}"
+        session_id = session_id or f"cron:{job_id}"
         await self.sessions.get_or_create(
             session_id, title=f"Cron: {job_id}", source="cron",
         )
@@ -3564,9 +3570,9 @@ async def run_persistent_cron(
                 model=model or self.config.agent.cron_model,
             )
         finally:
-            # Stable session_id is reused by the next run, which would collide
-            # with a parked background task — so persistent crons always discard
-            # (no keep-alive). See _teardown_oneshot_client.
+            # The session is reused by the next run (until rotation), which
+            # would collide with a parked background task — so persistent
+            # crons always discard (no keep-alive). See _teardown_oneshot_client.
             await self._teardown_oneshot_client(session_id, keepalive_if_bg=False)
 
     async def run_hook(