@invisibleloop/pulse 0.20.10 → 0.20.19

package/src/agent/identity.md

@@ -93,6 +93,15 @@ You understand what already exists before creating anything — inspect the proj
 
 You narrate your progress as you go. After each meaningful step — writing a file, completing a verification step, fixing an error — output a short status line before moving on. Do not run all your tool calls silently and then summarise at the end. Examples: `✓ Page written — running syntax check...`, `✓ No console errors — fetching SSR output...`, `✓ SSR looks good — building for production...`, `✗ Lighthouse accessibility 94 — fixing missing label on email input...`. One line is enough. Keep it factual and move on.
 
+**Always report Lighthouse results in this exact fixed format — never paraphrase the scores into prose** (not "Desktop 100 across the board", not a slash-joined string of all four numbers run together). Some hosts render this line specially (e.g. as score cards); paraphrasing breaks that and hides the real per-category numbers from the user. One line per device, right after that device's `lighthouse_audit` call returns:
+
+```
+Lighthouse desktop: Accessibility 100, Best Practices 100, SEO 100
+Lighthouse mobile: Accessibility 100, Best Practices 100, SEO 96
+```
+
+Always all three categories, always in that order, always `Category N` (not `N%`, not `N/100`). Include Performance only when it was actually gated for this page (ad-free pages only — see the Performance Baseline table) as a fourth `Performance N` pair, same line. If a score is missing/unavailable from the tool response, write `Category —` rather than omitting the category.
+
 You validate after you write. Fix every error AND every warning before moving on. Warnings include heading order violations and escaping issues that Lighthouse will flag.
 
 You write tests for every page you create. A minimal page test looks like this:

package/src/agent/workflow.md

