@nforma.ai/nforma 0.2.1

package/bin/run-transcript-alloy.cjs

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+'use strict';
+// bin/run-transcript-alloy.cjs
+// Invokes Alloy 6 JAR headless for QGSD transcript scanning spec (GAP-4).
+// Requirements: GAP-4
+//
+// Usage:
+//   node bin/run-transcript-alloy.cjs [--spec=<name>]
+//
+// Valid spec names:
+//   transcript-scan  (default) — GAP-4: transcript scanning invariants
+//
+// 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));
+}
+
+// ── 0. Parse --spec argument ──────────────────────────────────────────────────
+const VALID_SPECS = ['transcript-scan'];
+const args    = process.argv.slice(2);
+const specArg = args.find(a => a.startsWith('--spec=')) || null;
+const specName = specArg
+  ? specArg.split('=')[1]
+  : (args.find(a => !a.startsWith('-')) || 'transcript-scan');
+
+if (!VALID_SPECS.includes(specName)) {
+  process.stderr.write(
+    '[run-transcript-alloy] Unknown spec: ' + specName +
+    '. Valid: ' + VALID_SPECS.join(', ') + '\n'
+  );
+  try { writeCheckResult({ tool: 'run-transcript-alloy', formalism: 'alloy', result: 'fail', check_id: 'alloy:transcript', surface: 'alloy', property: 'Hook transcript scanning — boundary detection, tool_use/tool_result pairing uniqueness, ceiling enforcement', runtime_ms: 0, summary: 'fail: alloy:transcript (invalid spec)', triage_tags: [], requirement_ids: getRequirementIds('alloy:transcript'), metadata: { spec: specName } }); } catch (e) { process.stderr.write('[run-transcript-alloy] 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-transcript-alloy] JAVA_HOME is set but java binary not found at: ' + javaExe + '\n' +
+      '[run-transcript-alloy] Unset JAVA_HOME or fix the path.\n'
+    );
+    try { writeCheckResult({ tool: 'run-transcript-alloy', formalism: 'alloy', result: 'fail', check_id: 'alloy:transcript', surface: 'alloy', property: 'Hook transcript scanning — boundary detection, tool_use/tool_result pairing uniqueness, ceiling enforcement', runtime_ms: 0, summary: 'fail: alloy:transcript (Java not found)', triage_tags: [], requirement_ids: getRequirementIds('alloy:transcript'), metadata: { spec: specName } }); } catch (e) { process.stderr.write('[run-transcript-alloy] Warning: failed to write check result: ' + e.message + '\n'); }
+    process.exit(1);
+  }
+} else {
+  // Fall back to PATH lookup
+  const probe = spawnSync('java', ['--version'], { encoding: 'utf8' });
+  if (probe.error || probe.status !== 0) {
+    process.stderr.write(
+      '[run-transcript-alloy] Java not found. Install Java >=17 and set JAVA_HOME.\n' +
+      '[run-transcript-alloy] Download: https://adoptium.net/\n'
+    );
+    try { writeCheckResult({ tool: 'run-transcript-alloy', formalism: 'alloy', result: 'fail', check_id: 'alloy:transcript', surface: 'alloy', property: 'Hook transcript scanning — boundary detection, tool_use/tool_result pairing uniqueness, ceiling enforcement', runtime_ms: 0, summary: 'fail: alloy:transcript (Java not found)', triage_tags: [], requirement_ids: getRequirementIds('alloy:transcript'), metadata: { spec: specName } }); } catch (e) { process.stderr.write('[run-transcript-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-transcript-alloy] Failed to run: ' + javaExe + ' --version\n');
+  try { writeCheckResult({ tool: 'run-transcript-alloy', formalism: 'alloy', result: 'fail', check_id: 'alloy:transcript', surface: 'alloy', property: 'Hook transcript scanning — boundary detection, tool_use/tool_result pairing uniqueness, ceiling enforcement', runtime_ms: 0, summary: 'fail: alloy:transcript (version check failed)', triage_tags: [], requirement_ids: getRequirementIds('alloy:transcript'), metadata: { spec: specName } }); } catch (e) { process.stderr.write('[run-transcript-alloy] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(1);
+}
+const versionOutput = versionResult.stdout + versionResult.stderr;
+// Java version string varies: "openjdk 17.0.1 ..." or "java version \"17.0.1\""
+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-transcript-alloy] Java >=17 required. Found: ' + versionOutput.split('\n')[0] + '\n' +
+    '[run-transcript-alloy] Download Java 17+: https://adoptium.net/\n'
+  );
+  try { writeCheckResult({ tool: 'run-transcript-alloy', formalism: 'alloy', result: 'fail', check_id: 'alloy:transcript', surface: 'alloy', property: 'Hook transcript scanning — boundary detection, tool_use/tool_result pairing uniqueness, ceiling enforcement', runtime_ms: 0, summary: 'fail: alloy:transcript (Java < 17)', triage_tags: [], requirement_ids: getRequirementIds('alloy:transcript'), metadata: { spec: specName } }); } catch (e) { process.stderr.write('[run-transcript-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-transcript-alloy] org.alloytools.alloy.dist.jar not found at: ' + jarPath + '\n' +
+    '[run-transcript-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-transcript-alloy', formalism: 'alloy', result: 'fail', check_id: 'alloy:transcript', surface: 'alloy', property: 'Hook transcript scanning — boundary detection, tool_use/tool_result pairing uniqueness, ceiling enforcement', runtime_ms: 0, summary: 'fail: alloy:transcript (JAR not found)', triage_tags: [], requirement_ids: getRequirementIds('alloy:transcript'), metadata: { spec: specName } }); } catch (e) { process.stderr.write('[run-transcript-alloy] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(1);
+}
+
+// ── 4. Locate .als file ───────────────────────────────────────────────────────
+const alsPath = path.join(ROOT, '.planning', 'formal', 'alloy', specName + '.als');
+if (!fs.existsSync(alsPath)) {
+  process.stderr.write(
+    '[run-transcript-alloy] ' + specName + '.als not found at: ' + alsPath + '\n' +
+    '[run-transcript-alloy] This file should exist in the repository. Check your git status.\n'
+  );
+  try { writeCheckResult({ tool: 'run-transcript-alloy', formalism: 'alloy', result: 'fail', check_id: 'alloy:transcript', surface: 'alloy', property: 'Hook transcript scanning — boundary detection, tool_use/tool_result pairing uniqueness, ceiling enforcement', runtime_ms: 0, summary: 'fail: alloy:transcript (ALS not found)', triage_tags: [], requirement_ids: getRequirementIds('alloy:transcript'), metadata: { spec: specName } }); } catch (e) { process.stderr.write('[run-transcript-alloy] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(1);
+}
+
+// ── 5. Invoke Alloy 6 ────────────────────────────────────────────────────────
+process.stdout.write('[run-transcript-alloy] spec: ' + specName + '\n');
+process.stdout.write('[run-transcript-alloy] ALS:  ' + alsPath + '\n');
+process.stdout.write('[run-transcript-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-transcript-alloy] Alloy invocation failed: ' + alloyResult.error.message + '\n');
+  const _runtimeMs = Date.now() - _startMs;
+  try { writeCheckResult({ tool: 'run-transcript-alloy', formalism: 'alloy', result: 'fail', check_id: 'alloy:transcript', surface: 'alloy', property: 'Hook transcript scanning — boundary detection, tool_use/tool_result pairing uniqueness, ceiling enforcement', runtime_ms: _runtimeMs, summary: 'fail: alloy:transcript in ' + _runtimeMs + 'ms', triage_tags: _runtimeMs > 60000 ? ['timeout-risk'] : [], requirement_ids: getRequirementIds('alloy:transcript'), metadata: { spec: specName } }); } catch (e) { process.stderr.write('[run-transcript-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 || '';
+
+// Write stdout to process.stdout (mirrors stdio: 'inherit' output)
+if (stdout) { process.stdout.write(stdout); }
+if (stderr) { process.stderr.write(stderr); }
+
+if (/Counterexample/i.test(stdout)) {
+  process.stderr.write(
+    '[run-transcript-alloy] WARNING: Counterexample found in ' + specName + '.als assertion.\n' +
+    '[run-transcript-alloy] This indicates a spec violation — review .planning/formal/alloy/' + specName + '.als.\n'
+  );
+  const _runtimeMs = Date.now() - _startMs;
+  try { writeCheckResult({ tool: 'run-transcript-alloy', formalism: 'alloy', result: 'fail', check_id: 'alloy:transcript', surface: 'alloy', property: 'Hook transcript scanning — boundary detection, tool_use/tool_result pairing uniqueness, ceiling enforcement', runtime_ms: _runtimeMs, summary: 'fail: alloy:transcript in ' + _runtimeMs + 'ms', triage_tags: _runtimeMs > 60000 ? ['timeout-risk'] : [], requirement_ids: getRequirementIds('alloy:transcript'), metadata: { spec: specName } }); } catch (e) { process.stderr.write('[run-transcript-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-transcript-alloy', formalism: 'alloy', result: 'fail', check_id: 'alloy:transcript', surface: 'alloy', property: 'Hook transcript scanning — boundary detection, tool_use/tool_result pairing uniqueness, ceiling enforcement', runtime_ms: _runtimeMs, summary: 'fail: alloy:transcript in ' + _runtimeMs + 'ms', triage_tags: _runtimeMs > 60000 ? ['timeout-risk'] : [], requirement_ids: getRequirementIds('alloy:transcript'), metadata: { spec: specName } }); } catch (e) { process.stderr.write('[run-transcript-alloy] Warning: failed to write check result: ' + e.message + '\n'); }
+  process.exit(alloyResult.status || 1);
+}
+
+const _runtimeMs = Date.now() - _startMs;
+try { writeCheckResult({ tool: 'run-transcript-alloy', formalism: 'alloy', result: 'pass', check_id: 'alloy:transcript', surface: 'alloy', property: 'Hook transcript scanning — boundary detection, tool_use/tool_result pairing uniqueness, ceiling enforcement', runtime_ms: _runtimeMs, summary: 'pass: alloy:transcript in ' + _runtimeMs + 'ms', triage_tags: _runtimeMs > 60000 ? ['timeout-risk'] : [], requirement_ids: getRequirementIds('alloy:transcript'), metadata: { spec: specName } }); } catch (e) { process.stderr.write('[run-transcript-alloy] Warning: failed to write check result: ' + e.message + '\n'); }
+process.exit(0);

package/bin/run-uppaal.cjs

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+'use strict';
+// bin/run-uppaal.cjs
+// Invokes UPPAAL verifyta model checker against .planning/formal/uppaal/quorum-races.xml.
+// Requirements: UPPAAL-01, UPPAAL-02, UPPAAL-03
+//
+// Usage:
+//   node bin/run-uppaal.cjs
+//   VERIFYTA_BIN=/path/to/verifyta node bin/run-uppaal.cjs
+//
+// Prerequisites:
+//   - UPPAAL 4.x or 5.x; set VERIFYTA_BIN to path of the verifyta binary
+//     e.g. export VERIFYTA_BIN="$HOME/uppaal/bin/verifyta"
+//   - Download: https://uppaal.org/downloads/
+//
+// Graceful degradation: if verifyta is not found, exits 0 with result=inconclusive.
+
+const { spawnSync } = require('child_process');
+const fs   = require('fs');
+const path = require('path');
+const { writeCheckResult } = require('./write-check-result.cjs');
+const { parseNDJSON } = require('./verify-formal-results.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));
+}
+
+const CHECK_ID  = 'uppaal:quorum-races';
+const SURFACE   = 'uppaal';
+const PROPERTY  = 'Quorum timed race model — minimum inter-slot gap and maximum timeout for consensus';
+const TAG       = '[run-uppaal]';
+
+// Default timing fallbacks (override via empirical check-results.ndjson data)
+const DEFAULT_MIN_SLOT_MS = 50;
+const DEFAULT_MAX_SLOT_MS = 500;
+const DEFAULT_TIMEOUT_MS  = 1500;
+const DEFAULT_MIN_GAP_MS  = 10;
+
+/**
+ * Read empirical timing bounds from check-results.ndjson.
+ * Uses tla:* check records' runtime_ms as slot response time proxy.
+ * Falls back to defaults if no data.
+ * @returns {{ minSlotMs, maxSlotMs, timeoutMs, minGapMs }}
+ */
+function readTimingBounds() {
+  const ndjsonPath = process.env.CHECK_RESULTS_PATH ||
+    path.join(ROOT, '.planning', 'formal', 'check-results.ndjson');
+  const records = parseNDJSON(ndjsonPath);
+  const slotRuntimes = records
+    .filter(r => r.check_id && r.check_id.startsWith('tla:') && typeof r.runtime_ms === 'number' && r.runtime_ms > 0)
+    .map(r => r.runtime_ms);
+
+  if (slotRuntimes.length === 0) {
+    process.stderr.write(TAG + ' No tla: runtime_ms data found — using defaults\n');
+    return {
+      minSlotMs: DEFAULT_MIN_SLOT_MS,
+      maxSlotMs: DEFAULT_MAX_SLOT_MS,
+      timeoutMs: DEFAULT_TIMEOUT_MS,
+      minGapMs:  DEFAULT_MIN_GAP_MS,
+    };
+  }
+
+  const minSlotMs = Math.max(1, Math.min(...slotRuntimes));
+  const maxSlotMs = Math.max(...slotRuntimes);
+  const timeoutMs = Math.max(maxSlotMs * 3, DEFAULT_TIMEOUT_MS);
+  const minGapMs  = Math.max(1, Math.floor(minSlotMs / 5));
+
+  process.stderr.write(
+    TAG + ' Timing bounds from NDJSON: ' +
+    'min=' + minSlotMs + 'ms, max=' + maxSlotMs + 'ms, timeout=' + timeoutMs + 'ms\n'
+  );
+  return { minSlotMs, maxSlotMs, timeoutMs, minGapMs };
+}
+
+/**
+ * Find verifyta binary. Checks VERIFYTA_BIN env, then PATH.
+ * Returns null if not found (caller handles graceful degradation).
+ */
+function locateVerifyta() {
+  const envBin = process.env.VERIFYTA_BIN;
+  if (envBin) {
+    return fs.existsSync(envBin) ? envBin : null;
+  }
+  // Check local install from install-formal-tools.cjs
+  const localPath = path.join(ROOT, '.planning', 'formal', 'uppaal', 'bin', 'verifyta');
+  if (fs.existsSync(localPath)) {
+    process.stderr.write(TAG + ' Using local verifyta: ' + localPath + '\n');
+    return localPath;
+  }
+  // Try 'verifyta' on PATH via which
+  const which = spawnSync('which', ['verifyta'], { encoding: 'utf8' });
+  if (which.status === 0 && which.stdout.trim()) {
+    return which.stdout.trim();
+  }
+  return null;
+}
+
+function main() {
+  const startMs = Date.now();
+  const modelPath = path.join(ROOT, '.planning', 'formal', 'uppaal', 'quorum-races.xml');
+  const queryPath = path.join(ROOT, '.planning', 'formal', 'uppaal', 'quorum-races.q');
+
+  // Check model files exist
+  if (!fs.existsSync(modelPath) || !fs.existsSync(queryPath)) {
+    const missing = [modelPath, queryPath].filter(p => !fs.existsSync(p)).join(', ');
+    process.stderr.write(TAG + ' Model files not found: ' + missing + '\n');
+    writeCheckResult({
+      tool: 'run-uppaal', formalism: 'uppaal', result: 'inconclusive',
+      check_id: CHECK_ID, surface: SURFACE, property: PROPERTY,
+      runtime_ms: Date.now() - startMs,
+      summary: 'inconclusive: model files not found — run Plan 03 first',
+      triage_tags: ['missing-model'],
+      requirement_ids: getRequirementIds(CHECK_ID),
+      metadata: { missing },
+    });
+    process.exit(0);
+  }
+
+  // Read empirical timing bounds
+  const bounds = readTimingBounds();
+
+  // Locate verifyta
+  const verifytaBin = locateVerifyta();
+  if (!verifytaBin) {
+    process.stderr.write(
+      TAG + ' verifyta not found. Install UPPAAL and set VERIFYTA_BIN:\n' +
+      TAG + '   export VERIFYTA_BIN="$HOME/uppaal/bin/verifyta"\n' +
+      TAG + ' Download: https://uppaal.org/downloads/\n'
+    );
+    writeCheckResult({
+      tool: 'run-uppaal', formalism: 'uppaal', result: 'inconclusive',
+      check_id: CHECK_ID, surface: SURFACE, property: PROPERTY,
+      runtime_ms: Date.now() - startMs,
+      summary: 'inconclusive: verifyta not installed — install UPPAAL to run model checker',
+      triage_tags: ['no-verifyta'],
+      requirement_ids: getRequirementIds(CHECK_ID),
+      metadata: {
+        min_slot_ms: bounds.minSlotMs,
+        max_slot_ms: bounds.maxSlotMs,
+        timeout_ms: bounds.timeoutMs,
+      },
+    });
+    process.exit(0);
+  }
+
+  // Build verifyta arguments with empirical timing bounds as -C constants
+  const args = [
+    '-C', 'MIN_SLOT_MS=' + bounds.minSlotMs,
+    '-C', 'MAX_SLOT_MS=' + bounds.maxSlotMs,
+    '-C', 'TIMEOUT_MS=' + bounds.timeoutMs,
+    '-C', 'MIN_GAP_MS=' + bounds.minGapMs,
+    modelPath,
+    queryPath,
+  ];
+
+  process.stderr.write(TAG + ' Running: ' + verifytaBin + ' ' + args.join(' ') + '\n');
+  const result = spawnSync(verifytaBin, args, { stdio: ['pipe', 'pipe', 'pipe'], encoding: 'utf8' });
+
+  const runtimeMs = Date.now() - startMs;
+  const combinedOutput = (result.stdout || '') + (result.stderr || '');
+
+  // Stream output for visibility
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+
+  if (result.error) {
+    process.stderr.write(TAG + ' Launch error: ' + result.error.message + '\n');
+    writeCheckResult({
+      tool: 'run-uppaal', formalism: 'uppaal', result: 'fail',
+      check_id: CHECK_ID, surface: SURFACE, property: PROPERTY,
+      runtime_ms: runtimeMs,
+      summary: 'fail: verifyta launch error — ' + result.error.message,
+      triage_tags: ['verifyta-error'],
+      requirement_ids: getRequirementIds(CHECK_ID),
+      metadata: { bounds },
+    });
+    process.exit(0);
+  }
+
+  // Detect UPPAAL 5.x license requirement (free academic license changed in 5.0)
+  if (combinedOutput.includes('License does not cover verifier') ||
+      combinedOutput.includes('license key is not set')) {
+    process.stderr.write(
+      TAG + ' UPPAAL 5.x requires a free academic license key.\n' +
+      TAG + '   Register at: https://uppaal.org/academic/ \n' +
+      TAG + '   Then set: export UPPAAL_LICENSE_FILE=/path/to/license.key\n'
+    );
+    writeCheckResult({
+      tool: 'run-uppaal', formalism: 'uppaal', result: 'inconclusive',
+      check_id: CHECK_ID, surface: SURFACE, property: PROPERTY,
+      runtime_ms: runtimeMs,
+      summary: 'inconclusive: UPPAAL 5.x license required — register at uppaal.org/academic/',
+      triage_tags: ['needs-license'],
+      requirement_ids: getRequirementIds(CHECK_ID),
+      metadata: { bounds },
+    });
+    process.exit(0);
+  }
+
+  // Detect --disable-memory-reduction duplicate option bug (UPPAAL 5.0.0 bug with -C flags)
+  if (combinedOutput.includes('--disable-memory-reduction') &&
+      combinedOutput.includes('cannot be specified more than once')) {
+    process.stderr.write(
+      TAG + ' Known UPPAAL 5.0.0 bug: -C flags trigger duplicate --disable-memory-reduction.\n' +
+      TAG + ' Workaround: set constants in the XML model directly instead of via -C.\n'
+    );
+    writeCheckResult({
+      tool: 'run-uppaal', formalism: 'uppaal', result: 'inconclusive',
+      check_id: CHECK_ID, surface: SURFACE, property: PROPERTY,
+      runtime_ms: runtimeMs,
+      summary: 'inconclusive: UPPAAL 5.0.0 -C flag bug — falling back to XML-embedded constants',
+      triage_tags: ['uppaal-bug'],
+      requirement_ids: getRequirementIds(CHECK_ID),
+      metadata: { bounds },
+    });
+    // Retry without -C flags — use the XML-embedded default constants
+    process.stderr.write(TAG + ' Retrying without -C flags...\n');
+    const retryArgs = [modelPath, queryPath];
+    const retry = spawnSync(verifytaBin, retryArgs, { stdio: ['pipe', 'pipe', 'pipe'], encoding: 'utf8' });
+    const retryOutput = (retry.stdout || '') + (retry.stderr || '');
+    if (retry.stdout) process.stdout.write(retry.stdout);
+    if (retry.stderr) process.stderr.write(retry.stderr);
+
+    // If retry also hits license error, handle that
+    if (retryOutput.includes('License does not cover verifier')) {
+      process.stderr.write(TAG + ' License required — see above.\n');
+      process.exit(0);  // already wrote inconclusive check result
+    }
+
+    const retryPassed = retry.status === 0;
+    const retryMs = Date.now() - startMs;
+    writeCheckResult({
+      tool: 'run-uppaal', formalism: 'uppaal',
+      result: retryPassed ? 'pass' : 'fail',
+      check_id: CHECK_ID, surface: SURFACE, property: PROPERTY,
+      runtime_ms: retryMs,
+      summary: (retryPassed ? 'pass' : 'fail') + ': uppaal:quorum-races in ' + retryMs +
+        'ms (XML defaults, -C workaround)',
+      triage_tags: retryPassed ? [] : ['race-detected'],
+      requirement_ids: getRequirementIds(CHECK_ID),
+      metadata: { bounds, exit_status: retry.status, workaround: 'no-C-flags' },
+    });
+    process.exit(0);
+  }
+
+  const passed = result.status === 0;
+  writeCheckResult({
+    tool: 'run-uppaal', formalism: 'uppaal',
+    result: passed ? 'pass' : 'fail',
+    check_id: CHECK_ID, surface: SURFACE, property: PROPERTY,
+    runtime_ms: runtimeMs,
+    summary: (passed ? 'pass' : 'fail') + ': uppaal:quorum-races in ' + runtimeMs + 'ms' +
+      ' (min_slot=' + bounds.minSlotMs + 'ms, max_slot=' + bounds.maxSlotMs +
+      'ms, timeout=' + bounds.timeoutMs + 'ms)',
+    triage_tags: passed ? [] : ['race-detected'],
+    requirement_ids: getRequirementIds(CHECK_ID),
+    metadata: { bounds, exit_status: result.status },
+  });
+}
+
+main();

package/bin/secrets.cjs

@@ -0,0 +1,134 @@
+'use strict';
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+const SERVICE = 'qgsd';
+
+const INDEX_PATH = path.join(os.homedir(), '.claude', 'qgsd-key-index.json');
+
+// Read the key index (no keychain access needed — just a JSON file)
+function readIndex() {
+  try {
+    return new Set(JSON.parse(fs.readFileSync(INDEX_PATH, 'utf8')).accounts || []);
+  } catch (_) {
+    return new Set();
+  }
+}
+
+function writeIndex(accounts) {
+  fs.mkdirSync(path.dirname(INDEX_PATH), { recursive: true });
+  fs.writeFileSync(INDEX_PATH, JSON.stringify({ accounts: [...accounts] }, null, 2));
+}
+
+// Check if a key exists — no keychain prompt, reads local index only
+function hasKey(key) {
+  return readIndex().has(key);
+}
+
+// Lazy-load keytar with a graceful error if the native addon is missing
+function getKeytar() {
+  try {
+    return require('keytar');
+  } catch (e) {
+    throw new Error(
+      'keytar native addon not found. Run `npm install keytar` (requires libsecret-dev on Linux).\n' +
+      'Original error: ' + e.message
+    );
+  }
+}
+
+async function set(service, key, value) {
+  await getKeytar().setPassword(service, key, value);
+  const idx = readIndex();
+  idx.add(key);
+  writeIndex(idx);
+}
+
+async function get(service, key) {
+  return getKeytar().getPassword(service, key);
+}
+
+async function del(service, key) {
+  const result = await getKeytar().deletePassword(service, key);
+  const idx = readIndex();
+  idx.delete(key);
+  writeIndex(idx);
+  return result;
+}
+
+async function list(service) {
+  return getKeytar().findCredentials(service);
+  // returns [{account, password}]
+}
+
+/**
+ * Reads all secrets stored under `service` from the keychain,
+ * then patches matching env keys in every mcpServers entry in ~/.claude.json.
+ *
+ * Algorithm:
+ *   1. Load all credentials for the service (account = env var name, password = value)
+ *   2. Read ~/.claude.json (parse JSON; if missing/corrupt, log warning and return)
+ *   3. Iterate claudeJson.mcpServers — for each server with an `env` block,
+ *      for each credential whose account name appears as a key in `env`,
+ *      overwrite `env[account]` with the credential's password.
+ *   4. Write the patched JSON back to ~/.claude.json with 2-space indent.
+ */
+async function syncToClaudeJson(service) {
+  const os = require('os');
+  const fs = require('fs');
+  const path = require('path');
+
+  const claudeJsonPath = path.join(os.homedir(), '.claude.json');
+
+  let credentials;
+  try {
+    credentials = await list(service);
+  } catch (e) {
+    process.stderr.write('[qgsd-secrets] keytar unavailable: ' + e.message + '\n');
+    return;
+  }
+
+  if (!credentials || credentials.length === 0) return;
+
+  // Build a lookup map: { ACCOUNT_NAME: password }
+  const credMap = {};
+  for (const c of credentials) {
+    credMap[c.account] = c.password;
+  }
+
+  let raw;
+  try {
+    raw = fs.readFileSync(claudeJsonPath, 'utf8');
+  } catch (e) {
+    process.stderr.write('[qgsd-secrets] ~/.claude.json not found, skipping sync\n');
+    return;
+  }
+
+  let claudeJson;
+  try {
+    claudeJson = JSON.parse(raw);
+  } catch (e) {
+    process.stderr.write('[qgsd-secrets] ~/.claude.json is invalid JSON, skipping sync\n');
+    return;
+  }
+
+  if (!claudeJson.mcpServers || typeof claudeJson.mcpServers !== 'object') return;
+
+  let patched = 0;
+  for (const serverName of Object.keys(claudeJson.mcpServers)) {
+    const server = claudeJson.mcpServers[serverName];
+    if (!server.env || typeof server.env !== 'object') continue;
+    for (const envKey of Object.keys(server.env)) {
+      if (credMap[envKey] !== undefined) {
+        server.env[envKey] = credMap[envKey];
+        patched++;
+      }
+    }
+  }
+
+  if (patched > 0) {
+    fs.writeFileSync(claudeJsonPath, JSON.stringify(claudeJson, null, 2));
+  }
+}
+
+module.exports = { set, get, delete: del, list, hasKey, syncToClaudeJson, SERVICE };