@ijfw/memory-server 1.6.0 → 1.6.2

package/bin/ijfw-dashboard

@@ -40,10 +40,19 @@ function removePidFiles() {
 
 function openBrowser(url) {
   if (process.env.CI || process.env.NO_OPEN) return;
-  const cmd = process.platform === 'darwin' ? 'open'
-    : process.platform === 'win32' ? 'start'
-    : 'xdg-open';
-  try { spawn(cmd, [url], { detached: true, stdio: 'ignore' }).unref(); } catch {}
+  // `start` is a cmd.exe builtin (no start.exe on PATH), so it must be run
+  // through cmd. The empty '' arg is start's window-title slot, which would
+  // otherwise swallow the URL. url is built internally from a parsed port.
+  const [cmd, args] = process.platform === 'darwin' ? ['open', [url]]
+    : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]]
+    : ['xdg-open', [url]];
+  try {
+    const child = spawn(cmd, args, { detached: true, stdio: 'ignore' });
+    // Missing opener surfaces as an async 'error' event, not a throw --
+    // swallow it so it can never become an uncaught exception.
+    child.on('error', () => {});
+    child.unref();
+  } catch {}
 }
 
 // Probe a URL for HTTP 200, retrying on connection-refused until timeoutMs elapses.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ijfw/memory-server",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "description": "Cross-platform persistent memory server for IJFW. 14 MCP tools (memory + admin/update + brain). Works with 15 platforms: 14 via MCP (Claude Code, Codex, Gemini CLI, Cursor, Windsurf, Copilot, Hermes, Wayland, OpenCode, QwenCode, Cline, KimiCode, OpenClaw, Antigravity) plus Aider via the rules-only tier.",
   "author": "Sean Donahoe",
   "contributors": [

package/src/audit-roster.js

@@ -281,10 +281,22 @@ export function isInstalled(id) {
   // `[ -x ]` (or be a shell builtin/keyword/function with no filesystem path,
   // which `command -v` reports without a leading slash — those are genuinely
   // runnable). A real installed CLI is an executable file and still passes.
-  const probe = `p=$(command -v ${JSON.stringify(bin)} 2>/dev/null) || exit 1; ` +
-    `case "$p" in /*) [ -x "$p" ] ;; *) : ;; esac`;
-  const r = spawnSync('bash', ['-lc', probe], { timeout: 2000 });
-  const installed = r.status === 0;
+  //
+  // On native Windows `bash` is either absent (probe would mark every auditor
+  // uninstalled) or the WSL launcher (probe would report the Linux distro's
+  // PATH, which the Windows-side invoker cannot run). Use `where` instead:
+  // it resolves .cmd/.exe shims on the real Windows PATH, matching how the
+  // auditors are actually spawned (shell:true on win32).
+  let installed;
+  if (process.platform === 'win32') {
+    const r = spawnSync('where', [bin], { timeout: 2000, encoding: 'utf8', windowsHide: true });
+    installed = r.status === 0 && Boolean((r.stdout || '').trim());
+  } else {
+    const probe = `p=$(command -v ${JSON.stringify(bin)} 2>/dev/null) || exit 1; ` +
+      `case "$p" in /*) [ -x "$p" ] ;; *) : ;; esac`;
+    const r = spawnSync('bash', ['-lc', probe], { timeout: 2000 });
+    installed = r.status === 0;
+  }
   _installedCache.set(id, { value: installed, ts: Date.now() });
   return installed;
 }

package/src/compute/fts5.js

@@ -242,9 +242,34 @@ function readUserVersion(db) {
   return Number(row.user_version ?? row.USER_VERSION ?? 0);
 }
 
+// quick_check throttle state, keyed per db handle. First write per handle
+// always checks; then every Nth write or once the time floor elapses.
+const QUICK_CHECK_EVERY_N = 100;
+const QUICK_CHECK_MIN_INTERVAL_MS = 5 * 60 * 1000;
+const quickCheckState = new WeakMap(); // db handle -> { writes, lastTs }
+
+function shouldQuickCheck(db, now = Date.now()) {
+  let st = quickCheckState.get(db);
+  if (!st) {
+    st = { writes: 0, lastTs: 0 };
+    quickCheckState.set(db, st);
+  }
+  st.writes++;
+  if (
+    st.writes === 1 ||
+    st.writes % QUICK_CHECK_EVERY_N === 0 ||
+    (now - st.lastTs) >= QUICK_CHECK_MIN_INTERVAL_MS
+  ) {
+    st.lastTs = now;
+    return true;
+  }
+  return false;
+}
+
 // Insert one row into a content table inside a transaction, then run
-// PRAGMA quick_check on the whole db. Throws IntegrityError on anything
-// other than 'ok'. Returns { id } of the inserted row.
+// PRAGMA quick_check on the whole db (throttled; see above). Throws
+// IntegrityError on anything other than 'ok'. Returns { id } of the
+// inserted row.
 //
 // Allowed tables: raw, compiled, trident_run, schema_meta. Caller passes a
 // row object whose keys match the table's columns; binding is positional
@@ -291,19 +316,28 @@ export function safeWrite(db, table, row) {
   const sql = `INSERT INTO ${table} (${cols.join(', ')}) VALUES (${placeholders})`;
   const values = cols.map(c => row[c]);
 
-  // Run insert + quick_check inside a single transaction. Rollback on
-  // either failure so we never leave a half-written FTS index behind.
+  // Run insert + (throttled) quick_check inside a single transaction.
+  // Rollback on either failure so we never leave a half-written FTS index
+  // behind. quick_check is a full-database scan, so it can't run on every
+  // insert (O(db size) per write while the lock is held); the corruption
+  // tripwire fires on the FIRST write per handle (compute callers hold
+  // long-lived handles, so reopen-after-corruption is still caught), then
+  // every Nth write or after a time floor, whichever comes first. State is
+  // keyed per HANDLE (WeakMap), unlike memory/fts5.js which keys per
+  // filename because server.js re-opens that db per store.
   let inserted;
   const tx = db.txn(() => {
     const stmt = db.prepare(sql);
     const info = stmt.run(...values);
     inserted = { id: info && info.lastInsertRowid != null ? Number(info.lastInsertRowid) : null };
-    const qc = db.prepare('PRAGMA quick_check').get();
-    const status = qc && (qc.quick_check ?? qc.QUICK_CHECK);
-    if (status !== 'ok') {
-      throw new IntegrityError(
-        `PRAGMA quick_check failed after insert into ${table}: ${status || '(no result)'}.`
-      );
+    if (shouldQuickCheck(db)) {
+      const qc = db.prepare('PRAGMA quick_check').get();
+      const status = qc && (qc.quick_check ?? qc.QUICK_CHECK);
+      if (status !== 'ok') {
+        throw new IntegrityError(
+          `PRAGMA quick_check failed after insert into ${table}: ${status || '(no result)'}.`
+        );
+      }
     }
   });
   tx();

package/src/compute/staleness.js

@@ -166,11 +166,11 @@ export function propagateStale(db, supersededNodeId, options = {}) {
     // timeout in fts5.openDb, so concurrent reads remain unblocked.
     const updateRaw = db.prepare(
       `UPDATE raw SET stale_candidate = ? ` +
-      `WHERE stale_candidate < ? AND body LIKE ?`
+      `WHERE stale_candidate < ? AND body LIKE ? ESCAPE '\\'`
     );
     const updateCompiled = db.prepare(
       `UPDATE compiled SET stale_candidate = ? ` +
-      `WHERE stale_candidate < ? AND (topic LIKE ? OR body LIKE ?)`
+      `WHERE stale_candidate < ? AND (topic LIKE ? ESCAPE '\\' OR body LIKE ? ESCAPE '\\')`
     );
 
     const tx = (typeof db.txn === 'function')
@@ -204,12 +204,13 @@ export function propagateStale(db, supersededNodeId, options = {}) {
   };
 }
 
-// LIKE pattern escape -- our names can contain `%` or `_` (e.g. error
-// codes like `E_BUSY%` -- unlikely but possible). Escape both, plus the
-// backslash escape character. Use `\` as the escape; SQLite needs an
-// explicit ESCAPE clause to honour it, so we add that to the prepared
-// statement above. (Skipped here because in practice kg_node names from
-// our regex extractor never contain `%` or `_` chars.)
+// LIKE pattern escape -- kg_node names routinely contain `_` (the entity
+// extractor's snake_case/UPPER_SNAKE regexes REQUIRE underscores) and can
+// contain `%`. Escape both, plus the backslash escape character. SQLite
+// LIKE has NO default escape character, so every consuming statement above
+// carries an explicit ESCAPE '\' clause -- without it, `\_` matches a
+// literal backslash followed by ANY character and snake_case names
+// silently flag zero rows.
 function escapeLike(s) {
   return String(s).replace(/[\\%_]/g, '\\$&');
 }

package/src/cost/readers/codex.js

@@ -8,7 +8,7 @@
  */
 
 import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, basename } from 'node:path';
 import { homedir } from 'node:os';
 
 const CODEX_SESSIONS_DIR = join(homedir(), '.codex', 'sessions');
@@ -63,13 +63,13 @@ function processCodexFile(filePath, turns) {
   }
 
   if (!sessionId) {
-    // Derive session id from filename
-    const base = filePath.split('/').pop().replace('.jsonl', '');
-    sessionId = base;
+    // Derive session id from filename (basename handles both path separators)
+    sessionId = basename(filePath, '.jsonl');
   }
 
-  // Extract timestamp from session path (YYYY/MM/DD/filename)
-  const dateParts = filePath.match(/(\d{4})\/(\d{2})\/(\d{2})/);
+  // Extract timestamp from session path (YYYY/MM/DD/filename); paths are
+  // join()-built, so accept either separator (backslashes on Windows).
+  const dateParts = filePath.match(/(\d{4})[\\/](\d{2})[\\/](\d{2})/);
   const datePrefix = dateParts ? `${dateParts[1]}-${dateParts[2]}-${dateParts[3]}` : null;
 
   // Accumulate per-session totals from response_item/message content

package/src/cross-orchestrator-cli.js

@@ -9,7 +9,7 @@
 
 import { readFileSync, existsSync, writeFileSync, mkdirSync, statSync, openSync, readSync, closeSync, readdirSync, rmSync, realpathSync, copyFileSync } from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { join, dirname, basename, isAbsolute, resolve } from 'node:path';
+import { join, dirname, basename, isAbsolute, resolve, parse as parsePath, sep } from 'node:path';
 import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { writeAtomic } from './lib/atomic-io.js';
@@ -210,7 +210,7 @@ function emitJson(value) {
   process.stdout.write(JSON.stringify(value, null, 2) + '\n');
 }
 
-function parseArgs(argv) {
+export function parseArgs(argv) {
   const args = argv.slice(2); // strip node + script path
 
   // Global --json flag: any command can be forced to JSON output regardless
@@ -319,6 +319,10 @@ function parseArgsInner(args) {
     return { cmd: 'doctor' };
   }
 
+  if (args[0] === 'init') {
+    return { cmd: 'init', force: args.includes('--force') };
+  }
+
   if (args[0] === 'update') {
     const opts = { cmd: 'update' };
     for (let i = 1; i < args.length; i++) {
@@ -504,20 +508,12 @@ function parseArgsInner(args) {
       return { cmd: 'cross-project-audit', rule, dryRun };
     }
 
-    const target = args[2];
-    let only = null;
-    let confirm = false;
-    let expand = false;
-    let chunk = false;
-
-    for (let i = 3; i < args.length; i++) {
-      if (args[i] === '--confirm') { confirm = true; }
-      else if (args[i] === '--expand') { expand = true; }
-      else if (args[i] === '--chunk') { chunk = true; } // v1.5.1 H1.6 — wire chunker
-      else if (args[i] === '--with' && args[i + 1]) { only = args[++i]; }
-    }
-
-    return { cmd: 'cross', mode, target, only, confirm, expand, chunk };
+    // Reuse the alias parser so `ijfw cross <mode>` and `ijfw cross-<mode>`
+    // share one grammar: --with=<id> form, flags-before-target ordering, and
+    // flag tokens never consumed as the target. The old position-rigid parser
+    // (target = args[2], space-separated --with only) silently dropped
+    // --with=<id> and dispatched the full paid roster.
+    return parseCrossAlias(mode, args.slice(1));
   }
 
   return { cmd: 'unknown', raw: args[0] };
@@ -1369,7 +1365,7 @@ async function cmdCross({ mode, target, only, confirm, expand, chunk }) {
       console.log(`Auditors fired (union): ${[...auditorIds].join(', ') || '(none)'}`);
       if (!firedAny) {
         console.log('No auditors fired -- run `ijfw doctor` to see the install hints.');
-        process.exit(2); // r17.1 — degraded exit code
+        process.exit(3); // zero picks contributed -- INCONCLUSIVE, same code as the normal path
       }
       for (const f of merged) {
         const sev = (f.severity || 'note').toUpperCase();
@@ -1397,7 +1393,10 @@ async function cmdCross({ mode, target, only, confirm, expand, chunk }) {
     console.log('Trident is standing by -- no auditors reachable yet.');
     console.log('Wire one in 30 seconds: run `ijfw doctor` for the exact install commands.');
     console.log('Tip: any one of codex / gemini / claude / copilot is enough to start.');
-    process.exit(0);
+    // No audit happened: exit 3 per the documented contract below (zero picks
+    // contributed = INCONCLUSIVE). Exit 0 here let CI gates pass green on a
+    // machine with no auditors installed.
+    process.exit(3);
   }
 
   const projectDir = process.cwd();
@@ -1421,7 +1420,7 @@ async function cmdCross({ mode, target, only, confirm, expand, chunk }) {
   if (picks.length === 0) {
     console.log('\nIJFW has the Trident ready -- install codex or gemini (or set OPENAI_API_KEY / GEMINI_API_KEY), then run `ijfw demo`.');
     console.log('Run `ijfw doctor` to see which auditors are available on this machine.');
-    return;
+    process.exit(3); // zero picks contributed -- INCONCLUSIVE per the exit contract
   }
 
   console.log(`Fired: ${picks.map(p => p.id).join(', ')}`);
@@ -2865,6 +2864,8 @@ if (isMainModule) {
     cmdImport(parsed).catch(err => { console.error(err.message); process.exit(1); });
   } else if (parsed.cmd === 'doctor') {
     cmdDoctor(parsed);
+  } else if (parsed.cmd === 'init') {
+    cmdInit(parsed);
   } else if (parsed.cmd === 'update') {
     cmdUpdate(parsed);
   } else if (parsed.cmd === 'version') {
@@ -2954,6 +2955,52 @@ function findCliAsset(...rel) {
   ].filter(Boolean);
   return candidates.find(p => existsSync(p)) || null;
 }
+// `ijfw init` -- explicitly bless the current folder for codebase indexing.
+// The indexer (scripts/build-codebase-index.sh) refuses any folder that has no
+// project marker (issue #16). For a plain working folder with no .git/package.json
+// etc, this drops a .ijfw/project marker so the indexer will index it. It will
+// NOT bless the home directory or filesystem root -- that is the whole point of
+// the guard.
+function cmdInit(parsed = {}) {
+  const cwd = process.cwd();
+  let phys;
+  try { phys = realpathSync(cwd); } catch { phys = resolve(cwd); }
+  let homePhys;
+  try { homePhys = realpathSync(homedir()); } catch { homePhys = homedir(); }
+  // Refuse any filesystem/drive root (parse().root catches '/', 'C:\\', UNC
+  // roots), the home directory itself, or any ANCESTOR of home (blessing
+  // /Users or /home would let the indexer walk every user's home -- the
+  // issue #16 privacy hole one directory up).
+  const isFsRoot = parsePath(phys).root === phys;
+  const isHomeOrAncestor = phys === homePhys || homePhys.startsWith(phys + sep);
+  if (isFsRoot || isHomeOrAncestor) {
+    console.error('ijfw init: refusing to bless your home directory, its ancestors, or a filesystem root for indexing.');
+    console.error('Run `ijfw init` from inside an actual project folder.');
+    process.exit(1);
+  }
+  const marker = join(cwd, '.ijfw', 'project');
+  try {
+    mkdirSync(dirname(marker), { recursive: true });
+    if (existsSync(marker) && !parsed.force) {
+      console.log(`This folder is already initialised for IJFW indexing (${marker}).`);
+      process.exit(0);
+    }
+    const stamp = new Date().toISOString();
+    writeFileSync(
+      marker,
+      `# IJFW project marker\n` +
+      `# Created by \`ijfw init\`. This folder is approved for codebase indexing.\n` +
+      `# Safe to commit. Delete this file to stop IJFW indexing this folder.\n` +
+      `created_at: ${stamp}\n`,
+      { mode: 0o644 }
+    );
+    console.log('IJFW initialised. This folder is now approved for codebase indexing.');
+    console.log(`Marker: ${marker}`);
+  } catch (err) {
+    console.error(`ijfw init: could not write marker -- ${err.message}`);
+    process.exit(1);
+  }
+}
 function cmdInstall() {
   const script = findCliAsset('scripts', 'install.sh');
   if (!script) {
@@ -2961,6 +3008,9 @@ function cmdInstall() {
     process.exit(1);
   }
   const res = spawnSync('bash', [script, ...process.argv.slice(3)], { stdio: 'inherit' });
+  // spawnSync failure (bash missing, EACCES) yields status null + res.error
+  // and stdio:'inherit' prints nothing -- surface it instead of exiting mute.
+  if (res.error) console.error(`ijfw: failed to launch ${script}: ${res.error.message}`);
   process.exit(res.status ?? 1);
 }
 function cmdUninstall() {
@@ -2970,6 +3020,7 @@ function cmdUninstall() {
     process.exit(1);
   }
   const res = spawnSync(process.execPath, [script, ...process.argv.slice(3)], { stdio: 'inherit' });
+  if (res.error) console.error(`ijfw: failed to launch ${script}: ${res.error.message}`);
   process.exit(res.status ?? 1);
 }
 function cmdPreflight() {
@@ -2979,6 +3030,7 @@ function cmdPreflight() {
     process.exit(1);
   }
   const res = spawnSync(process.execPath, [script, ...process.argv.slice(3)], { stdio: 'inherit' });
+  if (res.error) console.error(`ijfw: failed to launch ${script}: ${res.error.message}`);
   process.exit(res.status ?? 1);
 }
 function cmdDashboard(sub) {
@@ -2998,6 +3050,7 @@ function cmdDashboard(sub) {
   // stays authoritative. argv = [node, cli, 'dashboard', <sub>, ...flags].
   const passthrough = process.argv.slice(4);
   const res = spawnSync(process.execPath, [launcher, sub, ...passthrough], { stdio: 'inherit' });
+  if (res.error) console.error(`ijfw: failed to launch ${launcher}: ${res.error.message}`);
   process.exit(res.status ?? 1);
 }
 

package/src/dashboard-server.js

@@ -7,7 +7,7 @@
  */
 
 import { createServer } from 'node:http';
-import { existsSync, readFileSync, watch, writeFileSync, mkdirSync, readdirSync, statSync, realpathSync, renameSync, unlinkSync } from 'node:fs';
+import { existsSync, readFileSync, watch, writeFileSync, mkdirSync, readdirSync, statSync, realpathSync, renameSync, unlinkSync, openSync, readSync, closeSync, chmodSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join, dirname, resolve, relative, isAbsolute, basename, sep } from 'node:path';
@@ -174,10 +174,43 @@ function requireLocalhost(req, res) {
   return false;
 }
 
+// CSRF guard: reject cross-origin browser requests to the data API. Browsers
+// stamp Sec-Fetch-Site; the dashboard's own page is 'same-origin', direct tools
+// (curl, address bar) send 'none'/nothing. Only same-machine cross-origin pages
+// hit 'cross-site'/'same-site' -- block those on /api.
+//
+// State-changing methods (POST/PUT/PATCH/DELETE) fail CLOSED when Sec-Fetch-Site
+// is absent: a browser cross-origin write always carries an Origin header (even
+// for no-preflight text/plain "simple requests"), so any Origin/Referer that does
+// not match our own Host is rejected. Requests with no browser markers at all
+// (curl, local scripts) carry neither header and stay allowed.
+function rejectCrossSiteApi(req, res, path) {
+  if (!path.startsWith('/api')) return false;
+  function reject() {
+    res.writeHead(403, { 'Content-Type': 'application/json' });
+    res.end('{"error":"cross-origin request rejected"}');
+    return true;
+  }
+  const sfs = req.headers['sec-fetch-site'];
+  if (sfs === 'cross-site' || sfs === 'same-site') return reject();
+  const method = (req.method || 'GET').toUpperCase();
+  if (method === 'GET' || method === 'HEAD' || method === 'OPTIONS') return false;
+  // Writes: 'same-origin'/'none' are browser-proven safe; otherwise require any
+  // Origin/Referer present to match the host the request was addressed to.
+  if (sfs === 'same-origin' || sfs === 'none') return false;
+  const proof = req.headers['origin'] || req.headers['referer'];
+  if (!proof) return false;
+  let proofHost = null;
+  try { proofHost = new URL(proof).host; } catch {}
+  if (proofHost === null || proofHost !== (req.headers.host || '')) return reject();
+  return false;
+}
+
 // ---------- simple router ----------
 function route(req, res, routes) {
   const url = new URL(req.url, 'http://localhost');
   const path = url.pathname;
+  if (rejectCrossSiteApi(req, res, path)) return;
   for (const [pattern, handler] of routes) {
     if (typeof pattern === 'string' ? path === pattern : pattern.test(path)) {
       handler(req, res, url);
@@ -189,14 +222,43 @@ function route(req, res, routes) {
 }
 
 // ---------- JSONL reader ----------
+// observations.jsonl is append-only with no rotation, so an unbounded
+// synchronous read+parse on every poll would stall the single-threaded server
+// (same hazard tailEvents() was rewritten to avoid). Bound the read to the
+// last OBS_TAIL_BYTES via fd+position, and cache the parsed array keyed on
+// mtime+size so repeated polls of an unchanged file never re-read it.
+const OBS_TAIL_BYTES = 5 * 1024 * 1024; // 5MB
+const obsCache = new Map(); // ledgerPath -> { key, data }
+
 function readObservations(ledgerPath) {
-  if (!existsSync(ledgerPath)) return [];
+  let st;
+  try { st = statSync(ledgerPath); } catch { return []; }
+  const key = `${st.mtimeMs}:${st.size}`;
+  const cached = obsCache.get(ledgerPath);
+  if (cached && cached.key === key) return cached.data;
   try {
-    return readFileSync(ledgerPath, 'utf8')
-      .split('\n')
-      .filter(Boolean)
+    const start = Math.max(0, st.size - OBS_TAIL_BYTES);
+    const len = st.size - start;
+    const buf = Buffer.allocUnsafe(len);
+    const fd = openSync(ledgerPath, 'r');
+    let read = 0;
+    try {
+      while (read < len) {
+        const n = readSync(fd, buf, read, len - read, start + read);
+        if (n === 0) break;
+        read += n;
+      }
+    } finally {
+      closeSync(fd);
+    }
+    let lines = buf.subarray(0, read).toString('utf8').split('\n').filter(Boolean);
+    // If we sliced mid-line, the first element may be truncated -- drop it.
+    if (start > 0) lines = lines.slice(1);
+    const data = lines
       .map(l => { try { return JSON.parse(l); } catch { return null; } })
       .filter(Boolean);
+    obsCache.set(ledgerPath, { key, data });
+    return data;
   } catch {
     return [];
   }
@@ -814,8 +876,11 @@ export async function startServer(options = {}) {
         req.on('end', () => {
           try {
             const parsed = JSON.parse(body);
-            mkdirSync(join(homedir(), '.ijfw'), { recursive: true });
-            writeFileSync(configPath, JSON.stringify(parsed, null, 2), 'utf8');
+            mkdirSync(join(homedir(), '.ijfw'), { recursive: true, mode: 0o700 });
+            // 0o600: config holds account/subscription data; keep it owner-only
+            // (mode only applies on create, so chmod existing files too).
+            writeFileSync(configPath, JSON.stringify(parsed, null, 2), { encoding: 'utf8', mode: 0o600 });
+            try { chmodSync(configPath, 0o600); } catch {}
             res.writeHead(200, { 'Content-Type': 'application/json' });
             res.end(JSON.stringify({ ok: true }));
           } catch (err) {
@@ -1481,6 +1546,50 @@ if (process.argv.includes('--daemon')) {
   const pidFile  = process.env.IJFW_PID_FILE  || join(homedir(), '.ijfw', 'dashboard.pid');
   const portFile = process.env.IJFW_PORT_FILE || join(homedir(), '.ijfw', 'dashboard.port');
 
+  // Singleton guard: the spawner's pid-check (session-start.sh) is a classic
+  // check-then-act race -- two sessions starting in the same window both see no
+  // live daemon and both spawn --daemon. Without a guard here, the loser walks
+  // to the next port and OVERWRITES the shared pid/port files, orphaning the
+  // winner forever. Acquire the pid file with O_EXCL BEFORE binding: exactly
+  // one starter wins; losers exit 0 without binding or clobbering. A pid file
+  // whose owner is dead is stale and reclaimed once.
+  const ijfwDir = dirname(pidFile);
+  mkdirSync(ijfwDir, { recursive: true });
+
+  function pidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0) return false;
+    try { process.kill(pid, 0); return true; }
+    catch (err) { return err.code === 'EPERM'; }
+  }
+
+  function acquirePidFile() {
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        writeFileSync(pidFile, String(process.pid), { encoding: 'utf8', flag: 'wx' });
+        return true;
+      } catch (err) {
+        if (err.code !== 'EEXIST') throw err;
+        let holder = NaN;
+        try { holder = Number.parseInt(readFileSync(pidFile, 'utf8').trim(), 10); } catch {}
+        if (pidAlive(holder)) return false; // live daemon already owns it
+        try { unlinkSync(pidFile); } catch {} // stale -- reclaim and retry once
+      }
+    }
+    return false; // lost the reclaim race to another starter; that one serves
+  }
+
+  if (!acquirePidFile()) {
+    process.stderr.write('[ijfw-dashboard] daemon already running -- exiting\n');
+    process.exit(0);
+  }
+
+  function releasePidFile() {
+    // Only remove the pid file if it is still ours.
+    try {
+      if (readFileSync(pidFile, 'utf8').trim() === String(process.pid)) unlinkSync(pidFile);
+    } catch {}
+  }
+
   // Optional preferred-port override (forwarded by the launcher's `--port N`).
   // Unset = default 37891-37900 walk. Invalid values fall back to the default.
   const startOpts = {};
@@ -1488,10 +1597,6 @@ if (process.argv.includes('--daemon')) {
   if (Number.isInteger(envPort) && envPort > 0 && envPort < 65536) startOpts.port = envPort;
 
   startServer(startOpts).then(({ port }) => {
-    const ijfwDir = dirname(pidFile);
-    mkdirSync(ijfwDir, { recursive: true });
-    // PID file: plain write (single writer; pid is meaningless mid-write)
-    writeFileSync(pidFile, String(process.pid), 'utf8');
     // Port file: atomic write via tmp+rename so readers never see a partial value (W4.2).
     // Cleanup tmp on rename failure so it doesn't leak (W9-M1).
     const portTmp = `${portFile}.tmp.${process.pid}.${Date.now()}`;
@@ -1503,6 +1608,7 @@ if (process.argv.includes('--daemon')) {
       throw new Error(`atomic write failed for ${portFile}: ${err.message}`);
     }
   }).catch(err => {
+    releasePidFile();
     process.stderr.write('[ijfw-dashboard] ' + err.message + '\n');
     process.exit(1);
   });

package/src/design/iframe-bridge.js

@@ -99,10 +99,18 @@ export async function createPreviewSandbox({ html, name } = {}) {
   // surface for vercel-sandbox is evolving; we accept any JSON line that
   // contains a `url` field.
   try {
+    // shell:true on Windows so the vercel.cmd npm shim resolves; harmless on
+    // POSIX. sandboxId/tmpFile are internally generated (sanitized name +
+    // uuid under tmpdir), not user input.
     const r = spawnSync('vercel', ['sandbox', 'create', '--file', tmpFile, '--name', sandboxId], {
       encoding: 'utf8',
       timeout: PROVISION_TIMEOUT_MS,
+      shell: process.platform === 'win32',
     });
+    if (r.error) {
+      _advise(`createPreviewSandbox: vercel CLI not spawnable (${r.error.message}) -- falling back to static`);
+      return null;
+    }
     if (r.status !== 0) {
       _advise(`createPreviewSandbox: vercel CLI exit ${r.status} -- falling back to static`);
       return null;
@@ -140,7 +148,11 @@ export async function destroySandbox(sandboxId) {
       return;
     }
     if (entry.mode === 'cli') {
-      spawnSync('vercel', ['sandbox', 'delete', sandboxId], { encoding: 'utf8', timeout: DESTROY_TIMEOUT_MS });
+      spawnSync('vercel', ['sandbox', 'delete', sandboxId], {
+        encoding: 'utf8',
+        timeout: DESTROY_TIMEOUT_MS,
+        shell: process.platform === 'win32',
+      });
       return;
     }
   } catch (err) {