refactor(handlers): encode failure in best-effort lookups — 13 silent-success-masking sites (#756 Cat 2)

[ClintEastman02]

Follow-up to #756 (Category 2 from @scottschreckengaust's triage on #756). Part of #756.

Problem

Best-effort network/DDB reads whose null/[] return collapses "not found" into "lookup broke". Each already logs, so the failure is observable — but not actionable by the caller, and where these feed orchestration state a swallowed read changes control flow, not just presentation.

Sites (verified on the PR #788 branch)

Fix first — cdk/src/handlers/orchestration-reconciler.ts:1455: a bare catch { return null; } with no logging at all (the pr_url read above resolvePrNumber). Strictly worse than its neighbours.

Cheap — widen the return type to encode failure:

• cdk/src/handlers/shared/slack-api.ts:112 — null conflates "no ts returned" with "Slack unreachable"
• cdk/src/handlers/shared/linear-feedback.ts:280 — GraphQL transport failure ≡ empty data
• cdk/src/handlers/shared/linear-subissue-fetch.ts:333 — "no parent" ≡ "parent lookup failed"; parent-vs-sub routing depends on this
• cdk/src/handlers/shared/jira-feedback.ts:372 and :395 — transition lookup; :395 masks invalid JSON from Jira, a distinct class from a network timeout
• cli/src/commands/linear.ts:1721 — queryLinearTeamKeys returns []; caller can't tell "no teams" from "auth failed"

Medium — these feed orchestration state (control flow, not presentation):

• cdk/src/handlers/orchestration-reconciler.ts:1476 and cdk/src/handlers/linear-webhook-processor.ts:2757 — duplicated resolvePrNumber/resolveChildPrNumber (identical body, both swallow). Extract to one shared helper while fixing so the fix lands once.
• cdk/src/handlers/orchestration-reconciler.ts:471 — combined screenshot read
• cdk/src/handlers/shared/orchestration-rollup.ts:490 — epic panel upsert; null → "no panel id" → next edit silently posts fresh
• cdk/src/handlers/github-webhook-processor.ts:448 — findIterationReplyId; a masked failure → duplicate top-level comment instead of a threaded edit (user-visible symptom)
• cdk/src/handlers/linear-webhook-processor.ts:532 — iteration ack reply

Fix

Widen return types to encode failure (discriminated result / typed error), dedupe the two resolvePrNumber copies, and add logging to :1455. Add an inline nosemgrep only where the empty value is genuinely the contract (none expected in this bucket).

Related

• bug(infra): webhook processors silently discard admitted events — no DLQ + transient DDB failure misread as "tenant not onboarded" #734 — webhook processors silently discard admitted events (adjacent masking class on the admission path)

_{Line numbers verified against the PR #788 branch. Credit: triage by @scottschreckengaust on #756.}

[ClintEastman02]

Note from #791 triage: cdk/src/handlers/shared/orchestration-store.ts parsePreScreenedAttachments (~L334) belongs here rather than in #791. A corrupt pre_screened_attachments_json currently returns [] (logged at warn) and releases children with attachments silently dropped. This is fail-safe for screening (no unscreened content passes) so it's not the Cat 1 attribution-erasure concern — recommend encoding the failure via error-level log + a metric so the corrupt state is observable/alertable, without changing the deliberate 'children still run' availability behavior.

[ClintEastman02]

Starting implementation. Branch: chore/792-encode-failure-lookups (off main @ 12c9b63). Approach per the issue: widen best-effort read return types to encode failure (discriminated result / typed error), dedupe the two resolvePrNumber/resolveChildPrNumber copies into one shared helper, add the missing logging to the bare catch at orchestration-reconciler.ts:1455, and add inline nosemgrep only where the empty value is genuinely the contract.