feat(miner): build a governor pause/resume control surface

[JSONbored]

Summary

• Adds a real, persisted pause/resume flag on governor-state.js's existing governor_scalar_state row (paused/pause_reason/paused_at columns), migrated in for on-disk files predating this via a guarded ALTER TABLE (mirrors portfolio-queue.js's own post-creation column migration).
• New governor-pause-cli.js implements gittensory-miner governor pause [--reason <text>] / governor resume / governor status, dispatched from the existing governor noun in governor-ledger-cli.js's runGovernorCli.
• loop-cli.js's iteration loop checks the flag at the same two boundaries as the kill switch — before the first cycle and at the top of every subsequent one — so pausing mid-run stops the loop before its next cycle claims anything.
• Distinct from governor-kill-switch.js (a read-only resolver over env/YAML inputs this package never writes) and governor-run-halt.js (a one-way, run-scoped terminal breaker with no resume path): this is the first genuinely operator/governor-writable stop/go control. Resuming is just clearing the flag and re-invoking the loop — every piece of per-cycle state it reads (portfolio queue, run state, governor state's own cap usage) is already persisted, so a resumed run continues from exactly where it left off.
• The autonomous logic that decides when to pause is separate, later-wave scope per the issue's own boundaries — this PR builds the mechanism only.

Test plan

• npx vitest run test/unit test/contract — 781 files / 15247 tests passing, 0 regressions
• npm run build --workspace @jsonbored/gittensory-miner (node --check over every lib file, including the new one)
• npx tsc --noEmit clean
• npm run docs:drift-check && npm run manifest:drift-check && npm run engine-parity:drift-check && npm run miner:env-reference:check
• npm audit --audit-level=moderate — 0 vulnerabilities
• Dedicated tests for: pause/resume/status CLI (JSON + plain-text, both Error and non-Error thrown open failures, default on-disk store), governor-state.js's pause accessors (round-trip, reason trimming/nulling, cross-preservation with rate-limit/cap-usage state, on-disk schema migration from a pre-Build a governor pause/resume control surface #4851 file, module-singleton wrappers), and loop-cli.js's two halt checkpoints — including a dedicated test proving the loop halts mid-run (not just before the first cycle) and a resume test proving a fresh invocation against the same on-disk files continues from the persisted queue state

Closes #4851

[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	a9edcfd	Commit Preview URL Branch Preview URL	Jul 13 2026, 04:17 AM

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.89%. Comparing base (7cffca2) to head (a9edcfd).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5523      +/-   ##
==========================================
+ Coverage   94.87%   94.89%   +0.02%     
==========================================
  Files         568      569       +1     
  Lines       45055    45154      +99     
  Branches    14675    14675              
==========================================
+ Hits        42746    42849     +103     
+ Misses       1575     1571       -4     
  Partials      734      734              

Flag	Coverage Δ
shard-1	43.87% <60.00%> (-0.35%)	⬇️
shard-2	35.42% <19.00%> (-0.07%)	⬇️
shard-3	32.07% <0.00%> (+0.06%)	⬆️
shard-4	31.30% <6.00%> (-0.74%)	⬇️
shard-5	33.44% <0.00%> (+0.54%)	⬆️
shard-6	44.48% <90.00%> (+0.18%)	⬆️

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

Files with missing lines	Coverage Δ
packages/gittensory-miner/lib/cli.js	100.00% <ø> (ø)
...ckages/gittensory-miner/lib/governor-ledger-cli.js	98.57% <100.00%> (+0.08%)	⬆️
...ackages/gittensory-miner/lib/governor-pause-cli.js	100.00% <100.00%> (ø)
packages/gittensory-miner/lib/governor-state.js	90.42% <100.00%> (+7.75%)	⬆️
packages/gittensory-miner/lib/loop-cli.js	95.02% <100.00%> (+0.21%)	⬆️

🚀 New features to boost your workflow:

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

[gittensory-orb]

Tip

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

✅ Gittensory review result - approve/merge recommended

_{Review updated: 2026-07-13 04:21:26 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
Adds a real, persisted pause/resume flag on governor-state.js's scalar row, a new governor-pause-cli.js exposing pause/resume/status subcommands wired through runGovernorCli, and two checkpoints in loop-cli.js's iteration loop (before the first cycle and at the top of every subsequent one) that halt on an active pause. The migration is correctly guarded by a column-presence check mirroring portfolio-queue.js's convention, savePauseState/loadPauseState correctly preserve the other scalar columns (cap usage, rate-limit state) on every write, and the loop wiring places the pause check in the same two spots as the existing kill-switch check. Console usage flagged by the debug-leftover scan is the CLI's own intended stdout/stderr output (mirrors every other *-cli.js in this package), not leftover debugging.

Blockers

• packages/gittensory-miner/lib/governor-state.js:53 checks only for the `paused` column before skipping the migration, so a file left with `paused` but missing `pause_reason` or `paused_at` will skip `ALTER TABLE` and then fail when `upsertScalarStatement` references absent columns; change `ensurePauseColumns` to inspect all three column names and add each missing column independently.

Nits — 6 non-blocking

• governor-pause-cli.js:43-50's parseGovernorPauseArgs loop nests to depth 5 per the external scan — consider an early-return guard clause to flatten it, though this is purely a style call given the function is otherwise easy to read.
• README.md's addition duplicates a lot of the pause/resume mechanism explanation already in loop-cli.js's own header comment (nit: DRY between the two, though this matches the existing pattern in this package's README of restating each module's own doc).
• Consider whether `governor status` should be readable without requiring `--json` for scripts polling loop health, though the current plain-text default already covers that case.
• governor-pause-cli.js's `renderPauseState` omits parentheses when reason is falsy — already handled correctly, no action needed.
• nit: packages/gittensory-miner/lib/governor-pause-cli.js:48 keeps injected governor states open, which is useful for tests, but the option name `openGovernorState` makes ownership ambiguous; document that injected handles are caller-owned or rename the hook in a follow-up.
• 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	#4851
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: 44 registered-repo PR(s), 36 merged, 399 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 44 PR(s), 399 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: 44 PR(s), 399 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.

[BETA] Chat with Gittensory

Ask Gittensory a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @gittensory ask <question> answers contribution-quality Q&A with source citations and freshness.
• @gittensory chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @gittensory mention with a real question is routed to the closest matching read-only command automatically -- no exact syntax required.

Full command reference: https://gittensory.aethereal.dev/docs/gittensory-commands

_{🟩 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