Release/3.3.4#19
Merged
Merged
Conversation
The 5-minute idle watchdog terminated opencode child processes whose stdout/stderr went silent for stretches longer than 5 minutes, even when the underlying iteration was still making progress. Real-world ralph-run iterations on medium repos commonly silence for 6-10 minutes during snapshot regen, large test runs, and TypeScript checks. Bumping the default to 15 minutes preserves the watchdog's value (catching truly hung child processes) while eliminating the most common false-positive termination class. Operators can still override via RALPH_ITERATION_IDLE_TIMEOUT_MS for their own workloads.
Surface the seven static checks that catch the most common BLOCKED_HANDOFF
failure modes before ralph-run consumes a tasks.md, rather than discovering
them mid-loop after iterations have burned auto-resolve budget on them.
The pre-scan codifies failure modes observed in practice:
1. Dangling file paths (Scope/Done-when/Stop-if reference files that
don't exist after upstream IA edits)
2. Missing referenced sections (e.g., "SPEC.md Acceptance Criteria
items 1-9" when only SPEC-IA.md §6 exists)
3. Verifier scope wider than Scope statement (e.g., a task scoped to
one test file whose verifier regenerates snapshots for all four)
4. Unclassified pre-existing failures in multi-file gates
5. Subjective stop conditions ("looks wrong", "cannot be explained")
that the agent can neither over- nor under-trigger reliably
6. Manual-only tasks not flagged as such, causing mid-loop ambiguity
7. Cross-task scope conflicts where two tasks claim the same file
Three additive edits, all backwards-compatible:
- OPENSPEC-RALPH-BP.md gains a "Pre-loop scope-handoff pre-scan"
section between Anti-patterns and Examples.
- ralphify_init's openspec/config.yaml heredoc adds a tasks-rule
requiring the pre-scan against tasks.md before ralph-run.
- ralphify_init's AGENTS.md heredoc adds the full seven-point
checklist as agent guidance.
All 22 ralphify_init + check_ralphified bats tests pass; edits are
inside existing 'RALPH_*'-quoted heredocs so no shell expansion risk.
Tasks completed: - [x] 2.1 **Extend `.ralph/ralph-loop.state.json` schema with the supervisor block**
Tasks completed: - [x] 2.2 **Extend `.ralph/ralph-history.json` schema with supervisor fields and `supervisorEdit` entries**
Tasks completed: - [x] 2.3 **Define and document the supervisor I/O contract (request fields + response JSON shape)**
Tasks completed: - [x] 3.1 **Add `_resolveSupervisorConfig()` and wire `--no-self-heal` / `--self-heal-max-tries` plus their env vars**
Tasks completed: - [x] 4.1 **Implement Layer α rule-source loader with in-process mtime+size cache**
Tasks completed: - [x] 4.2 **Implement token-economy preprocessors (Tier 1+2+3 default-on with per-variable escape hatches)**
Tasks completed: - [x] 4.3 **Implement the prompt renderer with try-aware suppression of `downstream_tasks` and `handoff_history`**
Tasks completed: - [x] 5.5 **Re-export `_supervisor` namespace from `lib/mini-ralph/index.js` for tests**
Tasks completed: - [x] 4.5 **Implement Layer β mechanical structural checks for patched task bodies**
Tasks completed: - [x] 4.6 **Implement atomic-swap-then-validate patch application with crash recovery**
Tasks completed: - [x] 4.7 **Implement the supervisor invocation orchestrator (budget + same-hash oscillation + downstream patches)**
Tasks completed: - [x] 4.8 **Implement investigation-hints normalization and persistence**
Tasks completed: - [x] 4.9 **Implement on-demand log-tail access plumbing and audit detection**
Tasks completed: - [x] 5.1 **Wire `runSupervisor` into `runner.js` between fast-path classifier and BLOCKED_HANDOFF exit**
…ion-6 integration tests Iter 25 batched substantial scope-aligned work across tasks 5.2-5.5 and 6.1-6.4 in one model call but exited via pending_dirty_paths because the runner's auto-commit guard rejected the multi-task pile. Manual triage verified each file matches its declared task scope, fixed one stale unit test in mini-ralph-index.test.js (asserted helpers undefined when task 5.5 explicitly required them exposed), and confirmed 702/702 unit tests + 160/160 bats tests pass. Tasks completed: - [x] 5.2 Wire HANDOFF.md `## Supervisor edits` and `### Supervisor attempts` sections - [x] 5.3 Wire status-dashboard rendering for supervisor activity - [x] 5.4 Wire startup recovery (`_recoverSupervisorTmpFiles`) into `ralph-run` startup - [x] 5.5 Re-export `_supervisor` namespace from `lib/mini-ralph/index.js` for tests - [x] 6.1 Integration test: end-to-end happy path resolves a structural blocker via supervisor patch - [x] 6.2 Integration test: budget exhaustion writes `### Supervisor attempts` and exits BLOCKED_HANDOFF - [x] 6.3 Integration test: investigation hints round-trip into the next implementer prompt - [x] 6.4 Integration test: log-tail access audit produces history fields and respects opt-out Verification: - npx jest tests/unit/javascript --runInBand: 29/29 suites, 702/702 tests passing - npx bats tests/integration: 160/160 tests passing (8 macOS-conditional skipped) - npx openspec validate add-supervisor-loop --strict: passes
Tasks completed: - [x] 6.5 **Cleanup bundle: refactor existing budget helpers and `_buildAutoResolveHandoffFeedback` to reuse supervisor budget machinery**
Tasks completed: - [x] 6.6 **Authoring docs: README "Supervisor Loop" section + token-economy subsection + flag table**
Tasks completed: - [x] 6.7 **Authoring docs: OPENSPEC-RALPH-BP, CONTRIBUTING, TESTING update**
Tasks completed: - [x] 6.8 **Close the remaining supervisor coverage gap and rerun the final quality gate**
Splits the two largest mini-ralph modules into cohesive files with
thin re-exports so existing tests + callers stay on the same API:
runner.js 2958 -> 1742 lines (-41%)
runner-handoff.js (HANDOFF.md writes, blocker notes,
supervisor section formatting)
runner-baseline-gate.js (strict-clean baseline-gate detection
+ agent feedback)
runner-autocommit.js (auto-commit pipeline: allowlist,
gitignore filter, message build,
protected-artifact guard)
runner-pending-dirty.js (cross-iteration pending-dirty paths)
supervisor.js 1813 -> 1320 lines (-27%)
supervisor-rules.js (rule-source loading + mtime cache +
RalphBP / design / proposal distillation)
supervisor-state.js (bounded-budget bookkeeping, blocker
hashing, hint normalization, return shape)
Other cleanup in this release:
* lib/mini-ralph/index.js: replace partial _supervisor proxy with a
full module passthrough so new helpers don't drift.
* scripts/ralph-run.sh: track per-run $TMPDIR/ralph-run-XXXXXX in
RALPH_RUN_TEMP_DIR and remove it in cleanup() with a basename
shape-guard. Fixes a long-standing tmpdir leak (~1k stale dirs
observed on a single workstation).
* Delete one-shot iteration error log
openspec/changes/add-supervisor-loop/.ralph/errors_*.md.
Verification:
* jest: 727/727 passing
* bats tests/integration/supervisor-loop.bats: 2/2 passing
* openspec validate add-supervisor-loop --strict: valid
* scripts/ralph-run.sh --version: 3.3.4
No behavioral changes; pure refactor + environmental cleanup.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.