feat(miner-hands): resolve concrete CLI/SDK providers in the CodingAgentDriver factory

[reyanthony062001-ops]

Closes #4289

What

The CodingAgentDriver factory (packages/gittensory-engine/src/miner/driver-factory.ts) now resolves the batch's two concrete implementations — claude-cli/codex-cli (the #4266 CLI-subprocess driver) and agent-sdk (the #4267 in-process driver) — alongside the existing noop stub, structurally mirroring resolveConfiguredProviderNames/isConfiguredSelfHostProvider (src/selfhost/ai-config.ts:41-74).

How it maps to the issue's deliverables

• Provider-name → driver factory: createCodingAgentDriver gains the three concrete arms. All provider names are locally-authenticated (no API-key requirement), so they are always-configured at the NAME level — mirroring how isConfiguredSelfHostProvider treats claude-code/codex.
• Config-resolution map, with every declared key CONSUMED: CODING_AGENT_DRIVER_CONFIG_ENV maps claude-cli/codex-cli to MINER_CODING_AGENT_{CLAUDE,CODEX}_MODEL + MINER_CODING_AGENT_TIMEOUT_MS — and the factory actually reads them: the configured model is prefixed onto the CLI driver's exported default argv (defaultCliSubprocessArgs, exported rather than re-invented so the baseline argv can't silently drift), and the timeout (positive-integer-validated) lands on the driver's timeoutMs. Deliberately NOT declared (documented in the map's comment): a max-turns key (that's task-level input, CodingAgentDriverTask.maxTurns) and an agent-sdk model key (the SDK session uses the account default; the driver exposes no model option today) — a declared-but-unread entry would be dead, misleading config-as-code surface.
• Deny-by-default / fail-closed: unknown names still throw unconfigured_coding_agent_driver:<name> via the default: return false arm; additionally, a CLI provider constructed without its required spawn dependency throws unconfigured_coding_agent_driver_missing_spawn:<name> (the engine ships no default spawn — never hand back a driver whose every run() would throw), matching resolveAutonomy's deny-by-default precedent.
• Fallback chain: resolveFirstConfiguredCodingAgentDriverName gives primary-then-fallback resolution over MINER_CODING_AGENT_PROVIDER's comma-separated list (the AiRunOptions.fallback semantic at the resolution layer); an all-unknown list resolves to undefined so callers fail closed. Per-repo overrides (.gittensory-miner.yml-sourced) are noted as a follow-up in code comments — that file sits outside the Worker's manifest plumbing today, so only the env layer is wired here (the firstConfigured value-priority helper is in place for it).
• runCodingAgentAttempt threads the new provider deps (spawn/query/hooks/knownSecrets) end-to-end.

Testing

13 new vitest cases in test/unit/coding-agent-miner.test.ts (the codecov-measured path) + a mirrored set in the engine's own node:test suite: every provider arm, model-env consumption asserted in the spawned argv (set, unset, whitespace-only), per-provider model keys isolated (codex ignores claude's), timeout consumption incl. all invalid-value fallbacks, missing-spawn fail-closed for both CLI providers, knownSecrets redaction pass-through, agent-sdk hooks forwarding + no-deps construction, name normalization, primary-then-fallback + fail-closed resolution, and an end-to-end runCodingAgentAttempt run. Changed-line coverage verified 100% (lines + branches) on both touched engine files; engine workspace suite 338/338, root typecheck and git diff --check clean.

[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.13%. Comparing base (8f9f2cb) to head (112f470).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4593   +/-   ##
=======================================
  Coverage   94.12%   94.13%           
=======================================
  Files         430      430           
  Lines       38178    38199   +21     
  Branches    13920    13929    +9     
=======================================
+ Hits        35936    35957   +21     
  Misses       1585     1585           
  Partials      657      657           

Files with missing lines	Coverage Δ
...ttensory-engine/src/miner/cli-subprocess-driver.ts	100.00% <100.00%> (ø)
...ages/gittensory-engine/src/miner/driver-factory.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]

Caution

🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥🟥

🛑 Gittensory review result - reject/close recommended

_{Review updated: 2026-07-10 07:10:52 UTC}

5 files · 1 AI reviewer · 1 blocker · readiness 100/100 · CI green · unstable

🛑 Suggested Action - Reject/Close

• AI reviewers agree on a likely critical defect: packages/gittensory-engine/src/miner/driver-factory.ts:211-224 — `runCodingAgentAttempt` calls `createCodingAgentDriver(...)` (which throws `unconfigured_coding_agent_driver_missing_spawn:<name>` for claude-cli/codex-cli without `spawn`) before checking whether `mode` even executes
• per the documented lifecycle in coding-agent-driver.md, a dry-run/paused attempt should just log a shadow event without spawning, but now it crashes if the caller omits `spawn` for a non-live attempt — construct the driver lazily inside the `codingAgentModeExecutes(mode)` branch (or pass mode-awareness into the factory) so dry-run/paused attempts for CLI providers don't require a real spawn dependency. — Resolve the flagged defect, or override if the AI reviewers are mistaken, then re-run the gate.

