fix(queue): surface a finding when capture-unobtainable degrades the screenshot-table gate

[bitfathers94]

fix(queue): surface a finding when capture-unobtainable degrades the screenshot-table gate

maybeAddScreenshotTableAdvisoryFinding early-returned on any action other than
"advisory", so a close/block gate degraded by the #9881 capture-unobtainable
check never appended a finding anywhere -- the close/hold comment that would
have said so doesn't fire on the degraded path either, leaving the maintainer
with no visibility that their gate is unsatisfiable. Thread captureUnobtainable
into the function and its evaluateScreenshotTableGate call, and only early-
return on a non-advisory action once enforcement wasn't degraded.

Closes #10060

[loopover-orb]

Tip

✅ LoopOver review result - approve/merge recommended

_{Review updated: 2026-07-31 14:41:19 UTC}

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

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR wires captureUnobtainable through maybeAddScreenshotTableAdvisoryFinding and its evaluateScreenshotTableGate call, changing the early-return from 'action !== advisory' to 'not enabled', then branching on result.enforcementDegradedReason before falling back to the original advisory-only gate. The logic correctly surfaces a degraded-gate finding for close/block actions (previously silently dropped) while leaving the pre-existing advisory-mode and non-degraded-close behavior byte-identical, and the accompanying tests exercise close/block/advisory permutations plus the disabled and error-swallowing paths. The captureUnobtainable/enforcementDegradedReason plumbing itself (evaluateScreenshotTableGate's signature) predates this diff per the existing #9881 test suite, so this PR is a narrow, well-targeted wiring fix rather than new gate logic.

Nits — 6 non-blocking

• src/queue/processors.ts:8944-8970 nests three sequential early-return/continue conditions (violated, degraded, non-advisory) inside one try block — a short comment above the degraded branch stating the fallthrough contract would help future readers avoid re-introducing the original bug.
• The captureUnobtainable comment in the call site at src/queue/processors.ts:12332 asserts it 'cannot disagree' with runAgentMaintenancePlanAndExecute's own expression, but that call site's expression itself is not visible in this diff, so this claim can't be independently verified from what's shown here.
• test/unit/screenshot-table-gate.test.ts's close/block wiring tests assert `screenshotTableEvidenceUnresolved: false` is hardcoded rather than derived from the real caller's degraded-state computation, so they pin the planner's response to a claimed fact rather than proving the real caller actually produces that fact.
• Consider extracting the `result.enforcementDegradedReason !== undefined` branch's early-return-with-push into a small named helper shared with the non-degraded advisory branch below it, since both construct near-identical AdvisoryFinding objects with only `detail`/`title` differing.
• The `let files = args.files; if (files === null) { ... }` rewrite (replacing `??`) is explained as a coverage workaround in the comment — worth double-checking with Codecov after merge that it actually resolves the phantom-0-hit issue described, since the two forms are logically equivalent for a non-optional `X | null` field.
• Readiness score is below the configured threshold — Use the readiness panel as advisory maintainer context; the score does not block this PR.

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	#10060
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	⚠️ 12/25	Preflight needs author follow-up before maintainer review.
Contributor workload	✅ 10/10	Author activity: 140 registered-repo PR(s), 99 merged, 3 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	bitfathers94; Gittensor profile; 140 PR(s), 3 issue(s).
Improvement	✅ Minor	risk: clean · value: minor · LLM: moderate

Linked issue satisfaction

Addressed
The diff threads captureUnobtainable into maybeAddScreenshotTableAdvisoryFinding and its evaluateScreenshotTableGate call, changes the early-return to only skip on non-advisory action when not degraded, appends a warning-severity finding combining the gate's reason and CAPTURE_UNOBTAINABLE_REASON on the degraded path regardless of action, and updates the call site at the visual-capture check to pa

Review context

• Author: bitfathers94
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: TypeScript
• Official Gittensor activity: 140 PR(s), 3 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Start here: Add a concise scope and risk note.
• Then work through the remaining 2 steps 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

[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 81.38%. Comparing base (5b24374) to head (5c9a846).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #10256      +/-   ##
==========================================
+ Coverage   80.60%   81.38%   +0.77%     
==========================================
  Files         283      284       +1     
  Lines       59101    62589    +3488     
  Branches     7000     8286    +1286     
==========================================
+ Hits        47641    50937    +3296     
- Misses      11167    11234      +67     
- Partials      293      418     +125     

Flag	Coverage Δ
backend	94.49% <100.00%> (?)

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

Files with missing lines	Coverage Δ
src/queue/processors.ts	94.49% <100.00%> (ø)

[loopover-orb]

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