devharness 0.9.8 → 0.9.10

package/docs/messages.md

@@ -1,6 +1,6 @@
-# cdp-tools Message Templates
+# devharness Message Templates
 
-This file contains all user-facing messages for the cdp-tools debugger. Messages use markdown formatting and support variable interpolation using `{{variable}}` syntax.
+This file contains all user-facing messages for the devharness debugger. Messages use markdown formatting and support variable interpolation using `{{variable}}` syntax.
 
 ## Template Usage Status
 
@@ -3631,7 +3631,7 @@ Note: `tools.enabled`/`tools.disabled` changes still require an MCP server resta
 **Type:** success
 **Summary:** Restart requested
 
-Sent a restart signal to the cdp-tools supervisor (PID {{pid}}). The server restarts shortly - no reconnect needed.
+Sent a restart signal to the devharness supervisor (PID {{pid}}). The server restarts shortly - no reconnect needed.
 
 Note: any Chrome instances this session launched will be killed (call `launchChrome` again). Managed dev servers (the `server` tool) survive and reattach automatically.
 
@@ -3881,6 +3881,97 @@ Cannot wait for {{condition}}: the debugger on "{{connectionReason}}" is paused
 
 ---
 
+## MESSAGE_SESSIONS
+
+**Type:** success
+**Summary:** {{count}} session(s) reachable
+
+This session is `{{self}}`. Its mailbox: `{{mailboxPath}}`
+
+{{sessionList}}
+
+**Note:** An arriving message announces itself on this session's event stream, `{{eventStreamPath}}`, which is also where guard blocks land - one watch covers both. The plugin's SessionStart hook prints that path and the `Monitor` call at the start of every session. Without a watch, messages surface only when `message({ action: 'read' })` runs. Nothing watches the mailbox file; it holds the conversation and the read cursor.
+
+---
+
+## MESSAGE_SENT
+
+**Type:** success
+**Summary:** Sent to {{to}}
+
+Message `{{shortId}}` appended to `{{mailboxPath}}`. The recipient sees it on `message({ action: 'read' })`, or immediately if it has a Monitor armed on its event stream.{{deliveryNote}}
+
+**Suggestions:**
+- To hold this call open until the other session answers: `message({ action: 'send', to: '{{to}}', text: '...', waitForReplyMs: 120000 })`
+
+---
+
+## MESSAGE_REPLY_RECEIVED
+
+**Type:** success
+**Summary:** {{count}} message(s) after {{elapsedMs}}ms
+
+{{messageList}}{{repeatNote}}
+
+**Suggestions:**
+- Answer with `message({ action: 'reply', replyTo: '<id>', text: '...' })`
+
+---
+
+## MESSAGE_INBOX
+
+**Type:** success
+**Summary:** {{count}} new of {{total}} in {{self}}
+
+{{messageList}}
+
+**Note:** Read advances a cursor, so the same message is returned once. The full history stays in `{{mailboxPath}}`.
+
+---
+
+## MESSAGE_REPLY_TIMEOUT
+
+**Type:** error
+**Code:** MESSAGE_REPLY_TIMEOUT
+
+Message `{{id}}` reached {{to}}, and nothing arrived in `{{self}}`'s mailbox within {{timeoutMs}}ms.
+
+**Suggestions:**
+- The other session is alive but was not calling devharness - it sees the message on its next `message({ action: 'read' })`
+- Check it is running: `message({ action: 'sessions' })`
+- Wait again without resending: `message({ action: 'read' })`, or send a follow-up with a longer `waitForReplyMs` (max 300000)
+- Its mailbox is `{{mailboxPath}}` - a Monitor on that file removes the need to poll
+
+---
+
+## MESSAGE_TARGET_UNKNOWN
+
+**Type:** error
+**Code:** MESSAGE_TARGET_UNKNOWN
+
+Cannot address "{{target}}": {{reason}}. This session is `{{self}}`.
+
+**Suggestions:**
+- List who is reachable: `message({ action: 'sessions' })`
+- A reply needs the id of a message in this session's own mailbox: `message({ action: 'read' })`
+
+---
+
+## MESSAGE_INVALID_ARGS
+
+**Type:** error
+**Code:** MESSAGE_INVALID_ARGS
+
+{{message}}
+
+**Suggestions:**
+- `message({ action: 'sessions' })` - who is reachable, and this session's mailbox path
+- `message({ action: 'send', to, text })` - write to another session
+- `message({ action: 'read' })` - take new messages
+- `message({ action: 'reply', replyTo, text })` - answer a message by id
+
+---
+
 ## CONFIG_USE_LOCAL_FAILED
 
 **Type:** error
