feat(launcher): UI-driven agent launcher with reusable profiles (gated by ORCHESTRATOR_ENABLED)

[kqb]

Summary

Extends the orchestrator surface introduced in a6343be (PWA + mobile orchestrator) to expose every session-launch CLI flag from code.claude.com/docs/en/cli-reference through a UI form, persists configurations as reusable Profiles (SQLite, JSON export/import), and adds a send composer to the existing Conversation tab so any session — live or imported — can be continued from the dashboard. The previous 6-flag preset is replaced by a strict ProfileConfig shape that the spawner validates before invoking claude.

All new surface stays gated behind ORCHESTRATOR_ENABLED=1. Default behavior of the dashboard (observe-only) is preserved — every new route 404s when the flag is unset, no schema or UI changes for users who don't opt in.

What ships

Server (8 new modules)

• server/lib/profile-schema.js — flag table + JSON validator + buildArgsFromConfig (drives spawn argv).
• server/lib/stream-json-parser.js — newline-delimited JSON line buffer.
• server/lib/spawner.js — full rewrite: stdin pipe, full flag mapping, stream-json broadcast over WS, concurrency cap (ORCHESTRATOR_MAX_CONCURRENT), sendMessage(), resume support.
• server/lib/profiles.js, server/lib/cwds.js, server/lib/launches.js, server/lib/launcher-secrets.js.
• server/routes/profiles.js, server/routes/cwds.js.
• Three new SQLite tables: launcher_profiles, launcher_allowed_cwds, launcher_launches (audit log; env values are never recorded — only names).

Client

• New /launcher page with a sectioned form (15 sections covering every applicable flag) + live argv preview + dangerous-flag highlighting.
• Settings → Agent Profiles tab with list / edit / duplicate / import-export.
• SendComposer mounted at the bottom of the existing ConversationView — pipes follow-up messages to live agents (POST /agents/:id/message) or runs claude --resume <session-id> for historical sessions. Cmd/Ctrl+Enter to send.
• useProfiles, useCwds, extended useOrchestrator (now sendMessage-aware).
• MobileChat refactored as a thin SendComposer wrapper.
• New WSMessage variant: agent_input_ack.
• New nav entry across Sidebar.tsx, BottomTabNav.tsx, plus i18n (en/vi/zh).

Docs

• docs/superpowers/specs/2026-05-05-agent-launcher-design.md — design spec (brainstorming output).
• docs/superpowers/plans/2026-05-05-agent-launcher.md — 26-task TDD implementation plan.
• docs/launcher.md — user-facing feature guide.
• README + ARCHITECTURE + .env.example cross-references.

Architecture (one-pass)

Launcher form / Conversation send composer
  → POST /api/orchestrator/spawn  or  /agents/:id/message
    → server validates body against ProfileConfig schema
    → server checks cwd against launcher_allowed_cwds (security gate)
    → server checks concurrency cap
    → spawnAgent() builds argv, spawns `claude` with cleanSpawnEnv()
      → child stdout (stream-json) → parseStreamJson() → broadcast WS agent_stream
      → spawned `claude` fires hooks → POST /api/hooks/event → existing dashboard ingestion
    → response { id, pid, status, startedAt }

Spawned claude processes ride the existing observation pipeline — Sessions, Conversation, Workflows, Cost Tracking all "just work" for orchestrator-launched sessions on day one.

Safety

• Every new HTTP route 404s unless ORCHESTRATOR_ENABLED=1.
• The cwd allowlist is enforced server-side in the spawn handler — UI dropdowns are convenience, not security. Even a hand-crafted request with cwd: "/etc" is rejected.
• Default permission mode is acceptEdits (never bypassPermissions implicit).
• Dangerous flags (--bare, --dangerously-skip-permissions, --allow-dangerously-skip-permissions, --dangerously-load-development-channels) live behind a collapsed red banner in the editor.
• Hook handlers always exit 0 (project gotcha Feature: Interactive Session Replay with Timeline Scrubber #2 preserved).
• Argv is recorded in launcher_launches.argv_json with env values redacted — only the names that were injected are kept. Secrets resolve at spawn from ~/.claude/launcher/secrets.env (gitignored) or process.env.
• Concurrency-capped via ORCHESTRATOR_MAX_CONCURRENT (default 5).
• Profile validation runs twice — at the lib boundary (DB) and again at the spawner — so a hand-edited row or future MCP tool can't slip a bad config into a child process.

Test Plan

• npm run test:server — 241 / 241 (was 186 baseline → +55 launcher tests).
• npm run test:client — 159 / 159 (was 139 baseline → +20 launcher tests).
• cd client && npx tsc --noEmit — clean.
• All new HTTP routes 404 when ORCHESTRATOR_ENABLED is unset (test profiles route first case + cwds route smoke).
• Spawner concurrency limit, env-stripping, sendMessage rejection on non-running, agent_stream broadcast, agent_input_ack on stdin write — all covered in spawner-extended.test.js.
• Profile + cwd + audit CRUD round-trips covered (profiles-lib.test.js, cwds.test.js, launches.test.js).
• secrets.env parser covers ENOENT-only swallowing + EACCES rethrow (launcher-secrets.test.js).
• Manual smoke (recommended for review): set ORCHESTRATOR_ENABLED=1, npm run dev, visit /launcher, save a profile, launch an agent, see it stream via the existing Conversation tab; type into a historical session's send box and confirm claude --resume runs.

Backwards compatibility

• The previous 6-field preset shape is a strict subset of ProfileConfig; the spawner validator accepts it and the new route translates configOverride into the same merged config path. Existing callers continue to work.
• WSMessage extension is additive — agent_input_ack is a new variant; existing variants unchanged.
• No schema migrations against existing tables; only CREATE TABLE IF NOT EXISTS additions.
• The ConversationView component gained two optional props (sessionCwd, sessionLiveHandleId); both default to "no composer rendered." Existing parents that don't pass them continue to render the read-only view.

Phased delivery (33 commits)

1. Server foundation — flag table, line parser, spawner rewrite, secrets reader.
2. Persistence — schema, profiles + cwds + launches libs, HTTP routes.
3. Spawn integration — extended /spawn body, /agents/:id/message, sub-router mounts, liveHandle on session detail, agent_input_ack WS type.
4. Launcher form UI — types, hooks, CommandPreview, ProfileEditor + 14 sections, LauncherView page, route mount.
5. Profile manager — Settings → Agent Profiles tab.
6. Send composer — useOrchestrator.sendMessage, SendComposer (mode: "resume" | "fresh"), ConversationView mount, MobileChat refactor.
7. Polish — docs/launcher.md, README/ARCHITECTURE/.env cross-refs.

References

• docs/superpowers/specs/2026-05-05-agent-launcher-design.md — full design.
• docs/superpowers/plans/2026-05-05-agent-launcher.md — TDD task breakdown.
• docs/launcher.md — user guide.
• Built atop a6343be (PWA + mobile orchestrator) and docs/orchestration-research/10-pwa-on-dashboard-design.md Phase 2 "preset shape" decision.

🤖 Generated with Claude Code