@nforma.ai/nforma 0.2.1

package/bin/review-mcp-logs.cjs

@@ -0,0 +1,294 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * review-mcp-logs.cjs
+ *
+ * Scans ~/.claude/debug/*.txt for MCP tool call timing, failures, and hang
+ * patterns. Outputs a structured report surfacing automation opportunities.
+ *
+ * Usage:
+ *   node bin/review-mcp-logs.cjs [--files N] [--days N] [--json] [--tool <name>]
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// ─── CLI args ─────────────────────────────────────────────────────────────────
+const args = process.argv.slice(2);
+const getArg = (flag) => {
+  const i = args.indexOf(flag);
+  return i !== -1 && args[i + 1] ? args[i + 1] : null;
+};
+const hasFlag = (flag) => args.includes(flag);
+
+const MAX_FILES   = parseInt(getArg('--files') ?? '50', 10);
+const MAX_DAYS    = parseInt(getArg('--days')  ?? '7',  10);
+const JSON_OUTPUT = hasFlag('--json');
+const TOOL_FILTER = getArg('--tool');
+
+// ─── Paths ────────────────────────────────────────────────────────────────────
+const DEBUG_DIR = path.join(os.homedir(), '.claude', 'debug');
+
+// ─── Regex patterns ───────────────────────────────────────────────────────────
+// MCP tool timing lines emitted by Claude Code
+const RE_RUNNING  = /MCP server "([^"]+)": Tool '([^']+)' still running \((\d+)s elapsed\)/;
+const RE_COMPLETE = /MCP server "([^"]+)": Tool '([^']+)' completed successfully in (\d+)ms/;
+const RE_FAILED   = /MCP server "([^"]+)": Tool '([^']+)' failed after (\d+)s: (.+)/;
+const RE_CALLING  = /MCP server "([^"]+)": Calling MCP tool: (.+)/;
+const RE_STDERR   = /MCP server "([^"]+)" Server stderr: (.+)/;
+const RE_CONNECT  = /MCP server "([^"]+)": Successfully connected .+ in (\d+)ms/;
+const RE_TOOL_ERR = /mcp__([^_]+)__(\S+) tool error \((\d+)ms\): (.+)/;
+const RE_TIMESTAMP = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d+Z)/;
+
+// ─── Data structures ──────────────────────────────────────────────────────────
+const servers   = {};   // serverName -> { calls: [], failures: [], hangs: [] }
+const timeline  = [];   // [{ts, server, tool, durationMs, status}]
+const stderrLog = {};   // serverName -> [messages]
+
+function ensureServer(name) {
+  if (!servers[name]) {
+    servers[name] = { calls: [], failures: [], hangs: [], connectMs: null };
+  }
+  return servers[name];
+}
+
+// ─── Parse files ──────────────────────────────────────────────────────────────
+const cutoff = Date.now() - MAX_DAYS * 86400 * 1000;
+
+let files;
+try {
+  files = fs.readdirSync(DEBUG_DIR)
+    .filter(f => f.endsWith('.txt'))
+    .map(f => ({ name: f, mtime: fs.statSync(path.join(DEBUG_DIR, f)).mtimeMs }))
+    .filter(f => f.mtime >= cutoff)
+    .sort((a, b) => b.mtime - a.mtime)
+    .slice(0, MAX_FILES)
+    .map(f => path.join(DEBUG_DIR, f.name));
+} catch {
+  console.error(`Cannot read debug dir: ${DEBUG_DIR}`);
+  process.exit(1);
+}
+
+if (files.length === 0) {
+  console.log(`No debug files found in last ${MAX_DAYS} days at ${DEBUG_DIR}`);
+  process.exit(0);
+}
+
+for (const file of files) {
+  let content;
+  try { content = fs.readFileSync(file, 'utf8'); } catch { continue; }
+
+  for (const line of content.split('\n')) {
+    const tsMatch = line.match(RE_TIMESTAMP);
+    const ts = tsMatch ? new Date(tsMatch[1]).getTime() : 0;
+
+    let m;
+
+    if ((m = line.match(RE_COMPLETE))) {
+      const [, server, tool, ms] = m;
+      if (TOOL_FILTER && !server.includes(TOOL_FILTER) && !tool.includes(TOOL_FILTER)) continue;
+      const s = ensureServer(server);
+      s.calls.push({ tool, durationMs: parseInt(ms, 10), status: 'ok', ts });
+      timeline.push({ ts, server, tool, durationMs: parseInt(ms, 10), status: 'ok' });
+    }
+
+    else if ((m = line.match(RE_FAILED))) {
+      const [, server, tool, sec, reason] = m;
+      if (TOOL_FILTER && !server.includes(TOOL_FILTER) && !tool.includes(TOOL_FILTER)) continue;
+      const s = ensureServer(server);
+      const durationMs = parseInt(sec, 10) * 1000;
+      s.failures.push({ tool, durationMs, reason: reason.trim(), ts });
+      timeline.push({ ts, server, tool, durationMs, status: 'fail', reason: reason.trim() });
+      if (durationMs > 60000) s.hangs.push({ tool, durationMs, reason: reason.trim(), ts });
+    }
+
+    else if ((m = line.match(RE_TOOL_ERR))) {
+      const [, serverPart, tool, ms, reason] = m;
+      const server = `claude-${serverPart}`;
+      if (TOOL_FILTER && !server.includes(TOOL_FILTER) && !tool.includes(TOOL_FILTER)) continue;
+      const s = ensureServer(server);
+      const durationMs = parseInt(ms, 10);
+      s.failures.push({ tool, durationMs, reason: reason.trim(), ts, fromToolError: true });
+    }
+
+    else if ((m = line.match(RE_CONNECT))) {
+      const [, server, ms] = m;
+      ensureServer(server).connectMs = parseInt(ms, 10);
+    }
+
+    else if ((m = line.match(RE_STDERR))) {
+      const [, server, msg] = m;
+      if (!stderrLog[server]) stderrLog[server] = [];
+      stderrLog[server].push(msg.trim());
+    }
+  }
+}
+
+// ─── Compute per-server stats ─────────────────────────────────────────────────
+const serverStats = {};
+for (const [name, data] of Object.entries(servers)) {
+  const ok = data.calls;
+  const failed = data.failures;
+  const durations = ok.map(c => c.durationMs);
+
+  serverStats[name] = {
+    totalCalls:    ok.length + failed.length,
+    successCount:  ok.length,
+    failureCount:  failed.length,
+    hangCount:     data.hangs.length,
+    connectMs:     data.connectMs,
+    p50Ms:  percentile(durations, 50),
+    p95Ms:  percentile(durations, 95),
+    maxMs:  durations.length ? Math.max(...durations) : 0,
+    failures:      failed,
+    hangs:         data.hangs,
+  };
+}
+
+// ─── Automation patterns ──────────────────────────────────────────────────────
+// Find tools that always fail — automation target: add to UNAVAIL skip list
+const alwaysFailing = Object.entries(serverStats)
+  .filter(([, s]) => s.totalCalls > 0 && s.successCount === 0)
+  .map(([name]) => name);
+
+// Find tools with consistent long latency — automation target: increase timeout or route differently
+const slowServers = Object.entries(serverStats)
+  .filter(([, s]) => s.p95Ms > 30000 && s.successCount > 0)
+  .sort(([, a], [, b]) => b.p95Ms - a.p95Ms);
+
+// Find recurring error messages — may hint at config fixes
+const errorFreq = {};
+for (const [server, data] of Object.entries(servers)) {
+  for (const f of data.failures) {
+    const key = f.reason.slice(0, 80);
+    errorFreq[key] = (errorFreq[key] ?? 0) + 1;
+  }
+}
+const topErrors = Object.entries(errorFreq)
+  .sort(([, a], [, b]) => b - a)
+  .slice(0, 8);
+
+// ─── Output ───────────────────────────────────────────────────────────────────
+if (JSON_OUTPUT) {
+  console.log(JSON.stringify({ serverStats, alwaysFailing, slowServers: slowServers.map(([n, s]) => ({ name: n, p95Ms: s.p95Ms, maxMs: s.maxMs })), topErrors }, null, 2));
+  process.exit(0);
+}
+
+const hr = '─'.repeat(60);
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const red   = (s) => `\x1b[31m${s}\x1b[0m`;
+const yellow= (s) => `\x1b[33m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const cyan  = (s) => `\x1b[36m${s}\x1b[0m`;
+const dim   = (s) => `\x1b[2m${s}\x1b[0m`;
+
+const fmtMs = (ms) => {
+  if (!ms) return dim('—');
+  if (ms >= 60000) return red(`${(ms/1000).toFixed(0)}s`);
+  if (ms >= 10000) return yellow(`${(ms/1000).toFixed(1)}s`);
+  return green(`${ms}ms`);
+};
+
+console.log(`\n${bold('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')}`);
+console.log(bold(' QGSD ► MCP LOG REVIEW'));
+console.log(bold('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+console.log(dim(` Scanned: ${files.length} debug files | Last ${MAX_DAYS} days | ${DEBUG_DIR}`));
+console.log();
+
+// ── Per-server table ──────────────────────────────────────────────────────────
+console.log(bold('MCP SERVER HEALTH'));
+console.log(hr);
+
+const colW = [22, 6, 6, 6, 6, 10, 10, 10];
+const header = [
+  'Server', 'Calls', 'OK', 'Fail', 'Hang', 'p50', 'p95', 'max'
+].map((h, i) => h.padEnd(colW[i])).join('  ');
+console.log(dim(header));
+
+for (const [name, s] of Object.entries(serverStats).sort(([a],[b]) => a.localeCompare(b))) {
+  const failColor = s.failureCount > 0 ? red : green;
+  const hangColor = s.hangCount > 0 ? red : dim;
+  const row = [
+    name.slice(0, 21).padEnd(colW[0]),
+    String(s.totalCalls).padEnd(colW[1]),
+    green(String(s.successCount)).padEnd(colW[2] + 9),
+    failColor(String(s.failureCount)).padEnd(colW[3] + 9),
+    hangColor(String(s.hangCount)).padEnd(colW[4] + 9),
+    fmtMs(s.p50Ms).padEnd(colW[5] + 9),
+    fmtMs(s.p95Ms).padEnd(colW[6] + 9),
+    fmtMs(s.maxMs),
+  ].join('  ');
+  console.log(row);
+}
+console.log();
+
+// ── Failures detail ───────────────────────────────────────────────────────────
+const allFailures = Object.entries(serverStats)
+  .flatMap(([server, s]) => s.failures.map(f => ({ server, ...f })))
+  .sort((a, b) => b.ts - a.ts)
+  .slice(0, 15);
+
+if (allFailures.length > 0) {
+  console.log(bold('RECENT FAILURES (last 15)'));
+  console.log(hr);
+  for (const f of allFailures) {
+    const dt = f.ts ? new Date(f.ts).toISOString().slice(0,19).replace('T',' ') : '?';
+    console.log(`  ${dim(dt)}  ${yellow(f.server)}  ${cyan(f.tool)}  ${fmtMs(f.durationMs)}`);
+    console.log(`    ${dim(f.reason.slice(0, 100))}`);
+  }
+  console.log();
+}
+
+// ── Automation insights ───────────────────────────────────────────────────────
+console.log(bold('AUTOMATION INSIGHTS'));
+console.log(hr);
+
+if (alwaysFailing.length > 0) {
+  console.log(red('  ✗ Always-failing servers (add to UNAVAIL skip list):'));
+  alwaysFailing.forEach(s => console.log(`    • ${s}`));
+  console.log();
+}
+
+if (slowServers.length > 0) {
+  console.log(yellow('  ⚠ Chronically slow servers (p95 > 30s):'));
+  slowServers.forEach(([name, s]) => {
+    console.log(`    • ${name}  p95=${fmtMs(s.p95Ms)}  max=${fmtMs(s.maxMs)}`);
+    console.log(`      → consider raising CLAUDE_MCP_TIMEOUT_MS or routing via faster provider`);
+  });
+  console.log();
+}
+
+if (topErrors.length > 0) {
+  console.log(cyan('  ↻ Most common error patterns:'));
+  topErrors.forEach(([msg, count]) => {
+    console.log(`    [${count}x] ${dim(msg)}`);
+  });
+  console.log();
+}
+
+// ── Suggested CLAUDE_MCP_TIMEOUT_MS ──────────────────────────────────────────
+const allP95 = Object.values(serverStats).map(s => s.p95Ms).filter(Boolean);
+if (allP95.length > 0) {
+  const suggested = Math.max(60000, Math.min(300000, Math.ceil(Math.max(...allP95) * 1.5 / 10000) * 10000));
+  console.log(bold('SUGGESTED CONFIG'));
+  console.log(hr);
+  console.log(`  CLAUDE_MCP_TIMEOUT_MS=${suggested}  ${dim('(1.5× observed p95 max, capped 60s–300s)')}`);
+  console.log(`  ${dim('Set this in ~/.claude.json env for claude-deepseek/minimax/etc.')}`);
+  console.log();
+}
+
+console.log(bold('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━'));
+console.log(dim(` Run with --json for machine-readable output`));
+console.log(dim(` Run with --tool <name> to filter a specific server`));
+console.log(dim(` Run with --days N to change lookback window`));
+console.log();
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function percentile(arr, p) {
+  if (!arr.length) return 0;
+  const sorted = [...arr].sort((a, b) => a - b);
+  const idx = Math.ceil((p / 100) * sorted.length) - 1;
+  return sorted[Math.max(0, idx)];
+}

package/bin/run-account-manager-tlc.cjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+'use strict';
+// bin/run-account-manager-tlc.cjs
+// Invokes TLC model checker for the QGSD account manager TLA+ specification.
+// Source spec: .planning/formal/tla/QGSDAccountManager.tla
+// Source impl: bin/account-manager.cjs
+//
+// Checks:
+//   TypeOK              — all variables conform to declared types
+//   ActiveIsPoolMember  — active account (when set) must be in the pool
+//   NoActiveWhenEmpty   — empty pool implies no active account
+//   IdleNoPending       — in IDLE state, no pending operation
+//   OpMatchesState      — pending_op.type matches current FSM state
+//   IdleReachable       — IDLE is eventually reachable from any state (liveness)
+//
+// Usage:
+//   node bin/run-account-manager-tlc.cjs                    # default: MCaccount-manager
+//   node bin/run-account-manager-tlc.cjs MCaccount-manager
+//   node bin/run-account-manager-tlc.cjs --config=MCaccount-manager
+//
+// Prerequisites:
+//   - Java >=17 (https://adoptium.net/)
+//   - .planning/formal/tla/tla2tools.jar (see .planning/formal/tla/README.md for download command)
+
+const { spawnSync } = require('child_process');
+const JAVA_HEAP_MAX = process.env.QGSD_JAVA_HEAP_MAX || '512m';
+const fs   = require('fs');
+const path = require('path');
+const { writeCheckResult } = require('./write-check-result.cjs');
+const { detectLivenessProperties } = require('./run-tlc.cjs');
+const { getRequirementIds } = require('./requirement-map.cjs');
+
+// ── Resolve project root (--project-root= overrides __dirname-relative) ─────
+let ROOT = path.join(__dirname, '..');
+for (const arg of process.argv) {
+  if (arg.startsWith('--project-root=')) ROOT = path.resolve(arg.slice('--project-root='.length));
+}
+
+// ── Parse --config argument ──────────────────────────────────────────────────
+const args       = process.argv.slice(2);
+const configArg  = args.find(a => a.startsWith('--config=')) || null;
+const configName = configArg
+  ? configArg.split('=')[1]
+  : (args.find(a => !a.startsWith('-')) || 'MCaccount-manager');
+
+const VALID_CONFIGS = ['MCaccount-manager'];
+if (!VALID_CONFIGS.includes(configName)) {
+  process.stderr.write(
+    '[run-account-manager-tlc] Unknown config: ' + configName +
+    '. Valid: ' + VALID_CONFIGS.join(', ') + '\n'
+  );
+  const _startMs = Date.now();
+  const _runtimeMs = 0;
+  try { writeCheckResult({ tool: 'run-account-manager-tlc', formalism: 'tla', result: 'fail', check_id: 'tla:account-manager', surface: 'tla', property: 'Account manager quorum state machine — MCAM correctness', runtime_ms: _runtimeMs, summary: 'fail: unknown config in ' + _runtimeMs + 'ms', requirement_ids: getRequirementIds('tla:account-manager'), metadata: {} }); } catch (e) { process.stderr.write('[run-account-manager-tlc] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(1);
+}
+
+// ── 1. Locate Java ───────────────────────────────────────────────────────────
+const JAVA_HOME = process.env.JAVA_HOME;
+let javaExe;
+
+if (JAVA_HOME) {
+  javaExe = path.join(JAVA_HOME, 'bin', 'java');
+  if (!fs.existsSync(javaExe)) {
+    process.stderr.write(
+      '[run-account-manager-tlc] JAVA_HOME is set but java binary not found at: ' + javaExe + '\n' +
+      '[run-account-manager-tlc] Unset JAVA_HOME or fix the path.\n'
+    );
+    const _startMs = Date.now();
+    const _runtimeMs = 0;
+    try { writeCheckResult({ tool: 'run-account-manager-tlc', formalism: 'tla', result: 'fail', check_id: 'tla:account-manager', surface: 'tla', property: 'Account manager quorum state machine — MCAM correctness', runtime_ms: _runtimeMs, summary: 'fail: Java not found in ' + _runtimeMs + 'ms', requirement_ids: getRequirementIds('tla:account-manager'), metadata: {} }); } catch (e) { process.stderr.write('[run-account-manager-tlc] Warning: failed to write check result: ' + e.message + '\n'); }
+    process.exit(1);
+  }
+} else {
+  const probe = spawnSync('java', ['--version'], { encoding: 'utf8' });
+  if (probe.error || probe.status !== 0) {
+    process.stderr.write(
+      '[run-account-manager-tlc] Java not found. Install Java >=17 and set JAVA_HOME.\n' +
+      '[run-account-manager-tlc] Download: https://adoptium.net/\n'
+    );
+    const _startMs = Date.now();
+    const _runtimeMs = 0;
+    try { writeCheckResult({ tool: 'run-account-manager-tlc', formalism: 'tla', result: 'fail', check_id: 'tla:account-manager', surface: 'tla', property: 'Account manager quorum state machine — MCAM correctness', runtime_ms: _runtimeMs, summary: 'fail: Java not found in ' + _runtimeMs + 'ms', requirement_ids: getRequirementIds('tla:account-manager'), metadata: {} }); } catch (e) { process.stderr.write('[run-account-manager-tlc] Warning: failed to write check result: ' + e.message + '\n'); }
+    process.exit(1);
+  }
+  javaExe = 'java';
+}
+
+// ── 2. Check Java version >=17 ───────────────────────────────────────────────
+const versionResult = spawnSync(javaExe, ['--version'], { encoding: 'utf8' });
+if (versionResult.error || versionResult.status !== 0) {
+  process.stderr.write('[run-account-manager-tlc] Failed to run: ' + javaExe + ' --version\n');
+  const _startMs = Date.now();
+  const _runtimeMs = 0;
+  try { writeCheckResult({ tool: 'run-account-manager-tlc', formalism: 'tla', result: 'fail', check_id: 'tla:account-manager', surface: 'tla', property: 'Account manager quorum state machine — MCAM correctness', runtime_ms: _runtimeMs, summary: 'fail: Java version check failed in ' + _runtimeMs + 'ms', requirement_ids: getRequirementIds('tla:account-manager'), metadata: {} }); } catch (e) { process.stderr.write('[run-account-manager-tlc] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(1);
+}
+const versionOutput = versionResult.stdout + versionResult.stderr;
+const versionMatch  = versionOutput.match(/(?:openjdk\s+|java version\s+[""]?)(\d+)/i);
+const javaMajor     = versionMatch ? parseInt(versionMatch[1], 10) : 0;
+if (javaMajor < 17) {
+  process.stderr.write(
+    '[run-account-manager-tlc] Java >=17 required. Found: ' + versionOutput.split('\n')[0] + '\n' +
+    '[run-account-manager-tlc] Download Java 17+: https://adoptium.net/\n'
+  );
+  const _startMs = Date.now();
+  const _runtimeMs = 0;
+  try { writeCheckResult({ tool: 'run-account-manager-tlc', formalism: 'tla', result: 'fail', check_id: 'tla:account-manager', surface: 'tla', property: 'Account manager quorum state machine — MCAM correctness', runtime_ms: _runtimeMs, summary: 'fail: Java ' + javaMajor + ' < 17 in ' + _runtimeMs + 'ms', requirement_ids: getRequirementIds('tla:account-manager'), metadata: {} }); } catch (e) { process.stderr.write('[run-account-manager-tlc] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(1);
+}
+
+// ── 3. Locate tla2tools.jar ──────────────────────────────────────────────────
+const jarPath = path.join(ROOT, '.planning', 'formal', 'tla', 'tla2tools.jar');
+if (!fs.existsSync(jarPath)) {
+  process.stderr.write(
+    '[run-account-manager-tlc] tla2tools.jar not found at: ' + jarPath + '\n' +
+    '[run-account-manager-tlc] Download v1.8.0:\n' +
+    '  curl -L https://github.com/tlaplus/tlaplus/releases/download/v1.8.0/tla2tools.jar \\\n' +
+    '       -o .planning/formal/tla/tla2tools.jar\n'
+  );
+  const _startMs = Date.now();
+  const _runtimeMs = 0;
+  try { writeCheckResult({ tool: 'run-account-manager-tlc', formalism: 'tla', result: 'fail', check_id: 'tla:account-manager', surface: 'tla', property: 'Account manager quorum state machine — MCAM correctness', runtime_ms: _runtimeMs, summary: 'fail: tla2tools.jar not found in ' + _runtimeMs + 'ms', requirement_ids: getRequirementIds('tla:account-manager'), metadata: {} }); } catch (e) { process.stderr.write('[run-account-manager-tlc] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(1);
+}
+
+// ── 4. Invoke TLC ────────────────────────────────────────────────────────────
+const specPath = path.join(ROOT, '.planning', 'formal', 'tla', 'QGSDAccountManager.tla');
+const cfgPath  = path.join(ROOT, '.planning', 'formal', 'tla', configName + '.cfg');
+// Use workers=1 for liveness (IdleReachable) — avoids multi-worker liveness bugs in TLC
+const workers  = '1';
+
+process.stdout.write('[run-account-manager-tlc] Config: ' + configName + '  Workers: ' + workers + '\n');
+process.stdout.write('[run-account-manager-tlc] Spec:   ' + specPath + '\n');
+process.stdout.write('[run-account-manager-tlc] Cfg:    ' + cfgPath + '\n');
+
+const _startMs = Date.now();
+process.stderr.write('[heap] Xms=64m Xmx=' + JAVA_HEAP_MAX + '\n');
+const tlcResult = spawnSync(javaExe, [
+  '-Xms64m', '-Xmx' + JAVA_HEAP_MAX,
+  '-jar', jarPath,
+  '-config', cfgPath,
+  '-workers', workers,
+  specPath,
+], { encoding: 'utf8', stdio: 'inherit' });
+const _runtimeMs = Date.now() - _startMs;
+
+if (tlcResult.error) {
+  process.stderr.write('[run-account-manager-tlc] TLC invocation failed: ' + tlcResult.error.message + '\n');
+  try { writeCheckResult({ tool: 'run-account-manager-tlc', formalism: 'tla', result: 'fail', check_id: 'tla:account-manager', surface: 'tla', property: 'Account manager quorum state machine — MCAM correctness', runtime_ms: _runtimeMs, summary: 'fail: TLC invocation failed in ' + _runtimeMs + 'ms', requirement_ids: getRequirementIds('tla:account-manager'), metadata: {} }); } catch (e) { process.stderr.write('[run-account-manager-tlc] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(1);
+}
+
+const passed = (tlcResult.status || 0) === 0;
+const triage_tags = _runtimeMs > 120000 ? ['timeout-risk'] : [];
+
+if (passed) {
+  const missingDeclarations = detectLivenessProperties(configName, cfgPath);
+  if (missingDeclarations.length > 0) {
+    try {
+      writeCheckResult({
+        tool: 'run-account-manager-tlc',
+        formalism: 'tla',
+        result: 'inconclusive',
+        check_id: 'tla:account-manager',
+        surface: 'tla',
+        property: 'Account manager quorum state machine — MCAM correctness',
+        runtime_ms: _runtimeMs,
+        summary: 'inconclusive: fairness missing in ' + _runtimeMs + 'ms',
+        triage_tags: ['needs-fairness'],
+        requirement_ids: getRequirementIds('tla:account-manager'),
+        metadata: {
+          config: configName,
+          reason: 'Fairness declaration missing for: ' + missingDeclarations.join(', '),
+        }
+      });
+    } catch (e) {
+      process.stderr.write('[run-account-manager-tlc] Warning: failed to write inconclusive result: ' + e.message + '\n');
+    }
+    process.stdout.write('[run-account-manager-tlc] Result: inconclusive — fairness declaration missing for: ' + missingDeclarations.join(', ') + '\n');
+    process.exit(0);
+  }
+  try { writeCheckResult({ tool: 'run-account-manager-tlc', formalism: 'tla', result: 'pass', check_id: 'tla:account-manager', surface: 'tla', property: 'Account manager quorum state machine — MCAM correctness', runtime_ms: _runtimeMs, summary: 'pass: ' + configName + ' in ' + _runtimeMs + 'ms', triage_tags: triage_tags, requirement_ids: getRequirementIds('tla:account-manager'), metadata: {} }); } catch (e) { process.stderr.write('[run-account-manager-tlc] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(0);
+} else {
+  try { writeCheckResult({ tool: 'run-account-manager-tlc', formalism: 'tla', result: 'fail', check_id: 'tla:account-manager', surface: 'tla', property: 'Account manager quorum state machine — MCAM correctness', runtime_ms: _runtimeMs, summary: 'fail: ' + configName + ' in ' + _runtimeMs + 'ms', triage_tags: triage_tags, requirement_ids: getRequirementIds('tla:account-manager'), metadata: {} }); } catch (e) { process.stderr.write('[run-account-manager-tlc] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(tlcResult.status || 0);
+}

package/bin/run-account-pool-alloy.cjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+'use strict';
+// bin/run-account-pool-alloy.cjs
+// Invokes Alloy 6 JAR headless for the QGSD account pool structure spec.
+// Requirements: ALY-AM-01
+//
+// Usage:
+//   node bin/run-account-pool-alloy.cjs
+//
+// Checks (defined in .planning/formal/alloy/account-pool-structure.als):
+//   AddPreservesValidity    — adding to a valid state yields a valid state
+//   SwitchPreservesValidity — switching in a valid state yields a valid state
+//   RemovePreservesValidity — removing from a valid state yields a valid state
+//   SwitchPreservesPool     — switch never modifies pool membership
+//   RemoveShrinksPool       — remove reduces pool size by exactly one
+//
+// Prerequisites:
+//   - Java >=17 (https://adoptium.net/)
+//   - .planning/formal/alloy/org.alloytools.alloy.dist.jar (see VERIFICATION_TOOLS.md for download)
+
+const { spawnSync } = require('child_process');
+const JAVA_HEAP_MAX = process.env.QGSD_JAVA_HEAP_MAX || '512m';
+const fs   = require('fs');
+const path = require('path');
+const { writeCheckResult } = require('./write-check-result.cjs');
+const { getRequirementIds } = require('./requirement-map.cjs');
+
+// ── Resolve project root (--project-root= overrides __dirname-relative) ─────
+let ROOT = path.join(__dirname, '..');
+for (const arg of process.argv) {
+  if (arg.startsWith('--project-root=')) ROOT = path.resolve(arg.slice('--project-root='.length));
+}
+
+// ── 1. Locate Java ───────────────────────────────────────────────────────────
+const JAVA_HOME = process.env.JAVA_HOME;
+let javaExe;
+
+if (JAVA_HOME) {
+  javaExe = path.join(JAVA_HOME, 'bin', 'java');
+  if (!fs.existsSync(javaExe)) {
+    process.stderr.write(
+      '[run-account-pool-alloy] JAVA_HOME is set but java binary not found at: ' + javaExe + '\n' +
+      '[run-account-pool-alloy] Unset JAVA_HOME or fix the path.\n'
+    );
+    try { writeCheckResult({ tool: 'run-account-pool-alloy', formalism: 'alloy', result: 'fail', check_id: 'alloy:account-pool', surface: 'alloy', property: 'Account pool state machine — slot assignment and release invariants', runtime_ms: 0, summary: 'fail: alloy:account-pool (Java not found)', triage_tags: [], requirement_ids: getRequirementIds('alloy:account-pool'), metadata: {} }); } catch (e) { process.stderr.write('[run-account-pool-alloy] Warning: failed to write check result: ' + e.message + '\n'); }
+    process.exit(1);
+  }
+} else {
+  const probe = spawnSync('java', ['--version'], { encoding: 'utf8' });
+  if (probe.error || probe.status !== 0) {
+    process.stderr.write(
+      '[run-account-pool-alloy] Java not found. Install Java >=17 and set JAVA_HOME.\n' +
+      '[run-account-pool-alloy] Download: https://adoptium.net/\n'
+    );
+    try { writeCheckResult({ tool: 'run-account-pool-alloy', formalism: 'alloy', result: 'fail', check_id: 'alloy:account-pool', surface: 'alloy', property: 'Account pool state machine — slot assignment and release invariants', runtime_ms: 0, summary: 'fail: alloy:account-pool (Java not found)', triage_tags: [], requirement_ids: getRequirementIds('alloy:account-pool'), metadata: {} }); } catch (e) { process.stderr.write('[run-account-pool-alloy] Warning: failed to write check result: ' + e.message + '\n'); }
+    process.exit(1);
+  }
+  javaExe = 'java';
+}
+
+// ── 2. Check Java version >=17 ───────────────────────────────────────────────
+const versionResult = spawnSync(javaExe, ['--version'], { encoding: 'utf8' });
+if (versionResult.error || versionResult.status !== 0) {
+  process.stderr.write('[run-account-pool-alloy] Failed to run: ' + javaExe + ' --version\n');
+  try { writeCheckResult({ tool: 'run-account-pool-alloy', formalism: 'alloy', result: 'fail', check_id: 'alloy:account-pool', surface: 'alloy', property: 'Account pool state machine — slot assignment and release invariants', runtime_ms: 0, summary: 'fail: alloy:account-pool (version check failed)', triage_tags: [], requirement_ids: getRequirementIds('alloy:account-pool'), metadata: {} }); } catch (e) { process.stderr.write('[run-account-pool-alloy] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(1);
+}
+const versionOutput = versionResult.stdout + versionResult.stderr;
+const versionMatch  = versionOutput.match(/(?:openjdk\s+|java version\s+[""]?)(\d+)/i);
+const javaMajor     = versionMatch ? parseInt(versionMatch[1], 10) : 0;
+if (javaMajor < 17) {
+  process.stderr.write(
+    '[run-account-pool-alloy] Java >=17 required. Found: ' + versionOutput.split('\n')[0] + '\n' +
+    '[run-account-pool-alloy] Download Java 17+: https://adoptium.net/\n'
+  );
+  try { writeCheckResult({ tool: 'run-account-pool-alloy', formalism: 'alloy', result: 'fail', check_id: 'alloy:account-pool', surface: 'alloy', property: 'Account pool state machine — slot assignment and release invariants', runtime_ms: 0, summary: 'fail: alloy:account-pool (Java < 17)', triage_tags: [], requirement_ids: getRequirementIds('alloy:account-pool'), metadata: {} }); } catch (e) { process.stderr.write('[run-account-pool-alloy] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(1);
+}
+
+// ── 3. Locate org.alloytools.alloy.dist.jar ──────────────────────────────────
+const jarPath = path.join(ROOT, '.planning', 'formal', 'alloy', 'org.alloytools.alloy.dist.jar');
+if (!fs.existsSync(jarPath)) {
+  process.stderr.write(
+    '[run-account-pool-alloy] org.alloytools.alloy.dist.jar not found at: ' + jarPath + '\n' +
+    '[run-account-pool-alloy] Download Alloy 6.2.0:\n' +
+    '  curl -L https://github.com/AlloyTools/org.alloytools.alloy/releases/download/v6.2.0/org.alloytools.alloy.dist.jar \\\n' +
+    '       -o .planning/formal/alloy/org.alloytools.alloy.dist.jar\n'
+  );
+  try { writeCheckResult({ tool: 'run-account-pool-alloy', formalism: 'alloy', result: 'fail', check_id: 'alloy:account-pool', surface: 'alloy', property: 'Account pool state machine — slot assignment and release invariants', runtime_ms: 0, summary: 'fail: alloy:account-pool (JAR not found)', triage_tags: [], requirement_ids: getRequirementIds('alloy:account-pool'), metadata: {} }); } catch (e) { process.stderr.write('[run-account-pool-alloy] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(1);
+}
+
+// ── 4. Locate .planning/formal/alloy/account-pool-structure.als ────────────────────────
+const alsPath = path.join(ROOT, '.planning', 'formal', 'alloy', 'account-pool-structure.als');
+if (!fs.existsSync(alsPath)) {
+  process.stderr.write(
+    '[run-account-pool-alloy] account-pool-structure.als not found at: ' + alsPath + '\n' +
+    '[run-account-pool-alloy] This file should exist in the repository. Check your git status.\n'
+  );
+  try { writeCheckResult({ tool: 'run-account-pool-alloy', formalism: 'alloy', result: 'fail', check_id: 'alloy:account-pool', surface: 'alloy', property: 'Account pool state machine — slot assignment and release invariants', runtime_ms: 0, summary: 'fail: alloy:account-pool (ALS not found)', triage_tags: [], requirement_ids: getRequirementIds('alloy:account-pool'), metadata: {} }); } catch (e) { process.stderr.write('[run-account-pool-alloy] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(1);
+}
+
+// ── 5. Invoke Alloy 6 ────────────────────────────────────────────────────────
+process.stdout.write('[run-account-pool-alloy] ALS: ' + alsPath + '\n');
+process.stdout.write('[run-account-pool-alloy] JAR: ' + jarPath + '\n');
+
+const _startMs = Date.now();
+
+// Use stdio: 'pipe' so we can scan stdout for counterexamples (Alloy exits 0 even on CEX)
+process.stderr.write('[heap] Xms=64m Xmx=' + JAVA_HEAP_MAX + '\n');
+const alloyResult = spawnSync(javaExe, [
+  '-Djava.awt.headless=true',
+  '-Xms64m', '-Xmx' + JAVA_HEAP_MAX,
+  '-jar', jarPath,
+  'exec',
+  '--output', '-',
+  '--type', 'text',
+  '--quiet',
+  alsPath,
+], { encoding: 'utf8', stdio: 'pipe' });
+
+if (alloyResult.error) {
+  process.stderr.write('[run-account-pool-alloy] Alloy invocation failed: ' + alloyResult.error.message + '\n');
+  const _runtimeMs = Date.now() - _startMs;
+  try { writeCheckResult({ tool: 'run-account-pool-alloy', formalism: 'alloy', result: 'fail', check_id: 'alloy:account-pool', surface: 'alloy', property: 'Account pool state machine — slot assignment and release invariants', runtime_ms: _runtimeMs, summary: 'fail: alloy:account-pool in ' + _runtimeMs + 'ms', triage_tags: _runtimeMs > 60000 ? ['timeout-risk'] : [], requirement_ids: getRequirementIds('alloy:account-pool'), metadata: {} }); } catch (e) { process.stderr.write('[run-account-pool-alloy] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(1);
+}
+
+// ── 6. Scan stdout for counterexamples ───────────────────────────────────────
+// Alloy 6 exits 0 even when counterexamples are found. Scan stdout to detect them.
+const stdout = alloyResult.stdout || '';
+const stderr = alloyResult.stderr || '';
+
+if (stdout) { process.stdout.write(stdout); }
+if (stderr) { process.stderr.write(stderr); }
+
+if (/Counterexample/i.test(stdout)) {
+  process.stderr.write(
+    '[run-account-pool-alloy] WARNING: Counterexample found in account-pool-structure.als assertion.\n' +
+    '[run-account-pool-alloy] This indicates a structural invariant violation — review .planning/formal/alloy/account-pool-structure.als.\n' +
+    '[run-account-pool-alloy] Assertions checked: AddPreservesValidity, SwitchPreservesValidity,\n' +
+    '[run-account-pool-alloy]   RemovePreservesValidity, SwitchPreservesPool, RemoveShrinksPool\n'
+  );
+  const _runtimeMs = Date.now() - _startMs;
+  try { writeCheckResult({ tool: 'run-account-pool-alloy', formalism: 'alloy', result: 'fail', check_id: 'alloy:account-pool', surface: 'alloy', property: 'Account pool state machine — slot assignment and release invariants', runtime_ms: _runtimeMs, summary: 'fail: alloy:account-pool in ' + _runtimeMs + 'ms', triage_tags: _runtimeMs > 60000 ? ['timeout-risk'] : [], requirement_ids: getRequirementIds('alloy:account-pool'), metadata: {} }); } catch (e) { process.stderr.write('[run-account-pool-alloy] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(1);
+}
+
+if (alloyResult.status !== 0) {
+  const _runtimeMs = Date.now() - _startMs;
+  try { writeCheckResult({ tool: 'run-account-pool-alloy', formalism: 'alloy', result: 'fail', check_id: 'alloy:account-pool', surface: 'alloy', property: 'Account pool state machine — slot assignment and release invariants', runtime_ms: _runtimeMs, summary: 'fail: alloy:account-pool in ' + _runtimeMs + 'ms', triage_tags: _runtimeMs > 60000 ? ['timeout-risk'] : [], requirement_ids: getRequirementIds('alloy:account-pool'), metadata: {} }); } catch (e) { process.stderr.write('[run-account-pool-alloy] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(alloyResult.status || 1);
+}
+
+const _runtimeMs = Date.now() - _startMs;
+try { writeCheckResult({ tool: 'run-account-pool-alloy', formalism: 'alloy', result: 'pass', check_id: 'alloy:account-pool', surface: 'alloy', property: 'Account pool state machine — slot assignment and release invariants', runtime_ms: _runtimeMs, summary: 'pass: alloy:account-pool in ' + _runtimeMs + 'ms', triage_tags: _runtimeMs > 60000 ? ['timeout-risk'] : [], requirement_ids: getRequirementIds('alloy:account-pool'), metadata: {} }); } catch (e) { process.stderr.write('[run-account-pool-alloy] Warning: failed to write check result: ' + e.message + '\n'); }
+process.exit(0);