@dfosco/storyboard 0.6.0-beta.2 → 0.6.0-beta.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dfosco/storyboard",
-  "version": "0.6.0-beta.2",
+  "version": "0.6.0-beta.4",
   "type": "module",
   "license": "MIT",
   "description": "Storyboard prototyping framework — core engine, React integration, and canvas",

package/scaffold/skills/migrate/SKILL.md

@@ -84,7 +84,9 @@ Clients on 4.1.x likely have no `canvas` block at all. The full canvas config is
         "label": "Codex CLI",
         "icon": "codex",
         "startupCommand": "codex --full-auto",
-        "resumeCommand": "codex --resume={id} --ask-for-approval never",
+        "resumeCommand": "codex resume {id}",
+        "sessionIdEnv": "CODEX_SESSION_ID",
+        "sessionStateGlob": "~/.codex/sessions/**/rollout-*-{id}.jsonl",
         "configFiles": [".codex/config.toml"],
         "resizable": true
       }
@@ -118,6 +120,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/scaffold/storyboard.config.json

@@ -33,6 +33,39 @@
       "resizable": false,
       "defaultWidth": 800,
       "defaultHeight": 450
+    },
+    "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",
+        "readinessSignal": "bypass permissions",
+        "resizable": true
+      },
+      "codex": {
+        "label": "Codex CLI",
+        "icon": "codex",
+        "startupCommand": "codex --ask-for-approval never",
+        "resumeCommand": "codex resume {id}",
+        "sessionIdEnv": "CODEX_SESSION_ID",
+        "sessionStateGlob": "~/.codex/sessions/**/rollout-*-{id}.jsonl",
+        "configFiles": [".codex/config.toml"],
+        "resizable": true
+      }
     }
   },
   "customerMode": {

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

@@ -21,6 +21,7 @@
 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')
@@ -28,6 +29,7 @@ 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) {
@@ -134,6 +136,47 @@ export function ensureClaudeCaptureHookInstalled() {
   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
@@ -211,14 +254,28 @@ export function isResumableSessionId(sessionId, agentCfg = {}) {
 
 /**
  * Check if `<root>/<anySubdir>/<id>.jsonl` exists, where `glob` is a
- * shorthand string. Currently only supports the Claude pattern
- * `~/.claude/projects/*‍/{id}.jsonl`. The `*` segment is interpreted as
- * any single directory level.
+ * 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}', sessionId)
-  // Find the `*` segment; everything before it is the root, everything
-  // after is the suffix to test inside each subdir.
+  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.

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

@@ -52,6 +52,19 @@ describe('agent-session', () => {
         { 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', () => {

package/src/core/canvas/terminal-server.js

@@ -63,6 +63,7 @@ import {
   captureFilePath,
   ensureCopilotCaptureHookInstalled,
   ensureClaudeCaptureHookInstalled,
+  ensureCodexCaptureHookInstalled,
 } from './agent-session.js'
 
 let pty
@@ -687,11 +688,13 @@ export function setupTerminalServer(httpServer, base = '/', branch = 'unknown',
   initRegistry(root, { gracePeriod: termCfg.orphanGracePeriod })
   initTerminalConfig(root)
 
-  // Install user-level Copilot CLI hook (~/.copilot/hooks/storyboard-capture.json)
-  // and Claude Code hook (~/.claude/settings.json) that capture sessionStart
-  // payloads into per-widget files. Idempotent.
+  // Install user-level Copilot CLI hook (~/.copilot/hooks/storyboard-capture.json),
+  // Claude Code hook (~/.claude/settings.json), and Codex CLI hook
+  // (~/.codex/hooks.json) that capture sessionStart payloads into per-widget
+  // files. All idempotent.
   try { ensureCopilotCaptureHookInstalled() } catch { /* best-effort */ }
   try { ensureClaudeCaptureHookInstalled() } catch { /* best-effort */ }
+  try { ensureCodexCaptureHookInstalled() } catch { /* best-effort */ }
 
   // Best-effort: apply shell-config overrides if a tmux server already exists
   // from a previous dev server run. If no server exists, this fails silently —