feat(runtime): add idle_cached lifecycle + Claude session resume

Adds the Claude-only idle_cached lifecycle with session-id capture/resume support, stale-session cold-start fallback, supervisor wake-path support, docs, and regression tests for Claude Code stale-resume wording.

Author: ZaynJarvis

README.md

@@ -123,7 +123,7 @@ Agent definitions live in a single JSON file:
 
 Each agent entry has:
 - `name` — unique identifier used on the message bus.
-- `lifecycle` — `24/7` (continuous respawn loop) or `on-demand` (idle until triggered).
+- `lifecycle` — `24/7` (continuous respawn loop), `on-demand` (idle until triggered), or `idle_cached` (idle until triggered, but the prior Claude `session_id` is preserved across triggers via `claude --resume` so context survives idle periods). **`idle_cached` is Claude-only**: pairing it with `runtime: codex` (or `WANMAN_RUNTIME=codex`) is rejected at startup since Codex has no equivalent resume mechanism in this runtime.
 - `model` — usually an abstract tier (`high` or `standard`); the runtime adapter maps it to Claude or Codex defaults, with environment overrides available.
 - `systemPrompt` — baked-in persona/mission; agents also auto-discover shared skill files at `~/.claude/skills/`.
 - Optional `cron`, `events`, and `tools` fields — see the architecture doc for the full schema.

docs/architecture.md

@@ -64,8 +64,33 @@ start()
 
 - Initial state is `idle`; no CPU is spent until something pokes it.
 - A steer-priority message or a cron tick triggers a single execution, after which the agent falls back to `idle`.
+- Each spawn is stateless: the next trigger gets a fresh CLI session.
 
-### 2.3 Agent states
+### 2.3 `idle_cached` — idle, but with resumed context (Claude-only)
+
+```
+start()
+  +-> state = 'idle'           (no CLI subprocess running)
+  +-> lastSessionId = null
+
+trigger() / handleSteer()
+  +- relay.recv()
+  +- spawnClaudeCode({ resumeSessionId: lastSessionId })   # claude --resume <id>
+  +- onSessionId(id => lastSessionId = id)                 # captured from system/init
+  +- wait()
+  +- if resumeMissed():                                    # stale session
+       lastSessionId = null
+       respawn without --resume                            # cold-start fallback
+  +- state = 'idle' again      (but lastSessionId is preserved)
+```
+
+- Same idle CPU profile as `on-demand`, but conversation context survives idle periods because the next spawn passes the captured Claude `session_id` as `--resume <id>`.
+- The first trigger always cold-starts (no captured session yet).
+- If the local Claude CLI has dropped the session id (rotated, manually deleted, etc.), the runtime detects the failure via stderr + exit code, clears the cached id, and re-spawns once without `--resume`. No agent gets stranded.
+- Useful for stateful long-running roles where keeping a process alive forever would be wasteful but losing context every trigger is also wrong (e.g. a "support" agent that should remember the customer between messages).
+- **Claude-only.** The resume mechanism depends on `claude --resume` and Claude Code's `system/init` session id; Codex has no equivalent in this runtime today. Pairing `idle_cached` with `runtime: codex` (or letting `WANMAN_RUNTIME=codex` flip the effective runtime) is rejected at supervisor startup so the misconfig surfaces loudly instead of silently degrading to `on-demand` semantics.
+
+### 2.4 Agent states
 
 | State | Meaning |
 |-------|---------|

packages/core/src/types.ts

@@ -1,5 +1,22 @@
-/** Agent lifecycle mode */
-export type AgentLifecycle = '24/7' | 'on-demand';
+/**
+ * Agent lifecycle mode.
+ *
+ * - `24/7`        — continuous respawn loop. The agent boots a fresh CLI
+ *                   subprocess every iteration. Use for always-on roles.
+ * - `on-demand`   — idle until triggered (cron / steer / message). Each
+ *                   trigger starts a fresh, stateless run.
+ * - `idle_cached` — idle until triggered (like `on-demand`), but the runtime
+ *                   remembers the previous Claude `session_id` and resumes
+ *                   it on the next trigger via `claude --resume`. Combines
+ *                   "no CPU when idle" with "preserved conversation context".
+ *                   **Claude-only.** The resume mechanism depends on Claude
+ *                   Code's `system/init` session id and `--resume` flag;
+ *                   Codex has no equivalent in this runtime today, so the
+ *                   supervisor rejects `idle_cached` paired with a non-Claude
+ *                   runtime at startup rather than letting it silently
+ *                   degrade to `on-demand` semantics.
+ */
+export type AgentLifecycle = '24/7' | 'on-demand' | 'idle_cached';
 
 /** Agent runtime backend */
 export type AgentRuntime = 'claude' | 'codex';

