@ironbee-ai/cli 0.6.2 → 0.7.0

package/dist/clients/claude/skills/ironbee-verification.md

@@ -1,91 +1,108 @@
 ---
 name: ironbee-verification
 description: >
-  MANDATORY browser verification after code changes. Activates when: implementing features,
-  fixing bugs, modifying UI components, changing API endpoints, updating styles, refactoring code,
-  or completing ANY task that changes application behavior. After writing or editing code files,
-  you MUST verify changes through the browser-devtools MCP server and submit a verdict (pass or fail)
-  before reporting task completion. If verification fails, submit the fail verdict before fixing.
+  MANDATORY verification after code changes. Activates when implementing features, fixing
+  bugs, modifying UI components, API endpoints, styles, refactoring, or any task that
+  changes application behavior. Frontend changes require browser verification via the
+  browser-devtools MCP server. Backend changes ALSO require runtime-specific verification
+  via the matching MCP server when the operator has enabled that runtime (see
+  `ironbee enable-backend <runtime>`). After every code edit you MUST verify the affected
+  cycle(s) through real tools and submit a single verdict (pass or fail) before reporting
+  task completion. If verification fails, submit the fail verdict first, then fix.
 ---
 
-# IronBee Browser Verification
+# IronBee Verification
 
 ## Rule
-No task is complete until changes are verified in the browser — visually AND functionally. After verification, you MUST submit a verdict (pass or fail) before doing anything else. If verification fails, submit the fail verdict first, then fix.
-
-## MCP Server
-Verification is performed using the **browser-devtools** MCP server (`browser-devtools-mcp` package).
-All browser interactions must go through this server's tools.
-
-## Application Lifecycle
-You are responsible for managing the application during verification:
-- **Build** the application if needed (e.g. `npm run build`, `npm run dev`, `docker compose build`, or whatever the project uses)
-- **Start** the dev server before navigating to any page (e.g. `npm run dev`, `docker compose up`, `docker compose up -d`)
-- **Stop** the dev server after verification is complete (e.g. `Ctrl+C`, `docker compose down`)
-
-If the application is already running, skip the start step. If the build fails, fix the build error before proceeding with verification.
-
-**Do NOT guess ports.** After starting the application, check the actual port (e.g. `docker compose ps`, process output, or config files) before navigating. Never assume a default port.
-
-## Flow
-1. Implement your changes (write/edit code)
-2. **Build and start** the application if not already running
-3. **Start verification**: `echo '{"session_id":"<your-session-id>"}' | ironbee hook verification-start`
-   - This is REQUIRED before using any browser-devtools tools. Browser tools are blocked without it.
-4. **Functionally test** your changes through the browser:
-   - **Navigate**: `mcp__browser-devtools__bdt_navigation_go-to` — go to the affected page(s)
-   - **Interact**: Use the browser agent to **actually test** what you changed — click buttons, fill forms, submit data, trigger workflows, navigate between pages. Do not just look at the page.
-   - **Screenshot**: `mcp__browser-devtools__bdt_content_take-screenshot` — capture the final visual state
-   - **Accessibility**: `mcp__browser-devtools__bdt_a11y_take-aria-snapshot` — verify page structure
-   - **Console**: `mcp__browser-devtools__bdt_o11y_get-console-messages` — check for errors
-   Navigate, Screenshot, Accessibility, and Console tools are MANDATORY (the Stop hook checks the transcript for each one). Functional interaction is expected for every verification.
-5. **Stop** the dev server when verification is complete
-6. **IMMEDIATELY submit your verdict** — do NOT edit any code before submitting: `echo '<verdict-json>' | ironbee hook submit-verdict`
-   - If everything works → submit pass verdict
-   - If something is broken → submit fail verdict with issues describing what failed
-   - **Never skip this step.** Every verification attempt must be recorded, pass or fail.
-   - Submitting a verdict automatically ends the verification cycle.
-7. If you submitted a fail verdict → fix the code → rebuild → go back to step 2 → submit again → repeat until pass
+No task is complete until changes are verified — through **real tools** (browser interaction or, when enabled, a backend-runtime debugger), not by reading code or inferring behavior. After verification, you MUST submit a verdict (pass or fail) before doing anything else. If verification fails, submit the fail verdict first, then fix.
 
-## What good verification looks like
-- Changed a form handler? → Start the app, fill the form, submit it, verify the response
-- Added a button? → Click it, confirm the expected action happens
-- Fixed a routing bug? → Navigate through the affected routes
-- Updated an API call? → Trigger the action that calls the API, verify the result in the UI
-- Changed styling? → Take a screenshot AND interact to ensure layout didn't break functionality
-
-## How it works
-- At session start, the SessionStart hook outputs your session ID
-- After verification, submit your verdict: `echo '<verdict-json>' | ironbee hook submit-verdict`
-- The submit-verdict command validates your verdict and records it
-- When you stop, the Stop hook checks that browser tools were used AND a valid verdict exists
-- If something is missing, the hook blocks you and gives you instructions
-
-## Agent Teams
-- Subagents focus on implementation only — do NOT verify
-- The main orchestrator agent verifies ALL changes after subagents complete
-- Each session's verification is isolated via session-specific verdict files
-
-## Verdict format
-
-On pass:
-```json
-{"session_id":"<your-session-id>","status":"pass","pages_tested":["http://localhost:3000/page"],"checks":["feature works"],"console_errors":0,"network_failures":0}
-```
+## Cycles
 
