claude-code-session-manager 0.100.0 → 0.101.0

package/src/main/lib/projectHomeAdminRoutes.cjs

@@ -1,14 +1,22 @@
 /**
- * projectHomeAdminRoutes.cjs — the single admin route behind the
- * `project_home_write` MCP tool: POST /admin/project-home/write {cwd, html}
- * writes one self-contained HTML document to
- * `session-manager-operations/project-pages/home.html` (owner: project-home,
- * see opsOwnership.cjs). Registered against the same injected
- * localAdminHttp.cjs transport as prdAdminRoutes.cjs.
+ * projectHomeAdminRoutes.cjs — the two admin routes behind the
+ * project_home_write MCP tool and its demo-video sibling:
+ *   POST /admin/project-home/write              {cwd, html} -> project-pages/home.html
+ *   POST /admin/project-home/demo-video/write   {cwd, html} -> project-pages/demo-video/index.html
+ * both owned by writer 'project-home' (see opsOwnership.cjs). Registered
+ * against the same injected localAdminHttp.cjs transport as
+ * prdAdminRoutes.cjs.
  *
  * "Self-contained" is enforced here, not trusted: the document must not
  * reference any remote resource (`<script src>`, `<link href=http*>`,
  * remote `@import` / `url(http*)`), so opening it never causes network egress.
+ *
+ * The demo-video document runs inline JavaScript (the home page does not), so
+ * it additionally rejects network-capable APIs (fetch, WebSocket, dynamic
+ * import, …) and has a Content-Security-Policy meta stamped into <head>
+ * before it is written — the real network fence, since the viewer renders it
+ * via smfile:// in a sandboxed iframe that sends no CSP header itself. The
+ * regex checks below are defence in depth, not the control.
  */
 'use strict';
 
@@ -21,8 +29,9 @@ const config = require('../config.cjs');
 const { schemas } = require('../ipcSchemas.cjs');
 
 const MAX_HTML_BYTES = 1024 * 1024;
+const MAX_DEMO_VIDEO_BYTES = 2 * 1024 * 1024;
 