@@ -32,6 +32,7 @@ For any **new page, landing page, or branded site**, run the intake sequence fir
 ```
 
 - **Step 0 — Ask for inspiration first (mandatory):** Before calling any tool or presenting any plan, ask the user: *"Do you have any design inspiration — a site you love, a screenshot, or a mood board image? Drop images into `public/intake/` or paste a URL and I'll extract the design intent before we start."* Wait for the answer. Do not skip this question, even if the user's brief already seems detailed. Check `public/intake/` for any images already dropped there.
+  - **Internal/functional tools (a staff dashboard, an admin screen, an internal work tool — not something customers see):** the question itself is still mandatory, but the aesthetic framing lands oddly ("a site you love" doesn't map onto "a work screen an employee glances at"). Ask instead: *"Do you have any reference for how this should look, or should I go with a clean, functional style typical of internal tools? Also — what's the most important thing to see at a glance, and how much will typically be on screen at once?"* This still catches a real visual reference if one exists, while asking what actually matters for this kind of build (information density, priority) instead of forcing a mood-board answer nobody has. A "no, we don't have anything" answer here is common and not a reason to skip `pulse_intake`'s theme/vibe/anti-style questions that follow — fold the answer in and move on, same as any other build.
 - **`pulse_extract_inspiration`** — call this after step 0 if the user supplies a URL, site name, or image they like. Also call it for any images already present in `public/intake/`. Gives you a structured extraction template: visit the URL or analyse the image with your vision tools, extract colours, layout, typography, and feel, then feed those findings into pulse_intake. If the user explicitly says they have no reference, skip this step.
 - **`pulse_intake`** — captures the real content (name, pitch, features, palette, theme, vibe, what it should NOT look like). Returns a brief with copy-ready content and early contrast warnings. Always ask the user one question at a time — never multi-choice for open-ended questions. **Always ask light or dark** — Pulse renders dark when `meta.theme` is unset, so an unstated light design ships dark.
 - **`pulse_sketch`** — generates 3 structurally distinct layout directions (full-bleed, asymmetric split, typography-only, editorial, dense grid, story scroll, content-first). **Call this before writing any code.** Prevents defaulting to centred hero + three-column features every time.
@@ -163,29 +164,9 @@ If you're about to type `class="hero"` or `class="product-card"` in Mode A, stop
 **Reuse across specs (both modes):** one spec = one page; a site is many specs sharing code. Before writing a new section, check `src/components/` — and if a section you're writing already exists in another spec, extract it to `src/components/` *now* and import it from both, rather than pasting a copy. Same for CSS: a shared section's styles go in the shared `app.css` (listed in `meta.styles` by every spec that uses it), never duplicated into per-page stylesheets.
 
 **Mode B — Creative override (raw HTML throughout)**
-When the design intent calls for a more expressive, unconventional, or typographically-driven layout that components would constrain, you may build with raw HTML throughout. This is a deliberate design decision, not a shortcut.
-
-**When to choose Mode B — use the component, unless:**
-- The layout requires **full-viewport height or edge-to-edge bleed** that the component doesn't support (e.g. `hero()` doesn't fill the viewport)
-- The design uses **custom gradient glows, parallax, or large-scale image fills** that the component would wrap in unwanted structure
-- The vibe is **brutalist, retro, neon, paper, or typographic-editorial** and the structural feel would be actively fought by the component's default padding/spacing/radius
-- The typography is **clamp-scaled display type** (e.g. `clamp(4rem, 10vw, 12rem)`) that breaks inside a component's internal box model
-- The layout is **asymmetric or zone-based** (e.g. 70/30 split, overlapping elements, staggered grid) that no single component supports
-- A **Figma/reference design was provided** that clearly departs from the component's output
-
-**When to use the component (not a valid reason for override):**
-- "The component doesn't have a perfect prop for this" — add a utility class or wrapper div instead
-- "I want a slightly different colour or size" — override with CSS tokens
-- "I'm not sure what the component looks like" — check the guide first
-- "It's easier to write raw HTML" — this is never a valid reason
-
-Rules for Mode B:
-- **Declare it in a comment at the top of the spec file:** `// component-free — creative override: <reason>`. The review tool detects creative override by reading this comment from the source — without it, `pulse_review` will flag every component pattern as a violation even though you chose Mode B deliberately. Announcing the mode in chat is not enough; the comment must be in the file.
-- Load `/pulse-ui.css` in `meta.styles` — the token system is still required
-- Functional atoms (`button`, `input`, `badge`, `modal`) should still come from components unless there is a specific design reason
-- The quality gate is Lighthouse 100 on Accessibility, Best Practices, and SEO (desktop and mobile) plus CLS 0.00 — this replaces the component checklist as the pass bar. Performance is reported but not gated.
-
-Announce Mode B explicitly in the build brief (*"Mode B — component-free, raw HTML for creative control"*) **and** write the override comment into the spec.
+When the design intent calls for a more expressive, unconventional, or typographically-driven layout that components would constrain, you may build with raw HTML throughout. Full criteria for when this is (and isn't) warranted, and the required spec comment, are in `checklist.md`'s "Components first — or creative override" section — read that before choosing Mode B. In short: it's a deliberate design decision for cases components structurally can't express (full-viewport bleed, brutalist/neon/editorial vibes, clamp-scaled display type, asymmetric layouts) — never a shortcut for "easier to write raw HTML."
+
+Announce Mode B explicitly in the build brief (*"Mode B — component-free, raw HTML for creative control"*) **and** write `// component-free — creative override: <reason>` at the top of the spec file — `pulse_review` only detects Mode B by reading that comment from the source, not from chat.
 
 ### 3b — Announce before writing
 

package/src/cli/check-bundles.js

@@ -0,0 +1,113 @@
+/**
+ * Pulse — Bundle content inspection (shared logic)
+ *
+ * The single source of truth behind pulse_check_bundles (MCP tool, for an
+ * agent) and `pulse check-bundles` (CLI command, for a human). Lighthouse
+ * checks scores; this checks what's actually inside the generated
+ * public/dist/ bundle files after a production build — a boot bundle
+ * generated for a page that doesn't need one, or server-only code that
+ * leaked through stripping. Neither of those shows up as a score failure.
+ */
+
+import fs   from 'fs'
+import path from 'path'
+import { discoverPages } from './discover.js'
+
+const NODE_BUILTINS = ['node:fs', 'node:path', 'node:crypto', 'node:os', 'node:child_process', 'node:http', 'node:https', 'node:net', 'node:dns']
+
+/**
+ * Inspect public/dist/ after a production build.
+ *
+ * @param {string} root - project root
+ * @returns {{
+ *   error: string|null,
+ *   issues: string[],
+ *   confirms: string[],
+ * }}
+ */
+export function checkBundles(root) {
+  const distDir = path.join(root, 'public', 'dist')
+  const manifestPath = path.join(distDir, 'manifest.json')
+  if (!fs.existsSync(manifestPath)) {
+    return { error: 'No public/dist/manifest.json found — run a production build first.', issues: [], confirms: [] }
+  }
+
+  let manifest
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'))
+  } catch (err) {
+    return { error: `Could not parse manifest.json: ${err.message}`, issues: [], confirms: [] }
+  }
+
+  const issues = []
+  const confirms = []
+
+  // Read each page's raw source directly rather than importing the module —
+  // no need to re-execute project code just to check for hydration need.
+  // needsHydration mirrors discover.js's own check exactly: mutations ||
+  // actions || persist. The manifest key for a page is always
+  // /src/pages/<relative path> — that's how loadPages/build.js both derive
+  // it, so no fuzzy route matching is needed.
+  let pageFiles = []
+  try {
+    pageFiles = discoverPages(root)
+  } catch { /* fall through — bundle-content checks below still run */ }
+
+  for (const { filePath, derivedRoute } of pageFiles) {
+    const source = fs.readFileSync(filePath, 'utf8')
+    const needsHydration = /\b(mutations|actions|persist)\s*:/.test(source) || /\bhydrate\s*:/.test(source)
+    if (needsHydration) continue // genuinely needs hydration — nothing to flag
+    const manifestKey = '/src/pages/' + path.relative(path.join(root, 'src', 'pages'), filePath)
+    const bundled = manifest[manifestKey]
+    if (bundled) {
+      // discoverPages' derivedRoute is a filename-based fallback (spec.route
+      // wins at runtime, e.g. for a dynamic /:code route on a file literally
+      // named redirect.js) — read the spec's real declared route from source
+      // when present, so the message names the route that's actually
+      // registered, not just what the filename implies.
+      const routeMatch = source.match(/\broute\s*:\s*['"]([^'"]+)['"]/)
+      const route = routeMatch ? routeMatch[1] : derivedRoute
+      issues.push(`✗ Route "${route}" (${manifestKey}) has no mutations/actions/persist but a boot bundle exists (${bundled}) — should ship zero client JS. If this page imports a local server-only helper (e.g. using node:fs), the build may be one dependency away from failing outright.`)
+    }
+  }
+
+  // Scan every generated boot file for a literal Node built-in reference —
+  // the strongest, cheapest signal that server-only code leaked through.
+  let bootFiles = []
+  try {
+    bootFiles = fs.readdirSync(distDir).filter(f => f.includes('.boot-') && f.endsWith('.js'))
+  } catch { /* dist dir read failure — nothing more to check */ }
+
+  for (const file of bootFiles) {
+    const content = fs.readFileSync(path.join(distDir, file), 'utf8')
+    const leaked = NODE_BUILTINS.filter(b => content.includes(b))
+    if (leaked.length > 0) {
+      issues.push(`✗ ${file} contains a literal reference to ${leaked.join(', ')} — server-only code leaked into a client bundle. This will throw at runtime in the browser (these modules don't exist there) even if the build itself succeeded.`)
+    } else {
+      confirms.push(`✓ ${file} — no Node built-in references found`)
+    }
+  }
+
+  if (bootFiles.length === 0) confirms.push('✓ No boot bundles generated — consistent with a purely server-rendered project, if that\'s expected')
+
+  return { error: null, issues, confirms }
+}
+
+export function formatBundleCheck(result) {
+  if (result.error) return result.error
+
+  const lines = ['## Bundle content check\n']
+  if (result.issues.length === 0) {
+    lines.push('✓ All clear — no unnecessary bundles, no leaked server-only code.\n')
+  } else {
+    lines.push('### Issues found\n')
+    for (const i of result.issues) lines.push(i)
+    lines.push('')
+  }
+  if (result.confirms.length > 0) {
+    lines.push('### Checked\n')
+    for (const c of result.confirms) lines.push(c)
+  }
+
+  return lines.join('\n')
+}