-On fail (issues is required):
-```json
-{"session_id":"<your-session-id>","status":"fail","pages_tested":["http://localhost:3000/page"],"checks":["feature broken"],"console_errors":1,"network_failures":0,"issues":["button click handler not firing"]}
-```
+IronBee runs verification in **cycles**. A single Stop hook can drive multiple cycles in parallel — every active cycle must pass for your task to complete.
+
+- **Browser cycle** — always available. Triggered when a changed file matches `browser.verifyPatterns` (default: most code extensions — `.ts`, `.tsx`, `.css`, `.html`, `.py`, `.go`, `.java`, etc.). Tools come from the **browser-devtools** MCP server (prefix `bdt_`). Verification means navigating to the affected page and FUNCTIONALLY exercising the change in the browser.
+- **Backend-runtime cycle(s)** — opt-in per project via `ironbee enable-backend <runtime>` (e.g. `node`). Triggered when a changed file matches `backend.<runtime>.verifyPatterns`. Tools come from a runtime-specific MCP server. **See the runtime section near the bottom of this file** for whether a backend cycle is active for this project and which tools to call.
+
+You don't choose which cycle runs — the file pattern decides. A single file can match multiple cycles' patterns and activate them all. Cycles always run in parallel within a single Stop run.
+
+## Application lifecycle (your responsibility)
+
+For both cycles you manage the running application:
+- **Build** if needed (`npm run build`, `docker compose build`, …)
+- **Start** before navigating/connecting (`npm run dev`, `docker compose up -d`, …)
+- **Stop** when verification is complete
+
+If already running, skip start. If the build fails, fix it before proceeding.
+
+**Don't guess ports.** After starting, check the actual port via `docker compose ps`, process output, or config files.
+
+## Universal flow
 
-On pass after a previous fail (fixes is required):
+1. Implement your changes (write/edit code).
+2. **Start verification** (one cycle covers every active mode — browser plus any enabled backend-runtime cycles):
+   ```
+   echo '{"session_id":"<your-session-id>"}' | ironbee hook verification-start
+   ```
+   Devtools tools are blocked without this.
+3. Build and start the application if not already running.
+4. Run the **Browser flow** below. **See the runtime section near the bottom of this file** — if a backend-runtime cycle is active for this project, run its flow within the same verification cycle as well.
+5. Stop the dev server when verification is complete.
+6. **If recording was started, stop it now** — `mcp__browser-devtools__bdt_content_stop-recording`. submit-verdict rejects when recording is still active.
+7. **Submit your verdict immediately** — do NOT edit any code first:
+   ```
+   echo '<verdict-json>' | ironbee hook submit-verdict
+   ```
+   - Pass → submit pass verdict (with fields for every active cycle)
+   - Fail → submit fail verdict with `issues`
+   - **The Stop hook overrides `status: pass` to fail when evidence doesn't back it.**
+8. If failed → fix → rebuild → go back to step 2 → repeat until pass.
+
+## Browser flow (when browser cycle is active)
+
+> **Recording (only when `recording.enable` is on in config):** the gate blocks every other browser tool until you first call `mcp__browser-devtools__bdt_content_start-recording`, and `submit-verdict` rejects with `"recording is still active"` unless you call `mcp__browser-devtools__bdt_content_stop-recording` after the steps below. **Treat start/stop as bookends around steps 1-5.** This is also enforced as step 6 of the Universal flow above.
+
+1. **Navigate**: `mcp__browser-devtools__bdt_navigation_go-to` — go to the affected page(s)
+2. **Interact**: actually exercise what changed — click buttons, fill forms, submit data, trigger workflows. Don't just look at the page.
+3. **Screenshot**: `mcp__browser-devtools__bdt_content_take-screenshot` — capture the final visual state
+4. **Accessibility**: `mcp__browser-devtools__bdt_a11y_take-aria-snapshot` — verify page structure
+5. **Console**: `mcp__browser-devtools__bdt_o11y_get-console-messages` — check for errors
+
+All four tools are MANDATORY (the Stop hook checks each). Functional interaction is expected for every verification.
+
+### Browser verdict fields
 ```json
-{"session_id":"<your-session-id>","status":"pass","pages_tested":["http://localhost:3000/page"],"checks":["feature works"],"console_errors":0,"network_failures":0,"fixes":["reattached click handler to submit button"]}
+{
+  "session_id": "<sid>",
+  "status": "pass",
+  "pages_tested": ["http://localhost:3000/page"],
+  "checks": ["form submits successfully", "new item appears in list", "no console errors"],
+  "console_errors": 0,
+  "network_failures": 0
+}
 ```
 
