dsh-ralph-loop

Conventional ReAct loops send an LLM into a blind think-act thrash: errors oscillate, no experience is retained, and the token budget is burned long before a reliable result appears. dsh-ralph-loop replaces that pattern with a five-stage state machine—Reflect, Assess, Learn, Plan, Handle—where every cycle has explicit reflection, evaluation, learning, planning, and execution nodes. Immutable state snapshots and a hard maxCycles ceiling keep the loop deterministic and bounded.

Three pillars carry the core value. First, sandboxed test verification: test commands run inside the Harness Sandbox with fail-closed semantics, so a missing or partial sandbox never lets an unconfined process escape. Second, cross-run lesson persistence: scoped by a lessonKey (hashed to a file name, so no path traversal), accumulated lessons are re-injected into the Plan prompt on the next run, ensuring the same failure does not recur. Third, best-effort return and checkpoint recovery: on failure the engine hands back the closest-to-passing round rather than nothing, and an aborted run can resume from its atomic snapshot with the same parameters. The full ralph/* event stream feeds Trajectory replay, and an optional applyBack writes final files into an operator-designated directory.

It is built for developers driving autonomous code generation inside DeepSeek Harness who need a repeatable loop: generate, test, diagnose, fix—observable, recoverable, and compounding its own experience across runs.