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

package/scaffold/skills/design-system-catalog/generate-catalog.sh

@@ -0,0 +1,255 @@
+#!/usr/bin/env bash
+#
+# generate-catalog.sh — Generate a component catalog skill for any design system
+#
+# Usage:
+#   .agents/skills/design-system-catalog/generate-catalog.sh <package-name> [display-name]
+#
+# Examples:
+#   .agents/skills/design-system-catalog/generate-catalog.sh @primer/react "Primer React"
+#   .agents/skills/design-system-catalog/generate-catalog.sh @chakra-ui/react "Chakra UI"
+#   .agents/skills/design-system-catalog/generate-catalog.sh antd "Ant Design"
+
+set -euo pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+
+# Resolve skills base directory — priority: .agents → .github → .claude
+SKILLS_BASE=""
+for candidate in .agents/skills .github/skills .claude/skills; do
+  if [ -d "$REPO_ROOT/$candidate/design-system-catalog" ]; then
+    SKILLS_BASE="$candidate"
+    break
+  fi
+done
+
+if [ -z "$SKILLS_BASE" ]; then
+  echo "Error: design-system-catalog skill not found in .agents/skills, .github/skills, or .claude/skills" >&2
+  exit 1
+fi
+
+SKILL_DIR="$REPO_ROOT/$SKILLS_BASE/design-system-catalog"
+EXTRACTOR="$SKILL_DIR/extract-components.mjs"
+
+PACKAGE_NAME="${1:?Usage: generate-catalog.sh <package-name> [display-name]}"
+DISPLAY_NAME="${2:-}"
+
+# ── Derive names ─────────────────────────────────────────────
+
+# Skill name: strip @, replace / with -, lowercase
+SKILL_NAME="${PACKAGE_NAME#@}"
+SKILL_NAME="${SKILL_NAME////-}"
+SKILL_NAME=$(echo "$SKILL_NAME" | tr '[:upper:]' '[:lower:]')
+CATALOG_SKILL_NAME="${SKILL_NAME}-components-catalog"
+
+# Display name: auto-derive if not provided
+if [ -z "$DISPLAY_NAME" ]; then
+  # @primer/react → Primer React, antd → Antd, @chakra-ui/react → Chakra Ui React
+  DISPLAY_NAME=$(echo "$SKILL_NAME" | sed 's/-/ /g' | awk '{for(i=1;i<=NF;i++) $i=toupper(substr($i,1,1)) tolower(substr($i,2))}1')
+fi
+
+OUTPUT_DIR="$REPO_ROOT/$SKILLS_BASE/$CATALOG_SKILL_NAME"
+OUTPUT_FILE="$OUTPUT_DIR/SKILL.md"
+
+echo "Package:      $PACKAGE_NAME"
+echo "Display name: $DISPLAY_NAME"
+echo "Skill name:   $CATALOG_SKILL_NAME"
+echo "Output dir:   $OUTPUT_DIR"
+echo ""
+
+# ── Validate ─────────────────────────────────────────────────
+
+if [ ! -f "$EXTRACTOR" ]; then
+  echo "Error: extractor not found at $EXTRACTOR" >&2
+  exit 1
+fi
+
+PKG_DIR="$REPO_ROOT/node_modules/${PACKAGE_NAME}"
+if [ ! -d "$PKG_DIR" ]; then
+  echo "Error: $PACKAGE_NAME not installed. Run npm install first." >&2
+  exit 1
+fi
+
+VERSION=$(node -e "console.log(require('$PKG_DIR/package.json').version)" 2>/dev/null || echo "unknown")
+
+# ── Extract components ───────────────────────────────────────
+
+TMP_DIR=$(mktemp -d)
+trap "rm -rf $TMP_DIR" EXIT
+
+echo "Extracting components from $PACKAGE_NAME@$VERSION ..."
+REPO_ROOT="$REPO_ROOT" node "$EXTRACTOR" "$PACKAGE_NAME" > "$TMP_DIR/components.json" 2>"$TMP_DIR/extract.log"
+
+cat "$TMP_DIR/extract.log" >&2
+
+TOTAL=$(node -e "console.log(JSON.parse(require('fs').readFileSync('$TMP_DIR/components.json','utf-8')).totalComponents)")
+
+if [ "$TOTAL" -eq 0 ]; then
+  echo "Error: no components found in $PACKAGE_NAME. Check that the package has TypeScript declarations." >&2
+  exit 1
+fi
+
+echo "Found $TOTAL components."
+
+# ── Format catalog markdown ──────────────────────────────────
+
+COMPONENTS_JSON="$TMP_DIR/components.json" node --input-type=module << 'FORMATTER' > "$TMP_DIR/catalog.md"
+import { readFileSync } from 'fs';
+
+const data = JSON.parse(readFileSync(process.env.COMPONENTS_JSON, 'utf-8'));
+const { packageName, version, components } = data;
+
+// Group components by category
+const groups = {};
+for (const comp of components) {
+  const cat = comp.category || 'Components';
+  if (!groups[cat]) groups[cat] = [];
+  groups[cat].push(comp);
+}
+
+// Sort categories: known categories first, then alphabetical
+const knownOrder = [
+  'Layout', 'Navigation', 'Actions', 'Actions & Menus', 'Forms',
+  'Data Display', 'Feedback', 'Overlays', 'Content', 'Typography',
+  'Utilities', 'General', 'Components',
+];
+const allCategories = Object.keys(groups);
+const sorted = [
+  ...knownOrder.filter(c => allCategories.includes(c)),
+  ...allCategories.filter(c => !knownOrder.includes(c)).sort(),
+];
+
+let md = '';
+md += `## Component Index\n\n`;
+
+let totalCount = 0;
+
+for (const cat of sorted) {
+  const comps = groups[cat];
+  if (!comps || comps.length === 0) continue;
+
+  comps.sort((a, b) => a.name.localeCompare(b.name));
+
+  md += `### ${cat}\n\n`;
+
+  for (const comp of comps) {
+    totalCount++;
+    md += `#### \`${comp.name}\`\n\n`;
+    md += `\`\`\`jsx\nimport { ${comp.name} } from '${comp.importPath}'\n\`\`\`\n\n`;
+
+    if (comp.subComponents.length > 0) {
+      md += '**Sub-components:** ';
+      md += comp.subComponents.map(s => `\`${comp.name}.${s}\``).join(', ');
+      md += '\n\n';
+    }
+
+    if (comp.props.length > 0) {
+      md += '**Props:**\n\n';
+      md += '| Prop | Type |\n';
+      md += '|------|------|\n';
+      for (const prop of comp.props) {
+        const safeType = prop.type.replace(/\|/g, '\\|').replace(/\n/g, ' ');
+        md += `| \`${prop.name}\` | \`${safeType}\` |\n`;
+      }
+      md += '\n';
+    }
+  }
+}
+
+md += '---\n\n';
+md += `_${totalCount} components total from ${packageName}@${version}._\n`;
+
+process.stdout.write(md);
+FORMATTER
+
+# ── Create output skill directory ────────────────────────────
+
+mkdir -p "$OUTPUT_DIR"
+
+# ── Write SKILL.md ───────────────────────────────────────────
+
+cat > "$OUTPUT_FILE" << SKILLEOF
+# ${DISPLAY_NAME} Components Catalog
+
+> Triggered by: ANY code that imports from \`${PACKAGE_NAME}\`, "what ${DISPLAY_NAME} components are available", "${DISPLAY_NAME,,} component list", "${DISPLAY_NAME,,} components", when building UI with ${DISPLAY_NAME}
+
+> Auto-update trigger: When \`package.json\` is modified and \`${PACKAGE_NAME}\` version changes, regenerate this catalog.
+
+## What This Does
+
+Provides a complete catalog of all \`${PACKAGE_NAME}\` components available in this codebase. Each entry includes the component name, import path, sub-components (for compound components), and props with types.
+
+## When This Applies
+
+- Building any new page or component that uses ${DISPLAY_NAME}
+- Deciding which component to use for a UI pattern
+- Looking up props or sub-components for a specific component
+
+## How to Use
+
+1. **Find the right component** — Browse by category or search alphabetically
+2. **Check sub-components** — Compound components list their sub-components (e.g. \`Table.Cell\`)
+3. **Check props** — Each component lists its specific props with types
+4. **Import** — Use the import path shown (always \`${PACKAGE_NAME}\`)
+
+### Regenerating This Catalog
+
+When \`${PACKAGE_NAME}\` is upgraded, regenerate with:
+
+\`\`\`bash
+${SKILLS_BASE}/${CATALOG_SKILL_NAME}/extract-components.sh
+\`\`\`
+
+<!-- CATALOG -->
+<!-- Generated from ${PACKAGE_NAME}@${VERSION} — do not edit manually -->
+<!-- Run ${SKILLS_BASE}/${CATALOG_SKILL_NAME}/extract-components.sh to regenerate -->
+
+---
+
+SKILLEOF
+
+# Append the formatted catalog
+cat "$TMP_DIR/catalog.md" >> "$OUTPUT_FILE"
+
+# ── Write regeneration script ────────────────────────────────
+
+REGEN_SCRIPT="$OUTPUT_DIR/extract-components.sh"
+cat > "$REGEN_SCRIPT" << 'REGENEOF'
+#!/usr/bin/env bash
+#
+# Regenerate the component catalog for PACKAGE_PLACEHOLDER
+#
+# This is a thin wrapper around the shared design-system-catalog extractor.
+# Run this script when the package is upgraded to refresh the catalog.
+
+set -euo pipefail
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+
+GENERATOR=""
+for candidate in .agents/skills .github/skills .claude/skills; do
+  if [ -f "$REPO_ROOT/$candidate/design-system-catalog/generate-catalog.sh" ]; then
+    GENERATOR="$REPO_ROOT/$candidate/design-system-catalog/generate-catalog.sh"
+    break
+  fi
+done
+
+if [ -z "$GENERATOR" ]; then
+  echo "Error: design-system-catalog skill not found in .agents/skills, .github/skills, or .claude/skills" >&2
+  echo "The shared extractor is required to regenerate this catalog." >&2
+  exit 1
+fi
+
+exec "$GENERATOR" "PACKAGE_PLACEHOLDER" "DISPLAY_PLACEHOLDER"
+REGENEOF
+
+# Replace placeholders
+sed -i '' "s|PACKAGE_PLACEHOLDER|${PACKAGE_NAME}|g" "$REGEN_SCRIPT"
+sed -i '' "s|DISPLAY_PLACEHOLDER|${DISPLAY_NAME}|g" "$REGEN_SCRIPT"
+chmod +x "$REGEN_SCRIPT"
+
+echo ""
+echo "✅ Generated skill: $CATALOG_SKILL_NAME"
+echo "   Skill file: $OUTPUT_FILE"
+echo "   Regenerate: $REGEN_SCRIPT"
+echo "   Components: $TOTAL from ${PACKAGE_NAME}@${VERSION}"

package/scaffold/skills/migrate/SKILL.md

@@ -37,63 +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",
-        "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} --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
 }
 ```
 