Review summary
This PR wires the three concrete CodingAgentDriver providers (claude-cli, codex-cli, agent-sdk) into the factory, threading configured model/timeout env vars into the CLI driver's argv and failing closed on unknown providers or a missing spawn dependency for CLI providers. The config-consumption logic (model prefixing, positive-integer timeout parsing, per-provider env keys) is correct and well tested. However, `runCodingAgentAttempt` (driver-factory.ts) constructs the driver unconditionally before checking the resolved execution mode, so a `dry_run`/`paused` attempt with `claude-cli`/`codex-cli` and no injected `spawn` now throws instead of recording the documented shadow/no-op attempt-log event — a regression versus the prior `noop`-only behavior where driver construction never had external dependencies.

Blockers

• packages/gittensory-engine/src/miner/driver-factory.ts:211-224 — `runCodingAgentAttempt` calls `createCodingAgentDriver(...)` (which throws `unconfigured_coding_agent_driver_missing_spawn:<name>` for claude-cli/codex-cli without `spawn`) before checking whether `mode` even executes; per the documented lifecycle in coding-agent-driver.md, a dry-run/paused attempt should just log a shadow event without spawning, but now it crashes if the caller omits `spawn` for a non-live attempt — construct the driver lazily inside the `codingAgentModeExecutes(mode)` branch (or pass mode-awareness into the factory) so dry-run/paused attempts for CLI providers don't require a real spawn dependency.

Nits — 5 non-blocking

• No test exercises `runCodingAgentAttempt` in `dry_run`/`paused` mode with `providerName: 'claude-cli'`/`codex-cli'` and no `spawn` — only the live-mode path is covered (test/unit/coding-agent-miner.test.ts), so this exact regression branch has zero coverage.
• `firstConfiguredEnvValue` (driver-factory.ts) duplicates the `firstConfigured` helper documented at src/selfhost/ai.ts:117-134; fine per the package-boundary rationale in the comment, but worth extracting to a shared util if a third caller needs the same pattern.
• The `agent-sdk` case in `createCodingAgentDriver` doesn't accept `knownSecrets`/timeout config (by design, since `CODING_AGENT_DRIVER_CONFIG_ENV['agent-sdk']` is `{}`) — a one-line comment on that switch arm would save a future reader from wondering why it's silently dropped.
• Guard the `createCodingAgentDriver` call in `runCodingAgentAttempt` with the resolved mode (or make driver construction lazy) so `spawn`/`query` are only required when a run will actually execute, matching coding-agent-driver.md's stated dry-run contract.
• Add a `runCodingAgentAttempt` test with `providerName: 'claude-cli'`, `agentDryRun: true`, and no `spawn`, asserting it records a shadow event instead of throwing.

Why this is blocked

• packages/gittensory-engine/src/miner/driver-factory.ts:211-224 — `runCodingAgentAttempt` calls `createCodingAgentDriver(...)` (which throws `unconfigured_coding_agent_driver_missing_spawn:<name>` for claude-cli/codex-cli without `spawn`) before checking whether `mode` even executes; per the documented lifecycle in coding-agent-driver.md, a dry-run/paused attempt should just log a shadow event without spawning, but now it crashes if the caller omits `spawn` for a non-live attempt — construct the driver lazily inside the `codingAgentModeExecutes(mode)` branch (or pass mode-awareness into the factory) so dry-run/paused attempts for CLI providers don't require a real spawn dependency.

Signal	Result	Evidence
Code review	❌ 1 blocker	1 reviewer
Linked issue	✅ Linked	#4289
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: 26 registered-repo PR(s), 16 merged, 1 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	reyanthony062001-ops; Gittensor profile; 26 PR(s), 1 issue(s).
Gate result	❌ Blocking	Repo-configured hard blocker found.

Linked issue satisfaction

Addressed
The PR adds concrete claude-cli/codex-cli/agent-sdk arms to createCodingAgentDriver, a config-resolution env map that is actually consumed for model/timeout, deny-by-default handling for unknown/misconfigured providers (including a fail-closed missing-spawn case), and unit tests covering a valid provider, an unknown provider, and a primary-then-fallback resolution via resolveFirstConfiguredCodingA

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: 26 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 is closing this pull request on the maintainer's behalf (AI reviewers agree on a likely critical defect: packages/gittensory-engine/src/miner/driver-factory.ts:211-224 — `runCodingAgentAttempt` calls `createCodingAgentDriver(...)` (which throws `unconfigured_coding_agent_driver_missing_spawn:` for claude-cli/codex-cli without `spawn`) before checking whether `mode` even executes; per the documented lifecycle in coding-agent-driver.md, a dry-run/paused attempt should just log a shadow event without spawning, but now it crashes if the caller omits `spawn` for a non-live attempt — construct the driver lazily inside the `codingAgentModeExecutes(mode)` branch (or pass mode-awareness into the factory) so dry-run/paused attempts for CLI providers don't require a real spawn dependency.). This is an automated maintenance action — to pursue this change, please open a new pull request with the issues resolved. Closed PRs may be analyzed later to improve review accuracy, but they are not automatically reopened or re-reviewed.