Phase 4: refactor & cleanup — selection engine, dedup rex runtime, bounded protocol buffers, doc/code sweep

[joctaTorres]

Phase 4 — refactor & cleanup

Fourth and final phase of the engine-runtime-hardening batch. Stacked on #99 (base: erh/phase-3-lifecycle-isolation). Consolidates duplicated engine/runtime logic and clears dead code / doc drift, behavior-preservingly.

What landed

• Single selection engine (engine: two selection implementations — selectRunnableStep is dead code while pickNextStep re-implements gate logic with a prose contract #83) — pickNextStep moved into engine/selection.ts; dead selectRunnableStep deleted; the duplicated status.ts/apply.ts gate walk unified behind a shared firstRunnableChange.
• Dedup rex runtime + CI (rex: dedup and packaging — shquote ×3, tail-poll algorithm ×2, docker image default ×2 (cross-language), sidecar tests outside CI #91) — one shared run-command builder; cross-language shquote contract test; the Python DEFAULT_DOCKER_IMAGE literal dropped (REX_IMAGE required); test_sidecar.py wired into CI with a build-time packaging assertion.
• Bounded protocol buffers (rex(protocol): robustness fixes — unbounded line buffers, byte-cursor divergence between sidecar and remote, silently dropped non-JSON frames #90) — partial-line buffers capped at 1 MiB on all three channels (flush-don't-drop); remote byte cursor aligned to the sidecar's surrogateescape arithmetic; non-JSON / unknown frames surfaced to the diagnostic transcript instead of dropped.
• Doc/code-drift sweep (engine: dead code and doc/code drift bundle — guidance handling, run/ vs .run/, dead states, legacy spawner fallback, unreachable llm-judge branch #84) — guidance documented as $ARGUMENTS; run-dir unification; unreachable llm-judge branch, phase-gated StepState, and legacy spawnerAsRuntime fallback removed; intentional identities annotated; drifted doctor tests fixed; coverage-gate.md relocated.
• Phase-3 regression fix — the sidecar used asyncio.SIGTERM (which does not exist) and crashed the local-locus agent spawn on startup; corrected to signal.SIGTERM.

Verification

• npm test — full suite green, exit 0.
• make test-sidecar — 44/44.
• Every change went through propose → apply → verify; two changes (rex: dedup and packaging — shquote ×3, tail-poll algorithm ×2, docker image default ×2 (cross-language), sidecar tests outside CI #91, rex(protocol): robustness fixes — unbounded line buffers, byte-cursor divergence between sidecar and remote, silently dropped non-JSON frames #90) were reworked after their verify caught a real defect (a bypassed build hard-fail, and missing test coverage below the 95% floor) and re-verified clean.

Closes #83
Closes #91
Closes #90
Closes #84

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	ratchet	c5e6295	Commit Preview URL Branch Preview URL	Jul 12 2026, 06:50 PM