fix(audit): close ten oxaudit findings across CLI, config and docs

[ojassug]

Lane A of the oxaudit.md split (2026-08-23, ox-alpha). Ten findings closed across five commits.
Lane B — the Gateway half (H2, H4, M1, M5, M8, M9 and five lows) — is unstarted and untouched here;
oxaudit-split.md carries the partition and the reason for it.

The cut is by file ownership, not severity: nothing in this branch touches
src/gateway/{proxy,server,session-store,types}.ts, stages/cleanup/session-dedup.ts,
stages/compression/token-hashing.ts, adapters/mcp/server.ts or bench/fixtures/loader.ts.

What's in it

Commit	Findings
ca104d4	H3 — vitest collected suites from other checkouts
76f5398	H1 — exec discarded the child exit code
84bdf5e	M2, M3, M14 — multi-file route accepted flags it dropped
b3f02f9	M4, M16 — directory ingestion (+L4 recorded, not fixed)
24712b9	M10, M11, M12 — config validation, ARCHITECTURE drift, stale comment

Three things worth reading the diff for

H1 was half a fix until the last moment. package.json's bin points at dist/src/cli/main.js,
so the shipped command runs the require.main === module block at the foot of main.ts — not the
exported main() that every test calls. The two had drifted into separate copies of the same
assignment, and the shipped copy carried a typeof exitCode === 'number' guard that was harmless
dead code while runCli always returned a number. The moment exec returned a promise it became a
silent drop: the installed binary would have gone on exiting 0 with the entire suite green. The
block now delegates to main(), and the test pins the delegation as well as the codes. Verified on
the built binary: 0→0, 3→3, 42→42, unresolvable command→1.

M3 is worse than the audit describes, and its part (a) is not a defect. --input-name does not
silently no-op on a directory — parseArguments already throws for any non-- input path (pinned so
it stays true). But blanket --language over a mixed tree moved languageSupport from "1 unsupported
(json)" to "3 supported, 0 unsupported", left astCoverage reading unchecked: 0 because the
Python validator genuinely did look at the JSON, and fell the whole run back. A coverage report
that lies with a guaranteed 0% behind it, so it is refused rather than documented.

M10 had three doors. The audit named TOKENDAMPER_MINIMUM_CONFIDENCE; the CLI flag carried the
identical Number.isFinite-and-nothing-else check and the config file was type-checked as bare
number. All three validate now.

Verification

Every behavioral fix was confirmed failing against the unfixed tree first. The two config-only
fixes were mutation-checked rather than assumed:

• H3's guard: widening the include, dropping .claude from exclude, deleting the config, and
  planting a suite outside test/ each fail it.
• M11's guard derives the documented stage lists from the planner; all four cases fail against the
  previous text.

Rebased onto main after #34 landed. npm run typecheck, npm run lint, npm run build and
npx vitest run all pass: 83 files / 769 tests.

Deliberately not fixed

L4 — symlinks are skipped in a directory walk but followed when named directly. Recorded at its
site with the reason: creating a symlink in the environment this was written in returns EPERM
without elevation, and shipping an unverified change to the code that decides which files reach the
pipeline is the trade this project keeps declining. Skipping omits a file; it never corrupts one.

Two notes for whoever takes Lane B

• tools/corpus-harness/measure.js passes --trace-output stderr, so withdrawing that flag under
  H5 breaks the harness. Worth knowing before the implement-vs-withdraw call.
• The changelog now cites OX-* IDs throughout, but oxaudit.md is not committed (unlike
  max_audit.md), so those references currently dangle.

🤖 Generated with Claude Code