@dfosco/storyboard-core 4.2.0-beta.2 → 4.2.0-beta.21

package/src/canvas/server.js

@@ -17,9 +17,11 @@
  *   GET    /page-order — read page order for a folder
  *   PUT    /update-folder-meta — update folder .meta.json title
  *   POST   /widget   — append a widget_added event
+ *   PATCH  /widget   — update a single widget's props/position
  *   DELETE /widget   — append a widget_removed event
  *   POST   /connector — append a connector_added event
  *   DELETE /connector — append a connector_removed event
+ *   POST   /batch    — execute multiple operations in one request (refs, single HMR push)
  *   POST   /create   — create a new .canvas.jsonl file
  *   GET    /stories  — list all .story.{jsx,tsx} files with exports
  *   POST   /create-story — scaffold a new .story.{jsx,tsx} file
@@ -27,7 +29,9 @@
  *   POST   /github/embed — fetch GitHub issue/discussion/PR/comment metadata via gh
  *   POST   /image    — upload a pasted image to src/canvas/images/
  *   GET    /images/* — serve an image file from src/canvas/images/
- *   POST   /image/toggle-private — toggle _prefix on image filename
+ *   POST   /image/toggle-private — toggle ~prefix on image filename
+ *   GET    /terminal-buffer/:id — read private terminal buffer (with ?length=N)
+ *   GET    /terminal-snapshot/:id — read public terminal snapshot
  */
 
 import fs from 'node:fs'
@@ -42,7 +46,43 @@ import {
   isGhCliAvailable,
   isGitHubEmbedUrl,
 } from './githubEmbeds.js'
