feat(miner-hands): add pure per-attempt cost/turn metering to gittensory-engine

[dhgoal]

Adds pure per-attempt cost/turn metering to the engine (Closes #4311).

New packages/gittensory-engine/src/miner/attempt-metering.ts: a pure accumulator + budget evaluator for a coding-agent attempt's usage.

• accumulateAttemptUsage(total, next) / meterAttemptUsage(increments) — fold usage increments ({tokens, turns, wallClockMs, costUsd}) into a running total. Pure; no mutation.
• evaluateAttemptBudget(totals, budget) — check totals against per-axis ceilings (maxTokens/maxTurns/maxWallClockMs/maxCostUsd), returning { totals, withinBudget, breaches }.

Metered unit is pinned explicitly (the issue's open design point): each axis is a plain numeric counter; drivers (CLI-subprocess vs. Agent-SDK) normalize their native usage shape to this unit. Breach semantics: an axis breaches at or above its ceiling (>=), so exactly-at-ceiling is a breach — the boundary the caller must stop on; an omitted ceiling never breaches.

Numbers only — no IO, no Date.now(), no randomness, no enforcement (a reached ceiling is reported, never acted on). Mirrors the governor/rate-limit.ts discipline. The breach-response wiring (graceful-stop vs. hard SIGKILL) and attempt-log persistence (#4294) are explicitly separate, maintainer-owned concerns.

Test

test/attempt-metering.test.ts — accumulation (incl. no-mutation + empty), within-budget, the exactly-at-ceiling boundary, just-under, each axis independently, multiple breaches, the omitted-ceiling arm, and a mid-attempt breach across incremental steps. Full engine suite: 321 pass; test:engine-parity green.

• Conventional Commit; focused; Closes feat(miner-hands): per-attempt cost/turn metering for CodingAgentDriver runs #4311. No site//CNAME/**/lovable/**; no CHANGELOG.md. New engine module + test + one entrypoint re-export.

[superagent-security]

🚨 Contributor flagged. Click here for more info: Superagent Dashboard

[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-09 17:29:14 UTC}

3 files · 1 AI reviewer · no blockers · readiness 82/100 · CI green · unstable

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This adds a small, pure accumulator/evaluator module for per-attempt cost/turn metering (tokens/turns/wallClockMs/costUsd), wired into the engine barrel via a single re-export line. The logic is correct and matches its stated contract: accumulateAttemptUsage/meterAttemptUsage don't mutate inputs, evaluateAttemptBudget uses a fixed axis order and a >= boundary so an exact-ceiling total correctly breaches, and an omitted ceiling never breaches. Tests exercise accumulation, no-mutation, empty-sequence, each axis independently, multi-axis breach ordering, the omitted-ceiling arm, and the exact/just-under boundary — this is real coverage of the actual branches, not fabricated scenarios, since every test drives the exported functions directly with representative inputs.

Nits — 5 non-blocking

• packages/gittensory-engine/test/attempt-metering.test.ts:7 imports from "../dist/index.js" rather than the src barrel — confirm this matches the existing test convention in this package (build-then-test) rather than being an accidental drift from source-level testing.
• attempt-metering.ts defines AttemptMeterTotals as a bare type alias of AttemptUsage with no structural distinction — fine for now, but if totals ever need extra fields (e.g., a sample count) this alias will need to diverge, so consider a comment noting that intent if it's deliberate.
• No validation or nit-level guard exists for negative/NaN usage increments; since the module explicitly delegates input normalization to callers, this is acceptable, but a one-line doc note on the exported types about the expected non-negative domain would help future driver implementers.
• Consider adding one test where a budget mixes an omitted axis with a breached axis (e.g., only maxTurns set while other totals are huge) to make explicit that partial budgets don't accidentally evaluate the unset axes — the current 'omitted ceiling never breaches' test already covers this at {} but not partial-budget shape.
• The header comment duplicates the PR description almost verbatim (enforcement/persistence are separate concerns) — consider trimming to the essential invariant list so future edits don't need to keep two prose copies in sync.

Flagged checks (non-blocking)

• Contributor trust — Contributor flagged for review

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#4311
Related work	⚠️ 3 scoped overlaps	Top overlaps are listed below; lower-confidence bulk is hidden.
Change scope	❌ 8/20	High 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: 93 registered-repo PR(s), 57 merged, 7 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	dhgoal; Gittensor profile; 93 PR(s), 7 issue(s).
Gate result	✅ Passing	No configured blocker found.

Linked issue satisfaction

Addressed
The PR adds a pure attempt-metering module with accumulate/evaluate functions matching the issue's requested cost/turn axes, pins down the metered unit explicitly, follows the numbers-only/no-IO discipline mirroring governor/rate-limit.ts, and includes unit tests covering normal accumulation, exact-ceiling boundary, and mid-attempt breach as requested.

Review context

• Author: dhgoal
• 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: 93 PR(s), 7 issue(s).
• Related work: Titles/paths share 6 meaningful terms. (issue #4297, issue #4307)
• Related work: Titles/paths share 8 meaningful terms. (issue #4297, issue #4311)
• Related work: Titles/paths share 6 meaningful terms. (issue #4307, issue #4311)

Contributor next steps

• Review top overlaps.
• Add a concise scope and risk note.
• Check active issues and PRs before submitting.

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

[loopover-orb]

Gittensory approves — the gate is satisfied and CI is green.