test(miner-hands): behavioral contract suite for the two CodingAgentDriver implementations

[reyanthony062001-ops]

Closes #4296

What

A behavioral contract/parity suite proving the CLI-subprocess (#4266) and Agent-SDK (#4267) CodingAgentDriver implementations are interchangeable behind the #4262 seam — the property the iterate-loop orchestrator (#2333) depends on. Test-only: test/contract/coding-agent-driver-parity.test.ts (homed alongside engine-parity.test.ts per the issue's guidance) plus the test:driver-parity script wired into test:ci, mirroring test:engine-parity's invocation pattern.

Design

• Same scenario fixtures against BOTH drivers: a DRIVER_HARNESSES table builds each driver around its own injected fake backend (fake CliSubprocessSpawnFn / fake AgentSdkQueryFn — no real subprocess, no real model call), each expressing the same three behaviors (success, clean_failure, budget_exhausted); every contract case runs via describe.each over the table.
• Shape contract, not byte-parity: coding-agent output is not deterministic across implementations, so the suite asserts identical result SHAPE and edge-case handling — the field-by-field CodingAgentDriverResult validator, structured never-throwing failures with changedFiles: [], a non-empty machine-readable error on both wall-clock (CLI timedOut) and turn-budget (SDK error_max_turns) exhaustion, distinguishable success-vs-failure summaries, and feat(miner-hands): immutable acceptance-criteria file written before the coding agent starts #4271's empty/malformed acceptance-criteria input degrading to a structured result on both.
• Working-directory scoping asserted, not assumed: each harness records every directory its backend was pointed at; the suite requires exactly the task's worktree, plus verbatim instruction forwarding — the CLI fake captures the FULL argv and asserts the instructions appear in it (no positional assumption about argv order, so a future argv change fails loud).
• Caller-side interchangeability: both drivers run through invokeCodingAgentDriver with a shared attempt-log sink and must produce the identical attempt_started → attempt_succeeded / attempt_failed event sequences.
• Divergences documented AND locked in: the header records the deliberately tolerated value-level divergences the shared interface does not paper over (changedFiles semantics, turnsUsed availability, differing budget mechanisms), and a dedicated describe block pins the turnsUsed divergence with explicit per-driver assertions so it can't drift silently.
• Third-driver workflow: the header documents how a future implementation plugs in — one harness entry, zero test-body changes.

Testing

18 cases, all green (npm run test:driver-parity); root typecheck and git diff --check clean. Test-only diff — no src/** or engine source changes.

[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.08%. Comparing base (4d8409d) to head (358f74c).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4562   +/-   ##
=======================================
  Coverage   94.08%   94.08%           
=======================================
  Files         427      427           
  Lines       37961    37961           
  Branches    13864    13864           
=======================================
  Hits        35715    35715           
  Misses       1586     1586           
  Partials      660      660           

🚀 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-10 03:12:21 UTC}

2 files · 1 AI reviewer · no blockers · readiness 100/100 · CI green · unknown

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This is a test-only PR that adds a behavioral contract/parity suite for the CLI-subprocess and Agent-SDK CodingAgentDriver implementations, plus wires a new test:driver-parity script into test:ci — no production code (src/**) is touched. The design mirrors the existing engine-parity.test.ts pattern: a DRIVER_HARNESSES table drives identical scenario fixtures (success/clean_failure/budget_exhausted) against both drivers via injected fakes, asserting result-shape and edge-case parity rather than byte-identical output, which is the right approach given the two backends are inherently non-deterministic. The PR closes the linked issue #4296, the diff matches the description, and CI (including typecheck, which would fail if the imported driver symbols didn't exist) is green.

Nits — 5 non-blocking

• test/contract/coding-agent-driver-parity.test.ts: the 'documented divergences' describe block indexes DRIVER_HARNESSES[0]!/[1]! positionally to pick the CLI vs SDK harness — a future reorder of the array silently swaps which driver each assertion targets; look up by `h.name.includes("cli-subprocess")` instead.
• packages/gittensory-miner/docs/coding-agent-driver.md still states the CLI-subprocess (feat(miner-hands): CLI-subprocess CodingAgentDriver (reuse SpawnFn/redactSecrets/EFFORT_TIMEOUT_MS pattern) #4266) and Agent-SDK (feat(miner-hands): Agent-SDK CodingAgentDriver (query() loop) #4267) drivers 'are the seam's first concrete implementations; until they land, createCodingAgentDriver resolves the built-in noop driver' — since this suite imports and exercises both as real exports, confirm that doc isn't stale (or update it alongside this PR) so it doesn't mislead future contributors about driver availability.
• The suite validates cwd-scoping and verbatim-instruction-forwarding only for the 'success' behavior branch in each harness (make("success")) — consider asserting the same scoping contract on the failure/budget-exhausted paths too, since a driver could plausibly diverge on cwd handling only in an error branch.
• Add a lookup helper (e.g. `const harnessByName = (needle) => DRIVER_HARNESSES.find(h => h.name.includes(needle))!`) for the 'documented divergences' block instead of positional indexing.
• Consider a short comment or CI-workflow confirmation that `validate`/CI actually invokes `test:ci` (and therefore `test:driver-parity`) rather than only `typecheck` + `test:coverage`, since the latter may not execute test/contract/** by default — worth a one-line note so future readers know this suite is exercised in CI.

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

Linked issue satisfaction

Addressed
The diff adds test/contract/coding-agent-driver-parity.test.ts running the same success/clean_failure/budget_exhausted fixtures against both injected drivers via a DRIVER_HARNESSES table, asserts shape-only contract fields, verifies working-directory scoping and verbatim instruction forwarding, covers the #4271 empty-criteria case, checks caller-side event-sequence interchangeability through invok

Review context

• Author: reyanthony062001-ops
• 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: 25 PR(s), 1 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

[loopover-orb]

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