+For `status: "pass"` (browser cycle): `console_errors === 0` AND `network_failures === 0`.
+
+On fail, include `issues`. On pass after a previous fail, include `fixes`.
+
+<!--IRONBEE:RUNTIME:node-->
+<!--/IRONBEE:RUNTIME:node-->
+
+## What good verification looks like
+
+- Changed a form handler? → Start the app, fill the form, submit it, verify the response (browser flow).
+- Added an API endpoint in a backend file (when a runtime cycle is enabled)? → Run that runtime's flow per the runtime section: attach to the running process, set a probe at the handler, exercise the path from the browser, confirm the probe triggered (or inspect runtime logs).
+- Fixed a bug that surfaced as both a UI glitch AND a server error? → Multi-cycle: visual confirmation in the browser AND probe/log proof on the server.
+- Changed styling only? → Browser flow with extra attention on screenshot review.
+
 ## Important
 - **Always submit a verdict after every verification attempt** — both pass AND fail. Fail verdicts are tracked for analytics.
-- The Stop hook checks BOTH that browser-devtools MCP tools were used AND a valid verdict exists
-- Submit verdicts via `ironbee hook submit-verdict`, do NOT write verdict.json directly
-- Every code edit (Write/Edit) automatically clears your session's verdict
-- After 3 failed verification attempts, you may complete but must report issues
+- The Stop hook checks tool usage AND verdict validity for every active cycle. Pass criteria are enforced separately per cycle, then AND-combined.
+- Submit verdicts via `ironbee hook submit-verdict`, never write `verdict.json` directly.
+- Every code edit (Write/Edit) automatically clears your session's verdict.
+- After 3 failed verification attempts, you may complete but must report unresolved issues.
+
+## Subagent teams
+- Subagents focus on implementation only — do NOT verify.
+- The main orchestrator agent verifies ALL changes after subagents complete.
+- Each session's verification is isolated via session-specific verdict files.

package/dist/clients/cursor/commands/ironbee-verify/SKILL.md

@@ -1,19 +1,21 @@
 ---
 name: ironbee-verify
-description: "Trigger browser verification of code changes. Args: (default), full, visual, functional"
+description: "Trigger verification of code changes (browser cycle for frontend, runtime-specific cycle for backend when enabled). Args: (default), full, visual, functional"
 disable-model-invocation: true
 ---
 
 # IronBee Verify
 
-Verify the current code changes in the browser.
+Verify the current code changes through real tools — browser interaction for frontend, runtime-specific debugger for any enabled backend cycle.
 
 ## Usage
-- `/ironbee-verify` — **default** — focus on what changed, visual + functional checks on affected areas
+- `/ironbee-verify` — **default** — focus on what changed, visual + functional checks on affected areas (browser-cycle modes; any enabled backend-runtime cycle runs alongside automatically — see runtime section below)
 - `/ironbee-verify full` — **full scope** — entire application, all checklists, edge cases, responsive, accessibility deep dive
 - `/ironbee-verify visual` — **visual only** — contrast, layout, spacing, fonts, images, theming
 - `/ironbee-verify functional` — **functional only** — clicks, forms, navigation, data flow, error handling
 
+A backend-runtime cycle (e.g. `node` after `ironbee enable-backend node`) may also be active for this project — **see the runtime section near the bottom of this file** for whether it applies and which tools to call.
+
 If no argument is given, use **default** mode.
 
 ---
@@ -23,9 +25,9 @@ If no argument is given, use **default** mode.
 1. **Start verification**: Run `echo '{"session_id":"<your-session-id>"}' | ironbee hook verification-start` via terminal
 2. **Build and start** the application if not already running
 3. **For EVERY page you visit**, repeat this cycle:
-   a. **Navigate** using browser-devtools MCP tools
-   b. **Take a FULL PAGE screenshot** with `fullPage: true`
-   c. **Take an ARIA snapshot** to capture the page structure
+   a. **Navigate** using `MCP:bdt_navigation_go-to`
+   b. **Take a FULL PAGE screenshot** using `MCP:bdt_content_take-screenshot` with `fullPage: true`
+   c. **Take an ARIA snapshot** using `MCP:bdt_a11y_take-aria-snapshot`
    d. **STOP and visually analyze the screenshot** — switch your focus entirely to finding visual problems. Look at this screenshot as if your ONLY job is to find visual defects:
       **WARNING: ARIA reports DOM content, not what the user actually sees.** Do NOT assume the page looks correct just because ARIA shows the right content. Only the screenshot tells you what the user actually sees.
       - Text readability — is it readable against its background? Look for text that blends in or poor contrast
@@ -39,13 +41,14 @@ If no argument is given, use **default** mode.
    e. **Read the ARIA snapshot** — verify headings, labels, landmarks, and structure
    f. If anything looks wrong → note it as an issue
 4. **Functionally test** — run the checklist for your mode (see below). After each significant interaction, take another screenshot and repeat the visual analysis.
-5. **Check console** for errors
+5. **Check console** for errors using `MCP:bdt_o11y_get-console-messages`
 6. **Stop** the dev server when verification is complete
