@dfosco/storyboard-core 4.2.0-alpha.6 → 4.2.0-alpha.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dfosco/storyboard-core",
-  "version": "4.2.0-alpha.6",
+  "version": "4.2.0-alpha.7",
   "type": "module",
   "license": "MIT",
   "bin": {

package/scaffold/agents/terminal-agent.agent.md

@@ -0,0 +1,144 @@
+---
+name: terminal-agent
+description: "Canvas-aware terminal agent that reads connected widget context and signals completion via the storyboard API."
+tools:
+  - read
+  - edit
+  - shell
+  - search
+---
+
+# Terminal Agent Context
+
+Before processing ANY user prompt, read the terminal config file for this session.
+
+## Step 1: Read terminal config
+
+Your widget ID is available via `$STORYBOARD_WIDGET_ID`. Use it to read your config directly:
+```bash
+cat .storyboard/terminals/${STORYBOARD_WIDGET_ID}.json
+```
+
+If the env var is empty, source it from the terminal env file first:
+```bash
+# Find the env file for this tmux session
+ENV_FILE=$(ls -t .storyboard/terminals/*.env 2>/dev/null | head -1)
+if [ -n "$ENV_FILE" ]; then source "$ENV_FILE"; fi
+cat .storyboard/terminals/${STORYBOARD_WIDGET_ID}.json
+```
+
+As a last resort, list all configs and pick the most recent non-deleted one with `connectedWidgets`:
+```bash
+cat .storyboard/terminals/*.json
+```
+
+The config file contains everything you need — no additional API calls required:
+
+```json
+{
+  "widgetId": "terminal-abc123",
+  "canvasId": "storyboarding/my-canvas",
+  "branch": "4.2.0--terminal-agents",
+  "worktree": "4.2.0--terminal-agents",
+  "devDomain": "storyboard-core",
+  "serverUrl": "http://localhost:1269",
+  "workingDirectory": "/path/to/worktree",
+  "connectedWidgets": [
+    {
+      "id": "sticky-def456",
+      "type": "sticky-note",
+      "props": { "text": "Build a login form", "color": "yellow" }
+    },
+    {
+      "id": "markdown-ghi789",
+      "type": "markdown",
+      "props": { "content": "# Requirements\n- Email + password\n- OAuth support" }
+    }
+  ]
+}
+```
+
+## Step 2: Use connected widget context
+
+The `connectedWidgets` array contains the FULL props of every widget connected to this terminal. This is your highest priority context:
+
+- **sticky-note**: `props.text` — instructions, notes, or requirements
+- **markdown**: `props.content` — documentation, specs, or prose
+- **image**: `props.src` — image filename at `assets/canvas/images/{props.src}`
+- **story**: `props.storyId` + `props.exportName` — component to work with
+- **link-preview**: `props.url` — external reference
+- **prototype**: `props.src` — prototype path
+
+Interpret the user's prompt in light of these connected widgets.
+
+## Step 3: Prefer CLI commands for canvas operations
+
+**Always prefer `npx storyboard` CLI commands over HTTP API calls.** CLI commands run directly in the worktree and resolve the dev server automatically — no port numbers or URLs needed.
+
+### Reading canvas state
+```bash
+npx storyboard canvas read <canvas-name> --json
+npx storyboard canvas read <canvas-name> --id <widget-id> --json
+```
+
+### Updating a widget
+```bash
+# Update text on a sticky note
+npx storyboard canvas update <widget-id> --canvas <canvas-name> --text "New text"
+
+# Update markdown content
+npx storyboard canvas update <widget-id> --canvas <canvas-name> --content "# New heading"
+
+# Update arbitrary props
+npx storyboard canvas update <widget-id> --canvas <canvas-name> --props '{"key":"value"}'
+
+# Move a widget
+npx storyboard canvas update <widget-id> --canvas <canvas-name> --x 100 --y 200
+
+# Shorthand flags: --text, --content, --src, --url, --color
+```
+
+### Adding a widget
+```bash
+npx storyboard canvas add sticky-note --canvas <canvas-name> --props '{"text":"Hello"}'
+npx storyboard canvas add markdown --canvas <canvas-name> --x 100 --y 200
+```
+
+**Why CLI over API:** The CLI resolves the correct dev server port automatically via the Caddy proxy or ports.json. You never need to know the port number. All commands work from any worktree directory.
+
+## Step 4: Signal completion
+
+When your task is complete:
+```bash
+npx storyboard agent signal --status done --message "Brief summary"
+```
+
+On failure:
+```bash
+npx storyboard agent signal --status error --message "What went wrong"
+```
+
+**IMPORTANT:**
+- NEVER write directly to `.canvas.jsonl` files — use the canvas CLI or server API
+- **Prefer CLI commands** (`npx storyboard canvas ...`) over direct HTTP calls — they resolve ports automatically
+- Only fall back to HTTP API (`{serverUrl}/_storyboard/canvas/`) if the CLI doesn't support the operation
+- Environment variables `$STORYBOARD_WIDGET_ID`, `$STORYBOARD_CANVAS_ID`, `$STORYBOARD_BRANCH`, `$STORYBOARD_SERVER_URL` are also available in the shell
+
+## HTTP API Reference (fallback only)
+
+If the CLI fails, use these endpoints. The `serverUrl` is in your terminal config or `$STORYBOARD_SERVER_URL`.
+
+### Safe: Update a single widget (PATCH)
+```bash
+curl -s -X PATCH "${STORYBOARD_SERVER_URL}/_storyboard/canvas/widget" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"<canvasId>","widgetId":"<widgetId>","props":{"text":"new value"}}'
+```
+
+### Safe: Read canvas state (GET)
+```bash
+curl -s "${STORYBOARD_SERVER_URL}/_storyboard/canvas/<canvasId>"
+```
+
+### ⚠️ NEVER use `PUT /_storyboard/canvas/update` with a `widgets` array
+That endpoint **replaces ALL widgets** in the canvas. Sending one widget = deleting everything else.

package/src/canvas/terminal-config.js

@@ -15,7 +15,8 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync, symlink
 import { join, dirname } from 'node:path'
 import { createHash } from 'node:crypto'
 import { execSync } from 'node:child_process'
-import { getPort, detectWorktreeName } from '../worktree/port.js'
+import { findByWorktree } from '../worktree/serverRegistry.js'
+import { detectWorktreeName } from '../worktree/port.js'
 
 const TERMINALS_DIR = '.storyboard/terminals'
 
@@ -70,7 +71,7 @@ function atomicWrite(filePath, data) {
  * Write or update a terminal config file.
  * Called when a terminal widget is created or reconnected.
  */
-export function writeTerminalConfig({ branch, canvasId, widgetId, canvasFile = null }) {
+export function writeTerminalConfig({ branch, canvasId, widgetId, canvasFile = null, serverUrl = null }) {
   const fp = configPath(branch, canvasId, widgetId)
   const dir = dirname(fp)
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
@@ -82,9 +83,16 @@ export function writeTerminalConfig({ branch, canvasId, widgetId, canvasFile = n
 
   const worktree = getWorktreeName()
   const devDomain = readDevDomain()
-  let serverPort = 1234
-  try { serverPort = getPort(detectWorktreeName()) } catch {}
-  const serverUrl = `http://localhost:${serverPort}`
+
+  // Resolve server URL: use passed value, or query server registry, or default
+  if (!serverUrl) {
+    try {
+      const name = detectWorktreeName()
+      const servers = findByWorktree(name)
+      if (servers.length > 0) serverUrl = `http://localhost:${servers[0].port}`
+    } catch {}
+  }
+  if (!serverUrl) serverUrl = 'http://localhost:1234'
 
   const config = {
     ...existing,

package/src/canvas/terminal-server.js

@@ -46,7 +46,8 @@ import {
   writeTerminalConfig as writeTermConfig,
   initTerminalConfig,
 } from './terminal-config.js'
-import { getPort, detectWorktreeName } from '../worktree/port.js'
+import { findByWorktree } from '../worktree/serverRegistry.js'
+import { detectWorktreeName } from '../worktree/port.js'
 
 let pty
 try {
@@ -86,6 +87,9 @@ const wsConnections = new Map()
 /** Branch name for this worktree, set during setup */
 let currentBranch = 'unknown'
 
+/** Actual server port, resolved from httpServer at setup time */
+let actualServerPort = null
+
 /** Check if a tmux session with the given name exists */
 function tmuxSessionExists(name) {
   try {
@@ -151,6 +155,12 @@ export function setupTerminalServer(httpServer, base = '/', branch = 'unknown')
 
   currentBranch = branch
 
+  // Capture the actual port from the running HTTP server
+  try {
+    const addr = httpServer.address()
+    if (addr && addr.port) actualServerPort = addr.port
+  } catch {}
+
   // Initialize registry and terminal config
   const root = process.cwd()
   const termCfg = readTerminalConfig()
@@ -197,7 +207,7 @@ function handleConnection(ws, widgetId, canvasId, prettyName) {
   const { entry, conflict } = registerSession({ branch, canvasId, widgetId, prettyName })
 
   // Write terminal config for agent context
-  writeTermConfig({ branch, canvasId, widgetId })
+  writeTermConfig({ branch, canvasId, widgetId, serverUrl })
 
   // Close any existing WS for this session (one viewer at a time)
   const existingWs = wsConnections.get(tmuxName)
@@ -226,9 +236,19 @@ function handleConnection(ws, widgetId, canvasId, prettyName) {
     writeFileSync(join(zdotdir, '.zshrc'), `export PS1='${prompt.replace(/'/g, "'\\''")}'\nunset RPS1\n`)
   } catch { /* best effort */ }
 
-  // Derive server URL for agents to call back
-  let serverPort = '1234'
-  try { serverPort = String(getPort(detectWorktreeName())) } catch {}
+  // Resolve server URL deterministically:
+  // 1. Use the actual port from httpServer (set at setup time)
+  // 2. Fall back to server registry (tracks running dev servers)
+  // 3. Last resort: default port 1234
+  let serverPort = actualServerPort
+  if (!serverPort) {
+    try {
+      const name = detectWorktreeName()
+      const servers = findByWorktree(name)
+      if (servers.length > 0) serverPort = servers[0].port
+    } catch {}
+  }
+  if (!serverPort) serverPort = 1234
   const serverUrl = `http://localhost:${serverPort}`
 
   const env = {

package/src/cli/exit.js

@@ -1,38 +1,37 @@
 /**
- * storyboard exit — Stop the Caddy proxy and all running dev servers.
+ * storyboard exit — Stop all running dev servers and the Caddy proxy.
  */
 
 import * as p from '@clack/prompts'
-import { execSync } from 'child_process'
+import { list, unregister } from '../worktree/serverRegistry.js'
+import { isCaddyRunning, stopCaddy } from './proxy.js'
 
 p.intro('storyboard exit')
 
-// 1. Stop all Vite dev servers started by storyboard
-try {
-  const psOutput = execSync('ps aux', { encoding: 'utf8' })
-  const vitePids = psOutput
-    .split('\n')
-    .filter((line) => line.includes('vite') && line.includes('VITE_BASE_PATH'))
-    .map((line) => line.trim().split(/\s+/)[1])
-    .filter(Boolean)
-
-  if (vitePids.length > 0) {
-    for (const pid of vitePids) {
-      try { process.kill(Number(pid), 'SIGTERM') } catch { /* already dead */ }
-    }
-    p.log.success(`Stopped ${vitePids.length} dev server${vitePids.length > 1 ? 's' : ''}`)
-  } else {
-    p.log.info('No dev servers running')
+// 1. Stop all registered dev servers
+const servers = list()
+if (servers.length > 0) {
+  let stopped = 0
+  for (const s of servers) {
+    try {
+      process.kill(s.pid, 'SIGTERM')
+      stopped++
+    } catch { /* already dead */ }
+    unregister(s.id)
   }
-} catch {
+  p.log.success(`Stopped ${stopped} dev server${stopped !== 1 ? 's' : ''}`)
+} else {
   p.log.info('No dev servers running')
 }
 
-// 2. Stop Caddy proxy
-try {
-  execSync('sudo caddy stop >/dev/null 2>&1', { stdio: ['inherit', 'pipe', 'pipe'] })
-  p.log.success('Proxy stopped')
-} catch {
+// 2. Stop Caddy proxy via admin API (no sudo needed)
+if (isCaddyRunning()) {
+  if (stopCaddy()) {
+    p.log.success('Proxy stopped')
+  } else {
+    p.log.warning('Failed to stop proxy via admin API')
+  }
+} else {
   p.log.info('Proxy was not running')
 }
 

package/src/cli/index.js

@@ -53,6 +53,10 @@ function helpScreen(version) {
     `  ${bold(cyan('Development'))}`,
     cmd('dev', 'Start Vite dev server + update proxy'),
     cmd('dev [branch]', 'Start dev for a specific worktree/branch'),
+    cmd('server list', 'List running dev servers'),
+    cmd('server start [wt]', 'Start dev server for a worktree'),
+    cmd('server stop <wt|ID>', 'Stop a dev server'),
+    cmd('server stop-proxy', 'Stop Caddy proxy (no sudo)'),
     cmd('code [branch]', 'Open a worktree in VS Code'),
     cmd('exit', 'Stop all dev servers and proxy'),
     '',

package/src/cli/proxy.js

@@ -222,6 +222,15 @@ export function startCaddy(caddyfilePath) {
   }
 }
 
+export function stopCaddy() {
+  try {
+    execSync('curl -sf -X POST http://localhost:2019/stop', { timeout: 5000, stdio: 'ignore' })
+    return true
+  } catch {
+    return false
+  }
+}
+
 // When run directly as `storyboard proxy` (not imported by setup.js)
 const isDirectRun = process.argv[2] === 'proxy'
 if (isDirectRun) {

package/src/cli/server.js

@@ -1,35 +1,76 @@
 /**
- * storyboard server [branch] — Start the persistent Storyboard dev server.
- *
- * Manages Vite child processes and serves the /_storyboard/ API.
- * If a branch is given, also starts Vite for that branch immediately.
+ * storyboard server — Dev server lifecycle management.
  *
  * Usage:
- *   storyboard server              # start server, detect branch from cwd
- *   storyboard server main         # start server + dev for main
- *   storyboard server my-feature   # start server + dev for my-feature
+ *   storyboard server              List running dev servers
+ *   storyboard server list         List running dev servers
+ *   storyboard server start [wt]   Start the persistent server + Vite for a worktree
+ *   storyboard server stop <id>    Stop a dev server by worktree name or ID
+ *   storyboard server stop-proxy   Stop the Caddy proxy (no sudo required)
  */
 
 import * as p from '@clack/prompts'
 import { startServer, SERVER_PORT, spawnViteForBranch } from '../server/index.js'
 import { parseFlags } from './flags.js'
-import { readDevDomain, generateCaddyfile, generateRouteConfig, upsertCaddyRoute, isCaddyRunning } from './proxy.js'
-import { detectWorktreeName, getPort } from '../worktree/port.js'
+import { readDevDomain, generateCaddyfile, generateRouteConfig, upsertCaddyRoute, isCaddyRunning, stopCaddy } from './proxy.js'
+import { detectWorktreeName, getPort, repoRoot } from '../worktree/port.js'
+import {
+  list,
+  findByWorktree,
+  findById,
+  unregister,
+  prune,
+} from '../worktree/serverRegistry.js'
 
 const flagSchema = {
   port: { type: 'number', description: 'Server port (default: 4100)' },
+  background: { type: 'boolean', default: false, description: 'Run in background (--bg alias)' },
+  bg: { type: 'boolean', default: false, description: 'Run in background' },
+  multiple: { type: 'boolean', default: false, description: 'Allow multiple servers per worktree' },
 }
 
-async function main() {
-  const { flags, positional } = parseFlags(process.argv.slice(3), flagSchema)
-  const port = flags.port || SERVER_PORT
-  const branchArg = positional[0] || undefined
+// ─── Commands ────────────────────────────────────────────
 
-  p.intro('storyboard server')
+function serverList() {
+  const servers = list()
+  if (servers.length === 0) {
+    p.log.info('No dev servers running.')
+    return
+  }
 
   const devDomain = readDevDomain()
 
-  // Register server itself with Caddy so it's reachable at the dev domain
+  p.log.info('Running dev servers:\n')
+  for (const s of servers) {
+    const isMain = s.worktree === 'main'
+    const basePath = isMain ? '/' : `/branch--${s.worktree}/`
+    const proxyUrl = `http://${devDomain}${basePath}`
+    const bg = s.background ? ' (bg)' : ''
+    console.log(`  ${s.id}  ${s.worktree.padEnd(32)}  :${String(s.port).padEnd(5)}  PID ${String(s.pid).padEnd(7)}  ${proxyUrl}${bg}`)
+  }
+  console.log()
+}
+
+async function serverStart(branchArg, flags) {
+  const { background, bg, multiple } = flags
+  const isBackground = background || bg
+  const worktreeName = branchArg || detectWorktreeName()
+
+  // Check for duplicate worktree servers
+  if (!multiple) {
+    const existing = findByWorktree(worktreeName)
+    if (existing.length > 0) {
+      p.log.error(`A dev server is already running for "${worktreeName}" (ID: ${existing[0].id}, PID: ${existing[0].pid}).`)
+      p.log.info(`To stop it:  npx storyboard server stop ${existing[0].id}`)
+      p.log.info(`To allow multiple:  npx storyboard server start ${worktreeName} --multiple`)
+      process.exit(1)
+    }
+  }
+
+  const devDomain = readDevDomain()
+  const port = flags.port || SERVER_PORT
+
+  // Register server itself with Caddy
   try {
     const serverRoute = generateRouteConfig({ __server__: port })
     if (isCaddyRunning()) {
@@ -39,31 +80,112 @@ async function main() {
 
   const server = startServer(port)
 
-  // Determine initial branch to start
-  const initialBranch = branchArg || detectWorktreeName()
-  const isMain = initialBranch === 'main'
-  const basePath = isMain ? '/' : `/branch--${initialBranch}/`
+  const isMain = worktreeName === 'main'
+  const basePath = isMain ? '/' : `/branch--${worktreeName}/`
   const proxyUrl = `http://${devDomain}${basePath}`
 
-  p.log.step(`Starting dev session for ${initialBranch}...`)
+  p.log.step(`Starting dev session for ${worktreeName}...`)
 
   try {
-    const entry = spawnViteForBranch(initialBranch)
-
-    // Wait for ready
+    const entry = spawnViteForBranch(worktreeName)
     const { waitForPort } = await import('../server/index.js')
     const ready = await waitForPort(entry.port)
 
     if (ready) {
-      p.log.success(proxyUrl)
+      p.log.success(`[${entry.serverId}] ${proxyUrl}`)
     } else {
       p.log.warning(`Vite started but may not be ready yet — check ${proxyUrl}`)
     }
   } catch (err) {
-    p.log.error(`Failed to start dev for ${initialBranch}: ${err.message}`)
+    p.log.error(`Failed to start dev for ${worktreeName}: ${err.message}`)
   }
 
   p.outro('Server running')
 }
 
+function serverStop(target) {
+  if (!target) {
+    p.log.error('Usage: storyboard server stop <worktree|ID>')
+    process.exit(1)
+  }
+
+  // Try by ID first
+  let entry = findById(target)
+
+  // Then by worktree name
+  if (!entry) {
+    const matches = findByWorktree(target)
+    if (matches.length === 0) {
+      p.log.error(`No server found for "${target}".`)
+      p.log.info('Run `npx storyboard server list` to see running servers.')
+      process.exit(1)
+    }
+    if (matches.length > 1) {
+      p.log.error(`Multiple servers running for worktree "${target}":`)
+      for (const s of matches) {
+        console.log(`  ${s.id}  PID: ${s.pid}  Port: ${s.port}`)
+      }
+      p.log.info('Specify an ID: npx storyboard server stop <ID>')
+      process.exit(1)
+    }
+    entry = matches[0]
+  }
+
+  try {
+    process.kill(entry.pid, 'SIGTERM')
+    p.log.success(`Stopped server ${entry.id} (PID: ${entry.pid}, worktree: "${entry.worktree}")`)
+  } catch (err) {
+    if (err.code === 'ESRCH') {
+      p.log.info(`Server ${entry.id} (PID: ${entry.pid}) was already dead.`)
+    } else {
+      p.log.error(`Failed to kill PID ${entry.pid}: ${err.message}`)
+    }
+  }
+
+  unregister(entry.id)
+}
+
+function serverStopProxy() {
+  if (!isCaddyRunning()) {
+    p.log.info('Caddy proxy is not running.')
+    return
+  }
+
+  if (stopCaddy()) {
+    p.log.success('Caddy proxy stopped.')
+  } else {
+    p.log.error('Failed to stop Caddy proxy.')
+    process.exit(1)
+  }
+}
+
+// ─── Dispatch ────────────────────────────────────────────
+
+async function main() {
+  const { flags, positional } = parseFlags(process.argv.slice(3), flagSchema)
+  const subcommand = positional[0]
+
+  p.intro('storyboard server')
+
+  switch (subcommand) {
+    case undefined:
+    case 'list':
+      serverList()
+      break
+    case 'start':
+      await serverStart(positional[1], flags)
+      break
+    case 'stop':
+      serverStop(positional[1])
+      break
+    case 'stop-proxy':
+      serverStopProxy()
+      break
+    default:
+      // Legacy behavior: treat argument as branch name (storyboard server <branch>)
+      await serverStart(subcommand, flags)
+      break
+  }
+}
+
 main()

package/src/cli/setup.js

@@ -188,7 +188,7 @@ if (isInstalled('code')) {
 
 // 7. Asset directories
 {
-  const dirs = ['assets/canvas/images', '.storyboard']
+  const dirs = ['assets/canvas/images', '.storyboard', '.storyboard/terminals']
   for (const dir of dirs) {
     if (!existsSync(dir)) {
       try { mkdirSync(dir, { recursive: true }) } catch { /* ignore */ }
@@ -211,6 +211,30 @@ if (isInstalled('code')) {
   p.log.success('Canvas asset directories ready')
 }
 
+// 7b. Copilot agents
+{
+  const agentsDir = '.github/agents'
+  if (!existsSync(agentsDir)) {
+    try { mkdirSync(agentsDir, { recursive: true }) } catch { /* ignore */ }
+  }
+
+  const scaffoldAgents = path.resolve(import.meta.dirname, '..', '..', 'scaffold', 'agents')
+  if (existsSync(scaffoldAgents)) {
+    try {
+      const agentFiles = execSync(`ls "${scaffoldAgents}"`, { encoding: 'utf8' }).trim().split('\n').filter(Boolean)
+      for (const file of agentFiles) {
+        const dest = path.join(agentsDir, file)
+        if (!existsSync(dest)) {
+          run(`cp "${path.join(scaffoldAgents, file)}" "${dest}"`)
+        }
+      }
+      if (agentFiles.length > 0) {
+        p.log.success('Copilot agents scaffolded (.github/agents/)')
+      }
+    } catch { /* ignore */ }
+  }
+}
+
 // 8. Proxy
 if (isCaddyInstalled()) {
   const proxySpin = p.spinner()

package/src/server/index.js

@@ -19,6 +19,7 @@ import { resolve, join, dirname } from 'node:path'
 import { getPort, portsFilePath, repoRoot, worktreeDir, listWorktrees } from '../worktree/port.js'
 import { generateCaddyfile, generateRouteConfig, upsertCaddyRoute, isCaddyRunning, reloadCaddy, readDevDomain } from '../cli/proxy.js'
 import { compactAll } from '../canvas/compact.js'
+import { register, unregister, generateId } from '../worktree/serverRegistry.js'
 
 const SERVER_PORT_BASE = 4100
 
@@ -117,9 +118,12 @@ function spawnVite(branch) {
         stdio: ['ignore', 'pipe', 'pipe'],
       })
 
-  const entry = { child, port, status: 'starting', cwd, branch }
+  const entry = { child, port, status: 'starting', cwd, branch, serverId: generateId() }
   processes.set(branch, entry)
 
+  // Register in persistent server registry
+  register({ id: entry.serverId, worktree: branch, pid: child.pid, port, background: true })
+
   // Detect ready state from stdout
   child.stdout.on('data', (data) => {
     const text = data.toString()
@@ -138,6 +142,7 @@ function spawnVite(branch) {
   child.on('exit', (code) => {
     entry.status = 'stopped'
     processes.delete(branch)
+    unregister(entry.serverId)
   })
 
   return entry

package/src/worktree/serverRegistry.js

@@ -0,0 +1,120 @@
+/**
+ * Server Registry — tracks running dev servers in .storyboard/servers.json.
+ *
+ * Each server gets a unique hex ID. The registry is pruned on every read
+ * to remove entries whose PIDs are no longer alive.
+ */
+
+import { randomBytes } from 'crypto'
+import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from 'fs'
+import { join, dirname } from 'path'
+import { repoRoot } from './port.js'
+
+/**
+ * Absolute path to .storyboard/servers.json.
+ */
+export function registryPath(cwd) {
+  return join(repoRoot(cwd), '.storyboard', 'servers.json')
+}
+
+/**
+ * Generate a short unique hex ID (6 chars).
+ */
+export function generateId() {
+  return randomBytes(3).toString('hex')
+}
+
+/**
+ * Check whether a PID is alive.
+ */
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Read the registry file. Returns an object keyed by server ID.
+ */
+function readRegistry(cwd) {
+  const file = registryPath(cwd)
+  if (!existsSync(file)) return {}
+  try {
+    const data = JSON.parse(readFileSync(file, 'utf8'))
+    return data.servers || {}
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * Write the registry atomically (write tmp then rename).
+ */
+function writeRegistry(servers, cwd) {
+  const file = registryPath(cwd)
+  const dir = dirname(file)
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true })
+  const tmp = file + '.tmp'
+  writeFileSync(tmp, JSON.stringify({ servers }, null, 2) + '\n')
+  renameSync(tmp, file)
+}
+
+/**
+ * Remove entries whose PIDs are dead.
+ * @returns {object} pruned servers map
+ */
+export function prune(cwd) {
+  const servers = readRegistry(cwd)
+  const alive = {}
+  for (const [id, entry] of Object.entries(servers)) {
+    if (isAlive(entry.pid)) {
+      alive[id] = entry
+    }
+  }
+  writeRegistry(alive, cwd)
+  return alive
+}
+
+/**
+ * Register a new server entry.
+ */
+export function register({ id, worktree, pid, port, background = false }, cwd) {
+  const servers = prune(cwd)
+  servers[id] = { id, worktree, pid, port, background, startedAt: new Date().toISOString() }
+  writeRegistry(servers, cwd)
+  return servers[id]
+}
+
+/**
+ * Unregister a server by ID.
+ */
+export function unregister(id, cwd) {
+  const servers = readRegistry(cwd)
+  delete servers[id]
+  writeRegistry(servers, cwd)
+}
+
+/**
+ * List all live servers (prunes dead ones first).
+ */
+export function list(cwd) {
+  return Object.values(prune(cwd))
+}
+
+/**
+ * Find servers running for a given worktree name.
+ */
+export function findByWorktree(name, cwd) {
+  return list(cwd).filter((s) => s.worktree === name)
+}
+
+/**
+ * Find a server by its unique ID.
+ */
+export function findById(id, cwd) {
+  const servers = prune(cwd)
+  return servers[id] || null
+}