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-20 17:03:24 +00:00 · 2026-07-02 13:11:15 -04:00
parent 1a0492992f
commit e6f26e9ac9
48 changed files with 2457 additions and 981 deletions
@@ -12,7 +12,7 @@
        "yargs": "^17.7.2"
      },
      "bin": {
-        "ruview": "dist/index.js"
+        "ruview-cli": "dist/index.js"
      },
      "devDependencies": {
        "@types/node": "^20.14.0",
@@ -1,13 +1,13 @@
 {
  "name": "@ruv/ruview-cli",
  "version": "0.0.1",
-  "description": "RuView CLI — shell access to WiFi-DensePose sensing, inference, and training capabilities",
+  "description": "RuView CLI — shell access to WiFi-DensePose sensing, inference, and training capabilities. Private/unpublished; the `ruview` bin name belongs to @ruvnet/ruview (ADR-265 D4).",
  "private": true,
  "type": "module",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "bin": {
-    "ruview": "dist/index.js"
+    "ruview-cli": "dist/index.js"
  },
  "files": [
    "dist"
@@ -15,7 +15,7 @@
  "scripts": {
    "build": "tsc",
    "dev": "tsc --watch",
-    "test": "node --experimental-vm-modules node_modules/.bin/jest",
+    "test": "node --experimental-vm-modules node_modules/.bin/jest --passWithNoTests",
    "lint": "eslint src --ext .ts",
    "typecheck": "tsc --noEmit"
  },
@@ -25,6 +25,7 @@
 * See ADR-104 for the full design rationale and security model.
 */

+import { createRequire } from "node:module";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import { csiCommand } from "./commands/csi.js";
@@ -34,9 +35,15 @@ import { cogsCommand } from "./commands/cogs.js";
 import { trainCommand } from "./commands/train.js";
 import { jobCommand } from "./commands/job.js";

+// Single-source the version from package.json (ADR-265 D3).
+const require = createRequire(import.meta.url);
+const VERSION: string = (require("../package.json") as { version: string }).version;
+
+// Bin name is `ruview-cli`: the bare `ruview` bin belongs to @ruvnet/ruview
+// (ADR-264 O9 / ADR-265 D4).
 const cli = yargs(hideBin(process.argv))
-  .scriptName("ruview")
-  .version("0.0.1")
+  .scriptName("ruview-cli")
+  .version(VERSION)
  .usage("$0 <command> [options]")
  .strict()
  .help()
@@ -2,52 +2,63 @@

 **SENSE-BRIDGE** is a dual-transport [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that bridges the RuView WiFi-DensePose sensing stack to AI agents (Claude Code, Cursor, ruflo swarms, and any MCP-compatible client).

-Install once; AI agents can then call `ruview.presence.now`, `ruview.vitals.get_heart_rate`, `ruview.bfld.last_scan`, and more — without writing HTTP or WebSocket client code.
+Install once; AI agents can then call `ruview_presence_now`, `ruview_vitals_get_heart_rate`, `ruview_bfld_last_scan`, and more — without writing HTTP or WebSocket client code.

 ## Quickstart

 ```bash
-# 1. Add to Claude Code
-claude mcp add rvagent -- npx @ruvnet/rvagent stdio
+# 1. Add to Claude Code (stdio transport — the default)
+claude mcp add rvagent -- npx -y @ruvnet/rvagent

 # 2. Or run directly
-RUVIEW_SENSING_SERVER_URL=http://cognitum-v0:3000 npx @ruvnet/rvagent stdio
+RUVIEW_SENSING_SERVER_URL=http://cognitum-v0:3000 npx @ruvnet/rvagent

-# 3. Streamable HTTP (remote agents, ruflo swarms)
+# 3. Streamable HTTP (remote agents, ruflo swarms) — explicit opt-in
 RUVIEW_SENSING_SERVER_URL=http://cognitum-v0:3000 \
 RVAGENT_HTTP_TOKEN=your-secret \
-npx @ruvnet/rvagent http --port 3001
-# POST JSON-RPC to http://127.0.0.1:3001/mcp
+RVAGENT_HTTP_PORT=3001 npx @ruvnet/rvagent
+# POST JSON-RPC to http://127.0.0.1:3001/mcp (initialize first; then send the
+# returned mcp-session-id header on every request)
 ```

 Requirements: **Node.js >= 20**. The `wifi-densepose-sensing-server` Rust binary must be reachable at `RUVIEW_SENSING_SERVER_URL` (default `http://localhost:3000`).

-## Feature matrix
+## Tools
+
+Canonical tool names are underscore-form (ADR-264 — host tool-name validators
+commonly enforce `^[a-zA-Z0-9_-]{1,64}$`). The pre-0.1.1 dotted names
+(`ruview.presence.now`, …) are still accepted at call time as deprecated
+aliases; `tools/list` advertises the underscore form only.

 | Tool | Description | ADR |
 |------|-------------|-----|
-| `ruview.presence.now` | Current occupancy: `present`, `n_persons`, `confidence` | ADR-124 §4.1 |
-| `ruview.vitals.get_breathing` | Breathing rate bpm (null if unavailable) | ADR-124 §4.1 |
-| `ruview.vitals.get_heart_rate` | Heart rate bpm (null if unavailable) | ADR-124 §4.1 |
-| `ruview.vitals.get_all` | Full `EdgeVitalsMessage` surface | ADR-124 §4.1 |
-| `ruview.bfld.last_scan` | Latest BFLD scan: `identity_risk_score`, `privacy_class`, `n_frames` | ADR-118/124 |
-| `ruview.bfld.subscribe` | Subscribe to `ruview/<node_id>/bfld/*` events for `duration_s` seconds | ADR-122/124 |
-| *(next iters)* | `pose.latest`, `primitives.*`, `node.*`, `vector.*`, `policy.*` | ADR-124 §4.1/4.1a |
+| `ruview_csi_latest` | Latest 56×20 CSI window from the sensing-server | ADR-101/102 |
+| `ruview_pose_infer` | Single-shot 17-keypoint pose inference via cog binary | ADR-101 |
+| `ruview_count_infer` | Single-shot person-count inference via cog binary | ADR-103 |
+| `ruview_registry_list` | Cognitum edge module registry (category/search filters) | ADR-102 |
+| `ruview_train_count` | Kick off a count-cog training run (background job) | ADR-103 |
+| `ruview_job_status` | Poll a training job (persists across server restarts) | ADR-103 |
+| `ruview_presence_now` | Current occupancy: `present`, `n_persons`, `confidence` | ADR-124 §4.1 |
+| `ruview_vitals_get_breathing` | Breathing rate bpm (null if unavailable) | ADR-124 §4.1 |
+| `ruview_vitals_get_heart_rate` | Heart rate bpm (null if unavailable) | ADR-124 §4.1 |
+| `ruview_vitals_get_all` | Full `EdgeVitalsMessage` surface | ADR-124 §4.1 |
+| `ruview_bfld_last_scan` | Latest BFLD scan: `identity_risk_score`, `privacy_class`, `n_frames` | ADR-118/124 |
+| `ruview_bfld_subscribe` | Subscribe to `ruview/<node_id>/bfld/*` events for `duration_s` seconds | ADR-122/124 |
+| *(roadmap, ADR-124 §4.1/4.1a)* | `pose.latest`, `primitives.*`, `node.*`, `vector.*`, and the `policy.*` governance layer are catalogued in `src/schemas/` but **not yet implemented** | ADR-124 |

-**Transport security (ADR-124 §6)**:
- **stdio**: process-level isolation — no auth needed for local Claude Code / Cursor.
- **Streamable HTTP** (`POST /mcp`): Origin header validation (cross-origin → 403), optional bearer token (`RVAGENT_HTTP_TOKEN` → 401 on mismatch), binds `127.0.0.1` by default per MCP spec.
+**Transport security (ADR-124 §6, hardened per ADR-264)**:
+- **stdio** (default): process-level isolation — no auth needed for local Claude Code / Cursor.
+- **Streamable HTTP** (`/mcp`, opt-in via `RVAGENT_HTTP_PORT`): one transport + one MCP server per session (routed by `mcp-session-id`), Origin validation (localhost on any port allowed; anything else → 403), optional bearer token (`RVAGENT_HTTP_TOKEN` → 401 on mismatch), 1 MiB request-body cap (413), binds `127.0.0.1` by default per MCP spec.

-**Schema validation**: every tool call runs `zod.safeParse` before dispatch; invalid arguments return `McpError(InvalidParams)` rather than a wrapped string.
-
-**Policy layer** (ADR-124 §4.1a): `ruview.policy.*` tools gate every sensing call — `vitals.*` is default-deny until a policy grant is registered via `npx @ruvnet/rvagent policy grant`. Presence and node-list are allow by default.
+**Schema validation**: each tool declares one Zod schema; the CallTool gate parses exactly once and the advertised JSON Schema is generated from the same Zod source. Invalid arguments return `McpError(InvalidParams)` rather than a wrapped string.

 ## ADR cross-reference

 | ADR | Decision |
 |-----|----------|
 | [ADR-124](../../docs/adr/ADR-124-rvagent-mcp-ruvector-npm-integration.md) | SENSE-BRIDGE: dual-transport MCP server + ruvector npm + ruflo integration |
-| [ADR-118](../../docs/adr/ADR-118-bfld-beamforming-feedback-layer-for-detection.md) | BFLD pipeline — source of `bfld.last_scan` wire format |
+| [ADR-264](../../docs/adr/ADR-264-rvagent-mcp-and-cli-npm-deep-review.md) | npm deep review — exports fix, map-free tarball, naming, session-per-transport |
+| [ADR-118](../../docs/adr/ADR-118-bfld-beamforming-feedback-layer-for-detection.md) | BFLD pipeline — source of `bfld_last_scan` wire format |
 | [ADR-122](../../docs/adr/ADR-122-bfld-ruview-ha-matter-exposure.md) | MQTT topic routing `ruview/<node_id>/bfld/*` |
 | [ADR-115](../../docs/adr/ADR-115-home-assistant-integration.md) | `EdgeVitalsMessage` WebSocket surface (`ws.py:74-88` parity) |
 | [ADR-055](../../docs/adr/ADR-055-integrated-sensing-server.md) | Sensing-server REST API (`/api/v1/*`) |
@@ -58,7 +69,7 @@ Requirements: **Node.js >= 20**. The `wifi-densepose-sensing-server` Rust binary
 cd tools/ruview-mcp
 npm install
 npm run build   # tsc
-npm test        # jest — 93 tests across 7 suites
+npm test        # jest — 99 tests across 7 suites
 ```

 Source: `tools/ruview-mcp/src/`. Tests: `tools/ruview-mcp/tests/`.
@@ -1,24 +1,24 @@
 {
  "name": "@ruvnet/rvagent",
-  "version": "0.1.0",
+  "version": "0.2.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "@ruvnet/rvagent",
-      "version": "0.1.0",
+      "version": "0.2.0",
      "license": "Apache-2.0",
      "dependencies": {
        "@modelcontextprotocol/sdk": "^1.0.0",
-        "zod": "^3.23.8"
+        "zod": "^3.23.8",
+        "zod-to-json-schema": "^3.25.2"
      },
      "bin": {
        "ruview-mcp": "dist/index.js",
        "rvagent": "dist/index.js"
      },
      "devDependencies": {
-        "@types/express": "^5.0.6",
-        "@types/jest": "^30.0.0",
+        "@types/jest": "^29.5.14",
        "@types/node": "^20.14.0",
        "jest": "^29.7.0",
        "ts-jest": "^29.1.0",
@@ -629,16 +629,6 @@
        }
      }
    },
-    "node_modules/@jest/diff-sequences": {
-      "version": "30.4.0",
-      "resolved": "https://registry.npmjs.org/@jest/diff-sequences/-/diff-sequences-30.4.0.tgz",
-      "integrity": "sha512-zOpzlfUs45l6u7jm39qr87JCHUDsaeCtvL+kQe/Vn9jSnRB4/5IPXISm0h9I1vZW/o00Kn4UTJ2MOlhnUGwv3g==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
-      }
-    },
    "node_modules/@jest/environment": {
      "version": "29.7.0",
      "resolved": "https://registry.npmjs.org/@jest/environment/-/environment-29.7.0.tgz",
@@ -700,16 +690,6 @@
        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
      }
    },
-    "node_modules/@jest/get-type": {
-      "version": "30.1.0",
-      "resolved": "https://registry.npmjs.org/@jest/get-type/-/get-type-30.1.0.tgz",
-      "integrity": "sha512-eMbZE2hUnx1WV0pmURZY9XoXPkUYjpc55mb0CrhtdWLtzMQPFvu/rZkTLZFTsdaVQa+Tr4eWAteqcUzoawq/uA==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
-      }
-    },
    "node_modules/@jest/globals": {
      "version": "29.7.0",
      "resolved": "https://registry.npmjs.org/@jest/globals/-/globals-29.7.0.tgz",
@@ -726,30 +706,6 @@
        "node": "^14.15.0 || ^16.10.0 || >=18.0.0"
      }
    },
-    "node_modules/@jest/pattern": {
-      "version": "30.4.0",
-      "resolved": "https://registry.npmjs.org/@jest/pattern/-/pattern-30.4.0.tgz",
-      "integrity": "sha512-RAWn3+f9u8BsHijKJ71uHcFp6vmyEt6VvoWXkl6hKF3qVIuWNmudVjg12DlBPGup/frIl5UcUlH5HfEuvHpEXg==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@types/node": "*",
-        "jest-regex-util": "30.4.0"
-      },
-      "engines": {
-        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
-      }
-    },
-    "node_modules/@jest/pattern/node_modules/jest-regex-util": {
-      "version": "30.4.0",
-      "resolved": "https://registry.npmjs.org/jest-regex-util/-/jest-regex-util-30.4.0.tgz",
-      "integrity": "sha512-mWlvLviKIgIQ8VCuM1xRdD0TWp3zlzionlmDBjuXVBs+VkmXq6FgW9T4Emr7oGz/Rk6feDCGyiugolcQEyp3mg==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
-      }
-    },
    "node_modules/@jest/reporters": {
      "version": "29.7.0",
      "resolved": "https://registry.npmjs.org/@jest/reporters/-/reporters-29.7.0.tgz",
@@ -1061,52 +1017,6 @@
        "@babel/types": "^7.28.2"
      }
    },
-    "node_modules/@types/body-parser": {
-      "version": "1.19.6",
-      "resolved": "https://registry.npmjs.org/@types/body-parser/-/body-parser-1.19.6.tgz",
-      "integrity": "sha512-HLFeCYgz89uk22N5Qg3dvGvsv46B8GLvKKo1zKG4NybA8U2DiEO3w9lqGg29t/tfLRJpJ6iQxnVw4OnB7MoM9g==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@types/connect": "*",
-        "@types/node": "*"
-      }
-    },
-    "node_modules/@types/connect": {
-      "version": "3.4.38",
-      "resolved": "https://registry.npmjs.org/@types/connect/-/connect-3.4.38.tgz",
-      "integrity": "sha512-K6uROf1LD88uDQqJCktA4yzL1YYAK6NgfsI0v/mTgyPKWsX1CnJ0XPSDhViejru1GcRkLWb8RlzFYJRqGUbaug==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@types/node": "*"
-      }
-    },
-    "node_modules/@types/express": {
-      "version": "5.0.6",
-      "resolved": "https://registry.npmjs.org/@types/express/-/express-5.0.6.tgz",
-      "integrity": "sha512-sKYVuV7Sv9fbPIt/442koC7+IIwK5olP1KWeD88e/idgoJqDm3JV/YUiPwkoKK92ylff2MGxSz1CSjsXelx0YA==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@types/body-parser": "*",
-        "@types/express-serve-static-core": "^5.0.0",
-        "@types/serve-static": "^2"
-      }
-    },
-    "node_modules/@types/express-serve-static-core": {
-      "version": "5.1.1",
-      "resolved": "https://registry.npmjs.org/@types/express-serve-static-core/-/express-serve-static-core-5.1.1.tgz",
-      "integrity": "sha512-v4zIMr/cX7/d2BpAEX3KNKL/JrT1s43s96lLvvdTmza1oEvDudCqK9aF/djc/SWgy8Yh0h30TZx5VpzqFCxk5A==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@types/node": "*",
-        "@types/qs": "*",
-        "@types/range-parser": "*",
-        "@types/send": "*"
-      }
-    },
    "node_modules/@types/graceful-fs": {
      "version": "4.1.9",
      "resolved": "https://registry.npmjs.org/@types/graceful-fs/-/graceful-fs-4.1.9.tgz",
@@ -1117,13 +1027,6 @@
        "@types/node": "*"
      }
    },
-    "node_modules/@types/http-errors": {
-      "version": "2.0.5",
-      "resolved": "https://registry.npmjs.org/@types/http-errors/-/http-errors-2.0.5.tgz",
-      "integrity": "sha512-r8Tayk8HJnX0FztbZN7oVqGccWgw98T/0neJphO91KkmOzug1KkofZURD4UaD5uH8AqcFLfdPErnBod0u71/qg==",
-      "dev": true,
-      "license": "MIT"
-    },
    "node_modules/@types/istanbul-lib-coverage": {
      "version": "2.0.6",
      "resolved": "https://registry.npmjs.org/@types/istanbul-lib-coverage/-/istanbul-lib-coverage-2.0.6.tgz",
@@ -1152,229 +1055,14 @@
      }
    },
    "node_modules/@types/jest": {
-      "version": "30.0.0",
-      "resolved": "https://registry.npmjs.org/@types/jest/-/jest-30.0.0.tgz",
-      "integrity": "sha512-XTYugzhuwqWjws0CVz8QpM36+T+Dz5mTEBKhNs/esGLnCIlGdRy+Dq78NRjd7ls7r8BC8ZRMOrKlkO1hU0JOwA==",
+      "version": "29.5.14",
+      "resolved": "https://registry.npmjs.org/@types/jest/-/jest-29.5.14.tgz",
+      "integrity": "sha512-ZN+4sdnLUbo8EVvVc2ao0GFW6oVrQRPn4K2lglySj7APvSrgzxHiNNK99us4WDMi57xxA2yggblIAMNhXOotLQ==",
      "dev": true,
      "license": "MIT",
      "dependencies": {
-        "expect": "^30.0.0",
-        "pretty-format": "^30.0.0"
-      }
-    },
-    "node_modules/@types/jest/node_modules/@jest/expect-utils": {
-      "version": "30.4.1",
-      "resolved": "https://registry.npmjs.org/@jest/expect-utils/-/expect-utils-30.4.1.tgz",
-      "integrity": "sha512-ZBn5CglH8fBsQsvs4VWNzD4aWfUYks+IdOOQU3MEK71ol/BcVm+P+rtb1KpiFBpSWSCE27uOahyyf1vfqOVbcQ==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@jest/get-type": "30.1.0"
-      },
-      "engines": {
-        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
-      }
-    },
-    "node_modules/@types/jest/node_modules/@jest/schemas": {
-      "version": "30.4.1",
-      "resolved": "https://registry.npmjs.org/@jest/schemas/-/schemas-30.4.1.tgz",
-      "integrity": "sha512-i6b4qw5qnP8c5FEeBJg/uZQ4ddrkN6Ca8qISJh0pr7a5hfn3h3v5x60BEbOC7OYAGZNMs1LfFLwnW2CuK8F57Q==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@sinclair/typebox": "^0.34.0"
-      },
-      "engines": {
-        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
-      }
-    },
-    "node_modules/@types/jest/node_modules/@jest/types": {
-      "version": "30.4.1",
-      "resolved": "https://registry.npmjs.org/@jest/types/-/types-30.4.1.tgz",
-      "integrity": "sha512-f1x/vJXIfjOlEmejYpbkbgw1gOqpPECwMvMEtBqe47j7H2Hg8h8w3o3ikhSXq3MI15kg+oQ0exWO0uCtTNJLoQ==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@jest/pattern": "30.4.0",
-        "@jest/schemas": "30.4.1",
-        "@types/istanbul-lib-coverage": "^2.0.6",
-        "@types/istanbul-reports": "^3.0.4",
-        "@types/node": "*",
-        "@types/yargs": "^17.0.33",
-        "chalk": "^4.1.2"
-      },
-      "engines": {
-        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
-      }
-    },
-    "node_modules/@types/jest/node_modules/@sinclair/typebox": {
-      "version": "0.34.49",
-      "resolved": "https://registry.npmjs.org/@sinclair/typebox/-/typebox-0.34.49.tgz",
-      "integrity": "sha512-brySQQs7Jtn0joV8Xh9ZV/hZb9Ozb0pmazDIASBkYKCjXrXU3mpcFahmK/z4YDhGkQvP9mWJbVyahdtU5wQA+A==",
-      "dev": true,
-      "license": "MIT"
-    },
-    "node_modules/@types/jest/node_modules/ansi-styles": {
-      "version": "5.2.0",
-      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-5.2.0.tgz",
-      "integrity": "sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">=10"
-      },
-      "funding": {
-        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
-      }
-    },
-    "node_modules/@types/jest/node_modules/ci-info": {
-      "version": "4.4.0",
-      "resolved": "https://registry.npmjs.org/ci-info/-/ci-info-4.4.0.tgz",
-      "integrity": "sha512-77PSwercCZU2Fc4sX94eF8k8Pxte6JAwL4/ICZLFjJLqegs7kCuAsqqj/70NQF6TvDpgFjkubQB2FW2ZZddvQg==",
-      "dev": true,
-      "funding": [
-        {
-          "type": "github",
-          "url": "https://github.com/sponsors/sibiraj-s"
-        }
-      ],
-      "license": "MIT",
-      "engines": {
-        "node": ">=8"
-      }
-    },
-    "node_modules/@types/jest/node_modules/expect": {
-      "version": "30.4.1",
-      "resolved": "https://registry.npmjs.org/expect/-/expect-30.4.1.tgz",
-      "integrity": "sha512-PMARsyh/JtqC20HoGqlFcIlQAyqUtW4PlI1rup1uhYJtKuwAjbvWi3GQMAn+STdHum/dk8xrKfUM1+5SAwpolA==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@jest/expect-utils": "30.4.1",
-        "@jest/get-type": "30.1.0",
-        "jest-matcher-utils": "30.4.1",
-        "jest-message-util": "30.4.1",
-        "jest-mock": "30.4.1",
-        "jest-util": "30.4.1"
-      },
-      "engines": {
-        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
-      }
-    },
-    "node_modules/@types/jest/node_modules/jest-diff": {
-      "version": "30.4.1",
-      "resolved": "https://registry.npmjs.org/jest-diff/-/jest-diff-30.4.1.tgz",
-      "integrity": "sha512-CRpFK0RtLriVDGcPPAnR6HMVI8bSR2jnUIgralhauzYQZIb4RH9AtEInTuQr65LmmGggGcRT6HIASxwqsVsmlA==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@jest/diff-sequences": "30.4.0",
-        "@jest/get-type": "30.1.0",
-        "chalk": "^4.1.2",
-        "pretty-format": "30.4.1"
-      },
-      "engines": {
-        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
-      }
-    },
-    "node_modules/@types/jest/node_modules/jest-matcher-utils": {
-      "version": "30.4.1",
-      "resolved": "https://registry.npmjs.org/jest-matcher-utils/-/jest-matcher-utils-30.4.1.tgz",
-      "integrity": "sha512-zvYfX5CaeEkFrrLS9suWe9rvJrm9J1Iv3ua8kIBv9GEPzcnsfBf0bob37la7s67fs0nlBC3EuvkOLnXQKxtx4A==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@jest/get-type": "30.1.0",
-        "chalk": "^4.1.2",
-        "jest-diff": "30.4.1",
-        "pretty-format": "30.4.1"
-      },
-      "engines": {
-        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
-      }
-    },
-    "node_modules/@types/jest/node_modules/jest-message-util": {
-      "version": "30.4.1",
-      "resolved": "https://registry.npmjs.org/jest-message-util/-/jest-message-util-30.4.1.tgz",
-      "integrity": "sha512-kwCKIvq0MCW1HzLoGola9Te6JUdzgV0loyKJ3Qghrkz9i5/RRIHsL95BMQc2HBBhlBKC4j22K9p11TGHH8RBpQ==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@babel/code-frame": "^7.27.1",
-        "@jest/types": "30.4.1",
-        "@types/stack-utils": "^2.0.3",
-        "chalk": "^4.1.2",
-        "graceful-fs": "^4.2.11",
-        "jest-util": "30.4.1",
-        "picomatch": "^4.0.3",
-        "pretty-format": "30.4.1",
-        "slash": "^3.0.0",
-        "stack-utils": "^2.0.6"
-      },
-      "engines": {
-        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
-      }
-    },
-    "node_modules/@types/jest/node_modules/jest-mock": {
-      "version": "30.4.1",
-      "resolved": "https://registry.npmjs.org/jest-mock/-/jest-mock-30.4.1.tgz",
-      "integrity": "sha512-/i8SVb8/NSB7RfNi8gfqu8gxLV23KaL5EpAttyb9iz8qWRIqXRLflycz/32wXsYkOnaUlx8NAKnJYtpsmXUmfw==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@jest/types": "30.4.1",
-        "@types/node": "*",
-        "jest-util": "30.4.1"
-      },
-      "engines": {
-        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
-      }
-    },
-    "node_modules/@types/jest/node_modules/jest-util": {
-      "version": "30.4.1",
-      "resolved": "https://registry.npmjs.org/jest-util/-/jest-util-30.4.1.tgz",
-      "integrity": "sha512-vjQb1sACEiv13DKJMDToJpzVW0joCsIQrmbg0fi7CyOOt+g9jTuQl2A216pWRBYhOVt53XbL/2LbMKg1BECWOw==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@jest/types": "30.4.1",
-        "@types/node": "*",
-        "chalk": "^4.1.2",
-        "ci-info": "^4.2.0",
-        "graceful-fs": "^4.2.11",
-        "picomatch": "^4.0.3"
-      },
-      "engines": {
-        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
-      }
-    },
-    "node_modules/@types/jest/node_modules/picomatch": {
-      "version": "4.0.4",
-      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz",
-      "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
-      "dev": true,
-      "license": "MIT",
-      "engines": {
-        "node": ">=12"
-      },
-      "funding": {
-        "url": "https://github.com/sponsors/jonschlinkert"
-      }
-    },
-    "node_modules/@types/jest/node_modules/pretty-format": {
-      "version": "30.4.1",
-      "resolved": "https://registry.npmjs.org/pretty-format/-/pretty-format-30.4.1.tgz",
-      "integrity": "sha512-K6KiKMHTL4jjX4u3Kir2EW07nRfcqVTXIImx50wbjHQTcZPgg+gjVeNTIT3l3L1Rd4UefxfogquC9J37SoFyyw==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@jest/schemas": "30.4.1",
-        "ansi-styles": "^5.2.0",
-        "react-is-18": "npm:react-is@^18.3.1",
-        "react-is-19": "npm:react-is@^19.2.5"
-      },
-      "engines": {
-        "node": "^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0"
+        "expect": "^29.0.0",
+        "pretty-format": "^29.0.0"
      }
    },
    "node_modules/@types/node": {
@@ -1387,41 +1075,6 @@
        "undici-types": "~6.21.0"
      }
    },
-    "node_modules/@types/qs": {
-      "version": "6.15.1",
-      "resolved": "https://registry.npmjs.org/@types/qs/-/qs-6.15.1.tgz",
-      "integrity": "sha512-GZHUBZR9hckSUhrxmp1nG6NwdpM9fCunJwyThLW1X3AyHgd9IlHb6VANpQQqDr2o/qQp6McZ3y/IA2rVzKzSbw==",
-      "dev": true,
-      "license": "MIT"
-    },
-    "node_modules/@types/range-parser": {
-      "version": "1.2.7",
-      "resolved": "https://registry.npmjs.org/@types/range-parser/-/range-parser-1.2.7.tgz",
-      "integrity": "sha512-hKormJbkJqzQGhziax5PItDUTMAM9uE2XXQmM37dyd4hVM+5aVl7oVxMVUiVQn2oCQFN/LKCZdvSM0pFRqbSmQ==",
-      "dev": true,
-      "license": "MIT"
-    },
-    "node_modules/@types/send": {
-      "version": "1.2.1",
-      "resolved": "https://registry.npmjs.org/@types/send/-/send-1.2.1.tgz",
-      "integrity": "sha512-arsCikDvlU99zl1g69TcAB3mzZPpxgw0UQnaHeC1Nwb015xp8bknZv5rIfri9xTOcMuaVgvabfIRA7PSZVuZIQ==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@types/node": "*"
-      }
-    },
-    "node_modules/@types/serve-static": {
-      "version": "2.2.0",
-      "resolved": "https://registry.npmjs.org/@types/serve-static/-/serve-static-2.2.0.tgz",
-      "integrity": "sha512-8mam4H1NHLtu7nmtalF7eyBH14QyOASmcxHhSfEoRyr0nP/YdoesEtU+uSRvMe96TW/HPTtkoKqQLl53N7UXMQ==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@types/http-errors": "*",
-        "@types/node": "*"
-      }
-    },
    "node_modules/@types/stack-utils": {
      "version": "2.0.3",
      "resolved": "https://registry.npmjs.org/@types/stack-utils/-/stack-utils-2.0.3.tgz",
@@ -4355,22 +4008,6 @@
      "dev": true,
      "license": "MIT"
    },
-    "node_modules/react-is-18": {
-      "name": "react-is",
-      "version": "18.3.1",
-      "resolved": "https://registry.npmjs.org/react-is/-/react-is-18.3.1.tgz",
-      "integrity": "sha512-/LLMVyas0ljjAtoYiPqYiL8VWXzUUdThrmU5+n20DZv+a+ClRoevUzw5JxU+Ieh5/c87ytoTBV9G1FiKfNJdmg==",
-      "dev": true,
-      "license": "MIT"
-    },
-    "node_modules/react-is-19": {
-      "name": "react-is",
-      "version": "19.2.6",
-      "resolved": "https://registry.npmjs.org/react-is/-/react-is-19.2.6.tgz",
-      "integrity": "sha512-XjBR15BhXuylgWGuslhDKqlSayuqvqBX91BP8pauG8kd1zY8kotkNWbXksTCNRarse4kuGbe2kIY05ARtwNIvw==",
-      "dev": true,
-      "license": "MIT"
-    },
    "node_modules/require-directory": {
      "version": "2.1.1",
      "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz",
@@ -1,15 +1,14 @@
 {
  "name": "@ruvnet/rvagent",
-  "version": "0.1.0",
-  "description": "SENSE-BRIDGE: dual-transport MCP server (stdio + Streamable HTTP) exposing RuView WiFi-DensePose sensing primitives to AI agents",
+  "version": "0.2.0",
+  "description": "SENSE-BRIDGE: dual-transport MCP server (stdio default; Streamable HTTP opt-in via RVAGENT_HTTP_PORT) exposing RuView WiFi-DensePose sensing primitives to AI agents",
  "type": "module",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "exports": {
    ".": {
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
    }
  },
  "bin": {
@@ -18,8 +17,7 @@
  },
  "files": [
    "dist",
-    "README.md",
-    "CHANGELOG.md"
+    "README.md"
  ],
  "scripts": {
    "build": "tsc",
@@ -27,7 +25,8 @@
    "start": "node dist/index.js",
    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js --forceExit",
    "lint": "eslint src --ext .ts",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm test"
  },
  "keywords": [
    "mcp",
@@ -53,11 +52,11 @@
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.0",
-    "zod": "^3.23.8"
+    "zod": "^3.23.8",
+    "zod-to-json-schema": "^3.25.2"
  },
  "devDependencies": {
-    "@types/express": "^5.0.6",
-    "@types/jest": "^30.0.0",
+    "@types/jest": "^29.5.14",
    "@types/node": "^20.14.0",
    "jest": "^29.7.0",
    "ts-jest": "^29.1.0",
@@ -8,6 +8,7 @@

 import os from "node:os";
 import path from "node:path";
+import { existsSync } from "node:fs";
 import type { RuviewConfig } from "./types.js";

 function env(key: string): string | undefined {
@@ -51,17 +52,35 @@ export function loadConfig(): RuviewConfig {
 }

 /**
- * Attempt to locate a cog binary on PATH or in common install locations.
- * Returns the bare binary name if not found (will fail gracefully at invocation).
+ * Ordered cog-binary candidate paths for a host of the given CPU architecture.
+ * The native-arch build is probed FIRST: an appliance that ships both
+ * `cog-<id>-arm` and `cog-<id>-x86_64` must never hand back the wrong-arch
+ * binary (ADR-264 F8/O7 — the pre-review order tried `-arm` unconditionally).
+ * The `/usr/local/bin` and bare-name (PATH) fallbacks follow, arch-agnostic.
+ *
+ * Pure and arch-injectable so the ordering is unit-testable.
+ */
+export function cogBinaryCandidates(
+  name: string,
+  arch: string = process.arch
+): string[] {
+  const id = name.replace("cog-", "");
+  const dir = `/var/lib/cognitum/apps/${id}`;
+  const arm = `${dir}/cog-${id}-arm`;
+  const x86 = `${dir}/cog-${id}-x86_64`;
+  // arm64 → prefer -arm; everything else (notably x64) → prefer -x86_64.
+  const archOrdered = arch === "arm64" ? [arm, x86] : [x86, arm];
+  return [...archOrdered, `/usr/local/bin/${name}`];
+}
+
+/**
+ * Locate a cog binary in the common appliance install locations, probing each
+ * candidate in native-arch-first order. Falls back to the bare name (PATH
+ * resolution at spawn time) when no candidate exists.
 */
 function detectCogBinary(name: string): string {
-  // Common install paths for Cognitum cog binaries on Linux/macOS appliances.
-  const candidates = [
-    `/var/lib/cognitum/apps/${name.replace("cog-", "")}/cog-${name.replace("cog-", "")}-arm`,
-    `/var/lib/cognitum/apps/${name.replace("cog-", "")}/cog-${name.replace("cog-", "")}-x86_64`,
-    `/usr/local/bin/${name}`,
-    name, // bare name — rely on PATH
-  ];
-  // Return the first candidate that might exist; actual existence is checked at call time.
-  return candidates[candidates.length - 1] ?? name;
+  for (const candidate of cogBinaryCandidates(name)) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return name; // bare name — rely on PATH; spawn fails gracefully if absent
 }
@@ -1,30 +1,44 @@
 /**
- * Streamable HTTP transport scaffold for @ruvnet/rvagent (ADR-124 §3).
+ * Streamable HTTP transport for @ruvnet/rvagent (ADR-124 §3, hardened per
+ * ADR-264 F7/O3).
 *
- * Binds to 127.0.0.1 by default and mounts a POST /mcp endpoint backed by
+ * Binds to 127.0.0.1 by default and mounts an /mcp endpoint backed by
 * StreamableHTTPServerTransport from @modelcontextprotocol/sdk.
 *
- * Security model (ADR-124 §6):
- *   - Origin validation: requests from origins other than the configured
- *     allowlist are rejected with 403 Forbidden before reaching the MCP layer.
- *   - Default allowlist: ['http://localhost', 'http://127.0.0.1'] — covers
- *     Claude Code and Cursor on the same machine.
+ * Session model (ADR-264 F7): the SDK's stateful mode requires ONE transport
+ * (and one MCP Server) per session. An `initialize` POST creates a fresh
+ * transport + server pair via the caller-supplied factory; follow-up
+ * POST/GET/DELETE requests are routed to their session by the
+ * `mcp-session-id` header. Transports are dropped when their session closes.
+ *
+ * Security model (ADR-124 §6 + ADR-264 F7):
+ *   - Origin validation: browser-style requests whose Origin is not local
+ *     are rejected with 403 before reaching the MCP layer. With NO explicit
+ *     allowlist, localhost origins match on hostname, ANY port
+ *     (http://localhost:5173 is local). When an explicit allowedOrigins list is
+ *     configured, matching is exact — the any-port-localhost convenience is off,
+ *     so a localhost peer on an unlisted port must be added to be accepted.
 *   - Bearer token: when RVAGENT_HTTP_TOKEN is set, requests must carry
 *     Authorization: Bearer <token>; missing/wrong tokens → 401.
+ *   - Body cap: request bodies over 1 MiB are rejected with 413 (the
+ *     unbounded-buffering DoS from the pre-ADR-264 scaffold).
 *   - Bind address: defaults to 127.0.0.1 per MCP spec security requirement.
 *     Set RVAGENT_HTTP_HOST=0.0.0.0 only for intentional fleet deployment.
 *
 * Usage:
 *   import { createHttpTransport } from './http-transport.js';
- *   const { server: httpServer, transport } = await createHttpTransport(mcpServer);
+ *   const { httpServer } = await createHttpTransport(() => buildServer(config));
 *   // httpServer is a node:http.Server — call httpServer.close() to shut down.
 */

 import { createServer, type Server as HttpServer, type IncomingMessage, type ServerResponse } from "node:http";
 import { randomUUID } from "node:crypto";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import type { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js";

+export type McpServerFactory = () => McpServer;
+
 export interface HttpTransportOptions {
  /** TCP host to bind (default: 127.0.0.1). */
  host?: string;
@@ -32,8 +46,8 @@ export interface HttpTransportOptions {
  port?: number;
  /**
   * Allowed Origin header values. Requests with an Origin not in this list
-   * are rejected with 403. Use '*' to disable Origin validation entirely
-   * (not recommended outside of local-dev flags).
+   * (and not a localhost origin) are rejected with 403. Use '*' to disable
+   * Origin validation entirely (not recommended outside of local-dev flags).
   */
  allowedOrigins?: string[];
  /**
@@ -42,32 +56,51 @@ export interface HttpTransportOptions {
   * Defaults to process.env.RVAGENT_HTTP_TOKEN (undefined = auth disabled).
   */
  bearerToken?: string;
+  /** Maximum accepted request body size in bytes (default: 1 MiB). */
+  maxBodyBytes?: number;
+  /**
+   * Maximum number of concurrent live sessions (default: 64). When a new
+   * `initialize` arrives at the cap, the oldest-idle session is evicted (its
+   * transport closed) to make room — bounds memory against a flaky client that
+   * loops `initialize` or a malicious localhost peer (ADR-264 F7).
+   */
+  maxSessions?: number;
+  /**
+   * Idle time-to-live for a session in ms (default: 5 min). Sessions with no
+   * request activity for longer than this are swept and closed.
+   */
+  sessionIdleMs?: number;
+  /** How often the idle-session sweeper runs, in ms (default: 60 s). */
+  sweepIntervalMs?: number;
 }

 export interface HttpTransportResult {
  /** The raw Node.js HTTP server — call .close() to shut down. */
  httpServer: HttpServer;
-  /** The MCP Streamable HTTP transport instance wired to the MCP server. */
-  transport: StreamableHTTPServerTransport;
+  /** Live sessions keyed by session id (exposed for tests/observability). */
+  sessions: Map<string, StreamableHTTPServerTransport>;
  /** The bound address string (e.g. "http://127.0.0.1:3001"). */
  boundAddress: string;
 }

 const DEFAULT_HOST = "127.0.0.1";
 const DEFAULT_PORT = 3001;
-const LOCALHOST_ORIGINS = new Set([
-  "http://localhost",
-  "http://127.0.0.1",
-  "https://localhost",
-  "https://127.0.0.1",
-]);
+const DEFAULT_MAX_BODY_BYTES = 1024 * 1024;
+const DEFAULT_MAX_SESSIONS = 64;
+const DEFAULT_SESSION_IDLE_MS = 5 * 60 * 1000;
+const DEFAULT_SWEEP_INTERVAL_MS = 60 * 1000;
+const LOCAL_HOSTNAMES = new Set(["localhost", "127.0.0.1", "[::1]"]);

 /**
 * Validate Origin header against the allowlist.
 * Returns true if the request should be allowed, false if it should be rejected.
 *
- * An absent Origin header is allowed (same-origin non-browser requests, curl, etc.).
- * A present Origin that is not in the allowlist is rejected.
+ * An absent Origin header is allowed (same-origin non-browser requests, curl,
+ * etc.). When NO explicit allowlist was configured (empty list), a localhost
+ * origin is allowed on any port as a convenience — real browser origins carry
+ * ports (ADR-264 F7). When an explicit allowlist IS configured, matching is
+ * exact: the any-port-localhost shortcut is disabled so an operator who pins an
+ * allowlist actually gets it (a looped-back peer on an unlisted port is denied).
 */
 export function isOriginAllowed(
  origin: string | undefined,
@@ -75,76 +108,222 @@ export function isOriginAllowed(
 ): boolean {
  if (origin === undefined) return true; // no Origin = not a cross-origin browser request
  if (allowedOrigins.includes("*")) return true;
-  return allowedOrigins.some((o) => o === origin);
+  if (allowedOrigins.includes(origin)) return true;
+  // Explicit allowlist ⇒ exact matching only; skip the localhost convenience.
+  if (allowedOrigins.length > 0) return false;
+  try {
+    const u = new URL(origin);
+    return (
+      (u.protocol === "http:" || u.protocol === "https:") &&
+      LOCAL_HOSTNAMES.has(u.hostname === "::1" ? "[::1]" : u.hostname)
+    );
+  } catch {
+    return false;
+  }
+}
+
+/** Read a request body with a hard size cap; null = payload too large. */
+function readBody(
+  req: IncomingMessage,
+  maxBytes: number
+): Promise<string | null> {
+  return new Promise((resolve, reject) => {
+    let size = 0;
+    let tooLarge = false;
+    const chunks: Buffer[] = [];
+    req.on("data", (chunk: Buffer) => {
+      if (tooLarge) return; // keep draining so the 413 response can flush
+      size += chunk.length;
+      if (size > maxBytes) {
+        tooLarge = true;
+        chunks.length = 0;
+        resolve(null);
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on("end", () => {
+      if (!tooLarge) resolve(Buffer.concat(chunks).toString("utf8"));
+    });
+    req.on("error", reject);
+  });
+}
+
+function json(res: ServerResponse, status: number, body: object): void {
+  res.writeHead(status, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(body));
 }

 /**
- * Build and wire a Streamable HTTP transport to the provided MCP server.
- * Returns the Node.js HTTP server (not yet listening) plus the transport.
+ * Build the HTTP server around a per-session MCP transport map.
+ * Returns the Node.js HTTP server (not yet listening) plus the session map.
 * Call httpServer.listen(port, host) or rely on createHttpTransport which
 * does that for you.
 */
 export function buildHttpApp(
-  mcpServer: McpServer,
+  serverFactory: McpServerFactory,
  opts: HttpTransportOptions = {}
-): { httpServer: HttpServer; transport: StreamableHTTPServerTransport } {
-  const allowedOrigins: string[] = opts.allowedOrigins ?? [
-    ...LOCALHOST_ORIGINS,
-  ];
+): { httpServer: HttpServer; sessions: Map<string, StreamableHTTPServerTransport> } {
+  const allowedOrigins: string[] = opts.allowedOrigins ?? [];
  const bearerToken = opts.bearerToken ?? process.env["RVAGENT_HTTP_TOKEN"];
+  const maxBodyBytes = opts.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+  const maxSessions = opts.maxSessions ?? DEFAULT_MAX_SESSIONS;
+  const sessionIdleMs = opts.sessionIdleMs ?? DEFAULT_SESSION_IDLE_MS;
+  const sweepIntervalMs = opts.sweepIntervalMs ?? DEFAULT_SWEEP_INTERVAL_MS;
+  const sessions = new Map<string, StreamableHTTPServerTransport>();
+  // lastSeen tracks per-session request activity so the sweeper and the
+  // oldest-idle eviction can bound the session map (ADR-264 F7).
+  const lastSeen = new Map<string, number>();

-  const transport = new StreamableHTTPServerTransport({
-    sessionIdGenerator: () => randomUUID(),
-  });
+  /** Mark a session as freshly used. */
+  function touch(sessionId: string): void {
+    lastSeen.set(sessionId, Date.now());
+  }

-  const httpServer = createServer(
-    (req: IncomingMessage, res: ServerResponse) => {
-      // ── Origin validation ────────────────────────────────────────────────
+  /** Close a session's transport and drop it from the bookkeeping maps. */
+  function closeSession(id: string): void {
+    const transport = sessions.get(id);
+    sessions.delete(id);
+    lastSeen.delete(id);
+    if (transport) {
+      try {
+        void transport.close(); // onclose is idempotent against the maps above
+      } catch {
+        /* best-effort: a half-open transport must not block eviction */
+      }
+    }
+  }
+
+  /** Evict the session that has been idle longest — called when at capacity. */
+  function evictOldestIdle(): void {
+    let oldestId: string | undefined;
+    let oldestSeen = Infinity;
+    for (const [id, seen] of lastSeen) {
+      if (seen < oldestSeen) {
+        oldestSeen = seen;
+        oldestId = id;
+      }
+    }
+    if (oldestId !== undefined) closeSession(oldestId);
+  }
+
+  /** Periodic sweep: close sessions idle beyond sessionIdleMs. */
+  function sweepIdleSessions(): void {
+    const now = Date.now();
+    for (const [id, seen] of lastSeen) {
+      if (now - seen > sessionIdleMs) closeSession(id);
+    }
+  }
+  const sweepTimer = setInterval(sweepIdleSessions, sweepIntervalMs);
+  sweepTimer.unref(); // never keep the process alive just to sweep
+
+  const httpServer = createServer((req: IncomingMessage, res: ServerResponse) => {
+    void (async () => {
+      // ── Origin validation ──────────────────────────────────────────────
      const origin = req.headers["origin"] as string | undefined;
      if (!isOriginAllowed(origin, allowedOrigins)) {
-        res.writeHead(403, { "Content-Type": "application/json" });
-        res.end(JSON.stringify({ error: "Forbidden: cross-origin request rejected" }));
+        json(res, 403, { error: "Forbidden: cross-origin request rejected" });
        return;
      }

-      // ── Bearer token auth ────────────────────────────────────────────────
+      // ── Bearer token auth ──────────────────────────────────────────────
      if (bearerToken !== undefined && bearerToken !== "") {
        const authHeader = req.headers["authorization"] as string | undefined;
        const supplied = authHeader?.startsWith("Bearer ")
          ? authHeader.slice("Bearer ".length)
          : undefined;
        if (supplied !== bearerToken) {
-          res.writeHead(401, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ error: "Unauthorized: missing or invalid bearer token" }));
+          json(res, 401, { error: "Unauthorized: missing or invalid bearer token" });
          return;
        }
      }

-      // ── Route: POST /mcp ─────────────────────────────────────────────────
-      if (req.method === "POST" && req.url === "/mcp") {
-        let body = "";
-        req.on("data", (chunk: Buffer) => { body += chunk.toString(); });
-        req.on("end", () => {
-          let parsed: unknown;
-          try {
-            parsed = JSON.parse(body);
-          } catch {
-            res.writeHead(400, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({ error: "Bad Request: invalid JSON body" }));
-            return;
-          }
-          void transport.handleRequest(req, res, parsed);
-        });
+      // ── Route: /mcp ────────────────────────────────────────────────────
+      if (req.url !== "/mcp") {
+        json(res, 404, { error: "Not found. MCP endpoint: /mcp" });
        return;
      }

-      // ── Fallback ─────────────────────────────────────────────────────────
-      res.writeHead(404, { "Content-Type": "application/json" });
-      res.end(JSON.stringify({ error: "Not found. MCP endpoint: POST /mcp" }));
-    }
-  );
+      const sessionId = req.headers["mcp-session-id"] as string | undefined;

-  return { httpServer, transport };
+      if (req.method === "POST") {
+        const body = await readBody(req, maxBodyBytes);
+        if (body === null) {
+          json(res, 413, { error: `Payload too large (max ${maxBodyBytes} bytes)` });
+          return;
+        }
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(body);
+        } catch {
+          json(res, 400, { error: "Bad Request: invalid JSON body" });
+          return;
+        }
+
+        // Existing session → route to its transport.
+        if (sessionId !== undefined) {
+          const transport = sessions.get(sessionId);
+          if (!transport) {
+            json(res, 404, { error: `Unknown session "${sessionId}"` });
+            return;
+          }
+          touch(sessionId);
+          await transport.handleRequest(req, res, parsed);
+          return;
+        }
+
+        // New session: must be an initialize request (ADR-264 F7 — one
+        // transport + one MCP Server per session).
+        if (!isInitializeRequest(parsed)) {
+          json(res, 400, {
+            error: "Bad Request: no mcp-session-id and not an initialize request",
+          });
+          return;
+        }
+        // Bound the session map: at capacity, reclaim the oldest-idle slot
+        // before minting a new session (ADR-264 F7).
+        if (sessions.size >= maxSessions) evictOldestIdle();
+        const transport = new StreamableHTTPServerTransport({
+          sessionIdGenerator: () => randomUUID(),
+          onsessioninitialized: (id: string) => {
+            sessions.set(id, transport);
+            touch(id);
+          },
+        });
+        transport.onclose = () => {
+          if (transport.sessionId !== undefined) {
+            sessions.delete(transport.sessionId);
+            lastSeen.delete(transport.sessionId);
+          }
+        };
+        const mcpServer = serverFactory();
+        await mcpServer.connect(transport as Parameters<typeof mcpServer.connect>[0]);
+        await transport.handleRequest(req, res, parsed);
+        return;
+      }
+
+      // GET (SSE stream) / DELETE (session termination) — session-scoped.
+      if (req.method === "GET" || req.method === "DELETE") {
+        const transport = sessionId !== undefined ? sessions.get(sessionId) : undefined;
+        if (!transport) {
+          json(res, 400, { error: "Bad Request: missing or unknown mcp-session-id" });
+          return;
+        }
+        if (sessionId !== undefined) touch(sessionId);
+        await transport.handleRequest(req, res);
+        return;
+      }
+
+      json(res, 405, { error: "Method not allowed. Use POST/GET/DELETE on /mcp" });
+    })().catch(() => {
+      if (!res.headersSent) json(res, 500, { error: "Internal server error" });
+      else res.end();
+    });
+  });
+
+  httpServer.on("close", () => clearInterval(sweepTimer));
+
+  return { httpServer, sessions };
 }

 /**
@@ -152,19 +331,13 @@ export function buildHttpApp(
 * is bound and listening.
 */
 export async function createHttpTransport(
-  mcpServer: McpServer,
+  serverFactory: McpServerFactory,
  opts: HttpTransportOptions = {}
 ): Promise<HttpTransportResult> {
  const host = opts.host ?? process.env["RVAGENT_HTTP_HOST"] ?? DEFAULT_HOST;
  const port = opts.port ?? Number(process.env["RVAGENT_HTTP_PORT"] ?? DEFAULT_PORT);

-  const { httpServer, transport } = buildHttpApp(mcpServer, opts);
-
-  // Wire MCP server to the transport only after the HTTP server is built.
-  // Cast needed: StreamableHTTPServerTransport implements Transport but
-  // exactOptionalPropertyTypes causes a false incompatibility on optional
-  // callback properties; the cast is safe — the SDK types are consistent.
-  await mcpServer.connect(transport as Parameters<typeof mcpServer.connect>[0]);
+  const { httpServer, sessions } = buildHttpApp(serverFactory, opts);

  await new Promise<void>((resolve, reject) => {
    httpServer.once("error", reject);
@@ -173,7 +346,7 @@ export async function createHttpTransport(

  return {
    httpServer,
-    transport,
+    sessions,
    boundAddress: `http://${host}:${port}`,
  };
 }
@@ -1,29 +1,39 @@
 #!/usr/bin/env node
 /**
- * @ruv/ruview-mcp — RuView MCP Server
+ * @ruvnet/rvagent — RuView MCP Server
 *
 * Exposes RuView's WiFi-DensePose sensing capabilities as Model Context Protocol
 * (MCP) tools that Claude Code, Cursor, Codex, and other MCP-compatible agents
 * can call directly.
 *
- * Tools exposed:
- *   ruview_csi_latest    — pull the latest CSI window from the sensing-server
- *   ruview_pose_infer    — single-shot 17-keypoint pose estimation
- *   ruview_count_infer   — single-shot person count with confidence interval
- *   ruview_registry_list — list cogs from the Cognitum edge registry (ADR-102)
- *   ruview_train_count   — kick off a count-cog training run (returns job ID)
- *   ruview_job_status    — poll a background training job
+ * Transports (ADR-264 O3):
+ *   stdio (default)      node dist/index.js
+ *   Streamable HTTP      RVAGENT_HTTP_PORT=3001 node dist/index.js
+ *                        (127.0.0.1-bound, Origin-gated, optional bearer token —
+ *                        see http-transport.ts for the security model)
 *
- * Usage:
- *   node dist/index.js                   # stdio transport (default)
- *   RUVIEW_SENSING_SERVER_URL=http://cognitum-v0:3000 node dist/index.js
+ * Tool naming (ADR-264 O4): canonical names are underscore-form
+ * (host tool-name regexes commonly enforce ^[a-zA-Z0-9_-]{1,64}$). The
+ * pre-ADR-264 dotted names (ruview.bfld.last_scan, …) remain callable as
+ * router-only aliases for one deprecation cycle; tools/list advertises the
+ * underscore form only.
+ *
+ * Validation (ADR-264 O5): each tool declares ONE Zod schema. The CallTool
+ * gate parses exactly once and hands the typed result to the handler; the
+ * advertised JSON Schema is generated from the same Zod source, so what is
+ * advertised is what is enforced.
 *
 * To register with Claude Code:
- *   claude mcp add ruview -- node /path/to/tools/ruview-mcp/dist/index.js
+ *   claude mcp add ruview -- npx -y @ruvnet/rvagent
 *
- * See ADR-104 for the full design rationale and security model.
+ * See ADR-104 for the original design rationale and ADR-264 for the npm
+ * deep-review this layout implements.
 */

+import { createRequire } from "node:module";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { argv } from "node:process";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
@@ -32,6 +42,8 @@ import {
  McpError,
  ErrorCode,
 } from "@modelcontextprotocol/sdk/types.js";
+import type { z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";

 import { loadConfig } from "./config.js";
 import { csiLatestSchema, csiLatest } from "./tools/csi-latest.js";
@@ -44,40 +56,51 @@ import {
  jobStatusSchema,
  jobStatus,
 } from "./tools/train-count.js";
-import { TOOL_INPUT_SCHEMAS } from "./schemas/index.js";
-import { bfldLastScan } from "./tools/bfld-last-scan.js";
-import { bfldSubscribe } from "./tools/bfld-subscribe.js";
-import { presenceNow } from "./tools/presence-now.js";
-import { vitalsGetBreathing } from "./tools/vitals-get-breathing.js";
-import { vitalsGetHeartRate } from "./tools/vitals-get-heart-rate.js";
-import { vitalsGetAll } from "./tools/vitals-get-all.js";
+import { bfldLastScanSchema, bfldLastScan } from "./tools/bfld-last-scan.js";
+import { bfldSubscribeSchema, bfldSubscribe } from "./tools/bfld-subscribe.js";
+import { presenceNowSchema, presenceNow } from "./tools/presence-now.js";
+import {
+  vitalsGetBreathingSchema,
+  vitalsGetBreathing,
+} from "./tools/vitals-get-breathing.js";
+import {
+  vitalsGetHeartRateSchema,
+  vitalsGetHeartRate,
+} from "./tools/vitals-get-heart-rate.js";
+import { vitalsGetAllSchema, vitalsGetAll } from "./tools/vitals-get-all.js";
+// NOTE: ./http-transport.js is imported lazily in main() — it chain-loads the
+// SDK's streamableHttp module (~48 ms MEASURED), which the default stdio path
+// never uses.

-const PACKAGE_VERSION = "0.1.0";
+// Single-source the version from package.json (ADR-264 O8/ADR-265 D3).
+const require = createRequire(import.meta.url);
+const PACKAGE_VERSION: string = (
+  require("../package.json") as { version: string }
+).version;
 const SERVER_NAME = "rvagent";

 // ── Tool registry ──────────────────────────────────────────────────────────

-const TOOLS = [
+type RuviewConfig = ReturnType<typeof loadConfig>;
+
+interface ToolDef {
+  name: string;
+  description: string;
+  /** The single validation source; the advertised JSON Schema derives from it. */
+  schema: z.ZodTypeAny;
+  handler: (parsedArgs: unknown, config: RuviewConfig) => Promise<object>;
+}
+
+export const TOOLS: ToolDef[] = [
  {
    name: "ruview_csi_latest",
    description:
      "Pull the latest CSI window from a running wifi-densepose-sensing-server. " +
      "Returns 56-subcarrier × 20-frame amplitude/phase arrays suitable for " +
      "downstream inference or research analysis.",
-    inputSchema: {
-      type: "object" as const,
-      properties: {
-        sensing_server_url: {
-          type: "string",
-          description:
-            "Base URL of the sensing-server (default: RUVIEW_SENSING_SERVER_URL or http://localhost:3000).",
-        },
-      },
-    },
-    handler: async (args: unknown, config: ReturnType<typeof loadConfig>) => {
-      const input = csiLatestSchema.parse(args);
-      return csiLatest(input, config);
-    },
+    schema: csiLatestSchema,
+    handler: (args, config) =>
+      csiLatest(args as Parameters<typeof csiLatest>[0], config),
  },
  {
    name: "ruview_pose_infer",
@@ -86,23 +109,9 @@ const TOOLS = [
      "cog-pose-estimation Cog binary (ADR-101). Accepts a CSI window JSON file " +
      "or uses the live sensing-server if no window is provided. " +
      "Returns [{keypoints: [[x,y]×17], confidence}] per detected person.",
-    inputSchema: {
-      type: "object" as const,
-      properties: {
-        window_path: {
-          type: "string",
-          description: "Path to a CSI window JSON file. Omit to use the live sensing-server.",
-        },
-        cog_binary: {
-          type: "string",
-          description: "Path to cog-pose-estimation binary.",
-        },
-      },
-    },
-    handler: async (args: unknown, config: ReturnType<typeof loadConfig>) => {
-      const input = poseInferSchema.parse(args);
-      return poseInfer(input, config);
-    },
+    schema: poseInferSchema,
+    handler: (args, config) =>
+      poseInfer(args as Parameters<typeof poseInfer>[0], config),
  },
  {
    name: "ruview_count_infer",
@@ -110,29 +119,9 @@ const TOOLS = [
      "Run a single-shot person-count inference using the cog-person-count Cog " +
      "binary (ADR-103). Returns {count, confidence, count_p95_low, count_p95_high} " +
      "with a Stoer-Wagner multi-node fusion upper bound when multiple nodes are active.",
-    inputSchema: {
-      type: "object" as const,
-      properties: {
-        window_path: {
-          type: "string",
-          description: "Path to a CSI window JSON file. Omit to use the live sensing-server.",
-        },
-        cog_binary: {
-          type: "string",
-          description: "Path to cog-person-count binary.",
-        },
-        max_persons: {
-          type: "integer",
-          minimum: 1,
-          maximum: 7,
-          description: "Upper bound on person count (1–7). Default: 7.",
-        },
-      },
-    },
-    handler: async (args: unknown, config: ReturnType<typeof loadConfig>) => {
-      const input = countInferSchema.parse(args);
-      return countInfer(input, config);
-    },
+    schema: countInferSchema,
+    handler: (args, config) =>
+      countInfer(args as Parameters<typeof countInfer>[0], config),
  },
  {
    name: "ruview_registry_list",
@@ -140,33 +129,9 @@ const TOOLS = [
      "List cogs from the Cognitum edge module registry (ADR-102). " +
      "Fetches /api/v1/edge/registry from the sensing-server, which proxies the " +
      "canonical GCS catalog (105 cogs, 11 categories). Supports category filter and search.",
-    inputSchema: {
-      type: "object" as const,
-      properties: {
-        category: {
-          type: "string",
-          description:
-            "Filter by category: health, security, building, retail, industrial, " +
-            "research, ai, swarm, signal, network, developer.",
-        },
-        search: {
-          type: "string",
-          description: "Search substring matched against cog id and name (case-insensitive).",
-        },
-        refresh: {
-          type: "boolean",
-          description: "Bypass the 1-hour registry cache.",
-        },
-        sensing_server_url: {
-          type: "string",
-          description: "Override the sensing-server URL.",
-        },
-      },
-    },
-    handler: async (args: unknown, config: ReturnType<typeof loadConfig>) => {
-      const input = registryListSchema.parse(args);
-      return registryList(input, config);
-    },
+    schema: registryListSchema,
+    handler: (args, config) =>
+      registryList(args as Parameters<typeof registryList>[0], config),
  },
  {
    name: "ruview_train_count",
@@ -174,211 +139,139 @@ const TOOLS = [
      "Kick off a cog-person-count training run using the Candle GPU trainer " +
      "(ADR-103). The paired JSONL file provides CSI windows + camera-derived " +
      "person-count labels. Returns a job_id to poll with ruview_job_status.",
-    inputSchema: {
-      type: "object" as const,
-      required: ["paired_jsonl"],
-      properties: {
-        paired_jsonl: {
-          type: "string",
-          description:
-            "Path to the paired JSONL training file (produced by scripts/align-ground-truth.js).",
-        },
-        epochs: {
-          type: "integer",
-          minimum: 1,
-          maximum: 10000,
-          description: "Training epochs (default: 400).",
-        },
-        learning_rate: {
-          type: "number",
-          description: "Initial learning rate (default: 0.001).",
-        },
-        output_dir: {
-          type: "string",
-          description:
-            "Directory for model artifacts (default: v2/crates/cog-person-count/cog/artifacts/).",
-        },
-      },
-    },
-    handler: async (args: unknown, config: ReturnType<typeof loadConfig>) => {
-      const input = trainCountSchema.parse(args);
-      return trainCount(input, config);
-    },
+    schema: trainCountSchema,
+    handler: (args, config) =>
+      trainCount(args as Parameters<typeof trainCount>[0], config),
  },
  {
    name: "ruview_job_status",
    description:
      "Poll the status of a background training job started by ruview_train_count. " +
      "Returns {status, epochs_done, epochs_total, recent_log} for the given job_id.",
-    inputSchema: {
-      type: "object" as const,
-      required: ["job_id"],
-      properties: {
-        job_id: {
-          type: "string",
-          description: "UUID returned by ruview_train_count.",
-        },
-      },
-    },
-    handler: async (args: unknown, config: ReturnType<typeof loadConfig>) => {
-      const input = jobStatusSchema.parse(args);
-      return jobStatus(input, config);
-    },
+    schema: jobStatusSchema,
+    handler: (args, config) =>
+      jobStatus(args as Parameters<typeof jobStatus>[0], config),
  },
-  // ── ADR-124 BFLD tools (Phase 4 Refinement) ──────────────────────────────
+  // ── ADR-124 BFLD tools (Phase 4 Refinement; underscore names per ADR-264) ─
  {
-    name: "ruview.bfld.last_scan",
+    name: "ruview_bfld_last_scan",
    description:
      "Return the most recent BFLD scan result for a node (ADR-118/ADR-121). " +
      "Fields: node_id, identity_risk_score [0,1], privacy_class, n_frames, timestamp_ms. " +
      "Proxied from sensing-server GET /api/v1/bfld/<node_id>/last_scan which aggregates " +
      "the MQTT state topics ruview/<node_id>/bfld/* (ADR-122 §2.2).",
-    inputSchema: {
-      type: "object" as const,
-      properties: {
-        node_id: {
-          type: "string",
-          description: "Target node id. Omit to use the single active node.",
-        },
-        sensing_server_url: {
-          type: "string",
-          description: "Override sensing-server URL for this call only.",
-        },
-      },
-    },
-    handler: async (args: unknown, config: ReturnType<typeof loadConfig>) => {
-      return bfldLastScan(args as Parameters<typeof bfldLastScan>[0], config);
-    },
+    schema: bfldLastScanSchema,
+    handler: (args, config) =>
+      bfldLastScan(args as Parameters<typeof bfldLastScan>[0], config),
  },
  {
-    name: "ruview.bfld.subscribe",
+    name: "ruview_bfld_subscribe",
    description:
      "Subscribe to BFLD events on ruview/<node_id>/bfld/* for duration_s seconds (ADR-122). " +
      "Returns {ok, subscription_id, expires_at, topic}. When the sensing-server is unreachable, " +
      "returns a synthetic envelope with ok:false,warn:true so the caller can distinguish " +
      "a network error from an invalid request.",
-    inputSchema: {
-      type: "object" as const,
-      required: ["duration_s"],
-      properties: {
-        node_id: {
-          type: "string",
-          description: "Target node id. Omit to use the single active node.",
-        },
-        duration_s: {
-          type: "number",
-          minimum: 0,
-          maximum: 3600,
-          description: "Subscription duration in seconds (max 3600).",
-        },
-        sensing_server_url: {
-          type: "string",
-          description: "Override sensing-server URL for this call only.",
-        },
-      },
-    },
-    handler: async (args: unknown, config: ReturnType<typeof loadConfig>) => {
-      return bfldSubscribe(args as Parameters<typeof bfldSubscribe>[0], config);
-    },
+    schema: bfldSubscribeSchema,
+    handler: (args, config) =>
+      bfldSubscribe(args as Parameters<typeof bfldSubscribe>[0], config),
  },
-  // ── ADR-124 Presence + Vitals tools (Phase 4 Refinement iter 5) ──────────
+  // ── ADR-124 Presence + Vitals tools ───────────────────────────────────────
  {
-    name: "ruview.presence.now",
+    name: "ruview_presence_now",
    description:
      "Return current occupancy for a node: present, n_persons, confidence, timestamp_ms. " +
      "Wraps EdgeVitalsMessage.presence + n_persons (ADR-124 §4.1, ws.py:74-88).",
-    inputSchema: {
-      type: "object" as const,
-      properties: {
-        node_id: { type: "string", description: "Target node id." },
-        sensing_server_url: { type: "string", description: "Override sensing-server URL." },
-      },
-    },
-    handler: async (args: unknown, config: ReturnType<typeof loadConfig>) =>
+    schema: presenceNowSchema,
+    handler: (args, config) =>
      presenceNow(args as Parameters<typeof presenceNow>[0], config),
  },
  {
-    name: "ruview.vitals.get_breathing",
+    name: "ruview_vitals_get_breathing",
    description:
      "Return breathing rate for a node: breathing_rate_bpm (null if unavailable), " +
      "confidence, timestamp_ms. Wraps EdgeVitalsMessage.breathing_rate_bpm (ws.py:82).",
-    inputSchema: {
-      type: "object" as const,
-      properties: {
-        node_id: { type: "string", description: "Target node id." },
-        window_s: { type: "number", description: "Averaging window in seconds (max 300)." },
-        sensing_server_url: { type: "string", description: "Override sensing-server URL." },
-      },
-    },
-    handler: async (args: unknown, config: ReturnType<typeof loadConfig>) =>
+    schema: vitalsGetBreathingSchema,
+    handler: (args, config) =>
      vitalsGetBreathing(args as Parameters<typeof vitalsGetBreathing>[0], config),
  },
  {
-    name: "ruview.vitals.get_heart_rate",
+    name: "ruview_vitals_get_heart_rate",
    description:
      "Return heart rate for a node: heartrate_bpm (null if unavailable), " +
      "confidence, timestamp_ms. Wraps EdgeVitalsMessage.heartrate_bpm (ws.py:83).",
-    inputSchema: {
-      type: "object" as const,
-      properties: {
-        node_id: { type: "string", description: "Target node id." },
-        window_s: { type: "number", description: "Averaging window in seconds (max 300)." },
-        sensing_server_url: { type: "string", description: "Override sensing-server URL." },
-      },
-    },
-    handler: async (args: unknown, config: ReturnType<typeof loadConfig>) =>
+    schema: vitalsGetHeartRateSchema,
+    handler: (args, config) =>
      vitalsGetHeartRate(args as Parameters<typeof vitalsGetHeartRate>[0], config),
  },
  {
-    name: "ruview.vitals.get_all",
+    name: "ruview_vitals_get_all",
    description:
      "Return the full EdgeVitalsMessage for a node (all fields except raw): " +
      "presence, n_persons, confidence, breathing_rate_bpm, heartrate_bpm, motion, zone_id. " +
      "Full surface of ws.py:74-88.",
-    inputSchema: {
-      type: "object" as const,
-      properties: {
-        node_id: { type: "string", description: "Target node id." },
-        sensing_server_url: { type: "string", description: "Override sensing-server URL." },
-      },
-    },
-    handler: async (args: unknown, config: ReturnType<typeof loadConfig>) =>
+    schema: vitalsGetAllSchema,
+    handler: (args, config) =>
      vitalsGetAll(args as Parameters<typeof vitalsGetAll>[0], config),
  },
-] as const;
+];

-// ── Server bootstrap ────────────────────────────────────────────────────────
+/**
+ * Pre-ADR-264 dotted tool names, accepted at call time for one deprecation
+ * cycle. Router-only: tools/list never advertises these.
+ */
+export const TOOL_ALIASES: Record<string, string> = {
+  "ruview.bfld.last_scan": "ruview_bfld_last_scan",
+  "ruview.bfld.subscribe": "ruview_bfld_subscribe",
+  "ruview.presence.now": "ruview_presence_now",
+  "ruview.vitals.get_breathing": "ruview_vitals_get_breathing",
+  "ruview.vitals.get_heart_rate": "ruview_vitals_get_heart_rate",
+  "ruview.vitals.get_all": "ruview_vitals_get_all",
+};

-async function main(): Promise<void> {
-  const config = loadConfig();
+/**
+ * Advertised JSON Schema, generated from the Zod source (ADR-264 O5).
+ * Memoized: schemas are static for the process lifetime, and tools/list is
+ * called once per session (per HTTP session under the session-per-server
+ * model) — no point re-walking the Zod tree each time.
+ */
+const jsonSchemaCache = new Map<string, object>();
+export function toolInputJsonSchema(def: ToolDef): object {
+  const cached = jsonSchemaCache.get(def.name);
+  if (cached !== undefined) return cached;
+  const raw = zodToJsonSchema(def.schema, { $refStrategy: "none" }) as Record<
+    string,
+    unknown
+  >;
+  delete raw["$schema"];
+  jsonSchemaCache.set(def.name, raw);
+  return raw;
+}

+// ── Server factory ──────────────────────────────────────────────────────────
+
+/**
+ * Build a fully-wired MCP Server. A factory (not a singleton) because each
+ * Streamable-HTTP session needs its own Server instance (ADR-264 F7/O3).
+ */
+export function buildServer(config: RuviewConfig = loadConfig()): Server {
  const server = new Server(
-    {
-      name: SERVER_NAME,
-      version: PACKAGE_VERSION,
-    },
-    {
-      capabilities: {
-        tools: {},
-      },
-    }
+    { name: SERVER_NAME, version: PACKAGE_VERSION },
+    { capabilities: { tools: {} } }
  );

-  // List tools handler.
  server.setRequestHandler(ListToolsRequestSchema, () => ({
    tools: TOOLS.map((t) => ({
      name: t.name,
      description: t.description,
-      inputSchema: t.inputSchema,
+      inputSchema: toolInputJsonSchema(t),
    })),
  }));

-  // Call tool handler — uniform Zod validation gate (ADR-124 §3 Architecture).
-  // If TOOL_INPUT_SCHEMAS has a schema for the tool name, run safeParse first.
-  // Parse failures throw McpError(InvalidParams) so the client sees a typed
-  // JSON-RPC error rather than a wrapped string error.
+  // Call tool handler — the SINGLE Zod validation gate (ADR-264 O5): parse
+  // once, hand the typed result (with defaults applied) to the handler.
  server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const { name, arguments: args } = request.params;
+    const { name: rawName, arguments: args } = request.params;
+    const name = TOOL_ALIASES[rawName] ?? rawName;
    const tool = TOOLS.find((t) => t.name === name);

    if (!tool) {
@@ -388,7 +281,7 @@ async function main(): Promise<void> {
            type: "text" as const,
            text: JSON.stringify({
              ok: false,
-              error: `Unknown tool "${name}". Available tools: ${TOOLS.map((t) => t.name).join(", ")}`,
+              error: `Unknown tool "${rawName}". Available tools: ${TOOLS.map((t) => t.name).join(", ")}`,
            }),
          },
        ],
@@ -396,22 +289,16 @@ async function main(): Promise<void> {
      };
    }

-    // Schema validation gate — applies to all tools registered in TOOL_INPUT_SCHEMAS.
-    const schemaEntry = Object.prototype.hasOwnProperty.call(TOOL_INPUT_SCHEMAS, name)
-      ? TOOL_INPUT_SCHEMAS[name as keyof typeof TOOL_INPUT_SCHEMAS]
-      : undefined;
-    if (schemaEntry !== undefined) {
-      const parsed = schemaEntry.safeParse(args ?? {});
-      if (!parsed.success) {
-        throw new McpError(
-          ErrorCode.InvalidParams,
-          `Invalid arguments for tool "${name}": ${parsed.error.message}`
-        );
-      }
+    const parsed = tool.schema.safeParse(args ?? {});
+    if (!parsed.success) {
+      throw new McpError(
+        ErrorCode.InvalidParams,
+        `Invalid arguments for tool "${rawName}": ${parsed.error.message}`
+      );
    }

    try {
-      const result = await tool.handler(args ?? {}, config);
+      const result = await tool.handler(parsed.data, config);
      return {
        content: [
          {
@@ -438,18 +325,59 @@ async function main(): Promise<void> {
    }
  });

-  // Wire up stdio transport.
+  return server;
+}
+
+// ── Server bootstrap ────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  const config = loadConfig();
+
+  // stdio transport (default, always on).
+  const stdioServer = buildServer(config);
  const transport = new StdioServerTransport();
-  await server.connect(transport);
+  await stdioServer.connect(transport);
+
+  // Streamable HTTP transport — explicit opt-in only (ADR-264 O3). Lazily
+  // imported so the stdio path never pays the streamableHttp load cost.
+  const httpPort = process.env["RVAGENT_HTTP_PORT"];
+  let httpNote = "";
+  if (httpPort !== undefined && httpPort !== "") {
+    const { createHttpTransport } = await import("./http-transport.js");
+    const { boundAddress } = await createHttpTransport(
+      () => buildServer(config),
+      { port: Number(httpPort) }
+    );
+    httpNote = ` HTTP: ${boundAddress}/mcp.`;
+  }

  // Log to stderr so it doesn't interfere with the MCP stdio protocol.
  process.stderr.write(
    `[@ruvnet/rvagent] Server v${PACKAGE_VERSION} started. ` +
-      `Sensing server: ${config.sensingServerUrl}\n`
+      `Sensing server: ${config.sensingServerUrl}.${httpNote}\n`
  );
 }

-main().catch((e) => {
-  process.stderr.write(`[ruview-mcp] Fatal: ${String(e)}\n`);
-  process.exit(1);
-});
+// CLI guard: boot the server only when this module is the entrypoint — invoked
+// as the `rvagent` / `ruview-mcp` bin or `node dist/index.js`. Importing it as a
+// library (`import { buildServer } from "@ruvnet/rvagent"`) must NOT side-effect
+// connect a StdioServerTransport to the consumer's stdin/stdout. Realpath both
+// sides because npm's bin shim is a symlink and passes a non-normalized,
+// possibly case-skewed argv[1] on Windows (mirrors harness/ruview/bin/cli.js).
+const invokedDirectly = (() => {
+  if (!argv[1]) return false;
+  try {
+    const a = realpathSync(argv[1]);
+    const b = realpathSync(fileURLToPath(import.meta.url));
+    return process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
+  } catch {
+    return false;
+  }
+})();
+
+if (invokedDirectly) {
+  main().catch((e) => {
+    process.stderr.write(`[ruview-mcp] Fatal: ${String(e)}\n`);
+    process.exit(1);
+  });
+}
@@ -17,7 +17,16 @@

 import { z } from "zod";
 import { randomUUID } from "node:crypto";
-import { mkdirSync, appendFileSync, openSync } from "node:fs";
+import {
+  mkdirSync,
+  appendFileSync,
+  openSync,
+  closeSync,
+  readFileSync,
+  writeFileSync,
+  statSync,
+  readSync,
+} from "node:fs";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import type { RuviewConfig, TrainJobResult, JobStatusResult } from "../types.js";
@@ -66,17 +75,101 @@ export const jobStatusSchema = z.object({

 export type JobStatusInput = z.infer<typeof jobStatusSchema>;

-// In-process job registry (survives for the lifetime of the MCP server process).
-// For a production implementation, persist to ~/.ruview/jobs/<id>.json.
-const jobRegistry = new Map<
-  string,
-  {
-    status: "queued" | "running" | "done" | "failed";
-    log_path: string;
-    queued_at: number;
-    epochs_total: number;
+interface JobRecord {
+  status: "queued" | "running" | "done" | "failed" | "unknown";
+  log_path: string;
+  queued_at: number;
+  epochs_total: number;
+  /**
+   * OS pid of the training child. Persisted so a later process (e.g. after an
+   * MCP server restart) can tell whether a job still marked 'running' actually
+   * outlived the process that spawned it (ADR-264 O6).
+   */
+  pid?: number | undefined;
+  /** Human-readable explanation attached during reconciliation (unknown state). */
+  reason?: string | undefined;
+}
+
+// In-process job registry, mirrored to <jobsDir>/<id>.json on every state
+// change so ruview_job_status survives an MCP server restart (ADR-264 O6).
+const jobRegistry = new Map<string, JobRecord>();
+
+function jobRecordPath(jobsDir: string, jobId: string): string {
+  return path.join(jobsDir, `${jobId}.json`);
+}
+
+function persistJob(jobsDir: string, jobId: string, record: JobRecord): void {
+  try {
+    writeFileSync(
+      jobRecordPath(jobsDir, jobId),
+      JSON.stringify({ job_id: jobId, ...record }, null, 2)
+    );
+  } catch {
+    // Persistence is best-effort; the in-memory record still serves this process.
  }
->();
+}
+
+function loadPersistedJob(jobsDir: string, jobId: string): JobRecord | undefined {
+  try {
+    const raw = JSON.parse(readFileSync(jobRecordPath(jobsDir, jobId), "utf8")) as
+      Partial<JobRecord>;
+    if (typeof raw.log_path !== "string" || typeof raw.status !== "string") {
+      return undefined;
+    }
+    return {
+      status: raw.status,
+      log_path: raw.log_path,
+      queued_at: typeof raw.queued_at === "number" ? raw.queued_at : 0,
+      epochs_total: typeof raw.epochs_total === "number" ? raw.epochs_total : 0,
+      pid: typeof raw.pid === "number" ? raw.pid : undefined,
+      reason: typeof raw.reason === "string" ? raw.reason : undefined,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Is `pid` still a live process? `process.kill(pid, 0)` sends no signal but
+ * probes existence: ESRCH ⇒ gone; EPERM ⇒ alive but owned by another user
+ * (treated as alive so we never falsely reconcile a still-running job).
+ */
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return (e as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/**
+ * Scan log lines (tail) for the "# exit code: N" marker the child.on('close')
+ * handler appends. `found:false` means the process died without the marker —
+ * i.e. this server never saw the close (it restarted mid-run).
+ */
+function findExitMarker(lines: string[]): { found: boolean; code: number | null } {
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const m = /^# exit code: (-?\d+|null)$/.exec((lines[i] ?? "").trim());
+    if (m) return { found: true, code: m[1] === "null" ? null : Number(m[1]) };
+  }
+  return { found: false, code: null };
+}
+
+/** Read the last `maxLines` lines of a file without loading the whole log. */
+function tailLines(filePath: string, maxLines: number, maxBytes = 64 * 1024): string[] {
+  const size = statSync(filePath).size;
+  const start = Math.max(0, size - maxBytes);
+  const buf = Buffer.alloc(size - start);
+  const fd = openSync(filePath, "r");
+  try {
+    readSync(fd, buf, 0, buf.length, start);
+  } finally {
+    closeSync(fd);
+  }
+  const lines = buf.toString("utf8").split("\n");
+  return lines.slice(Math.max(0, lines.length - maxLines));
+}

 export async function trainCount(
  input: TrainCountInput,
@@ -92,13 +185,16 @@ export async function trainCount(
  const outputDir =
    input.output_dir ?? "v2/crates/cog-person-count/cog/artifacts";

-  // Record the job immediately so ruview_job_status can find it.
-  jobRegistry.set(jobId, {
+  // Record the job immediately so ruview_job_status can find it — in memory
+  // and on disk (survives server restarts, ADR-264 O6).
+  const record: JobRecord = {
    status: "queued",
    log_path: logPath,
    queued_at: queuedAt,
    epochs_total: input.epochs,
-  });
+  };
+  jobRegistry.set(jobId, record);
+  persistJob(logDir, jobId, record);

  // Write the header synchronously so the log file exists before spawn.
  const header = [
@@ -142,21 +238,29 @@ export async function trainCount(

  child.unref(); // Allow the MCP server process to exit without waiting for training.

-  const entry = jobRegistry.get(jobId);
-  if (entry) {
-    entry.status = "running";
-  }
+  // The child holds its own duplicates of the log fds; close the parent's
+  // copies immediately or every job leaks 2 fds for the server's lifetime
+  // (ADR-264 F6/O6).
+  closeSync(logFdOut);
+  closeSync(logFdErr);
+
+  // Record the child pid so a later process can reconcile a stale 'running'
+  // record after a server restart (child.pid is undefined only if spawn failed
+  // synchronously, in which case the 'error' handler flips status to 'failed').
+  record.pid = child.pid;
+  record.status = "running";
+  persistJob(logDir, jobId, record);

  child.on("error", (e) => {
    appendFileSync(logPath, `\n# ERROR: ${e.message}\n`);
-    const rec = jobRegistry.get(jobId);
-    if (rec) rec.status = "failed";
+    record.status = "failed";
+    persistJob(logDir, jobId, record);
  });

  child.on("close", (code) => {
    appendFileSync(logPath, `\n# exit code: ${code}\n`);
-    const rec = jobRegistry.get(jobId);
-    if (rec) rec.status = code === 0 ? "done" : "failed";
+    record.status = code === 0 ? "done" : "failed";
+    persistJob(logDir, jobId, record);
  });

  const result: TrainJobResult = {
@@ -178,24 +282,48 @@ export async function trainCount(

 export async function jobStatus(
  input: JobStatusInput,
-  _config: RuviewConfig
+  config: RuviewConfig
 ): Promise<object> {
-  const job = jobRegistry.get(input.job_id);
+  // Memory first, then the persisted record (survives server restarts).
+  let job = jobRegistry.get(input.job_id) ?? loadPersistedJob(config.jobsDir, input.job_id);
  if (!job) {
    return {
      ok: false,
-      error: `Job ${input.job_id} not found. ` +
-        "The MCP server may have restarted — check the log directory directly.",
+      error: `Job ${input.job_id} not found in this server or in ${config.jobsDir}.`,
    };
  }

-  // Read the last 20 lines of the log file.
+  // Reconcile a 'running' record whose owning process is gone. The status flip
+  // to done/failed lives only in the spawning process's child.on('close'/'error')
+  // handlers; if this server restarted mid-run, the record froze at 'running'
+  // (ADR-264 O6). When the pid is dead, recover the true outcome from the log's
+  // "# exit code: N" marker, else surface an honest 'unknown'.
+  if (job.status === "running" && typeof job.pid === "number" && !isProcessAlive(job.pid)) {
+    let tail: string[] = [];
+    try {
+      tail = tailLines(job.log_path, 40);
+    } catch {
+      /* log unreadable — treated as no marker below */
+    }
+    const marker = findExitMarker(tail);
+    const reconciled: JobRecord = { ...job };
+    if (marker.found) {
+      reconciled.status = marker.code === 0 ? "done" : "failed";
+      reconciled.reason = undefined;
+    } else {
+      reconciled.status = "unknown";
+      reconciled.reason =
+        "process gone, no exit marker — server likely restarted mid-run";
+    }
+    jobRegistry.set(input.job_id, reconciled);
+    persistJob(config.jobsDir, input.job_id, reconciled);
+    job = reconciled;
+  }
+
+  // Bounded tail read — never load a multi-GB training log wholesale.
  let recentLog: string[] = [];
  try {
-    const { readFileSync } = await import("node:fs");
-    const content = readFileSync(job.log_path, "utf8");
-    const lines = content.split("\n");
-    recentLog = lines.slice(Math.max(0, lines.length - 20));
+    recentLog = tailLines(job.log_path, 20);
  } catch {
    recentLog = ["(log not readable yet)"];
  }
@@ -206,6 +334,7 @@ export async function jobStatus(
    log_path: job.log_path,
    recent_log: recentLog,
    epochs_total: job.epochs_total,
+    ...(job.reason !== undefined ? { reason: job.reason } : {}),
  };

  return { ok: true, result };
@@ -115,7 +115,12 @@ export interface TrainJobResult {
 /** Output of ruview_job_status. */
 export interface JobStatusResult {
  job_id: string;
-  status: "queued" | "running" | "done" | "failed";
+  /**
+   * 'unknown' is only ever produced by post-restart reconciliation: a record
+   * frozen at 'running' whose owning process is gone and whose log carries no
+   * exit-code marker (see reason).
+   */
+  status: "queued" | "running" | "done" | "failed" | "unknown";
  progress_pct?: number | undefined;
  /** Most recent log lines (last 20). */
  recent_log: string[];
@@ -124,6 +129,8 @@ export interface JobStatusResult {
  epochs_done?: number | undefined;
  /** Total epochs scheduled. */
  epochs_total?: number | undefined;
+  /** Explanation attached when status was reconciled to 'unknown'. */
+  reason?: string | undefined;
 }

 // ── Vitals (ADR-124 §6 Python surface parity: ws.py:74-88) ───────────────
@@ -0,0 +1,49 @@
+/**
+ * ADR-264 F8/O7 — cog-binary detection must be architecture-aware.
+ *
+ * detectCogBinary() itself probes hardcoded /var/lib paths, so it is not
+ * cheaply testable without fs mocking. The bug it fixes, however, lives purely
+ * in the candidate ORDER, which cogBinaryCandidates() exposes as a pure,
+ * arch-injectable function — that is what we pin here.
+ */
+
+import { cogBinaryCandidates } from "../src/config.js";
+
+describe("cogBinaryCandidates()", () => {
+  it("probes -arm before -x86_64 on arm64 hosts", () => {
+    const c = cogBinaryCandidates("cog-person-count", "arm64");
+    const arm = c.findIndex((p) => p.endsWith("cog-person-count-arm"));
+    const x86 = c.findIndex((p) => p.endsWith("cog-person-count-x86_64"));
+    expect(arm).toBeGreaterThanOrEqual(0);
+    expect(x86).toBeGreaterThanOrEqual(0);
+    expect(arm).toBeLessThan(x86);
+  });
+
+  it("probes -x86_64 before -arm on x64 hosts", () => {
+    const c = cogBinaryCandidates("cog-person-count", "x64");
+    const arm = c.findIndex((p) => p.endsWith("cog-person-count-arm"));
+    const x86 = c.findIndex((p) => p.endsWith("cog-person-count-x86_64"));
+    expect(x86).toBeLessThan(arm);
+  });
+
+  it("defaults an unknown arch to the x86_64-first order", () => {
+    const c = cogBinaryCandidates("cog-pose-estimation", "riscv64");
+    const arm = c.findIndex((p) => p.endsWith("cog-pose-estimation-arm"));
+    const x86 = c.findIndex((p) => p.endsWith("cog-pose-estimation-x86_64"));
+    expect(x86).toBeLessThan(arm);
+  });
+
+  it("keeps the /usr/local/bin and bare-name PATH fallbacks last", () => {
+    const c = cogBinaryCandidates("cog-person-count", "arm64");
+    // The two arch builds come first; the /usr/local/bin fallback follows them.
+    expect(c[c.length - 1]).toBe("/usr/local/bin/cog-person-count");
+    expect(c).toHaveLength(3);
+  });
+
+  it("derives the id by stripping the cog- prefix once", () => {
+    const c = cogBinaryCandidates("cog-person-count", "x64");
+    expect(c[0]).toBe(
+      "/var/lib/cognitum/apps/person-count/cog-person-count-x86_64"
+    );
+  });
+});
@@ -59,7 +59,9 @@ async function startServer(
  basePort: number
 ): Promise<{ port: number; close: () => Promise<void> }> {
  const port = basePort + Math.floor(Math.random() * 100);
-  const { httpServer } = buildHttpApp(makeMockMcpServer(), opts);
+  // Factory, not instance: each Streamable-HTTP session gets its own MCP
+  // Server (ADR-264 F7/O3).
+  const { httpServer } = buildHttpApp(() => makeMockMcpServer(), opts);
  await new Promise<void>((resolve, reject) => {
    httpServer.once("error", reject);
    httpServer.listen(port, "127.0.0.1", () => resolve());
@@ -95,8 +97,34 @@ describe("isOriginAllowed()", () => {
    expect(isOriginAllowed("https://evil.example.com", ["*"])).toBe(true);
  });

-  it("is case-sensitive per RFC 6454", () => {
-    expect(isOriginAllowed("HTTP://localhost", allow)).toBe(false);
+  // ADR-264 F7: real browser origins carry ports — localhost must match on
+  // hostname, any port, even with an empty allowlist.
+  it("allows localhost origins on any port", () => {
+    expect(isOriginAllowed("http://localhost:5173", [])).toBe(true);
+    expect(isOriginAllowed("http://127.0.0.1:8080", [])).toBe(true);
+    expect(isOriginAllowed("https://localhost:3001", [])).toBe(true);
+  });
+
+  it("rejects non-local origins even with a localhost-looking prefix", () => {
+    expect(isOriginAllowed("http://localhost.evil.example.com", [])).toBe(false);
+    expect(isOriginAllowed("https://evil.example.com:443", [])).toBe(false);
+  });
+
+  // ADR-264 F7 hardening: an EXPLICIT allowlist means exact matching only. The
+  // any-port-localhost convenience applies solely to the empty-allowlist case,
+  // so an operator who pins an allowlist actually gets it.
+  it("with an explicit allowlist, rejects a localhost origin on an unlisted port", () => {
+    expect(isOriginAllowed("http://localhost:5173", allow)).toBe(false);
+    expect(isOriginAllowed("http://127.0.0.1:8080", allow)).toBe(false);
+  });
+
+  it("with an explicit allowlist, still accepts an exactly-listed localhost origin", () => {
+    expect(isOriginAllowed("http://localhost", allow)).toBe(true);
+    expect(isOriginAllowed("http://127.0.0.1", allow)).toBe(true);
+  });
+
+  it("is case-sensitive for non-local allowlist entries per RFC 6454", () => {
+    expect(isOriginAllowed("HTTPS://Partner.Example.com", ["https://partner.example.com"])).toBe(false);
  });
 });

@@ -165,3 +193,117 @@ describe("HTTP transport bearer-token auth gate", () => {
    expect(r.status).not.toBe(401);
  });
 });
+
+// ── 7. ADR-264 F7/O3 hardening: body cap + per-session routing ─────────────
+
+describe("HTTP transport session + body-cap hardening (ADR-264 F7)", () => {
+  let port: number;
+  let close: () => Promise<void>;
+
+  beforeAll(async () => {
+    const srv = await startServer({ allowedOrigins: ["*"], maxBodyBytes: 64 * 1024 }, 49600);
+    port = srv.port;
+    close = srv.close;
+  });
+
+  afterAll(async () => { await close(); });
+
+  it("rejects oversized request bodies with 413", async () => {
+    const huge = JSON.stringify({ jsonrpc: "2.0", id: 1, method: "x", params: { pad: "y".repeat(128 * 1024) } });
+    const r = await post(port, "/mcp", {}, huge);
+    expect(r.status).toBe(413);
+  });
+
+  it("rejects a non-initialize POST without a session id with 400 (never a shared transport)", async () => {
+    const r = await post(port, "/mcp", {}, MCP_BODY); // tools/list, no mcp-session-id
+    expect(r.status).toBe(400);
+    const body = JSON.parse(r.body) as Record<string, unknown>;
+    expect(body["error"]).toMatch(/initialize/i);
+  });
+
+  it("rejects a POST with an unknown session id with 404", async () => {
+    const r = await post(port, "/mcp", { "mcp-session-id": "no-such-session" }, MCP_BODY);
+    expect(r.status).toBe(404);
+  });
+
+  it("creates a fresh session (and MCP server) per initialize request", async () => {
+    const init = JSON.stringify({
+      jsonrpc: "2.0",
+      id: 1,
+      method: "initialize",
+      params: {
+        protocolVersion: "2024-11-05",
+        capabilities: {},
+        clientInfo: { name: "test-client", version: "0.0.0" },
+      },
+    });
+    const r = await post(port, "/mcp", { Accept: "application/json, text/event-stream" }, init);
+    expect([200, 406]).not.toContain(0); // sanity
+    expect(r.status).toBe(200);
+  });
+});
+
+// ── 8. ADR-264 F7: session-map bounds (cap + idle TTL sweep) ───────────────
+
+describe("HTTP transport session bounds (ADR-264 F7)", () => {
+  const initBody = (id: number): string =>
+    JSON.stringify({
+      jsonrpc: "2.0",
+      id,
+      method: "initialize",
+      params: {
+        protocolVersion: "2024-11-05",
+        capabilities: {},
+        clientInfo: { name: "test-client", version: "0.0.0" },
+      },
+    });
+
+  // Build directly (not via startServer) so we can inspect the sessions map.
+  async function startWithApp(
+    opts: Parameters<typeof buildHttpApp>[1],
+    basePort: number
+  ): Promise<{
+    port: number;
+    sessions: ReturnType<typeof buildHttpApp>["sessions"];
+    close: () => Promise<void>;
+  }> {
+    const { httpServer, sessions } = buildHttpApp(() => makeMockMcpServer(), opts);
+    const port = basePort + Math.floor(Math.random() * 100);
+    await new Promise<void>((resolve, reject) => {
+      httpServer.once("error", reject);
+      httpServer.listen(port, "127.0.0.1", () => resolve());
+    });
+    const close = () =>
+      new Promise<void>((res, rej) => httpServer.close((e) => (e ? rej(e) : res())));
+    return { port, sessions, close };
+  }
+
+  const ACCEPT = { Accept: "application/json, text/event-stream" };
+
+  it("never exceeds maxSessions — evicts the oldest-idle session at capacity", async () => {
+    const srv = await startWithApp({ allowedOrigins: ["*"], maxSessions: 2 }, 49800);
+    try {
+      for (let i = 0; i < 5; i++) {
+        await post(srv.port, "/mcp", ACCEPT, initBody(i));
+      }
+      expect(srv.sessions.size).toBeLessThanOrEqual(2);
+    } finally {
+      await srv.close();
+    }
+  });
+
+  it("sweeps sessions idle beyond sessionIdleMs", async () => {
+    const srv = await startWithApp(
+      { allowedOrigins: ["*"], sessionIdleMs: 20, sweepIntervalMs: 10 },
+      49900
+    );
+    try {
+      await post(srv.port, "/mcp", ACCEPT, initBody(1));
+      expect(srv.sessions.size).toBe(1);
+      await new Promise((r) => setTimeout(r, 150));
+      expect(srv.sessions.size).toBe(0);
+    } finally {
+      await srv.close();
+    }
+  });
+});
@@ -15,11 +15,11 @@
 */

 import { readFileSync } from "node:fs";
-import { resolve, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";

-const __dirname = dirname(fileURLToPath(import.meta.url));
-const pkgPath = resolve(__dirname, "../package.json");
+// jest runs from the package root; avoid import.meta (ts-jest transforms this
+// suite to a module target that rejects it — pre-existing suite failure).
+const pkgPath = resolve(process.cwd(), "package.json");

 // Parse once; keep raw for snapshot assertions.
 const raw = readFileSync(pkgPath, "utf-8");
@@ -0,0 +1,96 @@
+/**
+ * ADR-264 O6 — post-restart job reconciliation.
+ *
+ * When the MCP server restarts mid-run, the persisted job record stays frozen
+ * at 'running' (the child.on('close') that flips it lived in the dead process).
+ * ruview_job_status must reconcile such a record against the recorded pid and
+ * the log's "# exit code: N" marker.
+ *
+ * We fabricate a persisted record pointing at a KNOWN-DEAD pid (a synchronous
+ * child that has already exited) and assert the reconciled status.
+ */
+
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { jobStatus } from "../src/tools/train-count.js";
+import type { RuviewConfig } from "../src/types.js";
+
+/** A pid that has certainly exited: spawnSync waits for the child to finish. */
+function deadPid(): number {
+  const r = spawnSync(process.execPath, ["-e", ""]);
+  if (typeof r.pid !== "number") throw new Error("could not spawn probe child");
+  return r.pid;
+}
+
+function makeConfig(jobsDir: string): RuviewConfig {
+  return {
+    sensingServerUrl: "http://127.0.0.1:19999",
+    apiToken: undefined,
+    poseCogBinary: "nonexistent",
+    countCogBinary: "nonexistent",
+    jobsDir,
+  };
+}
+
+/** Write a fake persisted 'running' record + its log, return {jobId, config}. */
+function seedRunningJob(logBody: string): { jobId: string; config: RuviewConfig } {
+  const jobsDir = mkdtempSync(path.join(os.tmpdir(), "rvagent-jobs-"));
+  const jobId = randomUUID();
+  const logPath = path.join(jobsDir, `${jobId}.log`);
+  writeFileSync(logPath, logBody);
+  const record = {
+    job_id: jobId,
+    status: "running",
+    log_path: logPath,
+    queued_at: Date.now() / 1000,
+    epochs_total: 5,
+    pid: deadPid(),
+  };
+  writeFileSync(
+    path.join(jobsDir, `${jobId}.json`),
+    JSON.stringify(record, null, 2)
+  );
+  return { jobId, config: makeConfig(jobsDir) };
+}
+
+describe("ruview_job_status reconciliation (ADR-264 O6)", () => {
+  it("reconciles a dead 'running' job with exit 0 to 'done'", async () => {
+    const { jobId, config } = seedRunningJob(
+      "# training...\nepoch 5/5\n# exit code: 0\n"
+    );
+    const out = (await jobStatus({ job_id: jobId }, config)) as Record<string, unknown>;
+    expect(out["ok"]).toBe(true);
+    const res = out["result"] as Record<string, unknown>;
+    expect(res["status"]).toBe("done");
+  });
+
+  it("reconciles a dead 'running' job with non-zero exit to 'failed'", async () => {
+    const { jobId, config } = seedRunningJob(
+      "# training...\npanic: cuda oom\n# exit code: 101\n"
+    );
+    const out = (await jobStatus({ job_id: jobId }, config)) as Record<string, unknown>;
+    const res = out["result"] as Record<string, unknown>;
+    expect(res["status"]).toBe("failed");
+  });
+
+  it("marks a dead 'running' job with no exit marker as 'unknown' with a reason", async () => {
+    const { jobId, config } = seedRunningJob("# training...\nepoch 2/5\n");
+    const out = (await jobStatus({ job_id: jobId }, config)) as Record<string, unknown>;
+    const res = out["result"] as Record<string, unknown>;
+    expect(res["status"]).toBe("unknown");
+    expect(typeof res["reason"]).toBe("string");
+    expect(res["reason"]).toMatch(/restarted/i);
+  });
+
+  it("treats a signal-killed marker (null) as 'failed'", async () => {
+    const { jobId, config } = seedRunningJob(
+      "# training...\n# exit code: null\n"
+    );
+    const out = (await jobStatus({ job_id: jobId }, config)) as Record<string, unknown>;
+    const res = out["result"] as Record<string, unknown>;
+    expect(res["status"]).toBe("failed");
+  });
+});
@@ -7,8 +7,8 @@
    "outDir": "dist",
    "rootDir": "src",
    "declaration": true,
-    "declarationMap": true,
-    "sourceMap": true,
+    "declarationMap": false,
+    "sourceMap": false,
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,