-7. **Submit your verdict** via terminal:
+7. **If recording was started, stop it now** — `MCP:bdt_content_stop-recording`. submit-verdict rejects with `"recording is still active"` when this step is skipped. (Recording is a server-side opt-in via `recording.enable` — when on, the gate forces `MCP:bdt_content_start-recording` BEFORE the steps above and demands the matching stop here.)
+8. **Submit your verdict** via terminal:
     - Pass: `echo '{"session_id":"...","status":"pass","pages_tested":[...],"checks":[...],"console_errors":0,"network_failures":0}' | ironbee hook submit-verdict`
     - Fail: `echo '{"session_id":"...","status":"fail","pages_tested":[...],"checks":[...],"console_errors":N,"network_failures":N,"issues":["describe what failed"]}' | ironbee hook submit-verdict`
-8. **If failed** → collect ALL issues first (finish testing all affected pages), submit one fail verdict with all issues, then fix everything, rebuild, and re-verify. Do not fix one issue at a time — batch fixes to avoid repeated build/restart cycles.
-9. If pass after a previous fail, include `"fixes"` in the verdict describing what was fixed
+9. **If failed** → collect ALL issues first (finish testing all affected pages), submit one fail verdict with all issues, then fix everything, rebuild, and re-verify. Do not fix one issue at a time — batch fixes to avoid repeated build/restart cycles.
+10. If pass after a previous fail, include `"fixes"` in the verdict describing what was fixed
 
 ---
 
@@ -131,3 +134,8 @@ Your `checks` array must list **specific observations**, not generic statements:
 - ALWAYS submit a verdict after every verification attempt — both pass AND fail
 - Do NOT edit code before submitting a fail verdict
 - **Noticing a bug and submitting pass is the #1 violation** — if you see it, fail it
+
+---
+
+<!--IRONBEE:RUNTIME:node-->
+<!--/IRONBEE:RUNTIME:node-->

package/dist/clients/cursor/fragments/command-verify.node.md

@@ -0,0 +1,33 @@
+<!-- Node backend verification is ENABLED for this project. -->
+
+## Backend Node Mode (when `backend.node.verifyPatterns` matches an edited file)
+
+> **Precondition: the backend must actually be Node.js.** If you see `pom.xml`, `build.gradle`, `requirements.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml`, etc., this section does NOT apply — `MCP:ndt_*` tools won't connect to non-Node processes. Just do browser verification.
+
+If the project has node backend verification enabled (`ironbee enable-backend node` once at setup, by an operator who confirmed the backend is Node.js) and your edits touch matching paths (e.g. `server/**`, `pages/api/**`), the stop hook also enforces a Node cycle. The same `verification-start` covers both cycles; the same verdict file carries fields for both.
+
+### Steps (additive to the browser flow above)
+1. **Identify the running Node process** — note its PID, container name (`docker compose ps`), or inspector port.
+2. **Connect**: `MCP:ndt_debug_connect` with one of `pid` / `processName` / `containerId` / `containerName` / `inspectorPort` / `wsUrl`. Inspector is auto-activated via SIGUSR1 if needed.
+3. **Pick an evidence path** for each changed code path:
+   - **Probe path** (proves the code path executed): `MCP:ndt_debug_put-tracepoint` (or `put-logpoint` / `put-exceptionpoint`) at the changed code, exercise the path (e.g. trigger the API call from the browser), then `MCP:ndt_debug_get-probe-snapshots`. At least one probe must come back with `triggered: true`.
+   - **Log path** (proves no errors): exercise the path, then `MCP:ndt_debug_get-logs` with the error level filter. `backend_node_log_errors` must be empty for `status: pass`.
+4. **Disconnect** (optional): `MCP:ndt_debug_disconnect`.
+5. **Submit verdict** including `backend_node_*` fields. If browser cycle is also active, include browser fields in the SAME verdict — do not submit two verdicts.
+
+### Verdict (node-cycle fields)
+```json
+{
+  "session_id": "...",
+  "status": "pass",
+  "checks": ["POST /api/orders returned 201", "tracepoint at handler.ts:42 fired once"],
+  "backend_node_processes_connected": ["pid:12345 (next-server)"],
+  "backend_node_probes_set": [
+    { "type": "tracepoint", "location": "src/api/orders.ts:42", "triggered": true }
+  ],
+  "backend_node_probe_snapshots_collected": 1,
+  "backend_node_log_errors": []
+}
+```
+
+For a multi-cycle pass, both browser and node criteria must hold — claiming `pass` without one cycle's evidence will be overridden to fail by the gate.

package/dist/clients/cursor/fragments/rule.node.md

