Technical audit (2026-06): findings and improvement plan tracking

[thymikee]

Umbrella issue tracking the repository technical audit (v0.17.1, commit 1de7e73) and its improvement plan. The full audit document lives on branch claude/repo-technical-audit-tzr3ub (kept out of main so it doesn't go stale there).

Audit summary

Overall health: A−. Engineering hygiene well above the OSS norm: zero any in ~97k LOC of production TS, one runtime dependency, clean dead-code analysis, per-PR real-emulator smoke CI plus nightly device replays, hardened daemon security (loopback bind, per-boot 0600 token, tar/upload defenses). No Critical findings in product code.

Key findings (severity):

• High — src/daemon-client.ts (1,801 LOC) concentrates daemon lifecycle, transports, progress streaming, and artifact transfer; 4 functions grandfathered complexity-critical; only fragment-level tests. The most failure-prone path is the hardest to test.
• High — Largest platform modules have no direct unit tests: platforms/ios/apps.ts (1,231 LOC), compat/maestro/runtime-targets.ts (1,080), platforms/android/app-lifecycle.ts (920), client-metro.ts (995).
• High (re-rated from Medium: cloud deployment is near) — Sync zlib (inflateSync/deflateSync, src/utils/png-codec.ts) runs on the daemon event loop via screenshot overlay/diff, stalling all sessions during decode.
• Medium — Layering drift: 10+ src/daemon/ files and 5 src/platforms/ files import from src/commands/; the CLI surface has become a de facto shared contract layer.
• Medium — Lint/format were configured but not CI-enforced (fixed by ci: enforce lint and formatting, add warn-only layering guard #732).
• Medium — CVE-2026-9277 (shell-quote@1.8.3) in examples/test-app lockfile (fixed by fix(daemon): timing-safe token comparison, daemon.json hardening, shell-quote CVE #731).
• Low — non-timing-safe token compares and daemon.json chmod gap (fixed by fix(daemon): timing-safe token comparison, daemon.json hardening, shell-quote CVE #731), one TODO in snapshot-unchanged.ts:72 (stringify-based snapshot identity).

Maintainer decisions (2026-06-10): cloud is very near (security/perf items re-rated up); Maestro compat stays; no formal perf target ("faster is better"); fallow config should be tuned to reduce overrides; daemon-client split approved where it improves maintainability.

Quick wins — PRs

• fix(daemon): timing-safe token comparison, daemon.json hardening, shell-quote CVE #731 — fix(daemon): timing-safe tokens + daemon.json hardening + shell-quote CVE
• ci: enforce lint and formatting, add warn-only layering guard #732 — ci: lint/format enforcement + warn-only layering guard
• docs: document daemon trust model and auth hook threat model #733 — docs: daemon trust model + auth hook threat model

Milestone 0 — safety net (before refactoring)

• test: characterization tests for daemon-client lifecycle (M0-1) #723 — characterization tests: daemon-client lifecycle
• test: characterization tests for artifact upload resume/redirect and download abort (M0-2) #724 — characterization tests: artifact upload resume/redirect, download abort
• test: daemon HTTP server edge cases — cancellation, body cap, malformed envelopes (M0-3) #725 — daemon HTTP server edge cases

Milestone 2 — high leverage

• refactor: extract shared contracts out of src/commands so daemon/platforms stop importing the CLI layer (M2-2) #726 — extract shared contracts out of src/commands/ (lands before refactor: split daemon-client.ts into lifecycle / transport / progress / artifacts modules (M2-1) #727; flips layering guard to hard fail)
• refactor: split daemon-client.ts into lifecycle / transport / progress / artifacts modules (M2-1) #727 — split daemon-client.ts (blocked by test: characterization tests for daemon-client lifecycle (M0-1) #723, test: characterization tests for artifact upload resume/redirect and download abort (M0-2) #724, refactor: extract shared contracts out of src/commands so daemon/platforms stop importing the CLI layer (M2-2) #726)
• perf: move PNG decode and screenshot diff off the daemon event loop (M2-3) #728 — worker-thread PNG decode/screenshot diff (parallel-safe)
• chore: fit fallow config to this repo so baselines/overrides are rarely needed (M2-4) #729 — fit fallow config to this repo (parallel-safe)
• test: fixture-based tests for Maestro compat runtime-targets (M3-1, promoted) #730 — Maestro runtime-targets fixture tests (parallel-safe)

Milestone 3 — polish (file as capacity allows)

Extract+test decision logic from android/app-lifecycle.ts and ios/apps.ts; client-metro.ts tests; replace 250ms+ real sleeps in unit tests with fake timers; ADR for daemon protocol/compatibility strategy.

Sequencing notes: #726 → #727 are strictly sequential (overlapping import graphs). #728/#729/#730 can each run in their own worktree in parallel with anything.