docs(03-02): complete Suspend/Resume Implementation plan

Tasks completed: 2/2
- Task 1: Suspend/resume wiring with race locks, startup cleanup, and graceful shutdown
- Task 2: /timeout and /sessions commands

SUMMARY: .planning/phases/03-lifecycle-management/03-02-SUMMARY.md

.planning/STATE.md

@@ -10,18 +10,18 @@ See: .planning/PROJECT.md (updated 2026-02-04)
 ## Current Position
 
 Phase: 3 of 4 (Lifecycle Management) — IN PROGRESS
-Plan: 03-01 complete (1 of 3 plans completed)
+Plan: 03-02 complete (2 of 3 plans completed)
 Status: In progress
-Last activity: 2026-02-04 — Completed 03-01-PLAN.md (Idle timer foundation)
+Last activity: 2026-02-04 — Completed 03-02-PLAN.md (Suspend/Resume Implementation)
 
-Progress: [████████████░░░] 60%
+Progress: [████████████░░░] 67%
 
 ## Performance Metrics
 
 **Velocity:**
-- Total plans completed: 6
+- Total plans completed: 7
-- Average duration: 18 min
+- Average duration: 16 min
-- Total execution time: 1.98 hours
+- Total execution time: 2.05 hours
 
 **By Phase:**
 
@@ -29,11 +29,11 @@ Progress: [████████████░░░] 60%
 |-------|-------|-------|----------|
 | 1     | 3     | 27min | 9min     |
 | 2     | 2     | 95min | 48min    |
-| 3     | 1     | 2min  | 2min     |
+| 3     | 2     | 6min  | 3min     |
 
 **Recent Trend:**
-- Last 3 plans: 02-01 (5min), 02-02 (90min), 03-01 (2min)
+- Last 3 plans: 02-02 (90min), 03-01 (2min), 03-02 (4min)
-- 03-01: Fast foundation module creation
+- Phase 3 maintaining fast execution: lightweight integration tasks
 
 *Updated after each plan completion*
 
@@ -66,6 +66,11 @@ Recent decisions affecting current work:
 - Default 600s (10 min) idle timeout per session: Balances responsiveness with resource conservation (03-01)
 - Timer reset via task cancellation: Cancel existing task, create new background sleep task (03-01)
 - PID property returns live process ID only: None if terminated to prevent stale references (03-01)
+- Silent suspension: No Telegram message when session auto-suspends (03-02, from CONTEXT.md)
+- Switching sessions leaves previous subprocess running: It suspends on its own timer (03-02, from CONTEXT.md)
+- Race prevention via per-session asyncio.Lock: Prevents concurrent suspend + resume on same session (03-02)
+- Resume shows idle duration if >1 min: "Resuming session (idle for 15 min)..." (03-02)
+- Orphaned PID verification via /proc/cmdline: Only kill claude processes at startup (03-02)
 
 ### Pending Todos
 
@@ -89,7 +94,7 @@ None yet.
 
 ## Session Continuity
 
-Last session: 2026-02-04T23:29:00Z
+Last session: 2026-02-04T23:37:56Z
-Stopped at: Completed 03-01-PLAN.md (Idle timer foundation)
+Stopped at: Completed 03-02-PLAN.md (Suspend/Resume Implementation)
 Resume file: None
-Next: 03-02 (Suspend/Resume Implementation)
+Next: 03-03 (Output Modes)

.planning/phases/03-lifecycle-management/03-02-SUMMARY.md