packages/runtime/src/__tests__/agent-process.test.ts

@@ -21,8 +21,21 @@ function deferred<T>() {
 // Per-call wait deferreds
 let waitDeferreds: Array<ReturnType<typeof deferred<number>>>
 let eventHandlers: Array<((event: Record<string, unknown>) => void) | undefined>
+/** Per-call session-id reporter. Tests call this to simulate Claude emitting
+ *  a system/init session id, which AgentProcess captures for idle_cached. */
+let sessionIdReporters: Array<(sessionId: string) => void>
+/** Per-call exit handler — AgentProcess registers one to read resumeMissed
+ *  after the process exits. The mock spawn invokes it on wait()-resolve. */
+let exitReporters: Array<(code: number) => void>
+/** Per-call resumeMissed flag — tests flip this via `setSpawnResumeMissed`
+ *  to simulate Claude refusing the requested --resume id. */
+let resumeMissedFlags: boolean[]
 let spawnCallCount: number
 
+function setSpawnResumeMissed(idx: number, missed: boolean) {
+  resumeMissedFlags[idx] = missed
+}
+
 const mockKill = vi.fn()
 const codexStartRunMock = vi.hoisted(() => vi.fn())
 
@@ -33,15 +46,30 @@ vi.mock('../claude-code.js', () => ({
       waitDeferreds[idx] = deferred<number>()
     }
     const handlers: { event?: (event: Record<string, unknown>) => void } = {}
+    const sessionIdHandlers: Array<(id: string) => void> = []
+    const exitHandlers: Array<(code: number) => void> = []
     eventHandlers[idx] = (event) => handlers.event?.(event)
+    sessionIdReporters[idx] = (id) => {
+      for (const h of sessionIdHandlers) h(id)
+    }
+    exitReporters[idx] = (code) => {
+      for (const h of exitHandlers) h(code)
+    }
     return {
       proc: { pid: 12345, stdin: { end: vi.fn() } },
-      wait: vi.fn(() => waitDeferreds[idx]!.promise),
+      wait: vi.fn(async () => {
+        const code = await waitDeferreds[idx]!.promise
+        // Mirror real adapter behaviour: onExit fires after wait resolves.
+        for (const h of exitHandlers) h(code)
+        return code
+      }),
       kill: mockKill,
       sendMessage: vi.fn(),
       onEvent: vi.fn((handler) => { handlers.event = handler }),
       onResult: vi.fn(),
-      onExit: vi.fn(),
+      onSessionId: vi.fn((handler) => { sessionIdHandlers.push(handler) }),
+      onExit: vi.fn((handler) => { exitHandlers.push(handler) }),
+      resumeMissed: vi.fn(() => resumeMissedFlags[idx] ?? false),
     }
   }),
 }))
@@ -106,6 +134,9 @@ describe('AgentProcess', () => {
     codexStartRunMock.mockClear()
     waitDeferreds = []
     eventHandlers = []
+    sessionIdReporters = []
+    exitReporters = []
+    resumeMissedFlags = []
     spawnCallCount = 0
     relay = makeRelay()
   })
@@ -130,6 +161,48 @@ describe('AgentProcess', () => {
       expect(agent.state).toBe('idle')
     })
 
