feat: factory session recovery — preserve branches, run index, and session commands

[colehurwitz]

Closes #698

Changes

• New module factory/runs.py: RunMetadata Pydantic model and CRUD functions (save_run, load_run, list_runs, update_run, delete_run, prune_runs) for persisting per-run metadata at .factory/runs/<run_id>.json. Emits run.created and run.updated events.

• factory/worktree.py: remove_worktree() now takes preserve_branch=True (default) — branches are preserved after worktree removal so sessions can be reconstructed. prune_stale() takes delete_branches=False (default) — orphaned branches are no longer deleted during stale worktree cleanup.

• factory/cli.py: cmd_ceo() and _run_single_cycle() now call save_run() after creating a worktree and update_run() in finally blocks to track run lifecycle. Three new CLI commands:

  • factory sessions-list <path> — list past sessions with --status filter and --json output
  • factory sessions-prune <path> — prune old sessions with --older-than, --dry-run, --all
  • factory sessions-resume <path> <run-id> — reconstruct worktree from a preserved branch

• Tests: 13 CRUD tests in test_runs.py, 4 branch preservation tests in test_worktree.py, 7 CLI smoke tests in test_sessions.py (41 total pass).

Test plan

• pytest tests/test_runs.py -v — all 13 pass
• pytest tests/test_sessions.py -v — all 7 pass
• pytest tests/test_worktree.py -v -k "not Symlink and not Filelock" — all 21 pass (4 pre-existing failures excluded)
• Manual: run factory ceo /path and verify .factory/runs/<id>.json is written
• Manual: verify branch persists after run completes (git branch --list factory/run-*)
• Manual: factory sessions-list /path shows the completed run
• Manual: factory sessions-resume /path <id> reconstructs the worktree

🤖 Generated with Claude Code

[github-actions]

Sentrux Quality Report

Absolute

Scanning ....
[scan] git ls-files: 348 total, 336 kept, 12 dropped (ext:12, meta:0, big:0)
[build_project_map] 336 files, 57 unique dirs, 53 cache misses, 2.6ms
[resolve] 468 resolved, 813 unresolved (of 1281 total specs)
[resolve_imports] project_map 2.6ms, suffix_idx 0.6ms, suffix_resolve 10.1ms, total 13.4ms
[build_graphs] 336 files | maps 0.8ms, imports 13.4ms, calls+inherit 3.0ms, total 17.2ms | 467 import, 4644 call, 0 inherit edges
sentrux check — 2 rules checked

Quality: 4715

✗ [Error] max_cc: 5 function(s) exceed max cyclomatic complexity of 30
    factory/cli.py:cmd_ceo (cc=85)
    factory/study.py:study_project_local (cc=43)
    factory/cli.py:_welcome_wizard (cc=39)
    factory/cli.py:cmd_run (cc=37)
    factory/workflow/validation.py:validate_workflow (cc=31)

✗ 1 violation(s) found

Diff (vs base branch)

Scanning ....
[scan] git ls-files: 348 total, 336 kept, 12 dropped (ext:12, meta:0, big:0)
[build_project_map] 336 files, 57 unique dirs, 53 cache misses, 2.5ms
[resolve] 468 resolved, 813 unresolved (of 1281 total specs)
[resolve_imports] project_map 2.6ms, suffix_idx 0.8ms, suffix_resolve 10.6ms, total 13.9ms
[build_graphs] 336 files | maps 0.8ms, imports 14.0ms, calls+inherit 3.2ms, total 18.0ms | 467 import, 4644 call, 0 inherit edges
sentrux gate — structural regression check

Quality:      4716 -> 4715
Coupling:     0.75 → 0.75
Cycles:       4 → 4
God files:    0 → 0

Distance from Main Sequence: 0.36

✓ No degradation detected

[colehurwitz]

Factory CEO: KEEP ✓

5 commits implementing issue #698:

1. Core: New factory/runs.py module with RunMetadata model + CRUD
2. Core: Updated worktree.py to preserve branches by default
3. Commands: Added sessions-list, sessions-prune, sessions-resume
4. Tests: 45 new tests covering CRUD, branch preservation, CLI commands
5. Fixes: Mock signature + path traversal security fix

QA verified:

• All 45 session recovery tests pass
• Branch preservation works correctly
• Security issue (path traversal via run_id) fixed

Issue #698 acceptance criteria — all met:

• ✓ Preserve git branches
• ✓ Write run metadata file per cycle
• ✓ factory sessions-resume reconstructs worktree
• ✓ factory sessions-list shows past sessions
• ✓ factory sessions-prune for opt-in cleanup

Ready for human review and merge.

[colehurwitz]

Code Review Fixes Applied

All feedback addressed in commit 6f43882:

1. CRITICAL: prune_runs() now unconditionally skips running sessions — removed the and not prune_all condition so status == running is always respected
2. --target arg: sessions-resume accepts --target <path> to override stored worktree path
3. Atomic writes: save_run() and update_run() use tempfile.mkstemp + os.replace pattern
4. Delete event: delete_run() now emits run.deleted event for consistency
5. Branch safety: prune_runs() checks git worktree list --porcelain before deleting branches

New test: test_prune_all_skips_running — all 21 tests pass.

[codecov]

Codecov Report

❌ Patch coverage is 81.06061% with 50 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.25%. Comparing base (941fcb7) to head (5559697).
⚠️ Report is 11 commits behind head on main.

Files with missing lines	Patch %	Lines
factory/cli.py	75.43%	28 Missing ⚠️
factory/runs.py	84.50%	22 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #822      +/-   ##
==========================================
- Coverage   87.39%   87.25%   -0.14%     
==========================================
  Files          86       87       +1     
  Lines       12689    12944     +255     
==========================================
+ Hits        11089    11294     +205     
- Misses       1600     1650      +50     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[osilkin98]

@colehurwitz Looks like this PR needs to be rebased onto the latest main