@mindrian_os/install 1.13.0-beta.11

package/lib/memory/write-lock-atomic.test.cjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+/**
+ * Phase 87-02 concurrency test: prove the atomic openSync('wx') acquire
+ * allows exactly ONE of N racing processes to win the write lock.
+ *
+ * BSL 1.1. Copyright (c) Mindrian 2026.
+ *
+ * Tests (run sequentially within a single parent process):
+ *   1. Spawn 20 forked children; exactly 1 exits 0, 19 exit 1 ("lock held")
+ *   2. Release by the winner, re-acquire from parent -> succeeds
+ *   3. Same-PID re-acquire (parent calls acquireLock twice) -> no throw
+ *
+ * The test uses child_process.fork to get true OS-level concurrency,
+ * not mocked "parallel" promises inside one event loop.
+ *
+ * Exit 0 on all pass, 1 on any failure. Integrated into the Feynman
+ * runner alongside other Phase 87-0x regression fences.
+ */
+
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { fork } = require('node:child_process');
+
+const { acquireLock, releaseLock } = require('../core/write-lock.cjs');
+
+const WORKER_SCRIPT = path.join(__dirname, 'write-lock-atomic.worker.cjs');
+const WORKERS = 20;
+
+async function main() {
+  // Sanity: the worker file we rely on must exist before we start forking.
+  assert.ok(
+    fs.existsSync(WORKER_SCRIPT),
+    'worker script missing: ' + WORKER_SCRIPT
+  );
+
+  const tmpRoom = fs.mkdtempSync(path.join(os.tmpdir(), 'lockrace-'));
+
+  try {
+    // ---------------------------------------------------------------------
+    // Test 1: 20 concurrent forked workers -- exactly 1 winner
+    // ---------------------------------------------------------------------
+    const forkPromises = [];
+    for (let i = 0; i < WORKERS; i++) {
+      forkPromises.push(
+        new Promise((resolve) => {
+          const child = fork(WORKER_SCRIPT, [tmpRoom], { silent: true });
+          let stderrBuf = '';
+          if (child.stderr) {
+            child.stderr.on('data', (chunk) => {
+              stderrBuf += chunk.toString();
+            });
+          }
+          child.on('exit', (code) => {
+            resolve({ code, stderr: stderrBuf });
+          });
+        })
+      );
+    }
+
+    const results = await Promise.all(forkPromises);
+    const codes = results.map((r) => r.code);
+    const winners = codes.filter((c) => c === 0).length;
+    const losers = codes.filter((c) => c === 1).length;
+    const unexpected = codes.filter((c) => c !== 0 && c !== 1).length;
+
+    if (unexpected !== 0) {
+      // Dump stderr for diagnostics before failing the assert.
+      for (const r of results) {
+        if (r.code !== 0 && r.code !== 1 && r.stderr) {
+          process.stderr.write('[worker stderr] ' + r.stderr);
+        }
+      }
+    }
+
+    assert.strictEqual(
+      unexpected,
+      0,
+      'unexpected exit codes among workers: ' + codes.join(',')
+    );
+    assert.strictEqual(
+      winners,
+      1,
+      'expected exactly 1 winner, got ' + winners + ' (codes: ' + codes.join(',') + ')'
+    );
+    assert.strictEqual(
+      losers,
+      WORKERS - 1,
+      'expected ' + (WORKERS - 1) + ' losers, got ' + losers
+    );
+
+    // ---------------------------------------------------------------------
+    // Test 2: release then re-acquire succeeds
+    // ---------------------------------------------------------------------
+    // The winning worker exited without releasing its lock file. We clean
+    // it up via releaseLock and re-acquire from the parent.
+    releaseLock(tmpRoom);
+    assert.doesNotThrow(
+      () => acquireLock(tmpRoom),
+      'post-release acquire should succeed'
+    );
+
+    // ---------------------------------------------------------------------
+    // Test 3: same-PID re-acquire does not throw
+    // ---------------------------------------------------------------------
+    // Same PID owns the lock -- the m11 rationale path. Must not throw.
+    assert.doesNotThrow(
+      () => acquireLock(tmpRoom),
+      'same-PID re-acquire must not throw'
+    );
+
+    // Cleanup: release parent-held lock before tmp teardown.
+    releaseLock(tmpRoom);
+
+    process.stdout.write(
+      'write-lock-atomic: all tests passed (winners=1, losers=' + (WORKERS - 1) + ', re-acquire green)\n'
+    );
+  } finally {
+    try {
+      fs.rmSync(tmpRoom, { recursive: true, force: true });
+    } catch (_) {
+      // ignore teardown errors
+    }
+  }
+}
+
+main().then(
+  () => process.exit(0),
+  (err) => {
+    process.stderr.write('write-lock-atomic FAIL: ' + (err && err.message || err) + '\n');
+    if (err && err.stack) process.stderr.write(err.stack + '\n');
+    process.exit(1);
+  }
+);

