docs(03-01): complete idle timer foundation plan

Tasks completed: 2/2
- Created SessionIdleTimer module with asyncio-based timeout detection
- Extended session metadata with idle_timeout field and PID tracking

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

.planning/STATE.md

@@ -9,19 +9,19 @@ See: .planning/PROJECT.md (updated 2026-02-04)
 
 ## Current Position
 
-Phase: 2 of 4 (Telegram Integration) — COMPLETE
+Phase: 3 of 4 (Lifecycle Management) — IN PROGRESS
-Plan: 02-02 complete (2 of 2 plans completed)
+Plan: 03-01 complete (1 of 3 plans completed)
-Status: Complete
+Status: In progress
-Last activity: 2026-02-04 — Completed 02-02-PLAN.md (Bot integration with batching, file handling, systemd service)
+Last activity: 2026-02-04 — Completed 03-01-PLAN.md (Idle timer foundation)
 
-Progress: [██████████░░░░░] 50%
+Progress: [████████████░░░] 60%
 
 ## Performance Metrics
 
 **Velocity:**
-- Total plans completed: 5
+- Total plans completed: 6
-- Average duration: 23 min
+- Average duration: 18 min
-- Total execution time: 1.95 hours
+- Total execution time: 1.98 hours
 
 **By Phase:**
 
@@ -29,10 +29,11 @@ Progress: [██████████░░░░░] 50%
 |-------|-------|-------|----------|
 | 1     | 3     | 27min | 9min     |
 | 2     | 2     | 95min | 48min    |
+| 3     | 1     | 2min  | 2min     |
 
 **Recent Trend:**
-- Last 3 plans: 01-03 (15min), 02-01 (5min), 02-02 (90min)
+- Last 3 plans: 02-01 (5min), 02-02 (90min), 03-01 (2min)
-- 02-02 included interactive debugging and human verification
+- 03-01: Fast foundation module creation
 
 *Updated after each plan completion*
 
@@ -62,6 +63,9 @@ Recent decisions affecting current work:
 - --dangerously-skip-permissions: Full tool access in non-interactive subprocess (02-02)
 - Full model ID in persona: Use claude-sonnet-4-5-20250929 instead of alias (02-02)
 - Stream-json NDJSON format: {type: user, message: {role: user, content: text}} (02-02)
+- 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)
 
 ### Pending Todos
 
@@ -80,9 +84,12 @@ None yet.
 - ~~Typing indicator not visible despite API success~~ — RESOLVED: Stale task cleanup + dynamic event lookup (02-02)
 - ~~Model identifies as wrong version~~ — RESOLVED: --append-system-prompt preserves CLI defaults (02-02)
 
+**Phase 3 (Lifecycle Management) — IN PROGRESS**
+- None yet
+
 ## Session Continuity
 
-Last session: 2026-02-04T22:10:00Z
+Last session: 2026-02-04T23:29:00Z
-Stopped at: Completed Phase 2 (Telegram Integration)
+Stopped at: Completed 03-01-PLAN.md (Idle timer foundation)
 Resume file: None
-Next: Phase 3 (Lifecycle Management)
+Next: 03-02 (Suspend/Resume Implementation)

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

@@ -0,0 +1,102 @@
+---
+phase: 03-lifecycle-management
+plan: 01
+subsystem: infra
+tags: [asyncio, python, session-management, lifecycle]
+
+# Dependency graph
+requires:
+  - phase: 02-telegram-integration
+    provides: Session management and persistent subprocess architecture
+provides:
+  - SessionIdleTimer class for per-session timeout detection
+  - Session metadata with idle_timeout field for lifecycle configuration
+  - ClaudeSubprocess.pid property for process tracking
+affects: [03-lifecycle-management]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns:
+    - "Asyncio-based timer with reset() cancellation pattern"
+    - "Session metadata defaults for configurable behavior"
+
+key-files:
+  created:
+    - telegram/idle_timer.py
+  modified:
+    - telegram/session_manager.py
+    - telegram/claude_subprocess.py
+
+key-decisions:
+  - "Default 600s (10 min) idle timeout per session"
+  - "Timer reset via task cancellation + new task creation"
+  - "PID property returns live process ID only (None if terminated)"
+
+patterns-established:
+  - "Timer pattern: cancel existing task, create new background sleep task"
+  - "Metadata defaults: provide sensible values in create_session()"
+
+# Metrics
+duration: 2min
+completed: 2026-02-04
+---
+
+# Phase 03 Plan 01: Idle Timer Foundation Summary
+
+**Asyncio-based per-session idle timer with configurable timeout metadata and subprocess PID tracking**
+
+## Performance
+
+- **Duration:** 2 min
+- **Started:** 2026-02-04T23:27:29Z
+- **Completed:** 2026-02-04T23:29:00Z
+- **Tasks:** 2
+- **Files modified:** 3
+
+## Accomplishments
+- Created SessionIdleTimer class with asyncio timer management
+- Extended session metadata to include idle_timeout field (default 600s)
+- Added PID property to ClaudeSubprocess for process tracking
+- Foundation ready for suspend/resume lifecycle implementation
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Create SessionIdleTimer module** - `488d94e` (feat)
+2. **Task 2: Extend session metadata and subprocess PID tracking** - `74f12a1` (feat)
+
+## Files Created/Modified
+- `telegram/idle_timer.py` - SessionIdleTimer class with reset(), cancel(), and activity tracking properties
+- `telegram/session_manager.py` - Added idle_timeout to metadata, get_session_timeout() helper method
+- `telegram/claude_subprocess.py` - Added pid property returning live process ID
+
+## Decisions Made
+- Default idle timeout: 600 seconds (10 minutes) - balances responsiveness with resource conservation
+- Timer reset pattern: Cancel existing asyncio task and create new one (clean slate approach)
+- PID property returns None for terminated processes - prevents stale PID references
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+
+None
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+
+Ready for next plan (03-02: Suspend/Resume Implementation):
+- Idle timer module complete and tested
+- Session metadata supports timeout configuration
+- Subprocess exposes PID for lifecycle tracking
+- All imports verified, no blockers
+
+---
+*Phase: 03-lifecycle-management*
+*Completed: 2026-02-04*