+    it('rejects idle_cached + declared codex runtime at construction', () => {
+      expect(() => new AgentProcess(
+        makeDef({ name: 'support', lifecycle: 'idle_cached', runtime: 'codex' }),
+        relay,
+        '/tmp/work',
+      )).toThrow(/idle_cached only works with the Claude runtime/)
+    })
+
+    it('rejects idle_cached when WANMAN_RUNTIME forces effective runtime to codex', () => {
+      const original = process.env['WANMAN_RUNTIME']
+      process.env['WANMAN_RUNTIME'] = 'codex'
+      try {
+        expect(() => new AgentProcess(
+          makeDef({ name: 'support', lifecycle: 'idle_cached' }),
+          relay,
+          '/tmp/work',
+        )).toThrow(/forced by WANMAN_RUNTIME=codex/)
+      } finally {
+        if (original === undefined) delete process.env['WANMAN_RUNTIME']
+        else process.env['WANMAN_RUNTIME'] = original
+      }
+    })
+
+    it('accepts idle_cached + claude runtime', () => {
+      const agent = new AgentProcess(
+        makeDef({ name: 'support', lifecycle: 'idle_cached', runtime: 'claude' }),
+        relay,
+        '/tmp/work',
+      )
+      expect(agent.state).toBe('idle')
+      expect(agent.definition.lifecycle).toBe('idle_cached')
+    })
+
+    it('accepts idle_cached with default runtime (claude)', () => {
+      const agent = new AgentProcess(
+        makeDef({ name: 'support', lifecycle: 'idle_cached' }),
+        relay,
+        '/tmp/work',
+      )
+      expect(agent.state).toBe('idle')
+    })
+
     it('should store definition', () => {
       const def = makeDef({ name: 'my-agent' })
       const agent = new AgentProcess(def, relay, '/tmp/work')
@@ -143,6 +216,12 @@ describe('AgentProcess', () => {
       await agent.start()
       expect(agent.state).toBe('idle')
     })
+
+    it('should stay idle for idle_cached agents (no respawn loop)', async () => {
+      const agent = new AgentProcess(makeDef({ lifecycle: 'idle_cached' }), relay, '/tmp')
+      await agent.start()
+      expect(agent.state).toBe('idle')
+    })
   })
 
   describe('start — 24/7 (runLoop)', () => {
@@ -368,6 +447,132 @@ describe('AgentProcess', () => {
       expect(agent.state).toBe('idle')
     })
 
+    it('on-demand never passes resumeSessionId, even after a session id is observed', async () => {
+      const { spawnClaudeCode } = await import('../claude-code.js')
+      waitDeferreds[0] = deferred<number>()
+      waitDeferreds[1] = deferred<number>()
+
+      const agent = new AgentProcess(makeDef({ lifecycle: 'on-demand' }), relay, '/tmp')
+
+      // First trigger: relay enqueues msg1, mock fires onSessionId mid-run.
+      relay.send('alice', 'test-agent', 'message', 'msg1', 'normal')
+      const t1 = agent.trigger()
+      await new Promise((r) => setTimeout(r, 5))
+      sessionIdReporters[0]!('session-from-claude-1')
+      waitDeferreds[0].resolve(0)
+      await t1
+
+      // Second trigger should still spawn fresh — on-demand discards the id.
+      relay.send('alice', 'test-agent', 'message', 'msg2', 'normal')
+      const t2 = agent.trigger()
+      await new Promise((r) => setTimeout(r, 5))
+      waitDeferreds[1].resolve(0)
+      await t2
+
+      const calls = vi.mocked(spawnClaudeCode).mock.calls
+      expect(calls.length).toBe(2)
+      expect(calls[0]![0]).not.toHaveProperty('resumeSessionId')
+      expect(calls[1]![0]).not.toHaveProperty('resumeSessionId')
+    })
+  })
+
+  describe('trigger — idle_cached', () => {
+    it('skips resumeSessionId on the very first trigger (no session captured yet)', async () => {
+      const { spawnClaudeCode } = await import('../claude-code.js')
+      waitDeferreds[0] = deferred<number>()
+      waitDeferreds[0].resolve(0)
+
+      const agent = new AgentProcess(makeDef({ lifecycle: 'idle_cached' }), relay, '/tmp')
+      relay.send('alice', 'test-agent', 'message', 'first message', 'normal')
+
+      await agent.trigger()
+
+      const calls = vi.mocked(spawnClaudeCode).mock.calls
+      expect(calls.length).toBe(1)
+      expect(calls[0]![0].resumeSessionId).toBeUndefined()
+    })
+
+    it('passes the previously-captured session id as resumeSessionId on the next trigger', async () => {
+      const { spawnClaudeCode } = await import('../claude-code.js')
+      waitDeferreds[0] = deferred<number>()
+      waitDeferreds[1] = deferred<number>()
+
+      const agent = new AgentProcess(makeDef({ lifecycle: 'idle_cached' }), relay, '/tmp')
+
+      relay.send('alice', 'test-agent', 'message', 'msg1', 'normal')
+      const t1 = agent.trigger()
+      await new Promise((r) => setTimeout(r, 5))
+      sessionIdReporters[0]!('captured-session-xyz')
+      waitDeferreds[0].resolve(0)
+      await t1
+
+      relay.send('alice', 'test-agent', 'message', 'msg2', 'normal')
+      const t2 = agent.trigger()
+      await new Promise((r) => setTimeout(r, 5))
+      waitDeferreds[1].resolve(0)
+      await t2
+
+      const calls = vi.mocked(spawnClaudeCode).mock.calls
+      expect(calls.length).toBe(2)
+      expect(calls[0]![0].resumeSessionId).toBeUndefined()
+      expect(calls[1]![0].resumeSessionId).toBe('captured-session-xyz')
+    })
+
+    it('falls back to a cold-start retry without resume when the prior session is missing', async () => {
+      const { spawnClaudeCode } = await import('../claude-code.js')
+      waitDeferreds[0] = deferred<number>()
+      waitDeferreds[1] = deferred<number>()
+      waitDeferreds[2] = deferred<number>()
+
+      const agent = new AgentProcess(makeDef({ lifecycle: 'idle_cached' }), relay, '/tmp')
+
+      // Run 1: capture a session id.
+      relay.send('alice', 'test-agent', 'message', 'msg1', 'normal')
+      const t1 = agent.trigger()
+      await new Promise((r) => setTimeout(r, 5))
+      sessionIdReporters[0]!('about-to-go-stale')
+      waitDeferreds[0].resolve(0)
+      await t1
+
+      // Run 2: simulate Claude rejecting --resume on the next spawn. The
+      // mock's resumeMissed flag is read inside onExit, which AgentProcess
+      // checks after wait() resolves.
+      setSpawnResumeMissed(1, true)
+      relay.send('alice', 'test-agent', 'message', 'msg2', 'normal')
+      const t2 = agent.trigger()
+      await new Promise((r) => setTimeout(r, 5))
+      waitDeferreds[1].resolve(0)
+      // Wait for AgentProcess to observe resumeMissed and fire the cold-start.
+      await new Promise((r) => setTimeout(r, 10))
+      waitDeferreds[2].resolve(0)
+      await t2
+
+      const calls = vi.mocked(spawnClaudeCode).mock.calls
+      expect(calls.length).toBe(3)
+      // Spawn 1: cold start (no session yet)
+      expect(calls[0]![0].resumeSessionId).toBeUndefined()
+      // Spawn 2: tried to resume the captured id...
+      expect(calls[1]![0].resumeSessionId).toBe('about-to-go-stale')
+      // Spawn 3: cold-start retry after the resume miss
+      expect(calls[2]![0].resumeSessionId).toBeUndefined()
+    })
+
+    it('handleSteer triggers idle_cached agents the same way it triggers on-demand', async () => {
+      waitDeferreds[0] = deferred<number>()
+      waitDeferreds[0].resolve(0)
+
+      const agent = new AgentProcess(makeDef({ lifecycle: 'idle_cached' }), relay, '/tmp')
+      await agent.start()
+      expect(agent.state).toBe('idle')
+
+      relay.send('alice', 'test-agent', 'message', 'urgent', 'steer')
+      agent.handleSteer()
+
+      // Let the async trigger run to completion.
+      await new Promise((r) => setTimeout(r, 10))
+      expect(spawnCallCount).toBeGreaterThanOrEqual(1)
+    })
+
     it('merges per-run environment from envProvider before spawn', async () => {
       const { spawnClaudeCode } = await import('../claude-code.js')
       waitDeferreds[0] = deferred<number>()