@@ -3940,3 +4031,62 @@ Section "{{section}}" was not found in the page content.
 
 ---
 
+## WORKER_TARGETS_LISTED
+
+**Type:** success
+**Code:** WORKER_TARGETS_LISTED
+
+{{count}} worker target(s). Pass a target id, or a substring of its URL, as `target`.
+
+{{targets}}
+
+---
+
+## WORKER_EVALUATED
+
+**Type:** success
+**Code:** WORKER_EVALUATED
+
+Evaluated inside worker target "{{target}}".
+
+{{result}}
+
+---
+
+## WORKER_TARGET_NOT_FOUND
+
+**Type:** error
+**Code:** WORKER_TARGET_NOT_FOUND
+
+No worker target matches "{{target}}". Available: {{available}}
+
+---
+
+## WORKER_TARGET_AMBIGUOUS
+
+**Type:** error
+**Code:** WORKER_TARGET_AMBIGUOUS
+
+"{{target}}" matches more than one worker target: {{matches}}. Pass a target id instead.
+
+---
+
+## WORKER_EVALUATE_FAILED
+
+**Type:** error
+**Code:** WORKER_EVALUATE_FAILED
+
+Evaluating inside worker target "{{target}}" failed: {{error}}
+
+---
+
+## WORKER_CONSOLE_LISTED
+
+**Type:** success
+**Code:** WORKER_CONSOLE_LISTED
+
+{{count}} console message(s) from worker target "{{target}}".
+
+{{messages}}
+
+---

package/docs/parser-plugins.md

@@ -2,7 +2,7 @@
 
 `content({ action: 'parse' })` runs small, user-written parser plugins against
 the current page and returns their JSON output. Plugins are **not** shipped with
-cdp-tools — you write the ones you need.
+devharness — you write the ones you need.
 
 ## Usage
 

package/docs/replay.md

@@ -1183,7 +1183,7 @@ rendered in their own section — never merged into `results` or the
 successful/failed counts. A broken cleanup must not turn a passing run red, nor
 make a failing one look like it failed somewhere it did not.
 
-Teardown is best-effort by construction: a killed cdp-tools process takes any
+Teardown is best-effort by construction: a killed devharness process takes any
 pending teardown with it. It reduces accumulation; it cannot guarantee a clean
 world, so assertions that depend on absence remain order-dependent regardless.
 

package/docs/troubleshooting.md

@@ -8,7 +8,7 @@
 dev server has stopped - but the MCP connection still works.
 
 **Cause:** The session was suspended. With no request from the client for
-`session.idleSuspendMinutes` (default 120), cdp-tools releases what it holds
+`session.idleSuspendMinutes` (default 120), devharness releases what it holds
 and exits; the supervisor stays connected and started a fresh server for your
 next call.
 
@@ -24,7 +24,7 @@ released when no other live session claims it or is working in its directory.
 
 ### A dev server stopped when I opened a new session
 
-**Problem:** Starting cdp-tools in a project stopped a dev server that was
+**Problem:** Starting devharness in a project stopped a dev server that was
 already running.
 
 **Cause:** Every session that had claimed it was gone, so it was collected as