package/lib/memory/write-lock-atomic.worker.cjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * Worker process for write-lock-atomic.test.cjs (Phase 87-02).
+ *
+ * BSL 1.1. Copyright (c) Mindrian 2026.
+ *
+ * Forked by the parent test. Attempts acquireLock on the roomDir passed
+ * via argv[2]. Exit codes:
+ *   0 -- acquired successfully
+ *   1 -- saw expected "SQLite write lock held by PID" (valid contention loss)
+ *   3 -- unexpected error (propagate for parent diagnostics)
+ *
+ * Written as a standalone file (not inline template string) to avoid
+ * Windows/Linux path-escape ambiguity in the parent test source.
+ */
+
+'use strict';
+
+const path = require('node:path');
+
+// Resolve the write-lock module relative to THIS worker file's location.
+// __dirname is lib/memory/, target is lib/core/write-lock.cjs.
+const { acquireLock } = require(path.resolve(__dirname, '..', 'core', 'write-lock.cjs'));
+
+const roomDir = process.argv[2];
+
+if (!roomDir) {
+  process.stderr.write('write-lock-atomic.worker: missing roomDir argv[2]\n');
+  process.exit(3);
+}
+
+try {
+  acquireLock(roomDir);
+  // Held lock -- winner. Must stay alive long enough for losers to finish
+  // their EEXIST + process.kill(winnerPid, 0) liveness check, otherwise
+  // the lock's dead-PID cleanup path lets multiple workers "win" in
+  // sequence (staggered), which is valid lock-system behavior but does
+  // NOT prove the atomic-create primitive.
+  //
+  // Winner sleep duration tuned for the release-gate stability floor
+  // (Phase 87-10). Under heavy WSL2 load, the original 500ms was too
+  // short -- a slow-starting loser could complete its liveness check
+  // AFTER the winner had already exited, see the dead-PID cleanup
+  // path unlink the lock, and re-acquire as a second "winner".
+  // Observed flake rate under 22-test suite parallelism: ~40%.
+  // 3000ms is 6x headroom: empirically stable across 10+ consecutive
+  // runs under the same load profile that produced the flake.
+  setTimeout(() => process.exit(0), 3000);
+} catch (e) {
+  if (e && e.message && e.message.startsWith('SQLite write lock')) {
+    process.exit(1);
+  }
+  process.stderr.write('write-lock-atomic.worker unexpected: ' + (e && e.message || e) + '\n');
+  process.exit(3);
+}

package/lib/parity/check-parity.cjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * CLI/MCP Parity Check
+ *
+ * Validates that every CLI command in commands/ has a corresponding
+ * MCP tool path in the hierarchical router. Designed for CI — exits 1
+ * on any missing mapping so parity drift is caught automatically.
+ *
+ * Usage:  node lib/parity/check-parity.cjs
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const COMMANDS_DIR = path.join(REPO_ROOT, 'commands');
+const TOOL_ROUTER = path.join(REPO_ROOT, 'lib', 'mcp', 'tool-router.cjs');
+
+// ── 1. Read CLI commands from commands/*.md ──────────────────────────────────
+
+if (!fs.existsSync(COMMANDS_DIR)) {
+  process.stderr.write(`ERROR: commands/ directory not found at ${COMMANDS_DIR}\n`);
+  process.exit(1);
+}
+
+const cliCommands = fs.readdirSync(COMMANDS_DIR)
+  .filter(f => f.endsWith('.md'))
+  .map(f => f.replace(/\.md$/, ''))
+  .sort();
+
+if (cliCommands.length === 0) {
+  process.stderr.write('ERROR: No .md files found in commands/ directory\n');
+  process.exit(1);
+}
+
+// ── 2. Import ALL_TOOL_COMMANDS from tool router ─────────────────────────────
+
+if (!fs.existsSync(TOOL_ROUTER)) {
+  process.stderr.write(`ERROR: tool-router.cjs not found at ${TOOL_ROUTER}\n`);
+  process.exit(1);
+}
+
+let ALL_TOOL_COMMANDS;
+try {
+  ({ ALL_TOOL_COMMANDS } = require(TOOL_ROUTER));
+} catch (err) {
+  process.stderr.write(`ERROR: Failed to load tool-router.cjs: ${err.message}\n`);
+  process.exit(1);
+}
+
+if (!Array.isArray(ALL_TOOL_COMMANDS)) {
+  process.stderr.write('ERROR: ALL_TOOL_COMMANDS is not an array\n');
+  process.exit(1);
+}
+
+const mcpSet = new Set(ALL_TOOL_COMMANDS);
+const cliSet = new Set(cliCommands);
+
+// ── 3. Compare ───────────────────────────────────────────────────────────────
+
+const missingInMcp = cliCommands.filter(cmd => !mcpSet.has(cmd));
+const extraInMcp = ALL_TOOL_COMMANDS.filter(cmd => !cliSet.has(cmd));
+
+// ── 4. Report ────────────────────────────────────────────────────────────────
+
+if (missingInMcp.length > 0) {
+  process.stderr.write(`FAIL: ${missingInMcp.length} CLI command(s) missing from MCP tools:\n`);
+  missingInMcp.forEach(cmd => process.stderr.write(`  - ${cmd}\n`));
+}
+
+if (extraInMcp.length > 0) {
+  process.stderr.write(`WARNING: ${extraInMcp.length} MCP tool command(s) not in CLI commands/:\n`);
+  extraInMcp.forEach(cmd => process.stderr.write(`  - ${cmd}\n`));
+}
+
+if (missingInMcp.length > 0) {
+  process.exit(1);
+}
+
+process.stdout.write(`Parity OK: ${cliCommands.length} CLI commands, ${ALL_TOOL_COMMANDS.length} MCP tool commands\n`);
+process.exit(0);

