@ijfw/memory-server 1.4.3 → 1.4.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ijfw/memory-server",
-  "version": "1.4.3",
+  "version": "1.4.4",
   "description": "Cross-platform persistent memory server for IJFW. 10 MCP tools (memory + admin/update). Works with 13 MCP-using platforms (Claude Code, Codex, Gemini CLI, Cursor, Windsurf, Copilot, Hermes, Wayland, OpenCode, QwenCode, Cline, KimiCode, OpenClaw) plus Aider via rules-only tier.",
   "author": "Sean Donahoe",
   "license": "MIT",

package/src/cross-orchestrator.js

@@ -15,8 +15,10 @@
 
 import { spawn } from 'node:child_process';
 import * as readline from 'node:readline';
-import { pickAuditors, isReachable } from './audit-roster.js';
-import { loadSwarmConfig } from './swarm-config.js';
+import { readdirSync, mkdirSync, writeFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { pickAuditors, isReachable, ROSTER } from './audit-roster.js';
+import { loadSwarmConfig, DEFAULT_AUDITORS } from './swarm-config.js';
 import { buildRequest, parseResponse, mergeResponses, checkBudget } from './cross-dispatcher.js';
 import { writeReceipt, readReceipts } from './receipts.js';
 import { runViaApi } from './api-client.js';
@@ -381,6 +383,158 @@ function countItems(p) {
   return 0;
 }
 
+// ---------------------------------------------------------------------------
+// phase-e-auto helpers (v1.4.4 N10)
+// ---------------------------------------------------------------------------
+
+// Resolve the next CROSS-AUDIT-r<N>.md path under .planning/<phase>/.
+// Scans for existing r<N> files and increments the highest N found.
+function resolveAuditOutputPath(projectDir, phase) {
+  const planningDir = join(projectDir, '.planning', phase);
+  let maxN = 0;
+  if (existsSync(planningDir)) {
+    try {
+      const files = readdirSync(planningDir);
+      for (const f of files) {
+        const m = f.match(/^CROSS-AUDIT-r(\d+)\.md$/);
+        if (m) {
+          const n = parseInt(m[1], 10);
+          if (n > maxN) maxN = n;
+        }
+      }
+    } catch { /* non-fatal */ }
+  }
+  return join(planningDir, `CROSS-AUDIT-r${maxN + 1}.md`);
+}
+
+// Classify a merged audit result into PASS / CONDITIONAL / FAIL.
+// HIGH severity finding → FAIL; any finding → CONDITIONAL; none → PASS.
+function classifyVerdict(items) {
+  if (!Array.isArray(items) || items.length === 0) return 'PASS';
+  const hasHigh = items.some(item => {
+    const sev = (item.severity || item.level || '').toString().toUpperCase();
+    return sev === 'HIGH' || sev === 'CRITICAL';
+  });
+  return hasHigh ? 'FAIL' : 'CONDITIONAL';
+}
+
+// Pick the auditor roster for phase-e-auto from swarm.json (or defaults).
+// Filters to entries that are reachable (CLI or API); missing CLI AND no
+// apiFallback → skipped with a NOTE entry in the return value.
+function resolvePhaseEAuditors(swarmConfig, env) {
+  const requestedIds = (Array.isArray(swarmConfig.auditors) && swarmConfig.auditors.length > 0)
+    ? swarmConfig.auditors
+    : [...DEFAULT_AUDITORS];
+
+  const picks = [];
+  const skipped = [];
+
+  for (const id of requestedIds) {
+    const entry = ROSTER.find(e => e.id === id);
+    if (!entry) {
+      skipped.push({ id, reason: 'not in roster' });
+      continue;
+    }
+    const reach = isReachable(id, env);
+    if (!reach.any) {
+      // CLI missing AND no apiFallback (or key not set) → skip with NOTE
+      skipped.push({ id, reason: 'CLI missing and no apiFallback configured' });
+      continue;
+    }
+    // Annotate API-only picks
+    const pick = (!reach.cli && reach.api) ? { ...entry, preferredSource: 'api' } : { ...entry };
+    picks.push(pick);
+  }
+
+  return { picks, skipped };
+}
+
+// Run the phase-e-auto branch.  Does NOT use process.exit / uxGate / budget
+// guard — it is a programmatic call from the orchestrator, not a CLI call.
+async function runPhaseEAuto({ projectDir, phase, target, env, quiet }) {
+  const swarmConfig = loadSwarmConfig(projectDir);
+  const { picks, skipped } = resolvePhaseEAuditors(swarmConfig, env);
+
+  const notes = skipped.map(s => `NOTE: skipped auditor '${s.id}' — ${s.reason}`);
+
+  if (!quiet && notes.length > 0) {
+    process.stderr.write(notes.join('\n') + '\n');
+  }
+
+  if (picks.length === 0) {
+    const outputPath = resolveAuditOutputPath(projectDir, phase);
+    const content = `# Cross-Audit Phase E\n\nNo auditors available.\n\n${notes.map(n => `- ${n}`).join('\n')}\n`;
+    const dir = dirname(outputPath);
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(outputPath, content, 'utf8');
+    return { verdict: 'CONDITIONAL', findings: [], outputPath, notes };
+  }
+
+  const auditTarget = target || 'HEAD~1..HEAD';
+  const resolvedTimeoutSec = null;
+
+  const requests = picks.map(pick => ({
+    pick,
+    payload: buildRequest('audit', auditTarget, pick.id, 'general', null),
+  }));
+
+  const tasks = requests.map(({ pick, payload }) => () =>
+    fireExternal(pick, payload, timeoutForPick(pick, resolvedTimeoutSec), env)
+  );
+  const rawResults = await fanOut(tasks, 3);
+
+  const auditorResults = rawResults.map((raw, i) => {
+    const pick = picks[i];
+    if (raw === null) {
+      return { status: 'failed', parsed: { items: [], prose: `[${pick.id}: spawn failed]` } };
+    }
+    const { stdout, exitCode, status: rawStatus } = raw;
+    if (rawStatus === 'timeout') return { status: 'timeout', parsed: { items: [], prose: `[${pick.id}: timeout]` } };
+    if (rawStatus === 'failed') return { status: 'failed', parsed: { items: [], prose: `[${pick.id}: failed]` } };
+    if (rawStatus === 'aborted') return { status: 'aborted', parsed: { items: [], prose: `[${pick.id}: aborted]` } };
+    if (rawStatus === 'fallback-used') {
+      const p = parseResponse('audit', stdout);
+      return { status: 'fallback-used', parsed: p };
+    }
+    if (exitCode !== 0) return { status: 'failed', parsed: { items: [], prose: `[${pick.id}: exited ${exitCode}]` } };
+    const p = parseResponse('audit', stdout);
+    return { status: 'ok', parsed: p };
+  });
+
+  const parsed = auditorResults.map(r => r.parsed);
+  const merged = mergeResponses('audit', parsed);
+  const items = Array.isArray(merged) ? merged : [];
+  const verdict = classifyVerdict(items);
+
+  // Write synthesis to .planning/<phase>/CROSS-AUDIT-r<N>.md
+  const outputPath = resolveAuditOutputPath(projectDir, phase);
+  const dir = dirname(outputPath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  const auditorSummary = picks.map((p, i) => `- ${p.id}: ${auditorResults[i].status}`).join('\n');
+  const findingsSection = items.length > 0
+    ? items.map(item => `- [${(item.severity || item.level || 'INFO').toUpperCase()}] ${item.text || item.description || JSON.stringify(item)}`).join('\n')
+    : '_(none)_';
+  const content = [
+    `# Cross-Audit Phase E — ${phase}`,
+    '',
+    `**Verdict:** ${verdict}`,
+    `**Auditors:** ${picks.map(p => p.id).join(', ')}`,
+    '',
+    '## Auditor Status',
+    auditorSummary,
+    '',
+    '## Findings',
+    findingsSection,
+    '',
+    ...(notes.length > 0 ? ['## Notes', ...notes, ''] : []),
+  ].join('\n');
+
+  writeFileSync(outputPath, content, 'utf8');
+
+  return { verdict, findings: items, outputPath, notes };
+}
+
 export async function runCrossOp({
   mode,
   target,
@@ -400,6 +554,14 @@ export async function runCrossOp({
   runStamp   = runStamp   ?? new Date().toISOString();
   env        = env        ?? process.env;
 
+  // v1.4.4 N10: phase-e-auto branch — programmatic orchestrator call.
+  // Reads .ijfw/swarm.json for auditor roster; graceful CLI-missing skip;
+  // writes .planning/<phase>/CROSS-AUDIT-r<N>.md; returns {verdict, findings, outputPath}.
+  if (mode === 'phase-e-auto') {
+    const phase = target || 'current';
+    return runPhaseEAuto({ projectDir, phase, target, env, quiet });
+  }
+
   const start = Date.now();
 
   // Shared abort controller for this run -- used by minResponsesFanOut to kill stragglers.

package/src/dashboard-client-planning.html

@@ -0,0 +1,273 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>IJFW · Planning Docs</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: 900px; margin: 0 auto; }
+  .path-input { width: 100%; padding: 8px 10px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 13px; border: 1px solid #ccc; border-radius: 4px; }
+  .roots { color: #777; font-size: 12px; margin: 8px 0 16px; }
+  .roots code { background: #eee; padding: 1px 5px; border-radius: 3px; }
+  .doc { background: #fff; padding: 24px 28px; border: 1px solid #ddd; border-radius: 6px; min-height: 300px; }
+  .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 { background: #222; border-color: #333; }
+    .doc, .path-input { background: #222; border-color: #333; color: #ddd; }
+    .doc pre, .doc code, .roots code, .doc th { background: #2a2a2a; }
+  }
+</style>
+</head>
+<body>
+<header>
+  <h1>IJFW · Planning Docs</h1>
+  <div class="sub">Browse .planning/, .ijfw/memory/, and .ijfw/wave-*/ docs from this project.</div>
+</header>
+<main>
+  <input type="text" id="path" class="path-input" placeholder=".planning/1.4.4/HANDOFF-1.4.4.md" autofocus>
+  <div class="roots">Allowed roots: .planning/ · .ijfw/memory/ · .ijfw/wave-*/STATE.md · .ijfw/wave-*/SUMMARY.md</div>
+  <div id="doc" class="doc"></div>
+</main>
+<script>
+  // Tiny markdown shim — produces a safe DOMFragment via DOMParser, no innerHTML.
+  // Renders the subset used in IJFW planning docs: headings, paragraphs, code blocks,
+  // inline code/bold/italic, links, lists, blockquotes, tables. Not a 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;
+  }
+
+  // Renders a single line of markdown-inline content into an array of DOM nodes.
+  // Handles `code`, **bold**, *italic*, [text](url). All text is added via
+  // createTextNode — no HTML parsing of user content.
+  function renderInlineToNodes(s) {
+    const nodes = [];
+    let i = 0;
+    while (i < s.length) {
+      // Code span: `...`
+      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;
+        }
+      }
+      // Bold: **...**
+      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;
+        }
+      }
+      // Italic: *...*
+      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;
+        }
+      }
+      // Link: [text](url)
+      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://, and same-origin relative paths (no protocol).
+            // BLOCK: javascript:, data:, mailto:, vbscript:, file:, AND protocol-relative
+            //        URLs starting with `//` (would open cross-origin without scheme).
+            const url = s.slice(close + 2, urlEnd);
+            const isAllowed = (
+              /^https?:\/\//.test(url) ||                  // explicit http/https
+              (!url.startsWith('//') && !/^[^:/?#]+:/.test(url))   // relative, no protocol, no `//`
+            );
+            if (isAllowed) {
+              a.href = url;
+              a.target = '_blank';
+              a.rel = 'noopener';
+            }
+            nodes.push(a);
+            i = urlEnd + 1;
+            continue;
+          }
+        }
+      }
+      // Plain text — accumulate until next special marker
+      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];
+      // Fenced code block
+      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;
+      }
+      // Headings
+      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;
+      }
+      // Table: header row + separator row + rows
+      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;
+      }
+      // Bullet list
+      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;
+      }
+      // Blockquote
+      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;
+      }
+      // Blank
+      if (line.trim() === '') { i++; continue; }
+      // Paragraph
+      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;
+  }
+
+  async function load(path) {
+    const doc = document.getElementById('doc');
+    setStatus(doc, 'Loading…', 'hint');
+    try {
+      const r = await fetch('/api/planning?path=' + encodeURIComponent(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');
+    }
+  }
+
+  // Initial hint
+  setStatus(document.getElementById('doc'),
+    'Enter a relative path above (e.g. .planning/1.4.4/HANDOFF-1.4.4.md) and press Enter.',
+    'hint');
+
+  const input = document.getElementById('path');
+  input.addEventListener('keydown', (e) => {
+    if (e.key === 'Enter' && input.value.trim()) load(input.value.trim());
+  });
+  // Auto-load if ?path= in URL
+  const params = new URLSearchParams(location.search);
+  const init = params.get('path');
+  if (init) { input.value = init; load(init); }
+</script>
+</body>
+</html>

package/src/dashboard-client.html

@@ -1402,7 +1402,18 @@ async function loadExtensionActive() {
       permsEl.setAttribute('style', 'font-size:12px;color:var(--fg-dim)');
       var reads = (a.permissions.reads || []).join(', ') || 'none';
       var writes = (a.permissions.writes || []).join(', ') || 'none';
-      permsEl.innerHTML = '<b style="color:var(--fg)">reads:</b> ' + reads + ' &nbsp; <b style="color:var(--fg)">writes:</b> ' + writes;
+      var bReads = document.createElement('b');
+      bReads.setAttribute('style', 'color:var(--fg)');
+      bReads.textContent = 'reads:';
+      var textReads = document.createTextNode(' ' + reads + '\u00A0\u00A0');
+      var bWrites = document.createElement('b');
+      bWrites.setAttribute('style', 'color:var(--fg)');
+      bWrites.textContent = 'writes:';
+      var textWrites = document.createTextNode(' ' + writes);
+      permsEl.appendChild(bReads);
+      permsEl.appendChild(textReads);
+      permsEl.appendChild(bWrites);
+      permsEl.appendChild(textWrites);
       wrap.appendChild(permsEl);
     }
     el.appendChild(wrap);

package/src/dashboard-server.js

@@ -434,6 +434,85 @@ export async function startServer(options = {}) {
       }));
     }],
 
