@dfosco/storyboard 0.6.0-beta.1 → 0.6.0-beta.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dfosco/storyboard",
-  "version": "0.6.0-beta.1",
+  "version": "0.6.0-beta.10",
   "type": "module",
   "license": "MIT",
   "description": "Storyboard prototyping framework — core engine, React integration, and canvas",
@@ -21,7 +21,8 @@
     "toolbar.config.json",
     "widgets.config.json",
     "paste.config.json",
-    "commandpalette.config.json"
+    "commandpalette.config.json",
+    "terminal.config.json"
   ],
   "scripts": {
     "build:css": "tailwindcss -i src/core/styles/tailwind.css -o dist/tailwind.css --minify",

package/scaffold/gitignore

@@ -52,8 +52,18 @@ packages/core/dist/storyboard-ui.*
 # Agent Browser
 agent-browser.json
 
-# Selected widgets bridge (real-time canvas selection for Copilot)
-.storyboard
+# Auto-generated scaffold dir (copies of library config defaults — overwritten on every dev-server boot)
+.storyboard/scaffold/
+
+# Real-time canvas selection bridge for Copilot
+.storyboard/.selectedwidgets.json
+
+# Runtime/transient state (per-machine, per-session)
+.storyboard/agent-sessions/
+.storyboard/hot-pool/
+.storyboard/logs/
+.storyboard/terminal-buffers/
+.storyboard/messages/
 
 # Private canvas images (tilde prefix = not committed)
 src/canvas/images/~*

package/scaffold/skills/migrate/SKILL.md

@@ -37,61 +37,81 @@ The storyboard homepage URL changed from `/viewfinder` to `/workspace`. The old
 
 #### 2. Canvas config — terminal + agents + hot pool
 
-Clients on 4.1.x likely have no `canvas` block at all. The full canvas config is required for terminal widgets, agent widgets, and prompt widgets to work on canvases.
+**As of `0.6.0-beta.4`, terminal + agent config has its own dedicated file: `terminal.config.json` at the project root.** The library ships full defaults in `node_modules/@dfosco/storyboard/terminal.config.json` and a copy is auto-scaffolded to `.storyboard/scaffold/terminal.config.json` on every dev-server boot. Most clients won't need any project-level config — the defaults already cover Copilot/Claude/Codex with auto-resume.
 
-**Read the client's `storyboard.config.json`.** If the `canvas` key is missing or incomplete, merge the missing sections. Here is the complete reference config — adapt values to the client's environment:
+**Only create a root `terminal.config.json`** if you want to override specific keys. Leaf-level merge means you set only what you change; everything else inherits the library defaults (so future agents and tweaks reach you automatically). Example minimal override:
 
 ```jsonc
 {
-  "canvas": {
-    // Terminal widget settings (the plain terminal, not agents)
-    "terminal": {
-      "fontSize": 18,
-      "fontFamily": "'SF Mono', 'Menlo', 'Monaco', 'Courier New', monospace",
-      "prompt": "❯ ",
-      "startupCommand": null,
-      "defaultStartupSequence": null,
-      "resizable": true,
-      "defaultWidth": 1000,
-      "defaultHeight": 600
-    },
+  "terminal": {
+    "fontSize": 18,
+    "fontFamily": "'Ghostty', 'SF Mono', monospace"
+  },
+  "agents": {
+    "copilot": {
+      "startupCommand": "copilot --remote --agent terminal-agent"
+    }
+  }
+}
+```
+
+**Legacy back-compat.** Existing clients with `canvas.terminal` and `canvas.agents` blocks under `storyboard.config.json` continue to work — the loader merges them with the new file (with `terminal.config.json` winning on overlap, and a warning logged). New clients should prefer `terminal.config.json` and keep `storyboard.config.json` lean.
+
+**Full reference for what `terminal.config.json` accepts** (don't copy this into a new project unless you actually need to override every key — the library ships these as defaults):
 
-    // Agent widgets — each key becomes an entry in the "Add Agent" menu
-    // Remove any agents the client doesn't have installed
-    "agents": {
-      "copilot": {
-        "label": "Copilot CLI",
-        "default": true,
-        "icon": "primer/copilot",
-        "startupCommand": "copilot --agent terminal-agent",
-        "resumeCommand": "copilot --resume={id} --agent terminal-agent",
-        "sessionIdEnv": "COPILOT_AGENT_SESSION_ID",
-        "postStartup": "/allow-all on",
-        "readinessSignal": "Environment loaded:",
-        "resizable": true
-      },
-      "claude": {
-        "label": "Claude Code",
-        "icon": "claude",
-        "startupCommand": "claude --agent terminal-agent --dangerously-skip-permissions",
-        "resumeCommand": "claude --resume={id} --agent terminal-agent --dangerously-skip-permissions",
-        "resizable": true,
-        "readinessSignal": "bypass permissions"
-      },
-      "codex": {
-        "label": "Codex CLI",
-        "icon": "codex",
-        "startupCommand": "codex --full-auto",
-        "resumeCommand": "codex --resume={id} --ask-for-approval never",
-        "configFiles": [".codex/config.toml"],
-        "resizable": true
-      }
+```jsonc
+{
+  // Terminal widget settings (the plain terminal, not agents)
+  "terminal": {
+    "fontSize": 18,
+    "fontFamily": "'SF Mono', 'Menlo', 'Monaco', 'Courier New', monospace",
+    "prompt": "❯ ",
+    "startupCommand": null,
+    "defaultStartupSequence": null,
+    "resizable": true,
+    "defaultWidth": 1000,
+    "defaultHeight": 600
+  },
+
+  // Agent widgets — each key becomes an entry in the "Add Agent" menu
+  // Remove any agents the client doesn't have installed
+  "agents": {
+    "copilot": {
+      "label": "Copilot CLI",
+      "default": true,
+      "icon": "primer/copilot",
+      "startupCommand": "copilot --agent terminal-agent",
+      "resumeCommand": "copilot --resume={id} --agent terminal-agent",
+      "sessionIdEnv": "COPILOT_AGENT_SESSION_ID",
+      "postStartup": "/allow-all on",
+      "readinessSignal": "Environment loaded:",
+      "resizable": true
+    },
+    "claude": {
+      "label": "Claude Code",
+      "icon": "claude",
+      "startupCommand": "claude --agent terminal-agent --dangerously-skip-permissions",
+      "resumeCommand": "claude --resume {id} --agent terminal-agent --dangerously-skip-permissions",
+      "sessionIdEnv": "CLAUDE_SESSION_ID",
+      "sessionStateGlob": "~/.claude/projects/*/{id}.jsonl",
+      "resizable": true,
+      "readinessSignal": "bypass permissions"
     },
+    "codex": {
+      "label": "Codex CLI",
+      "icon": "codex",
+      "startupCommand": "codex --full-auto",
+      "resumeCommand": "codex resume {id}",
+      "sessionIdEnv": "CODEX_SESSION_ID",
+      "sessionStateGlob": "~/.codex/sessions/**/rollout-*-{id}.jsonl",
+      "configFiles": [".codex/config.toml"],
+      "resizable": true
+    }
+  },
 
-    // Set to true to show agent entries in the canvas "+" add menu
-    // Set to false to only show them in the command palette
-    "showAgentsInAddMenu": false
-  }
+  // Set to true to show agent entries in the canvas "+" add menu
+  // Set to false to only show them in the command palette
+  "showAgentsInAddMenu": false
 }
 ```
 
@@ -116,6 +136,10 @@ Clients on 4.1.x likely have no `canvas` block at all. The full canvas config is
 | `startupCommand` | yes | Shell command to start the agent |
 | `resumeCommand` | no | Full launch template to resume a session, with `{id}` placeholder (e.g. `copilot --resume={id} --agent terminal-agent`). Used both for auto-resume on cold restart and for the interactive "Browse existing sessions" flow. |
 | `sessionIdEnv` | no | Env var exposed in the agent SessionStart hook payload that holds its session id (e.g. `COPILOT_AGENT_SESSION_ID`). When set, widget cold restarts auto-resume the previous session. |
+| `sessionStateDir` | no | Directory where the agent stores per-session state, used to pre-flight `--resume` (e.g. `~/.copilot/session-state`). Pass `null` to skip the fs check (UUID-only validation). |
+| `sessionStateGlob` | no | Glob to validate session existence for agents that store sessions in nested subdirs. Supports `<root>/*/{id}.jsonl` (Claude) and `<root>/**/<name-with-{id}>` (Codex). |
+
+**Codex CLI: one-time hook trust.** Codex requires explicit user trust for non-managed hooks (`Non-managed command hooks must be reviewed and trusted before they run`). After the first dev-server boot, run `codex` interactively in any directory and enter `/hooks`, navigate to SessionStart, and enable the `storyboard-capture` hook. Trust persists in `~/.codex/state_*.sqlite`. Until trusted, Codex agent widgets will launch fresh on restart instead of resuming.
 | `postStartup` | no | Text sent to the agent's stdin after it starts |
 | `readinessSignal` | no | Substring to wait for in output before marking agent as ready |
 | `configFiles` | no | Array of config file paths the agent requires |

package/src/core/canvas/agent-session.js

@@ -11,21 +11,25 @@
  *
  * A watcher on the per-widget capture file persists the captured id onto
  * the widget's terminal config as `lastAgentSessionId`. On the next cold
- * restart, the launch is rewritten to `copilot --resume=<id> --agent ...`,
- * with a pre-flight check that the session-state directory still exists
- * (copilot exits non-interactively when `--resume=<id>` doesn't match an
- * existing session, so we can't rely on `||` shell fallback — we have to
- * pre-validate).
+ * restart, the launch is rewritten to `copilot --resume=<id> --agent ...`
+ * (with a pre-flight check that the on-disk session still exists), and is
+ * shell-chained with a `|| <fresh-startup>` fallback so that if the agent
+ * CLI rejects the id at runtime the widget still ends up with a working
+ * fresh session instead of a dead terminal.
  */
 
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, watch as fsWatch } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, watch as fsWatch, readdirSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 import { homedir } from 'node:os'
+import { execFileSync } from 'node:child_process'
 
 const CAPTURE_DIR = join('.storyboard', 'agent-sessions')
 const COPILOT_USER_HOOKS_DIR = join(homedir(), '.copilot', 'hooks')
 const COPILOT_HOOK_FILENAME = 'storyboard-capture.json'
 const COPILOT_SESSION_STATE_DIR = join(homedir(), '.copilot', 'session-state')
+const CLAUDE_SETTINGS_PATH = join(homedir(), '.claude', 'settings.json')
+const CLAUDE_HOOK_MARKER = 'storyboard-capture'
+const CODEX_HOOKS_PATH = join(homedir(), '.codex', 'hooks.json')
 
 /** Resolve absolute path to the per-widget capture directory under root. */
 function captureDir(root) {
@@ -62,24 +66,11 @@ export function ensureCopilotCaptureHookInstalled() {
 
   const hookPath = join(COPILOT_USER_HOOKS_DIR, COPILOT_HOOK_FILENAME)
 
-  // Single-line bash script. Reads stdin JSON, extracts sessionId via sed
-  // (no jq dependency), writes it to the widget's per-project capture file.
-  const bashScript =
-    'wid="${STORYBOARD_WIDGET_ID}"; ' +
-    'root="${STORYBOARD_PROJECT_ROOT}"; ' +
-    '[ -z "$wid" ] && exit 0; ' +
-    '[ -z "$root" ] && exit 0; ' +
-    'id=$(cat | sed -n \'s/.*"sessionId"[[:space:]]*:[[:space:]]*"\\([^"]*\\)".*/\\1/p\' | head -n1); ' +
-    '[ -z "$id" ] && exit 0; ' +
-    'dir="$root/.storyboard/agent-sessions"; ' +
-    'mkdir -p "$dir" 2>/dev/null; ' +
-    'printf %s "$id" > "$dir/$wid.session-id"'
-
   const hook = {
     version: 1,
     hooks: {
       sessionStart: [
-        { type: 'command', bash: bashScript, timeoutSec: 5 },
+        { type: 'command', bash: buildCaptureBashScript(), timeoutSec: 5 },
       ],
     },
   }
@@ -94,6 +85,125 @@ export function ensureCopilotCaptureHookInstalled() {
   return hookPath
 }
 
+/**
+ * Install (idempotently) a SessionStart hook in `~/.claude/settings.json`
+ * that captures Claude Code session ids the same way the Copilot hook does.
+ *
+ * Claude's hook payload uses `session_id` (snake_case) instead of Copilot's
+ * `sessionId` — our capture script handles both. Claude reads the hook from
+ * `~/.claude/settings.json` and merges it with project / local / managed
+ * settings, so we install user-scope and let Claude do the merging.
+ *
+ * Existing settings are preserved: we read, deep-merge our hook into the
+ * SessionStart array (replacing any prior storyboard hook by `command`
+ * marker), and write back.
+ *
+ * Safe to call on every dev-server boot.
+ */
+export function ensureClaudeCaptureHookInstalled() {
+  let settings = {}
+  try {
+    settings = JSON.parse(readFileSync(CLAUDE_SETTINGS_PATH, 'utf8'))
+  } catch { /* file may not exist or be invalid — start fresh */ }
+
+  if (typeof settings !== 'object' || settings === null) settings = {}
+  if (typeof settings.hooks !== 'object' || settings.hooks === null) settings.hooks = {}
+  if (!Array.isArray(settings.hooks.SessionStart)) settings.hooks.SessionStart = []
+
+  const ourHandler = {
+    type: 'command',
+    command: buildCaptureBashScript(),
+    timeout: 5,
+  }
+  // Claude wraps handlers in a matcher group. Use no matcher (matches all).
+  const ourGroup = { hooks: [ourHandler] }
+
+  // Replace any prior storyboard-capture group; identify by marker substring.
+  const next = settings.hooks.SessionStart.filter((g) => {
+    const handlers = Array.isArray(g?.hooks) ? g.hooks : []
+    return !handlers.some((h) => typeof h?.command === 'string' && h.command.includes(CLAUDE_HOOK_MARKER))
+  })
+  // Tag our handler command with the marker so we can find/replace it later.
+  ourHandler.command = `# ${CLAUDE_HOOK_MARKER}\n${ourHandler.command}`
+  next.push(ourGroup)
+
+  settings.hooks.SessionStart = next
+
+  try { mkdirSync(join(homedir(), '.claude'), { recursive: true }) } catch { /* empty */ }
+  try {
+    writeFileSync(CLAUDE_SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n')
+  } catch { /* best-effort */ }
+  return CLAUDE_SETTINGS_PATH
+}
+
+/**
+ * Install (idempotently) a SessionStart hook for Codex CLI at
+ * `~/.codex/hooks.json` using the same shared capture script.
+ *
+ * Codex's hook format is JSON with PascalCase event names like Claude's
+ * (and uses `session_id` snake_case in the payload, also like Claude).
+ * We own this file end-to-end (Codex merges multiple hook sources, so
+ * other hooks the user has via config.toml or repo-level files keep
+ * working). The marker comment identifies our handler for replace.
+ */
+export function ensureCodexCaptureHookInstalled() {
+  let hooks = { hooks: { SessionStart: [] } }
+  try {
+    const existing = JSON.parse(readFileSync(CODEX_HOOKS_PATH, 'utf8'))
+    if (existing && typeof existing === 'object') hooks = existing
+  } catch { /* file may not exist — start fresh */ }
+
+  if (typeof hooks.hooks !== 'object' || hooks.hooks === null) hooks.hooks = {}
+  if (!Array.isArray(hooks.hooks.SessionStart)) hooks.hooks.SessionStart = []
+
+  const ourHandler = {
+    type: 'command',
+    command: `# ${CLAUDE_HOOK_MARKER}\n${buildCaptureBashScript()}`,
+    timeout: 5,
+  }
+  // Codex matchers for SessionStart: "startup", "resume", "clear" — match all
+  const ourGroup = { matcher: '*', hooks: [ourHandler] }
+
+  hooks.hooks.SessionStart = hooks.hooks.SessionStart.filter((g) => {
+    const handlers = Array.isArray(g?.hooks) ? g.hooks : []
+    return !handlers.some((h) => typeof h?.command === 'string' && h.command.includes(CLAUDE_HOOK_MARKER))
+  })
+  hooks.hooks.SessionStart.push(ourGroup)
+
+  try { mkdirSync(join(homedir(), '.codex'), { recursive: true }) } catch { /* empty */ }
+  try {
+    writeFileSync(CODEX_HOOKS_PATH, JSON.stringify(hooks, null, 2) + '\n')
+  } catch { /* best-effort */ }
+  return CODEX_HOOKS_PATH
+}
+
+/**
+ * Shared capture bash script. Handles both Copilot (`sessionId` camelCase)
+ * and Claude (`session_id` snake_case) payload shapes. Reads
+ * STORYBOARD_WIDGET_ID + STORYBOARD_PROJECT_ROOT from env (exported by
+ * terminal-server into the agent shell). Silently no-ops if either env
+ * var is missing.
+ */
+function buildCaptureBashScript() {
+  return [
+    'wid="${STORYBOARD_WIDGET_ID}"',
+    'root="${STORYBOARD_PROJECT_ROOT}"',
+    '[ -z "$wid" ] && exit 0',
+    '[ -z "$root" ] && exit 0',
+    'payload=$(cat)',
+    'id=$(printf %s "$payload" | sed -n \'s/.*"sessionId"[[:space:]]*:[[:space:]]*"\\([^"]*\\)".*/\\1/p\' | head -n1)',
+    '[ -z "$id" ] && id=$(printf %s "$payload" | sed -n \'s/.*"session_id"[[:space:]]*:[[:space:]]*"\\([^"]*\\)".*/\\1/p\' | head -n1)',
+    'dir="$root/.storyboard/agent-sessions"',
+    'mkdir -p "$dir" 2>/dev/null',
+    // Always touch the readiness marker — sessionStart fires only once
+    // the agent is fully loaded and the prompt input is interactive, so
+    // this is a much more reliable signal than the pre-agent shell echo.
+    'touch "$root/.storyboard/terminals/$wid.ready" 2>/dev/null',
+    '[ -z "$id" ] && exit 0',
+    'printf %s "$id" > "$dir/$wid.session-id"',
+  ].join('; ')
+}
+
 /**
  * Build a resume-aware startup command for an agent.
  *
@@ -114,19 +224,40 @@ export function buildResumeStartupCommand({ startupCommand, sessionId, agentCfg
   const template = agentCfg?.resumeCommand
   if (!template || !template.includes('{id}')) return startupCommand
 
-  return template.replace('{id}', sessionId)
+  const resumeCmd = template.replace('{id}', sessionId)
+
+  // Graceful fallback: if the resume command exits non-zero (e.g. the agent
+  // CLI rejected the id, the on-disk session is corrupt, or the binary
+  // doesn't actually support resume the way we expect), fall through to a
+  // fresh session instead of leaving the widget with a dead terminal.
+  // A clean exit (user `/exit`s) returns 0 and skips the fallback.
+  if (agentCfg?.resumeFallback === false) return resumeCmd
+  const notice = `printf '\\n\\033[33m[storyboard] resume failed; starting fresh session...\\033[0m\\n'`
+  return `${resumeCmd} || { ${notice}; ${startupCommand}; }`
 }
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
 
 /**
- * Decide whether a captured sessionId is still resumable. For copilot, this
- * means the id is a UUID and `~/.copilot/session-state/<id>/` still exists.
- * Other agents can opt out of validation by setting `sessionStateDir` to null.
+ * Decide whether a captured sessionId is still resumable.
+ *
+ * Strategies:
+ *   - `agentCfg.sessionStateDir` → check if `<dir>/<id>` exists (Copilot)
+ *   - `agentCfg.sessionStateGlob` → check if any
+ *     `~/.claude/projects/*‍/<id>.jsonl` exists (Claude)
+ *   - both null → trust the UUID
+ *
+ * Defaults to the Copilot session-state dir when nothing is configured.
  */
 export function isResumableSessionId(sessionId, agentCfg = {}) {
   if (!sessionId) return false
   if (!UUID_RE.test(sessionId)) return false
+
+  // Explicit glob check (Claude-style: <dir>/*/<id>.jsonl)
+  if (agentCfg.sessionStateGlob) {
+    return matchesSessionStateGlob(sessionId, agentCfg.sessionStateGlob)
+  }
+
   const stateDir = agentCfg.sessionStateDir === undefined
     ? COPILOT_SESSION_STATE_DIR
     : agentCfg.sessionStateDir
@@ -134,6 +265,48 @@ export function isResumableSessionId(sessionId, agentCfg = {}) {
   return existsSync(join(stateDir, sessionId))
 }
 
+/**
+ * Check if `<root>/<anySubdir>/<id>.jsonl` exists, where `glob` is a
+ * shorthand string. Supports two forms:
+ *   - `<root>/*` + `/{id}.jsonl` — exactly one subdir level (Claude pattern)
+ *   - `<root>/**` + `/<name-with-{id}>` — recursive find (Codex pattern, where
+ *     sessions are nested under year/month/day and the id is embedded in
+ *     a longer filename like `rollout-<ts>-<id>.jsonl`)
+ */
+function matchesSessionStateGlob(sessionId, glob) {
+  const expanded = glob.replace('~', homedir()).replace(/\{id\}/g, sessionId)
+
+  // Recursive form: root/**/name
+  if (expanded.includes('/**/')) {
+    const [root, namePattern] = expanded.split('/**/')
+    if (!existsSync(root)) return false
+    try {
+      const out = execFileSync('find', [root, '-name', namePattern, '-print', '-quit'], {
+        encoding: 'utf8', timeout: 3000, stdio: ['ignore', 'pipe', 'ignore'],
+      })
+      return out.trim().length > 0
+    } catch { return false }
+  }
+
+  // Single-level form: root/*/suffix
+  const parts = expanded.split('/*/')
+  if (parts.length !== 2) {
+    // Plain path with no wildcard — direct check.
+    return existsSync(expanded)
+  }
+  const [root, suffix] = parts
+  let entries = []
+  try { entries = readdirSync(root) } catch { return false }
+  for (const name of entries) {
+    const full = join(root, name)
+    try {
+      if (!statSync(full).isDirectory()) continue
+    } catch { continue }
+    if (existsSync(join(full, suffix))) return true
+  }
+  return false
+}
+
 /**
  * Watch `captureFile` for the agent's session id and call `onCapture(id)`
  * once it appears or is updated. Unlike the previous one-shot version,

package/src/core/canvas/agent-session.test.js

@@ -39,6 +39,32 @@ describe('agent-session', () => {
       mkdirSync(join(stateDir, id), { recursive: true })
       expect(isResumableSessionId(id, { sessionStateDir: stateDir })).toBe(true)
     })
+
+    it('uses sessionStateGlob to validate per-project session files (Claude shape)', () => {
+      const id = '11111111-2222-4333-8444-555555555555'
+      const { mkdirSync, writeFileSync } = require('node:fs')
+      const projectsDir = join(root, 'projects')
+      mkdirSync(join(projectsDir, '-Users-foo-some-project'), { recursive: true })
+      writeFileSync(join(projectsDir, '-Users-foo-some-project', `${id}.jsonl`), '')
+      expect(isResumableSessionId(id, { sessionStateGlob: `${projectsDir}/*/{id}.jsonl` })).toBe(true)
+      expect(isResumableSessionId(
+        '99999999-2222-4333-8444-555555555555',
+        { sessionStateGlob: `${projectsDir}/*/{id}.jsonl` },
+      )).toBe(false)
+    })
+
+    it('uses recursive ** in sessionStateGlob to validate nested session files (Codex shape)', () => {
+      const id = '22222222-2222-4333-8444-555555555555'
+      const { mkdirSync, writeFileSync } = require('node:fs')
+      const sessionsRoot = join(root, 'sessions')
+      mkdirSync(join(sessionsRoot, '2026', '05', '15'), { recursive: true })
+      writeFileSync(join(sessionsRoot, '2026', '05', '15', `rollout-2026-05-15T10-00-00-${id}.jsonl`), '')
+      expect(isResumableSessionId(id, { sessionStateGlob: `${sessionsRoot}/**/rollout-*-{id}.jsonl` })).toBe(true)
+      expect(isResumableSessionId(
+        '99999999-2222-4333-8444-555555555555',
+        { sessionStateGlob: `${sessionsRoot}/**/rollout-*-{id}.jsonl` },
+      )).toBe(false)
+    })
   })
 
   describe('buildResumeStartupCommand', () => {
@@ -56,13 +82,28 @@ describe('agent-session', () => {
       expect(out).toBe('copilot --agent terminal-agent')
     })
 
-    it('substitutes {id} into resumeCommand when valid', () => {
+    it('substitutes {id} into resumeCommand and chains a fresh-session fallback', () => {
+      const out = buildResumeStartupCommand({
+        startupCommand: 'copilot --agent terminal-agent',
+        sessionId: '11111111-2222-4333-8444-555555555555',
+        agentCfg: {
+          sessionStateDir: null,
+          resumeCommand: 'copilot --resume={id} --agent terminal-agent',
+        },
+      })
+      expect(out).toContain('copilot --resume=11111111-2222-4333-8444-555555555555 --agent terminal-agent')
+      expect(out).toContain('|| {')
+      expect(out).toContain('copilot --agent terminal-agent')
+    })
+
+    it('skips the fallback when resumeFallback: false', () => {
       const out = buildResumeStartupCommand({
         startupCommand: 'copilot --agent terminal-agent',
         sessionId: '11111111-2222-4333-8444-555555555555',
         agentCfg: {
           sessionStateDir: null,
           resumeCommand: 'copilot --resume={id} --agent terminal-agent',
+          resumeFallback: false,
         },
       })
       expect(out).toBe('copilot --resume=11111111-2222-4333-8444-555555555555 --agent terminal-agent')
@@ -78,8 +119,7 @@ describe('agent-session', () => {
     })
   })
 
-  describe('captureFilePath / readCapturedSessionId / clearCaptureFile', () => {
-    it('writes to .storyboard/agent-sessions/<key>.session-id', () => {
+  describe('captureFilePath / readCapturedSessionId / clearCaptureFile', () => {    it('writes to .storyboard/agent-sessions/<key>.session-id', () => {
       const cap = captureFilePath(root, 'agent-foo')
       expect(cap).toBe(join(root, '.storyboard', 'agent-sessions', 'agent-foo.session-id'))
     })

package/src/core/canvas/configReader.js

@@ -0,0 +1,110 @@
+/**
+ * Server-side reader for terminal + agents config.
+ *
+ * Replaces direct `JSON.parse(readFileSync('storyboard.config.json')).canvas.agents`
+ * reads in terminal-server / hot-pool / canvas server / terminal-welcome /
+ * server-plugin so the new `terminal.config.json` (and the library's default
+ * one shipped under `node_modules/@dfosco/storyboard/terminal.config.json`)
+ * is honored everywhere with leaf-level merge.
+ *
+ * Resolution order (lowest → highest priority), all leaf-merged:
+ *   1. Library default `<root>/{packages/storyboard,node_modules/@dfosco/storyboard}/terminal.config.json`
+ *   2. `storyboard.config.json` `canvas.terminal` + `canvas.agents` (legacy)
+ *   3. Root `terminal.config.json`
+ *
+ * Returns `{ terminal, agents, showAgentsInAddMenu }`. Empty objects when
+ * nothing is configured (rather than null) so callers can spread freely.
+ */
+
+import { readFileSync, existsSync } from 'node:fs'
+import { resolve, join } from 'node:path'
+
+/** Same shape as data-plugin's `deepMergeBuild`. */
+function deepMerge(target, source) {
+  if (!source || typeof source !== 'object') return target
+  if (!target || typeof target !== 'object') return source
+  const result = { ...target }
+  for (const key of Object.keys(source)) {
+    const sv = source[key]
+    const tv = target[key]
+    if (sv && typeof sv === 'object' && !Array.isArray(sv) && tv && typeof tv === 'object' && !Array.isArray(tv)) {
+      result[key] = deepMerge(tv, sv)
+    } else {
+      result[key] = sv
+    }
+  }
+  return result
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+function resolveLibTerminalConfig(root) {
+  const candidates = [
+    join(root, 'packages', 'storyboard', 'terminal.config.json'),
+    join(root, 'node_modules', '@dfosco', 'storyboard', 'terminal.config.json'),
+  ]
+  for (const p of candidates) {
+    if (existsSync(p)) {
+      const parsed = readJson(p)
+      if (parsed) return parsed
+    }
+  }
+  return null
+}
+
+/**
+ * Read the merged terminal + agents + hotPool config for a project root.
+ *
+ * @param {string} [root] - Project root, defaults to `process.cwd()`.
+ * @returns {{ terminal: object, agents: object, showAgentsInAddMenu: boolean|undefined, hotPool: object }}
+ */
+export function readTerminalConfigMerged(root = process.cwd()) {
+  const lib = resolveLibTerminalConfig(root) || {}
+  const sb = readJson(resolve(root, 'storyboard.config.json')) || {}
+  const userTerminal = readJson(resolve(root, 'terminal.config.json')) || {}
+
+  const sbCanvas = sb.canvas || {}
+  const sbLayer = {
+    ...(sbCanvas.terminal ? { terminal: sbCanvas.terminal } : {}),
+    ...(sbCanvas.agents ? { agents: sbCanvas.agents } : {}),
+    ...(sbCanvas.showAgentsInAddMenu !== undefined
+      ? { showAgentsInAddMenu: sbCanvas.showAgentsInAddMenu }
+      : {}),
+    ...(sb.hotPool ? { hotPool: sb.hotPool } : {}),
+  }
+
+  const merged = deepMerge(deepMerge(lib, sbLayer), userTerminal)
+  return {
+    terminal: merged.terminal || {},
+    agents: merged.agents || {},
+    showAgentsInAddMenu: merged.showAgentsInAddMenu,
+    hotPool: merged.hotPool || {},
+  }
+}
+
+/**
+ * Convenience: just the agents map.
+ */
+export function readAgentsConfig(root = process.cwd()) {
+  return readTerminalConfigMerged(root).agents
+}
+
+/**
+ * Convenience: just the terminal-widget settings.
+ */
+export function readTerminalSettings(root = process.cwd()) {
+  return readTerminalConfigMerged(root).terminal
+}
+
+/**
+ * Convenience: just the hotPool config.
+ */
+export function readHotPoolConfig(root = process.cwd()) {
+  return readTerminalConfigMerged(root).hotPool
+}