docs(adr): deep review of the RuView npm surface — ADR-263/264/265 optimization strategies (#1229)

* docs(adr): deep review of the RuView npm surface — ADR-263/264/265 optimization strategies ADR-263 — @ruvnet/ruview@0.1.0 harness review (O1–O9): - HIGH: claim-check CLI fails open on empty input (no --text/--file -> PASS exit 0) - HIGH: MCP stdio server head-of-line blocking (spawnSync verify/calibrate up to 600s) - MEASURED: optionalDependencies triple the cold npx install (4 pkgs/620kB/71 files vs 1 pkg/172kB/22 files with --omit=optional) for a path that never imports them - maxBuffer truncation, python -c port interpolation, version drift, duplicate skills, guardrail METRIC_TERMS substring false positives ('map'/'F1' — found by dogfooding claim-check on these very ADRs), zero CI ADR-264 — @ruvnet/rvagent@0.1.0 + @ruv/ruview-cli review (O1–O9), verified against the published registry tarball: - HIGH: exports.require -> dist/index.cjs which is never built nor published - MEASURED: 44 dead source-map files = 62,698B of the 188kB unpacked payload - stdio-only server described as dual-transport; mixed dot/underscore tool names; double Zod validation + hand-duplicated advertised schemas; 2-fd leak per training job; unbounded body in the unwired HTTP scaffold; dead detectCogBinary candidates; ruview bin-name collision ADR-265 — cross-cutting npm distribution strategy: npm-packages.yml CI matrix (test + pack-content/size gate + tarball-install smoke test), publish-from-CI-only with npm provenance, version single-sourcing from package.json, bin/namespace ownership (ruview bin belongs to @ruvnet/ruview), claim-check on package READMEs. Docs only — no runtime code changed. Index/CHANGELOG/CLAUDE.md/README counts updated. Co-Authored-By: claude-flow <ruv@ruv.net> Claude-Session: https://claude.ai/code/session_01WrGfTGKv1oWZ6iwXZACULz * fix(npm): implement ADR-263/264/265 — harness fail-closed + async MCP, rvagent packaging/transport/naming, npm CI+provenance gate ADR-263 (@ruvnet/ruview 0.2.0), O1-O9: - claim-check fails closed on empty input (CLI exit 2, empty_text tool error) - MCP stdio server dispatches tools/call asynchronously (promise-based spawn); ping answers while a 3s fake verify runs — pinned by new e2e test - optionalDependencies dropped: cold npx installs exactly 1 package (MEASURED: was 4 pkgs/620kB/71 files via npm i in a clean prefix) - bounded rolling output tails replace spawnSync 1MiB maxBuffer - node_monitor port passed via sys.argv, never spliced into python -c source - serverInfo.version read from package.json; resources/prompts stubs - skills single-sourced: prepack sync script generates .claude/skills/ copies - which() = memoized dep-free PATH scan - tools underscore-canonical (ruview_claim_check, ...) + dotted aliases - guardrail precision: word-boundary map/f1/auc/iou, code-span + F1/O2 label scrubbing, quantitative-claims-only; packaging reproducer hints - 30/30 tests (was 17), incl. concurrency e2e + fail-open regression pins ADR-264 (@ruvnet/rvagent 0.2.0), O1-O9: - exports fixed: types-first, phantom dist/index.cjs require target removed - tarball map-free: 127,704B unpacked / 46 files / 0 maps (MEASURED, npm pack --dry-run; was 188kB incl. 44 maps referencing unshipped src) - Streamable HTTP actually wired behind RVAGENT_HTTP_PORT: one transport + one MCP server per session (mcp-session-id routing), 1MiB body cap (413), port-aware localhost origin gate; dual-transport description now true - tools renamed underscore-canonical with dotted router-only aliases - single Zod validation gate; advertised inputSchema generated from the same Zod source (zod-to-json-schema) - train_count: parent log fds closed (was leaking 2/job); job records persisted to <jobsDir>/<id>.json (job_status survives restarts); bounded log-tail reads - detectCogBinary probes its candidates instead of dead-coding them - version from package.json; @types/express dropped; @types/jest -> 29 - README rewritten to match reality (no phantom subcommands/policy layer) - 99/99 jest tests (incl. new session/body-cap suite + previously-broken manifest suite); stdio handshake + HTTP session flow smoke-tested live ADR-265 D1-D4: - .github/workflows/npm-packages.yml: 3-package x Node 20/22 gate — tests, version-literal grep (D3), pack-content/size gate, tarball-install smoke test (catches the ADR-264 F1 class), README claim-check (D4) - .github/workflows/ruview-npm-release.yml: publish from CI only with npm publish --provenance - @ruv/ruview-cli bin renamed ruview-cli (ruview bin belongs to @ruvnet/ruview); version single-sourced - ci.yml NODE_VERSION 18 -> 20 ADR statuses updated to Accepted/implemented; harness manifest re-pinned; ADR-263/264/265 + both package READMEs pass claim-check. Co-Authored-By: claude-flow <ruv@ruv.net> Claude-Session: https://claude.ai/code/session_01WrGfTGKv1oWZ6iwXZACULz * perf(rvagent): lazy-load HTTP transport + memoize generated tool schemas stdio time-to-first-response ~242ms -> ~189ms (-22%; MEASURED, median of repeated initialize round-trips against dist/index.js in this container). - ./http-transport.js now imported lazily inside the RVAGENT_HTTP_PORT branch: it chain-loads the MCP SDK streamableHttp module (~48ms MEASURED via per-module import() timing) which the default stdio path never uses - toolInputJsonSchema memoized per tool: schemas are static for the process lifetime; under the session-per-server HTTP model every session calls tools/list, so stop re-walking the Zod tree each time No behavior change: 99/99 jest tests; HTTP session flow re-smoke-tested through the lazy import path (initialize -> 200 + mcp-session-id). Profiled @ruvnet/ruview too and left it alone: 50ms CLI startup vs ~29ms bare 'node -e ""' floor on the same box (MEASURED) — already near the interpreter floor with zero dependencies. Co-Authored-By: claude-flow <ruv@ruv.net> Claude-Session: https://claude.ai/code/session_01WrGfTGKv1oWZ6iwXZACULz * ci(ruview-cli): pass jest --passWithNoTests so the private no-test package doesn't fail the npm-packages matrix Co-Authored-By: claude-flow <ruv@ruv.net> * fix(npm): address 10 verified review findings in harness + rvagent before 0.2.0 publish harness/ruview (@ruvnet/ruview): - guardrails: digit gate now sees numbers inside code spans; F1-style metric tokens followed by ':' or a nearby number are no longer scrubbed (fail-open regressions in the honesty gate) - mcp-server: tools/call requests serialize through a FIFO promise chain (hardware/mutating tools never overlap) while ping/tools/list stay immediate; stdin close drains in-flight responses before exit - tools: which() no longer memoizes negative lookups tools/ruview-mcp (@ruvnet/rvagent): - index: realpath invoked-directly guard — library import no longer connects a stdio transport to the consumer's process - http-transport: explicit allowedOrigins is exact-match only (localhost any-port convenience applies only with no configured allowlist); session map gains maxSessions=64 + 5min idle TTL sweep - train-count: job records persist the child pid and reconcile stale 'running' status after a server restart (exit-code marker or dead pid) - config: cog binary candidates ordered by process.arch .github/workflows/ruview-npm-release.yml: port the full ADR-265 D1 gate (version-literal check, unpacked-size budget, tarball-install smoke test) from npm-packages.yml so the publish path enforces what the header claims. Tests: harness 30→36, rvagent 99→112, all passing. Co-Authored-By: claude-flow <ruv@ruv.net> --------- Co-authored-by: Claude <noreply@anthropic.com>
2026-07-26 18:01:48 +00:00 · 2026-07-02 13:11:15 -04:00
parent 1a0492992f
commit e6f26e9ac9
48 changed files with 2457 additions and 981 deletions
@@ -4,15 +4,44 @@
 // The project was accused of AI-slop; the cultural fix is that every accuracy
 // number must be tagged MEASURED (with a reproducer) or CLAIMED/SYNTHETIC, and
 // the retracted "100% accuracy" framing must never reappear untagged. This module
-// is the static enforcement of that, shared by the `ruview.claim_check` MCP tool,
+// is the static enforcement of that, shared by the `ruview_claim_check` MCP tool,
 // the `npx ruview claim-check` CLI, and the claude-code pre-output hook.

-/** Phrases that signal a quantitative accuracy claim. */
+/** Phrases that signal a quantitative accuracy claim (safe as substrings). */
 const METRIC_TERMS = [
-  'accuracy', 'pck', 'pck@', 'f1', 'precision', 'recall', 'map', 'auc',
-  'iou', 'mpjpe', 'error rate', 'detection rate', 'true positive',
+  'accuracy', 'pck', 'precision', 'recall',
+  'mpjpe', 'error rate', 'detection rate', 'true positive',
 ];

+// Short/ambiguous metric tokens (ADR-263 F11): 'map' is usually the English
+// word or a file extension, 'f1'/'o1' collide with finding/option labels.
+// They only count as metric mentions when word-bounded, not a `.map` file
+// reference, and the line (after scrubbing) carries a number — "mAP 62.3" is
+// a claim, "F-numbers map to findings" is not.
+// 'map' additionally must not be a `.map` file suffix or a hyphenated
+// compound ("map-free", "map-reduce") — mAP the metric never appears as either.
+const METRIC_TERMS_SHORT = [/(?<![.\w])map\b(?!-)/, /\bf1\b/, /\bauc\b/, /\biou\b/];
+// Finding/option labels (F1, O2, …) count as labels unless the token sits in a
+// metric context: an immediately following score/=/%/digit or colon ("F1: 0.91"),
+// or a number later in the same clause ("F1 reaches 0.91" — an F1-score claim).
+// Bare option refs ("F7 fixes", "O1–O9", "ADR-263 O2") carry no clause number of
+// their own and stay labels. (A surviving 'f1' still only fires as a metric when
+// its scrubbed line actually carries a number — see mentionsMetricTerm.)
+const LABEL_TOKEN_RE = /\b[fo]\d+\b(?!\s*(?:score|=|\d|%|:))(?![^\n.;]*\d)/g;
+const CODE_SPAN_RE = /`[^`]*`/g; // backticked identifiers are code, not claims
+const HAS_NUMBER_RE = /\d/;
+
+/** Line with code spans and finding/option labels removed. */
+function scrubLine(lower) {
+  return lower.replace(CODE_SPAN_RE, ' ').replace(LABEL_TOKEN_RE, ' ');
+}
+
+function mentionsMetricTerm(lower, scrubbed) {
+  if (METRIC_TERMS.some((t) => lower.includes(t))) return true;
+  if (!HAS_NUMBER_RE.test(scrubbed)) return false;
+  return METRIC_TERMS_SHORT.some((re) => re.test(scrubbed));
+}
+
 /** Tags that make a claim honest (case-insensitive). */
 const HONEST_TAGS = ['measured', 'claimed', 'synthetic', 'unvalidated', 'baseline'];

@@ -20,6 +49,8 @@ const HONEST_TAGS = ['measured', 'claimed', 'synthetic', 'unvalidated', 'baselin
 const REPRODUCER_HINTS = [
  'verify.py', 'witness', 'mean-pose', 'mean pose', 'held-out', 'held out',
  'baseline', 'reproduce', 'sha256', 'boot log', 'pck@20 vs', 'expected_features',
+  // Packaging-claim reproducers (ADR-263/264 npm reviews): the tarball itself.
+  'npm pack', 'npm view', 'npm i ', 'npm install', 'tarball', 'cargo test',
 ];

 const PERCENT_RE = /\b(\d{1,3}(?:\.\d+)?)\s?%/g;
@@ -49,7 +80,8 @@ export function claimCheck(text) {

    const hasPercent = PERCENT_RE.test(line);
    PERCENT_RE.lastIndex = 0; // reset stateful global regex
-    const mentionsMetric = METRIC_TERMS.some((t) => lower.includes(t));
+    const scrubbed = scrubLine(lower);
+    const mentionsMetric = mentionsMetricTerm(lower, scrubbed);
    if (!hasPercent && !mentionsMetric) return;

    const tagged = HONEST_TAGS.some((t) => lower.includes(t));
@@ -67,6 +99,15 @@ export function claimCheck(text) {
      return;
    }

+    // A quantitative claim needs a number. Digits hidden in a code span still
+    // count — "accuracy reached `0.95`" is a claim — so test the line with only
+    // finding/option labels stripped, NOT the code-span-scrubbed copy: scrubbing
+    // dropped `0.95` and wrongly short-circuited both the untagged and the
+    // MEASURED-without-reproducer checks below. A bare metric word in prose
+    // ("precision matters here", "every accuracy number must be MEASURED") has no
+    // number and is not a taggable claim (ADR-263 F11).
+    if (!hasPercent && !HAS_NUMBER_RE.test(lower.replace(LABEL_TOKEN_RE, ' '))) return;
+
    // A metric/percent with no honesty tag at all.
    if (!tagged) {
      findings.push({
@@ -79,7 +120,8 @@ export function claimCheck(text) {
      return;
    }

-    // Tagged MEASURED but cites no reproducer — still a gap.
+    // Tagged MEASURED but cites no reproducer — still a gap (reached now even
+    // when the only number is inside a code span, e.g. "accuracy `0.97` (MEASURED)").
    if (lower.includes('measured') && !hasReproducer) {
      findings.push({
        severity: 'medium',
@@ -3,14 +3,23 @@
 //
 // Dependency-free on purpose: a published `npx ruview` must `mcp start` without
 // pulling the full MCP SDK. Implements the subset hosts use: `initialize`,
-// `tools/list`, `tools/call`, and the `notifications/initialized` ack. Logs go to
-// stderr ONLY — stdout is the JSON-RPC channel and must stay clean.
+// `tools/list`, `tools/call`, `ping`, empty `resources/list`/`prompts/list`
+// stubs, and the `notifications/initialized` ack. Logs go to stderr ONLY —
+// stdout is the JSON-RPC channel and must stay clean.
+//
+// ADR-263 O2: `tools/call` is dispatched asynchronously — a long-running
+// verify/calibrate no longer blocks ping/tools/list, so hosts that health-check
+// mid-run see a live server. Responses may therefore arrive out of request
+// order, which JSON-RPC permits (ids correlate them).

 import { createInterface } from 'node:readline';
+import { readFileSync } from 'node:fs';
 import { listTools, runTool } from './tools.js';

 const PROTOCOL_VERSION = '2024-11-05';
-const SERVER_INFO = { name: 'ruview', version: '0.1.0' };
+// Single-source the version from package.json (ADR-263 O6).
+const PKG = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+const SERVER_INFO = { name: 'ruview', version: PKG.version };

 function send(msg) {
  process.stdout.write(JSON.stringify(msg) + '\n');
@@ -19,7 +28,7 @@ function result(id, res) { send({ jsonrpc: '2.0', id, result: res }); }
 function error(id, code, message) { send({ jsonrpc: '2.0', id, error: { code, message } }); }
 function log(...a) { process.stderr.write('[ruview-mcp] ' + a.join(' ') + '\n'); }

-function handle(msg) {
+async function handle(msg) {
  const { id, method, params } = msg;
  switch (method) {
    case 'initialize':
@@ -27,19 +36,24 @@ function handle(msg) {
        protocolVersion: PROTOCOL_VERSION,
        capabilities: { tools: { listChanged: false } },
        serverInfo: SERVER_INFO,
-        instructions: 'RuView WiFi-sensing operator tools. All results are fail-closed; accuracy claims must pass ruview.claim_check.',
+        instructions: 'RuView WiFi-sensing operator tools. All results are fail-closed; accuracy claims must pass ruview_claim_check.',
      });
    case 'notifications/initialized':
    case 'initialized':
-      return; // notification — no response
+    case 'notifications/cancelled':
+      return; // notifications — no response
    case 'ping':
      return result(id, {});
    case 'tools/list':
      return result(id, { tools: listTools() });
+    case 'resources/list':
+      return result(id, { resources: [] });
+    case 'prompts/list':
+      return result(id, { prompts: [] });
    case 'tools/call': {
      const name = params?.name;
      const args = params?.arguments || {};
-      const out = runTool(name, args);
+      const out = await runTool(name, args);
      // MCP content envelope: text block with the JSON, isError reflects ok=false.
      return result(id, {
        content: [{ type: 'text', text: JSON.stringify(out, null, 2) }],
@@ -52,17 +66,42 @@ function handle(msg) {
 }

 export function startMcpServer() {
-  log(`starting (protocol ${PROTOCOL_VERSION}, ${listTools().length} tools)`);
+  log(`starting v${SERVER_INFO.version} (protocol ${PROTOCOL_VERSION}, ${listTools().length} tools)`);
  const rl = createInterface({ input: process.stdin, crlfDelay: Infinity });
+
+  // tools/call runs are serialized through a FIFO promise chain: hardware/mutating
+  // tools (calibrate, serial monitor, flash) must never overlap. ping/tools/list/
+  // initialize/resources/prompts stay immediate (ADR-263 O2 — a health check must
+  // answer during a long tool run). `toolChain` also lets stdin-close drain the
+  // in-flight call so its response is flushed instead of dropped by process.exit.
+  let toolChain = Promise.resolve();
+
+  const dispatch = (msg) => handle(msg).catch((err) => {
+    if (msg && msg.id !== undefined) error(msg.id, -32603, String(err && err.message || err));
+    log('handler error:', String(err));
+  });
+
  rl.on('line', (line) => {
    const s = line.trim();
    if (!s) return;
    let msg;
    try { msg = JSON.parse(s); } catch { return log('bad JSON line dropped'); }
-    try { handle(msg); } catch (err) {
-      if (msg && msg.id !== undefined) error(msg.id, -32603, String(err && err.message || err));
-      log('handler error:', String(err));
+    if (msg && msg.method === 'tools/call') {
+      toolChain = toolChain.then(() => dispatch(msg)); // one tool at a time
+    } else {
+      dispatch(msg); // health/list/handshake answer immediately, even mid tool run
    }
  });
-  rl.on('close', () => { log('stdin closed — exiting'); process.exit(0); });
+
+  rl.on('close', () => {
+    // Wait for any queued/in-flight tool call to settle (its response written)
+    // before exiting — fire-and-forget used to race this and drop the response.
+    toolChain.then(() => {
+      log('stdin closed — exiting');
+      const done = () => process.exit(0);
+      // Pipe writes are async; flush buffered stdout before exit.
+      if (process.stdout.writableLength) process.stdout.once('drain', done);
+      else done();
+    });
+  });
 }
@@ -7,10 +7,15 @@
 // `wifi-densepose` binary, an ESP32 on a port) is absent, it returns an honest
 // negative — never a fabricated success. This mirrors the project's "prove
 // everything" rule and the RuField fail-closed posture (ADR-262 §3.3).
+//
+// ADR-263: handlers are async (promise-based spawn, never spawnSync) so the MCP
+// server keeps answering ping/tools/list while a long verify/calibrate runs.
+// Canonical tool names use underscores (host tool-name regexes commonly enforce
+// ^[a-zA-Z0-9_-]{1,64}$); the historical dotted names are accepted as aliases.

-import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
-import { join, dirname, resolve } from 'node:path';
+import { spawn } from 'node:child_process';
+import { existsSync, accessSync, constants } from 'node:fs';
+import { join, dirname, resolve, delimiter } from 'node:path';
 import { claimCheck, summarize } from './guardrails.js';

 /** Walk up from `start` to find the RuView monorepo root (or null). */
@@ -27,22 +32,75 @@ export function findRepoRoot(start = process.cwd()) {
  return null;
 }

-function which(cmd) {
-  const probe = process.platform === 'win32'
-    ? spawnSync('where', [cmd], { encoding: 'utf8' })
-    : spawnSync('command', ['-v', cmd], { encoding: 'utf8', shell: true });
-  return probe.status === 0 ? (probe.stdout || '').trim().split(/\r?\n/)[0] : null;
+// Dep-free PATH scan (ADR-263 O8) — no shell subprocess per lookup. Only hits
+// are memoized: a miss can resolve later in a long-lived MCP session (the
+// operator installs python/the CLI mid-run), so misses are re-probed each call.
+const whichCache = new Map();
+export function which(cmd) {
+  if (whichCache.has(cmd)) return whichCache.get(cmd);
+  const isWin = process.platform === 'win32';
+  const exts = isWin
+    ? (process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)
+    : [''];
+  let found = null;
+  outer:
+  for (const dir of (process.env.PATH || '').split(delimiter)) {
+    if (!dir) continue;
+    for (const ext of isWin ? ['', ...exts] : exts) {
+      const p = join(dir, cmd + ext);
+      try {
+        accessSync(p, isWin ? constants.F_OK : constants.X_OK);
+        found = p;
+        break outer;
+      } catch { /* keep scanning */ }
+    }
+  }
+  if (found !== null) whichCache.set(cmd, found);
+  return found;
 }

-function run(cmd, args, opts = {}) {
-  const r = spawnSync(cmd, args, { encoding: 'utf8', timeout: opts.timeout ?? 120000, ...opts });
-  return {
-    status: r.status,
-    ok: r.status === 0,
-    stdout: (r.stdout || '').slice(-8000),
-    stderr: (r.stderr || '').slice(-4000),
-    error: r.error ? r.error.message : null,
-  };
+// Bounded output tails (ADR-263 O4): spawnSync's default 1 MiB maxBuffer killed
+// chatty children with ENOBUFS; handlers only ever surface the last few kB, so
+// keep rolling tails instead of the full stream.
+const STDOUT_TAIL = 65536;
+const STDERR_TAIL = 16384;
+
+/** Promise-based spawn with timeout + rolling output tails. */
+export function run(cmd, args, opts = {}) {
+  const timeout = opts.timeout ?? 120000;
+  return new Promise((resolvePromise) => {
+    let stdout = '';
+    let stderr = '';
+    let child;
+    try {
+      child = spawn(cmd, args, { cwd: opts.cwd, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (e) {
+      resolvePromise({ status: null, ok: false, stdout: '', stderr: '', error: e.message });
+      return;
+    }
+    let timedOut = false;
+    const timer = setTimeout(() => { timedOut = true; child.kill('SIGKILL'); }, timeout);
+    child.stdout.on('data', (d) => {
+      stdout = (stdout + d).slice(-STDOUT_TAIL);
+    });
+    child.stderr.on('data', (d) => {
+      stderr = (stderr + d).slice(-STDERR_TAIL);
+    });
+    child.on('error', (e) => {
+      clearTimeout(timer);
+      resolvePromise({ status: null, ok: false, stdout, stderr, error: e.message });
+    });
+    child.on('close', (status) => {
+      clearTimeout(timer);
+      resolvePromise({
+        status,
+        ok: status === 0,
+        stdout,
+        stderr,
+        error: timedOut ? `timed out after ${timeout} ms` : null,
+      });
+    });
+  });
 }

 const ONBOARD_PATHS = {
@@ -51,12 +109,36 @@ const ONBOARD_PATHS = {
  'live-esp32': 'Real sensing. Flash an ESP32-S3 (see `provision-node` skill), point it at the sensing-server, then `calibrate → enroll → train-room → room-watch` (see `calibrate-room`). Good for an actual install.',
 };

+// Read-only serial monitor script; the port arrives via sys.argv (ADR-263 O5 —
+// never spliced into interpreter source).
+const MONITOR_SCRIPT = [
+  'import sys,time',
+  'try:',
+  ' import serial',
+  'except Exception as e:',
+  " print('NO_PYSERIAL'); sys.exit(3)",
+  'port=sys.argv[1]',
+  'dur=float(sys.argv[2])',
+  'ser=serial.Serial(port,115200,timeout=1)',
+  'csi=0; n=0; t=time.time()',
+  'while time.time()-t<dur:',
+  ' ln=ser.readline()',
+  ' if not ln: continue',
+  " s=ln.decode('utf-8','replace')",
+  ' n+=1',
+  " if 'CSI cb' in s or 'csi_collector' in s: csi+=1",
+  " if 'MGMT+DATA' in s: print('UPGRADE_MGMT_DATA')",
+  'ser.close()',
+  "print(f'LINES={n} CSI={csi}')",
+].join('\n');
+
 /**
 * The tool registry. Each entry: { title, description, inputSchema, handler }.
- * inputSchema is JSON-Schema (object). handler(args) → JSON-serializable result.
+ * inputSchema is JSON-Schema (object). handler(args) → JSON-serializable result
+ * (sync or promise). Canonical names are underscore-form.
 */
 export const TOOLS = {
-  'ruview.onboard': {
+  ruview_onboard: {
    title: 'Onboard',
    description: 'Pick a RuView setup path (docker-demo | repo-build | live-esp32) and print the next concrete command.',
    inputSchema: {
@@ -74,46 +156,50 @@ export const TOOLS = {
        repo_root: repo,
        paths: ONBOARD_PATHS,
        recommend: repo ? 'repo-build' : 'docker-demo',
-        note: 'WiFi sensing infers coarse pose/presence from CSI — it is not a camera. Accuracy claims must be MEASURED vs a baseline (run `ruview.claim_check`).',
+        note: 'WiFi sensing infers coarse pose/presence from CSI — it is not a camera. Accuracy claims must be MEASURED vs a baseline (run `ruview_claim_check`).',
      };
    },
  },

-  'ruview.claim_check': {
+  ruview_claim_check: {
    title: 'Claim check',
-    description: 'Static lint: scan text for untagged or overstated accuracy claims (the "prove everything" guardrail). Returns findings.',
+    description: 'Static lint: scan text for untagged or overstated accuracy claims (the "prove everything" guardrail). Returns findings. Fail-closed: empty input is an error, not a pass.',
    inputSchema: {
      type: 'object',
      required: ['text'],
      properties: { text: { type: 'string', description: 'The text to lint (a report, README section, PR body, model card).' } },
    },
    handler(args = {}) {
-      const result = claimCheck(String(args.text ?? ''));
+      const text = typeof args.text === 'string' ? args.text : '';
+      if (text.trim().length === 0) {
+        return { ok: false, reason: 'empty_text', hint: 'Pass the text to lint — an empty input must not pass an honesty gate.' };
+      }
+      const result = claimCheck(text);
      return { ...result, summary: summarize(result) };
    },
  },

-  'ruview.verify': {
+  ruview_verify: {
    title: 'Verify (witness)',
    description: 'Run the deterministic proof (archive/v1/data/proof/verify.py) and report VERDICT. Fail-closed if not in a RuView repo or python is missing.',
    inputSchema: {
      type: 'object',
      properties: { repo: { type: 'string', description: 'RuView repo root. Default: auto-detect from cwd.' } },
    },
-    handler(args = {}) {
+    async handler(args = {}) {
      const repo = args.repo ? resolve(args.repo) : findRepoRoot();
      if (!repo) return { ok: false, reason: 'not_in_ruview_repo', hint: 'Run inside the RuView monorepo or pass {repo}.' };
      const proof = join(repo, 'archive', 'v1', 'data', 'proof', 'verify.py');
      if (!existsSync(proof)) return { ok: false, reason: 'proof_missing', path: proof };
      const py = which('python') || which('python3');
      if (!py) return { ok: false, reason: 'python_missing', hint: 'Install python to run the deterministic proof.' };
-      const r = run(py, [proof], { cwd: repo, timeout: 180000 });
+      const r = await run(py, [proof], { cwd: repo, timeout: 180000 });
      const verdict = /VERDICT:\s*PASS/i.test(r.stdout) ? 'PASS' : (/VERDICT:\s*FAIL/i.test(r.stdout) ? 'FAIL' : 'UNKNOWN');
      return { ok: r.ok && verdict === 'PASS', verdict, exit: r.status, tail: r.stdout.slice(-1200), stderr: r.stderr.slice(-400) };
    },
  },

-  'ruview.node_monitor': {
+  ruview_node_monitor: {
    title: 'Node monitor',
    description: 'Open an ESP32 serial port and assert CSI is flowing (MGMT+DATA). Fail-closed if python+pyserial or the port is absent. Read-only.',
    inputSchema: {
@@ -123,31 +209,13 @@ export const TOOLS = {
        seconds: { type: 'number', description: 'Capture window (default 12).' },
      },
    },
-    handler(args = {}) {
+    async handler(args = {}) {
      const port = args.port;
-      if (!port) return { ok: false, reason: 'no_port', hint: 'Pass {port} (e.g. COM8).' };
+      if (!port || typeof port !== 'string') return { ok: false, reason: 'no_port', hint: 'Pass {port} (e.g. COM8).' };
      const py = which('python') || which('python3');
      if (!py) return { ok: false, reason: 'python_missing' };
      const dur = Number(args.seconds) > 0 ? Number(args.seconds) : 12;
-      const script = [
-        'import sys,time',
-        'try:',
-        ' import serial',
-        'except Exception as e:',
-        " print('NO_PYSERIAL'); sys.exit(3)",
-        `ser=serial.Serial(${JSON.stringify(port)},115200,timeout=1)`,
-        'csi=0; n=0; t=time.time()',
-        `while time.time()-t<${dur}:`,
-        ' ln=ser.readline()',
-        ' if not ln: continue',
-        " s=ln.decode('utf-8','replace')",
-        ' n+=1',
-        " if 'CSI cb' in s or 'csi_collector' in s: csi+=1",
-        " if 'MGMT+DATA' in s: print('UPGRADE_MGMT_DATA')",
-        'ser.close()',
-        "print(f'LINES={n} CSI={csi}')",
-      ].join('\n');
-      const r = run(py, ['-c', script], { timeout: (dur + 10) * 1000 });
+      const r = await run(py, ['-c', MONITOR_SCRIPT, port, String(dur)], { timeout: (dur + 10) * 1000 });
      if (r.stdout.includes('NO_PYSERIAL')) return { ok: false, reason: 'pyserial_missing', hint: 'pip install pyserial' };
      if (!r.ok) return { ok: false, reason: 'port_error', stderr: r.stderr, error: r.error };
      const csi = Number((r.stdout.match(/CSI=(\d+)/) || [])[1] || 0);
@@ -156,7 +224,7 @@ export const TOOLS = {
    },
  },

-  'ruview.calibrate': {
+  ruview_calibrate: {
    title: 'Calibrate room',
    description: 'Run the ADR-151 room pipeline via the wifi-densepose CLI (baseline→enroll→train-room). Fail-closed if the binary is absent.',
    inputSchema: {
@@ -166,7 +234,7 @@ export const TOOLS = {
        args: { type: 'array', items: { type: 'string' }, description: 'Extra CLI args passed through.' },
      },
    },
-    handler(args = {}) {
+    async handler(args = {}) {
      const step = args.step || 'baseline';
      const bin = which('wifi-densepose');
      const repo = findRepoRoot();
@@ -174,13 +242,13 @@ export const TOOLS = {
      const passthru = Array.isArray(args.args) ? args.args.map(String) : [];
      // Prefer the installed binary; otherwise cargo-run from the repo.
      const r = bin
-        ? run(bin, [step, ...passthru], { timeout: 300000 })
-        : run('cargo', ['run', '-q', '-p', 'wifi-densepose-cli', '--', step, ...passthru], { cwd: repo, timeout: 600000 });
+        ? await run(bin, [step, ...passthru], { timeout: 300000 })
+        : await run('cargo', ['run', '-q', '-p', 'wifi-densepose-cli', '--', step, ...passthru], { cwd: repo, timeout: 600000 });
      return { ok: r.ok, step, via: bin ? 'binary' : 'cargo', exit: r.status, tail: r.stdout.slice(-1500), stderr: r.stderr.slice(-500) };
    },
  },

-  'ruview.node_flash': {
+  ruview_node_flash: {
    title: 'Node flash',
    description: 'Build+flash an ESP32 firmware variant. MUTATING + hardware. Fail-closed off-Windows or without ESP-IDF. Never claims hardware validation without a boot log.',
    inputSchema: {
@@ -203,14 +271,27 @@ export const TOOLS = {
  },
 };

-/** Run one tool by name; returns the structured result (or an error envelope). */
-export function runTool(name, args) {
-  const tool = TOOLS[name];
-  if (!tool) return { ok: false, reason: 'unknown_tool', name, available: Object.keys(TOOLS) };
+// Historical dotted names (pre-ADR-263) accepted as call-time aliases; the
+// underscore form is what tools/list advertises.
+export const TOOL_ALIASES = Object.fromEntries(
+  Object.keys(TOOLS).map((name) => [name.replace(/_/, '.'), name])
+);
+
+/** Resolve a canonical or aliased tool name (or null). */
+export function resolveToolName(name) {
+  if (TOOLS[name]) return name;
+  if (TOOL_ALIASES[name]) return TOOL_ALIASES[name];
+  return null;
+}
+
+/** Run one tool by name (canonical or dotted alias); always resolves to the structured result. */
+export async function runTool(name, args) {
+  const canonical = resolveToolName(name);
+  if (!canonical) return { ok: false, reason: 'unknown_tool', name, available: Object.keys(TOOLS) };
  try {
-    return tool.handler(args || {});
+    return await TOOLS[canonical].handler(args || {});
  } catch (err) {
-    return { ok: false, reason: 'tool_threw', name, error: String(err && err.message || err) };
+    return { ok: false, reason: 'tool_threw', name: canonical, error: String(err && err.message || err) };
  }
 }