Fix concurrent session checkpoint assignment via PID matching

[jwbron]

Summary

Fixes #338 — checkpoint condensation fails with multiple concurrent Claude Code sessions because PrepareCommitMsg assigns the checkpoint to whichever session it encounters first (os.ReadDir order), not the session that initiated the commit.

• Add AgentPID field to session.State, recorded via os.Getppid() on every TurnStart (and at session creation)
• Implement PPID chain walker (findSessionByPIDChain) that traverses the process tree from the hook process to find the owning agent — works on both Linux (/proc/<pid>/stat) and macOS (ps -o ppid=)
• Fall back to most-recent LastInteractionTime sort when PID matching is unavailable (e.g., pre-upgrade sessions with AgentPID=0)
• Make all session selection paths deterministic (no more os.ReadDir ordering dependence)

Key files

File	Change
cmd/entire/cli/session/state.go	Add AgentPID field to State struct
cmd/entire/cli/strategy/pid_matching.go	New: PPID chain walker + LastInteractionTime sort
cmd/entire/cli/strategy/manual_commit_hooks.go	Update PrepareCommitMsg to use PID matching with fallback; record PID in InitializeSession
cmd/entire/cli/strategy/manual_commit_session.go	Set AgentPID at session creation
cmd/entire/cli/strategy/pid_matching_test.go	Unit tests for PID matching and sorting
cmd/entire/cli/strategy/pid_matching_tester_test.go	Comprehensive edge case tests
cmd/entire/cli/strategy/phase_prepare_commit_msg_test.go	Integration tests for concurrent session selection
cmd/entire/cli/strategy/session_state_test.go	AgentPID persistence and lifecycle tests
docs/architecture/sessions-and-checkpoints.md	Document PID-based matching in architecture docs

How it was built

This changeset was generated autonomously by egg, a structurally enforced SDLC pipeline for LLM agents. A human provided minimal guidance — only at the refinement stage to scope the approach — and egg drove the rest: planning, implementation, testing, documentation, and review.

This was an experiment in contributing to an unfamiliar codebase with egg handling the full development lifecycle.

egg pipeline execution

    ╔═════════════════════════════════════════════╗
    │ ✓ Refine                                    │
    │   complete                                  │
    │   ✓ refiner                                 │
    │   ✓ reviewer_refine  ✓ reviewer_agent_design│
    │   [9m52s]                                   │
    ╚═════════════════════════════════════════════╝
        │
        │
        ▼
    ╔══════════════════════════════════════╗
    │ ✓ Plan                               │
    │   complete                           │
    │   ✓ architect                        │
    │   ✓ task_planner  ✓ risk_analyst     │
    │   ✓ reviewer_unified  ✓ reviewer_plan│
    │   [18m50s]                           │
    ╚══════════════════════════════════════╝
        │
        │
        ▼
    ╔═══════════════════════════════════════════════════════════╗
    │ ✓ Implement                                               │
    │   complete                                                │
    │   ✓ coder                                                 │
    │   ✓ tester  ✓ documenter                                  │
    │   ✓ integrator                                            │
    │   ✓ reviewer_unified  ✓ reviewer_code  ✓ reviewer_contract│
    │   ✓ checker  ✓ checker                                    │
    │   [34m43s]                                                │
    ╚═══════════════════════════════════════════════════════════╝
        │
        │
        ▼
    ╔════════════╗
    │ ▶ PR       │
    │   running  │
    ╚════════════╝

Total pipeline time: ~63 minutes across 14+ specialized agents (refiner, architect, task planner, risk analyst, coder, tester, documenter, integrator, reviewers, checkers).

Contribution guidelines note

These commits do not carry Entire-Checkpoint trailers as required by the contribution guidelines — the work was performed inside egg's sandboxed containers rather than Entire-tracked sessions. The .egg-state/ files committed to the branch document the full pipeline audit trail (contract, reviews, check results).

Test plan

• Unit tests for findSessionByPIDChain (single match, no match, all-zero PIDs, duplicate PIDs, max depth)
• Unit tests for sortSessionsByLastInteraction (ordering, nil timestamps, single element, empty)
• Unit tests for getParentPIDLinux /proc/stat parsing edge cases
• Integration tests for PrepareCommitMsg concurrent session selection (PID match and fallback paths)
• Session state persistence tests (AgentPID survives save/load cycle)
• InitializeSession lifecycle tests (PID set on creation and refreshed on TurnStart)
• t.Parallel() on all eligible tests per repo convention
• mise run fmt && mise run lint && mise run test:ci pass

🤖 Generated with egg

[jwbron]

Note, the environment in the sandbox was slightly misconfigured so checks were not able to be run in the workflow. I ran them in a followup instance and had the agent fix any remaining errors.

[jwbron]

this contract defines the workflow that's been run and was validated by a separate agent after implementation.

[jwbron]

Note, I haven't tried running this locally yet. This was just meant to be a first time experiment of tacking a non-trivial task in an unfamiliar project. If repo maintainers are interested with moving forward with this change, I can do manual validation on this branch and move it towards a final state. If not, feel free to close this.