package/lib/presentation/presentation-server.cjs

@@ -0,0 +1,101 @@
+'use strict';
+/**
+ * presentation-server.cjs -- Express static server for presentation live reload
+ *
+ * Serves the exports/presentation/ directory as static files with SSE
+ * auto-reload injection. HTML responses get a small SSE client script
+ * injected before </body> so browsers auto-reload on room file changes.
+ *
+ * SSE injection is SERVER-SIDE ONLY -- deployed/static HTML files
+ * have zero SSE code baked in.
+ */
+
+const express = require('express');
+const fs = require('fs');
+const path = require('path');
+const { startWatcher, addSSEClient } = require('./presentation-watcher.cjs');
+
+// Minimal SSE client script injected into HTML responses
+const SSE_SCRIPT = `<script>(function(){var es=new EventSource('/__sse');es.onmessage=function(){location.reload()};es.onerror=function(){setTimeout(function(){location.reload()},3000)}})()</script>`;
+
+/**
+ * Start the presentation Express server.
+ * @param {string} roomDir - Path to room/ directory
+ * @param {number} [port=8422] - Port to listen on
+ * @returns {Promise<{app, server, port, watcher}>}
+ */
+function startPresentationServer(roomDir, port) {
+  port = port || 8422;
+  const absRoom = path.resolve(roomDir);
+  const outputDir = path.join(absRoom, 'exports', 'presentation');
+  const pluginRoot = path.join(__dirname, '..', '..');
+
+  // Verify output directory exists
+  if (!fs.existsSync(outputDir)) {
+    console.error(`ERROR: ${outputDir} does not exist.`);
+    console.error('Run generate-presentation.cjs first to create the presentation views.');
+    process.exit(1);
+  }
+
+  const app = express();
+
+  // -- SSE endpoint: connected browsers listen here for reload events --
+  app.get('/__sse', (req, res) => {
+    addSSEClient(res);
+  });
+
+  // -- HTML interception: inject SSE script before </body> --
+  // This middleware runs BEFORE express.static so we can intercept HTML
+  app.use((req, res, next) => {
+    // Only intercept .html requests or directory index
+    const reqPath = req.path;
+    const htmlPath = reqPath.endsWith('.html')
+      ? path.join(outputDir, reqPath)
+      : reqPath === '/' || reqPath.endsWith('/')
+        ? path.join(outputDir, reqPath, 'index.html')
+        : null;
+
+    if (!htmlPath || !fs.existsSync(htmlPath)) {
+      return next(); // Let express.static handle non-HTML or missing files
+    }
+
+    try {
+      let html = fs.readFileSync(htmlPath, 'utf8');
+
+      // Inject SSE script before closing </body> tag
+      if (html.includes('</body>')) {
+        html = html.replace('</body>', SSE_SCRIPT + '</body>');
+      } else {
+        // No </body> tag -- append to end
+        html += SSE_SCRIPT;
+      }
+
+      res.type('html').send(html);
+    } catch (err) {
+      next(); // Fall through to static on read error
+    }
+  });
+
+  // -- Static file serving for non-HTML assets (CSS, JS, images, JSON) --
+  app.use(express.static(outputDir));
+
+  // -- Start chokidar watcher on the ROOM directory --
+  const watcher = startWatcher(absRoom, outputDir, pluginRoot);
+
+  // -- Start server --
+  return new Promise((resolve) => {
+    const server = app.listen(port, () => {
+      console.log(`Presentation running at http://localhost:${port}`);
+      resolve({ app, server, port, watcher });
+    });
+  });
+}
+
+// -- CLI entry mode --
+if (require.main === module) {
+  const roomDir = process.argv[2] || './room';
+  const port = parseInt(process.argv[3] || '8422', 10);
+  startPresentationServer(roomDir, port);
+}
+
+module.exports = { startPresentationServer };

