diff --git a/.planning/phases/03-lifecycle-management/03-CONTEXT.md b/.planning/phases/03-lifecycle-management/03-CONTEXT.md new file mode 100644 index 0000000..6ab8412 --- /dev/null +++ b/.planning/phases/03-lifecycle-management/03-CONTEXT.md @@ -0,0 +1,64 @@ +# Phase 3: Lifecycle Management - Context + +**Gathered:** 2026-02-04 +**Status:** Ready for planning + + +## Phase Boundary + +Sessions suspend automatically after configurable idle timeout and resume transparently with full conversation history. Includes `/timeout` and `/sessions` commands. Graceful cleanup on bot restart with no zombie processes. + + + + +## Implementation Decisions + +### Suspend/resume feedback +- Silent suspension — no notification sent when a session auto-suspends +- On resume: send brief status message ("Resuming session...") before Claude's actual response +- Claude's Discretion: whether to include idle duration in the resume message + +### Resume mechanism +- Use Claude Code's `--resume` flag to restore full conversation state from before suspension +- If resume fails: send error message to user and wait for their decision (don't auto-start fresh) + +### Idle detection rules +- Activity = both user messages AND Claude responses/tool use reset the idle timer +- Never suspend while Claude is actively processing (timer only starts after response completes) +- Per-session idle timeout, stored in session metadata +- Default: 10 minutes +- Claude's Discretion: allowed range for `/timeout` command + +### Multi-session behavior +- Multiple sessions can have live subprocesses simultaneously, each with independent idle timers +- Switching sessions with `/session` leaves the previous session's subprocess running (it'll suspend on its own idle timer) +- Claude's Discretion: `/sessions` list format and detail level +- Claude's Discretion: message routing approach (always-active-session vs session prefix) + +### Startup & cleanup +- On bot restart: all sessions start in suspended state — no subprocesses launched until user messages +- Unlimited total sessions — no cap, sessions accumulate until manually archived +- Claude's Discretion: suspend method (SIGTERM + --resume vs SIGSTOP/SIGCONT) based on resource trade-offs + + + + +## Specific Ideas + +- Resume should feel fast and transparent — user messages a suspended session and it "just works" with a brief status indicator +- The system should be invisible when working — no notifications on suspend, minimal friction on resume +- Per-session timeouts allow long-running task sessions to stay alive longer while quick sessions clean up fast + + + + +## Deferred Ideas + +None — discussion stayed within phase scope + + + +--- + +*Phase: 03-lifecycle-management* +*Context gathered: 2026-02-04*