+    // v1.4.4 N8 — Planning doc viewer. Same path-traversal guard as /api/memory/file,
+    // but allowed roots are .planning/, .ijfw/memory/, and .ijfw/wave-*/ all under REPO_ROOT.
+    ['/api/planning', (req, res, url) => {
+      const rawPath = url.searchParams.get('path') || '';
+      if (!rawPath) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'path query param required' }));
+        return;
+      }
+      if (isAbsolute(rawPath) || rawPath.split(/[\\/]/).some((seg) => seg === '..')) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'path traversal not allowed' }));
+        return;
+      }
+      const reqPath = resolve(REPO_ROOT, rawPath);
+      function canonOrNull(p) {
+        try { return realpathSync(p); } catch { return null; }
+      }
+      function isUnder(allowedRoot, canonChild) {
+        const canonRoot = canonOrNull(allowedRoot);
+        if (!canonRoot || !canonChild) return false;
+        const rel = relative(canonRoot, canonChild);
+        return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+      }
+      function isUnderWaveRoot(canonChild) {
+        // r13-M-05: restrict to STATE.md / SUMMARY.md filenames within
+        // .ijfw/wave-*/ subdirs. Previously allowed ANY file in a wave dir;
+        // wave directories may contain .tmp, lock files, or partial blackboard
+        // data that shouldn't be browser-readable.
+        const ijfwDir = canonOrNull(join(REPO_ROOT, '.ijfw'));
+        if (!ijfwDir || !canonChild) return false;
+        const rel = relative(ijfwDir, canonChild);
+        if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) return false;
+        const first = rel.split(/[\\/]/)[0];
+        if (!first.startsWith('wave-') || first.length === 'wave-'.length) return false;
+        return rel.endsWith('STATE.md') || rel.endsWith('SUMMARY.md');
+      }
+      const canonPath = canonOrNull(reqPath);
+      if (!canonPath) {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'file not found' }));
+        return;
+      }
+      const allowed = (
+        isUnder(join(REPO_ROOT, '.planning'), canonPath) ||
+        isUnder(join(REPO_ROOT, '.ijfw', 'memory'), canonPath) ||
+        isUnderWaveRoot(canonPath)
+      );
+      if (!allowed) {
+        res.writeHead(403, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'outside allowed planning roots' }));
+        return;
+      }
+      try {
+        const body = readFileSync(canonPath, 'utf8');
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ body: body.slice(0, 200000), path: rawPath }));
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: err.message, endpoint: '/api/planning' }));
+      }
+    }],
+
+    // v1.4.4 N8 — Planning-docs viewer (HTML SPA).
+    ['/planning', async (req, res) => {
+      try {
+        const html = await readFile(join(__dirname, 'dashboard-client-planning.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('Planning viewer not found: ' + err.message);
+      }
+    }],
+
     ['/api/memory/file', (req, res, url) => {
       const rawPath = url.searchParams.get('path') || '';
       if (!rawPath) {

package/src/dispatch/extension.js

@@ -613,11 +613,12 @@ async function cmdDeactivate() {
 let _v143Handlers = null;
 async function loadV143Handlers() {
   if (_v143Handlers !== null) return _v143Handlers;
-  const [registry, signer, quota, active] = await Promise.all([
+  const [registry, signer, quota, active, wave] = await Promise.all([
     import('./registry-cli.js'),
     import('./signer-cli.js'),
     import('./quota-cli.js'),
     import('./active-cli.js'),
+    import('./wave-cli.js'),  // v1.4.4 N9 — wave-status / wave-list
   ]);
   _v143Handlers = Object.assign(
     Object.create(null),
@@ -625,6 +626,7 @@ async function loadV143Handlers() {
     signer.handlers || {},
     quota.handlers || {},
     active.handlers || {},
+    wave.handlers || {},
   );
   return _v143Handlers;
 }