devharness 0.9.3 → 0.9.4

package/build/tools/wait-tools.d.ts

@@ -49,19 +49,19 @@ export declare function createWaitTools(resolveConnectionFromReason: (connection
             pollIntervalMs: z.ZodOptional<z.ZodNumber>;
             connectionReason: z.ZodOptional<z.ZodString>;
         }, "strict", z.ZodTypeAny, {
-            timeoutMs?: number | undefined;
-            expression?: string | undefined;
             selector?: string | undefined;
             selectorGone?: string | undefined;
+            expression?: string | undefined;
             ms?: number | undefined;
+            timeoutMs?: number | undefined;
             connectionReason?: string | undefined;
             pollIntervalMs?: number | undefined;
         }, {
-            timeoutMs?: number | undefined;
-            expression?: string | undefined;
             selector?: string | undefined;
             selectorGone?: string | undefined;
+            expression?: string | undefined;
             ms?: number | undefined;
+            timeoutMs?: number | undefined;
             connectionReason?: string | undefined;
             pollIntervalMs?: number | undefined;
         }>;
@@ -72,11 +72,11 @@ export declare function createWaitTools(resolveConnectionFromReason: (connection
             } | undefined;
         };
         handler: (args: {
-            timeoutMs?: number | undefined;
-            expression?: string | undefined;
             selector?: string | undefined;
             selectorGone?: string | undefined;
+            expression?: string | undefined;
             ms?: number | undefined;
+            timeoutMs?: number | undefined;
             connectionReason?: string | undefined;
             pollIntervalMs?: number | undefined;
         }, abortSignal?: AbortSignal) => Promise<any>;

package/docs/instructions.md

@@ -120,6 +120,29 @@ Chrome DevTools Protocol debugging for JavaScript/TypeScript in Chrome, Node.js,
 - **Missing/invalid parameters**: the error includes a `continuationToken` and `missingParameters` (name/type/description/enum). Retry with just `{ continuationToken, <missing/bad field(s)> }` - don't resend everything. Expires after 5 min.
 - **A validated call gets blocked by a guard** (port failure, dead server, breakpoint pause): the response footer shows `**Repeat:** replay({ action: 'repeat', indices: [N] })`. Acknowledge the guard (e.g. `server({ action: 'acknowledgePort' })`), then use that hint to resume the exact call. Don't reuse a `continuationToken` here - that's for fixing bad input, not for retrying an already-valid call.
 
+## Getting notified when a guard blocks
+
+Guards only surface on the *next* tool call, so a server that dies while you're editing files stays invisible until you call back into devharness. Every new block also appends one JSON line to `.devharness/logs/blocks.jsonl`:
+
+```json
+{"ts":"2026-08-08T03:21:45.588Z","guard":"pendingStartup","tool":"navigate","detail":"died before port detected: \"web\"","resolve":"server({ action: 'acknowledgeStartup', serverId: 'web' })"}
+```
+
+`guard` is one of `port`, `breakpoint`, `pendingStartup`, `bug`, `duplicateSession`. Lines are deduplicated: one per *new* block, not one per blocked call. The same block re-firing on later calls stays quiet until a call clears every guard and the block recurs.
+
+In Claude Code, tail it with a persistent Monitor so blocks arrive as notifications while you work on something else:
+
+```
+Monitor({
+  command: "mkdir -p .devharness/logs && touch .devharness/logs/blocks.jsonl && tail -f -n0 .devharness/logs/blocks.jsonl",
+  description: "devharness guard blocks",
+  persistent: true,
+  timeout_ms: 3600000
+})
+```
+
+Any other client can watch the same file. `-n0` skips existing history so you only see blocks from that point on.
+
 ## Restarting devharness
 
 If devharness itself seems stuck or broken (not the target app), restart it yourself rather than asking the user to reconnect: `config({ action: 'restart' })`. Falls back to `kill -USR2 $(cat .devharness/mcp-supervisor.pid)` via Bash if that action reports `CONFIG_RESTART_NOT_SUPERVISED` (e.g. a bare `node build/index.js`, not through the supervisor). Editing devharness's own source and running `npm run build` triggers the same restart automatically via its postbuild hook - `config({ action: 'status' })` reports which build is actually answering (entry file, its timestamp, server and supervisor pids), so a rebuild that signalled the wrong supervisor is visible rather than silent. Either way, this kills any Chrome instances it launched (relaunch with `launchChrome`) but managed dev servers (`server` tool) survive and reattach automatically.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devharness",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "description": "MCP server that connects AI assistants to Chrome DevTools Protocol for runtime debugging - set breakpoints, inspect variables, monitor network traffic, and automate browser interactions",
   "type": "module",
   "main": "build/index.js",

package/plugin/skills/devharness/SKILL.md

@@ -2,7 +2,7 @@
 name: devharness
 description: Drive and debug a running app via the devharness MCP server - launch or attach to Chrome and Node.js, set breakpoints and logpoints, inspect call stacks and variables, watch console and network, manage dev servers, replay any earlier tool call by its history index, and record reproduction sequences that verify a fix. Use whenever a task involves running or debugging a live app, reproducing or verifying a bug, re-driving setup you already did (relaunching, re-logging in, refilling a form), or the user mentions breakpoints, Chrome DevTools, CDP, replay sequences, or devharness tools (launchChrome, navigate, breakpoint, inspect, replay, server, issues, etc.).
 compatibility: Requires the devharness MCP server to be connected (tools such as launchChrome, breakpoint, inspect, replay, server, issues). Previously published as cdp-tools-mcp.
-version: 0.9.3
+version: 0.9.4
 ---
 
 # devharness
@@ -63,6 +63,23 @@ Server merges and re-validates. Same token, repeat until it passes. Expires in 5
 
 **Guard blocked a valid call** (dead port, breakpoint pause) → it was already recorded. Acknowledge (`server({ action: 'acknowledgePort' })`, `acknowledgeStartup`), then use the footer's `replay` hint. Don't rebuild the arguments; don't use a `continuationToken` here.
 
+## Get told the moment a guard blocks
+
+Guards only surface on your *next* devharness call, so a server that dies while you're editing files stays invisible until you happen to call back. Every new block also appends one JSON line to `.devharness/logs/blocks.jsonl` — `{ts, guard, tool, detail, resolve}`, one of `port`, `breakpoint`, `pendingStartup`, `bug`, `duplicateSession`.
+
+Arm a Claude Code Monitor once, right after `launchChrome`/`server start`:
+
+```
+Monitor({
+  command: "mkdir -p .devharness/logs && touch .devharness/logs/blocks.jsonl && tail -f -n0 .devharness/logs/blocks.jsonl",
+  description: "devharness guard blocks",
+  persistent: true,
+  timeout_ms: 3600000
+})
+```
+
+`-n0` skips history — you only want blocks from now on. One line per *new* block, not per blocked call; the same block re-firing stays quiet until a call gets through all guards and it recurs. Act on the event's `resolve` field.
+
 ## Restarting devharness
 
 If devharness itself is stuck (not the target app), restart it — don't wait to be asked.