[EPIC] QuadWork v2.4.0 hardening & quality pass — audit remediation

[realproject7]

Goal

Systematic hardening + quality pass over QuadWork v2.4.0, driven by a full 4-part codebase audit (routes.js / server runtime / CLI+packaging / frontend). Close confirmed security holes, data-integrity races, and lifecycle leaks, then pay down the two god-files (routes.js 4.9k, index.js 2.1k) and frontend duplication — without breaking the working orchestrator.

Prime directive (non-negotiable)

A working QuadWork must never regress from this EPIC. Every sub-ticket states its blast-radius. Sequencing enforces safety:

• Phase 0 lands first: CI + release test-gate. This is the safety net that protects every later change — nothing else dispatches until PRs actually run the test suite.
• Isolated fixes before core-loop surgery. Refactors last, only after the fix tickets have landed and CI is green, each behind full v7 review (structural gate → EPIC alignment → kill-list → evidence verdict).
• Any sub-ticket touching the batch/queue/PTY hot path requires a live-verify step in its acceptance criteria (spawn a throwaway-port instance, run a real batch cycle, confirm no regression) before merge.

Architecture Direction

• Fixes are minimal and local; they do not rearchitect. Refactors are pure extraction (move code, keep behavior) guarded by the existing test suites (self-heal, watchdog, pty-dispatcher, reseed, batch-progress) plus new tests.
• Config becomes the single serialization point: atomic write (tmp+rename, the pattern migrate-ac.js already uses) + field-scoped endpoints (extend the Pinned projects (and sidebar groups) reset on server restart — pinned_projects dropped from config.json #944 pattern) so no path does whole-config read-modify-write.
• Security model stays "bind 127.0.0.1 + opt-in token for tailnet"; the WS/PTY surface gains an Origin allowlist + shared-token auth without breaking the local dashboard (token auto-provisioned locally).

Contracts (respect across sub-tickets)

• writeConfig (server/config.js:173) becomes atomic; all mutators go through it or field-scoped endpoints — no new whole-config PUT writers.
• WS auth: Origin allowlist in the server.on("upgrade") handler (index.js:1528) + token check on /ws/terminal, /api/agents/:p/:a/write, /interrupt; back-compatible default for localhost.
• Reseed/seed section-heading invariants from guidelines v7 still hold (no H2 renames; re1/re2 ## GitHub Authentication→## Forbidden Actions adjacency).
• Batch-progress state vocabulary, REST+ETag API-budget rule, [#<issue>] PR-title prefix — unchanged.

Sub-Tickets (ordered by phase)

Phase 0 — safety net (must land first)

• [#S1] CI on PRs + release test-gate + pack-smoke extension #976 CI on PRs + release test-gate + pack-smoke extension

Phase 1 — security (confirmed holes)

• [#S2] WS/PTY auth + Origin allowlist (tailnet keystroke-injection) #968 WS/PTY auth + Origin allowlist (tailnet keystroke-injection) — core-risky
• [#S3] Fix QueueManager markdown XSS — switch to react-markdown #969 QueueManager markdown XSS → react-markdown — isolated
• [#S4] activity/log path traversal + bridge reserved-sender + reviewer-token-path scoping #970 activity/log path traversal + bridge reserved-sender + reviewer-token-path scoping — isolated

Phase 2 — data integrity & lifecycle

• [#S5] Atomic config writes + field-scoped flag endpoints (kill whole-config races) #971 Atomic config writes + field-scoped flag endpoints (kill whole-config races) — core-risky
• [#S6] shutdown() cleanup + fix quadwork stop PID handling #972 shutdown() cleanup (PTYs/caffeinate/timers/bridges) + fix quadwork stop PID handling — isolated

Phase 3 — correctness (isolated, safe)

• [#S7] Frontend correctness bundle (chat auth banner, project-switch race, rename-clobber, confirms) #973 Frontend correctness bundle (chat auth banner, project-switch race, rename-clobber, destructive-action confirms, resize throttle, ws leak)
• [#S8] Setup hardening (stale-branch reuse, seed hard-fail, reviewer-token, EADDRINUSE) #974 Setup hardening (stale-branch reuse, CLI hard-fail on missing seed, reviewer-token collection, EADDRINUSE handler, origin-mismatch)
• [#S9] De-block the event loop (file-chat busy-wait, butler/setup execFileSync) #975 De-block the event loop (file-chat Atomics.wait, butler execFileSync, setup shell-outs → async)

Existing tickets folded in

• Lifecycle-aware cleanup of agent backend temp dirs (/tmp/claude-{uid}) to prevent /tmp quota exhaustion #957 Lifecycle-aware /tmp cleanup (PR [#957] Lifecycle-aware cleanup of agent backend temp dirs #960 is stale — rebase + re-review under v7, or reimplement)
• Reseed worktree CLAUDE.md alongside AGENTS.md so the two instruction files never drift #966 Reseed worktree CLAUDE.md alongside AGENTS.md
• Clarify Operator MCP VPS loopback and SSH forwarding troubleshooting #961 Clarify Operator MCP VPS loopback/SSH (docs, low)

Phase 4 — refactors (file JIT when the phase starts; fixes must be merged + CI green first)

• R1 Split index.js (agent-lifecycle / butler / triggers / mcp-config / static-serve) + delete dead MCP-proxy stack
• R2 Split routes.js (github-board / batch-progress / reseed / gh-ratelimit) + dedupe bridge routes + single bucketRow builder + evict per-SHA ETag cache
• R3 Frontend dedup (useBatchLifecycle + useProjectFlag hooks) + split SettingsPage/SetupWizard + unify Telegram/Discord widget + delete dead props/paths

Non-Goals

• No new features. No rearchitecting the agent model, chat transport, or GitHub sync design.
• No dependency additions beyond what a fix strictly needs (react-markdown is already a dep).
• Not touching a project's own hand-authored files; not changing the 127.0.0.1 default bind.

Audit provenance

Findings from a 4-agent audit of v2.4.0 (commit a344307). Full finding tables (severity/confidence/blast-radius/file:line) captured per sub-ticket. Cross-corroborated headline items: WS/PTY no-auth (2 independent auditors), whole-config race (2), lifecycle/caffeinate orphan (2).