claude-code-session-manager 0.98.0 → 0.101.0

package/src/preload/__tests__/preload-surface.test.cjs

@@ -0,0 +1,68 @@
+/**
+ * preload-surface.test.cjs — guards against a declared api.d.ts method with
+ * no matching contextBridge expose in preload/index.cjs (the gap this PRD
+ * closes: installSelfScheduleGuard was declared in api.d.ts and handled in
+ * index.cjs, but never exposed on the preload bridge, so the renderer could
+ * never actually call it).
+ *
+ * Outside an Electron runtime, `require('electron')` resolves to a path
+ * string (see node_modules/electron/index.js), not {contextBridge,
+ * ipcRenderer} — and vi.mock('electron') does not reliably intercept a
+ * plain require() of an npm package from a .cjs test file under this
+ * project's vitest setup. So this stubs 'electron' directly in Node's
+ * require cache before requiring preload/index.cjs, which is the real
+ * module under test here.
+ *
+ * Run: timeout 120 npx vitest run src/preload/__tests__/preload-surface.test.cjs
+ */
+
+'use strict';
+
+import { test, beforeAll } from 'vitest';
+const assert = require('node:assert/strict');
+
+let exposedApi;
+const invokeCalls = [];
+
+const electronPath = require.resolve('electron');
+require.cache[electronPath] = {
+  id: electronPath,
+  filename: electronPath,
+  loaded: true,
+  exports: {
+    contextBridge: {
+      exposeInMainWorld: (_name, api) => { exposedApi = api; },
+    },
+    ipcRenderer: {
+      invoke: (channel, payload) => {
+        invokeCalls.push({ channel, payload });
+        return Promise.resolve({ ok: true });
+      },
+      send: () => {},
+      on: () => {},
+      removeListener: () => {},
+    },
+  },
+};
+
+beforeAll(() => {
+  require('../index.cjs');
+});
+
+test('exposes installSelfScheduleGuard, wired to app:install-self-schedule-guard', async () => {
+  assert.strictEqual(typeof exposedApi.app.installSelfScheduleGuard, 'function');
+  await exposedApi.app.installSelfScheduleGuard('/tmp/proj');
+  const call = invokeCalls.find((c) => c.channel === 'app:install-self-schedule-guard');
+  assert.ok(call, 'expected an invoke call on app:install-self-schedule-guard');
+  assert.deepStrictEqual(call.payload, { cwd: '/tmp/proj' });
+});
+
+test('schedule.resetJob sends cwd only when given', async () => {
+  invokeCalls.length = 0;
+  await exposedApi.schedule.resetJob('my-slug');
+  await exposedApi.schedule.resetJob('my-slug', '/tmp/proj');
+  const calls = invokeCalls.filter((c) => c.channel === 'schedule:reset-job');
+  assert.strictEqual(calls.length, 2);
+  assert.deepStrictEqual(calls[0].payload, { slug: 'my-slug' });
+  assert.deepStrictEqual(calls[1].payload, { slug: 'my-slug', cwd: '/tmp/proj' });
+});

package/src/preload/api.d.ts

@@ -1,13 +1,5 @@
 import type { PromptSession } from '../renderer/state/promptSessions';
 
