@ijfw/memory-server 1.4.4 → 1.5.0

package/src/cross-project-search.js

@@ -1,50 +1,236 @@
 // --- cross-project-search: BM25 search across every registered IJFW project ---
 //
-// Complements the existing naive keyword-count searchAcrossProjects in
-// server.js. Builds a corpus of (project, source, line) docs from each
+// Canonical cross-project search surface. The legacy naive-keyword-count
+// `searchAcrossProjects` in server.js was removed in v1.5.1 H1.5 (audit
+// finding memory-engine.md F-FUN-4) — `scope:'all'` on the MCP search tool
+// now routes here. Builds a corpus of (project, source, line) docs from each
 // registered project's memory files, hands it to the BM25 ranker in
 // search-bm25.js, and returns hits tagged with [project:<basename>].
 //
 // Pure + injectable. The caller supplies the registry reader and the
 // per-project memory reader so this module can be unit-tested without
 // touching the home directory.
+//
+// v1.5.0 audit-H3.4 (memory-engine.md F-SEC-1): registry entries are
+// treated as UNTRUSTED. Each entry.path is:
+//   1. realpath-resolved (symlinks resolved against the filesystem)
+//   2. containment-checked against `allowedRoots` (default: $HOME)
+//   3. silently skipped if it escapes the allowed roots OR fails realpath
+//   4. logged to stderr ONCE per unique offending raw-path (Set dedup)
+// Threat model: a compromised dep / malicious project that writes a
+// registry entry pointing at /etc/passwd via a symlink in the user's
+// home directory will be caught by step 1+2. Plain `isAbsolute()` was
+// the only prior validation and was insufficient.
 
