rufloui 0.3.1 → 0.3.35

package/CHANGELOG.md

@@ -6,6 +6,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-03-12
+
+### Changed
+
+- **Port configuration** — Backend moved from 3001 to **28580**, frontend from 5173 to **28588**, daemon from 3002 to **28581**
+- Avoids conflicts with reserved port ranges on Windows (Hyper-V, Docker, antivirus)
+- All documentation, CORS config, WebSocket connections, and Vite proxy updated accordingly
+
+### Fixed
+
+- **Workflow cancel** — Now properly updates local store, kills running processes, and cancels linked tasks
+- **Task cancel** — Now kills running `claude -p` processes and cancels linked workflows
+- **Workflow delete** — Removes from local store even when CLI fails
+
 ## [0.3.1] - 2026-03-11
 
 ### Added

package/CLAUDE.md

@@ -14,13 +14,13 @@
 
 ```bash
 npm install
-npm run dev          # Starts both frontend (Vite :5173) and backend (Express :3001)
+npm run dev          # Starts both frontend (Vite :28588) and backend (Express :28580)
 # Or individually:
-npm run dev:frontend # Vite dev server on port 5173
-npm run dev:backend  # Express API on port 3001 (tsx watch, auto-reloads)
+npm run dev:frontend # Vite dev server on port 28588
+npm run dev:backend  # Express API on port 28580 (tsx watch, auto-reloads)
 ```
 
-The frontend proxies `/api/*` and `/ws` to `localhost:3001` via Vite config.
+The frontend proxies `/api/*` and `/ws` to `localhost:28580` via Vite config.
 
 ## Project Structure
 
@@ -141,7 +141,7 @@ The backend is a single Express file that wraps CLI commands, manages state, and
 
 ### WebSocket Events
 
-- Path: `ws://localhost:3001/ws`
+- Path: `ws://localhost:28580/ws`
 - **Broadcast events**: `swarm:status`, `agent:activity`, `agent:output`, `task:added`, `task:updated`, `task:output`, `workflow:added`, `workflow:updated`, `session:list`, `performance:metrics`, `viz:update`, `swarm-monitor:update`, `log`
 - Frontend connects in `App.tsx` and dispatches to Zustand store
 
@@ -255,7 +255,7 @@ These are critical to understand when modifying the backend:
 - ALWAYS read a file before editing it
 - NEVER commit secrets, credentials, or .env files
 - Keep files under 500 lines where possible (server.ts is an exception at ~2200 lines)
-- After editing `server.ts`, the backend must be restarted: `npx kill-port 3001; npx tsx src/backend/server.ts`
+- After editing `server.ts`, the backend must be restarted: `npx kill-port 28580; npx tsx src/backend/server.ts`
 - Frontend hot-reloads automatically via Vite
 - When API returns `{ items: [...] }` vs `[...]`, always normalize before setting store
 

package/README.md

@@ -47,14 +47,18 @@ npm run dev
 ```
 
 This starts:
-- **Frontend** (Vite) on `http://localhost:5173`
-- **Backend** (Express + WebSocket) on `http://localhost:3001`
+- **Frontend** (Vite) on `http://localhost:28588`
+- **Backend** (Express + WebSocket) on `http://localhost:28580`
 
 The frontend proxies `/api/*` and `/ws` to the backend automatically.
 
-### Install via GitHub Packages
+### Install via npm
 
-RuFloUI is also available as an npm package on GitHub Packages:
+```bash
+npm install rufloui
+```
+
+### Install via GitHub Packages
 
 ```bash
 # Configure npm to use GitHub Packages for the @mario-pb scope
@@ -64,14 +68,14 @@ echo "@mario-pb:registry=https://npm.pkg.github.com" >> .npmrc
 npm install @mario-pb/rufloui
 ```
 
-> **Note:** You need a GitHub personal access token with `read:packages` scope.
+> **Note:** GitHub Packages requires a personal access token with `read:packages` scope.
 > Add it to your `~/.npmrc`: `//npm.pkg.github.com/:_authToken=YOUR_TOKEN`
 
 ### Individual Services
 
 ```bash
-npm run dev:frontend   # Vite dev server on port 5173
-npm run dev:backend    # Express API on port 3001 (auto-reloads)
+npm run dev:frontend   # Vite dev server on port 28588
+npm run dev:backend    # Express API on port 28580 (auto-reloads)
 ```
 
 ### Production Build
