feat(miner-governor): the real create->review->gate->submit attempt pipeline (#2337)

[JSONbored]

Summary

Advances #2337.

Depends on #5112 (#3007's freshness check) — currently shows 2 commits until that merges, at which point this PR's diff will shrink to just the new commit below.

Adds runMinerAttempt (packages/gittensory-miner/lib/attempt-runner.js): the missing link between #2333's iterate-loop orchestrator and an actual, executed open_pr write. Composes, in order:

1. runIterateLoop (create → score → self-review → decide, maintainer: local create->score->self-review iterate-loop orchestrator (the control-flow core) #2333)
2. On handoff → checkSubmissionFreshness (feat(miner): add a late-binding freshness check against live repo state before open_pr fires #3007)
3. → prepareOpenPrSubmission (maintainer: gated-submission trigger — predicted-gate-PASS + slop-under-threshold check before calling open_pr #2336/maintainer: wire the submission-gate trigger into the harness driving loop #2337)
4. → the Governor chokepoint (maintainer: wire the fail-closed Governor chokepoint before every write action #2340) — confirmed by reading chokepoint.ts directly that it already composes kill-switch, dry-run, rate-limit, budget caps, non-convergence, self-reputation-throttle, and self-plagiarism into one precedence ladder, which is why this calls it exactly once rather than also separately invoking governor-open-pr.js's self-plagiarism check (that would double-gate the same decision)
5. On allowed: true → builds the real open_pr command via the now-shared buildOpenPrSpec (moved to the engine in refactor(engine): move local-write action specs into the shared engine package #5117) and executes it via an injected executeLocalWrite

Worktree lifecycle is deliberately not this module's job: runIterateLoop already takes a plain workingDirectory string, agnostic about where it came from. Allocating one is the caller's job, via the already-built slot allocator (worktree-allocator.js, #4297) — this composes the create/review/gate/submit sequence #2337 is actually about, not worktree allocation policy, which is separate, already-solved scope.

Two known, deliberate gaps — surfaced, not papered over

• runSlopAssessment has no production implementation anywhere in this package. The real slop scorer (src/signals/slop.ts, 518 lines, 5 sibling src/signals/** dependencies) is far larger and more interconnected than local-write-tools.ts was, so extracting it is separate, substantial scope. This function requires a real one be injected rather than silently stubbing a result that would either always pass (unsafe) or always fail (useless).
• The governor's cross-attempt state has no persistence wiring anywhere in this package either — rate-limit buckets, budget-cap usage, convergence input, reputation history, self-plagiarism recent-submissions. Confirmed by reading governor-write-rate-limit.js directly: every existing governor-*.js wrapper is a pure in/out transform over caller-supplied state, and nothing persists the returned value between calls. Durable cross-attempt tracking is portfolio-loop-level scope (the outer "process the queue" loop), not a single attempt's.

The CLI dispatch wiring (bin/gittensory-miner.js, real worktree allocation, a real subprocess exec for the final command) is tracked as a separate follow-up — this PR is the fully real, fully tested orchestrator those pieces will call once the two gaps above are resolved.

Scope

• Conventional Commit title.
• Focused: 1 new lib file + .d.ts + build-script entry + 1 test file (this PR's own commit; the extra commit is the feat(miner-governor): late-binding freshness check before open_pr fires (#3007) #5112 dependency, not new scope here).
• Follows CONTRIBUTING.md.
• Linked issue: Advances maintainer: wire the submission-gate trigger into the harness driving loop #2337 — not closing, since the CLI dispatch and the two gaps above remain.

Validation

• npm run build --workspace @jsonbored/gittensory-engine then npm run typecheck — clean.
• node --check on the new file + full packages/gittensory-miner build script (58 files) — all pass.
• npx vitest run test/unit/miner-attempt-runner.test.ts — 10/10 passing: the full happy path through to a constructed+executed open_pr command, abandon (no downstream gate consulted), stale (claim superseded), blocked (submission-gate kill-switch), governed×2 (dry-run mode, and the chokepoint's own kill-switch stage denying even though the submission-gate said ready), the default-governor-ledger fallback path, the body defaulting branch, and fail-closed validation on every malformed input/deps field.
• Scoped coverage: --coverage.include="packages/gittensory-miner/lib/attempt-runner.js" → 100% stmts/branches/funcs/lines (53/53, 64/64, 4/4, 38/38).
• Ran together with the 3 modules this composes (miner-submission-freshness-check, miner-governor-chokepoint, miner-harness-submission-trigger) — 68/68 passing, no interference.
• npm audit --audit-level=moderate — no dependency changes.

Safety

• No secrets/wallets/hotkeys/trust-scores exposed.
• Fail-closed on every malformed-input/deps path (tested).
• Cannot execute a real write without a real executeLocalWrite and a real runSlopAssessment both being injected by the caller — neither has a production default in this package yet, so there is no path to an accidental live write from this PR alone.
• Not an API/OpenAPI/MCP/UI surface change.

[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	21579ec	Commit Preview URL Branch Preview URL	Jul 11 2026, 04:33 PM

[superagent-security]

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.32%. Comparing base (7d260f1) to head (21579ec).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5118      +/-   ##
==========================================
+ Coverage   94.22%   94.32%   +0.10%     
==========================================
  Files         471      471              
  Lines       39821    39821              
  Branches    14533    14533              
==========================================
+ Hits        37520    37560      +40     
+ Misses       1645     1583      -62     
- Partials      656      678      +22     

Flag	Coverage Δ
shard-1	46.34% <ø> (-0.01%)	⬇️
shard-2	34.40% <ø> (+0.57%)	⬆️
shard-3	31.29% <ø> (-0.93%)	⬇️
shard-4	32.74% <ø> (+0.85%)	⬆️
shard-5	33.42% <ø> (-0.17%)	⬇️
shard-6	45.17% <ø> (+0.30%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 3 files 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.

[gittensory-orb]

Warning

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-11 15:59:43 UTC}

7 files · 2 AI reviewers · 2 blockers · readiness 93/100 · CI green · unstable

⏸️ Suggested Action - Manual Review

• No linked issue detected — If this PR is intended to solve an issue, link it explicitly in the PR body.
• Maintainer requires a linked issue — Link the relevant issue (for example Closes #123) before opening the PR.

Review summary
Adds `runMinerAttempt` composing runIterateLoop → checkSubmissionFreshness → prepareOpenPrSubmission → Governor chokepoint → buildOpenPrSpec/executeLocalWrite, plus the new `checkSubmissionFreshness` freshness-gate module. The control flow is a straightforward sequential short-circuit and matches the described precedence (freshness before submission-gate before Governor before write), with fail-closed validation on both malformed input/deps and a failed/null live-state fetch. The case-insensitive author comparison for 'already_addressed' is a real, tested correctness detail (GitHub logins are case-insensitive), and tests cover each branch outcome plus the default-governor-ledger fallback path.

Nits — 5 non-blocking

• `assertInput`/`assertDeps` in attempt-runner.js and the validation block in `checkSubmissionFreshness` are long chains of sequential `if` throws — approaching per the external brief's complexity notes; consider a small validation-list helper if more fields get added later.
• submission-freshness-check.js:60-62's `referencingPrs.some(...)` guards `pr.authorLogin` as string but doesn't guard `pr` itself being non-object — if `snapshot.referencingPrs` ever contains a non-object entry this would throw on `.authorLogin`; low risk given today's only caller passes well-formed fixtures, but worth a one-line typeof/pr-object check for defense.
• governor-ledger default-append fallback in attempt-runner.js relies on `evaluateGovernorChokepointGate`'s own default when `governorLedgerAppend` is omitted — the module doc comment explains this but it's worth double-checking (not visible in this diff) that the default doesn't silently no-op in a way that would lose governor audit events in production.
• Consider extracting the repeated `typeof x === "string" ? x.trim() : ""` pattern used across both new files into a tiny shared validation helper to reduce duplication (nit-level DRY, not required for merge).
• The module doc comments are unusually long (30+ lines) relative to the code — fine for a foundational composition module like this, but future edits to these files should keep the comment in sync with behavior rather than letting it drift.

Concerns raised — review before merging

• No linked issue detected — If this PR is intended to solve an issue, link it explicitly in the PR body.
• Maintainer requires a linked issue — Link the relevant issue (for example Closes #123) before opening the PR.

Signal	Result	Evidence
Code review	❌ 2 blockers	2 reviewers, synthesized
Linked issue	⚠️ Missing	No linked issue or no-issue rationale found.
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 (no linked issue context).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 46 registered-repo PR(s), 38 merged, 416 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 46 PR(s), 416 issue(s).
Gate result	❌ Blocking	Repo-configured hard blocker found.
Improvement	✅ Minor	risk: clean · value: minor — Code changes are accompanied by test evidence. LLM value judgment: significant — This wires together previously-injected-but-unused pipeline stages (iterate-loop, freshness check, submission gate, Governor chokepoint, and the real open_pr write) into one executable end-to-end attempt runner, which is the concrete missing link the PR title and linked issue (#2337) describe, with the two remaining gaps (slop assessment impl, cross-attempt governor persistence) explicitly surfaced rather than stubbed away.

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: 46 PR(s), 416 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.
• Explain no-issue PR.
• Link the issue being solved, or explicitly explain why this is a no-issue PR.

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