@shaykec/bridge 0.4.20 → 0.4.22

package/src/server.js

@@ -1,5 +1,5 @@
 /**
- * ClaudeTeach Bridge Server — WebSocket + SSE + REST communication hub.
+ * Socrates Bridge Server — WebSocket + SSE + REST communication hub.
  * Upgraded from packages/core/src/bridge-server.js.
  *
  * Endpoints:
@@ -21,7 +21,7 @@
  */
 
 import { createServer } from 'http';
-import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, statSync, createReadStream } from 'fs';
 import { join, dirname, extname, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { exec } from 'child_process';
@@ -34,17 +34,37 @@ import {
   serializeEnvelope,
   MSG_SYS_CONNECT,
   MSG_SYS_DISCONNECT,
+  MSG_EVENT_PTY_OUTPUT,
   DEFAULT_PORT,
   INBOX_DIR,
   MAX_LONG_POLL_TIMEOUT_MS,
   ACHIEVEMENTS,
+  BELTS,
+  PLAYGROUND_EXEC_TIMEOUT_MS,
+  PLAYGROUND_MAX_OUTPUT_BYTES,
 } from '@shaykec/shared';
 
 import { TierManager, generateClientId, validateHandshake } from './protocol.js';
 import { EventRouter } from './router.js';
 import { renderTemplate, listTemplates } from './templates.js';
 import { createSession, execCommand, getSession, destroySession, cleanupIdleSessions } from './terminal.js';
+import {
+  createPtySession, writeToPty, resizePty, setPtyCallbacks,
+  hasPtySession, destroyPtySession, writeSessionFiles, runSetupCommands,
+  cleanupIdlePtySessions, getPtyOutputBuffer,
+} from './pty-manager.js';
+import { extractAndRouteVisuals, extractAndRouteMedia, extractAndRouteSuggestions, extractButtons, extractInlineBlocks, enhanceWithSmartComponents, stripCanvasCommands } from './visual-interceptor.js';
 import { createAgentServer } from '@shaykec/agent-web/server';
+import {
+  listSessions as listStoredSessions,
+  getSession as getStoredSession,
+  appendMessage as appendStoredMessage,
+  updateMeta as updateStoredMeta,
+  deleteSession as deleteStoredSession,
+  purgeAll as purgeStoredSessions,
+  detectSessionTag,
+  generateTitle,
+} from './session-store.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -73,12 +93,12 @@ const MIME_TYPES = {
 };
 
 /**
- * Start the ClaudeTeach bridge server.
+ * Start the Socrates bridge server.
  * @param {object} [options]
  * @param {number} [options.port=3456] - Port number
  * @param {function} [options.onReady] - Callback when server is listening
  * @param {function} [options.onTierChange] - Callback(oldTier, newTier) on tier changes
- * @param {object} [options.progressProvider] - Object with getProgress() method
+ * @param {object} [options.progressProvider] - Object with getProgress() and saveProgress() methods
  * @returns {{ server: object, tierManager: TierManager, router: EventRouter, close: function }}
  */
 export function startServer(options = {}) {
@@ -87,24 +107,217 @@ export function startServer(options = {}) {
   const router = new EventRouter(tierManager);
 
   // Chat is delegated entirely to @shaykec/agent-web
-  const agentConfig = { cwd: process.cwd() };
+  const agentConfig = {
+    cwd: process.cwd(),
+    systemPrompt: [
+      'You are Socrates, a Socratic AI tutor. You teach through guided dialogue.',
+      '',
+      'RULES:',
+      '- Ask, don\'t tell. Guide the user to discover answers through questions.',
+      '- The user writes all code. You guide, they do.',
+      '- One step at a time. Award XP after milestones.',
+      '',
+      'ENVIRONMENT:',
+      '- The user is in a web app with a visual canvas beside the chat.',
+      '- A bridge server at http://localhost:3456 has visual tools.',
+      '- When a user sends /teach <topic>, use the Skill tool to read the "teach" skill, then follow its instructions.',
+      '- When a user sends /learn <topic>, use the Skill tool to read the "learn" skill, then follow its instructions.',
+      '- For /stats, /ask, /canvas, /level-up — use the Skill tool to read the matching skill name.',
+      '- For casual questions, answer helpfully. Include mermaid diagrams when useful —',
+      '  they auto-appear on the visual canvas.',
+      '',
+      'MANDATORY — RICH COMPONENTS IN EVERY TEACHING RESPONSE:',
+      'You MUST use the smart components below in EVERY teaching response. Plain markdown alone is NOT acceptable.',
+      'Each teaching response MUST include at least 3 of these components. The canvas renders them as interactive UI.',
+      '',
+      'SMART BUTTONS (REQUIRED for questions and choices):',
+      '- ALWAYS use buttons when asking the user a question or presenting choices.',
+      '- Embed inline buttons using an HTML comment:',
+      '  <!-- buttons: {"id":"unique-id","type":"single","prompt":"Pick one:","options":[{"label":"Option A","value":"text sent when clicked"}]} -->',
+      '- Types: "single" (pick one), "multi" (pick several + submit), "rating" (1-5 scale).',
+      '- Each option needs "label" (display text) and "value" (message sent on click).',
+      '- Use buttons for contextual choices (topic selection, difficulty rating, yes/no).',
+      '- Use suggestion chips (<!-- suggestions: [...] -->) for general navigation.',
+      '',
+      'SMART LISTS (REQUIRED for any list of items):',
+      '- NEVER use plain markdown lists. ALWAYS use smart lists instead:',
+      '  <!-- list: {"id":"x","style":"cards","items":[{"icon":"book","title":"T","description":"D","action":"msg"}]} -->',
+      '- Styles: "cards" (rich cards with icons), "numbered" (ordered steps), "checklist" (checkable items), "compact" (dense).',
+      '- Items with "action" are clickable and send the action text as a message.',
+      '',
+      'PROGRESS BARS (REQUIRED to show lesson progress):',
+      '- Include a progress bar in EVERY teaching response to show where the user is in the lesson:',
+      '  <!-- progress: {"id":"lesson-progress","label":"Lesson Progress","current":1,"total":7,"style":"bar"} -->',
+      '- Styles: "bar" (horizontal), "steps" (step indicators), "ring" (circular).',
+      '- Update the current value as the user progresses through steps.',
+      '',
+      'INFO CARDS (REQUIRED for tips, warnings, and key concepts):',
+      '- Use info cards for important callouts — NEVER use plain bold text for tips or warnings:',
+      '  <!-- card: {"id":"x","type":"tip","title":"Pro Tip","content":"markdown text here"} -->',
+      '- Types: "tip" (blue), "warning" (yellow), "error" (red), "success" (green), "concept" (purple).',
+      '- Use "concept" for key definitions, "tip" for best practices, "warning" for common mistakes.',
+      '',
+      'CODE SNIPPETS (use when showing code examples):',
+      '  <!-- code: {"id":"x","language":"js","filename":"app.js","code":"const x = 1;","highlight":[1]} -->',
+      '',
+      'STEP TRACKERS (use to show multi-step workflows):',
+      '  <!-- steps: {"id":"x","current":2,"steps":[{"label":"Create file","status":"done"},{"label":"Write code","status":"active"},{"label":"Test","status":"pending"}]} -->',
+      '  Statuses: done, active, pending.',
+      '',
+      'CANVAS VISUAL COMMANDS (appear in the canvas pane, not in the chat bubble):',
+      '- Diagrams: <!-- canvas:diagram: {"format":"mermaid","content":"graph TD\\n  A-->B","animate":true} -->',
+      '  Or use a fenced ```mermaid code block — it auto-routes to the canvas.',
+      '- Celebrations: <!-- canvas:celebrate: {"type":"xp","xpAwarded":20} -->',
+      '  Types: "xp" (confetti), "level-up" (include "newBelt":"green"), "perfect-score".',
+      '- Rich HTML: <!-- canvas:html: {"html":"<div>...</div>"} -->',
+      '  Use for images, YouTube embeds, further-reading cards.',
+      '- Practice terminal: <!-- canvas:terminal: {"task":"Create a git repo","validations":[{"label":"Repo created","passed":false}],"hints":["Use git init"]} -->',
+      '- Dashboard: <!-- canvas:dashboard: {"progress":{"xp":100,"belt":"yellow","modules":[...]}} -->',
+      '- Web embed: <!-- canvas:web-embed: {"url":"https://...","title":"Reference"} -->',
+      '- Code playground: <!-- canvas:code: {"language":"javascript","code":"function add(a,b) {...}","tests":[...]} -->',
+      '- These comments are stripped from the displayed text — the user sees only the rendered component.',
+      '- For interactive quizzes and games that need the user\'s answer back, use curl with await (read the skill for details).',
+      '',
+      'COMPONENT ORDER (follow this layout in every teaching response):',
+      '1. Step tracker / Progress bar — orientation elements go FIRST',
+      '2. Teaching text, concept cards, lists, diagrams, code snippets — content in the middle',
+      '3. Question + buttons — interactive prompt goes LAST (just before suggestions)',
+      '4. Suggestion chips — always the very last element',
+      'Never place a step tracker or progress bar after a question or buttons.',
+      '',
+      'EXAMPLE TEACHING RESPONSE (follow this pattern):',
+      '```',
+      '<!-- progress: {"id":"p1","label":"Lesson Progress","current":2,"total":5,"style":"bar"} -->',
+      '',
+      'Great question! Let\'s explore **variables** in JavaScript.',
+      '',
+      '<!-- card: {"id":"concept1","type":"concept","title":"What is a Variable?","content":"A variable is a named container that stores a value. Think of it as a labeled box."} -->',
+      '',
+      'There are three ways to declare variables:',
+      '',
+      '<!-- list: {"id":"var-types","style":"cards","items":[{"icon":"📦","title":"const","description":"Cannot be reassigned. Use by default."},{"icon":"🔄","title":"let","description":"Can be reassigned. Use for values that change."},{"icon":"⚠️","title":"var","description":"Old syntax. Avoid in modern code."}]} -->',
+      '',
+      '<!-- card: {"id":"tip1","type":"tip","title":"Best Practice","content":"Always start with `const`. Only switch to `let` if you need to reassign."} -->',
+      '',
+      '<!-- canvas:diagram: {"format":"mermaid","content":"graph LR\\n  const[const] -->|immutable| safe[Safe default]\\n  let[let] -->|mutable| change[Values that change]\\n  var[var] -->|avoid| legacy[Legacy code]"} -->',
+      '',
+      'Which declaration would you use for a user\'s age that changes every year?',
+      '',
+      '<!-- buttons: {"id":"q1","type":"single","prompt":"Pick the best option:","options":[{"label":"const","value":"I would use const for age"},{"label":"let","value":"I would use let for age"},{"label":"var","value":"I would use var for age"}]} -->',
+      '',
+      '<!-- suggestions: [{"label":"Show me an example","text":"Show me a code example"},{"label":"Quiz me","text":"Give me a quiz"}] -->',
+      '```',
+      '',
+      'START: /teach <topic> for lessons, /learn <topic> for free-form learning.',
+    ].join('\n'),
+    tools: ['Bash(*)', 'Read', 'Write', 'Edit', 'Glob', 'Grep', 'Skill'],
+    permissionMode: 'bypassPermissions',
+    settingSources: ['user', 'project'],
+  };
   if (options.pluginDir) {
     agentConfig.plugins = [{ type: 'local', path: options.pluginDir }];
   }
+  const autoRoutedMediaUrls = new Set();
+  const sessionTitleSet = new Set();
+
   const agentServer = createAgentServer({
     basePath: '/api',
     config: agentConfig,
     hooks: {
-      // Relay chat envelopes to visual WS clients so the canvas receives responses
       onMessage: (envelope) => {
+        if (envelope.type === 'chat:assistant' && envelope.payload?.text) {
+          // Auto-enhance plain markdown with smart components when the AI
+          // didn't emit them. Must run before extraction so the injected
+          // HTML comments get picked up by extractButtons/extractInlineBlocks.
+          envelope.payload.text = enhanceWithSmartComponents(envelope.payload.text);
+
+          const { cleanText, buttons } = extractButtons(envelope.payload.text);
+          if (buttons.length > 0) {
+            envelope.payload.text = cleanText;
+            envelope.payload.buttons = buttons;
+          }
+          const { cleanText: text2, blocks } = extractInlineBlocks(envelope.payload.text);
+          if (blocks.length > 0) {
+            envelope.payload.text = text2;
+            envelope.payload.blocks = blocks;
+          }
+        }
+
+        if (envelope.type === 'chat:assistant' && envelope.payload?.text) {
+          const rawText = envelope.payload.text;
+          extractAndRouteVisuals(rawText, tierManager, router);
+          extractAndRouteMedia(rawText, router, autoRoutedMediaUrls);
+          extractAndRouteSuggestions(rawText, tierManager);
+          envelope.payload.text = stripCanvasCommands(envelope.payload.text);
+        }
+
         const data = JSON.stringify(envelope);
         tierManager.broadcastWs(data);
         tierManager.broadcastSse(data);
+
+        // Persist messages to session store
+        const sid = envelope.sessionId || envelope.payload?.sessionId;
+        if (sid) {
+          try {
+            if (envelope.type === 'chat:assistant' && envelope.payload?.text) {
+              appendStoredMessage(sid, {
+                role: 'assistant',
+                text: envelope.payload.text,
+                timestamp: envelope.timestamp || Date.now(),
+              });
+              // Auto-title: set title from first assistant response
+              if (!sessionTitleSet.has(sid)) {
+                sessionTitleSet.add(sid);
+                const title = generateTitle(envelope.payload.text);
+                updateStoredMeta(sid, { title });
+              }
+            } else if (envelope.type === 'chat:tool-use') {
+              appendStoredMessage(sid, {
+                role: 'tool-use',
+                text: `Using ${envelope.payload?.toolName || 'tool'}`,
+                data: envelope.payload,
+                timestamp: envelope.timestamp || Date.now(),
+              });
+            } else if (envelope.type === 'chat:tool-result') {
+              appendStoredMessage(sid, {
+                role: 'tool-result',
+                data: envelope.payload,
+                timestamp: envelope.timestamp || Date.now(),
+              });
+            }
+          } catch { /* don't break chat flow on storage errors */ }
+        }
       },
     },
   });
   const chatMiddleware = agentServer.middleware();
 
+  // Patch: escape leading '/' in messages to prevent SDK slash command interception.
+  // The Claude Agent SDK intercepts messages starting with '/' as built-in slash commands
+  // (e.g., /debug, /review). Our custom skills (/teach, /learn, etc.) aren't registered
+  // with the SDK, so they get "Unknown skill" errors. Prepending a zero-width space
+  // bypasses the SDK's slash handler while preserving the text for Claude.
+  const sm = agentServer.sessions;
+  const origSend = sm.sendMessage.bind(sm);
+  sm.sendMessage = function(sessionId, text) {
+    // Persist user message + auto-tag session
+    try {
+      appendStoredMessage(sessionId, {
+        role: 'user',
+        text,
+        timestamp: Date.now(),
+      });
+      const tag = detectSessionTag(text);
+      if (tag) {
+        updateStoredMeta(sessionId, tag);
+        sessionTitleSet.add(sessionId);
+      }
+    } catch { /* don't break chat flow */ }
+
+    const escaped = text.startsWith('/') ? '\u200B' + text : text;
+    return origSend(sessionId, escaped);
+  };
+
   if (options.onTierChange) {
     tierManager.onTierChange(options.onTierChange);
   }
@@ -114,13 +327,14 @@ export function startServer(options = {}) {
 
   // Create HTTP server
   const server = createServer((req, res) => {
-    handleRequest(req, res, tierManager, router, options, chatMiddleware);
+    handleRequest(req, res, tierManager, router, options, chatMiddleware, agentServer);
   });
 
   // Both WSSes use noServer to avoid ws library destroying sockets
   // on path mismatch (ws docs: use noServer for multiple WSSes)
   const wss = new WebSocketServer({ noServer: true });
   const chatWss = new WebSocketServer({ noServer: true });
+  const ptyWss = new WebSocketServer({ noServer: true });
 
   server.on('upgrade', (req, socket, head) => {
     const { pathname } = new URL(req.url, `http://${req.headers.host}`);
@@ -132,11 +346,60 @@ export function startServer(options = {}) {
       chatWss.handleUpgrade(req, socket, head, (ws) => {
         chatWss.emit('connection', ws, req);
       });
+    } else if (pathname.startsWith('/ws/terminal/')) {
+      ptyWss.handleUpgrade(req, socket, head, (ws) => {
+        const sessionId = pathname.replace('/ws/terminal/', '');
+        ptyWss.emit('connection', ws, sessionId);
+      });
     } else {
       socket.destroy();
     }
   });
 
+  // PTY terminal WebSocket connections
+  ptyWss.on('connection', (ws, sessionId) => {
+    if (!hasPtySession(sessionId)) {
+      ws.close(4004, 'Unknown PTY session');
+      return;
+    }
+
+    setPtyCallbacks(sessionId,
+      (data) => {
+        if (ws.readyState === 1) {
+          ws.send(JSON.stringify({ type: 'data', data }));
+        }
+        // Tee output to agent event queue for observation
+        router.enqueuePtyEvent(sessionId, data);
+      },
+      ({ exitCode, signal }) => {
+        if (ws.readyState === 1) {
+          ws.send(JSON.stringify({ type: 'exit', exitCode, signal }));
+          ws.close(1000, 'PTY exited');
+        }
+      }
+    );
+
+    ws.on('message', (rawData) => {
+      try {
+        const msg = JSON.parse(rawData.toString());
+        switch (msg.type) {
+          case 'input':
+            writeToPty(sessionId, msg.data);
+            break;
+          case 'resize':
+            if (msg.cols && msg.rows) {
+              resizePty(sessionId, msg.cols, msg.rows);
+            }
+            break;
+        }
+      } catch { /* ignore malformed messages */ }
+    });
+
+    ws.on('close', () => {
+      // Keep PTY alive for reconnect; cleanup timer handles idle sessions
+    });
+  });
+
   // Wire agent-web transport to the chat WSS
   chatWss.on('connection', (ws) => {
     agentServer.transport.handleWsConnection(
@@ -257,11 +520,14 @@ export function startServer(options = {}) {
   tierManager.startHeartbeat();
 
   // Periodically clean up idle terminal sessions (every 60s)
-  const terminalCleanupInterval = setInterval(() => cleanupIdleSessions(), 60000);
+  const terminalCleanupInterval = setInterval(() => {
+    cleanupIdleSessions();
+    cleanupIdlePtySessions();
+  }, 60000);
 
   // Start listening
   server.listen(port, () => {
-    console.log(`ClaudeTeach bridge server running on http://localhost:${port}`);
+    console.log(`Socrates bridge server running on http://localhost:${port}`);
     console.log(`  WebSocket  /ws          — bidirectional (extension + canvas)`);
     console.log(`  SSE        /sse         — server-push (canvas-only)`);
     console.log(`  POST       /api/event   — receive user events`);
@@ -270,9 +536,13 @@ export function startServer(options = {}) {
     console.log(`  GET        /api/progress — progress data`);
     console.log(`  GET        /api/events/wait — long-poll for events`);
     console.log(`  POST       /api/terminal/exec — execute terminal commands`);
-    console.log(`  POST       /api/quiz    — send quiz + wait for answer`);
-    console.log(`  POST       /api/game    — send game + wait for result`);
+    console.log(`  POST       /api/canvas   — unified visual commands (with optional await)`);
+    console.log(`  POST       /api/pty/create    — create PTY terminal session`);
+    console.log(`  WebSocket  /ws/terminal/:id   — PTY terminal I/O`);
+    console.log(`  POST       /api/playground/exec — execute code snippets`);
+    console.log(`  POST       /api/workshop/setup — set up workshop scenario`);
     console.log(`  REST       /api/chat/*        — chat (via @shaykec/agent-web)`);
+    console.log(`  REST       /api/sessions      — session management (list/get/update/delete/purge)`);
     console.log(`  WebSocket  /api/ws            — chat WebSocket`);
     console.log(`  SSE        /api/sse           — chat SSE`);
     console.log(`  GET        /health            — health check`);
@@ -301,10 +571,10 @@ export function startServer(options = {}) {
 /**
  * Handle HTTP requests.
  */
-function handleRequest(req, res, tierManager, router, options, chatMiddleware) {
+function handleRequest(req, res, tierManager, router, options, chatMiddleware, agentServer) {
   // CORS headers
   res.setHeader('Access-Control-Allow-Origin', '*');
-  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
   res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
 
   if (req.method === 'OPTIONS') {
@@ -318,7 +588,15 @@ function handleRequest(req, res, tierManager, router, options, chatMiddleware) {
 
   // --- Chat endpoints delegated to @shaykec/agent-web ---
   if (pathname.startsWith('/api/chat') || pathname === '/api/sse' || pathname === '/api/health') {
-    chatMiddleware(req, res);
+    try {
+      chatMiddleware(req, res);
+    } catch (err) {
+      console.error('[bridge] chatMiddleware sync error:', err.message);
+      if (!res.headersSent) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Internal server error' }));
+      }
+    }
     return;
   }
 
@@ -349,6 +627,11 @@ function handleRequest(req, res, tierManager, router, options, chatMiddleware) {
     return;
   }
 
+  if (req.method === 'GET' && pathname === '/api/constants') {
+    sendJson(res, 200, { belts: BELTS });
+    return;
+  }
+
   if (req.method === 'GET' && pathname === '/api/events') {
     handleApiPollEvents(res, router);
     return;
@@ -364,8 +647,8 @@ function handleRequest(req, res, tierManager, router, options, chatMiddleware) {
     return;
   }
 
-  if (req.method === 'POST' && pathname === '/api/visual') {
-    handleApiVisual(req, res, router);
+  if (req.method === 'POST' && pathname === '/api/canvas') {
+    handleApiCanvas(req, res, router, url);
     return;
   }
 
@@ -374,13 +657,18 @@ function handleRequest(req, res, tierManager, router, options, chatMiddleware) {
     return;
   }
 
-  if (req.method === 'POST' && pathname === '/api/quiz') {
-    handleApiQuiz(req, res, router, url);
+  if (req.method === 'POST' && pathname === '/api/pty/create') {
+    handleApiPtyCreate(req, res);
+    return;
+  }
+
+  if (req.method === 'POST' && pathname === '/api/playground/exec') {
+    handleApiPlaygroundExec(req, res);
     return;
   }
 
-  if (req.method === 'POST' && pathname === '/api/game') {
-    handleApiGame(req, res, router, url);
+  if (req.method === 'POST' && pathname === '/api/workshop/setup') {
+    handleApiWorkshopSetup(req, res, router);
     return;
   }
 
@@ -389,12 +677,77 @@ function handleRequest(req, res, tierManager, router, options, chatMiddleware) {
     return;
   }
 
+  // --- Progress write ---
+  if (req.method === 'POST' && pathname === '/api/progress') {
+    handleApiProgressWrite(req, res, options, router);
+    return;
+  }
+
+  // --- Module static resources (images, videos, HTML snippets) ---
+  {
+    const resMatch = pathname.match(/^\/api\/module\/([\w-]+)\/resources\/([\w.-]+)$/);
+    if (req.method === 'GET' && resMatch) {
+      handleApiModuleResource(res, resMatch[1], resMatch[2]);
+      return;
+    }
+  }
+
+  // --- Module content ---
+  if (req.method === 'GET' && pathname.startsWith('/api/module/')) {
+    const slug = pathname.replace('/api/module/', '');
+    if (slug && !slug.includes('/')) {
+      handleApiModuleContent(res, slug);
+      return;
+    }
+  }
+
   // --- Modules catalog ---
   if (req.method === 'GET' && pathname === '/api/modules') {
     handleApiModules(res);
     return;
   }
 
+  // --- Journeys ---
+  if (req.method === 'GET' && pathname === '/api/journeys') {
+    handleApiJourneys(res, options);
+    return;
+  }
+
+  if (req.method === 'POST' && pathname === '/api/journeys/activate') {
+    handleApiJourneyActivate(req, res, options);
+    return;
+  }
+
+  // --- Sessions ---
+  if (req.method === 'GET' && pathname === '/api/sessions') {
+    handleApiSessionsList(res);
+    return;
+  }
+
+  {
+    const sessionMatch = pathname.match(/^\/api\/sessions\/([a-f0-9-]+)$/);
+    if (sessionMatch) {
+      const sid = sessionMatch[1];
+      if (req.method === 'GET') {
+        handleApiSessionGet(res, sid);
+        return;
+      }
+      if (req.method === 'PUT') {
+        handleApiSessionUpdate(req, res, sid);
+        return;
+      }
+      if (req.method === 'DELETE') {
+        handleApiSessionDelete(res, sid, agentServer);
+        return;
+      }
+    }
+  }
+
+  if (req.method === 'DELETE' && pathname === '/api/sessions') {
+    handleApiSessionsPurge(res, agentServer);
+    return;
+  }
+
   // --- Settings ---
   if (req.method === 'GET' && pathname === '/api/settings') {
     handleApiSettingsGet(res);
@@ -516,6 +869,7 @@ function handleApiCapture(req, res) {
 
 /**
  * GET /api/progress — return progress data with achievements.
+ * Enriches module entries with title/description/difficulty from module.yaml catalog.
  */
 function handleApiProgress(res, options) {
   let progress;
@@ -525,6 +879,11 @@ function handleApiProgress(res, options) {
     progress = { user: { xp: 0 }, modules: {} };
   }
 
+  // Enrich modules with catalog metadata
+  const modulesDir = resolve(__dirname, '..', '..', 'modules');
+  const moduleMap = buildModuleMap(modulesDir);
+  progress.modules = enrichModulesWithMetadata(progress.modules, moduleMap);
+
   // Include achievements data from progress file
   const achievements = progress.achievements || { unlocked: [], progress: {} };
   const unlocked = (achievements.unlocked || []).map(a => ({
@@ -590,6 +949,7 @@ function handleApiModules(res) {
             }
           }
           if (meta.slug) {
+            const hasWorkshop = existsSync(join(modulesDir, entry, 'workshop.yaml'));
             modules.push({
               slug: meta.slug,
               title: meta.title || meta.slug,
@@ -597,6 +957,7 @@ function handleApiModules(res) {
               category: meta.category || 'general',
               difficulty: meta.difficulty || 'beginner',
               icon: meta.icon || null,
+              hasWorkshop,
             });
           }
         } catch {
@@ -612,11 +973,565 @@ function handleApiModules(res) {
 }
 
 /**
- * Settings file path: ~/.claude-teach/config.yaml
+ * GET /api/journeys — return all journeys with resolved module status and progress.
+ */
+function handleApiJourneys(res, options) {
+  try {
+    const journeysDir = resolve(__dirname, '..', '..', 'journeys');
+    const journeys = [];
+
+    if (existsSync(journeysDir)) {
+      const files = readdirSync(journeysDir).filter(f => f.endsWith('.yaml') || f.endsWith('.yml'));
+      for (const file of files) {
+        try {
+          const raw = readFileSync(join(journeysDir, file), 'utf-8');
+          const parsed = parseYamlSimple(raw);
+          if (parsed && parsed.slug) {
+            journeys.push(parsed);
+          }
+        } catch { /* skip */ }
+      }
+    }
+
+    let progress = { modules: {}, journey: { active: null, progress: {} } };
+    if (options.progressProvider && typeof options.progressProvider.getProgress === 'function') {
+      progress = options.progressProvider.getProgress();
+    }
+
+    const modulesDir = resolve(__dirname, '..', '..', 'modules');
+    const moduleMap = buildModuleMap(modulesDir);
+
+    const resolved = journeys.map(j => resolveJourneyForApi(j, moduleMap, progress));
+    sendJson(res, 200, {
+      journeys: resolved,
+      activeJourney: progress.journey?.active || null,
+    });
+  } catch {
+    sendJson(res, 200, { journeys: [], activeJourney: null });
+  }
+}
+
+/**
+ * POST /api/journeys/activate — set or clear the active journey.
+ */
+function handleApiJourneyActivate(req, res, options) {
+  readBody(req, (err, body) => {
+    if (err) return sendJson(res, 400, { error: 'Invalid request body' });
+    try {
+      const { slug } = body;
+      if (options.progressProvider && typeof options.progressProvider.getProgress === 'function') {
+        const progress = options.progressProvider.getProgress();
+        if (!progress.journey) progress.journey = { active: null, progress: {} };
+
+        if (slug) {
+          progress.journey.active = slug;
+          if (!progress.journey.progress[slug]) {
+            progress.journey.progress[slug] = { started: new Date().toISOString().split('T')[0] };
+          }
+        } else {
+          progress.journey.active = null;
+        }
+
+        if (typeof options.progressProvider.saveProgress === 'function') {
+          options.progressProvider.saveProgress(progress);
+        }
+        sendJson(res, 200, { ok: true, active: progress.journey.active });
+      } else {
+        sendJson(res, 200, { ok: true, active: null });
+      }
+    } catch (activateErr) {
+      sendJson(res, 500, { error: activateErr.message });
+    }
+  });
+}
+
+/**
+ * Build a map of module slugs to basic metadata from the modules directory.
+ */
+function buildModuleMap(modulesDir) {
+  const map = new Map();
+  try {
+    if (!existsSync(modulesDir)) return map;
+    for (const entry of readdirSync(modulesDir)) {
+      const yamlPath = join(modulesDir, entry, 'module.yaml');
+      if (!existsSync(yamlPath)) continue;
+      try {
+        const raw = readFileSync(yamlPath, 'utf-8');
+        const meta = parseYamlSimple(raw);
+        if (meta?.slug) {
+          map.set(meta.slug, {
+            slug: meta.slug,
+            title: meta.title || meta.slug,
+            description: meta.description || '',
+            difficulty: meta.difficulty || 'beginner',
+          });
+        }
+      } catch { /* skip */ }
+    }
+  } catch { /* skip */ }
+  return map;
+}
+
+/**
+ * Parse simple flat YAML fields (no nested structures).
+ * For journey files we need nested parsing, so use JSON-safe subset.
+ */
+function parseYamlSimple(raw) {
+  try {
+    // Use dynamic import workaround — js-yaml may not be available in bridge
+    // Instead, parse the YAML structure manually for journeys
+    const lines = raw.split('\n');
+    const result = {};
+    let currentKey = null;
+    let currentArray = null;
+    let inStages = false;
+    let currentStage = null;
+    let inModules = false;
+
+    for (const line of lines) {
+      const trimmed = line.trimEnd();
+
+      // Top-level scalar
+      const scalarMatch = trimmed.match(/^(\w[\w_-]*):\s*(.+)$/);
+      if (scalarMatch && !inStages) {
+        currentKey = scalarMatch[1];
+        let val = scalarMatch[2].trim();
+        if (val.startsWith('"') && val.endsWith('"')) val = val.slice(1, -1);
+        if (val.startsWith('[') && val.endsWith(']')) {
+          val = val.slice(1, -1).split(',').map(s => s.trim().replace(/^["']|["']$/g, ''));
+        } else if (/^\d+$/.test(val)) {
+          val = parseInt(val, 10);
+        }
+        result[currentKey] = val;
+        continue;
+      }
+
+      // Top-level key with no value (start of block)
+      const blockMatch = trimmed.match(/^(\w[\w_-]*):\s*$/);
+      if (blockMatch) {
+        currentKey = blockMatch[1];
+        if (currentKey === 'stages') {
+          inStages = true;
+          result.stages = [];
+        }
+        continue;
+      }
+
+      if (inStages) {
+        // New stage entry
+        const stageStart = trimmed.match(/^\s+-\s+name:\s*"?(.+?)"?\s*$/);
+        if (stageStart) {
+          currentStage = { name: stageStart[1], description: '', modules: [] };
+          result.stages.push(currentStage);
+          inModules = false;
+          continue;
+        }
+
+        // Stage description
+        const descMatch = trimmed.match(/^\s+description:\s*"?(.+?)"?\s*$/);
+        if (descMatch && currentStage) {
+          currentStage.description = descMatch[1];
+          continue;
+        }
+
+        // Modules block start
+        if (trimmed.match(/^\s+modules:\s*$/)) {
+          inModules = true;
+          continue;
+        }
+
+        // Module entry — object form { slug: x, title: y }
+        const objModule = trimmed.match(/^\s+-\s*\{\s*slug:\s*(\S+),\s*title:\s*"(.+?)"\s*\}/);
+        if (objModule && inModules && currentStage) {
+          currentStage.modules.push({ slug: objModule[1], title: objModule[2] });
+          continue;
+        }
+
+        // Module entry — plain slug
+        const slugModule = trimmed.match(/^\s+-\s+(\S+)\s*$/);
+        if (slugModule && inModules && currentStage) {
+          currentStage.modules.push(slugModule[1]);
+          continue;
+        }
+      }
+    }
+
+    return result;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve a journey's modules against the module map and progress.
+ */
+function resolveJourneyForApi(journey, moduleMap, progress) {
+  const moduleProgress = progress.modules || {};
+  let totalModules = 0;
+  let completedModules = 0;
+  let comingSoonModules = 0;
+
+  const stages = (journey.stages || []).map((stage, idx) => {
+    const modules = (stage.modules || []).map(ref => {
+      totalModules++;
+      const slug = typeof ref === 'string' ? ref : ref.slug;
+      const titleHint = typeof ref === 'object' ? ref.title : null;
+      const regMod = moduleMap.get(slug);
+      const modProg = moduleProgress[slug];
+
+      if (!regMod) {
+        comingSoonModules++;
+        return { slug, title: titleHint || slug, status: 'coming_soon' };
+      }
+
+      let status = 'available';
+      if (modProg?.status === 'completed') { status = 'completed'; completedModules++; }
+      else if (modProg?.status === 'in-progress') { status = 'in_progress'; }
+
+      return { slug, title: regMod.title, status, difficulty: regMod.difficulty };
+    });
+
+    const existing = modules.filter(m => m.status !== 'coming_soon');
+    const done = existing.length > 0 && existing.every(m => m.status === 'completed');
+    const inProg = modules.some(m => m.status === 'in_progress' || m.status === 'completed') && !done;
+
+    let stageStatus = 'locked';
+    if (done) stageStatus = 'completed';
+    else if (inProg) stageStatus = 'in_progress';
+
+    return { name: stage.name, description: stage.description || '', stageIndex: idx, status: stageStatus, modules };
+  });
+
+  // Unlock logic
+  for (let i = 0; i < stages.length; i++) {
+    if (i === 0 && stages[i].status === 'locked') {
+      stages[i].status = 'available';
+      stages[i].modules.forEach(m => { if (m.status !== 'coming_soon' && m.status !== 'completed' && m.status !== 'in_progress') m.status = 'available'; });
+    } else if (i > 0 && stages[i - 1].status === 'completed' && stages[i].status === 'locked') {
+      stages[i].status = 'available';
+      stages[i].modules.forEach(m => { if (m.status !== 'coming_soon' && m.status !== 'completed' && m.status !== 'in_progress') m.status = 'available'; });
+    }
+  }
+
+  const currentStageIndex = stages.findIndex(s => s.status !== 'completed');
+  const availableModules = totalModules - comingSoonModules;
+
+  return {
+    slug: journey.slug,
+    title: journey.title,
+    description: journey.description || '',
+    icon: journey.icon || 'book',
+    tags: Array.isArray(journey.tags) ? journey.tags : [],
+    difficulty: journey.difficulty || 'beginner-to-advanced',
+    estimatedHours: journey.estimated_hours || null,
+    stages,
+    stats: {
+      totalModules,
+      completedModules,
+      comingSoonModules,
+      availableModules,
+      totalStages: stages.length,
+      completedStages: stages.filter(s => s.status === 'completed').length,
+      currentStageIndex: currentStageIndex >= 0 ? currentStageIndex : stages.length - 1,
+      progressPercent: availableModules > 0 ? Math.round((completedModules / availableModules) * 100) : 0,
+    },
+  };
+}
+
+/**
+ * POST /api/progress — write progress updates.
+ * Accepts { xp, module, status, walkthroughStep } and merges into the progress file.
+ * Uses progressProvider.saveProgress() when available for proper YAML serialization.
+ * Broadcasts updated progress to all connected canvas clients.
+ */
+function handleApiProgressWrite(req, res, options, router) {
+  readBody(req, (err, body) => {
+    if (err) {
+      sendJson(res, 400, { error: 'Invalid request body' });
+      return;
+    }
+
+    if (!body || typeof body !== 'object') {
+      sendJson(res, 400, { error: 'Body must be a JSON object' });
+      return;
+    }
+
+    const provider = options.progressProvider;
+    const hasProvider = provider
+      && typeof provider.getProgress === 'function'
+      && typeof provider.saveProgress === 'function';
+
+    try {
+      const progress = hasProvider
+        ? provider.getProgress()
+        : { user: { xp: 0 }, modules: {} };
+
+      if (!progress.user) progress.user = { xp: 0 };
+      if (!progress.modules) progress.modules = {};
+
+      if (typeof body.xp === 'number') {
+        progress.user.xp = body.xp;
+      }
+
+      if (body.module && body.status) {
+        if (!progress.modules[body.module]) {
+          progress.modules[body.module] = {
+            status: body.status,
+            started: new Date().toISOString().split('T')[0],
+          };
+        } else {
+          progress.modules[body.module].status = body.status;
+        }
+        progress.modules[body.module].last_session = new Date().toISOString().split('T')[0];
+
+        if (typeof body.walkthroughStep === 'number') {
+          progress.modules[body.module].walkthrough_step = body.walkthroughStep;
+        }
+      }
+
+      progress.user.modules_completed = Object.values(progress.modules)
+        .filter(m => m.status === 'completed').length;
+
+      if (hasProvider) {
+        provider.saveProgress(progress);
+      }
+
+      // Broadcast updated progress to connected canvas clients (enriched with catalog metadata)
+      if (router) {
+        const modulesDir = resolve(__dirname, '..', '..', 'modules');
+        const moduleMap = buildModuleMap(modulesDir);
+        const enriched = enrichModulesWithMetadata(progress.modules, moduleMap);
+        const modules = Object.entries(enriched).map(([slug, m]) => ({ slug, ...m }));
+        const dashboardEnvelope = createEnvelope('canvas:dashboard', {
+          progress: {
+            xp: progress.user.xp || 0,
+            belt: progress.user.belt,
+            modules,
+            completedCount: modules.filter(m => m.status === 'completed').length,
+            totalCount: modules.length,
+          },
+        }, 'bridge');
+        router.routeVisualCommand(dashboardEnvelope);
+      }
+
+      sendJson(res, 200, { ok: true });
+    } catch (writeErr) {
+      sendJson(res, 500, { error: writeErr.message });
+    }
+  });
+}
+
+/**
+ * GET /api/module/:slug — serve full module content.
+ */
+function handleApiModuleContent(res, slug) {
+  const modulesDir = resolve(__dirname, '..', '..', 'modules');
+  const moduleDir = join(modulesDir, slug);
+
+  if (!existsSync(join(moduleDir, 'module.yaml'))) {
+    sendJson(res, 404, { error: `Module "${slug}" not found` });
+    return;
+  }
+
+  try {
+    const files = {};
+    const entries = readdirSync(moduleDir);
+    for (const entry of entries) {
+      const filePath = join(moduleDir, entry);
+      try {
+        const stat = statSync(filePath);
+        if (stat.isFile() && stat.size < 100_000) {
+          files[entry] = readFileSync(filePath, 'utf-8');
+        }
+      } catch { /* skip unreadable files */ }
+    }
+
+    const meta = {};
+    const yamlRaw = files['module.yaml'] || '';
+    for (const line of yamlRaw.split('\n')) {
+      const match = line.match(/^(\w[\w-]*):\s*(.+)$/);
+      if (match) {
+        let val = match[2].trim();
+        if (val.startsWith('"') && val.endsWith('"')) val = val.slice(1, -1);
+        if (val === 'true') val = true;
+        else if (val === 'false') val = false;
+        else if (/^\d+$/.test(val)) val = parseInt(val, 10);
+        meta[match[1]] = val;
+      }
+    }
+
+    // Include list of static resources if resources/ directory exists
+    const resourcesDir = join(moduleDir, 'resources');
+    let resources = [];
+    try {
+      if (existsSync(resourcesDir)) {
+        resources = readdirSync(resourcesDir).filter(f => {
+          try { return statSync(join(resourcesDir, f)).isFile(); } catch { return false; }
+        });
+      }
+    } catch { /* no resources */ }
+
+    sendJson(res, 200, { slug, meta, files, resources });
+  } catch (readErr) {
+    sendJson(res, 500, { error: readErr.message });
+  }
+}
+
+const RESOURCE_CONTENT_TYPES = {
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.ogg': 'video/ogg',
+  '.html': 'text/html',
+  '.css': 'text/css',
+  '.js': 'text/javascript',
+  '.json': 'application/json',
+};
+const MAX_RESOURCE_SIZE = 10 * 1024 * 1024; // 10 MB
+
+/**
+ * GET /api/module/:slug/resources/:filename — serve static resource files.
+ */
+function handleApiModuleResource(res, slug, filename) {
+  if (filename.includes('..') || filename.includes('/') || filename.includes('\\')) {
+    sendJson(res, 400, { error: 'Invalid filename' });
+    return;
+  }
+
+  const modulesDir = resolve(__dirname, '..', '..', 'modules');
+  const filePath = join(modulesDir, slug, 'resources', filename);
+
+  if (!existsSync(filePath)) {
+    sendJson(res, 404, { error: 'Resource not found' });
+    return;
+  }
+
+  try {
+    const stat = statSync(filePath);
+    if (!stat.isFile() || stat.size > MAX_RESOURCE_SIZE) {
+      sendJson(res, 400, { error: 'Resource too large or not a file' });
+      return;
+    }
+
+    const ext = '.' + filename.split('.').pop().toLowerCase();
+    const contentType = RESOURCE_CONTENT_TYPES[ext] || 'application/octet-stream';
+
+    res.writeHead(200, {
+      'Content-Type': contentType,
+      'Content-Length': stat.size,
+      'Cache-Control': 'public, max-age=86400',
+    });
+    const stream = createReadStream(filePath);
+    stream.pipe(res);
+    stream.on('error', () => {
+      if (!res.headersSent) sendJson(res, 500, { error: 'Read error' });
+    });
+  } catch (err) {
+    sendJson(res, 500, { error: err.message });
+  }
+}
+
+// --- Session management handlers ---
+
+/**
+ * GET /api/sessions — list all sessions (metadata only).
+ */
+function handleApiSessionsList(res) {
+  try {
+    const sessions = listStoredSessions();
+    sendJson(res, 200, { sessions });
+  } catch (err) {
+    sendJson(res, 500, { error: err.message });
+  }
+}
+
+/**
+ * GET /api/sessions/:id — get full session with messages.
+ */
+function handleApiSessionGet(res, sessionId) {
+  try {
+    const session = getStoredSession(sessionId);
+    if (!session) {
+      sendJson(res, 404, { error: 'Session not found' });
+      return;
+    }
+    sendJson(res, 200, session);
+  } catch (err) {
+    sendJson(res, 500, { error: err.message });
+  }
+}
+
+/**
+ * PUT /api/sessions/:id — update session metadata.
+ */
+function handleApiSessionUpdate(req, res, sessionId) {
+  readBody(req, (err, body) => {
+    if (err) {
+      sendJson(res, 400, { error: 'Invalid request body' });
+      return;
+    }
+    try {
+      const updated = updateStoredMeta(sessionId, body);
+      if (!updated) {
+        sendJson(res, 404, { error: 'Session not found' });
+        return;
+      }
+      sendJson(res, 200, { ok: true, session: {
+        sessionId: updated.sessionId,
+        title: updated.title,
+        module: updated.module,
+        topic: updated.topic,
+        pinned: updated.pinned,
+      }});
+    } catch (err) {
+      sendJson(res, 500, { error: err.message });
+    }
+  });
+}
+
+/**
+ * DELETE /api/sessions/:id — delete a single session.
+ */
+function handleApiSessionDelete(res, sessionId, agentServer) {
+  try {
+    // Close SDK session if active
+    if (agentServer?.sessions) {
+      agentServer.sessions.closeSession(sessionId).catch(() => {});
+    }
+    const deleted = deleteStoredSession(sessionId);
+    sendJson(res, 200, { ok: true, deleted });
+  } catch (err) {
+    sendJson(res, 500, { error: err.message });
+  }
+}
+
+/**
+ * DELETE /api/sessions — purge all session history.
+ */
+function handleApiSessionsPurge(res, agentServer) {
+  try {
+    if (agentServer?.sessions) {
+      agentServer.sessions.closeAll().catch(() => {});
+    }
+    const count = purgeStoredSessions();
+    sendJson(res, 200, { ok: true, purged: count });
+  } catch (err) {
+    sendJson(res, 500, { error: err.message });
+  }
+}
+
+/**
+ * Settings file path: ~/.socrates/config.yaml
  */
 const SETTINGS_DIR = join(
   process.env.HOME || process.env.USERPROFILE || '/tmp',
-  '.claude-teach'
+  '.socrates'
 );
 const SETTINGS_FILE = join(SETTINGS_DIR, 'config.yaml');
 
@@ -625,6 +1540,7 @@ const DEFAULT_SETTINGS = {
   accent: 'blue',
   chatPosition: 'left',
   fontSize: 14,
+  model: 'claude-sonnet-4-6',
   animations: { confetti: true, transitions: true, diagrams: true },
 };
 
@@ -751,65 +1667,18 @@ function handleApiTemplates(res) {
 }
 
 /**
- * POST /api/visual — push a visual command to connected clients.
- * Used by the plugin to send canvas:* commands.
- * REJECTS canvas:quiz messages — those MUST go through POST /api/quiz.
- */
-function handleApiVisual(req, res, router) {
-  readBody(req, (err, body) => {
-    if (err) {
-      sendJson(res, 400, { error: 'Invalid request body' });
-      return;
-    }
-
-    const { valid, envelope, error } = parseEnvelope(body);
-    if (!valid) {
-      sendJson(res, 400, { error });
-      return;
-    }
-
-    // Reject quiz messages — they must use POST /api/quiz to capture answers
-    if (envelope.type === 'canvas:quiz') {
-      sendJson(res, 400, {
-        error: 'Quiz messages must use POST /api/quiz, not /api/visual. The /api/quiz endpoint sends the quiz AND waits for the browser answer in one request.',
-      });
-      return;
-    }
-
-    // Reject game messages — they must use POST /api/game to capture results
-    if (envelope.type === 'canvas:game') {
-      sendJson(res, 400, {
-        error: 'Game messages must use POST /api/game, not /api/visual. The /api/game endpoint sends the game AND waits for the browser result in one request.',
-      });
-      return;
-    }
-
-    // Check if we should render a template
-    if (envelope.payload && envelope.payload.template) {
-      const rendered = renderTemplate(envelope.payload.template, envelope.payload.data || {});
-      if (rendered) {
-        envelope.payload.renderedHtml = rendered;
-      }
-    }
-
-    router.routeVisualCommand(envelope);
-    sendJson(res, 200, { ok: true, tier: router.tierManager.getTier() });
-  });
-}
-
-/**
- * POST /api/quiz?timeout=30 — send a visual quiz AND wait for the browser answer.
- * Combines /api/visual + /api/events/wait into one atomic request so the caller
- * cannot accidentally skip the poll step.
+ * POST /api/canvas — unified endpoint for ALL visual commands.
+ *
+ * Accepts any canvas:* envelope. If the envelope contains an `await` field,
+ * the response is held until a matching event arrives or timeout expires.
+ *
+ * Without `await`: fire-and-forget (diagrams, dashboard, celebrations, HTML).
+ * With `await`: send visual + long-poll for matching event (quizzes, games, etc).
+ *
+ * Envelope format:
+ *   { v, type, payload, source, timestamp, await?: { event, timeout } }
  */
-function handleApiQuiz(req, res, router, url) {
-  const timeoutParam = parseInt(url.searchParams.get('timeout') || '30', 10);
-  const timeoutSec = isNaN(timeoutParam) ? 30 : timeoutParam;
-  const timeoutMs = Math.min(
-    Math.max(timeoutSec * 1000, 1000),
-    MAX_LONG_POLL_TIMEOUT_MS
-  );
-
+function handleApiCanvas(req, res, router, url) {
   readBody(req, (err, body) => {
     if (err) {
       sendJson(res, 400, { error: 'Invalid request body' });
@@ -822,7 +1691,6 @@ function handleApiQuiz(req, res, router, url) {
       return;
     }
 
-    // Render template if needed (same as /api/visual)
     if (envelope.payload && envelope.payload.template) {
       const rendered = renderTemplate(envelope.payload.template, envelope.payload.data || {});
       if (rendered) {
@@ -830,67 +1698,20 @@ function handleApiQuiz(req, res, router, url) {
       }
     }
 
-    // Step 1: Send the quiz to connected clients
     router.routeVisualCommand(envelope);
 
-    // Step 2: Wait for the browser answer
-    // Use res.on('close') — req 'close' fires when body is consumed (too early!)
-    let settled = false;
-    res.on('close', () => { settled = true; });
-
-    router.pollEventsAsync(timeoutMs).then((events) => {
-      if (settled) return;
-      settled = true;
-      sendJson(res, 200, {
-        ok: true,
-        tier: router.tierManager.getTier(),
-        events,
-        count: events.length,
-      });
-    });
-  });
-}
-
-/**
- * POST /api/game?timeout=120 — send a game to canvas AND wait for the game result.
- * Mirrors /api/quiz: combines /api/visual + /api/events/wait into one atomic request
- * so hooks cannot steal the event:game-result between the two calls.
- */
-function handleApiGame(req, res, router, url) {
-  const timeoutParam = parseInt(url.searchParams.get('timeout') || '120', 10);
-  const timeoutSec = isNaN(timeoutParam) ? 120 : timeoutParam;
-  const timeoutMs = Math.min(
-    Math.max(timeoutSec * 1000, 1000),
-    MAX_LONG_POLL_TIMEOUT_MS
-  );
-
-  readBody(req, (err, body) => {
-    if (err) {
-      sendJson(res, 400, { error: 'Invalid request body' });
-      return;
-    }
-
-    const { valid, envelope, error } = parseEnvelope(body);
-    if (!valid) {
-      sendJson(res, 400, { error });
+    const awaitSpec = envelope.await;
+    if (!awaitSpec || !awaitSpec.event) {
+      sendJson(res, 200, { ok: true, tier: router.tierManager.getTier() });
       return;
     }
 
-    // Render template if needed (same as /api/visual)
-    if (envelope.payload && envelope.payload.template) {
-      const rendered = renderTemplate(envelope.payload.template, envelope.payload.data || {});
-      if (rendered) {
-        envelope.payload.renderedHtml = rendered;
-      }
-    }
-
-    // Step 1: Send the game to connected clients
-    router.routeVisualCommand(envelope);
+    const timeoutSec = typeof awaitSpec.timeout === 'number' ? awaitSpec.timeout : 30;
+    const timeoutMs = Math.min(
+      Math.max(timeoutSec * 1000, 1000),
+      MAX_LONG_POLL_TIMEOUT_MS
+    );
 
-    // Step 2: Wait for the game result
-    // IMPORTANT: Use res.on('close'), NOT req.on('close').
-    // req 'close' fires when the request body is consumed (immediately after parsing),
-    // but res 'close' fires when the underlying connection is actually closed.
     let settled = false;
     res.on('close', () => { settled = true; });
 
@@ -1031,6 +1852,126 @@ function handleApiTerminalExec(req, res, router) {
   });
 }
 
+/**
+ * POST /api/pty/create — create a new PTY terminal session.
+ */
+function handleApiPtyCreate(req, res) {
+  readBody(req, async (err, body) => {
+    if (err) {
+      sendJson(res, 400, { error: 'Invalid request body' });
+      return;
+    }
+    try {
+      const { sessionId, cwd } = await createPtySession({
+        cwd: body?.cwd,
+        cols: body?.cols,
+        rows: body?.rows,
+        shell: body?.shell,
+        env: body?.env,
+      });
+      sendJson(res, 200, { sessionId, cwd });
+    } catch (e) {
+      sendJson(res, 500, { error: e.message });
+    }
+  });
+}
+
+/**
+ * POST /api/playground/exec — execute a code snippet and return output.
+ * Supports JavaScript (Node), Python, and Bash.
+ */
+function handleApiPlaygroundExec(req, res) {
+  readBody(req, (err, body) => {
+    if (err) {
+      sendJson(res, 400, { error: 'Invalid request body' });
+      return;
+    }
+
+    const { code, language } = body || {};
+    if (typeof code !== 'string') {
+      sendJson(res, 400, { error: 'Missing "code" string in request body' });
+      return;
+    }
+
+    const lang = (language || 'javascript').toLowerCase();
+    let cmd;
+    switch (lang) {
+      case 'javascript':
+      case 'js':
+        cmd = `node -e ${JSON.stringify(code)}`;
+        break;
+      case 'python':
+      case 'py':
+        cmd = `python3 -c ${JSON.stringify(code)}`;
+        break;
+      case 'bash':
+      case 'sh':
+      case 'shell':
+        cmd = `sh -c ${JSON.stringify(code)}`;
+        break;
+      case 'typescript':
+      case 'ts':
+        cmd = `node -e ${JSON.stringify(code)}`;
+        break;
+      default:
+        sendJson(res, 400, { error: `Unsupported language: ${lang}` });
+        return;
+    }
+
+    exec(cmd, {
+      timeout: PLAYGROUND_EXEC_TIMEOUT_MS,
+      maxBuffer: PLAYGROUND_MAX_OUTPUT_BYTES,
+      env: { ...process.env, NO_COLOR: '1' },
+    }, (error, stdout, stderr) => {
+      let output = '';
+      if (stdout) output += stdout;
+      if (stderr) output += (output ? '\n' : '') + stderr;
+      if (error && !stdout && !stderr) {
+        output = error.killed
+          ? `Execution timed out after ${PLAYGROUND_EXEC_TIMEOUT_MS / 1000}s`
+          : error.message;
+      }
+      const exitCode = error ? (error.code ?? 1) : 0;
+      sendJson(res, 200, { output, exitCode, language: lang });
+    });
+  });
+}
+
+/**
+ * POST /api/workshop/setup — set up a workshop scenario.
+ * Creates a PTY session, writes files, and optionally runs setup commands.
+ */
+function handleApiWorkshopSetup(req, res, router) {
+  readBody(req, async (err, body) => {
+    if (err) {
+      sendJson(res, 400, { error: 'Invalid request body' });
+      return;
+    }
+
+    try {
+      const { cwd, files, setup, cols, rows } = body || {};
+
+      const { sessionId, cwd: sessionCwd } = await createPtySession({
+        cwd,
+        cols: cols || 120,
+        rows: rows || 30,
+      });
+
+      if (files && Array.isArray(files)) {
+        await writeSessionFiles(sessionId, files);
+      }
+
+      if (setup && Array.isArray(setup)) {
+        runSetupCommands(sessionId, setup);
+      }
+
+      sendJson(res, 200, { sessionId, cwd: sessionCwd });
+    } catch (e) {
+      sendJson(res, 500, { error: e.message });
+    }
+  });
+}
+
 // --- Helpers ---
 
 function readBody(req, callback) {
@@ -1063,6 +2004,199 @@ function ensureDir(dirPath) {
   }
 }
 
+/**
+ * Enrich progress modules with metadata (title, description, difficulty)
+ * from the module catalog. Modules in progress get their metadata merged in;
+ * catalog modules not yet started are included as status: 'available'.
+ * @param {object} progressModules - { [slug]: { status, xp_earned, ... } }
+ * @param {Map} moduleMap - from buildModuleMap()
+ * @returns {object} enriched modules object keyed by slug
+ */
+export function enrichModulesWithMetadata(progressModules, moduleMap) {
+  const enriched = {};
+
+  for (const [slug, mod] of Object.entries(progressModules || {})) {
+    const meta = moduleMap.get(slug);
+    enriched[slug] = {
+      ...mod,
+      title: meta?.title || slug,
+      description: meta?.description || '',
+      difficulty: meta?.difficulty || 'beginner',
+    };
+  }
+
+  for (const [slug, meta] of moduleMap) {
+    if (!enriched[slug]) {
+      enriched[slug] = {
+        status: 'available',
+        title: meta.title || slug,
+        description: meta.description || '',
+        difficulty: meta.difficulty || 'beginner',
+      };
+    }
+  }
+
+  return enriched;
+}
+
+/**
+ * Parse a .socrates-progress.yaml file without js-yaml.
+ * Handles the 2-level nested structure: top-level sections (user, modules, journey)
+ * with flat key-value children, plus modules having per-slug sub-objects.
+ */
+export function parseProgressYaml(raw) {
+  const result = { user: { xp: 0, belt: 'white', modules_completed: 0 }, modules: {}, journey: { active: null, progress: {} } };
+  if (!raw) return result;
+
+  const lines = raw.split('\n');
+  let section = null;     // 'user', 'modules', 'journey'
+  let subKey = null;       // module slug or journey progress key
+
+  for (const line of lines) {
+    if (line.startsWith('#') || line.trim() === '') continue;
+
+    // Top-level section (no indent)
+    const sectionMatch = line.match(/^(\w[\w_-]*):\s*(.*)$/);
+    if (sectionMatch && !line.startsWith(' ') && !line.startsWith('\t')) {
+      section = sectionMatch[1];
+      subKey = null;
+      const val = sectionMatch[2].trim();
+      if (val && section !== 'user' && section !== 'modules' && section !== 'journey' && section !== 'achievements') {
+        result[section] = parseYamlValue(val);
+      }
+      continue;
+    }
+
+    // 2-space or 4-space indented content
+    const indent2 = line.match(/^  (\w[\w_-]*):\s*(.*)$/);
+    if (indent2) {
+      const key = indent2[1];
+      const val = indent2[2].trim();
+
+      if (section === 'user') {
+        result.user[key] = parseYamlValue(val);
+        subKey = null;
+      } else if (section === 'modules') {
+        if (!val) {
+          subKey = key;
+          result.modules[key] = result.modules[key] || {};
+        } else {
+          subKey = key;
+          result.modules[key] = result.modules[key] || {};
+        }
+      } else if (section === 'journey') {
+        if (key === 'active') {
+          result.journey.active = val === 'null' || val === '' ? null : parseYamlValue(val);
+        } else if (key === 'progress' && !val) {
+          subKey = 'progress';
+        }
+      }
+      continue;
+    }
+
+    // 4-space indented (module fields or journey progress fields)
+    const indent4 = line.match(/^    (\w[\w_-]*):\s*(.*)$/);
+    if (indent4 && subKey) {
+      const key = indent4[1];
+      const val = indent4[2].trim();
+      if (section === 'modules' && result.modules[subKey]) {
+        result.modules[subKey][key] = parseYamlValue(val);
+      } else if (section === 'journey' && subKey === 'progress') {
+        result.journey.progress[key] = parseYamlValue(val);
+      }
+    }
+  }
+
+  return result;
+}
+
+function parseYamlValue(val) {
+  if (val === 'null' || val === '~' || val === '') return null;
+  if (val === 'true') return true;
+  if (val === 'false') return false;
+  if (/^-?\d+$/.test(val)) return parseInt(val, 10);
+  if (/^-?\d+\.\d+$/.test(val)) return parseFloat(val);
+  if (val.startsWith("'") && val.endsWith("'")) return val.slice(1, -1);
+  if (val.startsWith('"') && val.endsWith('"')) return val.slice(1, -1);
+  return val;
+}
+
+/**
+ * Serialize a progress object back to YAML (simple 2-level nesting).
+ */
+export function serializeProgressYaml(progress) {
+  const lines = [];
+
+  if (progress.user) {
+    lines.push('user:');
+    for (const [k, v] of Object.entries(progress.user)) {
+      lines.push(`  ${k}: ${formatYamlValue(v)}`);
+    }
+  }
+
+  if (progress.modules && Object.keys(progress.modules).length > 0) {
+    lines.push('modules:');
+    for (const [slug, mod] of Object.entries(progress.modules)) {
+      lines.push(`  ${slug}:`);
+      for (const [k, v] of Object.entries(mod)) {
+        lines.push(`    ${k}: ${formatYamlValue(v)}`);
+      }
+    }
+  } else {
+    lines.push('modules: {}');
+  }
+
+  if (progress.journey) {
+    lines.push('journey:');
+    lines.push(`  active: ${formatYamlValue(progress.journey.active)}`);
+    if (progress.journey.progress && Object.keys(progress.journey.progress).length > 0) {
+      lines.push('  progress:');
+      for (const [k, v] of Object.entries(progress.journey.progress)) {
+        lines.push(`    ${k}: ${formatYamlValue(v)}`);
+      }
+    } else {
+      lines.push('  progress: {}');
+    }
+  }
+
+  return lines.join('\n') + '\n';
+}
+
+function formatYamlValue(v) {
+  if (v === null || v === undefined) return 'null';
+  if (typeof v === 'boolean') return v ? 'true' : 'false';
+  if (typeof v === 'number') return String(v);
+  if (typeof v === 'string' && /[:#{}[\],&*?|>!%@`]/.test(v)) return `"${v}"`;
+  return String(v);
+}
+
+/**
+ * Create a progressProvider that reads/writes .socrates-progress.yaml directly.
+ * Used in standalone bridge mode when no CLI-injected provider is available.
+ */
+export function createFileProgressProvider(filePath) {
+  return {
+    getProgress() {
+      try {
+        if (!existsSync(filePath)) {
+          return { user: { xp: 0, belt: 'white', modules_completed: 0 }, modules: {}, journey: { active: null, progress: {} } };
+        }
+        const raw = readFileSync(filePath, 'utf-8');
+        return parseProgressYaml(raw);
+      } catch {
+        return { user: { xp: 0, belt: 'white', modules_completed: 0 }, modules: {}, journey: { active: null, progress: {} } };
+      }
+    },
+    saveProgress(progress) {
+      try {
+        writeFileSync(filePath, serializeProgressYaml(progress), 'utf-8');
+      } catch (err) {
+        console.error('[bridge] Failed to save progress:', err.message);
+      }
+    },
+  };
+}
+
 // --- Standalone execution ---
 if (process.argv[1] && process.argv[1].includes('bridge/src/server.js')) {
   // Prevent unhandled errors from crashing the server
@@ -1075,5 +2209,7 @@ if (process.argv[1] && process.argv[1].includes('bridge/src/server.js')) {
 
   const port = parseInt(process.env.PORT || process.argv[2] || DEFAULT_PORT, 10);
   const pluginDir = resolve(__dirname, '..', '..', 'plugin');
-  startServer({ port, pluginDir });
+  const progressFile = resolve(process.cwd(), '.socrates-progress.yaml');
+  const progressProvider = createFileProgressProvider(progressFile);
+  startServer({ port, pluginDir, progressProvider });
 }