package/lib/presentation/presentation-watcher.cjs

@@ -0,0 +1,123 @@
+'use strict';
+/**
+ * presentation-watcher.cjs -- File watcher + SSE broadcast for presentation auto-refresh
+ *
+ * Watches room/ directory via chokidar. On file changes, triggers
+ * presentation regeneration and broadcasts SSE events to all
+ * connected browser clients.
+ */
+
+const chokidar = require('chokidar');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const sseClients = new Set();
+
+// Debounce timer for regeneration
+let regenTimer = null;
+const REGEN_DEBOUNCE_MS = 1000;
+
+/**
+ * Start watching a room directory for changes.
+ * On change: regenerate presentation views, then broadcast SSE reload.
+ *
+ * @param {string} roomDir - Path to room/ directory
+ * @param {string} outputDir - Path to exports/presentation/ directory
+ * @param {string} pluginRoot - Path to plugin root (for generate-presentation.cjs)
+ * @returns {object} chokidar watcher instance
+ */
+function startWatcher(roomDir, outputDir, pluginRoot) {
+  const absRoom = path.resolve(roomDir);
+  const absOutput = path.resolve(outputDir);
+  const generatorPath = path.join(pluginRoot, 'scripts', 'generate-presentation.cjs');
+
+  const watcher = chokidar.watch(absRoom, {
+    ignoreInitial: true,
+    ignored: [
+      /\.mindrian/,
+      /\.reasoning/,
+      /node_modules/,
+      /\.git/,
+      /exports\/presentation/  // Don't watch our own output
+    ],
+    persistent: true,
+    awaitWriteFinish: {
+      stabilityThreshold: 500,
+      pollInterval: 100
+    }
+  });
+
+  watcher.on('all', (event, filePath) => {
+    const relPath = path.relative(absRoom, filePath);
+    console.log(`[presentation] ${event}: ${relPath}`);
+
+    // Debounce regeneration to avoid hammering during rapid multi-file writes
+    if (regenTimer) clearTimeout(regenTimer);
+    regenTimer = setTimeout(() => {
+      try {
+        execSync(
+          `node "${generatorPath}" "${absRoom}" --output "${absOutput}"`,
+          { timeout: 15000, stdio: 'pipe' }
+        );
+        console.log('[presentation] Regenerated views');
+      } catch (err) {
+        console.error('[presentation] Regeneration failed:', err.message);
+      }
+
+      // Broadcast SSE reload event to all connected browsers
+      broadcast({ event: 'change', path: relPath, type: event });
+    }, REGEN_DEBOUNCE_MS);
+  });
+
+  return watcher;
+}
+
+/**
+ * Add an SSE client (Express response object).
+ * Sets appropriate headers and sends initial keepalive.
+ * @param {object} res - Express response object
+ */
+function addSSEClient(res) {
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    'Connection': 'keep-alive'
+  });
+
+  // Initial keepalive comment
+  res.write(':keepalive\n\n');
+
+  sseClients.add(res);
+
+  // Clean up on disconnect
+  res.on('close', () => {
+    removeSSEClient(res);
+  });
+}
+
+/**
+ * Remove an SSE client from the set.
+ * @param {object} res - Express response object
+ */
+function removeSSEClient(res) {
+  sseClients.delete(res);
+}
+
+/**
+ * Broadcast an SSE event to all connected clients.
+ * @param {object} data - Event data to serialize as JSON
+ */
+function broadcast(data) {
+  const message = `data: ${JSON.stringify(data)}\n\n`;
+
+  for (const client of sseClients) {
+    try {
+      client.write(message);
+    } catch (e) {
+      // Client disconnected -- remove
+      sseClients.delete(client);
+    }
+  }
+}
+
+module.exports = { startWatcher, addSSEClient, removeSSEClient };