-// Each detector is a linear regex scan; the input is capped at 1MB first.
+// Each detector is a linear regex scan; the input is capped first.
 const REMOTE_REFERENCE_CHECKS = [
   { re: /<script\b[^>]*\bsrc\s*=/i, message: '<script src> is not allowed — inline all scripts' },
   { re: /<link\b[^>]*\bhref\s*=\s*["']?\s*(?:https?:)?\/\//i, message: '<link href="http(s)://…"> is not allowed — inline all styles' },
@@ -30,6 +39,43 @@ const REMOTE_REFERENCE_CHECKS = [
   { re: /url\(\s*["']?\s*(?:https?:)?\/\//i, message: 'url(http(s)://…) is not allowed — embed assets as data: URIs' },
 ];
 
+// Demo-video documents run inline JS; these reject the network-capable
+// surface a self-contained, CSP-fenced document must never reach for.
+const NETWORK_CHECKS = [
+  { re: /\bfetch\s*\(/i, message: 'fetch(...) is not allowed' },
+  { re: /\bXMLHttpRequest\b/i, message: 'XMLHttpRequest is not allowed' },
+  { re: /\bWebSocket\b/i, message: 'WebSocket is not allowed' },
+  { re: /\bEventSource\b/i, message: 'EventSource is not allowed' },
+  { re: /\bsendBeacon\b/i, message: 'sendBeacon is not allowed' },
+  { re: /\bimport\s*\(/i, message: 'import(...) is not allowed' },
+  { re: /\bimportScripts\b/i, message: 'importScripts is not allowed' },
+  { re: /<iframe\b/i, message: '<iframe> is not allowed' },
+  { re: /<object\b/i, message: '<object> is not allowed' },
+  { re: /<embed\b/i, message: '<embed> is not allowed' },
+  { re: /\bwindow\.open\b/i, message: 'window.open is not allowed' },
+  { re: /\b(?:src|href)\s*=\s*["']?\s*(?:https?:)?\/\//i, message: 'src=/href= pointing at http(s): or // is not allowed' },
+  { re: /["'`](?:fetch|XMLHttpRequest|WebSocket|EventSource|sendBeacon|open|importScripts)["'`]/i, message: 'computed/bracket access to a network API (e.g. window["fetch"]) is not allowed' },
+  { re: /\bWorker\s*\(/i, message: 'Worker(...) is not allowed' },
+  { re: /\bSharedWorker\b/i, message: 'SharedWorker is not allowed' },
+  { re: /\bserviceWorker\b/i, message: 'serviceWorker is not allowed' },
+  { re: /rel\s*=\s*["']?\s*(?:prefetch|preconnect|dns-prefetch|preload)/i, message: 'rel="prefetch|preconnect|dns-prefetch|preload" is not allowed' },
+  { re: /\beval\s*\(/i, message: 'eval(...) is not allowed' },
+  { re: /\bFunction\s*\(/i, message: 'Function(...) is not allowed' },
+  { re: /<base\b/i, message: '<base> is not allowed' },
+  { re: /<form\b/i, message: '<form> is not allowed' },
+  { re: /http-equiv\s*=\s*["']?refresh/i, message: 'meta refresh is not allowed' },
+  { re: /\blocation\s*(?:\.\s*(?:href|assign|replace)\b|=[^=])/i, message: 'location.href/assign/replace/= navigation is not allowed' },
+  { re: /\bdocument\.location\b/i, message: 'document.location is not allowed' },
+  { re: /\b(?:top|parent)\./i, message: 'top./parent. property access is not allowed' },
+  { re: /<a\b[^>]*\bhref\s*=\s*["']?\s*(?:https?:|\/\/|javascript:)/i, message: '<a href="http(s):|//|javascript:…"> is not allowed' },
+];
+
+const DURATION_META_RE = /<meta\b[^>]*\bname\s*=\s*["']sm-demo-duration["'][^>]*\bcontent\s*=\s*["'](\d+)["'][^>]*>/i;
+const MIN_DEMO_DURATION_S = 5;
+const MAX_DEMO_DURATION_S = 30;
+
+const DEMO_VIDEO_CSP = '<meta http-equiv="Content-Security-Policy" content="default-src \'none\'; script-src \'unsafe-inline\'; style-src \'unsafe-inline\'; img-src data: blob:; media-src data: blob:; font-src data:; connect-src \'none\'">';
+
 /** -> null when `html` is acceptable, else a human-readable rejection reason. */
 function validateHomeHtml(html) {
   if (typeof html !== 'string' || html.trim().length === 0) return 'html must be a non-empty string';
@@ -40,6 +86,42 @@ function validateHomeHtml(html) {
   return null;
 }
 
+/** -> null when `html` is acceptable, else a human-readable rejection reason. */
+function validateDemoVideoHtml(html) {
+  if (typeof html !== 'string' || html.trim().length === 0) return 'html must be a non-empty string';
+  if (Buffer.byteLength(html, 'utf8') > MAX_DEMO_VIDEO_BYTES) return `html exceeds the ${MAX_DEMO_VIDEO_BYTES}-byte limit`;
+  for (const { re, message } of REMOTE_REFERENCE_CHECKS) {
+    if (re.test(html)) return `html must be self-contained: ${message}`;
+  }
+  for (const { re, message } of NETWORK_CHECKS) {
+    if (re.test(html)) return `html must not be network-capable: ${message}`;
+  }
+  const match = html.match(DURATION_META_RE);
+  if (!match) {
+    return 'html must declare <meta name="sm-demo-duration" content="N"> with '
+      + `${MIN_DEMO_DURATION_S} <= N <= ${MAX_DEMO_DURATION_S}`;
+  }
+  const duration = Number(match[1]);
+  if (!Number.isFinite(duration) || duration < MIN_DEMO_DURATION_S || duration > MAX_DEMO_DURATION_S) {
+    return `sm-demo-duration must be between ${MIN_DEMO_DURATION_S} and ${MAX_DEMO_DURATION_S}, got ${match[1]}`;
+  }
+  return null;
+}
+
+/**
+ * Strips any existing CSP meta and a leading doctype, then returns the CSP
+ * as the very first element after a fresh `<!DOCTYPE html>` — a position no
+ * decoy `<head` text, HTML comment, or string literal in the document can
+ * influence. The HTML parser folds a <meta> emitted right after the doctype
+ * into the implicitly-created <head>, and a later <html>/<head> start tag is
+ * merged/ignored, so the CSP still applies to the whole document.
+ */
+function injectCsp(html) {
+  const withoutCsp = html.replace(/<meta\b[^>]*\bhttp-equiv\s*=\s*["']Content-Security-Policy["'][^>]*>\s*/gi, '');
+  const withoutDoctype = withoutCsp.replace(/^\s*<!DOCTYPE\b[^>]*>\s*/i, '');
+  return `<!DOCTYPE html>${DEMO_VIDEO_CSP}${withoutDoctype}`;
+}
+
 /** Same definition crossProjectFeedback.cjs uses for "is this a Session
  * Manager project": it already has an operations root. */
 function isSessionManagerProject(cwd) {
@@ -79,16 +161,20 @@ function resolveCwd(rawCwd) {
   return { ok: true, cwd: realCwd };
 }
 
-function registerAdminRoute(adminHttp) {
-  // POST /admin/project-home/write {cwd, html}
-  adminHttp.registerRoute('POST', '/admin/project-home/write', async (req, res) => {
-    // Allow headroom over MAX_HTML_BYTES for JSON escaping; the html byte
-    // limit itself is enforced by validateHomeHtml below.
+/**
+ * Builds a POST handler shared by both routes: read+parse the body, validate
+ * against `schema`, resolve cwd, run `validate(html)`, optionally `transform`
+ * the html (CSP injection), then write it atomically as writer 'project-home'.
+ */
+function makeWriteHandler({ schema, maxBytes, validate, transform, targetPath }) {
+  return async (req, res) => {
+    // Allow headroom over maxBytes for JSON escaping; the html byte limit
+    // itself is enforced by `validate` below.
     let raw;
     try {
-      raw = await readBody(req, MAX_HTML_BYTES * 2 + 4096);
+      raw = await readBody(req, maxBytes * 2 + 4096);
     } catch (e) {
-      sendJson(res, 400, { ok: false, error: `request body rejected: ${e?.message ?? 'unreadable'} (html limit is ${MAX_HTML_BYTES} bytes)` });
+      sendJson(res, 400, { ok: false, error: `request body rejected: ${e?.message ?? 'unreadable'} (html limit is ${maxBytes} bytes)` });
       return;
     }
     let body;
@@ -100,7 +186,7 @@ function registerAdminRoute(adminHttp) {
     }
     let input;
     try {
-      input = schemas.projectHomeAdminWriteBody.parse(body);
+      input = schema.parse(body);
     } catch (e) {
       sendJson(res, 400, { ok: false, error: 'invalid payload', details: e?.issues ?? e?.message });
       return;
@@ -110,7 +196,7 @@ function registerAdminRoute(adminHttp) {
       sendJson(res, resolved.status, { ok: false, error: resolved.error });
       return;
     }
-    const rejection = validateHomeHtml(input.html);
+    const rejection = validate(input.html);
     if (rejection) {
       sendJson(res, 400, { ok: false, error: rejection });
       return;
@@ -118,14 +204,43 @@ function registerAdminRoute(adminHttp) {
     // Only a route that is actually about to write widens config.cjs's
     // write boundary to this project root.
     config.addAllowedRoot(resolved.cwd);
+    const finalHtml = transform ? transform(input.html) : input.html;
     try {
-      const homePath = opsPath(resolved.cwd, 'project-pages', 'home.html');
-      await config.writeTextAtomic(homePath, input.html, { writer: 'project-home' });
-      sendJson(res, 200, { ok: true, path: homePath, bytes: Buffer.byteLength(input.html, 'utf8') });
+      const abs = targetPath(resolved.cwd);
+      await fs.promises.mkdir(path.dirname(abs), { recursive: true });
+      await config.writeTextAtomic(abs, finalHtml, { writer: 'project-home' });
+      sendJson(res, 200, { ok: true, path: abs, bytes: Buffer.byteLength(finalHtml, 'utf8') });
     } catch (e) {
       sendJson(res, 500, { ok: false, error: e?.message ?? 'write failed' });
     }
-  });
+  };
+}
+
+function registerAdminRoute(adminHttp) {
+  // POST /admin/project-home/write {cwd, html}
+  adminHttp.registerRoute('POST', '/admin/project-home/write', makeWriteHandler({
+    schema: schemas.projectHomeAdminWriteBody,
+    maxBytes: MAX_HTML_BYTES,
+    validate: validateHomeHtml,
+    targetPath: (cwd) => opsPath(cwd, 'project-pages', 'home.html'),
+  }));
+
+  // POST /admin/project-home/demo-video/write {cwd, html}
+  adminHttp.registerRoute('POST', '/admin/project-home/demo-video/write', makeWriteHandler({
+    schema: schemas.projectDemoVideoAdminWriteBody,
+    maxBytes: MAX_DEMO_VIDEO_BYTES,
+    validate: validateDemoVideoHtml,
+    transform: injectCsp,
+    targetPath: (cwd) => opsPath(cwd, 'project-pages', 'demo-video', 'index.html'),
+  }));
 }
 
-module.exports = { registerAdminRoute, validateHomeHtml, MAX_HTML_BYTES };
+module.exports = {
+  registerAdminRoute,
+  validateHomeHtml,
+  validateDemoVideoHtml,
+  injectCsp,
+  DEMO_VIDEO_CSP,
+  MAX_HTML_BYTES,
+  MAX_DEMO_VIDEO_BYTES,
+};

package/src/main/lib/shippedPersonaSeeds.cjs

@@ -39,6 +39,18 @@ const SHIPPED_PERSONA_SEEDS = deepFreeze({
         tools: "Read, Grep, Glob, Bash, Edit, Write",
       },
     },
+    {
+      commit: "767c3b8e",
+      bodySha256: "40a4d41445e7fdb128f4f1d8d3eef88b857ca466726b3719b36cb69933f09168",
+      fm: {
+        description: "The primary Actor for an Epic's whole interactive conversation — owns overall plan and decomposition, clarifies scope, searches before building, decomposes work into scheduled PRDs via /develop, tracks them to completion, and verifies before calling anything done. Never implements a PRD itself — that's dev-lead's job, one PRD at a time, headless. Task-type framing is the Epic's Mission tag's job, not this persona's.",
+        model: "opus",
+        effort: "medium",
+        tags: "feature, bug, discussion",
+        title: "Engineering — Architect",
+        tools: "Read, Grep, Glob, Bash, Edit, Write",
+      },
+    },
   ],
   "dev-lead": [
     {
@@ -101,6 +113,17 @@ const SHIPPED_PERSONA_SEEDS = deepFreeze({
         tools: "Read, Grep, Glob, Bash, Edit, Write",
       },
     },
+    {
+      commit: "767c3b8e",
+      bodySha256: "91232cfd7ce5fb1dc608ff639a07dcb1c5c13c22502ae4790f51707f498ec917",
+      fm: {
+        description: "Executes exactly one already-scoped PRD at a time, headless, start to finish — reads the PRD's Goal/Acceptance Criteria/Implementation notes and standards.md, implements it, verifies against its own AC, and reports. Has no visibility into the overall plan — that's architect's job. This is the default persona a scheduled PRD runs as: the scheduler resolves a PRD's `agentType` frontmatter field (default `dev-lead`) to this file and launches the headless executor AS this persona via `--append-system-prompt`.",
+        model: "sonnet",
+        effort: "medium",
+        title: "Engineering — Software Engineer",
+        tools: "Read, Grep, Glob, Bash, Edit, Write",
+      },
+    },
   ],
   "project-home-builder": [
     {
@@ -121,6 +144,17 @@ const SHIPPED_PERSONA_SEEDS = deepFreeze({
         tools: "Read, Grep, Glob, Bash, Write, Edit",
       },
     },
+    {
+      commit: "e2cdd120",
+      bodySha256: "8cef2256f31d1d166a305923388d1d0d2f4f099275df24d869decc35a6cb11bb",
+      fm: {
+        description: "Reads a project and writes ONE self-contained overview page (home.html) for its Project Home tab, then saves it with a single project_home_write call.",
+        tools: "Read, Grep, Glob, Bash, Write, Edit",
+        title: "Project Home — Builder",
+        model: "sonnet",
+        effort: "medium",
+      },
+    },
   ],
   "validator": [
     {
@@ -174,6 +208,19 @@ const SHIPPED_PERSONA_SEEDS = deepFreeze({
       },
     },
   ],
+  "demo-video-builder": [
+    {
+      commit: "b4f4f84b",
+      bodySha256: "4bc6279a4553889f3996c4eb95803a9b38191a959f512b47ee9168b85e49b889",
+      fm: {
+        description: "30-second self-contained HTML/JS demo video for Project Home, saved via project_demo_video_write.",
+        tools: "Read, Grep, Glob, Bash, Write, Edit",
+        title: "Project Home — Demo Video",
+        model: "sonnet",
+        effort: "medium",
+      },
+    },
+  ],
 });
 
 module.exports = { SHIPPED_PERSONA_SEEDS };

package/src/main/lib/smfileHeaders.cjs

@@ -0,0 +1,66 @@
+'use strict';
+
+const DEMO_VIDEO_CSP_HEADER = [
+  "default-src 'none'",
+  "script-src 'unsafe-inline'",
+  "style-src 'unsafe-inline'",
+  'img-src data: blob:',
+  'media-src data: blob:',
+  "font-src data:",
+  "connect-src 'none'",
+  "frame-src 'none'",
+  "worker-src 'none'",
+  "form-action 'none'",
+  "base-uri 'none'",
+].join('; ');
+
+const DEMO_VIDEO_PATH_MARKER = '/session-manager-operations/project-pages/demo-video/';
+
+/**
+ * Response headers for a file served over the smfile:// protocol. A file
+ * under the demo-video project-pages folder gets a CSP response header —
+ * document content (a decoy <head>, HTML comments) cannot override this,
+ * unlike the meta-tag CSP the demo-video HTML ships inline.
+ * @param {string} realPath
+ * @param {string} contentType
+ */
+function smfileResponseHeaders(realPath, contentType) {
+  const normalised = String(realPath).replace(/\\/g, '/');
+  const headers = { 'content-type': contentType };
+  if (normalised.includes(DEMO_VIDEO_PATH_MARKER)) {
+    headers['content-security-policy'] = DEMO_VIDEO_CSP_HEADER;
+  }
+  return headers;
+}
+
+/**
+ * Guards against a demo-video document exfiltrating data by navigating its
+ * own sandboxed iframe (meta refresh, `location.href = 'https://…'`), which
+ * the CSP response header does not govern — `frame-src`/`connect-src` don't
+ * stop a top-level navigation of the subframe itself.
+ * @param {{ isMainFrame: boolean, currentUrl: string, targetUrl: string }} params
+ * @returns {boolean}
+ */
+function shouldBlockFrameNavigation({ isMainFrame, currentUrl, targetUrl }) {
+  if (isMainFrame) return false;
+  if (typeof currentUrl !== 'string' || !currentUrl.startsWith('smfile:')) return false;
+
+  let pathname;
+  try {
+    // Same normalisation as smfileResponseHeaders below: on Windows the
+    // absolute path (and therefore the smfile:// URL built from it) uses
+    // backslashes, which the forward-slash DEMO_VIDEO_PATH_MARKER would
+    // otherwise never match — silently disabling this guard on win32.
+    pathname = decodeURIComponent(new URL(currentUrl).pathname).replace(/\\/g, '/');
+  } catch {
+    return false;
+  }
+  if (!pathname.includes(DEMO_VIDEO_PATH_MARKER)) return false;
+
+  if (typeof targetUrl !== 'string') return false;
+  if (targetUrl.startsWith('smfile:')) return false;
+  if (targetUrl === 'about:blank' || targetUrl === 'about:srcdoc') return false;
+  return true;
+}
+
+module.exports = { DEMO_VIDEO_CSP_HEADER, smfileResponseHeaders, shouldBlockFrameNavigation };

package/src/main/projectPages.cjs

@@ -1,12 +1,15 @@
 'use strict';
 
 /**
- * projectPages.cjs — read-only backend for Project Home. The whole feature is
- * ONE self-contained HTML file, `session-manager-operations/project-pages/
- * home.html`, written by the `project_home_write` admin route
- * (lib/projectHomeAdminRoutes.cjs). This module only reads it: get() plus a
- * refcounted per-cwd watcher that pushes `project-pages:changed`. It never
- * writes content (watch()'s mkdir creates an empty directory only).
+ * projectPages.cjs — read-only backend for Project Home. Project Home has two
+ * self-contained generated artifacts under
+ * `session-manager-operations/project-pages/`: `home.html` (written by the
+ * `project_home_write` admin route) and `demo-video/index.html` (written by
+ * the `project_demo_video_write` admin route) — both in
+ * lib/projectHomeAdminRoutes.cjs. This module only reads them: get() returns
+ * home.html's content plus the demo video's { path, mtimeMs }, and a
+ * refcounted per-cwd watcher pushes `project-pages:changed` for either. It
+ * never writes content (watch()'s mkdir creates an empty directory only).
  */
 
 const { ipcMain } = require('electron');
@@ -26,6 +29,22 @@ function homePath(cwd) {
   return opsPath(cwd, 'project-pages', 'home.html');
 }
 
+function demoVideoPath(cwd) {
+  return opsPath(cwd, 'project-pages', 'demo-video', 'index.html');
+}
+
+/** -> { path: string, mtimeMs: number } | null */
+async function getDemoVideo(realCwd) {
+  const file = demoVideoPath(realCwd);
+  try {
+    const stat = await fs.promises.stat(file);
+    return { path: file, mtimeMs: stat.mtimeMs };
+  } catch (e) {
+    if (e.code === 'ENOENT') return null;
+    throw e;
+  }
+}
+
 /**
  * Resolve `cwd`'s home.html path, treating the opsOwnership "ephemeral cwd"
  * throw (a tmpdir/linked-worktree project root) as "no path available"
@@ -40,14 +59,15 @@ function tryHomePath(realCwd) {
   }
 }
 
-/** -> { html: string|null, mtimeMs: number|null } */
+/** -> { html: string|null, mtimeMs: number|null, demoVideo: {path, mtimeMs}|null } */
 async function get({ cwd }) {
   const realCwd = config.validatePath(cwd);
   const { file, ephemeral } = tryHomePath(realCwd);
-  if (ephemeral) return { html: null, mtimeMs: null };
+  if (ephemeral) return { html: null, mtimeMs: null, demoVideo: null };
   const res = await config.readText(file);
-  if (!res.exists) return { html: null, mtimeMs: null };
-  return { html: res.text, mtimeMs: res.mtimeMs };
+  const demoVideo = await getDemoVideo(realCwd);
+  if (!res.exists) return { html: null, mtimeMs: null, demoVideo };
+  return { html: res.text, mtimeMs: res.mtimeMs, demoVideo };
 }
 
 // ─── Push channel ─────────────────────────────────────────────────────────
@@ -90,21 +110,31 @@ async function watchOutput(cwd) {
   const dir = path.dirname(file);
   fs.mkdirSync(dir, { recursive: true });
 
+  const demoVideoFile = demoVideoPath(realCwd);
   const push = async (changedPath) => {
-    if (changedPath && path.resolve(changedPath) !== path.resolve(file)) return; // only home.html
+    // Only home.html or demo-video/index.html — ignore every other sibling file.
+    if (changedPath) {
+      const resolved = path.resolve(changedPath);
+      if (resolved !== path.resolve(file) && resolved !== path.resolve(demoVideoFile)) return;
+    }
     let result;
     try {
       result = await get({ cwd: realCwd });
     } catch {
       return; // best-effort; the renderer keeps its last-known output
     }
-    sendIfAlive(mainWindow, 'project-pages:changed', { cwd: realCwd, html: result.html, mtimeMs: result.mtimeMs });
+    sendIfAlive(mainWindow, 'project-pages:changed', {
+      cwd: realCwd,
+      html: result.html,
+      mtimeMs: result.mtimeMs,
+      demoVideo: result.demoVideo,
+    });
   };
 
   const watcher = chokidar.watch(dir, {
     ignoreInitial: true,
     persistent: true,
-    depth: 0,
+    depth: 1,
     // Same 50ms/25ms shape config.cjs's generic watcher uses.
     awaitWriteFinish: { stabilityThreshold: 50, pollInterval: 25 },
   });

package/src/main/seedAgentPersonas.cjs

@@ -80,7 +80,7 @@ const { writeJsonSync, writeTextAtomic, validatePath, validateWrite } = require(
 const { splitFrontmatter } = require('./lib/prdFrontmatter.cjs');
 const { SHIPPED_PERSONA_SEEDS } = require('./lib/shippedPersonaSeeds.cjs');
 
-const PERSONAS = ['architect', 'dev-lead', 'project-home-builder', 'validator'];
+const PERSONAS = ['architect', 'dev-lead', 'project-home-builder', 'validator', 'demo-video-builder'];
 // What `{ done: true }` (the pre-seeded-set marker format) meant: only these two personas existed
 // in PERSONAS at the time. Fixed, not derived from the current PERSONAS array above — otherwise
 // every future persona added to PERSONAS would retroactively count as already delivered to a

package/src/preload/api.d.ts

@@ -242,6 +242,12 @@ export interface Macro {
   tag: AgentPersonaTag;
   prompt: string;
   projects: string[];
+  /** Which strip shows this macro. Defaults to `'sessions'` when absent. */
+  surface: 'sessions' | 'project-home';
+  /** True for a seeded, machine-authored macro (e.g. the built-in Project Home actions). */
+  builtin?: boolean;
+  /** Bumped by the seed when a builtin macro's definition changes, to reseed it. */
+  builtinVersion?: number;
   createdAt: string;
   updatedAt: string;
 }
@@ -254,6 +260,7 @@ export interface MacroSaveInput {
   tag: AgentPersonaTag;
   prompt: string;
   projects?: string[];
+  surface?: 'sessions' | 'project-home';
 }
 
 /** One global `~/.claude/agents/<name>.md` persona, per the Agent Library nav page. */
@@ -1325,6 +1332,8 @@ export interface ProjectPagesGetResult {
   html: string | null;
   /** home.html's mtime, or null when `html` is null. */
   mtimeMs: number | null;
+  /** project-pages/demo-video/index.html's absolute path + mtime, or null when it does not exist. Load it via smfile:// — never pass its HTML across IPC. */
+  demoVideo: { path: string; mtimeMs: number } | null;
 }
 
 // ────────────────────────────────────────────── Per-subagent memory
@@ -1479,6 +1488,9 @@ export interface ChatRunToolUseEvent {
   label: string;
   /** Populated only for Edit/Write tool_use blocks; undefined for every other kind. */
   diff?: { filePath: string; oldText?: string; newText?: string };
+  /** The tool_use input's command/description/pattern/file_path, whichever applies —
+   *  empty string when the tool took none of those. */
+  detail?: string;
 }
 
 export interface ChatRunNeedsInputEvent {

package/src/seed/agents/architect.md

@@ -3,9 +3,10 @@ name: architect
 description: The primary Actor for an Epic's whole interactive conversation — owns overall plan and decomposition, clarifies scope, searches before building, decomposes work into scheduled PRDs via /develop, tracks them to completion, and verifies before calling anything done. Never implements a PRD itself — that's dev-lead's job, one PRD at a time, headless. Task-type framing is the Epic's Mission tag's job, not this persona's.
 tools: Read, Grep, Glob, Bash, Edit, Write
 model: opus
+effort: medium
 tags: feature, bug, discussion
 title: Engineering — Architect
-seedVersion: 1
+seedVersion: 2
 ---
 
 You are the architect. You are the one Actor a human talks to for the whole life of an Epic's

package/src/seed/agents/demo-video-builder.md

@@ -0,0 +1,84 @@
+---
+name: demo-video-builder
+description: 30-second self-contained HTML/JS demo video for Project Home, saved via project_demo_video_write.
+tools: Read, Grep, Glob, Bash, Write, Edit
+title: 'Project Home — Demo Video'
+model: sonnet
+effort: medium
+seedVersion: 1
+---
+
+You are the demo-video-builder. You make a 30-second animated demo that shows someone what this
+project is for and what it does best. It plays inside Project Home and may later be
+screen-recorded, so it must be deterministic — the same frame at the same time, every run.
+
+<context>
+You run inside a Session Manager Epic for the target project. The HTML you produce is rendered
+inside a sandboxed frame in that project's Project Home tab, triggered by a human pressing the
+Demo Video button — never automatically and never in a loop — so this run is the one chance to
+get it right before a person watches it.
+</context>
+
+<grounding_rules>
+Ground every goal and feature you show in something you read: the project's manifest
+(`package.json`, `pyproject.toml`, or equivalent), its README or docs, its source tree, or its
+git log. If you can't point to where a claim came from, leave it out rather than guess — a
+shorter video is far better than one with an invented feature. Never invent metrics, logos,
+testimonials, or UI screenshots. Where the project already describes itself well (a tagline, a
+feature list, a mission statement), reuse its own wording instead of paraphrasing.
+</grounding_rules>
+
+<storyboard>
+Before writing any code, write a 5-7 scene storyboard with timings that sum to exactly 30
+seconds:
+
+1. Title card — the project's name and a one-line purpose.
+2. The problem it solves.
+3-6. One scene per key feature (3 to 4 features), each a short caption plus a simple animated
+   diagram or kinetic type built from shapes, SVG, or canvas — never a fake screenshot.
+7. Closing card — the project's name and how to get started (the real command).
+
+Keep every caption at 12 words or fewer, and hold each scene on screen long enough to read twice.
+</storyboard>
+
+<output_contract>
+Produce exactly one complete HTML document:
+- All CSS and JS live inline, in a single `<style>` block and a single `<script>` block — no
+  `<script src="...">`, no `<link href="http...">`, no `@import`, and no `url(http...)`.
+- `<head>` includes `<meta name="sm-demo-duration" content="30">`.
+- A 16:9 stage, 1280x720 logical pixels, scaled to fit the viewport with letterboxing.
+- A single clock drives every scene via `requestAnimationFrame` — no per-scene timers of their
+  own, so seeking is exact.
+- Expose `window.smDemo = { duration: 30, seek(t), play(), pause() }`, where `seek(t)` renders
+  the exact frame for time `t` in seconds, independent of whatever played before it.
+- Autoplays once on load; shows play/pause, restart, and a progress bar.
+- No audio.
+- No network: no `fetch`, `XMLHttpRequest`, `WebSocket`, `import()`, or `<iframe>`. No external
+  fonts or images — system font stack only, and any images as `data:` URIs.
+- Respects `prefers-reduced-motion` by rendering the scenes as a static, steppable storyboard
+  instead of animating them.
+- Under 2 MB total.
+- A light/dark neutral palette with sufficient contrast in both.
+</output_contract>
+
+<process>
+1. Read, with a bounded pass: the manifest, the README or top-level docs index, the top-level
+   directory tree, and `git log --oneline -30` for a sense of recent direction. Stop once you
+   have enough to describe the project honestly.
+2. Write the claims list: for every goal or feature you plan to show, note the source you read
+   it from. Drop anything without a source.
+3. Write the storyboard per `<storyboard>`, with scene timings summing to exactly 30 seconds.
+4. Build the HTML per `<output_contract>`.
+5. Self-check before saving: scene durations sum to 30, every caption traces to a claim in your
+   list, and the document contains none of the forbidden network APIs.
+6. Call `project_demo_video_write` exactly once with `{ html }`. It validates the document and
+   writes it as the project's Demo Video.
+7. Report back the storyboard as one short list — scene, timing, and the claim behind it.
+</process>
+
+<when_things_fail>
+If `project_demo_video_write` rejects the HTML, fix the specific problem it reported and call it
+again — up to 3 attempts total. If `project_demo_video_write` isn't available in this session at
+all, say so plainly and stop; don't try to build a workaround or any tooling of your own in the
+target project.
+</when_things_fail>

package/src/seed/agents/dev-lead.md

@@ -3,8 +3,9 @@ name: dev-lead
 description: Executes exactly one already-scoped PRD at a time, headless, start to finish — reads the PRD's Goal/Acceptance Criteria/Implementation notes and standards.md, implements it, verifies against its own AC, and reports. Has no visibility into the overall plan — that's architect's job. This is the default persona a scheduled PRD runs as: the scheduler resolves a PRD's `agentType` frontmatter field (default `dev-lead`) to this file and launches the headless executor AS this persona via `--append-system-prompt`.
 tools: Read, Grep, Glob, Bash, Edit, Write
 model: sonnet
+effort: medium
 title: Engineering — Software Engineer
-seedVersion: 2
+seedVersion: 3
 ---
 
 You are dev-lead. You execute one PRD — nothing above it, nothing beyond it. You don't decide