package/src/cli/check-bundles.test.js

@@ -0,0 +1,137 @@
+/**
+ * Pulse — check-bundles.js tests
+ * run: node src/cli/check-bundles.test.js
+ *
+ * Shared logic behind pulse_check_bundles (MCP tool) and `pulse check-bundles`
+ * (CLI command). These tests build against a real manifest.json + real boot
+ * file content (not a mocked build) since the whole point of this check is
+ * reading what a real build actually produced.
+ */
+
+import { test }   from 'node:test'
+import assert     from 'node:assert/strict'
+import fs         from 'node:fs'
+import os         from 'node:os'
+import path       from 'node:path'
+import { checkBundles, formatBundleCheck } from './check-bundles.js'
+
+function tmpProject() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'pulse-check-bundles-test-'))
+  fs.mkdirSync(path.join(root, 'src', 'pages'), { recursive: true })
+  fs.mkdirSync(path.join(root, 'public', 'dist'), { recursive: true })
+  return root
+}
+
+function writeManifest(root, entries) {
+  fs.writeFileSync(path.join(root, 'public', 'dist', 'manifest.json'), JSON.stringify(entries, null, 2))
+}
+
+function writeBootFile(root, name, content = 'var x = 1;') {
+  fs.writeFileSync(path.join(root, 'public', 'dist', name), content)
+}
+
+test('reports an error when no manifest.json exists', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'pulse-check-bundles-test-'))
+  const result = checkBundles(root)
+  assert.match(result.error, /No public\/dist\/manifest\.json found/)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('clean pass: a page with mutations correctly has a bundle', () => {
+  const root = tmpProject()
+  fs.writeFileSync(path.join(root, 'src', 'pages', 'counter.js'),
+    `export default {\n  route: '/counter',\n  state: { count: 0 },\n  mutations: { inc: (s) => ({ count: s.count + 1 }) },\n  view: (state) => \`<button>\${state.count}</button>\`,\n}`)
+  writeManifest(root, { '/src/pages/counter.js': '/dist/counter.boot-ABC123.js' })
+  writeBootFile(root, 'counter.boot-ABC123.js')
+
+  const result = checkBundles(root)
+  assert.equal(result.error, null)
+  assert.equal(result.issues.length, 0, `Expected no issues, got: ${JSON.stringify(result.issues)}`)
+  assert.equal(result.confirms.length, 1)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('flags a boot bundle for a page with no mutations/actions/persist', () => {
+  const root = tmpProject()
+  fs.writeFileSync(path.join(root, 'src', 'pages', 'redirect.js'),
+    `export default {\n  route: '/:code',\n  guard: async (ctx) => { if (!ctx.params.code) return { status: 404 } },\n  view: () => '<main id="main-content">redirecting</main>',\n}`)
+  // Simulate the exact historical bug: a bundle exists for a page that needs none.
+  writeManifest(root, { '/src/pages/redirect.js': '/dist/redirect.boot-XYZ789.js' })
+  writeBootFile(root, 'redirect.boot-XYZ789.js')
+
+  const result = checkBundles(root)
+  assert.equal(result.issues.length, 1)
+  assert.match(result.issues[0], /\/:code/)
+  assert.match(result.issues[0], /no mutations\/actions\/persist/)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('issue message uses the spec\'s real declared route, not the filename-derived fallback', () => {
+  // Regression: discoverPages' derivedRoute is filename-based only (it doesn't
+  // parse spec.route) — a file named redirect.js with route: '/:code' was
+  // reported as route "/redirect" instead of the route actually registered.
+  const root = tmpProject()
+  fs.writeFileSync(path.join(root, 'src', 'pages', 'redirect.js'),
+    `export default {\n  route: '/:code',\n  guard: async (ctx) => { if (!ctx.params.code) return { status: 404 } },\n  view: () => '<main id="main-content">redirecting</main>',\n}`)
+  writeManifest(root, { '/src/pages/redirect.js': '/dist/redirect.boot-XYZ789.js' })
+  writeBootFile(root, 'redirect.boot-XYZ789.js')
+
+  const result = checkBundles(root)
+  assert.equal(result.issues.length, 1)
+  assert.match(result.issues[0], /Route "\/:code"/,
+    `Expected the real declared route /:code, not the filename-derived /redirect — got: ${result.issues[0]}`)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('does not flag a page with no mutations/actions/persist that correctly has no bundle', () => {
+  const root = tmpProject()
+  fs.writeFileSync(path.join(root, 'src', 'pages', 'redirect.js'),
+    `export default {\n  route: '/:code',\n  guard: async (ctx) => { if (!ctx.params.code) return { status: 404 } },\n  view: () => '<main id="main-content">redirecting</main>',\n}`)
+  // No manifest entry for this page — correct behaviour, nothing to flag.
+  writeManifest(root, {})
+
+  const result = checkBundles(root)
+  assert.equal(result.issues.length, 0)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('flags a boot bundle containing a literal Node built-in reference', () => {
+  const root = tmpProject()
+  writeManifest(root, {})
+  writeBootFile(root, 'leaky.boot-DEF456.js', `var x=require("node:fs");x.readFileSync("/tmp/y")`)
+
+  const result = checkBundles(root)
+  assert.equal(result.issues.length, 1)
+  assert.match(result.issues[0], /leaky\.boot-DEF456\.js/)
+  assert.match(result.issues[0], /node:fs/)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('a clean boot file with no Node built-ins is confirmed, not flagged', () => {
+  const root = tmpProject()
+  writeManifest(root, {})
+  writeBootFile(root, 'clean.boot-GHI999.js', `var mount=function(){};mount()`)
+
+  const result = checkBundles(root)
+  assert.equal(result.issues.length, 0)
+  assert.equal(result.confirms.some(c => c.includes('clean.boot-GHI999.js')), true)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('formatBundleCheck reports all-clear when there are no issues', () => {
+  const root = tmpProject()
+  writeManifest(root, {})
+  const output = formatBundleCheck(checkBundles(root))
+  assert.match(output, /All clear/)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('formatBundleCheck lists issues under their own heading', () => {
+  const root = tmpProject()
+  writeManifest(root, {})
+  writeBootFile(root, 'leaky.boot-JKL111.js', `require("node:crypto")`)
+  const output = formatBundleCheck(checkBundles(root))
+  assert.match(output, /### Issues found/)
+  assert.match(output, /node:crypto/)
+  fs.rmSync(root, { recursive: true, force: true })
+})

package/src/cli/cli.test.js

@@ -10,6 +10,9 @@
 
 import { existsSync, readFileSync } from 'fs'
 import path from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
 let passed = 0
 let failed = 0
@@ -79,6 +82,27 @@ test('discover: nested pages get unique names (collision prevention)', () => {
   }
 })
 
+test('discover: a store-only spec (no local mutations/actions/persist) still gets a hydrate URL — regression: mount() is what wires up data-store-event dispatch AND the live SSE store-push subscription; without this a store-only page silently ships zero JS and never receives pushStore() broadcasts', async () => {
+  const fs   = await import('fs')
+  const os   = await import('os')
+  const path = await import('path')
+  const { loadPages } = modules[1].value
+
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'pulse-discover-store-test-'))
+  fs.mkdirSync(path.join(root, 'src', 'pages'), { recursive: true })
+  fs.writeFileSync(
+    path.join(root, 'src', 'pages', 'storey.js'),
+    `export default {\n  route: '/storey',\n  store: ['count'],\n  state: {},\n  view: (state, server) => \`\${server.count}\`,\n}\n`
+  )
+
+  const specs = await loadPages(root)
+  const storey = specs.find(s => s.route === '/storey')
+  fs.rmSync(root, { recursive: true, force: true })
+
+  if (!storey) throw new Error('loadPages did not find the /storey spec')
+  if (!storey.hydrate) throw new Error('store-only spec should have gotten a hydrate URL, got: ' + storey.hydrate)
+})
+
 // ---------------------------------------------------------------------------
 // Skill source files
 
@@ -231,6 +255,87 @@ console.log('\nCoverage-check exemptions\n')
 }
 
 // ---------------------------------------------------------------------------
+// pulse start — PORT env var override warning
+// ---------------------------------------------------------------------------
+// Regression: found via a real dogfooding session. A `PORT` env var set on the
+// local machine for unrelated reasons (common in sandboxes/CI) silently
+// overrode --port with no explanation, even though this exact --port usage is
+// the documented local /verify convention (pulse-start.md). The behavior
+// (PORT always wins — correct for real PaaS deployment) is unchanged; this
+// only adds a visible warning when the override actually happens.
+
+{
+  console.log('\npulse start — PORT env var override\n')
+
+  const { spawnSync } = await import('child_process')
+  const os             = (await import('os')).default
+  const fsMod          = await import('fs')
+
+  function scaffoldMinimalBuiltProject() {
+    const dir = fsMod.mkdtempSync(path.join(os.tmpdir(), 'pulse-start-test-'))
+    fsMod.mkdirSync(path.join(dir, 'src', 'pages'), { recursive: true })
+    fsMod.mkdirSync(path.join(dir, 'public', 'dist'), { recursive: true })
+    fsMod.writeFileSync(path.join(dir, 'src', 'pages', 'home.js'),
+      `export default { route: '/', state: {}, view: () => '<main id="main-content">hi</main>' }`)
+    // start.js only needs public/dist/ + manifest.json to exist to pass its
+    // pre-flight checks — a real build isn't necessary to test port selection.
+    fsMod.writeFileSync(path.join(dir, 'public', 'dist', 'manifest.json'), '{}')
+    return dir
+  }
+
+  const startScriptPath = path.join(__dirname, 'start.js')
+
+  function runStart(dir, portFlag, env) {
+    const args = ['--root', dir]
+    if (portFlag) args.push('--port', String(portFlag))
+    return spawnSync(process.execPath, [startScriptPath, ...args], {
+      encoding: 'utf8',
+      timeout: 5000,
+      env: { ...process.env, ...env },
+    })
+  }
+
+  test('warns to stderr when PORT env var overrides an explicit --port flag', () => {
+    const dir = scaffoldMinimalBuiltProject()
+    try {
+      const result = runStart(dir, 3001, { PORT: '9999' })
+      if (!result.stderr.includes('PORT=9999') || !result.stderr.includes('overrides --port 3001'))
+        throw new Error(`Expected an override warning naming both ports, got stderr: ${result.stderr}`)
+    } finally {
+      cleanupTmpDir(dir)
+    }
+  })
+
+  test('no warning when PORT env var matches the requested --port', () => {
+    const dir = scaffoldMinimalBuiltProject()
+    try {
+      const result = runStart(dir, 3001, { PORT: '3001' })
+      if (result.stderr.includes('overrides --port'))
+        throw new Error(`Should not warn when PORT matches --port, got stderr: ${result.stderr}`)
+    } finally {
+      cleanupTmpDir(dir)
+    }
+  })
+
+  test('no warning when PORT is unset and only --port is used', () => {
+    const dir = scaffoldMinimalBuiltProject()
+    const env = { ...process.env }
+    delete env.PORT
+    try {
+      const result = spawnSync(process.execPath, [startScriptPath, '--root', dir, '--port', '3001'], {
+        encoding: 'utf8', timeout: 5000, env,
+      })
+      if (result.stderr.includes('overrides --port'))
+        throw new Error(`Should not warn when PORT is unset, got stderr: ${result.stderr}`)
+    } finally {
+      cleanupTmpDir(dir)
+    }
+  })
+
+  function cleanupTmpDir(dir) {
+    fsMod.rmSync(dir, { recursive: true, force: true })
+  }
+}
 
 console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed\n`)
 if (failed > 0) process.exit(1)

package/src/cli/dev.js

@@ -217,12 +217,57 @@ async function triggerReload(label = 'File changed') {
   }, 200)
 }
 
+// fs.watch's returned FSWatcher emits 'error' rather than throwing — with no
+// listener, that error is unhandled and crashes the whole dev server (a real,
+// confirmed failure: EMFILE from accumulated file descriptors, e.g. orphaned
+// dev-server processes left running from earlier sessions, took down the
+// process with a raw stack trace instead of a readable message). Wrap every
+// fs.watch call so exhaustion degrades to a warning — hot reload stops
+// working, but the dev server and the rest of the session stay up.
+//
+// EMFILE here isn't always this process's own fd usage — confirmed on a real
+// machine where this fired with the dev server holding only ~20 fds total,
+// while macOS's shared FSEvents/kqueue watcher infrastructure was under
+// system-wide pressure from unrelated apps (VS Code/Electron windows, etc.).
+// That kind of pressure is often transient, so retry once after a short
+// delay before giving up for the rest of the session — recovers
+// automatically if the spike clears, same "disabled until restart" fallback
+// as before if it doesn't.
+const WATCH_RETRY_DELAY_MS = 3000
+
+function watchSafely(target, options, onChange, isRetry = false) {
+  try {
+    const watcher = fs.watch(target, options, onChange)
+    watcher.on('error', (err) => {
+      if ((err.code === 'EMFILE' || err.code === 'ENOSPC') && !isRetry) {
+        log.error(
+          `File watching hit ${err.code} for ${target} — retrying in ${WATCH_RETRY_DELAY_MS / 1000}s ` +
+          `in case it was a transient spike (another app's file watchers, etc.)...`
+        )
+        setTimeout(() => watchSafely(target, options, onChange, true), WATCH_RETRY_DELAY_MS)
+        return
+      }
+      if (err.code === 'EMFILE' || err.code === 'ENOSPC') {
+        log.error(
+          `File watching disabled for ${target} (${err.code}: too many open file watchers, retry also failed). ` +
+          `Hot reload won't work until you restart — check for other running dev servers/processes ` +
+          `holding file watchers open and close them, or raise your OS file descriptor limit.`
+        )
+      } else {
+        log.error(`File watcher error on ${target}: ${err.message}`)
+      }
+    })
+  } catch (err) {
+    log.error(`Could not start file watching for ${target}: ${err.message}`)
+  }
+}
+
 // Watch src/ for changes to existing files (spec edits, component edits)
-fs.watch(path.join(ROOT, 'src'), { recursive: true }, () => triggerReload('File changed'))
+watchSafely(path.join(ROOT, 'src'), { recursive: true }, () => triggerReload('File changed'))
 
 // Watch the store file — it lives in the project root, outside src/
 if (fs.existsSync(path.join(ROOT, 'pulse.store.js'))) {
-  fs.watch(path.join(ROOT, 'pulse.store.js'), () => triggerReload('Store changed'))
+  watchSafely(path.join(ROOT, 'pulse.store.js'), {}, () => triggerReload('Store changed'))
 }
 
 // Also watch the pages directory explicitly so macOS reliably fires on new file creation.
@@ -231,7 +276,7 @@ if (fs.existsSync(path.join(ROOT, 'pulse.store.js'))) {
 // catches the "new entry added to this directory" event.
 const pagesDir = path.join(ROOT, 'src', 'pages')
 if (fs.existsSync(pagesDir)) {
-  fs.watch(pagesDir, { recursive: false }, () => triggerReload('New page detected'))
+  watchSafely(pagesDir, { recursive: false }, () => triggerReload('New page detected'))
 }
 
 // Tiny script injected into every page — connects to SSE and reloads on change

package/src/cli/diagnose.js

@@ -0,0 +1,105 @@
+/**
+ * Pulse — Error journal diagnostics (shared logic)
+ *
+ * The single source of truth for reading and resolving .pulse/errors.json.
+ * Used by both pulse_diagnose/pulse_resolve_error (MCP tools, for an agent)
+ * and `pulse diagnose`/`pulse resolve-error` (CLI commands, for a human).
+ * Neither wraps the other. Returns plain data — no MCP protocol coupling.
+ */
+
+import fs   from 'fs'
+import path from 'path'
+
+function journalPathFor(root) {
+  return path.join(root, '.pulse', 'errors.json')
+}
+
+/**
+ * Read and filter the error journal.
+ *
+ * @param {string} root - project root
+ * @param {{ route?: string, includeResolved?: boolean }} [opts]
+ * @returns {{ exists: boolean, entries: object[], error: string|null }}
+ */
+export function readJournal(root, { route, includeResolved = false } = {}) {
+  const journalPath = journalPathFor(root)
+  if (!fs.existsSync(journalPath)) {
+    return { exists: false, entries: [], error: null }
+  }
+
+  let entries
+  try {
+    entries = JSON.parse(fs.readFileSync(journalPath, 'utf8'))
+  } catch (err) {
+    return { exists: true, entries: [], error: `Error journal exists but could not be parsed: ${err.message}` }
+  }
+
+  let filtered = entries
+  if (route)            filtered = filtered.filter(e => e.route === route)
+  if (!includeResolved) filtered = filtered.filter(e => !e.resolved)
+
+  return { exists: true, entries: filtered, error: null }
+}
+
+/**
+ * Format a journal read result as human-readable text.
+ */
+export function formatJournal(result, { route, includeResolved = false } = {}) {
+  if (result.error) return result.error
+  if (!result.exists) {
+    return 'No errors recorded — .pulse/errors.json does not exist. Either nothing has thrown this session, or the dev server has not been started since it was added.'
+  }
+  if (result.entries.length === 0) {
+    return route
+      ? `No unresolved errors for route "${route}".${includeResolved ? '' : ' (Pass includeResolved: true to see resolved entries too.)'}`
+      : 'No unresolved errors recorded.'
+  }
+
+  const entries = result.entries
+  const lines = [`## ${entries.length} error${entries.length === 1 ? '' : 's'}${route ? ` on ${route}` : ''}\n`]
+  for (const e of entries.slice().reverse()) {
+    lines.push(`### ${e.phase} — ${e.route || '(unknown route)'} — ${e.ts}`)
+    lines.push(`\`${e.id}\`${e.resolved ? ' (resolved)' : ''}`)
+    lines.push(`\n${e.message}\n`)
+    if (e.stack) lines.push('```\n' + e.stack + '\n```\n')
+  }
+  return lines.join('\n')
+}
+
+/**
+ * Mark journal entries resolved by id or by route.
+ *
+ * @param {string} root - project root
+ * @param {{ id?: string, route?: string }} opts
+ * @returns {{ error: string|null, count: number }}
+ */
+export function resolveEntries(root, { id, route } = {}) {
+  if (!id && !route) return { error: 'Error: pass either id or route.', count: 0 }
+
+  const journalPath = journalPathFor(root)
+  if (!fs.existsSync(journalPath)) return { error: 'No error journal exists — nothing to resolve.', count: 0 }
+
+  let entries
+  try {
+    entries = JSON.parse(fs.readFileSync(journalPath, 'utf8'))
+  } catch (err) {
+    return { error: `Error journal could not be parsed: ${err.message}`, count: 0 }
+  }
+
+  let count = 0
+  for (const e of entries) {
+    if (e.resolved) continue
+    if (id && e.id === id) { e.resolved = true; count++ }
+    if (route && e.route === route) { e.resolved = true; count++ }
+  }
+
+  fs.writeFileSync(journalPath, JSON.stringify(entries, null, 2), 'utf8')
+  return { error: null, count }
+}
+
+export function formatResolveResult(result) {
+  if (result.error) return result.error
+  return result.count > 0
+    ? `✓ Resolved ${result.count} entr${result.count === 1 ? 'y' : 'ies'}.`
+    : 'No matching unresolved entries found.'
+}