boocode/openspec/changes/orchestrator/artifacts/.discovery-notes.md

Discovery notes — Orchestrator (Phase 2)

Single source of truth for project context. Specialists: read this first; do not re-grep for what's here. Search further only for what your domain needs that's missing.

Tech stack

• pnpm monorepo. apps/server (BooChat: Fastify + Postgres), apps/coder (BooCoder: host systemd service, agent dispatch), apps/web (React + Vite), apps/booterm, packages/contracts (@boocode/contracts, cross-app wire SSOT).
• DB boochat (Postgres 16). TypeScript strict, NodeNext (server/coder), .js import extensions. Tests: vitest (server + coder); no web test harness.
• Deploy: apps/coder change → sudo systemctl restart boocoder; apps/web/ apps/server → docker compose up --build -d boocode.

Phase 1 assets to reuse (/opt/boocode/conductor/)

• src/spine.ts — the Spine→Flow factory (band gating, fold, synthesizer, validator, render), + contracts injection.
• src/flows/*.ts + flows/index.ts — 22 flows (21 Spine configs + bespoke code-review.ts), registry (getFlow, FLOW_NAMES, describeFlows).
• src/contracts.ts — Han evidence/yagni contracts (produce/review).
• src/types.ts — Flow, Step, Spine, Angle, Band, Contract.
• src/flow.ts — the wave scheduler (dep-aware parallel). This is what Phase 2 must re-home/replace so steps dispatch through BooCoder backends + persist.
• src/dispatch.ts — current opencode run subprocess dispatch. Replaced in Phase 2 by BooCoder backend dispatch.
• agents/*.md — 23 Han personas (also live in ~/.config/opencode/agents/).

apps/coder — execution surfaces

• src/services/dispatcher.ts:46 — createDispatcher. LISTEN 'tasks_new' fast path (pg trigger notify_tasks_new, schema line 279) + 2s poll. runTask routes a state='pending' task to a backend. inflight map keyed session_id ?? 'task:<id>' serializes per session.
• src/services/agent-backend.ts:97 — AgentBackend (ensureSession / prompt / closeSession / dispose / health). Backends: backends/opencode-server.ts, warm-acp.ts, claude-sdk.ts; one-shot acp-dispatch.ts / pty-dispatch.ts.
• AgentEvent (agent-backend.ts:28, union text|reasoning|tool_call|tool_update| commands) → mapped to WS frames by the dispatcher → broker.publishUserFrame.
• Tasks are how work is dispatched. INSERT INTO tasks (project_id, input, agent, model, mode_id, thinking_option_id, session_id, chat_id) then the LISTEN/NOTIFY trigger picks it up. Precedents: routes/messages.ts:233, routes/skills.ts:94 (a skill IS already dispatched as a task), routes/arena.ts:49, tools/new_task.ts:54 (writes parent_task_id).

apps/coder — schema (src/schema.sql, coder-owned)

• tasks (line 18): id, project_id, parent_task_id (FK self, written by new_task, NOT read by dispatcher), state CHECK(pending|running|completed|failed|blocked| cancelled), input, output_summary (≤500 char), agent, model, execution_path, cost_tokens, started_at, ended_at, session_id, arena_id, mode_id, thinking_option_id, chat_id.
• agent_sessions (line 88): PK (chat_id, agent); backend, agent_session_id, server_port, status(idle|active|crashed|closed), config_hash, token/cost cols.
• worktrees (line 142), available_agents (line 36), checkpoints (233), claude_session_entries (252). notify_tasks_new trigger (279).
• Schema discipline (root CLAUDE.md): two schema files one DB; coder schema is applied by the host boocoder service. CHECK migrations: DROP IF EXISTS the system-named constraint → UPDATE → guarded ADD. CREATE OR REPLACE VIEW can't reorder cols. JSONB via sql.json(value as never). clock_timestamp() in txns.

packages/contracts — WS frames

• src/ws-frames.ts — Zod frames in WsFrameSchema (SSOT). Existing: snapshot, message_started, delta, reasoning_delta, tool_call, tool_result, message_complete, usage, messages_deleted, chat_renamed, compacted, error.
• Adding a frame (cross-app, root CLAUDE.md): add to WsFrameSchema here (rebuild pnpm -C packages/contracts build), AND the server's loose InferenceFrame union (services/inference/turn.ts), AND the web's strict WsFrame union (apps/web/src/api/types.ts) — the web type is the wire gate; missing it silently drops the frame at JSON-parse.

apps/web — panes + composer

• Pane kinds (api/types.ts:386 WorkspacePaneKind): empty | chat | coder | terminal | settings | markdown_artifact | html_artifact. Extra non-chat pane kinds are already precedented — adding orchestrator follows markdown_artifact/html_artifact.
• hooks/useWorkspacePanes.ts — pane state, addSplitPane(kind), server-persisted (+ legacy localStorage seed). Workspace.tsx, NewPaneMenu.tsx, ChatTabBar.tsx, PaneHeaderActions.tsx all take kind: 'chat'|'terminal'| 'coder' — adding a kind touches these.
• ChatInput.tsx is the shared composer rendered by BOTH ChatPane.tsx and CoderPane.tsx (CoderPane also stacks AgentComposerBar above it). Its toolbar row (icons: Globe, ListPlus, Paperclip, Send/Stop, SquareSlash for slash) is where the Orchestrator button goes → parity for free. It takes slashGroups (ChatPane passes BooChat skills; CoderPane passes agent-commands+skills), onSlashCommand. SlashCommandPicker.tsx, hooks/useSkills.ts.
• Mobile: per prior preference, crowded toolbars must fit one line (no scroll/wrap) and the new button shows icon-only on mobile.

Precedents / related

• Arena (routes/arena.ts): same task → N contestants (tasks sharing arena_id), parallel, [SELECTED] winner. Closest existing fan-out; stays separate but is a structural precedent for "one launch → many tasks grouped".
• BooChat skills (apps/server routes/skills.ts + services/skills, getSkillBody): slash injects a skill body, the single chat model runs it inline. The coder also has routes/skills.ts that dispatches a skill as a task.
• Event-dedup discipline (root CLAUDE.md): a mutation published via broker.publishUser must NOT also sessionEvents.emit locally; handlers idempotent.

Enumerated gaps (searched, not found)

• No flow_runs / flow_steps / flows tables, no depends_on/step_index on tasks, no DAG/pipeline concept anywhere (confirmed Phase-1 research).
• No orchestrator pane kind, component, or WS frame yet.
• No coding-standards dir hits for orchestration; ADR dir not present under docs/adr/ (none found) — architectural decisions live in openspec/changes/.
• No resume mechanism for a multi-step run after coder restart (single tasks resume via agent_sessions; a run spanning tasks does not).
• The conductor's scheduler (conductor/src/flow.ts) is in-process/in-memory; it does not persist step state or survive restart.