@@ -118,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/scaffold/terminal-agent.agent.md

@@ -116,11 +116,18 @@ When the user says "your partner", "your buddy", or "connected widget" — they
 - **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
+- **story**: `props.storyId` + `props.exportName` — a SINGLE named export of a story file
+- **component-set**: `props.storyId` — ALL exports of a story file in one grid iframe. **`props.selected` is the export name the user clicked on inside the grid** — treat it as "the variant the user is focused on right now" and scope edits/changes to that export when ambiguous.
 - **link-preview**: `props.url` — external reference
 - **prototype**: `props.src` — prototype path
 - **terminal** / **agent** / **prompt**: another terminal, agent, or prompt you can message (see Step 7)
 
+> **Creating widgets:** Never invent a `type` string. The authoritative list lives in `.agents/data/widget-types.json` (or invoke the **canvas** skill). When the user asks for "variants", "a component set", "a showcase", or anything implying multiple exports of the same story file, use a SINGLE `component-set` widget — NOT N `story` widgets.
+
+> **Scoping inside a `component-set`:** if a connected `component-set` widget has a non-empty `props.selected`, the user has explicitly chosen a variant inside that set. When they say "this variant", "the selected one", "this chart", etc., interpret it as the export named by `props.selected` and modify only that export's code path unless they say otherwise.
+
+
+
 Interpret the user's prompt in light of these connected widgets.
 
 ### Resolving widget references across the connection graph

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

