feat: npm run audit — read-only drift detector for state/dashboard divergence

[dhruva-reddy]

Summary

Adds npm run audit -- <org> — a single-command read-only diagnostic for the state-vs-dashboard drift conditions that have been silently accumulating in customer-fork repos (orphan tools, byte-identical assistant clusters, state ghosts, etc.).

7 checks:

Rule	Severity	What it catches
orphan-yaml	warn	Local YAML files with no state entry (Scenario B: dashboard-rename leftovers)
state-ghost	warn	State entries pointing at UUIDs the dashboard no longer has
state-uuid-collision	error	Multiple slugs in state pointing at the same UUID (cascade-bug fingerprint)
content-identical	warn	Multiple slugs sharing the same lastPulledHash (PR #19 enables this)
sibling-base-slug	warn	Multiple slugs sharing the same base-slug — cascade-duplicate risk warning
dashboard-orphan	warn	Dashboard UUIDs not in state (suppressed by .vapi-ignore patterns)
inline-tools	warn	Assistants with non-empty model.tools blocks — suspected duplicate-spawn surface
fetch-failed	warn	A specific resource type's dashboard fetch threw; other types proceed normally

Exit code: 0 if clean, 1 on any finding. Safe to wire into CI.

Design: DI surface for stateLoader / listLocalIds / remoteFetcher / readAssistantTools — tests are filesystem-free and network-free. Mirrors validate-cmd.ts / validate.ts structure.

Concurrency: per-type dashboard fetches use Promise.allSettled so a transient API hiccup on one type emits a fetch-failed finding and skips the remote checks for that type instead of aborting the whole audit.

Why now

Today's manual cleanup on a customer-fork repo (mudflap-prod) drained 13 orphan endCall tool UUIDs and 7 duplicate assistant UUIDs across two orgs — a ~30-minute cross-reference exercise involving Node scripts, dashboard API calls, and YAML grep. The same cleanup pattern is needed for other customer forks (gitops-amazon3p, gitops-notable). This command makes it a single read.

Files changed

File	Type	LOC
src/audit.ts	new	~490
src/audit-cmd.ts	new	~115
tests/audit.test.ts	new	~615 (28 tests, all passing)
src/pull.ts	edit	1 word (function → export function listExistingResourceIds)
package.json	edit	+1 script
README.md	edit	+1 command-table row

Test plan

• npm run build — clean
• npm test — 156 / 156 pass (28 new tests for audit, 128 prior)
• npx @biomejs/biome check --write — clean
• Smoke-run against in-memory synthetic state (collision + identical-hash + sibling-base + inline-tools + orphan-yaml): all 6 expected findings fire with correct severity bar and grouped output
• Operator dogfood against a real customer-fork repo (planned for gitops-amazon3p as the next user)

Residual risks / known follow-ups

Surfaced during the code-review phase (non-blocking, deferred):

1. credentials state section is intentionally not audited — VALID_RESOURCE_TYPES omits it by design, so the audit skips it silently. If credentials ever drift in state, audit won't detect. (Documented at the top of src/audit.ts.)
2. Inline-tools rule swallows YAML parse failures — an unparseable assistant YAML produces zero inline-tools findings. validate catches parse errors via a separate code path. Could be promoted to its own unparseable-assistant rule in a follow-up.
3. .vapi-ignore patterns must use slug form to suppress dashboard-orphan findings — bare UUIDs in .vapi-ignore won't work. Real-world .vapi-ignore content uses slug form, so unlikely to bite.
4. No --summary flag yet — on a 200-assistant fork with deep drift, a single rename can produce 3–4 findings for one logical issue. Future v2 could collapse per-resource-id.
5. No --fix flag — v1 is read-only by design; deletion stays a manual delete files → push → API-delete → pull sequence per safety.
6. Per-rule JSDoc comments missing — top-of-file comment lists all 7, but each checkX function could use a 1-line invariant doc. Mechanical follow-up.

Diagnostic context

This command is part of a broader investigation into duplicate-tool / duplicate-assistant drift in customer-fork repos. A separate vapi-core ticket is being filed against the dashboard UI's assistant-editor save handler, which is the leading suspect for the spawn-source (see customer-fork improvements.md revision for the full diagnosis history).