fix(visual): only mark capture structurally-unobtainable on a proven, not a failed, read

[RealDiligent]

Summary

previewUnobtainable / visual_capture_unobtainable_sha (#9881) records a proven fact — its migration and both JSDoc contracts say so: "the deployments read succeeded, reported no deployment whatsoever (not a failed one, not an API error), and the poll budget is spent." The screenshot-table gate degrades its CLOSE to advisory on it. But the code never enforced that:

• getPreviewBuildState returns "absent" on any read failure (preview-url.ts:334, fail-safe: never infinite-poll), and
• getLatestDeploymentStatus reports a non-404 failure (403 / rate-limit / 5xx) as { error: true }, which buildCapture ignored.

So a transient GitHub read failure was recorded as "this repo has no preview pipeline", degrading the gate on evidence the bot never actually obtained.

Fix

• getPreviewBuildState returns a new "unreadable" union member on a thrown read (its outer catch) — still a value, so the never-infinite-poll contract is preserved, but distinguishable from "absent" (a read that succeeded and found no build, which stays "absent"). Doc updated.
• buildCapture treats "unreadable" exactly like "absent" for polling / previewFailed (poll count unchanged), tracks whether getLatestDeploymentStatus reported error: true (or threw), and sets previewUnobtainable = true only when the check-run read genuinely succeeded empty ("absent") and the deployments read succeeded.

markPullRequestVisualCaptureUnobtainable, the gate evaluator, the poll budget, and previewPending/previewFailed/renderFailed for every both-reads-succeeded case are byte-identical.

Tests

Added to test/unit/visual-capture.test.ts: a rejecting check-runs read at an exhausted budget → previewUnobtainable: false, previewPending: false; a succeeding-empty check-runs read at an exhausted budget → previewUnobtainable: true (#9881 pinned); a rejecting deployments read with a succeeding-empty check-runs read → previewUnobtainable: false; and a sustained read failure across the whole budget → never true. test/unit/preview-url.test.ts: a later-page read failure now yields "unreadable", a completed empty read stays "absent".

The read-failure cases fail against the current "absent"-on-any-error code. Coverage of the changed lines is complete.

Closes #10059

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[loopover-orb]

Tip

✅ LoopOver review result - approve/merge recommended

_{Review updated: 2026-07-31 08:31:04 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR correctly narrows `previewUnobtainable` to only fire when both the check-runs read and the deployments read genuinely succeeded, by adding a new `unreadable` union member to `getPreviewBuildState` (distinct from the pre-existing `absent`) and tracking `deploymentsReadFailed` in `buildCapture`. The trace is sound: `getPreviewBuildState`'s catch previously collapsed both a proven-empty read and a thrown read into `absent`, which fed directly into the `previewUnobtainable = true` assignment at capture.ts — the fix correctly moves the check to the actual source of the ambiguity rather than patching a symptom. Tests exercise the real code paths (rejecting fetches, sustained failure across the poll budget, a failing deployments read alongside a succeeding empty check-runs read) rather than fabricating unreachable states, and the `absent`-still-succeeds pinned test guards against regressing #9881.

Nits — 4 non-blocking

• capture.ts:707-780 is part of an already-long file (~781 lines per the size-smell note); consider hoisting the preview-discovery block into its own function in a follow-up rather than growing it further inline.
• The `deploymentsReadFailed` flag name could be read as 'the deployments read itself failed as a boolean outcome' vs 'we observed a failure signal (error:true or throw)'; a short inline comment already covers this so it's a very minor naming nit only.
• Consider whether `getLatestDeploymentStatus`'s `error: true` case and its thrown-exception case could be unified at that call's own boundary (return `{error: true}` uniformly) so `buildCapture` doesn't need to track failure via two different code paths (try/catch plus a status field).
• The PR description references issue visual(capture): stop marking capture "structurally unobtainable" when the preview reads merely failed #10059 and The screenshot-table gate can close PRs for evidence the bot is structurally unable to produce #9881 for context — worth confirming the PR body itself includes an explicit 'Closes visual(capture): stop marking capture "structurally unobtainable" when the preview reads merely failed #10059' style linkage per repo convention.

Decision drivers

• ✅ Code review — No blockers (1 reviewer)
• ✅ Gate result — Passing (No configured blocker found.)

Context & advisory signals — never blocks the verdict

Signal	Result	Evidence
Linked issue	✅ Linked	#10059
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
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: 239 registered-repo PR(s), 89 merged, 38 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	RealDiligent; Gittensor profile; 239 PR(s), 38 issue(s).
Improvement	✅ Minor	risk: clean · value: minor · LLM: moderate

Linked issue satisfaction

Addressed
The diff adds an 'unreadable' terminal state to getPreviewBuildState for thrown reads while preserving 'absent' for genuine empty finds, tracks deployments-read failure via both error:true and thrown catch, and only sets previewUnobtainable=true when both reads genuinely succeeded (absent + no deployments failure), matching the issue's core requirements with targeted regression tests.

Review context

• Author: RealDiligent
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Python, Ruby, TypeScript, Svelte, Cuda, JavaScript, Markdown, MDX
• Official Gittensor activity: 239 PR(s), 38 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Start here: Add a concise scope and risk note.
• Then work through the remaining 1 step in the Signals table above.

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.

🧪 Chat with LoopOver

Ask LoopOver a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @loopover ask <question> answers contribution-quality Q&A with source citations and freshness.
• @loopover chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @loopover mention with a real question is routed to the closest matching read-only command automatically — no exact syntax required.

Full command reference: https://loopover.ai/docs/loopover-commands

🧪 Experimental — new and may change.

_{🟩 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 LoopOver, a quiet PR intelligence layer for OSS maintainers.

• Re-run LoopOver review

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 79.90%. Comparing base (9f673b8) to head (1c83559).
⚠️ Report is 14 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff             @@
##             main   #10129       +/-   ##
===========================================
- Coverage   91.95%   79.90%   -12.05%     
===========================================
  Files         931      284      -647     
  Lines      113921    59105    -54816     
  Branches    27504     8829    -18675     
===========================================
- Hits       104757    47230    -57527     
- Misses       7863    11574     +3711     
+ Partials     1301      301     -1000     

Flag	Coverage Δ
backend	95.90% <100.00%> (+0.23%)	⬆️

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

Files with missing lines	Coverage Δ
src/review/visual/capture.ts	96.37% <100.00%> (+0.05%)	⬆️
src/review/visual/preview-url.ts	94.96% <100.00%> (ø)

... and 780 files with indirect coverage changes

[loopover-orb]

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