@@ -123,7 +127,7 @@ src/
 ```
 Browser (React 19)                    Express Backend
 ┌────────────────────┐               ┌────────────────────────┐
-│  Vite :5173        │───REST /api──>│  Express :3001         │
+│  Vite :28588       │───REST /api──>│  Express :28580        │
 │  Zustand Store     │<──WebSocket──>│  WebSocket Server      │
 │  sessionStorage    │               │                        │
 └────────────────────┘               │  ┌──────────────────┐  │
@@ -161,7 +165,7 @@ Once the app is running, here's how to go from zero to a working multi-agent swa
 2. **Spawn agents** — Go to **Agents**, select a type (e.g. `coder`), give it a name, and click **Spawn**. Repeat for other roles you need (`researcher`, `tester`, etc.).
 3. **Create a task** — Go to **Tasks**, click **Create Task**, fill in a title and description (e.g. "Write a fibonacci function in Python with tests").
 4. **Assign to swarm** — On the task card, click **Assign to Swarm**. The multi-agent pipeline kicks in: a coordinator plans subtasks, specialist agents execute them in parallel waves.
-5. **Watch it live** — Switch to **Swarm Monitor** to see agent cards light up with real-time output and the orange working glow animation. Or open **Agent Viz** to see the full agent tree built from session logs.
+5. **Watch it live** — Switch to **Swarm Monitor** to see agent cards light up with real-time output and the orange working glow animation.
 6. **Continue if needed** — When a task completes, click **Continue Task** to send a follow-up instruction with full context from the previous run.
 
 ## Prerequisites

package/TESTS.md

@@ -0,0 +1,91 @@
+# RuFloUI Test Suite
+
+## Quick Start
+
+```bash
+npm test              # Run all tests once
+npx vitest            # Run in watch mode
+npx vitest --coverage # Run with coverage report
+npx vitest run src/backend   # Run only backend tests
+npx vitest run src/frontend  # Run only frontend tests
+```
+
+## Test Runner
+
+- **Vitest 2.x** with two environment modes:
+  - `jsdom` (default) — for React component and browser API tests
+  - `node` — for backend tests (opted-in per file via `// @vitest-environment node`)
+
+Configuration: `vitest.config.ts`
+Setup file: `src/frontend/test-setup.ts` (loads `@testing-library/jest-dom` matchers)
+
+## Test Structure
+
+```
+src/
+├── backend/__tests__/
+│   ├── server-utils.test.ts         # Unit: parseCliTable, parseCliOutput, sanitizeShellArg
+│   ├── server-integration.test.ts   # Integration: persistence layer, health check parsing,
+│   │                                 #   time matching, env var cleanup, WebSocket broadcast logic
+│   ├── e2e-workflows.test.ts        # E2E: task lifecycle, agent lifecycle, swarm lifecycle,
+│   │                                 #   session lifecycle, workflow lifecycle
+│   ├── webhook-github.test.ts       # Unit+Integration: GitHub webhook signature verification,
+│   │                                 #   route handlers, config, auto-assign, templates
+│   └── webhook-gitlab.test.ts       # Unit+Integration: GitLab webhook token validation,
+│                                     #   route handlers, config, auto-assign, edge cases
+└── frontend/__tests__/
+    ├── store.test.ts                # Unit: Zustand store actions and selectors (agents, tasks,
+    │                                 #   logs, viz sessions, swarm monitor, all setters)
+    ├── api.test.ts                  # Unit: API client (all endpoint namespaces, error handling,
+    │                                 #   timeout behavior)
+    └── components.test.tsx          # Unit: UI components (Button, Card, StatusBadge) with
+                                      #   variants, sizes, hover, disabled/loading states
+```
+
+## What Each File Covers
+
+### Backend
+
+| File | Level | Coverage |
+|------|-------|----------|
+| `server-utils.test.ts` | Unit | `parseCliTable` (8 cases: empty, headers, multi-col, ellipsis, separators, CRLF, missing cells), `parseCliOutput` (4 cases), `sanitizeShellArg` (6 cases: injection vectors) |
+| `server-integration.test.ts` | Integration | Persistence save/load (6 cases: tasks, agents, workflows, .tmp recovery, atomic write, corruption), health check parsing (5 cases: pass/warn/fail/Windows), time matching (3 cases), env var cleanup (3 cases), WebSocket broadcast event classification (3 cases), sanitizeShellArg injection prevention (5 cases), parseCliTable with real CLI output patterns (3 cases) |
+| `e2e-workflows.test.ts` | E2E | Task lifecycle: create-assign-complete-cancel (8 cases), Agent lifecycle: spawn-list-terminate (5 cases), Swarm lifecycle: init-status-shutdown-reinit (5 cases), Session lifecycle: save-list-restore-delete (6 cases), Workflow lifecycle: create-execute-complete (4 cases) |
+| `webhook-github.test.ts` | Unit+Integration | Signature verification (9 cases), webhook receiver (4 cases), event storage/ordering (3 cases), invalid payloads (8 cases), config GET/PUT (10 cases), HMAC integration (2 cases), test endpoint (5 cases), task templates (5 cases), auto-assign failures (2 cases), event status updates (3 cases) |
+| `webhook-gitlab.test.ts` | Unit+Integration | GitLab issue hooks (3 cases), disabled state (1 case), token validation (4 cases), event/repo filtering (5 cases), auto-assign (3 cases), config GET/PUT (3 cases), test endpoint (5 cases), event updates (2 cases), edge cases (4 cases) |
+
+### Frontend
+
+| File | Level | Coverage |
+|------|-------|----------|
+| `store.test.ts` | Unit | Simple setters (6 cases), agent CRUD (6 cases), task CRUD (4 cases), log management (3 cases: prepend, cap), collection setters (4 cases), viz session actions (4 cases), swarm monitor (1 case), additional setters (5 cases: memory stats, active session, hive mind, neural, performance, coordination) |
+| `api.test.ts` | Unit | System endpoints (2 cases), agent endpoints (5 cases), task endpoints (8 cases), memory endpoints (2 cases), swarm endpoints (3 cases), session endpoints (4 cases), webhook endpoints (6 cases), workflow endpoints (5 cases), config endpoints (3 cases), performance endpoints (2 cases), error handling (3 cases: non-OK, JSON parse fail, timeout) |
+| `components.test.tsx` | Unit | Button: render, click, disabled, loading, variants, sizes, hover behavior, custom style (12 cases). Card: children, title, actions, header presence, complex children (7 cases). StatusBadge: render, statuses, empty/null, dot element, sizes, all color mappings (8 cases) |
+
+## Coverage Strategy
+
+### Unit Tests
+Test individual functions and components in isolation. Mock external dependencies (fetch, store, CLI). Fast and deterministic.
+
+### Integration Tests
+Test interaction between components: persistence layer (file I/O), health check parsing (regex matching on CLI output), WebSocket message format and event classification. Use real file system (temp dirs) where needed.
+
+### E2E Tests
+Simulate full user workflows through the in-memory store layer: creating a task and moving it through its lifecycle, spawning agents and managing them, initializing and shutting down swarms. These verify the logical flow without requiring the actual Express server or CLI.
+
+## Test Dependencies
+
+- `vitest` — test runner
+- `jsdom` — browser environment for React tests
+- `@testing-library/react` — React component rendering
+- `@testing-library/jest-dom` — DOM assertion matchers
+- `@testing-library/user-event` — user interaction simulation
+
+All dependencies are in `devDependencies` in `package.json`.
+
+## Adding New Tests
+
+1. **Backend**: Add to `src/backend/__tests__/`. Use `// @vitest-environment node` at the top.
+2. **Frontend**: Add to `src/frontend/__tests__/`. Default jsdom environment applies.
+3. **Naming**: Use `*.test.ts` for pure logic, `*.test.tsx` for React components.
+4. **Pattern**: Server utility functions are copied into test files (since importing `server.ts` starts the server). Webhook modules export testable functions directly.

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "rufloui",
-  "version": "0.3.1",
+  "version": "0.3.35",
   "description": "React 19 dashboard for claude-flow v3 multi-agent orchestration",
   "repository": {
     "type": "git",
     "url": "https://github.com/Mario-PB/rufloui.git"
   },
   "publishConfig": {
-    "registry": "https://registry.npmjs.org"
+    "registry": "https://npm.pkg.github.com"
   },
   "license": "MIT",
   "type": "module",

