PR #69 followups: lifecycle tests, stop-hook env var, doc cleanup

[lukstafi]

Summary

• Lifecycle unit tests: Export refreshAgentStatuses() and add 20 new tests covering updateTurnLifecycle() edge cases, refreshAgentStatuses() integration (null snapshots, stop-hook fast-complete, inconsistency detection), and orchOnStop() env-var fallback
• Stop-hook env var routing: Update orchOnStop() to fall back to LUDICS_PEER_SYNC_DIR env var when CLI arg is missing/stale; deprecate legacy directory-walk in shell hook with stderr warning
• Doc cleanup: Rewrite stale isTurnFresh()/phaseDispatchedAt reference to past tense in phase-transitions doc

Test plan

• All 68 runner tests pass (was 48, +20 new)
• All 273 tests pass across 18 files
• bun run typecheck clean
• Shell hook guard only execs into orch on-stop when peer_sync_dir is validated (no stale env var regression)

🤖 Generated with Claude Code

[lukstafi]

Coder Refactor Notes — PR #97

1. Consolidate peer-sync resolution into a single function

orchOnStop() now has a 4-step peer-sync dir resolution chain (CLI arg → env var → phase file check → give up), and the shell hook has a parallel 3-step chain (env var → marker file → directory walk). These two resolution chains are coupled but not shared — if one changes, the other can drift.

Suggestion: Extract a resolvePeerSyncDir(cliArg?: string): string | null helper that encapsulates the full resolution logic (CLI arg → env var → marker file walk). Both the TypeScript handler and shell script can call this single source of truth. The shell script would invoke ludics orch resolve-peer-sync "$cwd" and branch on the exit code, eliminating the duplicated discovery logic.

2. Redundant phase file read in orchOnStop()

After the env-var fallback resolves peerSyncDir, the code reads the phase file twice:

• Line 112: readFileIfExists(join(peerSyncDir, "phase")) — to validate the resolved dir
• Line 122: readFileIfExists(join(peerSyncDir, "phase")) — to get the phase value for the stop record

These could be collapsed: store the phase value from the validation check and skip the second read.

3. Remove the deprecated directory-walk path entirely

The directory walk (shell script path 3) is now deprecated with a stderr warning. It's still a ~10-line code path that only fires in edge cases. A follow-up task should remove it outright after one release cycle, since the env var and marker file cover all orchestration scenarios. Track this with a TODO or a follow-up task.

4. orchOnStop docstring is now stale

The docstring says "The shell hook passes an empty-string placeholder for the CLI arg when it couldn't resolve the dir, so the env var kicks in." This was true in the v1 implementation but was reverted in round 2 — the shell now only calls orch on-stop when it has a validated peer_sync_dir. The docstring should be updated to reflect that the env-var fallback is for direct CLI invocations only.