feat(miner-governor): kill-switch propagation into the manage/loop subsystem (#2339)

[JSONbored]

Summary

Closes #2339.

Stacked on #5051 (#2338, still open) -- this PR's diff is scoped to just the kill-switch propagation; #2338's own changes are reviewed separately in its own PR.

Propagates the existing self-host kill-switch/dry-run control into the two manage-phase decision functions the sibling maintainer issues built: shouldSubmit (submission-gate.ts, #2336) and shouldReenter (loop-reentry-policy.ts, #2338). Both now check the kill-switch as their FIRST guard, before any other logic -- flipping the kill-switch halts any pending submission-gate check or loop-reentry immediately, the same way it already halts the Governor chokepoint (#2340).

Deliverables, mapped:

• Both functions check the kill-switch state as their FIRST guard -- done, both short-circuit (never even evaluate the rest of their own logic) when the kill-switch is active.
• A single shared helper, not duplicated per call site -- done. Both reuse isMinerKillSwitchActive (kill-switch.ts, maintainer: global + per-repo kill-switch #2341) directly -- the same function the Governor chokepoint (maintainer: wire the fail-closed Governor chokepoint before every write action #2340) already consults -- rather than inventing a bespoke wrapper. killSwitchScope: MinerKillSwitchScope is a new REQUIRED field on both SubmissionGateCandidate and LoopReentryCandidate (not optional-with-a-permissive-default), so a caller cannot forget to resolve and pass it.
• Read-only polling is explicitly EXEMPTED, documented and tested -- neither countConsecutiveDisengagements/countReentriesSince (loop-reentry.js) nor countConsecutiveGateBlocks (harness-submission-trigger.js) -- the read-side tally computations both wrappers use to build their audit payloads -- ever consult the kill-switch; they keep computing real tallies for accurate logging even when the kill-switch is active, and are called unconditionally regardless of kill-switch state (there's nothing to "exempt" a pure read from -- it was never gated in the first place). Documented in loop-reentry-policy.ts's own module comment.
• Unit tests: kill-switch active blocks unconditionally regardless of otherwise-passing checks -- done, for both functions, including a test that an active kill-switch wins even over a candidate that would otherwise cleanly pass or a per-repo circuit breaker with a maxed-out tally.
• Manual owner review -- flagging here per the issue's own deliverable, given this touches the safety-governor chokepoint.

Coupling fixups applied to the two sibling open PRs, since both shouldSubmit and shouldReenter gained a new required field their existing callers construct internally:

• packages/gittensory-miner/lib/loop-reentry.js's attemptLoopReentry (maintainer: closed-loop discovery re-entry trigger #2338) -- threads killSwitchScope through, validated fail-closed alongside its existing checks, included in the audit payload. This PR is stacked directly on maintainer: closed-loop discovery re-entry trigger #2338's branch, so this fixup is bundled into the SAME commit chain (see the 2nd commit).
• packages/gittensory-engine/src/miner/harness-submission-trigger.ts's evaluateHarnessSubmissionTrigger (maintainer: wire the submission-gate trigger into the harness driving loop #2337, PR feat(miner-governor): wire the gated-submission trigger into the driving loop's handoff signal (#2337) #5054) -- pushed as a separate commit directly to that PR's branch, since maintainer: kill-switch propagation into the manage/loop subsystem #2339 and maintainer: wire the submission-gate trigger into the harness driving loop #2337 are independent, parallel stacks off maintainer: closed-loop discovery re-entry trigger #2338. Also closed a real, pre-existing codecov gap discovered while verifying that fixup: submission-gate.ts had zero root-vitest scenarios for several of its own branches.

Validation

Measured, not assumed -- across both the engine's own node:test suite and the actual codecov-visible root vitest path:

npx tsc -p tsconfig.json --incremental false && npx tsc -p tsconfig.test.json --incremental false && node --experimental-test-coverage --test "dist-test/**/*.test.js"

• 467/467 engine tests pass.
• submission-gate.js: 100.00% lines/branch/funcs.
• loop-reentry-policy.js: 100.00% lines/branch/funcs.
• packages/gittensory-miner's node --check build script passes cleanly.
• Root vitest test/unit/miner-loop-reentry.test.ts (the actual codecov-visible path for loop-reentry.js/loop-reentry-policy.ts): 10/10 tests pass, both files 100% branch coverage.

Test plan

• Kill-switch (global and per-repo scope) blocks shouldSubmit unconditionally, even with an otherwise-clean predicted-gate pass and slop-under-threshold.
• Kill-switch blocks shouldReenter unconditionally, even with a per-repo circuit breaker tally that would otherwise still permit re-entry (99 consecutive disengagements, checked before the circuit breaker itself).
• An inactive kill-switch (scope: "none") never itself blocks -- the underlying signals are still evaluated normally.
• Full integration test (root vitest, real SQLite-backed event-ledger/portfolio-queue/run-state): an active kill-switch blocks attemptLoopReentry without dequeuing or moving run-state, and the block is recorded to the audit ledger with the scope that caused it.

[superagent-security]

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

[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	gittensory-ui	e172927	Commit Preview URL Branch Preview URL	Jul 11 2026, 01:04 PM

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.18%. Comparing base (ad44723) to head (e172927).
⚠️ Report is 3 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5057      +/-   ##
==========================================
+ Coverage   94.14%   94.18%   +0.04%     
==========================================
  Files         467      468       +1     
  Lines       39609    39619      +10     
  Branches    14446    14450       +4     
==========================================
+ Hits        37289    37317      +28     
+ Misses       1664     1646      -18     
  Partials      656      656              

Flag	Coverage Δ
shard-1	46.49% <10.00%> (-0.01%)	⬇️
shard-2	33.83% <10.00%> (-0.01%)	⬇️
shard-3	32.19% <30.00%> (+0.04%)	⬆️
shard-4	31.95% <10.00%> (+0.24%)	⬆️
shard-5	33.29% <30.00%> (+<0.01%)	⬆️
shard-6	44.95% <80.00%> (+0.04%)	⬆️

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

Files with missing lines	Coverage Δ
...ory-engine/src/miner/harness-submission-trigger.ts	100.00% <100.00%> (ø)
...gittensory-engine/src/miner/loop-reentry-policy.ts	100.00% <100.00%> (ø)
...ges/gittensory-engine/src/miner/submission-gate.ts	100.00% <100.00%> (+90.00%)	⬆️

🚀 New features to boost your workflow:

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

[loopover-orb]

Tip

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

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-11 12:58:15 UTC}

8 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 required killSwitchScope field to SubmissionGateCandidate and LoopReentryCandidate and checks it as the very first guard in both shouldSubmit (submission-gate.ts) and shouldReenter (loop-reentry-policy.ts), short-circuiting before any other logic when isMinerKillSwitchActive returns true. It reuses the existing shared helper rather than inventing a bespoke wrapper, threads the scope through the JS-side attemptLoopReentry orchestrator (loop-reentry.js) with a runtime validation guard, and adds matching unit tests for global/repo/none scopes at both the pure-policy and orchestrator layers. The diff is narrowly scoped to the stated issue (#2339), makes the field required (not optional-with-default) so callers can't silently omit it, and every changed branch shown here has a corresponding test.

Nits — 6 non-blocking

• loop-reentry.js:63 hardcodes the scope validation array `["global", "repo", "none"]` inline rather than importing it from a single shared source (kill-switch.ts), so the union could drift silently if a new scope is ever added there.
• submission-gate.ts has no runtime guard analogous to loop-reentry.js's `invalid_kill_switch_scope` check -- it relies entirely on TypeScript's compile-time type, so an untyped/JS caller could pass an unrecognized scope string straight into `isMinerKillSwitchActive` with no fail-closed validation at that boundary; worth confirming the (unseen) harness-submission-trigger.js wrapper validates it the same way loop-reentry.js does.
• The near-identical `if (isMinerKillSwitchActive(...)) return {...}` short-circuit block is duplicated verbatim across submission-gate.ts and loop-reentry-policy.ts; consider a tiny shared `killSwitchGuard(scope)` helper in kill-switch.ts if a third call site shows up.
• Export the scope literal list from kill-switch.ts and import it in loop-reentry.js's validation instead of hardcoding `["global", "repo", "none"]`.
• Add a test (or confirm one exists in the stacked maintainer: closed-loop discovery re-entry trigger #2338/maintainer: wire the fail-closed Governor chokepoint before every write action #2340 PRs) verifying the real production call site for shouldSubmit validates killSwitchScope at its own runtime boundary, mirroring loop-reentry.js's guard.
• PR author also opened the linked issue — Link an issue that was opened by a different contributor, or provide a rationale for why this self-authored issue represents genuine discovery work.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#2339
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: 47 registered-repo PR(s), 39 merged, 423 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 47 PR(s), 423 issue(s).
Gate result	✅ Passing	No configured blocker found.
Improvement	✅ Minor	risk: clean · value: minor — Code changes are accompanied by test evidence.

Review context

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

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.

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