feat(miner-hands): two-tier stalled-output fast-fail timeout for the CLI-subprocess driver (#5167)

[joaovictor91123]

Summary

• packages/gittensory-engine/src/miner/cli-subprocess-driver.ts's createCliSubprocessCodingAgentDriver currently wires only a single flat timeoutMs with no first-output liveness signal. Ports the proven firstOutputTimer/resolveClaudeFirstOutputTimeoutMs pattern from src/selfhost/ai.ts -- built specifically because a naive single-timeout design caused a real production outage against the identical claude/codex binaries (fix(review): claude-code subscription-CLI hangs/times out repeatedly (4,030 Sentry events, ongoing) #4994/fix(selfhost): claude-code fast-fail timeout false-positives on --output-format json (buffered, non-streaming) #5053).
• CliSubprocessDriverOptions gains an optional firstOutputTimeoutMs. CliSubprocessSpawnFn's opts/return shape grows to match (firstOutputTimeoutMs in, stalledNoOutput out), mirroring src/selfhost/ai.ts's SpawnFn exactly.
• When the injected spawn reports timedOut && stalledNoOutput, the driver returns a distinct ${command}_stalled_no_output error (never reusing ${command}_timeout_...) -- so a hung CLI with zero stdout is separately countable in logs from a genuine full timeout where output was at least flowing.
• Opt-in and backward compatible: when firstOutputTimeoutMs is omitted, it is not even forwarded to spawn's opts, so behavior is byte-for-byte unchanged from before this option existed.
• Scoped strictly to the driver's own subprocess handling: no attempt/governor state is read or written, no retry/requeue decision is made -- the driver only reports which timeout fired, same as it always has.

Test plan

• npx vitest run test/unit/cli-subprocess-driver.test.ts -- 11/11 passing, including the new describe("two-tier stalled-output fast-fail timeout (#4994/#5053)", ...) block: zero-stdout stall (killed early, distinct error), live-output-before-deadline (not misclassified as a stall), output-arrived-but-never-exited (existing full-timeout behavior preserved unchanged -- the regression guard), omitted-option backward compatibility, and an invariant asserting the result never carries any field beyond the CodingAgentDriverResult contract (no attempt/governor state leak).
• npx vitest run test/contract/coding-agent-driver-parity.test.ts -- 18/18 passing (unaffected).
• npx vitest run test/unit/coding-agent-miner.test.ts -- 57/57 passing (unaffected; this driver's consumers didn't need changes).
• npm --workspace @jsonbored/gittensory-engine run build -- clean.
• npm run typecheck -- clean.
• Isolated coverage via COVERAGE_NO_THRESHOLDS=1 npx vitest run test/unit/cli-subprocess-driver.test.ts --coverage --coverage.include="packages/gittensory-engine/src/miner/cli-subprocess-driver.ts" -- 100% statements/branches/functions/lines.
• npm run docs:drift-check -- clean.
• 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 #5167.

[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.34%. Comparing base (e6adb43) to head (c084c0f).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5251   +/-   ##
=======================================
  Coverage   94.34%   94.34%           
=======================================
  Files         473      473           
  Lines       39982    39985    +3     
  Branches    14576    14578    +2     
=======================================
+ Hits        37722    37725    +3     
  Misses       1585     1585           
  Partials      675      675           

Flag	Coverage Δ
shard-1	46.43% <100.00%> (+<0.01%)	⬆️
shard-2	34.59% <0.00%> (-0.01%)	⬇️
shard-3	32.17% <0.00%> (+0.08%)	⬆️
shard-4	32.08% <0.00%> (-0.03%)	⬇️
shard-5	33.71% <0.00%> (-0.10%)	⬇️
shard-6	44.85% <0.00%> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...ttensory-engine/src/miner/cli-subprocess-driver.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-12 11:49:42 UTC}

2 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 two-tier timeout to the CLI subprocess driver: an early `firstOutputTimeoutMs` fast-fail path distinct from the existing full `timeoutMs`, mirroring the pattern already proven in src/selfhost/ai.ts. The wiring is correct — the new field is only spread into spawn opts when defined (preserving byte-identical behavior when omitted), the stalled branch is checked before the generic timeout branch, and the error/summary strings are distinct and non-colliding. Tests cover the stall path, the live-output-before-deadline non-misclassification, the regression guard for output-arrived-but-never-exited, opt-in omission, and a result-shape invariant — all exercising the driver's actual branches rather than fabricated states.

Nits — 5 non-blocking

• The driver itself doesn't clamp `firstOutputTimeoutMs` below `timeoutMs` the way `src/selfhost/ai.ts` does (`Math.min(..., timeoutMs - 1)`) — since the real clamping happens in the spawn implementation/caller here, consider a one-line doc note in cli-subprocess-driver.ts:52 clarifying that the driver trusts the caller to pass a sane value, so a future caller doesn't assume the driver enforces the invariant.
• The summary string `${options.command} stalled with no stdout within ${options.firstOutputTimeoutMs}ms` (cli-subprocess-driver.ts:126) will silently print 'undefined' if `stalledNoOutput` is somehow set without `firstOutputTimeoutMs` being passed to spawn — not reachable via this driver's own logic today, but worth a defensive comment given it's an injected/fake-testable seam.
• Consider asserting in a test that when `firstOutputTimeoutMs` is omitted, `stalledNoOutput` is never interpreted (i.e., a fake spawn that ignores the opt-in and returns `stalledNoOutput: true` anyway still produces a stalled result) — currently that's implicit rather than explicitly guarded against by contract.
• nit: `packages/gittensory-engine/src/miner/cli-subprocess-driver.ts:121` forwards any numeric `firstOutputTimeoutMs`, so a caller can pass `0`, a negative value, or a value greater than/equal to `timeoutMs`, which undercuts the documented two-tier behavior even though it is not a reachable break from this diff alone.
• nit: `test/unit/cli-subprocess-driver.test.ts:132` says live output is never mistaken for a stall, but the fake spawn does not simulate first-output timer clearing; this is only testing that the driver trusts the spawn result when `stalledNoOutput` is absent.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#5167
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: 117 registered-repo PR(s), 68 merged, 11 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	joaovictor91123; Gittensor profile; 117 PR(s), 11 issue(s).
Gate result	✅ Passing	No configured blocker found.
Improvement	✅ Minor	risk: clean · value: minor — Code changes are accompanied by test evidence.

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: 117 PR(s), 11 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.

[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