@@ -0,0 +1,29 @@
+<!-- Node backend verification is ENABLED for this project. The stop hook
+     enforces a node cycle in addition to the browser cycle whenever an
+     edited file matches `backend.node.verifyPatterns`. -->
+
+## Node cycle
+
+Backend file changes IF the file matches `backend.node.verifyPatterns` ALSO require verification through the **node-devtools** MCP server (prefix `MCP:ndt_*`). Node-cycle verification means attaching to the running Node process via the V8 inspector, setting a probe (tracepoint / logpoint / exceptionpoint) at the changed code, exercising the path so the probe fires, and reading snapshots — OR inspecting runtime error logs.
+
+Both cycles can be active simultaneously (e.g. you edit both a React component and an API handler in the same task). One `verification-start` covers all active cycles; one verdict file carries fields for all active cycles; one retry counter applies globally.
+
+### ⚠️ `node-devtools` is ONLY for Node.js backends
+
+`node-devtools` is a V8 inspector wrapper. It does NOT work for Java, Python, Go, Rust, Ruby, .NET, PHP, or any other runtime. If you see `pom.xml`, `build.gradle`, `requirements.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml`, etc., the backend is NOT Node.js and you must NOT call `MCP:ndt_*` tools — they will fail to connect to non-Node processes.
+
+**Misconfiguration recovery.** If you reach this state, the operator enabled the node cycle for a non-Node project by mistake. The stop hook will keep blocking with `incomplete_tools` for the node cycle until you call `MCP:ndt_debug_connect` (which will fail) or until `maxRetries` is exhausted. Don't attempt the connection. Instead, stop and clearly report to the user: the project's backend is not Node.js, and they must run `ironbee disable-backend node` to unblock the gate. Continue with browser-cycle verification only in the meantime.
+
+### Node-cycle additions to the main flow
+
+These attach to the **Required steps** above — they don't replace any step. Numbering follows the main flow:
+
+- **Within step 3 (run flow):** also run the node flow: connect (`MCP:ndt_debug_connect`) → set probe (`MCP:ndt_debug_put-tracepoint` / `put-logpoint` / `put-exceptionpoint`) AND exercise + read snapshots (`MCP:ndt_debug_get-probe-snapshots`), OR exercise + read logs (`MCP:ndt_debug_get-logs`). When both browser and node cycles are active, run BOTH within the same verification cycle.
+- **Within step 6 (submit verdict):** include `backend_node_*` fields (`backend_node_processes_connected` non-empty, plus `backend_node_probes_set` and/or `backend_node_log_errors`). One verdict carries fields for every active cycle.
+
+### Additional BANNED for node cycle
+
+- Calling `MCP:ndt_*` tools without first opening a verification cycle (`ironbee hook verification-start`).
+- **Calling `MCP:ndt_*` tools when the project's backend is NOT Node.js** (Java / Python / Go / Rust / .NET / Ruby / PHP / Elixir / etc.). Use the browser cycle only for non-Node backends.
+- Claiming `status: pass` for a node cycle when no probe triggered AND `backend_node_log_errors` was never collected.
+- Submitting a node-only verdict that omits `backend_node_processes_connected` — every node-cycle verdict requires this field non-empty.

package/dist/clients/cursor/fragments/skill.node.md