@@ -11,16 +11,17 @@
  *
  * 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, 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
@@ -150,9 +193,13 @@ function buildCaptureBashScript() {
     '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)',
-    '[ -z "$id" ] && exit 0',
     '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('; ')
 }
@@ -171,13 +218,38 @@ function buildCaptureBashScript() {
  * keeping it in one field avoids confusion about which args go where.
  */
 export function buildResumeStartupCommand({ startupCommand, sessionId, agentCfg }) {
-  if (!startupCommand || !sessionId) return startupCommand
-  if (!isResumableSessionId(sessionId, agentCfg)) return startupCommand
+  if (!startupCommand) return startupCommand
+
+  const notice = `printf '\\n\\033[33m[storyboard] resume failed; starting fresh session...\\033[0m\\n'`
+  const lastCmd = agentCfg?.resumeLastCommand
 
-  const template = agentCfg?.resumeCommand
-  if (!template || !template.includes('{id}')) return startupCommand
+  // Chain: stored-id resume → resumeLastCommand (if any) → fresh startupCommand.
+  // Each step's non-zero exit cascades to the next via shell `||`. Note: if a
+  // resume hangs (vs. exits non-zero), the chain won't progress — users
+  // should use the widget's restart button. We deliberately don't wrap in a
+  // timeout to avoid killing slow-starting agents on flaky networks.
+  const wrapFallback = (cmd) => {
+    if (agentCfg?.resumeFallback === false) return cmd
+    const last = lastCmd ? `${lastCmd} || { ${notice}; ${startupCommand}; }` : `${notice}; ${startupCommand}`
+    return `${cmd} || { ${last}; }`
+  }
 
-  return template.replace('{id}', sessionId)
+  // Primary: per-widget captured sessionId → `resumeCommand` with {id}.
+  if (sessionId && UUID_RE.test(sessionId)) {
+    const template = agentCfg?.resumeCommand
+    if (template && template.includes('{id}')) {
+      return wrapFallback(template.replace('{id}', sessionId))
+    }
+  }
+
+  // No id stored — try resumeLastCommand (e.g. `--continue` / `resume --last`),
+  // falling through to fresh startupCommand if it exits non-zero.
+  if (lastCmd) {
+    if (agentCfg?.resumeFallback === false) return lastCmd
+    return `${lastCmd} || { ${notice}; ${startupCommand}; }`
+  }
+
+  return 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
@@ -211,14 +283,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', () => {
@@ -69,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')