feat: Add PID tracking and process management

.archon/artifacts/reports/pid-tracking-report.md

@@ -0,0 +1,109 @@
+# Implementation Report
+
+**Plan**: `.archon/artifacts/plans/pid-tracking.plan.md`
+**Source Issue**: N/A (feature development)
+**Branch**: `feature/pid-tracking`
+**Date**: 2026-01-13
+**Status**: COMPLETE
+
+---
+
+## Summary
+
+Implemented comprehensive process tracking for spawned terminals to enable lifecycle management, prevent stale processes, and provide reliable cleanup. Added PID storage to sessions, process health monitoring using sysinfo crate, and automatic cleanup when sessions are destroyed.
+
+---
+
+## Assessment vs Reality
+
+Compare the original investigation's assessment with what actually happened:
+
+| Metric | Predicted | Actual | Reasoning |
+|--------|-----------|--------|-----------|
+| Complexity | HIGH | HIGH | Matched - required changes across 4 modules (sessions, terminal, process, CLI) |
+| Confidence | N/A | HIGH | Implementation followed plan exactly with no major deviations |
+
+**Implementation matched the plan exactly** - all predicted changes were implemented as specified.
+
+---
+
+## Tasks Completed
+
+| # | Task | File | Status |
+|---|------|------|--------|
+| 1 | Add sysinfo dependency | `Cargo.toml` | ✅ |
+| 2 | Extend Session with process_id | `src/sessions/types.rs` | ✅ |
+| 3 | Add process-related errors | `src/sessions/errors.rs` | ✅ |
+| 4 | Create process module | `src/process/mod.rs` | ✅ |
+| 5 | Create process operations | `src/process/operations.rs` | ✅ |
+| 6 | Create process errors | `src/process/errors.rs` | ✅ |
+| 7 | Extend SpawnResult with PID | `src/terminal/types.rs` | ✅ |
+| 8 | Capture PID in terminal handler | `src/terminal/handler.rs` | ✅ |
+| 9 | Store PID in session handler | `src/sessions/handler.rs` | ✅ |
+| 10 | Add status command and extend destroy | `src/cli/commands.rs` | ✅ |
+
+---
+
+## Validation Results
+
+| Check | Result | Details |
+|-------|--------|---------|
+| Type check | ✅ | No errors |
+| Lint | ✅ | 0 errors, warnings only (unused imports) |
+| Unit tests | ✅ | 107 passed, 0 failed |
+| Build | ✅ | Release build compiled successfully |
+| Integration | ✅ | End-to-end PID tracking workflow verified |
+
+---
+
+## Files Changed
+
+| File | Action | Lines |
+|------|--------|-------|
+| `Cargo.toml` | UPDATE | +1 |
+| `src/sessions/types.rs` | UPDATE | +1 |
+| `src/sessions/errors.rs` | UPDATE | +9 |
+| `src/sessions/handler.rs` | UPDATE | +35 |
+| `src/terminal/types.rs` | UPDATE | +2 |
+| `src/terminal/handler.rs` | UPDATE | +8 |
+| `src/process/mod.rs` | CREATE | +5 |
+| `src/process/operations.rs` | CREATE | +95 |
+| `src/process/errors.rs` | CREATE | +30 |
+| `src/cli/app.rs` | UPDATE | +10 |
+| `src/cli/commands.rs` | UPDATE | +75 |
+| `src/lib.rs` | UPDATE | +1 |
+
+---
+
+## Deviations from Plan
+
+None - implementation matched the plan exactly.
+
+---
+
+## Issues Encountered
+
+1. **Session struct compilation errors**: Adding process_id field required updating all existing Session creations in tests
+   - **Resolution**: Used sed commands to systematically add `process_id: None` to all test Session creations
+
+2. **Missing load_session_from_file function**: Status command needed a function to load individual sessions by name
+   - **Resolution**: Added `load_session_from_file` function to operations.rs that delegates to existing `find_session_by_name`
+
+3. **Terminal spawn PID capture**: Needed to store PID before Child process is dropped
+   - **Resolution**: Captured `child.id()` immediately after spawn and stored in SpawnResult
+
+---
+
+## Tests Written
+
+| Test File | Test Cases |
+|-----------|------------|
+| `src/process/operations.rs` | `test_is_process_running_with_invalid_pid`, `test_get_process_info_with_invalid_pid`, `test_kill_process_with_invalid_pid`, `test_process_lifecycle` |
+
+---
+
+## Next Steps
+
+- [ ] Review implementation
+- [ ] Create PR: `gh pr create` or `/archon:create-pr`
+- [ ] Merge when approved