feat: evidence-driven review hub, agent review chains, and process layer v2

[web3dev1337]

Summary

Implements the tier-workflow vision from the optimal-agent-orcestration-system research on top of the existing (mostly hidden) Jan–Feb process layer. Full design rationale: PLANS/2026-07-15/EVIDENCE_REVIEW_WORKFLOWS_PLAN.md.

The evidence system (centerpiece)

Everything a human needs at a glance before approve/merge, per finished task:

• New evidence field on task records: tests (ran/command/passed/failed), appRun proof (puppeteer/server-smoke/studio/manual), agent review chain verdicts with findings/fixed counts, screenshots/video, before/after data for balance changes, standards reviewed against, handoff notes, diff stats
• evidenceService collects it from fenced agent-evidence blocks in PR bodies/comments (travels with the PR), .agent-evidence.json in worktrees, or direct API; PR diff stats are computed server-side, never agent-claimed
• Queue detail gets an Evidence card (badge row + review verdicts + media lightbox + data table) and a Refresh button
• docs/agents/EVIDENCE_PROTOCOL.md teaches agents to self-report; a compact snippet is auto-appended to batch launch prompts (media endpoint only serves from the server-recorded worktree root — traversal rejected, extension whitelist)

Multi-agent review chains (data-driven)

• config/review-workflows.json: standard (1 general) / hardened (security→general) / full-gate (security+perf+general) with per-stage agent, model, effort; risk level picks the default chain (research: p_chain = Πp — 30% → 9% → 2.7%)
• reviewWorkflowService spawns each stage into an idle worktree, detects its GitHub verdict, records the outcome into evidence.reviews[], advances/blocks/stalls; run state persists across restarts
• Per-role model routing: claude --model <alias> support added; codex uses existing model/reasoning flags

Bugs found & fixed (the "spammed out, untested" batch)

• PR review auto-spawn never worked: startAgentWithConfig was called with {provider, skipPermissions} instead of {agentId, mode, flags} — failed validation every time; also wrong repo name in session ids, and prompt+\n in one write (bracketed paste, never submits)
• Commander /clear (and all slash commands): forwarded as a single "/clear\r" paste chunk — now text + delayed \r
• Codex unattended launches lacked --dangerously-bypass-approvals-and-sandbox → stalled on approvals
• Plugin POST routes never saw req.body (no JSON parser on plugin routers)
• Server launch was hardcoded hytopia start for every project type

Resurfacing the hidden process layer

• UI Mode presets (Settings → UI Mode): one-click Simple ↔ Power/Process switch over the ~40 ui.visibility flags that had no UI at all; the Review Hub (📥 Review) header button is visible by default again (a hardcoded display:none was overriding its true flag)

Prompt-cache freshness

• Feedback routing by cache age: warm sessions (<55 min) get review feedback inline; cold/missing sessions get a fresh fixer seeded with the review feedback + evidence handoff notes (also implements the previously-stubbed autoSpawnFixer); 🧊 cache-cold chip in Queue detail

Context-switch telemetry (local-only)

• JSONL log of worktree focus / workspace switches / workflow mode / review timers with refocus-cost estimate and top thrash pairs, surfaced in the dashboard Telemetry overlay; nothing leaves the machine

Plugins made real

• First working example plugin: youtube-transcript (Commander tools button or command → yt-dlp subtitles → plain-text transcript in ~/Downloads/transcripts/)
• New post_route slot action (local routes only, optional prompted input), new commander.tools slot renderer, Settings → Plugins admin (failed plugins finally visible) + reload, client.slots finally documented in plugins/README.md

Play buttons revived

• Launch commands resolve from the cascaded config (serverCommand + {{gameMode}}/{{commonFlags}} templating — the substitution the docs promised now exists); Start Server dropdown re-enabled behind existing visibility flags (Power preset turns them on)

Follow-up

• Multi-commander: seam analysis + recommended path in PLANS/2026-07-15/MULTI_COMMANDER_FEASIBILITY.md (PR-sized follow-up)

Test plan

• npm run test:unit: 652 tests / 111 suites green (39 new tests across 8 new/extended suites)
• node scripts/check-command-surface-drift.js: clean
• Live smoke on a scratch port: review-workflow config API, visibility presets, plugin load (youtube-transcript loads, zero failures), client-surface slot, context-switch track/summary, evidence PUT→normalize→GET roundtrip, media path-traversal rejection, all new client files served
• Manual: open Queue → select a PR → Evidence card + Review workflow block render; Settings → UI Mode / Plugins sections
• Defaults unchanged for existing users: everything new is additive or behind flags except the Review button and the (previously broken) automation fixes

🤖 Generated with Claude Code

Agent-agnostic launches (added after review)

Any CLI agent — Gemini, OpenCode, Grok, aider, anything — registers via ~/.agent-workspace/custom-agents.json (documented skeletons in config/custom-agents.example.json) with zero code changes: it appears in the agent picker, batch launches, and review-workflow stages, with its own launch flags, init delay, and per-agent model/effort CLI syntax (modelFlag/reasoningFlag templates). Reviewer/fixer/stage spawns resolve flags from the registry instead of hardcoded claude/codex branches. Status-light heuristics for gemini/opencode already existed and apply automatically.

Multiple Commanders (added after review)

CommanderManager runs N independent commander instances keyed by id — the primary keeps id commander so every existing route and the single-panel behavior are byte-for-byte unchanged. Additional commanders each get their own PTY + Claude launch + data dir (own CLAUDE.md persona). Id-aware PTY-lifecycle routes (default to primary), scoped socket payloads, list/spawn/remove routes (limit 6, primary un-removable), and a titlebar tab-switcher that rebinds the one xterm to another backend PTY. Hidden by default (commander.tabs), on in the Power preset.

Independent security review (Codex/gpt-5.5) + 8 fixes

Ran an independent review of the full branch diff; all 8 findings fixed with tests (server/utils/shellSafety.js, tests/unit/securityFixes.test.js):

• HIGH shell-injection in custom-agent command construction and in the server-launch {{gameMode}}/{{commonFlags}} templating → shell-safe allowlist on all config-derived values; unsafe configs rejected at load / fall back to safe defaults.
• HIGH evidence media endpoint was lexical-only → realpath-confines target under the worktree root (blocks symlink-out) and rejects non-regular files.
• HIGH refresh() trusted an arbitrary request-body worktreePath → an explicit path is honored only if it resolves to a known workspace worktree.
• MEDIUM review-workflow poll serialization (in-flight guard + CAS), stage-review attribution prefers the agent's marked review, prompt-cache routing treats missing timestamps as warm-if-live-session, and post_route is restricted to the plugin's own /api/plugins/<id>/ namespace (rejects //host).

All 679 unit tests pass (114 suites).

[web3dev1337]

Swept as part of the open-PR review (two scoped reviewers + fixes). Branch was already rebased on current main with zero drift. Fixed and pushed: (1) SECURITY — evidence.worktreePath could be planted via the generic task-records PUT and steer the media endpoint at any readable directory; resolveMediaPath now re-validates the recorded root against the managed-worktree set at read time (+ regression test), plus nosniff and forced download for SVG; (2) advanceWorkflow now refuses to resurrect cancelled/complete runs (it used to spawn a live agent for a dead run), and cancelWorkflow clears the in-flight spawn's delayed prompt-injection timers; (3) evidence review/appRun URLs are scheme-allowlisted (javascript: URIs were rendered clickable), the client now listens to the review-workflow socket events so stage chips update live, the lightbox keydown-listener leak is fixed, and terminal.startServer ships default-off so the Power preset is what enables it, matching the PR description. Full suite: 681/681 passing.