@@ -0,0 +1,77 @@
+<!-- Node backend verification is ENABLED for this project. The stop hook
+     enforces a node cycle in addition to the browser cycle whenever an
+     edited file matches `backend.node.verifyPatterns`. -->
+
+## ⚠️ CRITICAL: when NOT to use node-devtools
+
+**`node-devtools` is ONLY for Node.js backends.** It is a V8 inspector wrapper (`node --inspect` attach via PID / inspector port / Docker container). It does **NOT** work with any other runtime. Do **NOT** call `MCP:ndt_*` tools for projects whose backend is:
+- Java (Spring, Quarkus, Micronaut, …) — use the JVM debugger, not supported by IronBee yet
+- Python (FastAPI, Django, Flask, …) — not supported yet
+- Go, Rust, Ruby, .NET, PHP, Elixir, Kotlin/JVM, Swift — not supported yet
+
+**How to tell whether the backend is Node.js:**
+- `package.json` is the main project manifest, with `"type": "module"` or `"engines": { "node": ... }`, or scripts that run `node`/`tsx`/`ts-node`.
+- The dev server command is `npm run dev`, `next dev`, `nest start`, `nodemon`, etc.
+
+If you see `pom.xml`, `build.gradle`, `requirements.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `Gemfile`, `composer.json`, `*.csproj` — the backend is NOT Node.js. Do NOT call any `MCP:ndt_*` tools.
+
+**Misconfiguration recovery.** If you read this section it means the operator enabled the node cycle for this project. If the backend isn't actually Node.js, this was a mistake — the stop hook will keep blocking the gate (with `incomplete_tools` for the node cycle) until you call `MCP:ndt_debug_connect` (which will fail) or `maxRetries` is exhausted. Don't attempt the connection. Stop and tell the user clearly: the project's backend is not Node.js; ask them to run `ironbee disable-backend node` to unblock the gate. Continue with browser-cycle verification only in the meantime.
+
+## Node flow
+
+1. **Identify the running Node process** — note its PID, container name (`docker compose ps`), or inspector port.
+2. **Connect**: `MCP:ndt_debug_connect` with one of `pid` / `processName` / `containerId` / `containerName` / `inspectorPort` / `wsUrl`. SIGUSR1 is auto-sent if the inspector isn't on; for Docker, it goes through `docker exec`.
+3. **Pick an evidence path** per changed code path:
+   - **Probe path** (proves the code path executed):
+     - Set a probe at the changed location: `MCP:ndt_debug_put-tracepoint` (checkpoint), `MCP:ndt_debug_put-logpoint` (logged expression), or `MCP:ndt_debug_put-exceptionpoint` (caught/uncaught exception).
+     - **Exercise the path** (e.g. send a request from the browser, run a CLI command, post to a queue) — without this the probe never fires.
+     - Read collected snapshots: `MCP:ndt_debug_get-probe-snapshots`. At least one probe must come back with `triggered: true`.
+   - **Log path** (proves no errors during execution):
+     - Exercise the path.
+     - Read errors: `MCP:ndt_debug_get-logs` with the error-level filter. `backend_node_log_errors` must be empty for `status: pass`.
+4. **Disconnect** (optional): `MCP:ndt_debug_disconnect`.
+
+### Node verdict fields
+```json
+{
+  "session_id": "<sid>",
+  "status": "pass",
+  "checks": ["POST /api/orders returned 201", "tracepoint at handler.ts:42 fired once"],
+  "backend_node_processes_connected": ["pid:12345 (next-server)"],
+  "backend_node_probes_set": [
+    { "type": "tracepoint", "location": "src/api/orders.ts:42", "triggered": true }
+  ],
+  "backend_node_probe_snapshots_collected": 1,
+  "backend_node_log_errors": []
+}
+```
+
+For `status: "pass"` (node cycle):
+- If probes were set, at least one must have `triggered: true` (proves the code path executed).
+- If only logs were used, `backend_node_log_errors.length === 0` (no errors observed).
+- If both forms were used, both conditions must hold.
+
+## Multi-cycle (browser + node simultaneously)
+
+Common case: in the same task you edit a `.tsx` component (browser-cycle) and a `server/api/*.ts` handler (node-cycle). Both cycles activate. **Single** `verification-start`, **single** `verdict.json`, **single** retry counter cover both.
+
+Submit ONE verdict carrying fields for every active cycle:
+
+```json
+{
+  "session_id": "<sid>",
+  "status": "pass",
+  "pages_tested": ["http://localhost:3000/checkout"],
+  "checks": ["checkout submits", "POST /api/orders returned 201", "no console errors"],
+  "console_errors": 0,
+  "network_failures": 0,
+  "backend_node_processes_connected": ["pid:12345 (next-server)"],
+  "backend_node_probes_set": [
+    { "type": "tracepoint", "location": "src/api/orders.ts:42", "triggered": true }
+  ],
+  "backend_node_probe_snapshots_collected": 1,
+  "backend_node_log_errors": []
+}
+```
+
+For a multi-cycle `pass`, BOTH cycles' pass criteria must hold. Claiming `pass` without one cycle's evidence will be overridden to `fail` by the gate.

package/dist/clients/cursor/hooks/activity-end.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Cursor — activity-end hook adapter (monitoring-only mode).
+ *
+ * stop hook for sessions where verification is disabled. Closes the active
+ * activity and triggers a background queue flush so accumulated `send_event`
+ * jobs ship to the collector before the next turn starts.
+ *
+ * Replaces `verify-gate` on stop when `verification.enable: false`. The two
+ * are mutually exclusive at install time — only one stop handler is registered
+ * per session. Unlike verify-gate, this hook never emits a followup_message
+ * (no enforcement) — it returns an empty JSON object.
+ */
+export declare function run(projectDir: string): Promise<void>;
+//# sourceMappingURL=activity-end.d.ts.map

package/dist/clients/cursor/hooks/activity-end.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-end.d.ts","sourceRoot":"","sources":["../../../../src/clients/cursor/hooks/activity-end.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAYH,wBAAsB,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA0B3D"}

package/dist/clients/cursor/hooks/activity-end.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Cursor — activity-end hook adapter (monitoring-only mode).
+ *
+ * stop hook for sessions where verification is disabled. Closes the active
+ * activity and triggers a background queue flush so accumulated `send_event`
+ * jobs ship to the collector before the next turn starts.
+ *
+ * Replaces `verify-gate` on stop when `verification.enable: false`. The two
+ * are mutually exclusive at install time — only one stop handler is registered
+ * per session. Unlike verify-gate, this hook never emits a followup_message
+ * (no enforcement) — it returns an empty JSON object.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = run;
+const activity_end_1 = require("../../../hooks/core/activity-end");
+const logger_1 = require("../../../lib/logger");
+const output_1 = require("../../../lib/output");
+const stdin_1 = require("../../../lib/stdin");
+const hook_trigger_1 = require("../../../analytics/hook-trigger");
+async function run(projectDir) {
+    let input;
+    try {
+        input = JSON.parse((0, stdin_1.readStdin)());
+    }
+    catch (e) {
+        logger_1.logger.debug(`failed to parse stdin: ${e}`);
+        (0, output_1.writeAndExit)(JSON.stringify({}), 0);
+        return;
+    }
+    const sessionId = input.conversation_id ?? "default";
+    const sessionDir = `${projectDir}/.ironbee/sessions/${sessionId}`;
+    const actionsFile = `${sessionDir}/actions.jsonl`;
+    (0, logger_1.setLogFile)(`${sessionDir}/session.log`);
+    await (0, activity_end_1.runActivityEnd)({ sessionDir, actionsFile, projectDir, sessionId });
+    // Analytics trigger — fail-safe; Cursor transcript path TBD (§9).
+    (0, hook_trigger_1.runAnalyticsTrigger)({
+        projectDir,
+        sessionId,
+        triggerType: "Stop",
+        transcriptSource: "cursor",
+    });
+    (0, output_1.writeAndExit)(JSON.stringify({}), 0);
+}
+//# sourceMappingURL=activity-end.js.map