-import { basename } from 'node:path';
+import { basename, resolve, join } from 'node:path';
+import { realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { searchCorpus } from './search-bm25.js';
 
+// v1.5.0 audit MED #10 (memory-engine.md F-SPD-2): per-project corpus
+// cache keyed on (canonicalProjectPath, signature) where `signature` is
+// the joined mtimes of the project's memory files. As long as nothing
+// has changed under .ijfw/memory the cache hits and we skip the
+// readProjectMemory() call entirely. Cache is module-local; tests can
+// reset via _resetCorpusCache(). Cap at 64 entries (LRU-ish via Map
+// insertion order) so a long-lived dashboard process can't OOM the cache.
+const CORPUS_CACHE = new Map();
+const CORPUS_CACHE_CAP = 64;
+
+/** Reset the corpus mtime cache. Test-only. */
+export function _resetCorpusCache() {
+  CORPUS_CACHE.clear();
+}
+
+// Files that participate in the cache signature. Match the readers used
+// by readProjectMemory in server.js so an edit to any of them busts the
+// cache. Missing files contribute "0" -- creation of a previously-missing
+// file is a cache-bust on its own.
+const CACHE_SIGNATURE_FILES = [
+  ['.ijfw', 'memory', 'knowledge.md'],
+  ['.ijfw', 'memory', 'project-journal.md'],
+  ['.ijfw', 'memory', 'handoff.md'],
+  ['.ijfw', 'memory', 'team-knowledge.md'],
+];
+
+function computeProjectSignature(canonicalProjectPath) {
+  let sig = '';
+  for (const parts of CACHE_SIGNATURE_FILES) {
+    const p = join(canonicalProjectPath, ...parts);
+    try {
+      const s = statSync(p);
+      sig += `${s.mtimeMs.toFixed(3)}:${s.size}|`;
+    } catch {
+      sig += '0|';
+    }
+  }
+  return sig;
+}
+
+function getCachedDocs(canonicalProjectPath) {
+  const sig = computeProjectSignature(canonicalProjectPath);
+  const cached = CORPUS_CACHE.get(canonicalProjectPath);
+  if (cached && cached.sig === sig) {
+    // LRU touch: re-insert at the end of the Map iteration order.
+    CORPUS_CACHE.delete(canonicalProjectPath);
+    CORPUS_CACHE.set(canonicalProjectPath, cached);
+    return cached.docs;
+  }
+  return null;
+}
+
+function setCachedDocs(canonicalProjectPath, docs) {
+  const sig = computeProjectSignature(canonicalProjectPath);
+  CORPUS_CACHE.set(canonicalProjectPath, { sig, docs });
+  // Trim oldest entry if we're over the cap. Map iteration is insertion
+  // order so the first key is the oldest.
+  if (CORPUS_CACHE.size > CORPUS_CACHE_CAP) {
+    const oldestKey = CORPUS_CACHE.keys().next().value;
+    if (oldestKey !== undefined) CORPUS_CACHE.delete(oldestKey);
+  }
+}
+
+// Module-level dedup set for "skipped offender" stderr noise control.
+// Keyed by the raw entry.path (the attacker-controlled string) so the same
+// malicious entry is reported only once per process lifetime. Exported for
+// test reset via `_resetSkipLog()`.
+const SKIP_LOG = new Set();
+
+/** Reset the skip-log dedup set. Test-only. */
+export function _resetSkipLog() {
+  SKIP_LOG.clear();
+}
+
+/** Default allowed roots: just the user's home directory.
+ *  Tests can pass `opts.allowedRoots` to constrain or widen.
+ *  Returned as resolved (realpath'd) absolute paths so containment
+ *  comparison is apples-to-apples with the realpath'd entry. */
+function defaultAllowedRoots() {
+  const roots = [];
+  try {
+    const home = homedir();
+    if (home && typeof home === 'string') {
+      // realpath the root itself so /var/root on macOS resolves to
+      // /private/var/root (same canonicalization as the entry side).
+      try { roots.push(realpathSync(home)); } catch { roots.push(resolve(home)); }
+    }
+  } catch { /* ignore */ }
+  return roots;
+}
+
+/** True iff `child` is `root` or a path nested under `root`.
+ *  Both inputs are expected to be already-canonical absolute paths.
+ *  We compare with a trailing-separator guard so `/home/alice-evil`
+ *  is NOT considered inside `/home/alice`. */
+function isUnder(child, root) {
+  if (!child || !root) return false;
+  if (child === root) return true;
+  // Use both POSIX and Windows separators defensively. Path normalization
+  // has already happened via realpathSync; we just need the boundary check.
+  const withPosixSep   = root.endsWith('/')  ? root : root + '/';
+  const withWindowsSep = root.endsWith('\\') ? root : root + '\\';
+  return child.startsWith(withPosixSep) || child.startsWith(withWindowsSep);
+}
+
+/** Resolve + containment check.
+ *  Returns the canonical path on success, or null if the entry must be
+ *  skipped. On skip, logs to stderr once per unique raw path. */
+function safeResolveProjectPath(rawPath, allowedRoots) {
+  if (!rawPath || typeof rawPath !== 'string') {
+    return _skip(rawPath, 'not-a-string');
+  }
+  let canonical;
+  try {
+    // realpathSync resolves symlinks. If the entry points to a symlink
+    // chain whose target escapes allowedRoots, this is where we catch it.
+    canonical = realpathSync(rawPath);
+  } catch {
+    // ENOENT / EACCES / ELOOP — entry path doesn't exist or is unreadable.
+    // Graceful skip; don't throw (a stale registry shouldn't crash search).
+    return _skip(rawPath, 'realpath-failed');
+  }
+  if (!allowedRoots.some(root => isUnder(canonical, root))) {
+    return _skip(rawPath, `escapes-allowed-roots (realpath=${canonical})`);
+  }
+  return canonical;
+}
+
+function _skip(rawPath, reason) {
+  const key = String(rawPath || '<null>');
+  if (!SKIP_LOG.has(key)) {
+    SKIP_LOG.add(key);
+    try {
+      // Single-line, stderr-only — same posture as the rest of the engine's
+      // advisory warnings. Production callers (Claude Code) capture stderr
+      // and surface in the dashboard's diagnostics tab.
+      process.stderr.write(
+        `[ijfw cross-project-search] skipped registry entry: ${reason}: ${key}\n`
+      );
+    } catch { /* never let a logging failure break search */ }
+  }
+  return null;
+}
+
 // Build a corpus of line-level docs from the provided projects.
 //   projects: [{ path, hash?, iso? }]
 //   readProjectMemory(path) -> { knowledge, journal, handoff }  (strings)
+//   opts.allowedRoots: optional array of canonical absolute roots; entries
+//                      whose realpath escapes ALL of them are skipped.
+//                      Default: [realpath(homedir())].
 // Returns [{ id, text, meta }] where meta carries project + source + lineNo.
-export function buildCorpus(projects, readProjectMemory) {
+export function buildCorpus(projects, readProjectMemory, opts = {}) {
+  const allowedRoots = Array.isArray(opts.allowedRoots) && opts.allowedRoots.length
+    ? opts.allowedRoots
+    : defaultAllowedRoots();
   const docs = [];
   for (const entry of projects) {
-    const tag = basename(entry.path);
-    const mem = readProjectMemory(entry.path) || {};
+    if (!entry || typeof entry !== 'object') continue;
+    const canonical = safeResolveProjectPath(entry.path, allowedRoots);
+    if (canonical === null) continue;  // skipped (symlink-escape or missing)
+
+    // v1.5.0 audit MED #10: try the mtime cache before re-reading.
+    // The cache is opt-out via opts.useCache=false (tests / consistency runs).
+    const useCache = opts.useCache !== false;
+    let projectDocs = useCache ? getCachedDocs(canonical) : null;
+    if (projectDocs) {
+      for (const d of projectDocs) docs.push(d);
+      continue;
+    }
+
+    const tag = basename(canonical);
+    // Pass the CANONICAL path to the reader, not the raw one — so a reader
+    // that joins with `.ijfw/memory/...` walks the canonical tree, not a
+    // possibly-spoofed symlink chain.
+    const mem = readProjectMemory(canonical) || {};
+    projectDocs = [];
     for (const [source, content] of Object.entries(mem)) {
       if (typeof content !== 'string' || content.length === 0) continue;
       const lines = content.split('\n');
       for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
         if (line.trim().length === 0) continue;
-        docs.push({
+        projectDocs.push({
           id: `${tag}:${source}:${i + 1}`,
           text: line,
-          meta: { project: tag, projectPath: entry.path, source, lineNo: i + 1 },
+          meta: { project: tag, projectPath: canonical, source, lineNo: i + 1 },
         });
       }
     }
+    if (useCache) setCachedDocs(canonical, projectDocs);
+    for (const d of projectDocs) docs.push(d);
   }
   return docs;
 }
 
 // Run a BM25-ranked search across the corpus produced from `projects`.
 // Returns [{ content, source, line, project, score, snippet }], capped at limit.
+//   opts.allowedRoots: forwarded to buildCorpus (see above).
+//   opts.limit: 1..50, default 10.
 export function crossProjectSearch(query, projects, readProjectMemory, opts = {}) {
   const limit = clamp(opts.limit, 1, 50, 10);
   if (!query || typeof query !== 'string') return [];
 
-  const docs = buildCorpus(projects, readProjectMemory);
+  const docs = buildCorpus(projects, readProjectMemory, opts);
   if (docs.length === 0) return [];
 
   const hits = searchCorpus(query, docs, { limit });

package/src/dashboard-client-waves.html

@@ -0,0 +1,304 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>IJFW · Waves</title>
+<style>
+  :root { color-scheme: light dark; }
+  * { box-sizing: border-box; }
+  body { margin: 0; font: 14px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; background: #fafafa; color: #222; }
+  header { padding: 12px 20px; border-bottom: 1px solid #ddd; background: #fff; }
+  header h1 { margin: 0; font-size: 18px; font-weight: 600; }
+  header .sub { color: #777; font-size: 12px; margin-top: 4px; }
+  main { padding: 20px; max-width: 1200px; margin: 0 auto; }
+  .layout { display: grid; grid-template-columns: 320px 1fr; gap: 20px; min-height: 500px; }
+  .sidebar { background: #fff; border: 1px solid #ddd; border-radius: 6px; overflow: hidden; }
+  .sidebar-header { padding: 10px 14px; font-weight: 600; border-bottom: 1px solid #eee; font-size: 13px; color: #555; }
+  .wave-list { max-height: 70vh; overflow-y: auto; }
+  .wave-row { padding: 10px 14px; border-bottom: 1px solid #f0f0f0; cursor: pointer; display: grid; grid-template-columns: 1fr auto; gap: 4px; }
+  .wave-row:hover { background: #f4f8ff; }
+  .wave-row.selected { background: #eaf3ff; }
+  .wave-row .id { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 13px; font-weight: 600; }
+  .wave-row .status { font-size: 11px; padding: 1px 6px; border-radius: 3px; background: #eee; color: #555; text-transform: uppercase; align-self: center; }
+  .wave-row.status-done .status { background: #d6f5d6; color: #1a6b1a; }
+  .wave-row.status-in_progress .status { background: #fff4cc; color: #7a5a00; }
+  .wave-row.status-blocked .status { background: #fbd5d5; color: #8a1a1a; }
+  .wave-row .ts { grid-column: 1 / -1; font-size: 11px; color: #888; }
+  .viewer { background: #fff; padding: 24px 28px; border: 1px solid #ddd; border-radius: 6px; min-height: 500px; }
+  .meta { font-size: 12px; color: #666; margin-bottom: 16px; padding-bottom: 10px; border-bottom: 1px solid #eee; }
+  .meta .meta-row { display: inline-block; margin-right: 16px; }
+  .meta strong { color: #333; }
+  .doc h1 { font-size: 22px; margin: 0 0 12px; }
+  .doc h2 { font-size: 18px; margin: 24px 0 10px; padding-bottom: 4px; border-bottom: 1px solid #eee; }
+  .doc h3 { font-size: 15px; margin: 20px 0 8px; }
+  .doc pre { background: #f4f4f4; padding: 12px; border-radius: 4px; overflow-x: auto; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; }
+  .doc code { background: #f4f4f4; padding: 1px 4px; border-radius: 3px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; }
+  .doc pre code { background: transparent; padding: 0; }
+  .doc table { border-collapse: collapse; margin: 12px 0; }
+  .doc th, .doc td { border: 1px solid #ddd; padding: 6px 10px; text-align: left; font-size: 13px; }
+  .doc th { background: #f4f4f4; }
+  .doc blockquote { border-left: 3px solid #ccc; padding-left: 12px; color: #666; margin: 12px 0; }
+  .err { color: #c00; font-style: italic; }
+  .hint { color: #777; font-style: italic; }
+  @media (prefers-color-scheme: dark) {
+    body { background: #1a1a1a; color: #ddd; }
+    header, .sidebar, .viewer { background: #222; border-color: #333; }
+    .sidebar-header, .meta { border-color: #2e2e2e; color: #aaa; }
+    .wave-row { border-color: #2a2a2a; }
+    .wave-row:hover { background: #2a2f3a; }
+    .wave-row.selected { background: #2c3548; }
+    .wave-row .status { background: #333; color: #ccc; }
+    .doc pre, .doc code, .doc th { background: #2a2a2a; }
+  }
+</style>
+</head>
+<body>
+<header>
+  <h1>IJFW · Waves</h1>
+  <div class="sub">Live state of .ijfw/wave-*/STATE.md across the current project.</div>
+</header>
+<main>
+  <div class="layout">
+    <aside class="sidebar">
+      <div class="sidebar-header">Waves (newest first)</div>
+      <div class="wave-list" id="waveList"></div>
+    </aside>
+    <section class="viewer">
+      <div class="meta" id="waveMeta"></div>
+      <div id="doc" class="doc"></div>
+    </section>
+  </div>
+</main>
+<script>
+  // Reused markdown shim from /planning — produces a safe DOMFragment, no innerHTML.
+  // Handles headings, paragraphs, code blocks, inline code/bold/italic, links,
+  // lists, blockquotes, tables. Not full CommonMark.
+
+  function setText(el, text) {
+    while (el.firstChild) el.removeChild(el.firstChild);
+    el.appendChild(document.createTextNode(text));
+  }
+  function setStatus(el, text, cls) {
+    while (el.firstChild) el.removeChild(el.firstChild);
+    const div = document.createElement('div');
+    div.className = cls;
+    div.textContent = text;
+    el.appendChild(div);
+  }
+
+  function makeNode(tag, text) {
+    const el = document.createElement(tag);
+    if (text !== undefined) el.appendChild(document.createTextNode(text));
+    return el;
+  }
+
+  function renderInlineToNodes(s) {
+    const nodes = [];
+    let i = 0;
+    while (i < s.length) {
+      if (s[i] === '`') {
+        const end = s.indexOf('`', i + 1);
+        if (end !== -1) { nodes.push(makeNode('code', s.slice(i + 1, end))); i = end + 1; continue; }
+      }
+      if (s[i] === '*' && s[i + 1] === '*') {
+        const end = s.indexOf('**', i + 2);
+        if (end !== -1) { nodes.push(makeNode('strong', s.slice(i + 2, end))); i = end + 2; continue; }
+      }
+      if (s[i] === '*') {
+        const end = s.indexOf('*', i + 1);
+        if (end !== -1 && end - i > 1) { nodes.push(makeNode('em', s.slice(i + 1, end))); i = end + 1; continue; }
+      }
+      if (s[i] === '[') {
+        const close = s.indexOf(']', i + 1);
+        if (close !== -1 && s[close + 1] === '(') {
+          const urlEnd = s.indexOf(')', close + 2);
+          if (urlEnd !== -1) {
+            const a = document.createElement('a');
+            a.textContent = s.slice(i + 1, close);
+            // r13-L-01: tightened URL guard. ALLOW http/https + same-origin relative.
+            // BLOCK javascript:, data:, mailto:, vbscript:, file:, AND protocol-relative `//`.
+            const url = s.slice(close + 2, urlEnd);
+            const isAllowed = (
+              /^https?:\/\//.test(url) ||
+              (!url.startsWith('//') && !/^[^:/?#]+:/.test(url))
+            );
+            if (isAllowed) { a.href = url; a.target = '_blank'; a.rel = 'noopener'; }
+            nodes.push(a);
+            i = urlEnd + 1;
+            continue;
+          }
+        }
+      }
+      let j = i;
+      while (j < s.length && !'`*['.includes(s[j])) j++;
+      if (j === i) j = i + 1;
+      nodes.push(document.createTextNode(s.slice(i, j)));
+      i = j;
+    }
+    return nodes;
+  }
+
+  function renderMarkdownToFragment(md) {
+    const frag = document.createDocumentFragment();
+    const lines = md.split('\n');
+    let i = 0;
+    while (i < lines.length) {
+      const line = lines[i];
+      if (/^```/.test(line)) {
+        const buf = []; i++;
+        while (i < lines.length && !/^```/.test(lines[i])) { buf.push(lines[i]); i++; }
+        i++;
+        const pre = document.createElement('pre');
+        const code = document.createElement('code');
+        code.textContent = buf.join('\n');
+        pre.appendChild(code);
+        frag.appendChild(pre);
+        continue;
+      }
+      const h = line.match(/^(#{1,6})\s+(.*)$/);
+      if (h) {
+        const tag = 'h' + h[1].length;
+        const el = document.createElement(tag);
+        for (const n of renderInlineToNodes(h[2])) el.appendChild(n);
+        frag.appendChild(el); i++; continue;
+      }
+      if (/^\s*\|/.test(line) && i + 1 < lines.length && /^\s*\|?\s*-/.test(lines[i + 1])) {
+        const tbl = document.createElement('table');
+        const head = line.split('|').slice(1, -1).map((c) => c.trim());
+        const tr = document.createElement('tr');
+        for (const c of head) {
+          const th = document.createElement('th');
+          for (const n of renderInlineToNodes(c)) th.appendChild(n);
+          tr.appendChild(th);
+        }
+        tbl.appendChild(tr); i += 2;
+        while (i < lines.length && /^\s*\|/.test(lines[i])) {
+          const cells = lines[i].split('|').slice(1, -1).map((c) => c.trim());
+          const row = document.createElement('tr');
+          for (const c of cells) {
+            const td = document.createElement('td');
+            for (const n of renderInlineToNodes(c)) td.appendChild(n);
+            row.appendChild(td);
+          }
+          tbl.appendChild(row); i++;
+        }
+        frag.appendChild(tbl); continue;
+      }
+      if (/^\s*[-*]\s+/.test(line)) {
+        const ul = document.createElement('ul');
+        while (i < lines.length && /^\s*[-*]\s+/.test(lines[i])) {
+          const li = document.createElement('li');
+          for (const n of renderInlineToNodes(lines[i].replace(/^\s*[-*]\s+/, ''))) li.appendChild(n);
+          ul.appendChild(li); i++;
+        }
+        frag.appendChild(ul); continue;
+      }
+      if (/^>\s?/.test(line)) {
+        const bq = document.createElement('blockquote');
+        let first = true;
+        while (i < lines.length && /^>\s?/.test(lines[i])) {
+          if (!first) bq.appendChild(document.createElement('br'));
+          for (const n of renderInlineToNodes(lines[i].replace(/^>\s?/, ''))) bq.appendChild(n);
+          first = false; i++;
+        }
+        frag.appendChild(bq); continue;
+      }
+      if (line.trim() === '') { i++; continue; }
+      const p = document.createElement('p');
+      const buf = [line]; i++;
+      while (i < lines.length && lines[i].trim() !== '' && !/^(#{1,6}\s|```|>|\s*[-*]\s|\s*\|)/.test(lines[i])) {
+        buf.push(lines[i]); i++;
+      }
+      for (const n of renderInlineToNodes(buf.join(' '))) p.appendChild(n);
+      frag.appendChild(p);
+    }
+    return frag;
+  }
+
+  // ---------- wave list + viewer ----------
+
+  let selectedRow = null;
+
+  function renderMeta(w) {
+    const meta = document.getElementById('waveMeta');
+    while (meta.firstChild) meta.removeChild(meta.firstChild);
+    const fields = [
+      ['Wave', w.id],
+      ['Status', w.status],
+      ['Created', w.created_at ?? '—'],
+      ['Checkpoint', w.checkpoint_at ?? '—'],
+      ['Agents', String(w.agents_count ?? 0)],
+      ['Active claims', String(w.claims_active ?? 0)],
+      ['Open blockers', String(w.blockers_open ?? 0)],
+    ];
+    for (const [label, val] of fields) {
+      const row = document.createElement('span');
+      row.className = 'meta-row';
+      const lab = document.createElement('strong');
+      lab.textContent = label + ': ';
+      row.appendChild(lab);
+      row.appendChild(document.createTextNode(val));
+      meta.appendChild(row);
+    }
+  }
+
+  async function loadWaveState(w, row) {
+    if (selectedRow) selectedRow.classList.remove('selected');
+    if (row) { row.classList.add('selected'); selectedRow = row; }
+    renderMeta(w);
+    const doc = document.getElementById('doc');
+    setStatus(doc, 'Loading…', 'hint');
+    try {
+      const r = await fetch('/api/planning?path=' + encodeURIComponent(w.path));
+      if (!r.ok) {
+        const err = await r.json().catch(() => ({ error: 'unknown' }));
+        setStatus(doc, r.status + ': ' + (err.error || 'failed'), 'err');
+        return;
+      }
+      const j = await r.json();
+      while (doc.firstChild) doc.removeChild(doc.firstChild);
+      doc.appendChild(renderMarkdownToFragment(j.body || ''));
+    } catch (e) {
+      setStatus(doc, e.message, 'err');
+    }
+  }
+
+  async function loadWaves() {
+    const list = document.getElementById('waveList');
+    setStatus(list, 'Loading…', 'hint');
+    try {
+      const r = await fetch('/api/waves');
+      const j = await r.json();
+      while (list.firstChild) list.removeChild(list.firstChild);
+      const waves = j.waves || [];
+      if (waves.length === 0) {
+        setStatus(list, 'No waves found in .ijfw/wave-*/', 'hint');
+        setStatus(document.getElementById('doc'),
+          'No wave-* directories exist yet. Dispatch a wave via /superpowers:subagent-driven-development to see live state here.',
+          'hint');
+        return;
+      }
+      for (const w of waves) {
+        const row = document.createElement('div');
+        row.className = 'wave-row status-' + (w.status || 'unknown');
+        const id = document.createElement('div'); id.className = 'id'; id.textContent = w.id;
+        const status = document.createElement('div'); status.className = 'status'; status.textContent = w.status || 'unknown';
+        const ts = document.createElement('div'); ts.className = 'ts'; ts.textContent = w.checkpoint_at ?? (w.created_at ?? '');
+        row.appendChild(id); row.appendChild(status); row.appendChild(ts);
+        row.addEventListener('click', () => loadWaveState(w, row));
+        list.appendChild(row);
+      }
+      // Auto-select first (newest) wave.
+      const first = list.firstChild;
+      if (first) loadWaveState(waves[0], first);
+    } catch (e) {
+      setStatus(list, e.message, 'err');
+    }
+  }
+
+  setStatus(document.getElementById('doc'), 'Select a wave from the list to view its STATE.md.', 'hint');
+  loadWaves();
+</script>
+</body>
+</html>

package/src/dashboard-client.html

@@ -255,6 +255,10 @@ tr:hover td{background:var(--surface)}
     <div class="breadcrumb" id="breadcrumb"><span style="color:var(--fg-dim)">Overview</span> <b>Today</b></div>
     <div class="spacer"></div>
     <span class="tier-pill">MAX 20x</span>
+    <!-- v1.5.0 N4.obs M5: cross-link back to the operator dashboard (port
+         19747). Operators flip between MCP (wave/orchestrator views) and
+         operator (cost/memory views) so the link is reciprocal. -->
+    <a class="icon-btn" id="operatorDashLink" href="http://localhost:19747/" target="_blank" rel="noopener" title="Open operator dashboard (cost + memory views)">Operator dashboard</a>
     <button class="icon-btn" id="themeBtn" aria-label="Toggle theme">&#9790; Theme</button>
   </header>
 
@@ -275,7 +279,7 @@ tr:hover td{background:var(--surface)}
         <div class="hcard">
           <div class="hlabel"><span class="pulse"></span> Active Session</div>
           <div class="hval" style="font-size:20px;padding-top:6px">ijfw</div>
-          <div class="hsub">claude-opus-4-6 -- <b>current</b></div>
+          <div class="hsub">claude-opus-4-7 -- <b>current</b></div>
         </div>
         <div class="hcard">
           <div class="hlabel">Cache Efficiency</div>

package/src/dashboard-server.js

@@ -513,6 +513,79 @@ export async function startServer(options = {}) {
       }
     }],
 
+    // v1.5.0 S10 — wave-state JSON list. Reads .ijfw/wave-*/STATE.md frontmatter.
+    // Sorted by checkpoint_at desc, capped at 50 (any project with >50 active
+    // waves has bigger problems). Same security pattern as /api/planning.
+    ['/api/waves', async (req, res) => {
+      try {
+        const ijfwDir = join(REPO_ROOT, '.ijfw');
+        if (!existsSync(ijfwDir)) {
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ waves: [] }));
+          return;
+        }
+        const entries = readdirSync(ijfwDir, { withFileTypes: true });
+        const { readWaveState } = await import('./orchestrator/wave-state.js');
+        const out = [];
+        for (const ent of entries) {
+          if (!ent.isDirectory() || !ent.name.startsWith('wave-')) continue;
+          const waveId = ent.name.slice('wave-'.length);
+          if (!waveId || !/^[A-Za-z0-9_-]+$/.test(waveId)) continue;
+          try {
+            const state = await readWaveState(waveId, REPO_ROOT);
+            if (!state) continue;
+            out.push({
+              id: waveId,
+              status: state.frontmatter.status ?? 'unknown',
+              created_at: state.frontmatter.created_at ?? null,
+              checkpoint_at: state.frontmatter.checkpoint_at ?? null,
+              claims_active: state.frontmatter.claims_active ?? 0,
+              agents_count: Array.isArray(state.frontmatter.agents) ? state.frontmatter.agents.length : 0,
+              path: `.ijfw/wave-${waveId}/STATE.md`,
+            });
+          } catch { /* skip malformed wave dirs */ }
+        }
+        out.sort((a, b) => String(b.checkpoint_at || '').localeCompare(String(a.checkpoint_at || '')));
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ waves: out.slice(0, 50) }));
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: err.message, endpoint: '/api/waves' }));
+      }
+    }],
+
+    // v1.5.0 S10 — wave-state viewer (HTML SPA). Same CSP as /planning.
+    ['/waves', async (req, res) => {
+      try {
+        const html = await readFile(join(__dirname, 'dashboard-client-waves.html'), 'utf8');
+        res.writeHead(200, {
+          'Content-Type': 'text/html; charset=utf-8',
+          'Cache-Control': 'no-store',
+          'Content-Security-Policy': "default-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline'; connect-src 'self'",
+        });
+        res.end(html);
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'text/plain' });
+        res.end('Waves viewer not found: ' + err.message);
+      }
+    }],
+
+    // v1.5.0 F4 — serve checkpoint-contract.md as plain text so operators can
+    // find the implementer-side checkpoint protocol from the dashboard.
+    ['/docs/checkpoint-contract', async (req, res) => {
+      try {
+        const md = await readFile(join(__dirname, 'orchestrator/checkpoint-contract.md'), 'utf8');
+        res.writeHead(200, {
+          'Content-Type': 'text/plain; charset=utf-8',
+          'Cache-Control': 'public, max-age=300',
+        });
+        res.end(md);
+      } catch (err) {
+        res.writeHead(404, { 'Content-Type': 'text/plain' });
+        res.end('Checkpoint contract not found: ' + err.message);
+      }
+    }],
+
     ['/api/memory/file', (req, res, url) => {
       const rawPath = url.searchParams.get('path') || '';
       if (!rawPath) {