-import { stampBounds, stampBoundsAll } from './collision.js'
+import { stampBounds, stampBoundsAll, resolvePosition, getWidgetBounds } from './collision.js'
+import { markCanvasWrite, unmarkCanvasWrite } from './writeGuard.js'
+import { devLog } from '../logger/devLogger.js'
+import widgetsConfig from '../../widgets.config.json' with { type: 'json' }
+
+/**
+ * Read the prompt widget's execution config from widgets.config.json.
+ * Returns { default, agents } where each agent has a command template.
+ */
+function getPromptExecution() {
+  return widgetsConfig?.widgets?.prompt?.execution || null
+}
+
+/**
+ * Build the CLI command for a prompt spawn.
+ * Reads the prompt widget's execution.agents config and interpolates ${prompt}.
+ */
+function buildPromptCmd({ prompt, envFile, agentId }) {
+  const execution = getPromptExecution()
+
+  if (!execution) {
+    // Bare fallback — no execution config found
+    const escaped = prompt.replace(/"/g, '\\"')
+    return `source ${envFile} && copilot -p "${escaped}" --allow-all`
+  }
+
+  const id = agentId || execution.default
+  const agent = execution.agents?.[id]
+
+  if (!agent?.command) {
+    return null // This agent doesn't have a prompt command
+  }
+
+  const escaped = prompt.replace(/"/g, '\\"')
+  const cmd = agent.command.replace('${prompt}', escaped)
+  return `source ${envFile} && ${cmd}`
+}
 
 /**
  * Scan src/canvas/ for directories containing .meta.json files.
@@ -209,14 +249,261 @@ function generateWidgetId(type) {
  * Create the canvas API route handler.
  */
 export function createCanvasHandler(ctx) {
-  const { root, sendJson } = ctx
+  const { root, sendJson, hotPool } = ctx
+
+  /**
+   * Compute a target position relative to a reference widget.
+   * @param {object} refWidget — widget to position near (must have position + type/props)
+   * @param {string} direction — 'right' | 'left' | 'above' | 'below'
+   * @param {string} newType — type of the widget being created (for size defaults)
+   * @param {object} newProps — props of the widget being created
+   * @param {number} gap — spacing between widgets (default 40)
+   * @returns {{ x: number, y: number }}
+   */
+  function computeNearPosition(refWidget, direction = 'right', newType = 'sticky-note', newProps = {}, gap = 40) {
+    const refBounds = getWidgetBounds(refWidget)
+    const newDefaults = getWidgetBounds({ type: newType, props: newProps, position: { x: 0, y: 0 } })
+    switch (direction) {
+      case 'left':
+        return { x: refBounds.x - newDefaults.width - gap, y: refBounds.y }
+      case 'above':
+        return { x: refBounds.x, y: refBounds.y - newDefaults.height - gap }
+      case 'below':
+        return { x: refBounds.x, y: refBounds.y + refBounds.height + gap }
+      case 'right':
+      default:
+        return { x: refBounds.x + refBounds.width + gap, y: refBounds.y }
+    }
+  }
+
+  /**
+   * Compute a smart default position when no --near or explicit x,y is given.
+   * Priority chain:
+   *   1. Active agent/terminal (source widget ID from request)
+   *   2. User-selected widget (from .selectedwidgets.json, same canvas)
+   *   3. Viewport center (from .selectedwidgets.json)
+   *   4. Last widget on canvas
+   *   5. Origin (0, 0) — empty canvas, no viewport
+   *
+   * @param {object[]} canvasWidgets — current widgets on the canvas
+   * @param {string} type — widget type being created
+   * @param {object} props — widget props
+   * @param {string} projectRoot — project root directory
+   * @param {string|null} canvasName — canvas ID for matching selectedwidgets context
+   * @param {string|null} sourceWidgetId — caller's widget ID (agent/terminal creating this widget)
+   */
+  async function computeAutoPosition(canvasWidgets, type, props, projectRoot, canvasName, sourceWidgetId) {
+    const widgetMap = new Map((canvasWidgets || []).map(w => [w.id, w]))
+
+    // 1. Place near the source agent/terminal widget
+    if (sourceWidgetId && widgetMap.has(sourceWidgetId)) {
+      return computeNearPosition(widgetMap.get(sourceWidgetId), 'right', type, props)
+    }
+
+    // 2–3. Read .selectedwidgets.json for selection + viewport context
+    try {
+      const { readSelectedWidgets } = await import('./selectedWidgets.js')
+      const sw = readSelectedWidgets(projectRoot)
+      if (sw && sw.canvasId === canvasName) {
+        // 2. Place near the selected widget
+        if (sw.selectedWidgetIds?.length > 0) {
+          const selectedId = sw.selectedWidgetIds[0]
+          if (widgetMap.has(selectedId)) {
+            return computeNearPosition(widgetMap.get(selectedId), 'right', type, props)
+          }
+        }
+
+        // 3. Place at viewport center
+        const vp = sw.viewport
+        if (vp && vp.centerX != null && vp.centerY != null) {
+          return { x: Math.round(vp.centerX / 24) * 24, y: Math.round(vp.centerY / 24) * 24 }
+        }
+      }
+    } catch { /* selectedWidgets bridge may not be initialized */ }
+
+    // 4. Place near the last widget on the canvas
+    if (canvasWidgets && canvasWidgets.length > 0) {
+      const lastWidget = canvasWidgets[canvasWidgets.length - 1]
+      return computeNearPosition(lastWidget, 'right', type, props)
+    }
+
+    // 5. Truly empty canvas, no viewport
+    return { x: 0, y: 0 }
+  }
+
+  /**
+   * Update terminal configs when connectors change.
+   * Finds all terminal widgets in the canvas, computes their connected widget IDs
+   * from the current connector list, and updates their config files.
+   */
+  async function updateTerminalConnectionsForCanvas(root, canvasName, canvasData, connectors) {
+    try {
+      const { updateTerminalConnections, initTerminalConfig } = await import('./terminal-config.js')
+      const { execSync } = await import('node:child_process')
+      initTerminalConfig(root)
+
+      let branch = 'unknown'
+      try {
+        branch = execSync('git branch --show-current', { encoding: 'utf8', cwd: root }).trim()
+      } catch {}
+
+      const widgets = canvasData.widgets || []
+      const widgetMap = new Map(widgets.map(w => [w.id, w]))
+      const terminalWidgets = widgets.filter((w) => w.type === 'terminal' || w.type === 'agent' || w.type === 'prompt')
+
+      for (const tw of terminalWidgets) {
+        const connectedIds = new Set()
+        const messagingPeers = []
+        for (const conn of connectors) {
+          let peerId = null
+          let direction = null
+          if (conn.start?.widgetId === tw.id) {
+            peerId = conn.end?.widgetId
+            direction = 'outgoing' // tw → peer
+          }
+          if (conn.end?.widgetId === tw.id) {
+            peerId = conn.start?.widgetId
+            direction = 'incoming' // peer → tw
+          }
+          if (peerId) {
+            connectedIds.add(peerId)
+            const mode = conn.meta?.messagingMode || 'none'
+            if (mode !== 'none') {
+              const peerWidget = widgetMap.get(peerId)
+              if (peerWidget && (peerWidget.type === 'terminal' || peerWidget.type === 'agent')) {
+                const canSend = mode === 'two-way' || (mode === 'one-way' && direction === 'outgoing')
+                const canReceive = mode === 'two-way' || (mode === 'one-way' && direction === 'incoming')
+                messagingPeers.push({
+                  widgetId: peerId,
+                  displayName: peerWidget.props?.prettyName || peerId,
+                  configPath: `.storyboard/terminals/${peerId}.json`,
+                  type: peerWidget.type,
+                  canSend,
+                  canReceive,
+                  mode,
+                })
+              }
+            }
+          }
+        }
+        connectedIds.delete(undefined)
+        connectedIds.delete(null)
+
+        // Resolve full widget objects for connected widgets
+        const connectedWidgets = [...connectedIds]
+          .map(id => widgetMap.get(id))
+          .filter(Boolean)
+          .map(w => ({ id: w.id, type: w.type, props: w.props, position: w.position }))
+
+        // Build messaging section if there are messaging-enabled peers
+        const messaging = messagingPeers.length > 0 ? { peers: messagingPeers } : null
+
+        updateTerminalConnections({
+          branch,
+          canvasId: canvasName,
+          widgetId: tw.id,
+          connectedWidgets,
+          widgetProps: tw.props || null,
+          messaging,
+        })
+      }
+    } catch (err) {
+      devLog().logEvent('warn', 'Failed to update terminal connections', { error: err.message })
+    }
+  }
 
   // Append an event to an existing canvas file.
-  // The data plugin already skips .canvas.jsonl `change` events to avoid
-  // a save → reload → lost-editing-state feedback loop, so we just write
-  // directly without touching the watcher.
+  // Marks the file in the write guard so the data plugin's watcher handler
+  // skips sending a duplicate HMR event (the server pushes its own via
+  // pushCanvasUpdate after the write).
   function appendEvent(filePath, event) {
+    markCanvasWrite(filePath)
     appendEventRaw(filePath, event)
+    // Unmark after enough time for the watcher to fire and be suppressed.
+    // macOS FSEvents latency is typically 100-500ms; 1s covers edge cases.
+    setTimeout(() => unmarkCanvasWrite(filePath), 1000)
+  }
+
+  /**
+   * Prepare a terminal/agent widget: auto-assign displayName and pre-reserve identity.
+   * Shared by POST /widget and batch create-widget.
+   * @param {{ type: string, props: Object }} opts
+   * @param {string} widgetId
+   * @param {string} canvasName
+   * @param {import('node:http').IncomingMessage} [req]
+   */
+  async function prepareTerminalWidget({ type, props, widgetId, canvasName, req }) {
+    if (type !== 'terminal' && type !== 'agent') return
+
+    if (!props.prettyName) {
+      try {
+        const { generateFriendlyName } = await import('./terminal-registry.js')
+        props.prettyName = generateFriendlyName()
+      } catch { /* registry not initialized yet */ }
+    }
+
+    try {
+      const { preReserveTerminalIdentity, initTerminalConfig } = await import('./terminal-config.js')
+      initTerminalConfig(root)
+      let branch = 'unknown'
+      try {
+        const { execSync } = await import('node:child_process')
+        branch = execSync('git branch --show-current', { encoding: 'utf8', cwd: root }).trim()
+      } catch {}
+      const serverUrl = `http://localhost:${req?.socket?.localPort || 1234}`
+      preReserveTerminalIdentity({
+        widgetId,
+        preDisplayName: props.prettyName || null,
+        canvasId: canvasName,
+        branch,
+        serverUrl,
+      })
+    } catch { /* best effort */ }
+  }
+
+  /**
+   * Resolve which hot pool to use for a widget type + props.
+   * Agent widgets use their agentId as pool ID; terminals use 'terminal'.
+   */
+  function resolvePoolId(type, props) {
+    if (type === 'agent' && props?.agentId) return props.agentId
+    return 'terminal'
+  }
+
+  /**
+   * Try to acquire a warm session from the hot pool.
+   * @param {Object|null} hotPool — HotPoolManager instance
+   * @param {string} poolId — pool to acquire from
+   * @param {string} [mode] — 'auto' (default), 'hot', or 'cold'
+   * @returns {Object|null} acquired session or null
+   */
+  function acquireFromPool(hotPool, poolId, mode) {
+    if (!hotPool || mode === 'cold') return null
+    const effectiveMode = mode || 'auto'
+    if (effectiveMode === 'cold') return null
+    if (!hotPool.has(poolId)) return null
+    return hotPool.acquire(poolId) || null
+  }
+
+  /**
+   * Push live canvas update to connected clients via Vite HMR.
+   * Reads the full materialized state from disk and sends it as a custom
+   * event so useCanvas can update in-place without a page refresh.
+   */
+  function pushCanvasUpdate(canvasName, filePath, viteWs) {
+    if (!viteWs) return
+    try {
+      const data = readCanvas(filePath)
+      viteWs.send({
+        type: 'custom',
+        event: 'storyboard:canvas-file-changed',
+        data: { canvasId: canvasName, name: canvasName, metadata: data },
+      })
+
+      // Refresh terminal config files on every canvas change so agents
+      // always see up-to-date connectedWidgets and widget props.
+      updateTerminalConnectionsForCanvas(root, canvasName, data, data.connectors || [])
+    } catch { /* best effort — watcher will catch it eventually */ }
   }
 
   // Write a new JSONL file with a single creation event.
@@ -226,7 +513,7 @@ export function createCanvasHandler(ctx) {
     fs.writeFileSync(filePath, serializeEvent(event) + '\n', 'utf-8')
   }
 
-  return async (req, res, { body, path: routePath, method }) => {
+  return async (req, res, { body, path: routePath, method, __viteWs }) => {
     // GET /folders — list available canvas folders
     if (routePath === '/folders' && method === 'GET') {
       const canvasDir = path.join(root, 'src', 'canvas')
@@ -336,7 +623,7 @@ export function createCanvasHandler(ctx) {
 
     // PUT /update — append update events to the canvas stream
     if (routePath === '/update' && method === 'PUT') {
-      const { name, widgets, sources, settings } = body
+      const { name, widgets, sources, settings, connectors } = body
 
       if (!name) {
         sendJson(res, 400, { error: 'Canvas name is required' })
@@ -353,6 +640,21 @@ export function createCanvasHandler(ctx) {
         const ts = new Date().toISOString()
 
         if (widgets) {
+          // Guard against accidental canvas wipes: if the incoming widget count
+          // is much smaller than the current canvas, reject unless explicitly confirmed.
+          // This protects against agents/scripts that accidentally send a partial widget
+          // array to the widgets_replaced endpoint (which replaces ALL widgets).
+          const current = readCanvas(filePath)
+          const currentCount = (current.widgets || []).length
+          if (currentCount > 1 && widgets.length < currentCount * 0.5 && body.replaceAll !== true) {
+            sendJson(res, 400, {
+              error: `Refusing to replace ${currentCount} widgets with ${widgets.length}. `
+                + `This would delete ${currentCount - widgets.length} widgets. `
+                + `Use PATCH /_storyboard/canvas/widget to update individual widgets, `
+                + `or pass "replaceAll": true to confirm full replacement.`,
+            })
+            return
+          }
           const stamped = stampBoundsAll(widgets)
           appendEvent(filePath, { event: 'widgets_replaced', timestamp: ts, widgets: stamped })
         }
@@ -361,6 +663,10 @@ export function createCanvasHandler(ctx) {
           appendEvent(filePath, { event: 'source_updated', timestamp: ts, sources })
         }
 
+        if (connectors) {
+          appendEvent(filePath, { event: 'connectors_replaced', timestamp: ts, connectors })
+        }
+
         if (settings) {
           const filtered = {}
           for (const [key, value] of Object.entries(settings)) {
@@ -374,6 +680,7 @@ export function createCanvasHandler(ctx) {
         }
 
         sendJson(res, 200, { success: true, name })
+        pushCanvasUpdate(name, filePath, __viteWs)
       } catch (err) {
         sendJson(res, 500, { error: `Failed to update canvas: ${err.message}` })
       }
@@ -382,7 +689,14 @@ export function createCanvasHandler(ctx) {
 
     // POST /widget — append a widget_added event
     if (routePath === '/widget' && method === 'POST') {
-      const { name, type, props = {}, position = { x: 0, y: 0 } } = body
+      const { name, type, props = {}, pool, near, direction, resolve, source } = body
+      let position = body.position || { x: 0, y: 0 }
+
+      // Detect whether the caller provided an explicit position.
+      // `near === false` is the explicit opt-out ("put it exactly here").
+      const hasExplicitPosition = body.position && (body.position.x !== 0 || body.position.y !== 0)
+      const hasNearOptOut = near === false
+      const needsAutoPosition = !near && !hasExplicitPosition && !hasNearOptOut
 
       if (!name) {
         sendJson(res, 400, { error: 'Canvas name is required' })
@@ -400,14 +714,51 @@ export function createCanvasHandler(ctx) {
       }
 
       try {
+        // Always read canvas when we need near, resolve, or auto-positioning
+        const needsCanvasRead = near || resolve || needsAutoPosition
+        let canvasWidgets = null
+        let canvasData = null
+        if (needsCanvasRead) {
+          canvasData = readCanvas(filePath)
+          canvasWidgets = canvasData.widgets || []
+        }
+
+        if (near) {
+          const refWidget = canvasWidgets.find((w) => w.id === near)
+          if (!refWidget) {
+            sendJson(res, 400, { error: `Widget "${near}" not found (--near)` })
+            return
+          }
+          position = computeNearPosition(refWidget, direction || 'right', type, props)
+        }
+
+        // Auto-position: no --near, no explicit x,y → smart default
+        if (needsAutoPosition && !near) {
+          position = await computeAutoPosition(canvasWidgets, type, props, root, name, source || null)
+        }
+
+        if (near || resolve || needsAutoPosition) {
+          const resolved = resolvePosition({
+            x: position.x, y: position.y, type, props,
+            widgets: canvasWidgets,
+            gridSize: (canvasData && canvasData.gridSize) || 24,
+          })
+          position = { x: resolved.x, y: resolved.y }
+        }
+
         const widgetId = generateWidgetId(type)
 
-        // Auto-assign a pretty name for terminal widgets
-        if (type === 'terminal' && !props.prettyName) {
-          try {
-            const { generateFriendlyName } = await import('./terminal-registry.js')
-            props.prettyName = generateFriendlyName()
-          } catch { /* registry not initialized yet — will get a name on session connect */ }
+        await prepareTerminalWidget({ type, props, widgetId, canvasName: name, req })
+
+        // Hot pool acquisition for terminal/agent widgets
+        let hotSession = null
+        if ((type === 'terminal' || type === 'agent') && pool !== 'cold') {
+          const poolId = resolvePoolId(type, props)
+          hotSession = acquireFromPool(hotPool, poolId, pool)
+          if (!hotSession && pool === 'hot') {
+            sendJson(res, 409, { error: `No warm sessions available in pool "${poolId}"` })
+            return
+          }
         }
 
         const widget = stampBounds({ id: widgetId, type, position, props })
@@ -418,7 +769,10 @@ export function createCanvasHandler(ctx) {
           widget,
         })
 
-        sendJson(res, 201, { success: true, widget })
+        const response = { success: true, widget }
+        if (hotSession) response.hotSession = { id: hotSession.id, tmuxName: hotSession.tmuxName || null }
+        sendJson(res, 201, response)
+        pushCanvasUpdate(name, filePath, __viteWs)
       } catch (err) {
         sendJson(res, 500, { error: `Failed to add widget: ${err.message}` })
       }
@@ -456,22 +810,86 @@ export function createCanvasHandler(ctx) {
         })
 
         // Orphan terminal session when a terminal widget is deleted (not killed)
-        if (widget.type === 'terminal') {
+        if (widget.type === 'terminal' || widget.type === 'agent') {
           try {
             const { orphanTerminalSession } = await import('./terminal-server.js')
             orphanTerminalSession(widgetId)
           } catch (err) {
-            console.warn(`[storyboard] Failed to orphan terminal session for ${widgetId}:`, err.message)
+            devLog().logEvent('warn', `Failed to orphan terminal session for ${widgetId}`, { widgetId, error: err.message })
           }
         }
 
         sendJson(res, 200, { success: true, removed: 1 })
+        pushCanvasUpdate(name, filePath, __viteWs)
       } catch (err) {
         sendJson(res, 500, { error: `Failed to remove widget: ${err.message}` })
       }
       return
     }
 
+    // PATCH /widget — update a single widget's props
+    if (routePath === '/widget' && method === 'PATCH') {
+      const { name, widgetId, props, position } = body
+
+      if (!name || !widgetId) {
+        sendJson(res, 400, { error: 'Canvas name and widgetId are required' })
+        return
+      }
+      if (!props && !position) {
+        sendJson(res, 400, { error: 'At least one of props or position is required' })
+        return
+      }
+
+      const filePath = findCanvasPath(root, name)
+      if (!filePath) {
+        sendJson(res, 404, { error: `Canvas "${name}" not found` })
+        return
+      }
+
+      try {
+        const data = readCanvas(filePath)
+        const widget = (data.widgets || []).find((w) => w.id === widgetId)
+        if (!widget) {
+          sendJson(res, 404, { error: `Widget "${widgetId}" not found in canvas "${name}"` })
+          return
+        }
+
+        const ts = new Date().toISOString()
+
+        if (props) {
+          appendEvent(filePath, {
+            event: 'widget_updated',
+            timestamp: ts,
+            widgetId,
+            props,
+          })
+        }
+
+        if (position) {
+          // Merge with existing position so partial updates (only --x or --y) are safe
+          const mergedPosition = { ...widget.position, ...position }
+          appendEvent(filePath, {
+            event: 'widget_moved',
+            timestamp: ts,
+            widgetId,
+            position: mergedPosition,
+          })
+        }
+
+        // Return the merged widget for convenience
+        const merged = {
+          ...widget,
+          props: { ...widget.props, ...(props || {}) },
+          position: position ? { ...widget.position, ...position } : widget.position,
+        }
+        sendJson(res, 200, { success: true, widget: merged })
+        pushCanvasUpdate(name, filePath, __viteWs)
+      } catch (err) {
+        sendJson(res, 500, { error: `Failed to update widget: ${err.message}` })
+      }
+      return
+    }
+
     // POST /connector — append a connector_added event
     if (routePath === '/connector' && method === 'POST') {
       const { name, startWidgetId, startAnchor, endWidgetId, endAnchor, connectorType = 'default' } = body
@@ -529,12 +947,115 @@ export function createCanvasHandler(ctx) {
         })
 
         sendJson(res, 201, { success: true, connector })
+        pushCanvasUpdate(name, filePath, __viteWs)
       } catch (err) {
         sendJson(res, 500, { error: `Failed to add connector: ${err.message}` })
       }
       return
     }
 
+    // PATCH /connector — update connector anchors and/or meta
+    if (routePath === '/connector' && method === 'PATCH') {
+      const { name, connectorId, meta, startAnchor, endAnchor } = body
+
+      if (!name || !connectorId) {
+        sendJson(res, 400, { error: 'Canvas name and connectorId are required' })
+        return
+      }
+
+      const filePath = findCanvasPath(root, name)
+      if (!filePath) {
+        sendJson(res, 404, { error: `Canvas "${name}" not found` })
+        return
+      }
+
+      try {
+        const data = readCanvas(filePath)
+        const connector = (data.connectors || []).find((c) => c.id === connectorId)
+        if (!connector) {
+          sendJson(res, 404, { error: `Connector "${connectorId}" not found in canvas "${name}"` })
+          return
+        }
+
+        const validAnchors = ['top', 'right', 'bottom', 'left']
+        if (startAnchor && !validAnchors.includes(startAnchor)) {
+          sendJson(res, 400, { error: `Invalid startAnchor "${startAnchor}". Must be one of: ${validAnchors.join(', ')}` })
+          return
+        }
+        if (endAnchor && !validAnchors.includes(endAnchor)) {
+          sendJson(res, 400, { error: `Invalid endAnchor "${endAnchor}". Must be one of: ${validAnchors.join(', ')}` })
+          return
+        }
+
+        const updates = {}
+        if (meta) updates.meta = { ...meta }
+        if (startAnchor) updates.startAnchor = startAnchor
+        if (endAnchor) updates.endAnchor = endAnchor
+
+        appendEvent(filePath, {
+          event: 'connector_updated',
+          timestamp: new Date().toISOString(),
+          connectorId,
+          updates,
+        })
+
+        sendJson(res, 200, { success: true })
+        pushCanvasUpdate(name, filePath, __viteWs)
+
+        // Inject messaging skill into both terminals when mode changes
+        if (meta?.messagingMode || meta?.messaging) {
+          const widgets = data.widgets || []
+          const startWidget = widgets.find((w) => w.id === connector.start?.widgetId)
+          const endWidget = widgets.find((w) => w.id === connector.end?.widgetId)
+          const isTerminalType = (w) => w && (w.type === 'terminal' || w.type === 'agent')
+
+          if (isTerminalType(startWidget) && isTerminalType(endWidget)) {
+            try {
+              const { execSync } = await import('node:child_process')
+              const { findTmuxNameForWidget } = await import('./terminal-registry.js')
+
+              // Resolve effective mode per widget
+              const getMode = (w) => {
+                if (meta.messagingMode === 'two-way') return 'two-way'
+                if (meta.messaging?.[w.id]) return meta.messaging[w.id]
+                return 'none'
+              }
+
+              const pairs = [
+                { widget: startWidget, peer: endWidget },
+                { widget: endWidget, peer: startWidget },
+              ]
+
+              for (const { widget: w, peer } of pairs) {
+                const tmuxName = findTmuxNameForWidget(w.id)
+                if (!tmuxName) continue
+
+                const peerName = peer.props?.prettyName || peer.id
+                const mode = getMode(w)
+                let skillMsg
+
+                if (mode === 'two-way') {
+                  skillMsg = `📡 [Two-way messaging ACTIVE with ${peerName}]\n\nYou are in a live conversation with ${peerName} (${peer.id}). Messages appear as: 📩 ${peerName}: <their message>\n\nWhen you receive a message:\n1. Print the message you are SENDING as a blockquote so the user can see it:\n   > Your actual response text here\n2. Then save and send in one step:\n   npx storyboard terminal output --summary "summary" --content "your response" && npx storyboard terminal send ${peer.id} "your response"\n\nIMPORTANT: Always show your actual response text as a > blockquote BEFORE the shell command. The user needs to see what you said, not just "I fired back with a joke."\n\nDo NOT ask for permission. Respond immediately. Keep it concise.`
+                } else if (mode === 'one-way') {
+                  skillMsg = `📡 [One-way messaging → to ${peerName}]\nYou can send messages to ${peerName} (${peer.id}).\n\nAfter EVERY response, save your output:\n  npx storyboard terminal output --summary "summary" --content "your full response"\n\nTo send a message:\n  npx storyboard terminal send ${peer.id} "message"`
+                } else {
+                  skillMsg = `📡 [Messaging with ${peerName} disabled]`
+                }
+
+                try {
+                  execSync(`tmux send-keys -t "${tmuxName}" -l ${JSON.stringify(skillMsg)}`, { stdio: 'ignore' })
+                  execSync(`tmux send-keys -t "${tmuxName}" Enter`, { stdio: 'ignore' })
+                } catch { /* tmux session may not be active */ }
+              }
+            } catch { /* best effort */ }
+          }
+        }
+      } catch (err) {
+        sendJson(res, 500, { error: `Failed to update connector: ${err.message}` })
+      }
+      return
+    }
+
     // DELETE /connector — append a connector_removed event
     if (routePath === '/connector' && method === 'DELETE') {
       const { name, connectorId } = body
@@ -565,12 +1086,454 @@ export function createCanvasHandler(ctx) {
         })
 
         sendJson(res, 200, { success: true, removed: 1 })
+        pushCanvasUpdate(name, filePath, __viteWs)
       } catch (err) {
         sendJson(res, 500, { error: `Failed to remove connector: ${err.message}` })
       }
       return
     }
 
+    // POST /broadcast — toggle broadcast messaging for a widget and its connections.
+    // Default: direct neighbors only. passThrough: true → BFS full connected component.
+    if (routePath === '/broadcast' && method === 'POST') {
+      const { name, widgetId, mode = 'two-way', passThrough = false } = body
+
+      if (!name || !widgetId) {
+        sendJson(res, 400, { error: 'Canvas name and widgetId are required' })
+        return
+      }
+      if (mode !== 'two-way' && mode !== 'one-way' && mode !== 'none') {
+        sendJson(res, 400, { error: 'mode must be "two-way", "one-way", or "none"' })
+        return
+      }
+
+      const filePath = findCanvasPath(root, name)
+      if (!filePath) {
+        sendJson(res, 404, { error: `Canvas "${name}" not found` })
+        return
+      }
+
+      try {
+        const data = readCanvas(filePath)
+        const widgets = data.widgets || []
+        const connectors = data.connectors || []
+        const widgetMap = new Map(widgets.map((w) => [w.id, w]))
+
+        const sourceWidget = widgetMap.get(widgetId)
+        if (!sourceWidget) {
+          sendJson(res, 404, { error: `Widget "${widgetId}" not found` })
+          return
+        }
+
+        const isTerminalType = (w) => w && (w.type === 'terminal' || w.type === 'agent')
+
+        // Find connectors to update via BFS (or direct neighbors only)
+        const affectedConnectorIds = new Set()
+        const affectedWidgetIds = new Set([widgetId])
+
+        if (passThrough) {
+          // BFS: traverse entire connected component of terminal/agent widgets
+          const visited = new Set([widgetId])
+          const queue = [widgetId]
+          while (queue.length > 0) {
+            const current = queue.shift()
+            for (const conn of connectors) {
+              let peerId = null
+              if (conn.start?.widgetId === current && conn.end?.widgetId) peerId = conn.end.widgetId
+              if (conn.end?.widgetId === current && conn.start?.widgetId) peerId = conn.start.widgetId
+              if (!peerId || visited.has(peerId)) continue
+              const peer = widgetMap.get(peerId)
+              if (!isTerminalType(peer)) continue
+              affectedConnectorIds.add(conn.id)
+              affectedWidgetIds.add(peerId)
+              visited.add(peerId)
+              queue.push(peerId)
+            }
+          }
+        } else {
+          // Direct neighbors only
+          for (const conn of connectors) {
+            let peerId = null
+            if (conn.start?.widgetId === widgetId && conn.end?.widgetId) peerId = conn.end.widgetId
+            if (conn.end?.widgetId === widgetId && conn.start?.widgetId) peerId = conn.start.widgetId
+            if (!peerId) continue
+            const peer = widgetMap.get(peerId)
+            if (!isTerminalType(peer)) continue
+            affectedConnectorIds.add(conn.id)
+            affectedWidgetIds.add(peerId)
+          }
+        }
+
+        // Update all affected connectors
+        const ts = new Date().toISOString()
+        const messagingMode = mode === 'none' ? null : mode
+        for (const connId of affectedConnectorIds) {
+          appendEvent(filePath, {
+            event: 'connector_updated',
+            timestamp: ts,
+            connectorId: connId,
+            updates: { meta: { messagingMode } },
+          })
+        }
+
+        sendJson(res, 200, {
+          success: true,
+          affectedConnectors: [...affectedConnectorIds],
+          affectedWidgets: [...affectedWidgetIds],
+        })
+        pushCanvasUpdate(name, filePath, __viteWs)
+
+        // Inject messaging skill into affected terminals
+        if (affectedConnectorIds.size > 0) {
+          try {
+            const { execSync } = await import('node:child_process')
+            const { findTmuxNameForWidget } = await import('./terminal-registry.js')
+
+            for (const wId of affectedWidgetIds) {
+              const w = widgetMap.get(wId)
+              if (!isTerminalType(w)) continue
+              const tmuxName = findTmuxNameForWidget(wId)
+              if (!tmuxName) continue
+
+              // Build peer list for this widget
+              const peers = []
+              for (const conn of connectors) {
+                let peerId = null
+                if (conn.start?.widgetId === wId) peerId = conn.end?.widgetId
+                if (conn.end?.widgetId === wId) peerId = conn.start?.widgetId
+                if (peerId && affectedWidgetIds.has(peerId) && peerId !== wId) {
+                  const peer = widgetMap.get(peerId)
+                  if (peer) peers.push(peer)
+                }
+              }
+
+              if (mode === 'none') {
+                const msg = '📡 [Broadcast disabled]'
+                try {
+                  execSync(`tmux send-keys -t "${tmuxName}" -l ${JSON.stringify(msg)}`, { stdio: 'ignore' })
+                  execSync(`tmux send-keys -t "${tmuxName}" Enter`, { stdio: 'ignore' })
+                } catch { /* session may not be active */ }
+              } else {
+                const peerNames = peers.map((p) => p.props?.prettyName || p.id).join(', ')
+                const msg = `📡 [Broadcast ${mode} ACTIVE with ${peerNames}]`
+                try {
+                  execSync(`tmux send-keys -t "${tmuxName}" -l ${JSON.stringify(msg)}`, { stdio: 'ignore' })
+                  execSync(`tmux send-keys -t "${tmuxName}" Enter`, { stdio: 'ignore' })
+                } catch { /* session may not be active */ }
+              }
+            }
+          } catch { /* best effort */ }
+        }
+      } catch (err) {
+        sendJson(res, 500, { error: `Failed to update broadcast: ${err.message}` })
+      }
+      return
+    }
+
+    // POST /batch — execute multiple canvas operations in a single request.
+    // Reads the canvas once, appends all events, pushes ONE HMR update at the end.
+    // Operations reference earlier results via $index (auto) or $refName (opt-in).
+    if (routePath === '/batch' && method === 'POST') {
+      const { name, operations } = body
+
+      if (!name) {
+        sendJson(res, 400, { error: 'Canvas name is required' })
+        return
+      }
+      if (!Array.isArray(operations) || operations.length === 0) {
+        sendJson(res, 400, { error: 'operations must be a non-empty array' })
+        return
+      }
+      if (operations.length > 200) {
+        sendJson(res, 400, { error: 'Maximum 200 operations per batch' })
+        return
+      }
+
+      const filePath = findCanvasPath(root, name)
+      if (!filePath) {
+        sendJson(res, 404, { error: `Canvas "${name}" not found` })
+        return
+      }
+
+      try {
+        const canvasData = readCanvas(filePath)
+        const widgetIds = new Set((canvasData.widgets || []).map((w) => w.id))
+        const connectorIds = new Set((canvasData.connectors || []).map((c) => c.id))
+        const widgetMap = new Map((canvasData.widgets || []).map((w) => [w.id, { ...w }]))
+        const connectorMap = new Map((canvasData.connectors || []).map((c) => [c.id, { ...c }]))
+
+        const refs = {}
+        const results = []
+        const validAnchors = ['top', 'bottom', 'left', 'right']
+
+        // Resolve $ref strings — "$0", "$myName", etc.
+        function resolveRef(val) {
+          if (typeof val !== 'string' || !val.startsWith('$')) return val
+          const refName = val.slice(1)
+          if (refs[refName] !== undefined) return refs[refName]
+          throw new Error(`Unknown ref "${val}"`)
+        }
+
+        for (let i = 0; i < operations.length; i++) {
+          const op = operations[i]
+          const ts = new Date().toISOString()
+
+          try {
+            switch (op.op) {
+              case 'create-widget': {
+                const { type, props = {}, ref, pool, near, direction, resolve: doResolve, source: opSource } = op
+                let position = op.position || { x: 0, y: 0 }
+                if (!type) throw new Error('type is required')
+
+                // Detect whether an explicit position was provided
+                const hasExplicitPos = op.position && (op.position.x !== 0 || op.position.y !== 0)
+                const hasNearOptOut = near === false
+                const needsAuto = !near && !hasExplicitPos && !hasNearOptOut
+
+                // --near: compute position relative to a reference widget
+                if (near) {
+                  const nearId = resolveRef(near)
+                  const refWidget = widgetMap.get(nearId)
+                  if (!refWidget) throw new Error(`Widget "${nearId}" not found (near)`)
+                  position = computeNearPosition(refWidget, direction || 'right', type, props)
+                }
+
+                // Auto-position: no --near, no explicit x,y → smart default
+                if (needsAuto && !near) {
+                  const currentWidgets = Array.from(widgetMap.values())
+                  position = await computeAutoPosition(currentWidgets, type, props, root, name, opSource || null)
+                }
+
+                // Collision resolution: uses live widgetMap (includes earlier batch creates)
+                if (near || doResolve || needsAuto) {
+                  const resolved = resolvePosition({
+                    x: position.x, y: position.y, type, props,
+                    widgets: Array.from(widgetMap.values()),
+                    gridSize: canvasData.gridSize || 24,
+                  })
+                  position = { x: resolved.x, y: resolved.y }
+                }
+
+                const widgetId = generateWidgetId(type)
+                await prepareTerminalWidget({ type, props, widgetId, canvasName: name, req })
+
+                let hotSession = null
+                if ((type === 'terminal' || type === 'agent') && pool !== 'cold') {
+                  const poolId = resolvePoolId(type, props)
+                  hotSession = acquireFromPool(hotPool, poolId, pool)
+                  if (!hotSession && pool === 'hot') throw new Error(`No warm sessions available in pool "${poolId}"`)
+                }
+
+                const widget = stampBounds({ id: widgetId, type, position, props })
+
+                appendEvent(filePath, { event: 'widget_added', timestamp: ts, widget })
+
+                widgetIds.add(widgetId)
+                widgetMap.set(widgetId, widget)
+                refs[String(i)] = widgetId
+                if (ref) refs[ref] = widgetId
+
+                const result = { index: i, op: 'create-widget', ref: ref || undefined, widgetId, widget }
+                if (hotSession) result.hotSession = { id: hotSession.id, tmuxName: hotSession.tmuxName || null }
+                results.push(result)
+                break
+              }
+
+              case 'update-widget': {
+                const widgetId = resolveRef(op.widgetId)
+                const { props } = op
+                if (!widgetId) throw new Error('widgetId is required')
+                if (!props) throw new Error('props is required')
+                if (!widgetIds.has(widgetId)) throw new Error(`Widget "${widgetId}" not found`)
+
+                appendEvent(filePath, { event: 'widget_updated', timestamp: ts, widgetId, props })
+
+                const existing = widgetMap.get(widgetId)
+                if (existing) existing.props = { ...existing.props, ...props }
+
+                results.push({ index: i, op: 'update-widget', widgetId, success: true })
+                break
+              }
+
+              case 'move-widget': {
+                const widgetId = resolveRef(op.widgetId)
+                const { position } = op
+                if (!widgetId) throw new Error('widgetId is required')
+                if (!position) throw new Error('position is required')
+                if (!widgetIds.has(widgetId)) throw new Error(`Widget "${widgetId}" not found`)
+
+                const existing = widgetMap.get(widgetId)
+                const mergedPosition = { ...(existing?.position || {}), ...position }
+
+                appendEvent(filePath, { event: 'widget_moved', timestamp: ts, widgetId, position: mergedPosition })
+
+                if (existing) existing.position = mergedPosition
+
+                results.push({ index: i, op: 'move-widget', widgetId, success: true })
+                break
+              }
+
+              case 'delete-widget': {
+                const widgetId = resolveRef(op.widgetId)
+                if (!widgetId) throw new Error('widgetId is required')
+                if (!widgetIds.has(widgetId)) throw new Error(`Widget "${widgetId}" not found`)
+
+                appendEvent(filePath, { event: 'widget_removed', timestamp: ts, widgetId })
+
+                widgetIds.delete(widgetId)
+                widgetMap.delete(widgetId)
+
+                results.push({ index: i, op: 'delete-widget', widgetId, success: true })
+                break
+              }
+
+              case 'create-connector': {
+                const startWidgetId = resolveRef(op.startWidgetId)
+                const endWidgetId = resolveRef(op.endWidgetId)
+                const { startAnchor = 'right', endAnchor = 'left', connectorType = 'default', ref } = op
+
+                if (!startWidgetId || !endWidgetId) throw new Error('startWidgetId and endWidgetId are required')
+                if (!validAnchors.includes(startAnchor) || !validAnchors.includes(endAnchor)) {
+                  throw new Error(`Anchors must be one of: ${validAnchors.join(', ')}`)
+                }
+                if (startWidgetId === endWidgetId) throw new Error('Cannot connect a widget to itself')
+                if (!widgetIds.has(startWidgetId)) throw new Error(`Widget "${startWidgetId}" not found`)
+                if (!widgetIds.has(endWidgetId)) throw new Error(`Widget "${endWidgetId}" not found`)
+
+                const connectorId = generateWidgetId('connector')
+                const connector = {
+                  id: connectorId,
+                  type: 'connector',
+                  connectorType,
+                  start: { widgetId: startWidgetId, anchor: startAnchor },
+                  end: { widgetId: endWidgetId, anchor: endAnchor },
+                  meta: {},
+                }
+
+                appendEvent(filePath, { event: 'connector_added', timestamp: ts, connector })
+
+                connectorIds.add(connectorId)
+                connectorMap.set(connectorId, connector)
+                refs[String(i)] = connectorId
+                if (ref) refs[ref] = connectorId
+
+                results.push({ index: i, op: 'create-connector', ref: ref || undefined, connectorId, success: true })
+                break
+              }
+
+              case 'delete-connector': {
+                const connectorId = resolveRef(op.connectorId)
+                if (!connectorId) throw new Error('connectorId is required')
+                if (!connectorIds.has(connectorId)) throw new Error(`Connector "${connectorId}" not found`)
+
+                appendEvent(filePath, { event: 'connector_removed', timestamp: ts, connectorId })
+                connectorIds.delete(connectorId)
+                connectorMap.delete(connectorId)
+
+                results.push({ index: i, op: 'delete-connector', connectorId, success: true })
+                break
+              }
+
+              case 'update-connector': {
+                const connectorId = resolveRef(op.connectorId)
+                const { meta } = op
+                if (!connectorId) throw new Error('connectorId is required')
+                if (!meta) throw new Error('meta is required')
+                if (!connectorIds.has(connectorId)) throw new Error(`Connector "${connectorId}" not found`)
+
+                appendEvent(filePath, { event: 'connector_updated', timestamp: ts, connectorId, updates: { meta } })
+
+                const existing = connectorMap.get(connectorId)
+                if (existing) existing.meta = { ...(existing.meta || {}), ...meta }
+
+                results.push({ index: i, op: 'update-connector', connectorId, success: true })
+                break
+              }
+
+              case 'broadcast': {
+                const wId = resolveRef(op.widgetId)
+                const mode = op.mode || 'two-way'
+                const passThrough = !!op.passThrough
+                if (!wId) throw new Error('widgetId is required')
+                if (!widgetIds.has(wId)) throw new Error(`Widget "${wId}" not found`)
+
+                const isTerminalType = (w) => w && (w.type === 'terminal' || w.type === 'agent')
+                const allConnectors = [...connectorMap.values()]
+                const affectedConnectorIds = new Set()
+                const affectedWidgetIds = new Set([wId])
+
+                if (passThrough) {
+                  const visited = new Set([wId])
+                  const queue = [wId]
+                  while (queue.length > 0) {
+                    const current = queue.shift()
+                    for (const conn of allConnectors) {
+                      let peerId = null
+                      if (conn.start?.widgetId === current && conn.end?.widgetId) peerId = conn.end.widgetId
+                      if (conn.end?.widgetId === current && conn.start?.widgetId) peerId = conn.start.widgetId
+                      if (!peerId || visited.has(peerId)) continue
+                      const peer = widgetMap.get(peerId)
+                      if (!isTerminalType(peer)) continue
+                      affectedConnectorIds.add(conn.id)
+                      affectedWidgetIds.add(peerId)
+                      visited.add(peerId)
+                      queue.push(peerId)
+                    }
+                  }
+                } else {
+                  for (const conn of allConnectors) {
+                    let peerId = null
+                    if (conn.start?.widgetId === wId && conn.end?.widgetId) peerId = conn.end.widgetId
+                    if (conn.end?.widgetId === wId && conn.start?.widgetId) peerId = conn.start.widgetId
+                    if (!peerId) continue
+                    const peer = widgetMap.get(peerId)
+                    if (!isTerminalType(peer)) continue
+                    affectedConnectorIds.add(conn.id)
+                    affectedWidgetIds.add(peerId)
+                  }
+                }
+
+                const messagingMode = mode === 'none' ? null : mode
+                for (const connId of affectedConnectorIds) {
+                  appendEvent(filePath, { event: 'connector_updated', timestamp: ts, connectorId: connId, updates: { meta: { messagingMode } } })
+                  const conn = connectorMap.get(connId)
+                  if (conn) conn.meta = { ...(conn.meta || {}), messagingMode }
+                }
+
+                results.push({
+                  index: i, op: 'broadcast',
+                  affectedConnectors: [...affectedConnectorIds],
+                  affectedWidgets: [...affectedWidgetIds],
+                  success: true,
+                })
+                break
+              }
+
+              default:
+                throw new Error(`Unknown operation "${op.op}"`)
+            }
+          } catch (opErr) {
+            // Fail-fast: push what we have so far, then return the error
+            pushCanvasUpdate(name, filePath, __viteWs)
+            sendJson(res, 400, {
+              success: false,
+              error: `Operation ${i} (${op.op}) failed: ${opErr.message}`,
+              failedAt: i,
+              results,
+              refs,
+            })
+            return
+          }
+        }
+
+        sendJson(res, 200, { success: true, results, refs })
+        pushCanvasUpdate(name, filePath, __viteWs)
+      } catch (err) {
+        sendJson(res, 500, { error: `Batch failed: ${err.message}` })
+      }
+      return
+    }
+
     // PUT /rename-page — rename a canvas page file
     if (routePath === '/rename-page' && method === 'PUT') {
       const { name, newTitle } = body
@@ -1258,15 +2221,25 @@ export function Default() {
       const now = new Date()
       const pad = (n) => String(n).padStart(2, '0')
       const dateStr = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}--${pad(now.getHours())}-${pad(now.getMinutes())}-${pad(now.getSeconds())}`
+      const suffix = `-${Math.random().toString(36).slice(2, 6)}`
       const prefix = canvasName ? `${canvasName.replace(/[/:]/g, '--')}--` : ''
 
       // Support explicit filename for snapshot uploads (stable naming)
+      // and cropped image uploads (user-initiated crop)
       const explicitName = body.filename
       let filename
       if (explicitName && /^snapshot-[a-z0-9_-]+--(latest|light|dark)\.webp$/i.test(explicitName)) {
         filename = explicitName
+      } else if (explicitName && /--cropped--\d{4}-\d{2}-\d{2}--\d{2}-\d{2}-\d{2}\.\w+$/.test(explicitName)) {
+        // Cropped image: validate format, strip path traversal
+        const safeName = explicitName.replace(/[/\\]/g, '')
+        if (safeName === explicitName && !explicitName.includes('..')) {
+          filename = explicitName
+        } else {
+          filename = `${prefix}${dateStr}${suffix}.${ext}`
+        }
       } else {
-        filename = `${prefix}${dateStr}.${ext}`
+        filename = `${prefix}${dateStr}${suffix}.${ext}`
       }
       const targetDir = resolveWriteDir(canvasName || '')
 
@@ -1316,7 +2289,48 @@ export function Default() {
       return
     }
 
-    // POST /image/toggle-private — toggle underscore prefix on image filename
+    // POST /image/duplicate — copy an image file with a new timestamped name
+    if (routePath === '/image/duplicate' && method === 'POST') {
+      const { filename } = body
+
+      if (!filename || typeof filename !== 'string') {
+        sendJson(res, 400, { error: 'filename is required' })
+        return
+      }
+
+      if (filename.includes('..') || filename.includes('/') || filename.includes('\\')) {
+        sendJson(res, 400, { error: 'Invalid filename' })
+        return
+      }
+
+      const sourcePath = resolveImagePath(filename)
+      if (!sourcePath) {
+        sendJson(res, 404, { error: 'Image not found' })
+        return
+      }
+
+      try {
+        const ext = path.extname(filename)
+        const now = new Date()
+        const pad = (n) => String(n).padStart(2, '0')
+        const dateStr = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}--${pad(now.getHours())}-${pad(now.getMinutes())}-${pad(now.getSeconds())}`
+        // Preserve privacy prefix
+        const prefix = filename.startsWith('~') ? '~' : ''
+        const baseName = filename.replace(/^~/, '').replace(ext, '')
+        // Extract canvas prefix (everything before the date pattern or the full base)
+        const canvasMatch = baseName.match(/^(.+?--)\d{4}-/)
+        const canvasPrefix = canvasMatch ? canvasMatch[1] : ''
+        const newFilename = `${prefix}${canvasPrefix}${dateStr}${ext}`
+        const targetDir = path.dirname(sourcePath)
+        fs.copyFileSync(sourcePath, path.join(targetDir, newFilename))
+        sendJson(res, 201, { success: true, filename: newFilename })
+      } catch (err) {
+        sendJson(res, 500, { error: `Failed to duplicate image: ${err.message}` })
+      }
+      return
+    }
+
+    // POST /image/toggle-private — toggle tilde prefix on image filename
     if (routePath === '/image/toggle-private' && method === 'POST') {
       const { filename } = body
 
@@ -1330,8 +2344,8 @@ export function Default() {
         return
       }
 
-      const isPrivate = filename.startsWith('_')
-      const newFilename = isPrivate ? filename.slice(1) : `_${filename}`
+      const isPrivate = filename.startsWith('~')
+      const newFilename = isPrivate ? filename.slice(1) : `~${filename}`
       const oldPath = resolveImagePath(filename)
       if (!oldPath) {
         sendJson(res, 404, { error: 'Image not found' })
@@ -1349,6 +2363,771 @@ export function Default() {
       return
     }
 
+    // ── Agent Signal API ──────────────────────────────────────────────────
+
+    // POST /agent/signal — agent signals status (done/error/running)
+    if (routePath === '/agent/signal' && method === 'POST') {
+      const { widgetId, canvasId, branch, status, message, data: payload } = body
+
+      if (!widgetId || !status) {
+        sendJson(res, 400, { error: 'widgetId and status are required' })
+        return
+      }
+
+      const validStatuses = ['done', 'error', 'running']
+      if (!validStatuses.includes(status)) {
+        sendJson(res, 400, { error: `status must be one of: ${validStatuses.join(', ')}` })
+        return
+      }
+
+      try {
+        const { updateAgentStatus, initTerminalConfig } = await import('./terminal-config.js')
+        initTerminalConfig(root)
+        updateAgentStatus({
+          branch: branch || 'unknown',
+          canvasId: canvasId || 'unknown',
+          widgetId,
+          status,
+          message: message || null,
+          data: payload || null,
+        })
+
+        // Push status to canvas clients via Vite WS custom event
+        if (__viteWs) {
+          __viteWs.send({
+            type: 'custom',
+            event: 'storyboard:agent-status',
+            data: { widgetId, canvasId, status, message, timestamp: new Date().toISOString() },
+          })
+        }
+
+        sendJson(res, 200, { success: true, status })
+      } catch (err) {
+        sendJson(res, 500, { error: `Failed to update agent status: ${err.message}` })
+      }
+      return
+    }
+
+    // GET /agent/status — poll agent status for a widget
+    if (routePath === '/agent/status' && method === 'GET') {
+      const url = new URL(req.url, 'http://localhost')
+      const widgetId = url.searchParams.get('widgetId')
+      const canvasId = url.searchParams.get('canvasId') || 'unknown'
+      const branch = url.searchParams.get('branch') || 'unknown'
+
+      if (!widgetId) {
+        sendJson(res, 400, { error: 'widgetId query parameter is required' })
+        return
+      }
+
+      try {
+        const { readTerminalConfig, initTerminalConfig } = await import('./terminal-config.js')
+        initTerminalConfig(root)
+        const config = readTerminalConfig({ branch, canvasId, widgetId })
+        sendJson(res, 200, { agentStatus: config?.agentStatus || null })
+      } catch (err) {
+        sendJson(res, 500, { error: `Failed to read agent status: ${err.message}` })
+      }
+      return
+    }
+
+    // POST /agent/spawn — spawn a headless agent session
+    if (routePath === '/agent/spawn' && method === 'POST') {
+      const { canvasId, widgetId, prompt, autopilot = true, branch: reqBranch } = body
+
+      if (!canvasId || !widgetId || !prompt) {
+        sendJson(res, 400, { error: 'canvasId, widgetId, and prompt are required' })
+        return
+      }
+
+      try {
+        const { execSync } = await import('node:child_process')
+        const { writeTerminalConfig, updateAgentStatus, initTerminalConfig } = await import('./terminal-config.js')
+        const { generateTmuxName, registerSession } = await import('./terminal-registry.js')
+        const fsModule = await import('node:fs')
+
+        initTerminalConfig(root)
+
+        let branch = reqBranch || 'unknown'
+        try {
+          branch = execSync('git branch --show-current', { encoding: 'utf8', cwd: root }).trim()
+        } catch {}
+
+        const tmuxName = generateTmuxName(branch, canvasId, widgetId)
+
+        // Register in session registry
+        registerSession({ branch, canvasId, widgetId, prettyName: null })
+
+        // Write terminal config with connected widget context
+        writeTerminalConfig({ branch, canvasId, widgetId })
+
+        // Mark as running
+        updateAgentStatus({ branch, canvasId, widgetId, status: 'running', message: 'Agent spawning...' })
+
+        // Push running status to clients
+        if (__viteWs) {
+          __viteWs.send({
+            type: 'custom',
+            event: 'storyboard:agent-status',
+            data: { widgetId, canvasId, status: 'running', timestamp: new Date().toISOString() },
+          })
+        }
+
+        // Build server URL for agent env vars
+        const serverUrl = `http://localhost:${req.socket?.localPort || 1234}`
+
+        // Create headless tmux session
+        try {
+          execSync(`tmux new-session -d -s "${tmuxName}" -c "${root}"`, { stdio: 'ignore' })
+          execSync(`tmux set-option -t "${tmuxName}" status off`, { stdio: 'ignore' })
+          execSync(`tmux set-option -t "${tmuxName}" mouse on`, { stdio: 'ignore' })
+          execSync(`tmux set-option -t "${tmuxName}" set-clipboard off`, { stdio: 'ignore' })
+        } catch (err) {
+          // Session may already exist
+          devLog().logEvent('warn', 'tmux session create failed', { tmuxName, error: err.message })
+        }
+
+        // Set environment variables at tmux session level (inherited by new panes)
+        const envMap = {
+          STORYBOARD_WIDGET_ID: widgetId,
+          STORYBOARD_CANVAS_ID: canvasId,
+          STORYBOARD_BRANCH: branch,
+          STORYBOARD_SERVER_URL: serverUrl,
+        }
+        for (const [key, val] of Object.entries(envMap)) {
+          execSync(`tmux setenv -t "${tmuxName}" ${key} "${val}"`, { stdio: 'ignore' })
+        }
+
+        // Write env file for this terminal session — sourced before copilot launch
+        // This avoids race conditions with tmux send-keys export
+        const envFile = join(root, '.storyboard', 'terminals', `${tmuxName}.env`)
+        const envContent = Object.entries(envMap).map(([k, v]) => `export ${k}=${JSON.stringify(v)}`).join('\n') + '\n'
+        fsModule.writeFileSync(envFile, envContent)
+
+        // Build command from widgets.config.json (prompt mode) or storyboard.config.json (interactive)
+        let copilotCmd
+        if (autopilot) {
+          copilotCmd = buildPromptCmd({ prompt, envFile })
+          if (!copilotCmd) {
+            const execution = getPromptExecution()
+            sendJson(res, 400, { error: `Default agent "${execution?.default || 'unknown'}" has no prompt command configured` })
+            return
+          }
+        } else {
+          // Interactive mode — read startupCommand from storyboard.config.json
+          let startupCmd = 'copilot'
+          try {
+            const configPath = path.join(root, 'storyboard.config.json')
+            const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'))
+            const agents = config?.canvas?.agents || {}
+            const defaultAgent = Object.values(agents).find(a => a.default) || Object.values(agents)[0]
+            if (defaultAgent?.startupCommand) startupCmd = defaultAgent.startupCommand
+          } catch {}
+          copilotCmd = `source ${envFile} && ${startupCmd}`
+        }
+
+        setTimeout(() => {
+          try {
+            execSync(`tmux send-keys -t "${tmuxName}" -l ${JSON.stringify(copilotCmd)}`, { stdio: 'ignore' })
+            execSync(`tmux send-keys -t "${tmuxName}" Enter`, { stdio: 'ignore' })
+          } catch (err) {
+            devLog().logEvent('warn', 'Failed to launch copilot', { tmuxName, error: err.message })
+          }
+          // Poll for copilot readiness, then send /autopilot + Enter once
+          let sent = false
+          const poll = setInterval(() => {
+            if (sent) { clearInterval(poll); return }
+            try {
+              const pane = execSync(`tmux capture-pane -t "${tmuxName}" -p`, { encoding: 'utf8', timeout: 1000 })
+              if (pane.includes('Environment loaded:')) {
+                sent = true
+                clearInterval(poll)
+                setTimeout(() => {
+                  try {
+                    execSync(`tmux send-keys -t "${tmuxName}" -l "/allow-all on"`, { stdio: 'ignore' })
+                    execSync(`tmux send-keys -t "${tmuxName}" Enter`, { stdio: 'ignore' })
+                  } catch {}
+                }, 500)
+              }
+            } catch {}
+          }, 1000)
+          setTimeout(() => { if (!sent) { sent = true; clearInterval(poll) } }, 15000)
+        }, 500)
+
+        // Set up idle timeout (5 minutes)
+        const IDLE_TIMEOUT = 5 * 60 * 1000
+        setTimeout(async () => {
+          try {
+            const { readTerminalConfig } = await import('./terminal-config.js')
+            const config = readTerminalConfig({ branch, canvasId, widgetId })
+            if (config?.agentStatus?.status === 'running') {
+              updateAgentStatus({ branch, canvasId, widgetId, status: 'error', message: 'Agent timed out (5 min idle)' })
+              if (__viteWs) {
+                __viteWs.send({
+                  type: 'custom',
+                  event: 'storyboard:agent-status',
+                  data: { widgetId, canvasId, status: 'error', message: 'Agent timed out', timestamp: new Date().toISOString() },
+                })
+              }
+            }
+          } catch {}
+        }, IDLE_TIMEOUT)
+
+        sendJson(res, 200, { success: true, tmuxName, status: 'running' })
+      } catch (err) {
+        sendJson(res, 500, { error: `Failed to spawn agent: ${err.message}` })
+      }
+      return
+    }
+
+    // POST /agent/peek — reconnect a headless agent session to a visible terminal widget
+    if (routePath === '/agent/peek' && method === 'POST') {
+      const { widgetId, canvasId } = body
+
+      if (!widgetId) {
+        sendJson(res, 400, { error: 'widgetId is required' })
+        return
+      }
+
+      try {
+        const { execSync } = await import('node:child_process')
+        const { generateTmuxName } = await import('./terminal-registry.js')
+
+        let branch = 'unknown'
+        try {
+          branch = execSync('git branch --show-current', { encoding: 'utf8', cwd: root }).trim()
+        } catch {}
+
+        const tmuxName = generateTmuxName(branch, canvasId || 'unknown', widgetId)
+
+        // Check if the tmux session exists
+        try {
+          execSync(`tmux has-session -t "${tmuxName}"`, { stdio: 'ignore' })
+        } catch {
+          sendJson(res, 404, { error: `No tmux session found for widget ${widgetId}` })
+          return
+        }
+
+        // The session exists — return info so the client can create a terminal widget
+        // that connects to it
+        sendJson(res, 200, {
+          success: true,
+          tmuxName,
+          widgetId,
+          canvasId: canvasId || 'unknown',
+          message: 'Session is alive. Create a terminal widget to connect.',
+        })
+      } catch (err) {
+        sendJson(res, 500, { error: `Failed to peek agent session: ${err.message}` })
+      }
+      return
+    }
+
+    // ── Terminal Messaging API ──────────────────────────────────────────
+
+    // POST /terminal/send — send a message to a terminal via tmux send-keys
+    if (routePath === '/terminal/send' && method === 'POST') {
+      const { widgetId: targetWidgetId, message, from: senderWidgetId } = body
+
+      if (!targetWidgetId || !message) {
+        sendJson(res, 400, { error: 'widgetId and message are required' })
+        return
+      }
+
+      try {
+        const { execSync } = await import('node:child_process')
+        const { findTmuxNameForWidget } = await import('./terminal-registry.js')
+        const { readTerminalConfigById, updatePendingMessages, initTerminalConfig } = await import('./terminal-config.js')
+
+        initTerminalConfig(root)
+
+        const tmuxName = findTmuxNameForWidget(targetWidgetId)
+        if (!tmuxName) {
+          sendJson(res, 404, { error: `No active session for widget ${targetWidgetId}` })
+          return
+        }
+
+        // Check session is live (widget open in browser)
+        const { getSession } = await import('./terminal-registry.js')
+        const session = getSession(tmuxName)
+        const isLive = session?.status === 'live'
+
+        // Resolve sender display name
+        let senderName = senderWidgetId || 'unknown'
+        if (senderWidgetId) {
+          try {
+            const senderConfig = readTerminalConfigById(senderWidgetId)
+            if (senderConfig?.displayName) senderName = senderConfig.displayName
+          } catch { /* use widgetId as fallback */ }
+        }
+
+        // Deterministic agent detection: get the pane's shell PID, then
+        // check its child process. Known agent CLIs (copilot, claude) run
+        // as direct children of the shell. We match against the process
+        // name (comm) to identify which agent is running.
+        let runningAgent = null // null = no agent, 'copilot' | 'claude' | 'codex' = which one
+        try {
+          const panePid = execSync(
+            `tmux list-panes -t "${tmuxName}" -F '#{pane_pid}'`,
+            { encoding: 'utf8', timeout: 2000 }
+          ).trim()
+          if (panePid && isLive) {
+            const children = execSync(
+              `ps -o comm= -p $(pgrep -P ${panePid} 2>/dev/null | tr '\\n' ',') 2>/dev/null || true`,
+              { encoding: 'utf8', timeout: 2000 }
+            ).trim().split('\n').map(s => s.trim()).filter(Boolean)
+            for (const cmd of children) {
+              if (cmd === 'copilot') { runningAgent = 'copilot'; break }
+              if (cmd === 'claude') { runningAgent = 'claude'; break }
+              if (cmd === 'codex') { runningAgent = 'codex'; break }
+            }
+          }
+        } catch { /* tmux/ps not available */ }
+
+        const isAgentRunning = runningAgent !== null
+
+        if (isAgentRunning) {
+          // Agent is running — send the full message directly (like a chat bubble)
+          const formatted = `📩 ${senderName}: ${message}`
+
+          try {
+            execSync(`tmux send-keys -t "${tmuxName}" -l ${JSON.stringify(formatted)}`, { stdio: 'ignore' })
+            execSync(`tmux send-keys -t "${tmuxName}" Enter`, { stdio: 'ignore' })
+          } catch (err) {
+            sendJson(res, 500, { error: `Failed to send via tmux: ${err.message}` })
+            return
+          }
+
+          sendJson(res, 200, { success: true, delivered: true })
+        } else {
+          // Shell prompt or unknown — queue the message
+          updatePendingMessages(targetWidgetId, {
+            from: senderWidgetId || null,
+            fromName: senderName,
+            message,
+            createdAt: new Date().toISOString(),
+          })
+
+          sendJson(res, 200, { success: true, queued: true })
+        }
+      } catch (err) {
+        sendJson(res, 500, { error: `Failed to send message: ${err.message}` })
+      }
+      return
+    }
+
+    // POST /terminal/output — save latest output to terminal config
+    if (routePath === '/terminal/output' && method === 'POST') {
+      const { widgetId: outputWidgetId, content, summary } = body
+
+      if (!outputWidgetId) {
+        sendJson(res, 400, { error: 'widgetId is required' })
+        return
+      }
+
+      try {
+        const { updateLatestOutput, initTerminalConfig } = await import('./terminal-config.js')
+        initTerminalConfig(root)
+
+        updateLatestOutput(outputWidgetId, {
+          content: content || '',
+          summary: summary || '',
+          updatedAt: new Date().toISOString(),
+        })
+
+        sendJson(res, 200, { success: true })
+      } catch (err) {
+        sendJson(res, 500, { error: `Failed to save output: ${err.message}` })
+      }
+      return
+    }
+
+    // POST /prompt/spawn — spawn a prompt agent session (acquires from hot pool)
+    if (routePath === '/prompt/spawn' && method === 'POST') {
+      const { canvasId, widgetId, prompt } = body
+
+      if (!canvasId || !widgetId || !prompt) {
+        sendJson(res, 400, { error: 'canvasId, widgetId, and prompt are required' })
+        return
+      }
+
+      // Try to acquire a warm tmux session from the prompt pool
+      const warmSession = hotPool?.acquire('prompt') || null
+
+      // Delegate to agent/spawn — the prompt widget is just a specialized agent
+      // We reuse the same tmux-based infrastructure
+      try {
+        const { execSync } = await import('node:child_process')
+        const { writeTerminalConfig, updateAgentStatus, updateTerminalConnections, initTerminalConfig } = await import('./terminal-config.js')
+        const { generateTmuxName, registerSession } = await import('./terminal-registry.js')
+        const fsModule = await import('node:fs')
+
+        initTerminalConfig(root)
+
+        let branch = 'unknown'
+        try {
+          branch = execSync('git branch --show-current', { encoding: 'utf8', cwd: root }).trim()
+        } catch {}
+
+        const serverUrl = `http://localhost:${req.socket?.localPort || 1234}`
+        const tmuxName = generateTmuxName(branch, canvasId, widgetId)
+
+        registerSession({ branch, canvasId, widgetId, prettyName: null })
+        writeTerminalConfig({ branch, canvasId, widgetId, serverUrl, tmuxName })
+        updateAgentStatus({ branch, canvasId, widgetId, status: 'running', message: 'Prompt agent spawning...' })
+
+        // Resolve connected widgets so the terminal-agent has context
+        try {
+          const canvasFilePath = findCanvasPath(root, canvasId)
+          if (canvasFilePath) {
+            const canvasData = readCanvas(canvasFilePath)
+            const widgetMap = new Map((canvasData.widgets || []).map(w => [w.id, w]))
+            const connectors = canvasData.connectors || []
+            const connectedIds = new Set()
+            for (const conn of connectors) {
+              if (conn.start?.widgetId === widgetId) connectedIds.add(conn.end?.widgetId)
+              if (conn.end?.widgetId === widgetId) connectedIds.add(conn.start?.widgetId)
+            }
+            connectedIds.delete(undefined)
+            connectedIds.delete(null)
+            const connectedWidgets = [...connectedIds]
+              .map(id => widgetMap.get(id))
+              .filter(Boolean)
+              .map(w => ({ id: w.id, type: w.type, props: w.props, position: w.position }))
+            if (connectedWidgets.length > 0) {
+              updateTerminalConnections({ branch, canvasId, widgetId, connectedWidgets })
+            }
+          }
+        } catch (err) {
+          devLog().logEvent('warn', 'Failed to resolve prompt connections', { error: err.message })
+        }
+
+        if (__viteWs) {
+          __viteWs.send({
+            type: 'custom',
+            event: 'storyboard:agent-status',
+            data: { widgetId, canvasId, status: 'running', timestamp: new Date().toISOString() },
+          })
+        }
+
+        // If we got a warm tmux session, rename it to the canonical name.
+        // Otherwise, create a fresh tmux session from scratch.
+        let usedWarm = false
+        if (warmSession?.tmuxName) {
+          try {
+            // Kill any existing session with the canonical name first
+            try { execSync(`tmux kill-session -t "${tmuxName}" 2>/dev/null`, { stdio: 'ignore' }) } catch {}
+            // Rename the warm session to the canonical name
+            execSync(`tmux rename-session -t "${warmSession.tmuxName}" "${tmuxName}"`, { stdio: 'ignore' })
+            usedWarm = true
+            hotPool.consume('prompt', warmSession.id)
+          } catch {
+            // Rename failed — fall back to creating fresh session
+            hotPool.release('prompt', warmSession.id)
+          }
+        }
+
+        if (!usedWarm) {
+          // Fresh tmux session (cold path)
+          try {
+            execSync(`tmux -f /dev/null new-session -d -s "${tmuxName}" -c "${root}"`, { stdio: 'ignore' })
+            execSync(`tmux set-option -t "${tmuxName}" status off`, { stdio: 'ignore' })
+            execSync(`tmux set-option -t "${tmuxName}" set-clipboard off 2>/dev/null`, { stdio: 'ignore' })
+          } catch { /* session may already exist */ }
+        }
+
+        // Set env vars — use send-keys to export into the running shell
+        const envMap = {
+          STORYBOARD_WIDGET_ID: widgetId,
+          STORYBOARD_CANVAS_ID: canvasId,
+          STORYBOARD_BRANCH: branch,
+          STORYBOARD_SERVER_URL: serverUrl,
+        }
+
+        // Write env file for the copilot command to source
+        const { join } = await import('node:path')
+        const envFile = join(root, '.storyboard', 'terminals', `${tmuxName}.env`)
+        const envContent = Object.entries(envMap).map(([k, v]) => `export ${k}=${JSON.stringify(v)}`).join('\n') + '\n'
+        fsModule.writeFileSync(envFile, envContent)
+
+        const copilotCmd = buildPromptCmd({ prompt, envFile })
+        if (!copilotCmd) {
+          const execution = getPromptExecution()
+          sendJson(res, 400, { error: `Default agent "${execution?.default || 'unknown'}" has no prompt command configured` })
+          return
+        }
+
+        // Send the copilot command — warm sessions have a shell ready, no delay needed
+        const delay = usedWarm ? 0 : 500
+        const displayName = (() => {
+          try {
+            const canvasFilePath = findCanvasPath(root, canvasId)
+            if (!canvasFilePath) return null
+            const canvasData = readCanvas(canvasFilePath)
+            const w = (canvasData.widgets || []).find(w => w.id === widgetId)
+            return w?.props?.prettyName || null
+          } catch { return null }
+        })()
+        const sendCmd = () => {
+          try {
+            execSync(`tmux send-keys -t "${tmuxName}" -l ${JSON.stringify(copilotCmd)}`, { stdio: 'ignore' })
+            execSync(`tmux send-keys -t "${tmuxName}" Enter`, { stdio: 'ignore' })
+          } catch {}
+          // Inject identity after the agent command starts
+          setTimeout(() => {
+            const configFile = `.storyboard/terminals/${widgetId}.json`
+            const msg = `[System] Your terminal identity has been set. widgetId=${widgetId} displayName=${displayName || widgetId} canvasId=${canvasId} configFile=${configFile} serverUrl=${serverUrl} — this is a configuration step, no response needed.`
+            try {
+              execSync(`tmux send-keys -t "${tmuxName}" -l ${JSON.stringify(msg)}`, { stdio: 'ignore' })
+              execSync(`tmux send-keys -t "${tmuxName}" Enter`, { stdio: 'ignore' })
+            } catch {}
+          }, 3000)
+        }
+
+        if (delay > 0) {
+          setTimeout(sendCmd, delay)
+        } else {
+          sendCmd()
+        }
+
+        // Idle timeout (5 min)
+        setTimeout(async () => {
+          try {
+            const { readTerminalConfig } = await import('./terminal-config.js')
+            const cfg = readTerminalConfig({ branch, canvasId, widgetId })
+            if (cfg?.agentStatus?.status === 'running') {
+              updateAgentStatus({ branch, canvasId, widgetId, status: 'error', message: 'Prompt timed out (5 min)' })
+              if (__viteWs) {
+                __viteWs.send({
+                  type: 'custom',
+                  event: 'storyboard:agent-status',
+                  data: { widgetId, canvasId, status: 'error', message: 'Prompt timed out', timestamp: new Date().toISOString() },
+                })
+              }
+            }
+          } catch {}
+        }, 5 * 60 * 1000)
+
+        sendJson(res, 200, { success: true, tmuxName, status: 'running', warm: usedWarm })
+      } catch (err) {
+        sendJson(res, 500, { error: `Failed to spawn prompt agent: ${err.message}` })
+      }
+      return
+    }
+
+    // POST /terminal/kill — kill a terminal/prompt tmux session
+    if (routePath === '/terminal/kill' && method === 'POST') {
+      const { widgetId: targetWidgetId } = body
+
+      if (!targetWidgetId) {
+        sendJson(res, 400, { error: 'widgetId is required' })
+        return
+      }
+
+      try {
+        const { findTmuxNameForWidget, killSession } = await import('./terminal-registry.js')
+        const { updateAgentStatus, initTerminalConfig } = await import('./terminal-config.js')
+
+        initTerminalConfig(root)
+
+        const tmuxName = findTmuxNameForWidget(targetWidgetId)
+        if (!tmuxName) {
+          sendJson(res, 404, { error: `No active session for widget ${targetWidgetId}` })
+          return
+        }
+
+        // Close any WS connections for this session
+        const { orphanTerminalSession } = await import('./terminal-server.js')
+        orphanTerminalSession(targetWidgetId)
+
+        // Kill the tmux session and clean up registry
+        killSession(tmuxName)
+
+        // Update agent status
+        const pathParts = req.url.split('/')
+        const canvasIdx = pathParts.indexOf('canvas')
+        let branch = 'unknown'
+        try {
+          const { execSync } = await import('node:child_process')
+          branch = execSync('git branch --show-current', { encoding: 'utf8', cwd: root }).trim()
+        } catch {}
+
+        try {
+          updateAgentStatus({ branch, canvasId: 'unknown', widgetId: targetWidgetId, status: 'cancelled', message: 'Cancelled by user' })
+        } catch {}
+
+        // Notify via HMR
+        if (__viteWs) {
+          __viteWs.send({
+            type: 'custom',
+            event: 'storyboard:agent-status',
+            data: { widgetId: targetWidgetId, status: 'cancelled', message: 'Cancelled by user', timestamp: new Date().toISOString() },
+          })
+        }
+
+        sendJson(res, 200, { success: true, killed: tmuxName })
+      } catch (err) {
+        sendJson(res, 500, { error: `Failed to kill session: ${err.message}` })
+      }
+      return
+    }
+
+    // GET /terminal-buffer/:widgetId — read terminal buffer JSON
+    // Accepts optional ?length=N query param to truncate scrollback
+    if (routePath.startsWith('/terminal-buffer/') && method === 'GET') {
+      const widgetId = routePath.slice('/terminal-buffer/'.length).split('?')[0]
+      if (!widgetId || widgetId.includes('..') || widgetId.includes('/')) {
+        sendJson(res, 400, { error: 'Invalid widgetId' })
+        return
+      }
+
+      const urlObj = new URL(req.url, 'http://localhost')
+      const lengthParam = urlObj.searchParams.get('length')
+      const maxLength = lengthParam ? parseInt(lengthParam, 10) : undefined
+
+      try {
+        const { readTerminalBuffer } = await import('./terminal-server.js')
+        const buffer = readTerminalBuffer(widgetId, { maxLength: maxLength || undefined })
+        if (buffer) {
+          sendJson(res, 200, buffer)
+          return
+        }
+        sendJson(res, 404, { error: 'Buffer not found' })
+      } catch (err) {
+        sendJson(res, 500, { error: `Failed to read buffer: ${err.message}` })
+      }
+      return
+    }
+
+    // GET /terminal-snapshot/:widgetId — read terminal snapshot JSON (new + legacy fallback)
+    if (routePath.startsWith('/terminal-snapshot/') && method === 'GET') {
+      const widgetId = routePath.slice('/terminal-snapshot/'.length)
+      if (!widgetId || widgetId.includes('..') || widgetId.includes('/')) {
+        sendJson(res, 400, { error: 'Invalid widgetId' })
+        return
+      }
+
+      try {
+        const { readTerminalSnapshot } = await import('./terminal-server.js')
+
+        // Try new path first
+        const snapshot = readTerminalSnapshot(widgetId)
+        if (snapshot) {
+          sendJson(res, 200, snapshot)
+          return
+        }
+
+        // Legacy fallback: .storyboard/terminal-snapshots/<canvasDir>/<widgetId>.json
+        const snapshotsRoot = path.join(root, '.storyboard', 'terminal-snapshots')
+        if (fs.existsSync(snapshotsRoot)) {
+          const dirs = fs.readdirSync(snapshotsRoot, { withFileTypes: true })
+          for (const d of dirs) {
+            if (!d.isDirectory()) continue
+            const filePath = path.join(snapshotsRoot, d.name, `${widgetId}.json`)
+            if (fs.existsSync(filePath)) {
+              const data = fs.readFileSync(filePath, 'utf8')
+              res.writeHead(200, { 'Content-Type': 'application/json' })
+              res.end(data)
+              return
+            }
+          }
+        }
+        sendJson(res, 404, { error: 'Snapshot not found' })
+      } catch (err) {
+        sendJson(res, 500, { error: `Failed to read snapshot: ${err.message}` })
+      }
+      return
+    }
+
+    // DELETE /delete-canvas — delete a canvas and its directory
+    if (routePath === '/delete-canvas' && method === 'DELETE') {
+      const { name } = body
+      if (!name || typeof name !== 'string') {
+        sendJson(res, 400, { error: 'Canvas name is required' })
+        return
+      }
+
+      const filePath = findCanvasPath(root, name)
+      if (!filePath) {
+        sendJson(res, 404, { error: `Canvas "${name}" not found` })
+        return
+      }
+
+      try {
+        const dir = path.dirname(filePath)
+        const canvasDir = path.join(root, 'src', 'canvas')
+
+        // Delete the canvas file
+        fs.unlinkSync(filePath)
+
+        // If the parent directory is inside src/canvas/ and now empty (or only has .meta.json), remove it
+        if (dir !== canvasDir) {
+          const remaining = fs.readdirSync(dir).filter(f => !f.endsWith('.meta.json'))
+          if (remaining.length === 0) {
+            for (const f of fs.readdirSync(dir)) {
+              fs.unlinkSync(path.join(dir, f))
+            }
+            fs.rmdirSync(dir)
+          }
+        }
+
+        sendJson(res, 200, { success: true, deleted: name })
+      } catch (err) {
+        sendJson(res, 500, { error: `Failed to delete canvas: ${err.message}` })
+      }
+      return
+    }
+
+    // PUT /update-meta — update canvas metadata
+    if (routePath === '/update-meta' && method === 'PUT') {
+      const { name, title, description, author } = body
+      if (!name || typeof name !== 'string') {
+        sendJson(res, 400, { error: 'Canvas name is required' })
+        return
+      }
+
+      const filePath = findCanvasPath(root, name)
+      if (!filePath) {
+        sendJson(res, 404, { error: `Canvas "${name}" not found` })
+        return
+      }
+
+      try {
+        // Try to find and update .meta.json first
+        const dir = path.dirname(filePath)
+        const dirName = path.basename(dir).replace(/\.folder$/, '')
+        const metaPath = path.join(dir, `${dirName}.meta.json`)
+
+        if (fs.existsSync(metaPath)) {
+          const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'))
+          if (title !== undefined) meta.title = title
+          if (description !== undefined) meta.description = description
+          if (author !== undefined) meta.author = author
+          fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2) + '\n', 'utf-8')
+        } else {
+          // Update the canvas JSONL's canvas_created event metadata
+          const text = fs.readFileSync(filePath, 'utf-8')
+          const lines = text.split('\n').filter(Boolean)
+          if (lines.length > 0) {
+            const firstEvent = JSON.parse(lines[0])
+            if (title !== undefined) firstEvent.title = title
+            if (description !== undefined) firstEvent.description = description
+            if (author !== undefined) firstEvent.author = author
+            lines[0] = JSON.stringify(firstEvent)
+            fs.writeFileSync(filePath, lines.join('\n') + '\n', 'utf-8')
+          }
+        }
+
+        // Notify via WebSocket
+        pushCanvasUpdate(name, filePath, __viteWs)
+
+        sendJson(res, 200, { success: true, updated: name })
+      } catch (err) {
+        sendJson(res, 500, { error: `Failed to update canvas metadata: ${err.message}` })
+      }
+      return
+    }
+
     sendJson(res, 404, { error: `Unknown route: ${method} ${routePath}` })
   }
 }