@@ -0,0 +1,124 @@
+---
+phase: 03-lifecycle-management
+plan: 02
+subsystem: bot-lifecycle
+tags: [asyncio, telegram, subprocess-management, idle-timeout, graceful-shutdown]
+
+# Dependency graph
+requires:
+  - phase: 03-01
+    provides: SessionIdleTimer class with reset/cancel and PID tracking in ClaudeSubprocess
+provides:
+  - Automatic session suspension after idle timeout
+  - Transparent session resume with history preservation
+  - Race-free suspend/resume via asyncio.Lock per session
+  - Orphaned subprocess cleanup at bot startup
+  - Graceful shutdown with subprocess termination
+  - /timeout command for per-session idle configuration
+  - /sessions command for session status overview
+affects: [03-03-output-modes]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns:
+    - "Race prevention via per-session asyncio.Lock for concurrent suspend/resume"
+    - "Silent suspension (no Telegram notification) per CONTEXT.md decision"
+    - "Resume detection via .claude/ directory existence check"
+    - "Idle timer reset in on_complete callback (timer only counts after Claude finishes)"
+
+key-files:
+  created: []
+  modified:
+    - telegram/bot.py
+
+key-decisions:
+  - "Silent suspension (no Telegram notification) per CONTEXT.md LOCKED decision"
+  - "Race prevention via subprocess_locks dict: one asyncio.Lock per session"
+  - "Resume shows idle duration if >1 min (e.g., 'Resuming session (idle for 15 min)...')"
+  - "Orphaned PID verification via /proc/cmdline check (only kill claude processes)"
+  - "Bot shutdown uses post_shutdown callback (python-telegram-bot handles signals)"
+
+patterns-established:
+  - "Per-session locking: subprocess_locks.setdefault(session_name, asyncio.Lock())"
+  - "Idle timer lifecycle: create on session spawn, reset in on_complete, cancel on archive"
+  - "Resume status message format: 'Resuming session (idle for Xm)...'"
+
+# Metrics
+duration: 4min
+completed: 2026-02-04
+---
+
+# Phase 3 Plan 2: Suspend/Resume Implementation Summary
+
+**Automatic session suspension after 10min idle, transparent resume with full history, race-free with asyncio.Lock per session**
+
+## Performance
+
+- **Duration:** 4 min
+- **Started:** 2026-02-04T23:33:30Z
+- **Completed:** 2026-02-04T23:37:56Z
+- **Tasks:** 2
+- **Files modified:** 1
+
+## Accomplishments
+- Sessions automatically suspend after idle timeout (subprocess terminated, metadata updated, silent)
+- User messages to suspended sessions transparently resume with full history
+- Race condition between timeout-fire and user-message prevented via asyncio.Lock per session
+- Bot startup kills orphaned subprocess PIDs (verified via /proc/cmdline)
+- Bot shutdown terminates all subprocesses gracefully (SIGTERM + timeout + SIGKILL)
+- /timeout command sets per-session idle timeout (1-120 min range)
+- /sessions command lists all sessions with LIVE/IDLE status, persona, and relative last-active time
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Suspend/resume wiring with race locks, startup cleanup, and graceful shutdown** - `6ebdb4a` (feat)
+   - suspend_session() callback for idle timer
+   - get_subprocess_lock() helper to prevent races
+   - Resume logic in handle_message/handle_photo/handle_document
+   - Idle timer reset in on_complete and on user activity
+   - cleanup_orphaned_subprocesses() with /proc/cmdline verification
+   - post_init() and post_shutdown() lifecycle callbacks
+   - Updated new_session, switch_session_cmd, archive_session_cmd, model_cmd
+
+2. **Task 2: /timeout and /sessions commands** - `06c5246` (feat)
+   - timeout_cmd() to set/show per-session idle timeout
+   - sessions_cmd() to list all sessions with status
+   - Registered both commands in main()
+
+## Files Created/Modified
+- `telegram/bot.py` - Added suspend/resume lifecycle, idle timers, race locks, startup cleanup, graceful shutdown, /timeout and /sessions commands
+
+## Decisions Made
+
+**From plan execution:**
+- Resume status message shows idle duration if >1 min: "Resuming session (idle for 15 min)..."
+- Orphaned subprocess cleanup verifies PID is a claude process via /proc/cmdline before killing
+- Bot shutdown uses post_shutdown callback (python-telegram-bot Application handles signal installation internally)
+
+**Already documented in STATE.md:**
+- Silent suspension (no Telegram notification) - from CONTEXT.md LOCKED decision
+- Switching sessions leaves previous subprocess running (suspends on its own timer) - from CONTEXT.md LOCKED decision
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+
+None
+
+## Next Phase Readiness
+
+**Ready for Phase 3 Plan 3 (Output Modes):**
+- Session lifecycle fully implemented (suspend/resume, timeout configuration, status commands)
+- Subprocess management robust (startup cleanup, graceful shutdown)
+- Race conditions handled via per-session locks
+
+**No blockers or concerns**
+
+---
+*Phase: 03-lifecycle-management*
+*Completed: 2026-02-04*