package/dist/clients/cursor/hooks/activity-end.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-end.js","sourceRoot":"","sources":["../../../../src/clients/cursor/hooks/activity-end.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;AAYH,kBA0BC;AApCD,mEAAkE;AAClE,gDAAyD;AACzD,gDAAmD;AACnD,8CAA+C;AAC/C,kEAAsE;AAM/D,KAAK,UAAU,GAAG,CAAC,UAAkB;IACxC,IAAI,KAA0B,CAAC;IAC/B,IAAI,CAAC;QACD,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAA,iBAAS,GAAE,CAAwB,CAAC;IAC3D,CAAC;IAAC,OAAO,CAAU,EAAE,CAAC;QAClB,eAAM,CAAC,KAAK,CAAC,0BAA0B,CAAC,EAAE,CAAC,CAAC;QAC5C,IAAA,qBAAY,EAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QACpC,OAAO;IACX,CAAC;IAED,MAAM,SAAS,GAAW,KAAK,CAAC,eAAe,IAAI,SAAS,CAAC;IAC7D,MAAM,UAAU,GAAW,GAAG,UAAU,sBAAsB,SAAS,EAAE,CAAC;IAC1E,MAAM,WAAW,GAAW,GAAG,UAAU,gBAAgB,CAAC;IAC1D,IAAA,mBAAU,EAAC,GAAG,UAAU,cAAc,CAAC,CAAC;IAExC,MAAM,IAAA,6BAAc,EAAC,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC;IAEzE,kEAAkE;IAClE,IAAA,kCAAmB,EAAC;QAChB,UAAU;QACV,SAAS;QACT,WAAW,EAAE,MAAM;QACnB,gBAAgB,EAAE,QAAQ;KAC7B,CAAC,CAAC;IAEH,IAAA,qBAAY,EAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AACxC,CAAC"}

package/dist/clients/cursor/hooks/require-verdict.d.ts

@@ -2,7 +2,7 @@
  * Cursor — require-verdict hook adapter
  *
  * preToolUse hook for Write|StrReplace|Delete — blocks file edits
- * if the agent used browser-devtools tools but hasn't submitted a verdict
+ * if the agent used any devtools tools (browser-devtools or node-devtools) but hasn't submitted a verdict
  * yet. Forces the agent to submit a fail verdict before fixing code.
  *
  * Side effect: when `tool_name === "Write"`, stashes whether the target

package/dist/clients/cursor/hooks/require-verdict.js

@@ -3,7 +3,7 @@
  * Cursor — require-verdict hook adapter
  *
  * preToolUse hook for Write|StrReplace|Delete — blocks file edits
- * if the agent used browser-devtools tools but hasn't submitted a verdict
+ * if the agent used any devtools tools (browser-devtools or node-devtools) but hasn't submitted a verdict
  * yet. Forces the agent to submit a fail verdict before fixing code.
  *
  * Side effect: when `tool_name === "Write"`, stashes whether the target