@@ -34,7 +34,7 @@ running until you reboot.
 **Solutions:**
 - Restart it (`server({ action: 'start', serverId: '...' })`).
 - To keep a server outside this lifecycle, run it yourself rather than through
-  the `server` tool; cdp-tools only collects servers it manages, and only ones
+  the `server` tool; devharness only collects servers it manages, and only ones
   it can prove nobody is left to use.
 
 ## Chrome Connection Issues

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devharness",
-  "version": "0.9.8",
+  "version": "0.9.10",
   "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",
@@ -22,6 +22,7 @@
     "test:coverage": "vitest run --coverage",
     "stress:suspend": "node scripts/stress-suspend.mjs",
     "check:targets": "node scripts/check-target-resume.mjs",
+    "check:workers": "node scripts/check-worker-eval.mjs",
     "prepublishOnly": "npm run test:run && npm run build:verify",
     "version": "node scripts/sync-skill-version.mjs",
     "postversion": "git push && git push --tags"

package/plugin/skills/devharness/SKILL.md

@@ -1,8 +1,8 @@
 ---
 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.8
+compatibility: Requires the devharness MCP server to be connected (tools such as launchChrome, breakpoint, inspect, replay, server, issues). The shell commands need `devharness` on PATH (`npm i -g devharness`); without it use `npx -y devharness@<version> <command>`. Previously published as cdp-tools-mcp.
+version: 0.9.10
 ---
 
 # devharness
@@ -27,6 +27,7 @@ Launched without a reference? `tab({ action: 'rename', reference: "unnamed-conne
 
 Paused: `inspect({ action: 'getCallStack' })` → `getVariables` → `evaluateExpression`.
 Watch: `console({ action: 'list' })`, `network({ action: 'list' })` (needs `network({ action: 'enable' })` first).
+Inside a worker: `inspect({ action: 'listTargets' })` → `evaluateExpression({ target, expression })`, and `console({ action: 'list', target })` — a service worker's console reaches no page listener.
 
 ## `.devharness/` must be git-ignored
 
@@ -63,22 +64,49 @@ 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
+## The event stream
 
-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`.
+Everything devharness pushes at you - a guard block, a message from another session - appends one JSON line to `~/.devharness/events/<sessionId>.jsonl`. One file, one watch, and any kind added later arrives on the same watch.
 
