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

.env.example

@@ -1,4 +1,13 @@
 # Claude Code home directory (default: ~/.claude)
 # Override this if your Claude Code data is in a different location, e.g.:
 #   CLAUDE_HOME=~/.codefuse/engine/cc
-# CLAUDE_HOME=~/.claude
+# CLAUDE_HOME=~/.claude
+
+# Local agent orchestrator — gates the Launcher feature (see docs/launcher.md).
+# Without this flag, every /api/orchestrator/* route returns 404.
+# ORCHESTRATOR_ENABLED=1
+# ORCHESTRATOR_MAX_CONCURRENT=5
+
+# Composer file upload max size in MB (default 25). Applies to the paperclip
+# / photo pickers and drag-and-drop on the Conversation tab's send box.
+# LAUNCHER_MAX_UPLOAD_MB=25

ARCHITECTURE.md

@@ -2,6 +2,8 @@
 
 Architectural overview and technical reference for the Agent Dashboard system, covering design goals, high-level architecture, data flow, server and client components, database design, WebSocket protocol, hook integration, MCP extension layer, Claude Code plugins & skills, state management, security considerations, performance characteristics, deployment modes, and technology choices.
 
+> **Optional control plane (`ORCHESTRATOR_ENABLED=1`)** — the dashboard can also drive new `claude` sessions and continue existing ones. New routes under `/api/orchestrator/*` (profiles, cwds, spawn, agents, message) and three new SQLite tables (`launcher_profiles`, `launcher_allowed_cwds`, `launcher_launches`) become reachable. Default behavior (observe-only) is preserved when the flag is off — every new route 404s. Spawned `claude` processes fire hooks back into the same `POST /api/hooks/event` ingestion path, so the existing observability stack covers them automatically. See [`docs/launcher.md`](docs/launcher.md).
+
 ![Claude Code](https://img.shields.io/badge/Claude_Code-orange?style=flat-square&logo=claude&logoColor=white)
 ![Claude Code Plugins](https://img.shields.io/badge/Claude_Code-Plugins_&_Skills-orange?style=flat-square&logo=anthropic&logoColor=white)
 ![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-339933?style=flat-square&logo=node.js&logoColor=white)

README.md

@@ -230,6 +230,7 @@ The dashboard offers a comprehensive set of features to monitor and analyze your
 | **Notifications**                  | Full Web Push (VAPID) pipeline for reliable delivery. Arrive even when the tab is backgrounded or the browser is closed. Explicitly configured for macOS audio support. Configurable per-event toggles with subscription management |
 | **Update Notifier**                | Server periodically runs a non-blocking `git fetch` and compares the local checkout to `origin/master`/`origin/main`/`origin/HEAD`. When upstream is ahead, the UI surfaces a modal with the exact `git pull && npm run setup` command and a one-click **Copy** button; the Sidebar gets a persistent "Check for updates" button with live badge. The dashboard never pulls or restarts itself — the user runs the command in a terminal — so the mechanism cannot break dev sessions, pm2/systemd/Docker supervision, or leave orphaned processes |
 | **Settings**                       | System info, hook status, model pricing management, notification preferences, data export, session cleanup. The Model Pricing section exposes an info popover (the `i` icon next to the title) explaining how rule lookup works (first matching pattern wins), the SQL-style `%` wildcard syntax with concrete examples (`claude-opus-4-7%`, `claude-%-haiku`, exact ids), and that prices must be updated manually when Anthropic publishes new rates — already-stored sessions keep the price applied at ingest time. The CLAUDE_HOME box and Import History panel are fully i18n-driven across en/vi/zh |
+| **Agent Launcher** *(opt-in)*      | UI-driven `claude` subprocess launcher with every session-launch CLI flag exposed (`--model`, `--effort`, `--permission-mode`, `--tools`, `--system-prompt`, `--mcp-config`, …) and saved as reusable **Profiles** (SQLite-backed, JSON export/import). Per-session **Send composer** at the bottom of the Conversation tab pipes follow-up turns to live agents (`POST /agents/:id/message`) and transparently runs `claude --resume <session-id>` for historical sessions. Cwd allowlist enforced server-side; concurrency cap (`ORCHESTRATOR_MAX_CONCURRENT`, default 5); env-var values resolved at spawn from `~/.claude/launcher/secrets.env` (gitignored) — names only stored in profiles and audit log. Gated by `ORCHESTRATOR_ENABLED=1`; full guide at [`docs/launcher.md`](docs/launcher.md) |
 | **MCP Server (Local)**             | Enterprise-grade local MCP server in `mcp/` with three transport modes (stdio, HTTP+SSE, interactive REPL), 25 typed tools across 6 domains, strict input schemas, retry/backoff, localhost-only API enforcement, and tiered mutation/destructive safety gates. HTTP mode serves Streamable HTTP (2025-11-25) and legacy SSE (2024-11-05) on configurable port. REPL mode provides tab-completed interactive tool invocation with colored output |
 | **Workflows**                      | D3.js-powered visualization page with 11 interactive sections: agent orchestration DAG, tool execution Sankey diagram, collaboration network, subagent effectiveness (day-of-week sparklines with portal-rendered tooltips that escape the card's `overflow:hidden` and clamp to the viewport so they never get clipped), detected workflow patterns, model delegation flow, error propagation map (horizontal bars with rate badges, agent type breakdown, API/session error cards), concurrency timeline, session complexity scatter, compaction impact analysis, and per-session drill-in. **Rich, i18n-aware tooltips throughout:** every chart's section title carries an `i` icon that opens a structured "What this shows / How to read it / Why it matters" popover; hovering nodes, edges, bars, and bubbles surfaces multi-section tooltips with deterministic, value-dependent interpretations (e.g. share-of-source / share-of-target percentages, success-rate health buckets, family descriptions for Opus / Sonnet / Haiku, timing patterns like front-loaded / mid-session / back-loaded). Each of the six headline stat cards has a bottom-right info popover explaining how the metric is calculated and what its current value means in plain language. Tooltips are DOM-mutated through a single ref per chart with container-level `mouseleave` fallbacks, so they never lag behind the cursor or stick after re-render. Clicking a row in **Detected Workflow Patterns** expands an in-place detail panel with the full step sequence, stats grid, a deterministic narrative (loop detection, frequency bucket), and a practical suggestion. Status filter tabs (Active Only / Completed / All) filter all 11 sections. Cross-filtering, JSON export, and real-time WebSocket auto-refresh with 3-second debounce |
 | **Compaction Tracking**            | Detects `/compact` events from JSONL transcripts, creates compaction agents and events. Backfills legacy compactions on startup. A periodic scanner (cadence derived from `DASHBOARD_STALE_MINUTES`) catches compactions even when no hooks fire. Shares the transcript cache so no duplicate file reads occur |