@ijfw/memory-server 1.4.0 → 1.4.1

package/README.md

@@ -0,0 +1,67 @@
+# @ijfw/memory-server
+
+IJFW MCP memory server — the runtime backend that powers memory, metrics,
+update checks, and the extension sandbox for all supported AI coding agents.
+
+## Install
+
+This package is installed automatically by `@ijfw/install`. You generally
+do not need to install it manually.
+
+```bash
+npm install -g @ijfw/memory-server
+```
+
+## Extension CLI
+
+IJFW ships a full extension system for installing and sandboxing third-party skills.
+
+```bash
+# Publisher key management
+ijfw extension keygen <author>              # Generate an Ed25519 publisher keypair
+ijfw extension trust <keyId> <publicKey>   # Add a publisher to your trusted store
+ijfw extension trust-registry [<url>]      # Pull + apply the hosted publisher registry
+ijfw extension untrust <keyId>             # Remove a publisher from your trusted store
+ijfw extension trusted                     # List all trusted publishers
+
+# Extension lifecycle
+ijfw extension add <source> [flags]        # Install an extension (npm name, local path, or https git URL)
+  --allow-unsigned                         #   Accept extensions with no signature
+  --accept-untrusted                       #   Accept extensions signed by an untrusted publisher (prompts on TTY)
+  --activate                               #   Auto-activate after install
+ijfw extension activate <name>             # Activate an installed extension (enforces declared permissions)
+ijfw extension deactivate                  # Deactivate the current extension
+
+# Admin / registry maintainer (rare)
+ijfw extension rotate-keys <oldKeyId> <newKeyId>   # Produce a signed rotation token
+ijfw extension keygen-meta <author>                # Generate the registry meta-keypair
+ijfw extension sign-registry <path>                # Sign a registry JSON file in place
+ijfw extension verify-registry <path>              # Verify a registry JSON signature
+ijfw extension registry-status                     # Show registry cache age + signature status
+```
+
+The rotation flow and registry maintainer docs live in `docs/REGISTRY-MAINTAINER.md`.
+
+## MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `ijfw_memory_store` | Store a memory entry |
+| `ijfw_memory_recall` | Recall memory entries |
+| `ijfw_memory_search` | Full-text search over memories |
+| `ijfw_memory_prelude` | Load project context at session start |
+| `ijfw_cross_project_search` | Search memories across projects |
+| `ijfw_metrics` | Read cost + usage metrics |
+| `ijfw_update_check` | Check for IJFW updates |
+| `ijfw_update_apply` | Apply a pending IJFW update |
+| `ijfw_prompt_check` | Validate a prompt against IJFW rules |
+| `ijfw_run` | Run a sandboxed IJFW command |
+
+## Build (contributors)
+
+```bash
+cd mcp-server
+npm install
+npm test
+node --experimental-sqlite --test test-*.js
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ijfw/memory-server",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "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/.registry-meta-key.pem

@@ -0,0 +1,3 @@
+-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAL2lCdti0bYiFTGUo/hffy+NiBUBXdbDcdaDmjJS27i0=
+-----END PUBLIC KEY-----

package/src/active-extension-writer.js

@@ -10,6 +10,7 @@
 import { readFile, writeFile, unlink, mkdir } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
+import { randomBytes } from 'node:crypto';
 
 const STATE_PATH_REL = ['.ijfw', 'state', 'active-extension.json'];
 
@@ -50,7 +51,7 @@ export async function writeActiveExtension(manifest, scope, opts = {}) {
   const home = opts && opts.homeDir ? opts.homeDir : (process.env.HOME || homedir());
   const path = statePath(home);
   await mkdir(dirname(path), { recursive: true });
-  const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
+  const tmp = `${path}.tmp.${randomBytes(4).toString('hex')}`;
   await writeFile(tmp, JSON.stringify(out, null, 2) + '\n', 'utf8');
   const { rename } = await import('node:fs/promises');
   await rename(tmp, path);
@@ -86,7 +87,7 @@ export async function clearActiveExtension(opts = {}) {
  *
  * @param {string} name
  * @param {string} [projectRoot]
- * @param {{ homeDir?: string }} [opts]
+ * @param {{ homeDir?: string, strictShadow?: boolean }} [opts]
  * @returns {Promise<{ ok: boolean, manifest?: object, scope?: string, path?: string, error?: string }>}
  */
 export async function findInstalledManifest(name, projectRoot, opts = {}) {
@@ -102,15 +103,40 @@ export async function findInstalledManifest(name, projectRoot, opts = {}) {
   candidates.push({ scope: 'org', path: join(home, '.ijfw', 'extensions-org', name, 'manifest.json') });
   candidates.push({ scope: 'user', path: join(home, '.ijfw', 'extensions-user', name, 'manifest.json') });
 
+  // Collect all found manifests to detect project-scope shadowing.
+  const found = [];
   for (const c of candidates) {
     try {
       const raw = await readFile(c.path, 'utf8');
       const manifest = JSON.parse(raw);
-      return { ok: true, manifest, scope: c.scope, path: c.path };
+      found.push({ scope: c.scope, path: c.path, manifest });
     } catch (err) {
       if (err && err.code === 'ENOENT') continue;
       if (err instanceof SyntaxError) continue;
     }
   }
-  return { ok: false, error: `extension "${name}" not found in project/org/user scope` };
+
+  if (found.length === 0) {
+    return { ok: false, error: `extension "${name}" not found in project/org/user scope` };
+  }
+
+  const winner = found[0];
+
+  // B13.1: warn when project-scope shadows a lower-priority scope entry.
+  if (winner.scope === 'project' && found.length > 1) {
+    const shadowed = found[1];
+    const winnerKeyId = winner.manifest.signature?.keyId ?? '(unsigned)';
+    const shadowedKeyId = shadowed.manifest.signature?.keyId ?? '(unsigned)';
+    if (opts && opts.strictShadow) {
+      return {
+        ok: false,
+        error: `extension activate: project-scope "${name}" shadows ${shadowed.scope}-scope "${name}" (keyId ${winnerKeyId} vs ${shadowedKeyId}) — refused by strictShadow`,
+      };
+    }
+    process.stderr.write(
+      `[ijfw] extension activate: project-scope "${name}" shadows ${shadowed.scope}-scope "${name}" (keyId ${winnerKeyId} vs ${shadowedKeyId}) — using project\n`,
+    );
+  }
+
+  return { ok: true, manifest: winner.manifest, scope: winner.scope, path: winner.path };
 }

package/src/dashboard-client.html

@@ -143,6 +143,15 @@ tr:hover td{background:var(--surface)}
 .empty{text-align:center;padding:40px 20px;color:var(--fg-dim)}
 .empty-icon{font-size:32px;margin-bottom:10px;opacity:.4}
 
+/* Extension events */
+.evt-row{display:flex;gap:8px;padding:5px 0;border-bottom:1px solid var(--border);align-items:flex-start}
+.evt-row:last-child{border-bottom:none}
+.evt-ts{color:var(--fg-dim);white-space:nowrap;font-size:11px;min-width:80px}
+.evt-badge{display:inline-block;padding:1px 6px;border-radius:3px;font-size:10px;font-weight:700;white-space:nowrap}
+.evt-allow{background:rgba(46,204,113,0.15);color:var(--success)}
+.evt-deny{background:rgba(239,68,68,0.15);color:var(--danger)}
+.evt-body{flex:1;color:var(--fg);font-size:11px;word-break:break-all}
+
 /* Memory tree */
 .mem-layout{display:flex;gap:0;height:calc(100vh - 180px);border:1px solid var(--border);border-radius:var(--radius);overflow:hidden}
 .mem-l{width:300px;flex-shrink:0;border-right:1px solid var(--border);display:flex;flex-direction:column;background:var(--bg-elevated)}
@@ -563,8 +572,9 @@ tr:hover td{background:var(--surface)}
       </div>
     </div>
 
-    <!-- ======== EXTENSIONS (W3/t15) ======== -->
+    <!-- ======== EXTENSIONS (W3/t15 + B9) ======== -->
     <div class="section" data-section="extensions">
+      <!-- Sub-section: Installed -->
       <div class="card">
         <div class="ctitle"><span id="ext-count">Extensions</span></div>
         <div id="extensions-content">
@@ -574,6 +584,35 @@ tr:hover td{background:var(--surface)}
           </div>
         </div>
       </div>
+
+      <!-- Sub-section: Active extension -->
+      <div class="card">
+        <div class="ctitle">Active Extension</div>
+        <div id="ext-active-content">
+          <div class="empty"><p style="font-size:13px">Loading...</p></div>
+        </div>
+      </div>
+
+      <!-- Sub-section: Permission events -->
+      <div class="card">
+        <div class="ctitle" style="justify-content:space-between">
+          <span>Permission Events <span id="ext-events-live" style="display:none"><span class="pulse"></span></span></span>
+          <span style="display:flex;gap:8px;align-items:center">
+            <select id="ext-evt-filter-ext" class="btn-g" style="padding:3px 8px;font-size:11px" aria-label="Filter by extension">
+              <option value="">All extensions</option>
+            </select>
+            <select id="ext-evt-filter-denied" class="btn-g" style="padding:3px 8px;font-size:11px" aria-label="Filter by outcome">
+              <option value="">All outcomes</option>
+              <option value="true">Denied only</option>
+              <option value="false">Allowed only</option>
+            </select>
+            <button class="btn-g" id="ext-evt-clear" style="font-size:11px" aria-label="Clear events">Clear</button>
+          </span>
+        </div>
+        <div id="ext-events-content" style="max-height:320px;overflow-y:auto;font-size:12px;font-family:ui-monospace,monospace">
+          <div class="empty"><p>No permission events yet.</p></div>
+        </div>
+      </div>
     </div>
 
     <!-- ======== SUBSCRIPTIONS ======== -->
@@ -1303,6 +1342,174 @@ async function loadExtensions() {
   }
 }
 
+// ====== ACTIVE EXTENSION LOADER (B9) ======
+async function loadExtensionActive() {
+  var el = document.getElementById('ext-active-content');
+  if (!el) return;
+  try {
+    var r = await fetch('/api/extensions/active');
+    var d = await r.json();
+    while (el.firstChild) el.removeChild(el.firstChild);
+    if (!d.active) {
+      var p = document.createElement('p');
+      p.setAttribute('style', 'font-size:13px;color:var(--fg-dim);padding:4px 0');
+      p.textContent = 'None — bundled IJFW context active';
+      el.appendChild(p);
+      return;
+    }
+    var a = d.active;
+    var wrap = document.createElement('div');
+    wrap.setAttribute('style', 'font-size:13px');
+    var nameRow = document.createElement('div');
+    nameRow.setAttribute('style', 'margin-bottom:6px');
+    var strong = document.createElement('strong');
+    strong.textContent = a.name || 'unknown';
+    nameRow.appendChild(strong);
+    if (a.scope) {
+      var sc = document.createElement('span');
+      sc.setAttribute('style', 'margin-left:8px;font-size:11px;color:var(--fg-dim)');
+      sc.textContent = '(' + a.scope + ')';
+      nameRow.appendChild(sc);
+    }
+    wrap.appendChild(nameRow);
+    if (a.permissions) {
+      var permsEl = document.createElement('div');
+      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;
+      wrap.appendChild(permsEl);
+    }
+    el.appendChild(wrap);
+  } catch (err) {
+    if (el) { while (el.firstChild) el.removeChild(el.firstChild); }
+    var errP = document.createElement('p');
+    errP.setAttribute('style', 'font-size:12px;color:var(--fg-dim)');
+    errP.textContent = 'Could not load active extension state.';
+    if (el) el.appendChild(errP);
+  }
+}
+
+// ====== PERMISSION EVENTS LOADER (B9) ======
+var _evtSource = null;
+var _evtRows = [];
+var _evtExtensions = new Set();
+
+function _renderEvtRows() {
+  var el = document.getElementById('ext-events-content');
+  if (!el) return;
+  var filterExt = (document.getElementById('ext-evt-filter-ext') || {}).value || '';
+  var filterDenied = (document.getElementById('ext-evt-filter-denied') || {}).value || '';
+  var visible = _evtRows.filter(function(e) {
+    if (filterExt && e.extension !== filterExt) return false;
+    if (filterDenied === 'true' && e.allowed !== false) return false;
+    if (filterDenied === 'false' && e.allowed === false) return false;
+    return true;
+  });
+  while (el.firstChild) el.removeChild(el.firstChild);
+  if (visible.length === 0) {
+    var empty = document.createElement('div');
+    empty.className = 'empty';
+    var ep = document.createElement('p');
+    ep.textContent = 'No permission events match the current filters.';
+    empty.appendChild(ep);
+    el.appendChild(empty);
+    return;
+  }
+  var frag = document.createDocumentFragment();
+  visible.slice(-200).forEach(function(e) {
+    var row = document.createElement('div');
+    row.className = 'evt-row';
+    var ts = document.createElement('span');
+    ts.className = 'evt-ts';
+    ts.textContent = e.ts ? new Date(e.ts).toLocaleTimeString() : '';
+    row.appendChild(ts);
+    var badge = document.createElement('span');
+    badge.className = 'evt-badge ' + (e.allowed === false ? 'evt-deny' : 'evt-allow');
+    badge.textContent = e.allowed === false ? 'DENY' : 'ALLOW';
+    row.appendChild(badge);
+    var body = document.createElement('span');
+    body.className = 'evt-body';
+    body.textContent = (e.extension || '') + ' → ' + (e.tool || e.action || '') + (e.target ? ':' + e.target : '');
+    row.appendChild(body);
+    frag.appendChild(row);
+  });
+  el.appendChild(frag);
+  el.scrollTop = el.scrollHeight;
+}
+
+function _addEvtRow(obj) {
+  _evtRows.push(obj);
+  if (obj.extension) {
+    _evtExtensions.add(obj.extension);
+    // Rebuild extension filter options
+    var sel = document.getElementById('ext-evt-filter-ext');
+    if (sel) {
+      var existing = new Set(Array.from(sel.options).map(function(o) { return o.value; }));
+      _evtExtensions.forEach(function(name) {
+        if (!existing.has(name)) {
+          var opt = document.createElement('option');
+          opt.value = name; opt.textContent = name;
+          sel.appendChild(opt);
+        }
+      });
+    }
+  }
+}
+
+function loadExtensionEvents() {
+  var liveEl = document.getElementById('ext-events-live');
+
+  // Close any previous SSE connection.
+  if (_evtSource) { try { _evtSource.close(); } catch {} _evtSource = null; }
+  if (liveEl) liveEl.style.display = 'none';
+
+  // Pre-load current tail via JSON (no SSE until section is active).
+  fetch('/api/extensions/events?limit=200')
+    .then(function(r) { return r.json(); })
+    .then(function(arr) {
+      if (!Array.isArray(arr)) return;
+      _evtRows = [];
+      arr.forEach(_addEvtRow);
+      _renderEvtRows();
+      // Open SSE for live updates.
+      try {
+        _evtSource = new EventSource('/api/extensions/events?limit=1');
+        _evtSource.onopen = function() { if (liveEl) liveEl.style.display = ''; };
+        _evtSource.onmessage = function(e) {
+          try {
+            var obj = JSON.parse(e.data);
+            if (obj && typeof obj === 'object' && !obj.showing) {
+              _addEvtRow(obj);
+              _renderEvtRows();
+            }
+          } catch {}
+        };
+        _evtSource.onerror = function() { if (liveEl) liveEl.style.display = 'none'; };
+      } catch {}
+    })
+    .catch(function() {
+      var el = document.getElementById('ext-events-content');
+      if (!el) return;
+      while (el.firstChild) el.removeChild(el.firstChild);
+      var p = document.createElement('p');
+      p.setAttribute('style', 'font-size:12px;color:var(--fg-dim);padding:8px 0');
+      p.textContent = 'Permission events unavailable.';
+      el.appendChild(p);
+    });
+
+  // Wire filter controls.
+  var filterExt = document.getElementById('ext-evt-filter-ext');
+  var filterDenied = document.getElementById('ext-evt-filter-denied');
+  var clearBtn = document.getElementById('ext-evt-clear');
+  if (filterExt) filterExt.onchange = _renderEvtRows;
+  if (filterDenied) filterDenied.onchange = _renderEvtRows;
+  if (clearBtn) clearBtn.onclick = function() {
+    _evtRows = [];
+    _renderEvtRows();
+  };
+}
+
 // ====== RUN ALL LOADERS ======
 document.addEventListener('DOMContentLoaded', function() {
   loadCostToday();
@@ -1317,6 +1524,8 @@ document.addEventListener('DOMContentLoaded', function() {
   loadTrendSparkline();
   loadBlockUsage();
   loadExtensions();
+  loadExtensionActive();
+  loadExtensionEvents();
 });
 </script>
 </body>

package/src/dashboard-server.js

@@ -688,6 +688,249 @@ export async function startServer(options = {}) {
       res.end(JSON.stringify(config));
     }],
 
+    // ---------- extensions: installed (B9) ----------
+    // Enumerate ~/.ijfw/state-org/extension-registry.json,
+    // ~/.ijfw/state-user/extension-registry.json, and project-scope registry.
+    // Returns JSON list with name, scope, version, publisher_keyId, permissions,
+    // last_activated_time. Path-traversal defence: resolve + assert under HOME.
+    ['/api/extensions/installed', async (req, res) => {
+      try {
+        const home = homedir();
+        // realpath both sides — on macOS /var/folders -> /private/var/folders is a symlink,
+        // so the registry's realpathed path won't show as under un-realpathed HOME.
+        let homeCanon;
+        try { homeCanon = realpathSync(home); } catch { homeCanon = home; }
+        function isUnderHome(p) {
+          try {
+            const canon = realpathSync(p);
+            const rel = relative(homeCanon, canon);
+            return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+          } catch { return false; }
+        }
+
+        const REGISTRY_FILENAME = 'extension-registry.json';
+        const registryPaths = [
+          { scope: 'org',  path: join(home, '.ijfw', 'state-org',  REGISTRY_FILENAME) },
+          { scope: 'user', path: join(home, '.ijfw', 'state-user', REGISTRY_FILENAME) },
+          { scope: 'project', path: join(REPO_ROOT, '.ijfw', 'state', REGISTRY_FILENAME) },
+        ];
+
+        const seen = new Map();
+        for (const { scope, path: regPath } of registryPaths) {
+          // Path-traversal check on each registry path.
+          const resolvedReg = resolve(regPath);
+          const underHome = isUnderHome(resolvedReg) ||
+            resolvedReg.startsWith(resolve(REPO_ROOT));
+          if (!underHome) continue;
+          if (!existsSync(resolvedReg)) continue;
+          let registry;
+          try {
+            const raw = readFileSync(resolvedReg, 'utf8');
+            const parsed = JSON.parse(raw);
+            registry = Array.isArray(parsed.extensions) ? parsed.extensions : [];
+          } catch { continue; }
+
+          for (const e of registry) {
+            if (!e || !e.name || !e.version) continue;
+            const key = `${e.name}@${e.version}`;
+            if (seen.has(key)) continue;
+            const manifest = (e.manifest && typeof e.manifest === 'object') ? e.manifest : null;
+            seen.set(key, {
+              name: e.name,
+              scope,
+              version: e.version,
+              publisher_keyId: manifest ? (manifest.publisher_keyId || null) : null,
+              permissions: manifest ? (manifest.permissions || null) : null,
+              last_activated_time: e.last_activated_time || null,
+            });
+          }
+        }
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ extensions: Array.from(seen.values()) }));
+      } catch (err) {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ extensions: [], error: err.message }));
+      }
+    }],
+
+    // ---------- extensions: active (B9) ----------
+    ['/api/extensions/active', async (req, res) => {
+      try {
+        const home = homedir();
+        const activePath = join(home, '.ijfw', 'state', 'active-extension.json');
+        const resolvedActive = resolve(activePath);
+        // Return {active:null} BEFORE realpath — realpathSync throws on non-existent paths.
+        if (!existsSync(resolvedActive)) {
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ active: null }));
+          return;
+        }
+        // Path-traversal: realpath BOTH home and target so macOS /private symlinks
+        // (e.g. /var/folders -> /private/var/folders) resolve correctly AND symlinks
+        // pointing outside HOME are rejected.
+        let homeCanon;
+        try { homeCanon = realpathSync(home); } catch { homeCanon = home; }
+        let activeCanon;
+        try {
+          activeCanon = realpathSync(resolvedActive);
+        } catch {
+          res.writeHead(403, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'path traversal rejected' }));
+          return;
+        }
+        const rel = relative(homeCanon, activeCanon);
+        if (rel.startsWith('..') || isAbsolute(rel)) {
+          res.writeHead(403, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'path traversal rejected' }));
+          return;
+        }
+        const raw = readFileSync(activeCanon, 'utf8');
+        const parsed = JSON.parse(raw);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ active: parsed }));
+      } catch (err) {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ active: null, error: err.message }));
+      }
+    }],
+
+    // ---------- extensions: events (B9) ----------
+    // Tail-streams ~/.ijfw/state/permission-events.jsonl with optional filters.
+    // Allowlisted query params: limit, extension, tool, denied.
+    // SSE mode: Accept: text/event-stream. JSON array otherwise.
+    // Never reads full file into memory: streams line-by-line.
+    ['/api/extensions/events', async (req, res, url) => {
+      const ALLOWED_FILTER_KEYS = new Set(['limit', 'extension', 'tool', 'denied']);
+      // Reject any non-allowlisted filter key.
+      for (const key of url.searchParams.keys()) {
+        if (!ALLOWED_FILTER_KEYS.has(key)) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: `unknown filter parameter: ${key}` }));
+          return;
+        }
+      }
+
+      const home = homedir();
+      const eventsPath = join(home, '.ijfw', 'state', 'permission-events.jsonl');
+
+      const rawLimit = url.searchParams.get('limit');
+      let limit = 200;
+      if (rawLimit !== null) {
+        const n = safeIntegerParam(rawLimit, 10_000);
+        if (n === null) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'invalid limit' }));
+          return;
+        }
+        limit = n;
+      }
+      const filterExtension = url.searchParams.get('extension') || null;
+      const filterTool      = url.searchParams.get('tool') || null;
+      const filterDenied    = url.searchParams.has('denied')
+        ? (url.searchParams.get('denied') !== 'false')
+        : null;
+
+      // Stream-tail: read only the last TAIL_CHUNK bytes, never slurp the full file.
+      // For permission-events.jsonl which rotates at 10_000 lines, 2MB covers
+      // many thousands of events without loading the entire file into memory.
+      const TAIL_CHUNK = 2 * 1024 * 1024; // 2MB
+      function tailEvents() {
+        if (!existsSync(eventsPath)) return [];
+        let st;
+        try { st = statSync(eventsPath); } catch { return []; }
+        if (st.size === 0) return [];
+        let lines = [];
+        try {
+          const fullBuf = readFileSync(eventsPath);
+          const slice = fullBuf.subarray(Math.max(0, fullBuf.length - TAIL_CHUNK));
+          const text = slice.toString('utf8');
+          lines = text.split('\n').filter(Boolean);
+          // If we sliced mid-line, the first element may be truncated — drop it.
+          if (fullBuf.length > TAIL_CHUNK) lines = lines.slice(1);
+        } catch { return []; }
+
+        const results = [];
+        for (let i = lines.length - 1; i >= 0 && results.length < limit; i--) {
+          let obj;
+          try { obj = JSON.parse(lines[i]); } catch { continue; }
+          if (filterExtension !== null && obj.extension !== filterExtension) continue;
+          if (filterTool !== null && obj.tool !== filterTool) continue;
+          if (filterDenied !== null && Boolean(!obj.allowed) !== filterDenied) continue;
+          results.unshift(obj);
+        }
+        return results;
+      }
+
+      const isSSE = (req.headers['accept'] || '').includes('text/event-stream');
+      if (isSSE) {
+        res.writeHead(200, {
+          'Content-Type': 'text/event-stream',
+          'Cache-Control': 'no-cache',
+          'Connection': 'keep-alive',
+          'X-Accel-Buffering': 'no',
+        });
+        res.write(': connected\n\n');
+        // Send current tail as initial batch.
+        const initial = tailEvents();
+        for (const evt of initial) {
+          try { res.write(`data: ${JSON.stringify(evt)}\n\n`); } catch { break; }
+        }
+        // Watch for new events. lastLineCount must match what the watcher
+        // measures (tail-chunk lines), NOT the limited initial batch length —
+        // mismatching them causes a replay storm when the file is bigger than
+        // the limit.
+        let evtWatcher = null;
+        let lastLineCount = 0;
+        try {
+          const buf0 = readFileSync(eventsPath);
+          const slice0 = buf0.subarray(Math.max(0, buf0.length - TAIL_CHUNK));
+          let lines0 = slice0.toString('utf8').split('\n').filter(Boolean);
+          if (buf0.length > TAIL_CHUNK) lines0 = lines0.slice(1);
+          lastLineCount = lines0.length;
+        } catch { /* eventsPath missing or unreadable — start from 0 */ }
+        try {
+          evtWatcher = watch(existsSync(eventsPath) ? eventsPath : join(home, '.ijfw', 'state'), () => {
+            if (!existsSync(eventsPath)) return;
+            try {
+              // Use the tail-chunk reader (bounded read) rather than slurping the
+              // full file. At 10K lines × ~1-2KB each = 10-20MB sync read per watch
+              // event, which is unacceptable for a long-lived SSE connection.
+              try { statSync(eventsPath); } catch { return; }
+              const buf = (() => {
+                try { return readFileSync(eventsPath); } catch { return null; }
+              })();
+              if (!buf) return;
+              const slice = buf.subarray(Math.max(0, buf.length - TAIL_CHUNK));
+              const text = slice.toString('utf8');
+              let lines = text.split('\n').filter(Boolean);
+              if (buf.length > TAIL_CHUNK) lines = lines.slice(1);
+              if (lines.length > lastLineCount) {
+                const newLines = lines.slice(lastLineCount);
+                lastLineCount = lines.length;
+                for (const line of newLines) {
+                  let obj; try { obj = JSON.parse(line); } catch { continue; }
+                  if (filterExtension !== null && obj.extension !== filterExtension) continue;
+                  if (filterTool !== null && obj.tool !== filterTool) continue;
+                  if (filterDenied !== null && Boolean(!obj.allowed) !== filterDenied) continue;
+                  try { res.write(`data: ${JSON.stringify(obj)}\n\n`); } catch {}
+                }
+              }
+            } catch {}
+          });
+          if (evtWatcher) evtWatcher.on('error', () => {});
+        } catch {}
+        req.on('close', () => {
+          if (evtWatcher) { try { evtWatcher.close(); } catch {} }
+        });
+        return;
+      }
+
+      // JSON array response.
+      const events = tailEvents();
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(events));
+    }],
+
     // ---------- extensions health (W3/t15) ----------
     // Reads .ijfw/state/extension-registry.json (project) plus org/user via
     // listExtensions(). Missing or malformed registry yields {extensions: []}