@@ -41,10 +41,10 @@ async function run(projectDir) {
     if ((0, actions_1.hasToolCallsSinceLastVerdict)(actionsFile)) {
         const output = {
             permission: "deny",
-            agent_message: `BLOCKED: You used browser-devtools tools but did not submit a verdict. You MUST submit a verdict (pass or fail) before editing code.
+            agent_message: `BLOCKED: You used verification tools (browser-devtools or node-devtools) but did not submit a verdict. You MUST submit a verdict (pass or fail) before editing code.
 
-Submit your verdict first:
-  echo '{"session_id":"${sessionId}","status":"fail","pages_tested":[...],"checks":[...],"console_errors":0,"network_failures":0,"issues":["describe what failed"]}' | ironbee hook submit-verdict
+Submit your verdict first (include cycle-appropriate fields — browser fields for bdt_*, backend_node_* fields for ndt_*):
+  echo '{"session_id":"${sessionId}","status":"fail","checks":[...],"issues":["describe what failed"], ...}' | ironbee hook submit-verdict
 
 Then you can edit code to fix the issues.`,
         };

package/dist/clients/cursor/hooks/require-verification.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"require-verification.d.ts","sourceRoot":"","sources":["../../../../src/clients/cursor/hooks/require-verification.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA2BH,wBAAsB,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAwG3D"}
+{"version":3,"file":"require-verification.d.ts","sourceRoot":"","sources":["../../../../src/clients/cursor/hooks/require-verification.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAkCH,wBAAsB,GAAG,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA8H3D"}

package/dist/clients/cursor/hooks/require-verification.js

@@ -14,14 +14,20 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.run = run;
+const crypto_1 = require("crypto");
 const session_state_1 = require("../../../hooks/core/session-state");
 const actions_1 = require("../../../hooks/core/actions");
 const activity_1 = require("../../../hooks/core/activity");
 const config_1 = require("../../../lib/config");
 const logger_1 = require("../../../lib/logger");
 const stdin_1 = require("../../../lib/stdin");
-/** MCP server key that this hook is routed to via the `MCP:bdt_.*` matcher. */
-const MCP_SERVER_NAME = "browser-devtools";
+/** Prefix → MCP server lookup. Cursor's `MCP:<bare-tool>` wire has no server
+ *  segment, so we identify by tool prefix (matcher widened to `MCP:(bdt|ndt)_.*`). */
+const SERVER_BY_PREFIX = {
+    "MCP:bdt_": "browser-devtools",
+    "MCP:ndt_": "node-devtools",
+};
+const FALLBACK_MCP_SERVER_NAME = "browser-devtools";
 async function run(projectDir) {
     let input;
     try {
@@ -42,29 +48,38 @@ async function run(projectDir) {
     if (!verificationId) {
         const output = {
             permission: "deny",
-            agent_message: `BLOCKED: You must start a verification cycle before using browser-devtools tools.
+            agent_message: `BLOCKED: You must start a verification cycle before using devtools tools (browser-devtools or node-devtools).
 
 Start verification first:
   echo '{"session_id":"${sessionId}"}' | ironbee hook verification-start
 
-Then use browser tools to verify your changes.`,
+Then use the verification tools for the active cycle(s) — MCP:bdt_* for browser, MCP:ndt_* for node.`,
         };
         process.stdout.write(JSON.stringify(output));
         process.exit(2);
         return;
     }
-    // enforce recording if required (allow recording start tool through)
+    // Recording enforcement is browser-only (§12). Node-devtools tools
+    // (MCP:ndt_*) bypass this check entirely.
     const toolName = input.tool_name ?? "";
+    const isBrowserDevToolsCall = toolName.startsWith("MCP:bdt_");
     const isRecordingStartTool = toolName.endsWith("bdt_content_start-recording");
-    if ((0, session_state_1.isRecordingRequired)(sessionDir) && !(0, session_state_1.isRecordingActive)(sessionDir) && !isRecordingStartTool) {
+    if (isBrowserDevToolsCall &&
+        (0, session_state_1.isRecordingRequired)(sessionDir) &&
+        !(0, session_state_1.isRecordingActive)(sessionDir) &&
+        !isRecordingStartTool) {
         const output = {
             permission: "deny",
             agent_message: `BLOCKED: Recording is required but not started.
 
-Start recording first:
-  Use bdt_content_start-recording to begin recording.
+1. Start recording NOW:
+     Use MCP:bdt_content_start-recording
 
-Then use other browser tools to verify your changes.`,
+2. Run the verification (navigate, screenshot, aria, console, etc.)
+
+3. **Stop recording BEFORE submitting verdict:**
+     Use MCP:bdt_content_stop-recording
+   submit-verdict will reject with "recording is still active" if you skip this.`,
         };
         process.stdout.write(JSON.stringify(output));
         process.exit(2);
@@ -91,17 +106,28 @@ Then use other browser tools to verify your changes.`,
         verificationId,
         traceId,
         traceState,
+        // Stable wire id for the tool_call event. The MCP server reads this
+        // and uses it as the `id` of the event it POSTs to the collector.
+        // `ironbee import` reads the same field from the transcript and
+        // reuses it as the event id, so live and offline-derived events
+        // collapse on `(session_id, id)` collector dedup.
+        toolCallId: (0, crypto_1.randomUUID)(),
     };
     if (input.tool_use_id) {
         metadata.toolUseId = input.tool_use_id;
     }
-    // Cursor's postToolUse stdin doesn't expose the MCP server and its
-    // tool_name format (`MCP:bdt_*`) has no server segment. But the
-    // matcher restricts this hook to `MCP:bdt_.*` — i.e. we KNOW it's the
-    // browser-devtools MCP server by virtue of routing. Hardcode the name
-    // so MCP-emitted telemetry carries the same `mcp_server` dimension as
-    // on the Claude adapter.
-    metadata.mcpServer = MCP_SERVER_NAME;
+    // Cursor's preToolUse stdin doesn't expose the MCP server and its
+    // tool_name format (`MCP:<bare-tool>`) has no server segment. The
+    // matcher restricts this hook to `MCP:(bdt|ndt)_.*` — we identify the
+    // server by prefix lookup. Future runtimes extend SERVER_BY_PREFIX.
+    metadata.mcpServer = (() => {
+        for (const prefix of Object.keys(SERVER_BY_PREFIX)) {
+            if (toolName.startsWith(prefix)) {
+                return SERVER_BY_PREFIX[prefix];
+            }
+        }
+        return FALLBACK_MCP_SERVER_NAME;
+    })();
     const userEmail = (0, session_state_1.getUserEmail)(sessionDir);
     if (userEmail) {
         metadata.userEmail = userEmail;