package/src/backend/__tests__/e2e-workflows.test.ts

@@ -0,0 +1,438 @@
+// @vitest-environment node
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+// ── E2E-style tests that verify full workflows ──────────────────────────
+// These simulate the complete request/response cycles that the server handles,
+// testing the logical flow without actually starting the Express server or CLI.
+
+// ── In-memory stores (replicating server.ts store pattern) ──────────────
+
+type TaskRecord = {
+  id: string; title: string; description: string; status: string
+  priority: string; createdAt: string; assignedTo?: string; completedAt?: string; result?: string
+}
+
+type WorkflowRecord = {
+  id: string; name: string; status: string
+  steps: Array<{ id: string; name: string; status: string }>; createdAt: string
+}
+
+type SessionRecord = {
+  id: string; name: string; status: string; createdAt: string
+  agentCount: number; taskCount: number
+}
+
+let taskStore: Map<string, TaskRecord>
+let agentRegistry: Map<string, { id: string; name: string; type: string }>
+let terminatedAgents: Set<string>
+let workflowStore: Map<string, WorkflowRecord>
+let sessionStore: Map<string, SessionRecord>
+let broadcastEvents: Array<{ type: string; payload: unknown }>
+
+function broadcast(type: string, payload: unknown) {
+  broadcastEvents.push({ type, payload })
+}
+
+beforeEach(() => {
+  taskStore = new Map()
+  agentRegistry = new Map()
+  terminatedAgents = new Set()
+  workflowStore = new Map()
+  sessionStore = new Map()
+  broadcastEvents = []
+})
+
+// ── Task lifecycle: create → assign → complete ──────────────────────────
+
+describe('E2E: Task lifecycle (create → assign → complete)', () => {
+  function createTask(title: string, description: string, priority = 'normal'): TaskRecord {
+    const id = `task-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`
+    const task: TaskRecord = {
+      id, title, description, status: 'pending', priority, createdAt: new Date().toISOString(),
+    }
+    taskStore.set(id, task)
+    broadcast('task:added', task)
+    return task
+  }
+
+  function assignTask(taskId: string, agentId: string): TaskRecord {
+    const task = taskStore.get(taskId)
+    if (!task) throw new Error(`Task ${taskId} not found`)
+    task.status = 'in_progress'
+    task.assignedTo = agentId
+    broadcast('task:updated', task)
+    return task
+  }
+
+  function completeTask(taskId: string, result: string): TaskRecord {
+    const task = taskStore.get(taskId)
+    if (!task) throw new Error(`Task ${taskId} not found`)
+    task.status = 'completed'
+    task.completedAt = new Date().toISOString()
+    task.result = result
+    broadcast('task:updated', task)
+    return task
+  }
+
+  function cancelTask(taskId: string): TaskRecord {
+    const task = taskStore.get(taskId)
+    if (!task) throw new Error(`Task ${taskId} not found`)
+    task.status = 'cancelled'
+    broadcast('task:updated', task)
+    return task
+  }
+
+  it('creates a task with pending status', () => {
+    const task = createTask('Fix bug', 'Fix the login bug')
+    expect(task.status).toBe('pending')
+    expect(task.title).toBe('Fix bug')
+    expect(taskStore.has(task.id)).toBe(true)
+    expect(broadcastEvents).toHaveLength(1)
+    expect(broadcastEvents[0].type).toBe('task:added')
+  })
+
+  it('assigns a task to an agent', () => {
+    const task = createTask('Fix bug', 'Fix the login bug')
+    const assigned = assignTask(task.id, 'agent-1')
+    expect(assigned.status).toBe('in_progress')
+    expect(assigned.assignedTo).toBe('agent-1')
+    expect(broadcastEvents).toHaveLength(2)
+    expect(broadcastEvents[1].type).toBe('task:updated')
+  })
+
+  it('completes a task with result', () => {
+    const task = createTask('Fix bug', 'Fix the login bug')
+    assignTask(task.id, 'agent-1')
+    const completed = completeTask(task.id, 'Bug fixed by patching auth module')
+    expect(completed.status).toBe('completed')
+    expect(completed.result).toBe('Bug fixed by patching auth module')
+    expect(completed.completedAt).toBeTruthy()
+    expect(broadcastEvents).toHaveLength(3)
+  })
+
+  it('full lifecycle: create → assign → complete broadcasts 3 events', () => {
+    const task = createTask('Deploy', 'Deploy to staging')
+    assignTask(task.id, 'agent-1')
+    completeTask(task.id, 'Deployed successfully')
+
+    const types = broadcastEvents.map(e => e.type)
+    expect(types).toEqual(['task:added', 'task:updated', 'task:updated'])
+  })
+
+  it('cancels a pending task', () => {
+    const task = createTask('Unused task', 'Not needed')
+    const cancelled = cancelTask(task.id)
+    expect(cancelled.status).toBe('cancelled')
+  })
+
+  it('cancels an in-progress task', () => {
+    const task = createTask('Long task', 'Takes too long')
+    assignTask(task.id, 'agent-1')
+    const cancelled = cancelTask(task.id)
+    expect(cancelled.status).toBe('cancelled')
+  })
+
+  it('throws when assigning a non-existent task', () => {
+    expect(() => assignTask('nonexistent', 'agent-1')).toThrow('not found')
+  })
+
+  it('handles multiple tasks independently', () => {
+    const t1 = createTask('Task 1', 'First')
+    const t2 = createTask('Task 2', 'Second')
+    assignTask(t1.id, 'agent-1')
+    completeTask(t1.id, 'Done 1')
+
+    expect(taskStore.get(t1.id)!.status).toBe('completed')
+    expect(taskStore.get(t2.id)!.status).toBe('pending')
+  })
+})
+
+// ── Agent lifecycle: spawn → list → terminate ───────────────────────────
+
+describe('E2E: Agent lifecycle (spawn → list → terminate)', () => {
+  let agentCounter = 0
+  function spawnAgent(type: string, name: string): { id: string; name: string; type: string; createdAt: string } {
+    agentCounter++
+    const createdAt = `2025-01-01T00:00:${String(agentCounter).padStart(2, '0')}Z`
+    const id = `agent-${agentCounter}`
+    const agent = { id, name, type }
+    agentRegistry.set(createdAt, agent)
+    broadcast('agent:added', { ...agent, createdAt })
+    return { ...agent, createdAt }
+  }
+
+  function listAgents(): Array<{ id: string; name: string; type: string; terminated: boolean }> {
+    return [...agentRegistry.entries()].map(([createdAt, agent]) => ({
+      ...agent,
+      terminated: terminatedAgents.has(createdAt),
+    })).filter(a => !a.terminated)
+  }
+
+  function terminateAgent(createdAt: string) {
+    if (!agentRegistry.has(createdAt)) throw new Error('Agent not found')
+    terminatedAgents.add(createdAt)
+    const agent = agentRegistry.get(createdAt)!
+    broadcast('agent:removed', { id: agent.id })
+  }
+
+  it('spawns an agent and adds to registry', () => {
+    const agent = spawnAgent('coder', 'my-coder')
+    expect(agent.type).toBe('coder')
+    expect(agent.name).toBe('my-coder')
+    expect(agentRegistry.size).toBe(1)
+    expect(broadcastEvents[0].type).toBe('agent:added')
+  })
+
+  it('lists active agents (excludes terminated)', () => {
+    const a1 = spawnAgent('coder', 'coder-1')
+    const a2 = spawnAgent('tester', 'tester-1')
+
+    let agents = listAgents()
+    expect(agents).toHaveLength(2)
+
+    terminateAgent(a1.createdAt)
+    agents = listAgents()
+    expect(agents).toHaveLength(1)
+    expect(agents[0].name).toBe('tester-1')
+  })
+
+  it('terminate broadcasts agent:removed event', () => {
+    const a1 = spawnAgent('coder', 'coder-1')
+    terminateAgent(a1.createdAt)
+    const removeEvents = broadcastEvents.filter(e => e.type === 'agent:removed')
+    expect(removeEvents).toHaveLength(1)
+  })
+
+  it('throws when terminating unknown agent', () => {
+    expect(() => terminateAgent('unknown-time')).toThrow('not found')
+  })
+
+  it('supports spawning multiple agent types', () => {
+    spawnAgent('coder', 'c1')
+    spawnAgent('researcher', 'r1')
+    spawnAgent('tester', 't1')
+    spawnAgent('reviewer', 'rev1')
+
+    const agents = listAgents()
+    expect(agents).toHaveLength(4)
+    expect(agents.map(a => a.type).sort()).toEqual(['coder', 'researcher', 'reviewer', 'tester'])
+  })
+})
+
+// ── Swarm lifecycle: init → status → shutdown ───────────────────────────
+
+describe('E2E: Swarm lifecycle (init → status → shutdown)', () => {
+  let swarmConfig = {
+    id: '', topology: '', strategy: '', maxAgents: 0, createdAt: '', shutdown: true,
+  }
+
+  function initSwarm(topology: string, maxAgents: number, strategy = 'round-robin') {
+    swarmConfig = {
+      id: `swarm-${Date.now()}`,
+      topology,
+      strategy,
+      maxAgents,
+      createdAt: new Date().toISOString(),
+      shutdown: false,
+    }
+    broadcast('swarm:status', {
+      status: 'active', id: swarmConfig.id, topology, maxAgents, strategy,
+    })
+    return swarmConfig
+  }
+
+  function getSwarmStatus() {
+    if (swarmConfig.shutdown) {
+      return { status: 'inactive', id: '', topology: '', maxAgents: 0 }
+    }
+    return {
+      status: 'active',
+      id: swarmConfig.id,
+      topology: swarmConfig.topology,
+      maxAgents: swarmConfig.maxAgents,
+      strategy: swarmConfig.strategy,
+    }
+  }
+
+  function shutdownSwarm() {
+    swarmConfig.shutdown = true
+    broadcast('swarm:status', { status: 'inactive' })
+  }
+
+  beforeEach(() => {
+    swarmConfig = { id: '', topology: '', strategy: '', maxAgents: 0, createdAt: '', shutdown: true }
+  })
+
+  it('initializes a swarm', () => {
+    const config = initSwarm('mesh', 8, 'round-robin')
+    expect(config.topology).toBe('mesh')
+    expect(config.maxAgents).toBe(8)
+    expect(config.shutdown).toBe(false)
+  })
+
+  it('reports active status after init', () => {
+    initSwarm('hierarchical', 4)
+    const status = getSwarmStatus()
+    expect(status.status).toBe('active')
+    expect(status.topology).toBe('hierarchical')
+  })
+
+  it('reports inactive status after shutdown', () => {
+    initSwarm('mesh', 8)
+    shutdownSwarm()
+    const status = getSwarmStatus()
+    expect(status.status).toBe('inactive')
+  })
+
+  it('full lifecycle broadcasts correct events', () => {
+    initSwarm('star', 6)
+    shutdownSwarm()
+    expect(broadcastEvents).toHaveLength(2)
+    expect(broadcastEvents[0].type).toBe('swarm:status')
+    expect((broadcastEvents[0].payload as any).status).toBe('active')
+    expect((broadcastEvents[1].payload as any).status).toBe('inactive')
+  })
+
+  it('can re-initialize after shutdown', () => {
+    initSwarm('mesh', 8)
+    shutdownSwarm()
+    initSwarm('hierarchical', 12)
+    const status = getSwarmStatus()
+    expect(status.status).toBe('active')
+    expect(status.topology).toBe('hierarchical')
+    expect(status.maxAgents).toBe(12)
+  })
+})
+
+// ── Session lifecycle: save → list → restore → delete ───────────────────
+
+describe('E2E: Session lifecycle (save → list → restore → delete)', () => {
+  let sessionCounter = 0
+  function saveSession(name: string): SessionRecord {
+    sessionCounter++
+    const id = `sess-${sessionCounter}`
+    const session: SessionRecord = {
+      id, name, status: 'saved', createdAt: new Date().toISOString(),
+      agentCount: agentRegistry.size, taskCount: taskStore.size,
+    }
+    sessionStore.set(id, session)
+    broadcast('session:list', [...sessionStore.values()])
+    return session
+  }
+
+  function listSessions(): SessionRecord[] {
+    return [...sessionStore.values()]
+  }
+
+  function restoreSession(id: string): SessionRecord {
+    const session = sessionStore.get(id)
+    if (!session) throw new Error('Session not found')
+    session.status = 'restored'
+    broadcast('session:active', session)
+    return session
+  }
+
+  function deleteSession(id: string) {
+    if (!sessionStore.has(id)) throw new Error('Session not found')
+    sessionStore.delete(id)
+    broadcast('session:list', [...sessionStore.values()])
+  }
+
+  it('saves a session', () => {
+    const session = saveSession('morning-session')
+    expect(session.status).toBe('saved')
+    expect(session.name).toBe('morning-session')
+    expect(sessionStore.size).toBe(1)
+  })
+
+  it('lists all sessions', () => {
+    saveSession('session-1')
+    saveSession('session-2')
+    const sessions = listSessions()
+    expect(sessions).toHaveLength(2)
+  })
+
+  it('restores a session', () => {
+    const saved = saveSession('my-session')
+    const restored = restoreSession(saved.id)
+    expect(restored.status).toBe('restored')
+  })
+
+  it('deletes a session', () => {
+    const s1 = saveSession('temp')
+    deleteSession(s1.id)
+    expect(sessionStore.size).toBe(0)
+  })
+
+  it('throws when restoring non-existent session', () => {
+    expect(() => restoreSession('bad-id')).toThrow('not found')
+  })
+
+  it('throws when deleting non-existent session', () => {
+    expect(() => deleteSession('bad-id')).toThrow('not found')
+  })
+})
+
+// ── Workflow lifecycle ──────────────────────────────────────────────────
+
+describe('E2E: Workflow lifecycle', () => {
+  function createWorkflow(name: string, steps: string[]): WorkflowRecord {
+    const id = `wf-${Date.now()}`
+    const workflow: WorkflowRecord = {
+      id, name, status: 'draft', createdAt: new Date().toISOString(),
+      steps: steps.map((s, i) => ({ id: `step-${i}`, name: s, status: 'pending' })),
+    }
+    workflowStore.set(id, workflow)
+    broadcast('workflow:added', workflow)
+    return workflow
+  }
+
+  function executeWorkflow(id: string): WorkflowRecord {
+    const wf = workflowStore.get(id)
+    if (!wf) throw new Error('Workflow not found')
+    wf.status = 'running'
+    for (const step of wf.steps) step.status = 'running'
+    broadcast('workflow:updated', wf)
+    return wf
+  }
+
+  function completeWorkflow(id: string): WorkflowRecord {
+    const wf = workflowStore.get(id)
+    if (!wf) throw new Error('Workflow not found')
+    wf.status = 'completed'
+    for (const step of wf.steps) step.status = 'completed'
+    broadcast('workflow:updated', wf)
+    return wf
+  }
+
+  it('creates a workflow with steps', () => {
+    const wf = createWorkflow('deploy-pipeline', ['build', 'test', 'deploy'])
+    expect(wf.steps).toHaveLength(3)
+    expect(wf.status).toBe('draft')
+    expect(wf.steps[0].name).toBe('build')
+  })
+
+  it('executes a workflow', () => {
+    const wf = createWorkflow('ci', ['lint', 'test'])
+    const running = executeWorkflow(wf.id)
+    expect(running.status).toBe('running')
+    expect(running.steps.every(s => s.status === 'running')).toBe(true)
+  })
+
+  it('completes a workflow', () => {
+    const wf = createWorkflow('ci', ['lint', 'test'])
+    executeWorkflow(wf.id)
+    const completed = completeWorkflow(wf.id)
+    expect(completed.status).toBe('completed')
+    expect(completed.steps.every(s => s.status === 'completed')).toBe(true)
+  })
+
+  it('full lifecycle broadcasts correct events', () => {
+    const wf = createWorkflow('ci', ['test'])
+    executeWorkflow(wf.id)
+    completeWorkflow(wf.id)
+    expect(broadcastEvents.map(e => e.type)).toEqual([
+      'workflow:added', 'workflow:updated', 'workflow:updated',
+    ])
+  })
+})