Summary

Add a CI-enforced check that fails when any symbol defined as a "stub" (unconditional-throw or silent-neuter return) has live non-test callers. Prevents recurrence of the class documented in #2408 and #2337.

Rationale

Both #2408 (unconditional-throw regression) and #2337 (silent-neuter regressions — Telegram vision, node-host skills, TUI listModels) shipped because:

• TypeScript accepts never-return functions and empty-return stubs anywhere a compatible signature is expected.
• Unit tests mock the stub, so the integration-level error is invisible.
• No lint rule forbids the pattern.

A CI gate closes this hole without relying on reviewer vigilance or memory of the anti-pattern.

Detection scope

Minimum target: (..._args: unknown[]): never { throw ... } with live non-test callers.

Stretch target: silent-neuter forms (=> false, => [], => {}, => undefined) explicitly marked as upstream-compat stubs (e.g., via a // Gutted in RemoteClaw fork comment convention, a @upstream-stub JSDoc tag, or similar).

Implementation options (choose during design phase)

1. oxlint custom rule — AST-based detection. Check whether the repo's oxlint setup supports custom rules.
2. Script in scripts/ — invoked from pnpm check or a dedicated pnpm lint:stubs step in CI. Grep for pattern + caller graph, fail on live non-test callers.
3. Brand-type phantom parameter — give stubs a never-typed phantom parameter callers cannot satisfy. Most invasive; fallback only.

Acceptance criteria

• Detection pattern defined and documented (AST rule or grep + caller graph).
• Check integrated into CI (.github/workflows/ci.yml required check or pnpm check pipeline).
• Self-test evidence in PR: introducing a fake stub+caller pair causes the check to fail.
• False-positive budget: check passes on main after fix(agents): restore resolveAgentRuntimeOrThrow body — regression stub crashed every agent dispatch #2408 and audit(agents): inventory throwing-stubs-with-live-callers across src/ #2409 findings resolved.
• Documentation (CLAUDE.md or CONTRIBUTING) explaining the pattern and the legitimate way to add a no-caller upstream-compat stub.

Related

• Evidence: fix(agents): restore resolveAgentRuntimeOrThrow body — regression stub crashed every agent dispatch #2408 (unconditional-throw regression), gut: re-apply provider/model cascade after v2026.3.7 sync regression (~19 files) #2337 (silent-neuter regressions).
• Parallel prevention: Audit: upstream fixes silently lost in sync (v2026.2.25 → v2026.3.22, 32 gaps) #2406 INCLUDE Reconciliation Gate (covers lost-files class, not stub-with-callers class).
• Informed by: audit(agents): inventory throwing-stubs-with-live-callers across src/ #2409 (audit findings calibrate detection pattern and establish the false-positive floor).

Dependencies

• Soft dependency on audit(agents): inventory throwing-stubs-with-live-callers across src/ #2409 output for detection-pattern calibration. Can start with a conservative grep-based heuristic and tighten after audit(agents): inventory throwing-stubs-with-live-callers across src/ #2409 lands.