feat(miner-governor): enforce non-convergence + budget/turn/termination halts (#2347)

[andriypolanski]

Closes #2347

Summary

Wires the existing pure non-convergence detector (classifyPortfolioConvergence) and budget/turn/termination cap calculator (evaluateGovernorCaps) into the run-loop iteration boundary. Either signal tripping halts the current run, releases the in-flight portfolio item via markFailed, blocks further queue claims until a human clears the halt, and records full context to the governor ledger.

Changes

Area	Change
packages/gittensory-engine/src/governor/run-halt.ts	evaluateRunLoopHalt, detectNonConvergence, evaluateBudgetCaps alias, ledger event builder
packages/gittensory-engine/src/index.ts	Export run-halt module
packages/gittensory-miner/lib/governor-run-halt.js	evaluateRunLoopBoundaryGate — halt check + release + ledger
packages/gittensory-miner/lib/governor-run-halt.d.ts	Type declarations
packages/gittensory-miner/lib/portfolio-queue.js	markFailed — release in_progress → queued
packages/gittensory-miner/lib/portfolio-queue-manager.js	Delegate markFailed
packages/gittensory-miner/package.json	build --check for governor-run-halt
Tests	governor-run-halt.test.ts, miner-governor-run-halt.test.ts, markFailed queue tests, engine package test

Behavior

• Healthy run → canClaimNext: true; ledger records allowed / continue
• Non-convergence → halt; in-flight item released to queued; ledger records denied with convergence context
• Budget / turn cap → halt on next iteration boundary; ledger records denied with cap dimension
• Termination cap → halt; ledger records kill_switch
• Prior halt latched → no further claims; no duplicate ledger rows until cleared

Test plan

• Flapping run halts within detection window and releases in-flight queue item
• Budget-cap breach halts immediately on next iteration boundary
• Healthy run under both signals never halts
• Prior halt stays latched without duplicate ledger writes
• markFailed releases in-progress rows and rejects queued/done/missing items
• Engine package barrel + enforcement smoke test
• npm run test:unit -- test/unit/governor-run-halt.test.ts test/unit/miner-governor-run-halt.test.ts test/unit/miner-portfolio-queue.test.ts
• npm run test --workspace @jsonbored/gittensory-engine
• npm run test:ci (full gate before push)

Notes

• Composes with the Governor chokepoint (maintainer: wire the fail-closed Governor chokepoint before every write action #2340) — this issue delivers run-loop halt wiring + ledger helper, not the full composed chokepoint.
• Pure calculators were already on main; this PR adds enforcement only.
• Issue vocabulary aliases: detectNonConvergence, evaluateBudgetCaps.

Test plan

• Integration tests: flapping halt + item release, budget-cap halt, healthy run continues
• markFailed portfolio queue tests
• Miner governor gate + ledger persistence tests
• npm run test:ci

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[loopover-orb]

Tip

🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩🟩

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-11 08:16:20 UTC}

13 files · 1 AI reviewer · no blockers · readiness 100/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR adds a pure run-loop halt gate (evaluateRunLoopHalt) that composes the existing non-convergence detector and budget/turn/termination cap calculator with a sane priority order (prior_halt > termination > budget > turns > non-convergence), plus a miner-side wrapper (evaluateRunLoopBoundaryGate) that releases the in-flight portfolio item via the new markFailed and records a ledger row, with a latch that prevents duplicate ledger rows while a halt persists. The pure logic and the queue-release SQL are correctly implemented and thoroughly tested (priority ordering, latching, malformed-input rejection). The one gap: the diff only ships the gate primitives, the queue-release helper, and tests — no file in this changeset actually invokes evaluateRunLoopBoundaryGate/evaluateRunLoopHalt from the miner's real iteration loop, so I can't confirm from what's shown that halts are actually enforced in production rather than just available to be called.

Nits — 5 non-blocking

• Verify the miner's actual run loop (not included in this diff) calls `evaluateRunLoopBoundaryGate` at each iteration boundary — the PR description says it 'wires' the gate in, but every changed file here is either the gate itself, the queue-release helper, or tests, so I can't confirm the enforcement is actually reachable from production code.
• `governor-run-halt.js:35-45` records an `allowed` ledger row on every single healthy iteration boundary check (not just on state transitions) — over a long healthy run this can grow the governor ledger unboundedly; consider only recording on the healthy→halted and halted→cleared transitions if that wasn't already the intent.
• `run-halt.ts:111` (the `evaluateRunLoopHalt` if-chain) is flagged at nesting depth 5; consider a small lookup table of `(predicate, reason, eventType, ledgerReason)` tuples evaluated in order to flatten it, since the current early-return chain is already close to readable.
• `evaluateBudgetCaps` (run-halt.ts:21) is a pure re-export alias of `evaluateGovernorCaps` with no added behavior — fine per the 'issue vocabulary' comment, but worth a one-line note in the PR description so future readers don't wonder why two names exist for the same function.
• Add (or point to) the actual run-loop file that calls `evaluateRunLoopBoundaryGate` so reviewers can confirm the halt is wired into a real claim path, per repo#2347's stated goal.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#2347
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 140 registered-repo PR(s), 95 merged, 25 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	andriypolanski; Gittensor profile; 140 PR(s), 25 issue(s).
Gate result	✅ Passing	No configured blocker found.
Improvement	✅ Minor	risk: clean · value: minor — Code changes are accompanied by test evidence. LLM value judgment: moderate — The pure halt-composition logic, queue-release path, and latch behavior are well-designed and well-tested, but the diff stops short of demonstrating the actual production call site that would make the claimed 'enforcement' real.

Review context

• Author: andriypolanski
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Official Gittensor activity: 140 PR(s), 25 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.34%. Comparing base (f175e0c) to head (ae5cfd0).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4989      +/-   ##
==========================================
+ Coverage   94.31%   94.34%   +0.02%     
==========================================
  Files         455      456       +1     
  Lines       39083    39105      +22     
  Branches    14256    14264       +8     
==========================================
+ Hits        36862    36893      +31     
+ Misses       1572     1560      -12     
- Partials      649      652       +3     

Flag	Coverage Δ
shard-1	46.83% <4.54%> (-0.03%)	⬇️
shard-2	33.34% <4.54%> (-0.02%)	⬇️
shard-3	31.11% <4.54%> (-0.02%)	⬇️
shard-4	33.08% <100.00%> (+0.07%)	⬆️
shard-5	33.62% <4.54%> (-0.02%)	⬇️
shard-6	45.23% <4.54%> (-0.03%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...ackages/gittensory-engine/src/governor/run-halt.ts	100.00% <100.00%> (ø)

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.