feat(miner-hands): lint-guarded edit wrapper for coding-agent drivers (#4276)

[joaovictor91123]

Summary

• Adds packages/gittensory-engine/src/miner/lint-guard.ts, which classifies each changed file into the package whose existing check governs it: apps/gittensory-ui -> ui:typecheck, packages/gittensory-engine -> its own tsc -p tsconfig.json build, packages/gittensory-miner/packages/gittensory-mcp .js files -> node --check (per file), everything else (including non-.js files like hand-written .d.ts under those two packages) -> the root npm run typecheck. Runs one check per package group, not per file (except node --check, which is inherently per-file).
• Wires it in: runCodingAgentAttempt (packages/gittensory-engine/src/miner/driver-factory.ts) now accepts an optional lintGuard: LintGuardOptions option. When supplied, the driver's changed files are run through guardCodingAgentDriverResult before the caller sees the result, downgrading ok: false if any check fails. Omitting the option preserves the previous behavior exactly — this is a real call site into the coding-agent invocation path, not a standalone/unreferenced utility.
• No new linter is introduced — this reuses the exact checks the repo already runs in CI.

This is a resubmission of #4477, which the review gate correctly closed for shipping the guard module with zero real callers. This version wires guardCodingAgentDriverResult into runCodingAgentAttempt's live path and addresses the nits (removed the unused LintGuardSpawnResult type, added a direct guardChangedFiles([]) test).

Test plan

• npx vitest run test/unit/coding-agent-miner.test.ts — 43/43 passing, including package classification (all 5 outcomes, .d.ts fallthrough, Windows backslash-path normalization), guardChangedFiles (root/engine/miner-js/ui failures, clean pass, multi-package changeset checked once per package, same-package grouping, empty changeset), guardCodingAgentDriverResult (skip-on-driver-failure, skip-on-no-changes, propagate-failure, preserve-fields-on-success), and runCodingAgentAttempt wiring (omitted lintGuard is a no-op, supplied lintGuard fails/passes the attempt).
• npm --workspace @jsonbored/gittensory-engine run build — clean.
• npm run typecheck — clean.
• Isolated coverage via COVERAGE_NO_THRESHOLDS=1 npx vitest run test/unit/coding-agent-miner.test.ts --coverage --coverage.include="packages/gittensory-engine/src/miner/lint-guard.ts" --coverage.include="packages/gittensory-engine/src/miner/driver-factory.ts" — 100% statements/branches/functions/lines on both touched files.
• Did not run the full unsharded npm run test:coverage locally (shared/resource-contended machine); relying on CI's Codecov patch-coverage gate plus the isolated-coverage check above.

Fixes #4276.

[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.03%. Comparing base (953fdef) to head (3987ad0).
⚠️ Report is 5 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4486   +/-   ##
=======================================
  Coverage   94.03%   94.03%           
=======================================
  Files         420      421    +1     
  Lines       37521    37554   +33     
  Branches    13701    13711   +10     
=======================================
+ Hits        35282    35315   +33     
  Misses       1583     1583           
  Partials      656      656           

Files with missing lines	Coverage Δ
...ages/gittensory-engine/src/miner/driver-factory.ts	100.00% <100.00%> (ø)
packages/gittensory-engine/src/miner/lint-guard.ts	100.00% <100.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-09 22:12:24 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This adds an opt-in lint-guard wrapper (packages/gittensory-engine/src/miner/lint-guard.ts) that classifies changed files into the package whose existing check governs them (ui/engine/miner-js/mcp-js/root), runs that check once per package group, and decorates a CodingAgentDriverResult with the verdict; driver-factory.ts wires an optional `lintGuard` param into `runCodingAgentAttempt` that downgrades `ok` on failure while leaving the omitted-option path byte-for-byte unchanged (verified by the 'unaffected when lintGuard is omitted' test). The classification, grouping, and skip-on-driver-failure/no-changes logic are correct and thoroughly covered by 43 real (non-fabricated) DI-based tests using the same injected-spawn pattern as `SelfHostAi`. Since `CODING_AGENT_DRIVER_NAMES` is still only `["noop"]` and nothing in this diff actually supplies a real `lintGuard` config at a live call site, the wrapper remains wired-but-unexercised in production — worth a direct answer from the author on whether that still counts as the 'real caller' #4477 was rejected for lacking.

Nits — 5 non-blocking

• lint-guard.ts:63-67 runs the engine check via `npm run build --workspace @​jsonbored/gittensory-engine`, but the file's own header comment (lint-guard.ts:4-5) describes the check as `tsc -p tsconfig.json`; confirm the build script is `--noEmit` or otherwise doesn't write dist output into the attempt's worktree, since emitted files there could pollute git status for any downstream step that re-diffs changedFiles after the guard runs.
• No caller in this diff actually passes `lintGuard` into `runCodingAgentAttempt` for a live driver (driver-factory.ts:100-113) — confirm this resubmission still needs a genuine invocation site beyond the optional parameter to fully close out the 'zero real callers' reason feat(miner-hands): lint-guarded edit wrapper for coding-agent drivers (#4276) #4477 was rejected for.
• runPackageCheck's per-file `node --check` loop (lint-guard.ts:73-80) runs sequentially rather than via `Promise.all`; not urgent for typical small changesets but worth a comment if large miner/mcp JS changesets become common.
• The multi-package test (test/unit/coding-agent-miner.test.ts, 'checks a changeset spanning multiple packages') exercises root/engine/miner-js/ui together but never mcp-js in the same combined scenario — a minor coverage gap given mcp-js otherwise only gets its classification tested, not a full guardChangedFiles run.
• Swap the engine PACKAGE_COMMAND to a direct `tsc --noEmit -p tsconfig.json` invocation (or confirm the workspace `build` script is noEmit) so the guard can't leave build artifacts in the attempt's worktree.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#4276
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: 95 registered-repo PR(s), 46 merged, 10 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	joaovictor91123; Gittensor profile; 95 PR(s), 10 issue(s).
Gate result	✅ Passing	No configured blocker found.

Linked issue satisfaction

Addressed
The PR adds lint-guard.ts classifying files by package (ui/engine/miner-js/mcp-js/root) and running the existing checks (ui:typecheck, engine tsc build, node --check per miner/mcp js file, root typecheck) rather than introducing a new linter, wires guardCodingAgentDriverResult into runCodingAgentAttempt as a real call site, returns a structured LintGuardResult instead of throwing, and includes tes

Review context

• Author: joaovictor91123
• 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: 95 PR(s), 10 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