@vitronai/alethia 0.8.5 → 0.9.0

package/LICENSE

@@ -41,4 +41,4 @@ or any other patent rights of vitron.ai. Use of the Alethia Core runtime is
 governed by separate terms; commercial and production use may require a
 patent license from vitron.ai once the patent grants.
 
-For licensing inquiries: gatekeeper@vitron.ai
+For licensing inquiries: team@vitron.ai

package/README.md

@@ -15,7 +15,7 @@ This package is the **MIT-licensed MCP bridge** (~22 KB) — a thin stdio-to-HTT
 
 The cockpit is an **oversight surface**, not an authoring IDE. Humans do not write tests in a GUI. Agents propose tests, run them, and prove safety — humans review the evidence.
 
-> **Patent notice.** The MIT license on this bridge does **not** grant a patent license to the Alethia runtime (U.S. Application No. 19/571,437). Commercial runtime use may require a separate license. Contact **gatekeeper@vitron.ai**.
+> **Patent notice.** The MIT license on this bridge does **not** grant a patent license to the Alethia runtime (U.S. Application No. 19/571,437). Commercial runtime use may require a separate license. Contact **team@vitron.ai**.
 
 ---
 
@@ -29,6 +29,9 @@ The cockpit is an **oversight surface**, not an authoring IDE. Humans do not wri
 | Speed (per call) | ~200 ms via Playwright MCP, ~2 s via Playwright CLI | ~40 ms — 2-5× faster than Playwright MCP; up to 50× vs Playwright CLI on simple flows — [reproduce the numbers yourself](https://github.com/vitron-ai/alethia-anvil#verify-the-faster-than-cdp-based-tools-claim-yourself) |
 | Evidence | screenshots, videos | signed evidence pack with per-step integrity hashes |
 | Network | Telemetry on by default; optional cloud dashboards | **Air-gap deployable** — no cloud product, no telemetry path, bound to 127.0.0.1 |
+| Dev feedback during coding | reload + devtools + screenshot (can serve cached frames) | `alethia_eval` → live `getComputedStyle()` and layout values, no cache, no round-trip |
+
+Alethia isn't only a post-development testing tool. AI coding agents can use `alethia_eval` as a real-time DOM oracle *while writing code* — call `getComputedStyle()` to read exact computed values, `offsetWidth` for layout dimensions, `querySelectorAll().length` to verify list renders. The eval path always returns live values from the current page with no caching ambiguity, catching CSS cascade bugs in seconds that would otherwise require multiple reload-and-inspect cycles.
 
 ---
 
@@ -225,25 +228,34 @@ If you don't care about any of those (quick iteration, scratch testing), you can
 
 Once the MCP is configured (above), Alethia is available to any agent in any project — no per-project install, no scaffold to run. To add tests:
 
-1. **Create the directory.** Convention is `__alethia__/` at the project root, mirroring how Jest/Vitest treat `__tests__/`.
+1. **Drop a `.alethia` file anywhere your repo treats as test code.** No enforced directory; pick whatever fits your existing layout (e.g. `tests/e2e/`, `e2e/`, `cypress/`-style — your call).
+
+2. **Write the test in plain English.** First line is a `name <label>` so cockpit history reads cleanly when the same file runs locally:
 
-2. **Write a smoke test.** Plain English, one file per scenario:
    ```
-   # __alethia__/smoke.alethia
+   # tests/e2e/login.alethia
+   name login flow
    navigate to http://127.0.0.1:5173
    assert "Sign in" is visible
+   click Sign in
+   type dev@company.com into the email field
+   assert dashboard is visible
    ```
 
 3. **Ask your agent to run it:**
-   > *"Run the Alethia tests in `__alethia__/` against the app at http://127.0.0.1:5173."*
+   > *"Run `tests/e2e/login.alethia` against the app at http://127.0.0.1:5173."*
 
-   The agent calls `alethia_tell` once per file and reports pass/fail.
+   The agent calls `alethia_tell` and reports pass/fail.
 
-4. **For CI**, copy [`ci-runner.mjs`](https://github.com/vitron-ai/alethia-anvil/blob/main/__alethia__/ci-runner.mjs) from alethia-anvil — a small stdio MCP client that pipes every `.alethia` file through the bridge and exits non-zero on failure. Wire it into GitHub Actions or your pipeline of choice.
+4. **For CI**, use the native `alethia run` subcommand — no MCP host or extra scripts needed:
+   ```bash
+   alethia run tests/e2e/login.alethia
+   ```
+   Exits 0 on pass, 1 on fail. See [Running in CI](#running-in-ci) below + the drop-in workflow at [`examples/github-actions.yml`](examples/github-actions.yml).
 
 5. **For evidence**, ask the agent to call `alethia_export_session` after a run — produces a signed evidence pack with per-step integrity hashes and full audit trail.
 
-The full reference example lives at [**vitron-ai/alethia-anvil**](https://github.com/vitron-ai/alethia-anvil) — Anvil demo app + 14 spec files + CI workflow + the head-to-head Playwright/PW-MCP benchmark. Fork it to see the pattern end-to-end.
+The full reference example lives at [**vitron-ai/alethia-anvil**](https://github.com/vitron-ai/alethia-anvil) — demo app + spec files + CI workflow + the head-to-head Playwright/PW-MCP benchmark. Fork it to see the pattern end-to-end.
 
 ---
 
@@ -319,11 +331,12 @@ subcommand that drives the runtime headless and exits 0 (all passed) or 1
 (any failed):
 
 ```bash
-# from a file
+# from a file (recommended — first line "name <label>" lands in cockpit history)
 alethia run tests/e2e/login.alethia
 
 # inline
-alethia run --nlp "navigate to http://localhost:3000
+alethia run --nlp "name smoke
+navigate to http://localhost:3000
 click Sign In
 assert dashboard is visible"
 
@@ -453,7 +466,26 @@ The Alethia runtime (which this bridge connects to) is local-only **by architect
 
 **Full security posture** — threat model, cryptographic chain of custody, supply-chain posture, update cadence, disclosure process — is at [`SECURITY.md`](./SECURITY.md).
 
-Abuse reports + vulnerability disclosure: **`gatekeeper@vitron.ai`**.
+Abuse reports + vulnerability disclosure: **`team@vitron.ai`**.
+
+---
+
+## Privacy Policy
+
+Alethia is **local-only by architecture**. No data is collected, transmitted, or stored outside your machine.
+
+| What | How it's handled |
+|------|-----------------|
+| **Page content** | Processed locally inside the Alethia runtime binary. Never sent to Vitron or any third party. |
+| **Screenshots** | Held in memory for the duration of the tool call, returned to your MCP client. Never persisted or uploaded. |
+| **Test instructions** | Compiled and executed locally. Never logged to external services. |
+| **Session evidence packs** | Written to your local filesystem on explicit `alethia_export_session` call. You control the file. |
+| **Telemetry** | Zero. The runtime contains no analytics, crash reporting, or usage tracking of any kind. |
+| **Network access** | The signed runtime binary only navigates to `file://`, `localhost`, `127.0.0.1`, `.local`, and RFC1918 private ranges — hard-coded at compile time, not configurable. |
+| **Third-party sharing** | None. No data reaches Vitron servers during normal operation. |
+| **Data retention** | No data is retained by Vitron. In-memory state is cleared when the runtime exits. |
+
+For questions or concerns: **team@vitron.ai**
 
 ---
 
@@ -463,4 +495,4 @@ MIT — see [LICENSE](./LICENSE). Covers **this MCP bridge only.**
 
 ## Patent Notice
 
-The Alethia runtime is patent pending (U.S. Application No. 19/571,437). The MIT license on this bridge does **not** grant any patent license. For licensing inquiries: **gatekeeper@vitron.ai**.
+The Alethia runtime is patent pending (U.S. Application No. 19/571,437). The MIT license on this bridge does **not** grant any patent license. For licensing inquiries: **team@vitron.ai**.

package/demo/claude-code-app.alethia

@@ -2,7 +2,7 @@ name Claude Code TaskFlow verification
 navigate to http://localhost:8765/claude-code-app.html
 assert TaskFlow is visible
 type dev@company.com into the you@company.com field
-type Engineering into the Your team name field
+type Engineering into the Team field
 click Sign in
 assert Signed in as is visible
 type Deploy to production into the Add a new task field

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;GAmBG;AA6HH,eAAO,MAAM,WAAW,GAAI,GAAG,MAAM,KAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAO9D,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,GAAG,MAAM,EAAE,GAAG,MAAM,KAAG,MAMpD,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,MAAM,MAAM,EAAE,IAAI,MAAM,KAAG,OACrB,CAAC;AAkH9C,eAAO,MAAM,qBAAqB,QAAO;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,IA8ClG,CAAC;AA8PF,eAAO,MAAM,iCAAiC,GAAI,IAAI,CAAC,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,GAAG,IAAI,KAAG,IAE7F,CAAC;AAIF,eAAO,MAAM,+BAA+B,QAAO,MAA6B,CAAC;AAEjF,eAAO,MAAM,qBAAqB,QAAa,OAAO,CAAC,MAAM,CAmC5D,CAAC;AAuDF,eAAO,MAAM,eAAe,GAAI,gBAAgB,MAAM,KAAG,MAAM,GAAG,IAiBjE,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAI,gBAAgB,MAAM,KAAG,MACe,CAAC;AAsF9E,eAAO,MAAM,+BAA+B,GAAI,mBAAwB,KAAG,MAAM,GAAG,IAsBnF,CAAC;AAmTF,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7E;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5E;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/D;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,EAAE,KAAG,UAkD7C,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAC5G,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,EAAE,CAAC;CAClB,CAAC;AAIF,eAAO,MAAM,gBAAgB,GAAI,UAAU,OAAO,KAAG,SA0CpD,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,QAAQ,SAAS,EAAE,MAAM;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,KAAG,MA4B5F,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;GAmBG;AA6HH,eAAO,MAAM,WAAW,GAAI,GAAG,MAAM,KAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAO9D,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,GAAG,MAAM,EAAE,GAAG,MAAM,KAAG,MAMpD,CAAC;AAEF,eAAO,MAAM,sBAAsB,GAAI,MAAM,MAAM,EAAE,IAAI,MAAM,KAAG,OACrB,CAAC;AAkH9C,eAAO,MAAM,qBAAqB,QAAO;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,IA8ClG,CAAC;AA8PF,eAAO,MAAM,iCAAiC,GAAI,IAAI,CAAC,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,GAAG,IAAI,KAAG,IAE7F,CAAC;AAIF,eAAO,MAAM,+BAA+B,QAAO,MAA6B,CAAC;AAEjF,eAAO,MAAM,qBAAqB,QAAa,OAAO,CAAC,MAAM,CAmC5D,CAAC;AAuDF,eAAO,MAAM,eAAe,GAAI,gBAAgB,MAAM,KAAG,MAAM,GAAG,IAiBjE,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAI,gBAAgB,MAAM,KAAG,MACe,CAAC;AAsF9E,eAAO,MAAM,+BAA+B,GAAI,mBAAwB,KAAG,MAAM,GAAG,IAsBnF,CAAC;AA8UF,MAAM,MAAM,UAAU,GAClB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7E;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5E;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/D;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,EAAE,KAAG,UAkD7C,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAC5G,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,EAAE,CAAC;CAClB,CAAC;AAQF,eAAO,MAAM,gBAAgB,GAAI,UAAU,OAAO,KAAG,SAkDpD,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,QAAQ,SAAS,EAAE,MAAM;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,KAAG,MA4B5F,CAAC"}

package/dist/index.js

@@ -823,7 +823,7 @@ const ensureRuntime = async () => {
     if (!artifactName) {
         throw new Error(`No Alethia runtime available for ${platform()}-${arch()}. ` +
             `Supported: macOS (x64/arm64), Linux (x64/arm64), Windows (x64). ` +
-            `Contact gatekeeper@vitron.ai for assistance.`);
+            `Contact team@vitron.ai for assistance.`);
     }
     // Check what's installed on disk. Marker is fast path; Info.plist fallback
     // catches legacy installs / partial extracts that never wrote a marker.
@@ -857,7 +857,7 @@ const ensureRuntime = async () => {
     if (!verifyManifest(manifest)) {
         throw new Error('Release manifest signature verification FAILED. ' +
             'The download may have been tampered with. Aborting. ' +
-            'Contact gatekeeper@vitron.ai if this persists.');
+            'Contact team@vitron.ai if this persists.');
     }
     debug('manifest signature verified');
     // Download the binary
@@ -926,9 +926,19 @@ const spawnRuntime = async (runtimeVersion) => {
     // setting on the caller's shell doesn't silently re-route the runtime
     // into a non-runtime interpreter mode.
     const { ELECTRON_RUN_AS_NODE: _stripped, ...safeEnv } = process.env;
-    runtimeProcess = spawn(exe, [], {
+    // In CI, pass --no-sandbox to the runtime. Container/runner environments
+    // typically lack the kernel-level isolation primitives the runtime's
+    // sandbox relies on; without this flag the runtime aborts before binding
+    // its port. Production / local installs aren't affected — the flag only
+    // applies when the bridge has detected a CI environment above.
+    const ciArgs = isCi ? ['--no-sandbox'] : [];
+    // In CI, surface the runtime's stderr to the bridge's stderr so spawn
+    // failures aren't silent. Local/production keep stdio:'ignore' to avoid
+    // leaking lower-level diagnostics in normal use.
+    const ciStdio = ['ignore', 'ignore', 'inherit'];
+    runtimeProcess = spawn(exe, ciArgs, {
         env: { ...safeEnv, ...(visible ? {} : { ALETHIA_HEADLESS: '1' }) },
-        stdio: 'ignore',
+        stdio: isCi ? ciStdio : 'ignore',
         detached: false,
     });
     runtimeProcess.on('exit', (code) => {
@@ -936,19 +946,36 @@ const spawnRuntime = async (runtimeVersion) => {
         runtimeProcess = null;
     });
     // Wait for port to bind
-    const maxWait = 15_000;
+    // CI runners have cold caches, slower disk IO, and warmup penalties; the
+    // 15s budget that's plenty for local hits 'first run' floors in CI. Give
+    // CI a 60s window and keep local snappy.
+    const maxWait = isCi ? 60_000 : 15_000;
     const interval = 300;
     const start = Date.now();
+    let lastErr;
+    let pollCount = 0;
     while (Date.now() - start < maxWait) {
         try {
             await callAlethia({ jsonrpc: '2.0', id: 0, method: 'tools/list' }, 2_000);
             process.stderr.write('[alethia] Runtime is ready.\n');
             return;
         }
-        catch {
+        catch (err) {
+            lastErr = err;
+            pollCount++;
+            if (isCi && pollCount % 10 === 1) {
+                // Surface the polling error every ~3s in CI so a stuck spawn is
+                // diagnosable. The error is otherwise silently swallowed.
+                const msg = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`[alethia] poll ${pollCount} failed: ${msg.slice(0, 120)}\n`);
+            }
             await new Promise(r => setTimeout(r, interval));
         }
     }
+    if (isCi && lastErr) {
+        const msg = lastErr instanceof Error ? lastErr.message : String(lastErr);
+        process.stderr.write(`[alethia] last poll error: ${msg}\n`);
+    }
     throw new Error(`Runtime failed to start within ${maxWait / 1000}s. Check ${RUNTIME_DIR} for issues.`);
 };
 // Clean up spawned runtime on exit
@@ -993,7 +1020,7 @@ RUNTIME
   Ed25519-signed, SHA-256 verified. No signup required.
 
       Releases:        https://github.com/vitron-ai/alethia/releases
-      Licensing:       gatekeeper@vitron.ai
+      Licensing:       team@vitron.ai
 
 ENVIRONMENT
   ALETHIA_HOST          Host of the Alethia runtime (default: 127.0.0.1)
@@ -1014,7 +1041,7 @@ ABOUT
   Patent Pending — U.S. Application No. 19/571,437.
   Title: "Deterministic Local Automation Runtime with Zero-IPC Execution,
           Offline Operation, and Per-Step Policy Enforcement"
-  Licensing inquiries: gatekeeper@vitron.ai
+  Licensing inquiries: team@vitron.ai
   Bridge source (MIT): https://github.com/vitron-ai/alethia-mcp
   Project landing:     https://github.com/vitron-ai/alethia
 `;
@@ -1117,26 +1144,29 @@ export const parseRunArgs = (argv) => {
     return { mode: 'error', message: 'No NLP source provided. Use a file path, --nlp <text>, or - for stdin. Try --help.' };
 };
 // Extract a normalized RunResult from the alethia_tell response. The runtime
-// wraps the run in MCP content blocks; we want the raw run object.
+// returns one of three shapes:
+//   1. Compact (default): { ok, runId, name, elapsedMs, steps[], snapshot }
+//   2. Audit: { ok, run: { stepRuns[], lines[], name, elapsedMs, ... }, ... }
+//   3. MCP-wrapped: { content: [{ type: 'text', text: <JSON of (1) or (2)> }] }
+// extractRunResult handles all three.
 export const extractRunResult = (response) => {
-    const r = response ?? {};
-    // The runtime returns either { ok, run: {...} } directly or wrapped in
-    // MCP content. Handle both shapes.
-    let run = r.run;
-    if (!run && r.content && Array.isArray(r.content)) {
-        // MCP content shape — first text block holds JSON
+    let r = response ?? {};
+    // MCP-wrapped — unwrap the inner JSON.
+    if (Array.isArray(r.content) && r.content.length > 0) {
         const text = r.content[0]?.text;
         if (text) {
             try {
-                const parsed = JSON.parse(text);
-                run = parsed.run ?? parsed;
+                r = JSON.parse(text);
             }
-            catch { /* leave run undefined; will fall through to defaults */ }
+            catch { /* keep r */ }
         }
     }
-    run = run ?? r;
-    const stepRunsRaw = Array.isArray(run.stepRuns) ? run.stepRuns : [];
-    const linesRaw = Array.isArray(run.lines) ? run.lines : [];
+    // Audit shape has r.run.stepRuns; compact has r.steps directly.
+    const auditRun = (r.run && typeof r.run === 'object' ? r.run : null);
+    const stepRunsRaw = auditRun && Array.isArray(auditRun.stepRuns) ? auditRun.stepRuns :
+        Array.isArray(r.steps) ? r.steps :
+            [];
+    const linesRaw = auditRun && Array.isArray(auditRun.lines) ? auditRun.lines : [];
     const steps = stepRunsRaw.map((s, i) => {
         const step = s ?? {};
         const lineEntry = linesRaw[i] ?? {};
@@ -1150,13 +1180,20 @@ export const extractRunResult = (response) => {
     });
     const passCount = steps.filter((s) => s.ok).length;
     const failCount = steps.length - passCount;
+    // Plan name: audit.run.name is the actual plan name (from NAME directive
+    // or --name arg); compact's r.name is just the tool tag ("tell"). For
+    // compact, prefer r.runId or fall back.
+    const planName = (auditRun && typeof auditRun.name === 'string' && auditRun.name) ? auditRun.name :
+        (typeof r.runId === 'string' ? r.runId : 'alethia run');
     return {
         ok: failCount === 0 && r.ok !== false,
-        name: typeof run.name === 'string' ? run.name : 'unnamed',
+        name: planName,
         passCount,
         failCount,
         stepCount: steps.length,
-        elapsedMs: typeof run.elapsedMs === 'number' ? run.elapsedMs : 0,
+        elapsedMs: auditRun && typeof auditRun.elapsedMs === 'number' ? auditRun.elapsedMs :
+            typeof r.elapsedMs === 'number' ? r.elapsedMs :
+                0,
         steps,
     };
 };
@@ -1267,20 +1304,13 @@ const runCli = async (argv) => {
         process.exit(1);
     }
 };
-// `alethia-mcp run <...>` — agent-less CLI runner for CI. Branches BEFORE
-// the global --help / --version handlers so `alethia run --help` shows
-// run-specific help, not the top-level help. Below this block, control
-// falls through to the existing MCP stdio-server bootstrap.
-if (process.argv[2] === 'run') {
-    await runCli(process.argv.slice(3));
-    // runCli() always calls process.exit(); this is unreachable but satisfies
-    // the type system.
-    process.exit(0);
-}
-if (process.argv.includes('--help') || process.argv.includes('-h')) {
+// Skip the global --help / --version handlers when the user is in run mode.
+// run-mode has its own --help and the dispatcher fires below in isMainModule.
+const inRunMode = process.argv[2] === 'run';
+if (!inRunMode && (process.argv.includes('--help') || process.argv.includes('-h'))) {
     printAndExit(CLI_HELP);
 }
-if (process.argv.includes('--version') || process.argv.includes('-v')) {
+if (!inRunMode && (process.argv.includes('--version') || process.argv.includes('-v'))) {
     printAndExit(`${PKG_NAME} v${PKG_VERSION}`);
 }
 // ---------------------------------------------------------------------------
@@ -1354,7 +1384,7 @@ const callAlethia = (body, timeoutMs = ALETHIA_TIMEOUT_MS) => new Promise((resol
                 `Troubleshooting:\n` +
                 `  → Run: alethia-mcp --health-check\n` +
                 `  → Releases: https://github.com/vitron-ai/alethia/releases\n` +
-                `  → Licensing: gatekeeper@vitron.ai\n` +
+                `  → Licensing: team@vitron.ai\n` +
                 `\n` +
                 `Override host/port with ALETHIA_HOST / ALETHIA_PORT environment vars\n` +
                 `if your runtime listens on a non-default address.`));
@@ -1424,7 +1454,7 @@ const runHealthCheck = async () => {
             `GitHub Releases. Ed25519-signed, no signup required.\n` +
             `\n` +
             `  → https://github.com/vitron-ai/alethia/releases\n` +
-            `  → Licensing: gatekeeper@vitron.ai\n`);
+            `  → Licensing: team@vitron.ai\n`);
         process.exit(1);
     }
 };
@@ -1473,6 +1503,12 @@ const TOOLS = [
             'Destructive actions (delete, purchase, transfer, etc.) are blocked unconditionally. ' +
             'Sensitive input (passwords, credit cards, SSN) is blocked unless allowSensitiveInput is true. ' +
             '~13 ms per step on average.',
+        annotations: {
+            title: 'Run E2E Tests',
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
         inputSchema: {
             type: 'object',
             properties: {
@@ -1498,6 +1534,11 @@ const TOOLS = [
             'Returns the compiled IR, per-line confidence scores (0-1), and warnings for any lines the compiler ' +
             'could not parse. Use this to preview what tell() will run, debug coverage gaps, or generate ' +
             'reproducible IR scripts for CI pipelines.',
+        annotations: {
+            title: 'Compile Test Instructions',
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
         inputSchema: {
             type: 'object',
             properties: {
@@ -1515,6 +1556,12 @@ const TOOLS = [
             'kill switch state, driver statistics (queued plans, run count, audit count), the current page domain, ' +
             'and runtime capabilities. Use this for liveness checks before sending tell() calls, and to verify ' +
             'the runtime is in a known-good state at the start of an agent loop.',
+        annotations: {
+            title: 'Check Runtime Status',
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
         inputSchema: { type: 'object', properties: {} },
     },
     {
@@ -1523,6 +1570,11 @@ const TOOLS = [
             'subsequent tell() calls will be blocked with reason KILL_SWITCH_ACTIVE until reset. ' +
             'Use this when an agent appears to be acting unsafely, when human review is required, or to enforce ' +
             'a hard boundary at the end of a controlled test run.',
+        annotations: {
+            title: 'Activate Kill Switch',
+            readOnlyHint: false,
+            destructiveHint: true,
+        },
         inputSchema: {
             type: 'object',
             properties: {
@@ -1533,16 +1585,15 @@ const TOOLS = [
             },
         },
     },
-    {
-        name: 'alethia_reset_kill_switch',
-        description: 'Clear an active kill switch and resume normal operation. ' +
-            'Re-enables tell() calls. The reset itself is logged in the audit trail for compliance review.',
-        inputSchema: { type: 'object', properties: {} },
-    },
     {
         name: 'alethia_screenshot',
         description: 'Capture a PNG screenshot of the current page and return it as a base64-encoded image. ' +
             'Use this to visually verify what the browser is showing after running test steps with alethia_tell.',
+        annotations: {
+            title: 'Take Screenshot',
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
         inputSchema: { type: 'object', properties: {} },
     },
     {
@@ -1551,6 +1602,12 @@ const TOOLS = [
             'Runs in the context of the navigated page, not the Alethia host UI. ' +
             'Use this for queries the NLP compiler cannot express — counting elements, reading computed styles, ' +
             'checking localStorage, or any DOM inspection that needs raw JS.',
+        annotations: {
+            title: 'Evaluate JavaScript',
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
         inputSchema: {
             type: 'object',
             properties: {
@@ -1568,6 +1625,11 @@ const TOOLS = [
             'alt text, form labels, keyboard access, page title, lang attribute, link purpose, ' +
             'heading structure, duplicate IDs, and more. Call after navigating with alethia_tell. ' +
             'Returns findings with WCAG criterion numbers, severity levels, and issue counts.',
+        annotations: {
+            title: 'WCAG Accessibility Audit',
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
         inputSchema: { type: 'object', properties: {} },
     },
     {
@@ -1577,6 +1639,11 @@ const TOOLS = [
             'IA (unmasked passwords, weak password constraints, MFA indicators), ' +
             'SI (input validation, error information leakage). ' +
             'Call after navigating with alethia_tell. Returns findings with control IDs and severity levels.',
+        annotations: {
+            title: 'NIST 800-53 Security Audit',
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
         inputSchema: { type: 'object', properties: {} },
     },
     {
@@ -1585,6 +1652,11 @@ const TOOLS = [
             'made during this session with timestamps, inputs, outputs, policy decisions, and a ' +
             'SHA-256 integrity hash. Use at the end of an agent loop to produce cryptographic proof ' +
             'of everything the agent did. Designed for compliance review and chain-of-custody.',
+        annotations: {
+            title: 'Export Session Evidence',
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
         inputSchema: { type: 'object', properties: {} },
     },
     {
@@ -1592,6 +1664,12 @@ const TOOLS = [
         description: 'Run multiple test flows concurrently — each against a different URL. ' +
             'Takes an array of test specs, spawns a browser instance per spec, runs them in parallel, ' +
             'and returns all results together. Use this to verify multiple pages simultaneously.',
+        annotations: {
+            title: 'Run Parallel Tests',
+            readOnlyHint: false,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
         inputSchema: {
             type: 'object',
             properties: {
@@ -1618,6 +1696,12 @@ const TOOLS = [
             'Use this to serve demo pages on localhost so they appear in preview panels (Claude Code, VS Code, etc.). ' +
             'The server runs on a random available port on 127.0.0.1. Call this before alethia_tell to get a localhost URL ' +
             'instead of a file:// path. Returns the base URL and a list of available demo pages.',
+        annotations: {
+            title: 'Serve Demo Pages',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
         inputSchema: { type: 'object', properties: {} },
     },
     {
@@ -1627,6 +1711,12 @@ const TOOLS = [
             'Returns an array of plain-English test blocks, including an auto-generated "EA1 Safety Gate Verification" ' +
             'block that uses "expect block: <action>" for every destructive control on the page. ' +
             'Use this to bootstrap test coverage for a new page or to discover what the safety gate should be watching.',
+        annotations: {
+            title: 'Propose Test Suite',
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
         inputSchema: {
             type: 'object',
             properties: {
@@ -1645,6 +1735,12 @@ const TOOLS = [
             'This is the automated policy-verification primitive — proves the safety gate works on a real page ' +
             'without the agent or human having to click each destructive button manually. Use it as a compliance ' +
             'check before releasing an agent-driven workflow against a customer environment.',
+        annotations: {
+            title: 'Verify EA1 Safety Gate',
+            readOnlyHint: true,
+            destructiveHint: false,
+            openWorldHint: true,
+        },
         inputSchema: {
             type: 'object',
             properties: {
@@ -1661,12 +1757,24 @@ const TOOLS = [
         description: 'Show the Alethia cockpit window — the oversight surface where the target app is driven and each ' +
             'step is highlighted live (green = pass, blue = type, red = EA1 block). Use this to pop the UI ' +
             'into view during a headless-launched session for demos, review, or partner walkthroughs.',
+        annotations: {
+            title: 'Show Cockpit',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
         inputSchema: { type: 'object', properties: {} },
     },
     {
         name: 'alethia_hide_cockpit',
         description: 'Hide the Alethia cockpit window. The runtime keeps running and continues to accept tool calls; ' +
             'only the visible window is dismissed.',
+        annotations: {
+            title: 'Hide Cockpit',
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+        },
         inputSchema: { type: 'object', properties: {} },
     },
 ];
@@ -1676,7 +1784,6 @@ const TOOL_NAME_MAP = {
     alethia_compile: 'alethia_compile_nlp',
     alethia_status: 'alethia_status',
     alethia_activate_kill_switch: 'alethia_activate_kill_switch',
-    alethia_reset_kill_switch: 'alethia_reset_kill_switch',
     alethia_screenshot: 'alethia_screenshot',
     alethia_eval: 'alethia_eval',
     alethia_audit_wcag: 'alethia_audit_wcag',
@@ -1732,7 +1839,6 @@ const validateToolArgs = (toolName, args) => {
             return null;
         }
         case 'alethia_status':
-        case 'alethia_reset_kill_switch':
         case 'alethia_screenshot':
         case 'alethia_audit_wcag':
         case 'alethia_audit_nist':
@@ -1896,7 +2002,7 @@ const handle = async (request) => {
                         '- alethia_status: Health check — version, policy profile, kill switch state.\n' +
                         '- alethia_screenshot: Capture a PNG screenshot of the current page.\n' +
                         '- alethia_eval: Run JavaScript in the page under test.\n' +
-                        '- alethia_activate_kill_switch / alethia_reset_kill_switch: Emergency halt and resume.\n' +
+                        '- alethia_activate_kill_switch: Emergency halt. The kill auto-clears on the operator\'s next Run from the cockpit; agents have no self-release path by design.\n' +
                         '- alethia_audit_wcag: WCAG 2.1 AA accessibility audit — 14 criteria.\n' +
                         '- alethia_audit_nist: NIST SP 800-53 security controls audit — 8 controls.\n' +
                         '- alethia_export_session: Export signed evidence pack of everything the agent did this session.\n' +
@@ -2142,6 +2248,15 @@ const isMainModule = (() => {
     }
 })();
 if (isMainModule) {
+    // `alethia-mcp run <...>` — agent-less CLI runner for CI. Has to dispatch
+    // here, AFTER all module-level const declarations (callAlethia, ensureRuntime
+    // et al.) have evaluated; calling runCli earlier hits a temporal-dead-zone
+    // error when spawnRuntime references callAlethia. Bypasses bootstrap
+    // handoff + the MCP stdio server below — runCli always exits.
+    if (process.argv[2] === 'run') {
+        await runCli(process.argv.slice(3));
+        process.exit(0);
+    }
     // BOOTSTRAP HANDOFF: if a newer, signature-verified bridge is installed
     // at ~/.alethia/bridge/<version>/, exec to it instead of running ourselves.
     // This is how the self-update mechanism hands off control without requiring