-Arm a Claude Code Monitor once, right after `launchChrome`/`server start`:
+Installed as a plugin, a `SessionStart` hook prints that path and the `Monitor` call at the top of every session. Arm it when you see it:
 
 ```
 Monitor({
-  command: "mkdir -p .devharness/logs && touch .devharness/logs/blocks.jsonl && tail -f -n0 .devharness/logs/blocks.jsonl",
-  description: "devharness guard blocks",
+  command: "mkdir -p ~/.devharness/events && touch <streamPath> && tail -f -n0 <streamPath>",
+  description: "devharness events",
   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.
+Nothing is lost without it: blocks and messages still surface on your next devharness call. The watch is what makes them arrive while you are doing something else, which for a dev server that died an hour ago is the difference that matters.
+
+Each line carries `kind` and, where there is one, `resolve` - the call that clears it. `kind: "block"` also carries `guard`, one of `port`, `breakpoint`, `pendingStartup`, `bug`, `duplicateSession`; blocks are deduplicated, one line per *new* block rather than one per blocked call. `kind: "message"` carries `from` and the message id.
+
+## Talking to another devharness session
+
+Two devharness sessions on this machine reach each other by mailbox id - the session hitting a devharness bug and the session working on devharness itself, for example.
+
+`message({ action: 'sessions' })` lists who is reachable and prints this session's own mailbox path.
+
+```
+message({ action: 'send', to: 'a1b2c3d4', text: 'Repro: ...', waitForReplyMs: 120000 })
+```
+
+That holds the call open until something lands in this session's mailbox, then returns it; answer with `message({ action: 'reply', replyTo: '<id>', text: '...' })`. The wait returns on ANY arrival, not only a tagged reply - two sessions blocking at the same moment both release instead of both timing out.
+
+An arriving message announces itself on the event stream, so the watch above covers it and there is no second watch to arm. `message({ action: 'read' })` is what takes them, advancing a cursor so each is returned once; the full history stays in the mailbox file.
+
+## Running a tool from the shell
+
+`devharness <command>` typed in a session's shell runs that tool **inside that session**, against the connections it already holds. The plugin does not put `devharness` on PATH - `npm i -g devharness` does, or run it as `npx -y devharness@<version> <command>`. The SessionStart hook reports which of those applies here. The session is found by walking up the process tree, so `! devharness screenshot` uses the browser this session opened, not a new one.
+
+- `devharness which` - which session this shell resolves to
+- `devharness call <tool> '<json>'` - any tool: `devharness call config '{"action":"status"}'`
+- `devharness sessions` / `send <id> "text"` / `read` / `reply <id> "text"` - the message tool, with `--wait=<ms>` to hold for an answer
+- `--session=<id>` names a session explicitly, `--json` prints the raw response, `--timeout=<ms>` bounds the call
+
+Two differences from an MCP call. Guards do not apply - a dead dev server port, a paused breakpoint or a pending bug blocks a tool call through MCP and does not block this one. And a session the supervisor has suspended is not listening, so the CLI reports that rather than waiting.
 
 ## Restarting devharness
 

package/plugin/skills/devharness/references/sequences.md

@@ -1,6 +1,6 @@
 # Replay Sequences
 
-A sequence is an ordered list of tool calls you can re-run. It's how cdp-tools
+A sequence is an ordered list of tool calls you can re-run. It's how devharness
 turns "I clicked around and hit the bug" into something repeatable - a
 regression test, a repro attached to an issue, or a multi-step automation.
 
@@ -590,7 +590,7 @@ A failing teardown step never changes the run's verdict; it is reported in its
 own section. Otherwise a broken cleanup would mask the failure it was cleaning up
 after.
 
-**Teardown is always best-effort.** A killed cdp-tools process takes any pending
+**Teardown is always best-effort.** A killed devharness process takes any pending
 teardown with it, so it reduces accumulation and cannot guarantee a clean world.
 An assertion that depends on nothing being left over ("No assets yet") stays
 order-dependent whether or not teardown exists - mint your own fixture and assert

package/plugin/skills/devharness/references/tool-categories.md

@@ -22,13 +22,15 @@ runs against (see the skill's Quick Start).
 
 **Execution**: `execution` (actions: pause, resume, stepOver, stepInto, stepOut, acknowledge)
 
-**Inspection**: `inspect` (actions: getCallStack, getVariables, evaluateExpression, searchCode, searchFunctions)
+**Inspection**: `inspect` (actions: getCallStack, getVariables, evaluateExpression, searchCode, searchFunctions, listTargets)
+- `listTargets` lists the service, dedicated and shared worker targets on this browser. `evaluateExpression({ target })` runs the expression inside one of them, addressed by target id or by a substring of its URL - a substring matching two targets is refused with both named. A worker's console reaches no page listener, so `console({ action: 'list' | 'recent', target })` reads it from that target; recording starts at first attach
 - `evaluateExpression` awaits a returned Promise by default (async IIFEs resolve to their settled value; a rejection is reported as the expression's own error). Pass `awaitPromise: false` to inspect the Promise object itself. While paused at a breakpoint only already-settled promises can be resolved - a pending one fails fast because the event loop is stopped
 
 **Source**: `getSourceCode`, `loadSourceMaps`
 - Individual tools, not actions
 
 **Console**: `console` (actions: list, get, recent, search, clear, setObjectDepth)
+- `target` on `list` and `recent` reads a worker's console instead of the page's
 
 **Network**: `network` (actions: list, get, search, enable, disable, setConditions)
 
@@ -75,9 +77,14 @@ runs against (see the skill's Quick Start).
 - `pullSequence` writes a sequence out of an issue to disk. Nothing is written until you ask, and nothing is ever run automatically: sequence steps are `{tool, params}` for **any** tool, so a sequence in a public issue is a script, not a macro. One authored by a GitHub account other than the one `gh` is logged in as is refused until a **person** has read it and re-run with `confirm: true` - an agent must not confirm on its own. One using `execution`, `saveToDisk`, `server`, `request` or `download` is refused unless you pass `allowPrivilegedSteps: true`. Read the step list in the response before you do
 - All of these are blocked while any bug is `pending` - `acknowledge` first
 
+**Messages**: `message` (actions: sessions, send, read, reply)
+- Text between two devharness sessions on this machine - a session hitting a devharness bug talking to the session working on devharness itself. `sessions` lists reachable mailboxes and this session's own mailbox path
+- `send({ to, text, waitForReplyMs })` holds the call open until something lands in this session's mailbox (max 300000ms) and returns it; without `waitForReplyMs` it returns as soon as the line is written. `reply({ replyTo, text })` routes back to the sender of that message. The wait returns on ANY arrival, not only a tagged reply, so two sessions blocking at the same moment both release
+- The mailbox is one append-only JSONL file per session under `~/.devharness/messages/`, holding the conversation and the read cursor; the global directory is what makes it reach across project roots. Nothing watches it. An arrival announces itself on that session's event stream, `~/.devharness/events/<id>.jsonl`, so one watch covers messages and guard blocks alike; without one, messages surface on the next `message({ action: 'read' })`
+
 **Server**: `server` (actions: start, stop, restart, list, logs, stopAll, setAutoRun, clearLogs, remove, monitorPort, unmonitorPort, listMonitored, acknowledgePort, acknowledgeStartup, extendStartup, cancelPendingRestart)
 - Use `global: true` to access servers started from a different working directory
-- `start({ watch: true, watchPaths?: [...] })`: cdp-tools watches the given paths (default: cwd) and auto-restarts the server on file changes, instead of relying on `--watch`/nodemon. Pause-aware: if a breakpoint debugger is paused on that server's inspector port, the restart queues instead of firing immediately - `cancelPendingRestart` discards a queued restart to keep debugging without it firing on resume
+- `start({ watch: true, watchPaths?: [...] })`: devharness watches the given paths (default: cwd) and auto-restarts the server on file changes, instead of relying on `--watch`/nodemon. Pause-aware: if a breakpoint debugger is paused on that server's inspector port, the restart queues instead of firing immediately - `cancelPendingRestart` discards a queued restart to keep debugging without it firing on resume
 
 **Replay**: `replay` (actions: history, create, list, get, delete, export, load, listSaved, deleteSaved, run, runAll, step, finish, insert, addConditional, status, cancel, repeat, runFromLog, recordInteraction)
 - `recordInteraction`: record mouse, keyboard, and navigation events with a visual overlay
@@ -101,6 +108,6 @@ runs against (see the skill's Quick Start).
 - `show`: Display current configuration
 - `listTools`: List all toggleable tools with status and dependency conflicts
 - `reload`: Re-read config.json now (also happens automatically on file edits, ~250ms debounce). Doesn't apply `tools.enabled`/`tools.disabled` - those need `restart`
-- `restart`: Restart cdp-tools itself via the mcp-supervisor (see "Restarting cdp-tools" above) - use when the server seems stuck/broken, or to apply `tools.enabled`/`tools.disabled` changes
+- `restart`: Restart devharness itself via the mcp-supervisor (see "Restarting devharness" above) - use when the server seems stuck/broken, or to apply `tools.enabled`/`tools.disabled` changes
 - `listProfiles`: List named persistent Chrome profiles and the root they live under
 - `resetProfile`: Wipe and recreate a named profile (`config({ action: 'resetProfile', profile: 'device-a' })`). Refused while a live Chrome holds that profile - nothing is deleted in that case