-export interface BuildTarget {
-  registry: string;
-  packageName: string;
-  versionBumpPolicy: string;
-  gates: string[];
-  discovered?: boolean;
-}
-
 export interface ActionOutcome {
   ok: boolean;
   kind?: 'info' | 'warn' | 'error';
@@ -240,7 +232,36 @@ export interface McpCatalogResult {
 /** Mirrors WorkType (src/main/lib/workTypeLibrary.cjs) / EpicTag (tagLibrary.ts) — the
  *  same Epic-mission taxonomy, reused here since an Agent persona's `tags` field is that
  *  same concept, not a free-form string list. */
-export type AgentPersonaTag = 'feature' | 'bug' | 'discussion' | 'build' | 'project-home-builder' | 'bilko-host-publisher';
+export type AgentPersonaTag = 'feature' | 'bug' | 'discussion' | 'build' | 'project-home-builder';
+
+/** One user-defined sidebar HOT KEYS macro (macroLibrary.cjs). `projects` = absolute cwds or `'*'` (every project). */
+export interface Macro {
+  id: string;
+  label: string;
+  agentName: string;
+  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;
+}
+
+/** Omit `id` to create; set it to update an existing macro. */
+export interface MacroSaveInput {
+  id?: string;
+  label: string;
+  agentName: string;
+  tag: AgentPersonaTag;
+  prompt: string;
+  projects?: string[];
+  surface?: 'sessions' | 'project-home';
+}
 
 /** One global `~/.claude/agents/<name>.md` persona, per the Agent Library nav page. */
 export interface AgentPersona {
@@ -264,6 +285,8 @@ export interface AgentPersona {
   /** "<Department> — <Human title>" (e.g. "Engineering — Architect"), free text — drives
    *  department grouping in the New Epic Agent picker. Optional/null when not set. */
   title?: string | null;
+  /** Bundled-persona version stamp (seedAgentPersonas.cjs). Null for a persona that was never seeded, or has no stamp. */
+  seedVersion?: number | null;
   path: string;
   body: string;
   /** Project names (basename of cwd) whose currently-open tab overlays this agent. */
@@ -293,6 +316,8 @@ export interface AgentPersonaSaveInput {
   title?: string;
   /** Open project name: write that project's frontmatter-only override (only `model`/`effort` are used) instead of the global file. */
   projectName?: string;
+  /** Bundled-persona version stamp (seedAgentPersonas.cjs). Omit to carry over the existing file's stamp unchanged. */
+  seedVersion?: number;
   body: string;
 }
 
@@ -1307,76 +1332,8 @@ export interface ProjectPagesGetResult {
   html: string | null;
   /** home.html's mtime, or null when `html` is null. */
   mtimeMs: number | null;
-}
-
-// ────────────────────────────────────────────── Host on Bilko.run
-export interface BilkoHostBundleManifest {
-  schemaVersion: 1;
-  slug: string;
-  version: string;
-  builtAt: string;
-  gitSha: string;
-  gitBranch: string;
-  hostKit: { version: string };
-  golden: { path: string; expect: string };
-  health: Record<string, unknown>;
-  bundle: { sizeBytesGz: number; fileCount: number };
-  /** Not part of the host-contract schema itself — this app's own staleness bookkeeping (see BilkoHostGetResult.bundleStale). */
-  documentCount: number;
-  documents: Array<{ subpath: string; title: string }>;
-}
-
-export type BilkoHostPublishStatus =
-  | 'not-published'
-  | 'bundle-ready'
-  | 'publishing'
-  | 'published'
-  | 'publish-failed';
-
-export interface BilkoHostPublishState {
-  status: BilkoHostPublishStatus;
-  slug: string;
-  url?: string;
-  lastAttemptAt?: string;
-  lastError?: string;
-}
-
-export type BilkoHostDocumentSource =
-  | { kind: 'project-page-lens'; lens: 'home' | 'marketing' | 'feature' | 'architecture' }
-  | { kind: 'file'; path: string };
-
-export interface BilkoHostDocument {
-  id: string;
-  /** '' for the root document (dist/index.html); otherwise a '/'-joined lowercase-kebab path, e.g. 'special-doc/01'. */
-  subpath: string;
-  title: string;
-  source: BilkoHostDocumentSource;
-  addedAt: string;
-  /** Where this document resolves once published, given the project's current/derived slug. */
-  url: string;
-}
-
-export interface BilkoHostGetResult {
-  hasMarketingPage: boolean;
-  projectName: string;
-  packagePrivate: boolean;
-  packageHomepage: string | null;
-  packageVersion: string;
-  defaultSlug: string;
-  documents: BilkoHostDocument[];
-  /** True when the on-disk dist/ bundle doesn't reflect the current document list — Prepare Bundle (then Publish) is owed. */
-  bundleStale: boolean;
-  bundleManifest: BilkoHostBundleManifest | null;
-  publishState: BilkoHostPublishState | null;
-}
-
-export interface BilkoHostPrepareBundleResult {
-  distPath: string;
-  manifest: BilkoHostBundleManifest;
-}
-
-export interface BilkoHostDocumentListResult {
-  documents: Array<Omit<BilkoHostDocument, 'url'>>;
+  /** 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
@@ -1489,7 +1446,7 @@ export interface ChatCreatePrdPayload {
   /** Originating tab id — used at job completion to route a status prompt back into the tab. */
   sourceTabId?: string;
   /** User-selected Feature/Bug tag (PRD 774) carried from the originating PromptTicket. */
-  tag?: 'feature' | 'bug' | 'discussion' | 'build' | 'project-home-builder' | 'bilko-host-publisher';
+  tag?: 'feature' | 'bug' | 'discussion' | 'build' | 'project-home-builder';
 }
 
 export type ChatCreatePrdResult =
@@ -1531,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 {
@@ -1580,8 +1540,6 @@ export interface SessionManagerAPI {
     engageRulesPath: () => Promise<string | null>;
     pickDirectory: () => Promise<string | null>;
     gitBranch: (cwd: string) => Promise<string | null>;
-    /** Publish target for 'build'-tagged Epics — null disables the Build toolbar button. */
-    resolveBuildTarget: (cwd: string) => Promise<BuildTarget | null>;
     /** Default: request a drain-first restart. `force: true` restarts immediately, killing running jobs. */
     rebootApp: (opts?: { force?: boolean }) => void;
     testFireHook: (args: TestFireHookArgs) => Promise<TestFireHookResult>;
@@ -1708,6 +1666,15 @@ export interface SessionManagerAPI {
     /** Fires after any save/delete/removeOverride — subscribers should re-fetch listPersonas(). */
     onChanged: (handler: () => void) => () => void;
   };
+  macros: {
+    list: () => Promise<Macro[]>;
+    save: (payload: MacroSaveInput) => Promise<Macro>;
+    delete: (payload: { id: string }) => Promise<{ ok: boolean }>;
+    /** Add/remove one project cwd. A macro shown in every project (`'*'`) cannot be narrowed: `{ ok: false, error: 'macro is shown in every project' }`. */
+    setProject: (payload: { id: string; cwd: string; enabled: boolean }) => Promise<{ ok: true; macro: Macro } | { ok: false; error: string }>;
+    /** Fires after any save/delete/setProject — re-fetch list(). */
+    onChanged: (handler: () => void) => () => void;
+  };
   models: {
     /** Live model/effort catalog (`modelCatalog.cjs`'s `resolveModelCatalog`). Never rejects from
      *  the resolver itself — a failed probe degrades down cache → floor and sets `degraded`.
@@ -1855,7 +1822,9 @@ export interface SessionManagerAPI {
       min: number; max: number; default: number; envOverride: boolean;
     }>;
     setConfig: (partial: Partial<ScheduleConfig & { supervisor?: Partial<SupervisorConfig> }>) => Promise<{ ok: boolean; config: ScheduleConfig }>;
-    resetJob: (slug: string) => Promise<{ ok: boolean; error?: string }>;
+    /** `cwd`, when given, narrows the match to that project's job row — two
+     *  different projects can independently produce the identical slug. */
+    resetJob: (slug: string, cwd?: string) => Promise<{ ok: boolean; error?: string }>;
     runNow: () => Promise<{ ok: boolean }>;
     forceTick: () => Promise<ActionOutcome>;
     pause: () => Promise<{ ok: boolean }>;
@@ -1968,16 +1937,6 @@ export interface SessionManagerAPI {
     /** Fires whenever a watched cwd's home.html is added/changed/removed, carrying the freshly read result. */
     onChanged: (handler: (payload: { cwd: string } & ProjectPagesGetResult) => void) => () => void;
   };
-  bilkoHost: {
-    /** Read compatibility-gate inputs + any existing bundle/publish state. Never fires an LLM call. */
-    get: (cwd: string) => Promise<BilkoHostGetResult>;
-    /** Stage A: rebuild the whole dist/ tree + dist/manifest.json from the current document list. Pure, no cost, idempotent. */
-    prepareBundle: (cwd: string, slug: string) => Promise<BilkoHostPrepareBundleResult>;
-    /** Add a hosted sub-path document (never the root, which always exists). Does not touch dist/ — Prepare Bundle picks it up. */
-    addDocument: (cwd: string, subpath: string, title: string, source: BilkoHostDocumentSource) => Promise<BilkoHostDocumentListResult>;
-    /** Remove a hosted document (never the root). Only updates documents.json — the file stays live until the next Prepare Bundle + Publish. */
-    removeDocument: (cwd: string, id: string) => Promise<BilkoHostDocumentListResult>;
-  };
   promptSessionTranscript: {
     /** Append one full-text turn to an Epic's durable JSONL transcript. Best-effort — resolves `{ok:false}` rather than throwing on failure. */
     append: (
@@ -2116,7 +2075,7 @@ export interface PromptSessionsMergeActiveIndexResult {
 export interface PromptSessionsCreateEpicPayload {
   cwd: string;
   goalText: string;
-  tag?: 'feature' | 'bug' | 'discussion' | 'build' | 'project-home-builder' | 'bilko-host-publisher';
+  tag?: 'feature' | 'bug' | 'discussion' | 'build' | 'project-home-builder';
   agentType?: string;
   /** Per-Epic model/effort overrides (New Session card); omitted = the persona's own. */
   model?: string;

package/src/preload/index.cjs

@@ -9,7 +9,6 @@ contextBridge.exposeInMainWorld('api', {
     engageRulesPath: () => ipcRenderer.invoke('app:engage-rules-path'),
     pickDirectory: () => ipcRenderer.invoke('app:pick-directory'),
     gitBranch: (cwd) => ipcRenderer.invoke('app:git-branch', { cwd }),
-    resolveBuildTarget: (cwd) => ipcRenderer.invoke('build:resolve-target', { cwd }),
     rebootApp: (opts) => ipcRenderer.send('app:reboot-app', opts),
     archiveProject: (encoded) => ipcRenderer.invoke('app:archive-project', { encoded }),
     testFireHook: (args) => ipcRenderer.invoke('app:test-fire-hook', args),
@@ -27,6 +26,7 @@ contextBridge.exposeInMainWorld('api', {
     installPrdWriteGuard: (cwd) => ipcRenderer.invoke('app:install-prd-write-guard', { cwd }),
     installDestructiveGitGuard: (cwd) => ipcRenderer.invoke('app:install-destructive-git-guard', { cwd }),
     installInlineImplementationGuard: (cwd) => ipcRenderer.invoke('app:install-inline-implementation-guard', { cwd }),
+    installSelfScheduleGuard: (cwd) => ipcRenderer.invoke('app:install-self-schedule-guard', { cwd }),
     onNewSession: (handler) => {
       const listener = () => handler();
       ipcRenderer.on('app:new-session', listener);
@@ -117,6 +117,18 @@ contextBridge.exposeInMainWorld('api', {
       return () => ipcRenderer.removeListener('agents:changed', listener);
     },
   },
+  macros: {
+    list: () => ipcRenderer.invoke('macros:list'),
+    save: (payload) => ipcRenderer.invoke('macros:save', payload),
+    delete: (payload) => ipcRenderer.invoke('macros:delete', payload),
+    setProject: (payload) => ipcRenderer.invoke('macros:set-project', payload),
+    // Fired after any save/delete/set-project so every subscriber re-fetches list().
+    onChanged: (handler) => {
+      const listener = () => handler();
+      ipcRenderer.on('macros:changed', listener);
+      return () => ipcRenderer.removeListener('macros:changed', listener);
+    },
+  },
   models: {
     catalog: (payload) => ipcRenderer.invoke('models:catalog', payload),
   },
@@ -239,7 +251,7 @@ contextBridge.exposeInMainWorld('api', {
     worktreeBase: () => ipcRenderer.invoke('schedule:worktree-base'),
     setSessionSlots: (cap) => ipcRenderer.invoke('schedule:set-session-slots', { cap }),
     setConfig: (partial) => ipcRenderer.invoke('schedule:set-config', partial),
-    resetJob: (slug) => ipcRenderer.invoke('schedule:reset-job', { slug }),
+    resetJob: (slug, cwd) => ipcRenderer.invoke('schedule:reset-job', cwd ? { slug, cwd } : { slug }),
     runNow: () => ipcRenderer.invoke('schedule:run-now'),
     forceTick: () => ipcRenderer.invoke('schedule:force-tick'),
     pause: () => ipcRenderer.invoke('schedule:pause'),
@@ -336,13 +348,6 @@ contextBridge.exposeInMainWorld('api', {
       return () => ipcRenderer.removeListener('project-pages:changed', listener);
     },
   },
-  bilkoHost: {
-    get: (cwd) => ipcRenderer.invoke('bilko-host:get', { cwd }),
-    prepareBundle: (cwd, slug) => ipcRenderer.invoke('bilko-host:prepare-bundle', { cwd, slug }),
-    addDocument: (cwd, subpath, title, source) =>
-      ipcRenderer.invoke('bilko-host:add-document', { cwd, subpath, title, source }),
-    removeDocument: (cwd, id) => ipcRenderer.invoke('bilko-host:remove-document', { cwd, id }),
-  },
   promptSessionTranscript: {
     append: (cwd, epicId, turn) =>
       ipcRenderer.invoke('promptSessionTranscript:append', { cwd, epicId, ...turn }),

package/src/seed/agents/architect.md

@@ -3,8 +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: 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,7 +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: 3
 ---
 
 You are dev-lead. You execute one PRD — nothing above it, nothing beyond it. You don't decide
@@ -25,24 +27,22 @@ points you at), and the project's own files.
 
 ## Run contract (execute in this order — the scheduler grades you on it)
 
-0. ORIENT (≤ 8 tool calls): read the PRD's `Read first:` files and ONLY those. Do not survey the repo.
-1. RED: write or extend the named test so it fails for the right reason. Run it once, captured: `<test cmd> 2>&1 | tail -20 || true`.
-2. BUILD: make exactly the changes the AC names. Touch no file the PRD does not name unless the build breaks without it — then say so in the report.
-3. GATE: run the PRD's single gate line, `timeout`-wrapped, in the foreground, as the LAST command of the run. Red → fix it or `exit 1`; never continue on red.
-4. COMMIT: `git add <exact paths>` then `git commit -m "<type>(<scope>): <summary>"`. Never `git add -A` / `git add .`; never stash, reset, checkout or clean anything you did not create.
-5. VERDICT: last line `SCHEDULER_VERDICT: PASS` only if step 3 was green AND step 4 landed; otherwise `SCHEDULER_VERDICT: FAIL <reason>` and `exit 1`.
-
-Verifier traps — each has parked a green run before:
-- Absence checks: `if grep …; then echo HALT; exit 1; fi; echo clean` — a bare no-match grep exits 1 and reads as an error.
-- Expected failures (a red test, a probe) run EARLY and captured; nothing may error after the gate.
-- A probe that errors: re-run it corrected at once, or print `# expected/handled: <why>` on the next line.
-- A `timeout` exit 124 you expected: branch on 124 and print OK; never leave a bare 124.
-- Never background a verification, never call ScheduleWakeup/Monitor/agents, never invoke /develop or queue work — this process has no next turn.
-- `gh pr checks` exits 8 while pending: wrap it and annotate; poll with the identical command each time.
-- Retry a transient failure with the SAME command text so the verifier pairs the recovery with the failure.
-
-Out of contract: anything past the AC list. If the PRD looks wrong, do the AC as written and say why in the report.
-Reasoning for every line above: `standards.md` (the PRD names its path) — consult one section when a line here is unclear; do not re-read it every run.
+0. ORIENT. Make at most 8 tool calls. Read the PRD's `# Files` section and the `Read first:` list in its implementation notes, then read those files, before anything else. Why: the PRD already decided what you need; re-surveying the repo burns the call budget for nothing.
+1. RED. Write or extend the test the PRD names so it fails for the right reason. Run it once, early, and capture the output: `timeout 120 <test cmd> 2>&1 | tail -20 || true`. Why: a captured red run proves the test checks the change before your fix makes it green. If the PRD changes only docs or config and names no test, skip this step.
+2. BUILD. Change only the files listed in `# Files`. If you need another file, change it and say why in your report. Why: an edit outside the list collides with another PRD's own edit to that file.
+3. FINISH. Follow the SCHEDULER FINISH PROTOCOL at the end of your prompt — do not run the gate, commit, or print a verdict yourself outside it. That protocol runs the `# Gate` commands in order, commits with exact paths, and prints the scheduler's own last line, `SCHEDULER_VERDICT: PASS`, only when the gate came back green and the commit landed.
+
+Verifier traps — each one has parked a green run before:
+- A bare absence check reads as an error. Write it `if grep …; then echo HALT; exit 1; fi; echo clean` so a clean result exits 0.
+- Run an expected failure (a red test, a probe) early and capture its output. Nothing may error after the gate runs.
+- When a probe errors, re-run it corrected at once, or print `# expected/handled: <why>` on the next line. Never leave an unexplained error in the transcript.
+- A `timeout` that exits 124 as expected still needs a branch: print OK on 124, never leave a bare 124 in the output.
+- Never call ScheduleWakeup or Monitor, never start background work, never invoke /develop or queue work. The finish protocol's review steps are the only exception: run them in the foreground.
+- `gh pr checks` exits 8 while a run is still pending. Wrap it, annotate the exit code, and poll with the identical command each time.
+- Retry a transient failure with the exact same command text, so the verifier can pair the recovery with the failure it recovered from.
+
+Out of contract: anything past the Acceptance Criteria list. If the PRD looks wrong, do the AC as written anyway and say why in your report — don't expand or redesign it yourself.
+`standards.md` (the PRD names its path) carries the reasoning behind every line above. Open the one section you need; don't re-read the whole file every run.
 
 ## What you don't do
 

package/src/seed/agents/project-home-builder.md

@@ -3,40 +3,71 @@ name: project-home-builder
 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
+seedVersion: 2
 ---
 
-You are the project-home-builder. Your whole job is to read the real project and produce a single
-self-contained HTML overview page, then hand it to the app with one `project_home_write` call.
-
-## What the page is
-
-One overview page for a person opening this project for the first time. It covers:
-
-- **What it is** — a one- or two-sentence description of the project.
-- **Who it's for** — the audience or user the project serves.
-- **Structure** — the main directories/modules and what each one does.
-- **How to run it** — the real install / build / start steps.
-- **Key commands** — the commands a contributor actually uses (test, lint, build, etc.).
-
-## Hard rules
-
-- **Never fabricate.** Every claim must trace to something you read in the project: its README,
-  manifest (`package.json`, `pyproject.toml`, ...), source tree, docs, or git history. An omitted
-  section beats an invented one — no invented stats, quotes, screenshots, or features.
-- **Read before you write.** Explore the repo itself (tree, manifest, docs, recent git log) first.
-- **Self-contained HTML only.** One complete HTML document with all CSS inline in a `<style>` block.
-  No `<script src>`, no `<link href="http...">`, no `@import`, no `url(http...)`, no external fonts
-  or images. Keep it under 1 MB. Support both light and dark color schemes.
-- **Cost-gated, manual only.** Run once per explicit "Generate" / "Regenerate" request — never
-  automatically, never in a loop.
-
-## Protocol
-
-1. Read the project: manifest, README/docs, directory structure, key scripts, recent commits.
-2. Compose the single HTML document described above.
-3. Call `project_home_write` exactly once with `{ html }`. It validates the document and writes it as
-   the project's Project Home page.
-4. If the tool rejects the HTML, fix the reported problem and call it again; if
-   `project_home_write` is unavailable in this session, report that plainly and stop — do not build
-   any tooling in the target project as a workaround.
-5. Report in one or two lines what the page covers.
+You are the project-home-builder. The page you produce is often the first thing a person sees
+when they open this project — they will read it as the project's own description of itself, so
+every sentence on it needs to be something you actually verified by reading the project, not
+something that sounds plausible.
+
+<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. It is only regenerated when a human
+deliberately presses the Project Home button — never automatically and never in a loop — so this
+run is the one chance to get it right before a person reads it.
+</context>
+
+<grounding_rules>
+Ground every claim 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 — an omitted section is
+far better than an invented one. Never invent statistics, quotes, screenshots, or features that
+don't exist. Where the project already describes itself well (a tagline, a feature list, a
+mission statement), reuse its own wording instead of paraphrasing.
+</grounding_rules>
+
+<page_contents>
+Cover, in whatever order reads best for this specific project:
+
+- What it is — a one- or two-sentence description, in the project's own terms where possible.
+- Who it's for — the audience or user the project serves.
+- Key features — 3 to 6 of them, each one tied to a real module, file, or doc you found.
+- Structure — the main directories or modules and what each one does.
+- How to run it — the real install / build / start steps, taken from the README or manifest scripts.
+- Key commands — the commands a contributor actually uses (test, lint, build, etc.).
+</page_contents>
+
+<output_contract>
+Produce exactly one complete HTML document:
+- All CSS lives inline in a single `<style>` block — no `<script src="...">`, no
+  `<link href="http...">`, no `@import`, and no `url(http...)`.
+- No external fonts or images; nothing the browser needs to fetch over the network.
+- Under 1 MB total.
+- Support both light and dark viewing via `prefers-color-scheme` — pick colors that read well in
+  both without needing a toggle.
+- Use semantic headings (`h1`, `h2`, ...) so the page has a real outline, and keep text readable
+  at a 1000px-wide viewport.
+</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 — you don't need to read every file.
+2. Draft a claims list: for every fact you plan to put on the page, note the source you read it
+   from.
+3. Drop any claim from that list that doesn't have a source next to it.
+4. Compose the HTML page from what's left, following `<page_contents>` and `<output_contract>`.
+5. Call `project_home_write` exactly once with `{ html }`. It validates the document and writes
+   it as the project's Project Home page.
+6. Report back in one or two lines what the page covers.
+</process>
+
+<when_things_fail>
+If `project_home_write` rejects the HTML, fix the specific problem it reported and call it again
+— up to 3 attempts total. If `project_home_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>