feat(channels): bound session lifetime with sessionRotation

docs/users/features/channels/overview.md

@@ -62,6 +62,7 @@ Channels are configured under the `channels` key in `settings.json`. Each channe
 | `senderPolicy`           | No               | Who can talk to the bot: `allowlist` (default), `open`, or `pairing`                                                                                                                                                    |
 | `allowedUsers`           | No               | List of user IDs allowed to use the bot (used by `allowlist` and `pairing` policies)                                                                                                                                    |
 | `sessionScope`           | No               | How sessions are scoped: `user` (default), `thread`, or `single`                                                                                                                                                        |
+| `sessionRotation`        | No               | Bounds after which a route starts a fresh session: `{ "maxTurns": N, "maxAgeHours": N }`. Unset means a session is reused forever. See [Session rotation](#session-rotation)                                            |
 | `cwd`                    | No               | Working directory for the agent. Defaults to the current directory                                                                                                                                                      |
 | `approvalMode`           | No               | Tool approval mode for channel sessions. Unattended webhook tasks require `yolo`; the setting applies to every session on the channel                                                                                   |
 | `instructions`           | No               | Custom instructions prepended to the first message of each session                                                                                                                                                      |
@@ -91,6 +92,32 @@ Controls how conversation sessions are managed:
 - **`thread`** — One session per thread/topic. Useful for group chats with threads.
 - **`single`** — One shared session for all users. Everyone shares the same conversation.
 
+### Session Rotation
+
+By default a route keeps the same session forever, so a long-lived route — a busy group thread, a `single`-scope channel — accumulates context without bound. Once it grows past the model's context window every later message on that route fails, while the rest of the channel keeps working. `sessionRotation` puts a ceiling on that: when the current session is past its bound, the next message starts a fresh one instead.
+
+```json
+{
+  "channels": {
+    "my-bot": {
+      "type": "dingtalk",
+      "sessionScope": "thread",
+      "sessionRotation": {
+        "maxTurns": 200,
+        "maxAgeHours": 24
+      }
+    }
+  }
+}
+```
+
+- **`maxTurns`** — Rotate once this many messages have used the current session.
+- **`maxAgeHours`** — Rotate once the current session is older than this.
+
+Set either, both, or neither; whichever bound is hit first rotates. Both must be positive numbers. Omitting `sessionRotation` keeps the previous behavior of never rotating.
+
+Rotation is a context reset, not a cleanup: the new session starts empty, so the bot no longer remembers the earlier conversation on that route. Counters are stored alongside the routes and survive a daemon restart. Sessions that were already routed before you enabled rotation start their clock at the first message after the upgrade.
+
 ### Channel Memory
 
 Channel memory stores durable context for one chat or thread. Entries have stable

packages/channels/base/src/ChannelBase.ts

@@ -847,6 +847,11 @@ export abstract class ChannelBase {
     this.router =
       options?.router ||
       new SessionRouter(bridge, config.cwd, config.sessionScope);
+    // In gateway mode the caller registers rotation for every channel it owns;
+    // a standalone channel owns its router, so it registers its own.
+    if (!options?.router) {
+      this.router.setChannelRotation(this.name, config.sessionRotation);
+    }
 
     this.registerSharedCommands();
     if (this.loopController) {

packages/channels/base/src/SessionRouter.test.ts

@@ -1270,6 +1270,115 @@ describe('SessionRouter', () => {
     });
   });
 
+  describe('session rotation', () => {
+    it('keeps reusing the session when no rotation is configured', async () => {
+      const router = new SessionRouter(bridge, '/tmp');
+      const first = await router.resolve('ch', 'alice', 'chat1');
+      for (let index = 0; index < 20; index++) {
+        expect(await router.resolve('ch', 'alice', 'chat1')).toBe(first);
+      }
+    });
+
+    it('starts a new session once maxTurns is reached', async () => {
+      const router = new SessionRouter(bridge, '/tmp');
+      router.setChannelRotation('ch', { maxTurns: 3 });
+
+      const first = await router.resolve('ch', 'alice', 'chat1');
+      expect(await router.resolve('ch', 'alice', 'chat1')).toBe(first);
+      expect(await router.resolve('ch', 'alice', 'chat1')).toBe(first);
+
+      const rotated = await router.resolve('ch', 'alice', 'chat1');
+      expect(rotated).not.toBe(first);
+      expect(await router.resolve('ch', 'alice', 'chat1')).toBe(rotated);
+    });
+
+    it('rotates only the route that hit the bound', async () => {
+      const router = new SessionRouter(bridge, '/tmp');
+      router.setChannelRotation('ch', { maxTurns: 2 });
+
+      const busy = await router.resolve('ch', 'alice', 'chat1');
+      const quiet = await router.resolve('ch', 'bob', 'chat2');
+      await router.resolve('ch', 'alice', 'chat1');
+
+      expect(await router.resolve('ch', 'alice', 'chat1')).not.toBe(busy);
+      expect(await router.resolve('ch', 'bob', 'chat2')).toBe(quiet);
+    });
+
+    it('does not rotate a channel that has no bound configured', async () => {
+      const router = new SessionRouter(bridge, '/tmp');
+      router.setChannelRotation('bounded', { maxTurns: 2 });
+
+      const unbounded = await router.resolve('other', 'alice', 'chat1');
+      for (let index = 0; index < 5; index++) {
+        expect(await router.resolve('other', 'alice', 'chat1')).toBe(unbounded);
+      }
+    });
+
+    it('starts a new session once maxAgeHours has elapsed', async () => {
+      vi.useFakeTimers();
+      try {
+        const router = new SessionRouter(bridge, '/tmp');
+        router.setChannelRotation('ch', { maxAgeHours: 2 });
+
+        const first = await router.resolve('ch', 'alice', 'chat1');
+        vi.advanceTimersByTime(90 * 60 * 1000);
+        expect(await router.resolve('ch', 'alice', 'chat1')).toBe(first);
+
+        vi.advanceTimersByTime(31 * 60 * 1000);
+        expect(await router.resolve('ch', 'alice', 'chat1')).not.toBe(first);
+      } finally {
+        vi.useRealTimers();
+      }
+    });
+
+    it('ignores non-positive bounds instead of rotating every message', async () => {
+      const router = new SessionRouter(bridge, '/tmp');
+      router.setChannelRotation('ch', { maxTurns: 0, maxAgeHours: -1 });
+
+      const first = await router.resolve('ch', 'alice', 'chat1');
+      expect(await router.resolve('ch', 'alice', 'chat1')).toBe(first);
+    });
+
+    it('persists turn counts so a restart cannot reset the bound', async () => {
+      const dir = mkdtempSync(join(tmpdir(), 'qwen-router-'));
+      tempDirs.push(dir);
+      const persistPath = join(dir, 'routes.json');
+
+      const router = new SessionRouter(bridge, '/tmp', 'user', persistPath);
+      router.setChannelRotation('ch', { maxTurns: 3 });
+      const first = await router.resolve('ch', 'alice', 'chat1');
+      await router.resolve('ch', 'alice', 'chat1');
+
+      const persisted = JSON.parse(readFileSync(persistPath, 'utf-8'));
+      expect(persisted['ch:alice:chat1'].turns).toBe(2);
+
+      const revived = new SessionRouter(bridge, '/tmp', 'user', persistPath, {
+        recoveryMode: 'lazy',
+      });
+      revived.setChannelRotation('ch', { maxTurns: 3 });
+      revived.restoreRoutes();
+
+      expect(await revived.resolve('ch', 'alice', 'chat1')).toBe(first);
+      expect(await revived.resolve('ch', 'alice', 'chat1')).not.toBe(first);
+    });
+
+    it('accepts route stores written before rotation existed', async () => {
+      const dir = mkdtempSync(join(tmpdir(), 'qwen-router-'));
+      tempDirs.push(dir);
+      const persistPath = join(dir, 'routes.json');
+      writePersistedSession(persistPath, 'ch:alice:chat1');
+
+      const router = new SessionRouter(bridge, '/tmp', 'user', persistPath, {
+        recoveryMode: 'lazy',
+      });
+      router.setChannelRotation('ch', { maxAgeHours: 1 });
+
+      expect(router.restoreRoutes()).toEqual({ restored: 1, dropped: 0 });
+      // No recorded start: the clock starts now rather than rotating on sight.
+      expect(await router.resolve('ch', 'alice', 'chat1')).toBe('old-session');
+    });
+  });
+
   describe('clearAll', () => {
     it('clears all in-memory state', async () => {
       const router = new SessionRouter(bridge, '/tmp');