stack/docs/scratchpads/ms19-chat-terminal-20260225.md

Mission Scratchpad — MS19 Chat & Terminal System

Append-only log. NEVER delete entries. NEVER overwrite sections. This is the orchestrator's working memory across sessions.

Original Mission Prompt

Plan MS19+, update mission artifacts for Coolify → Portainer transition.
MS18 is complete. Coolify deprecated, Portainer migration in progress with another agent.

Planning Decisions

2026-02-25 — Infrastructure Assessment

Existing chat infrastructure (~95% complete):

• ChatOverlay.tsx, ConversationSidebar.tsx, ChatInput.tsx, MessageList.tsx
• useChat hook with conversation management and LLM interaction
• Backend LLM controller with SSE streaming support
• Providers: Ollama, Claude, OpenAI
• Chat persistence via Ideas API

Existing terminal infrastructure (UI-only):

• TerminalPanel.tsx with tabs, rich output styling, animations
• No backend connection — purely mock UI

Existing orchestrator infrastructure:

• Orchestrator service (NestJS, port 3002) with agent spawn/kill/status
• SSE stream at /agents/events for real-time agent status
• Web proxy routes at /api/orchestrator/*
• Coordinator integration in API for job tracking

Key pattern reference:

• Speech gateway (apps/api/src/speech/speech.gateway.ts) shows namespace WebSocket pattern with session management

2026-02-25 — Architecture Decisions

Decision: node-pty for terminal backend

• Standard PTY management for Node.js (used by VS Code)
• Spawns real shell processes (bash/zsh)
• Handles resize, input/output streams
• WebSocket namespace /terminal for communication

Decision: Terminal sessions in PostgreSQL

• Consistent with workspace isolation pattern
• Prisma model: TerminalSession (id, workspaceId, name, status, createdAt, closedAt)
• Sessions survive page reload, recover on reconnect

Decision: SSE for chat streaming (not WebSocket)

• Backend already has SSE setup in LLM controller
• Only frontend wiring missing (streamChatMessage() is TODO)
• SSE is simpler and sufficient for unidirectional token streaming

Decision: Orchestrator commands as chat prefixes

• /spawn, /status, /jobs, /kill parsed in frontend
• Route through existing /api/orchestrator/* proxy
• Display structured responses inline in chat

2026-02-25 — Portainer Migration

Context: Coolify has been deprecated and shut down. Infrastructure migration to Portainer is being handled by another agent. All deployment references updated from Coolify to Portainer in PRD and mission manifest.

Impact on MS19:

• Deployment target is now Portainer (was Coolify)
• No code changes needed — only infrastructure config
• Smoke testing blocked until Portainer stack is running

Session Log

S1 — 2026-02-25

• Read mission state (MS18 complete, all 16 tasks done)
• Explored codebase for MS19 infrastructure (chat, terminal, WebSocket, orchestrator)
• Updated PRD: Coolify → Portainer, added MS18 completion, added MS19 FRs and acceptance criteria
• Created new MISSION-MANIFEST.md for MS19+ mission
• Created TASKS.md with 12-task breakdown (~250K token estimate)
• Created this scratchpad
• Archived MS18 TASKS.md to docs/tasks/MS18-ThemeWidgets-tasks.md

S2 — 2026-02-25

• Fixed CSRF token issue affecting API route health checks
• Wave 1 dispatch: CT-TERM-001 (terminal gateway) + CT-CHAT-001 (chat streaming) in parallel sonnet workers
• CT-TERM-001 → PR #515 merged (6290fc3), 48 tests
• CT-CHAT-001 → PR #516 merged (7de0e73), streaming + fallback + abort
• Wave 2 dispatch: CT-TERM-002 (persistence) + CT-TERM-003 (xterm.js) in parallel sonnet workers
• CT-TERM-002 → PR #517 merged (8128eb7), 12 tests, #508 closed
• CT-TERM-003 → PR #518 merged (417c6ab), 40 tests
• Context exhaustion after 5 tasks

S3 — 2026-02-25

• Resume: Re-applied lost S2 TASKS.md edits (git stash during S2 cleanup lost docs)
• Wave 3a dispatch: CT-TERM-004 + CT-CHAT-002 in parallel sonnet workers
• CT-CHAT-002 → PR #519 merged (13aa52a), 46 tests, #510 closed
• CT-TERM-004 → PR #520 merged (859dcfc), 76 tests, #509 closed
• Wave 3b dispatch: CT-ORCH-001 (orchestrator chat) as sonnet worker
• CT-ORCH-001 → PR #521 merged (b110c46), 34 tests
• Wave 4 dispatch: CT-ORCH-002 (agent terminal) as sonnet worker
• CT-ORCH-002 worker completed with 79 tests, commit a0ceb30
• Context exhaustion before processing ORCH-002 output

S4 — 2026-02-26

• Resume: Processed CT-ORCH-002 worker output from S3
• Cherry-picked a0ceb30 → clean branch → PR #522 merged (9b2520c), #511 closed
• CT-VER-001 verified: 328 MS19 tests (268 web + 60 API) across 15 test files, all passing
• CT-DOC-001: Updated TASKS.md, MISSION-MANIFEST.md, PRD.md, scratchpad
• Remaining: CT-VER-002 (deploy + smoke test)