devharness 0.9.8 → 0.9.9

package/build/worker-targets.js

@@ -0,0 +1,171 @@
+/**
+ * Worker targets - service workers, dedicated workers, shared workers.
+ *
+ * Every debugging tool runs against the page target, so code inside a worker
+ * has been unreachable: no evaluation, no console. A worker is its own CDP
+ * target with its own websocket, listed by the browser alongside the page, so
+ * a client per worker reaches it without touching the page's debugger state.
+ */
+import CDP from 'chrome-remote-interface';
+/** The three target types that run script outside the page. */
+const WORKER_TYPES = ['service_worker', 'worker', 'shared_worker'];
+export class WorkerTargetNotFoundError extends Error {
+    ref;
+    available;
+    constructor(ref, available) {
+        super(`No worker target matches "${ref}"`);
+        this.ref = ref;
+        this.available = available;
+        this.name = 'WorkerTargetNotFoundError';
+    }
+}
+export class WorkerTargetAmbiguousError extends Error {
+    ref;
+    matches;
+    constructor(ref, matches) {
+        super(`"${ref}" matches ${matches.length} worker targets`);
+        this.ref = ref;
+        this.matches = matches;
+        this.name = 'WorkerTargetAmbiguousError';
+    }
+}
+export class WorkerEvaluateError extends Error {
+    details;
+    constructor(message, details) {
+        super(message);
+        this.details = details;
+        this.name = 'WorkerEvaluateError';
+    }
+}
+/** Console output is capped per target; a chatty worker cannot grow unbounded. */
+const MAX_MESSAGES = 200;
+/**
+ * One browser's worker targets. Keyed by host and port, since that pair is
+ * what locates a target's websocket.
+ */
+export class WorkerTargetRegistry {
+    host;
+    port;
+    listTargets;
+    connect;
+    attached = new Map();
+    constructor(host, port, listTargets = CDP.List, connect = CDP) {
+        this.host = host;
+        this.port = port;
+        this.listTargets = listTargets;
+        this.connect = connect;
+    }
+    async list() {
+        const targets = await this.listTargets({ host: this.host, port: this.port });
+        return targets
+            .filter((t) => WORKER_TYPES.includes(t.type))
+            .map((t) => ({
+            targetId: t.id,
+            type: t.type,
+            url: t.url,
+            attached: this.attached.has(t.id),
+        }));
+    }
+    /**
+     * A target id, or a substring of a target's URL. A substring matching more
+     * than one target is refused with both named - picking the first would
+     * evaluate in a worker the caller did not choose.
+     */
+    async resolve(ref) {
+        const targets = await this.list();
+        const byId = targets.find((t) => t.targetId === ref);
+        if (byId)
+            return byId;
+        const matches = targets.filter((t) => t.url.includes(ref));
+        if (matches.length === 1)
+            return matches[0];
+        if (matches.length === 0)
+            throw new WorkerTargetNotFoundError(ref, targets);
+        throw new WorkerTargetAmbiguousError(ref, matches);
+    }
+    /**
+     * Evaluate inside the worker. Console output from the target is recorded
+     * from the moment of first attach, so a log emitted before that is not held.
+     */
+    async evaluate(ref, expression, awaitPromise = true) {
+        const target = await this.resolve(ref);
+        const worker = await this.attach(target);
+        const result = await worker.client.Runtime.evaluate({
+            expression,
+            returnByValue: true,
+            awaitPromise,
+        });
+        if (result.exceptionDetails) {
+            const thrown = result.exceptionDetails.exception;
+            throw new WorkerEvaluateError(thrown?.description || thrown?.value || result.exceptionDetails.text, result.exceptionDetails.text);
+        }
+        return result.result?.value;
+    }
+    /** Console output recorded since this target was first attached. */
+    async messages(ref) {
+        const target = await this.resolve(ref);
+        const worker = await this.attach(target);
+        return [...worker.messages];
+    }
+    async attach(target) {
+        const existing = this.attached.get(target.targetId);
+        if (existing)
+            return existing;
+        const client = await this.connect({ host: this.host, port: this.port, target: target.targetId });
+        const worker = { client, messages: [] };
+        const record = (type, text) => {
+            worker.messages.push({ type, text, timestamp: Date.now() });
+            if (worker.messages.length > MAX_MESSAGES)
+                worker.messages.shift();
+        };
+        client.Runtime.consoleAPICalled((e) => {
+            record(e.type, (e.args || []).map(describeArg).join(' '));
+        });
+        client.Runtime.exceptionThrown((e) => {
+            const thrown = e.exceptionDetails?.exception;
+            record('error', thrown?.description || e.exceptionDetails?.text || 'exception');
+        });
+        await client.Runtime.enable();
+        this.attached.set(target.targetId, worker);
+        return worker;
+    }
+    /** Closes every client. A client left open holds its worker alive. */
+    async dispose() {
+        const workers = [...this.attached.values()];
+        this.attached.clear();
+        for (const worker of workers) {
+            try {
+                await worker.client.close();
+            }
+            catch {
+                // Its target is already gone; the socket went with it.
+            }
+        }
+    }
+}
+function describeArg(arg) {
+    if (arg.value !== undefined)
+        return typeof arg.value === 'string' ? arg.value : JSON.stringify(arg.value);
+    return arg.description || arg.className || arg.type || '';
+}
+const registries = new Map();
+/** One registry per browser, so a second call reuses the open clients. */
+export function getWorkerTargetRegistry(host, port) {
+    const key = `${host}:${port}`;
+    const existing = registries.get(key);
+    if (existing)
+        return existing;
+    const registry = new WorkerTargetRegistry(host, port);
+    registries.set(key, registry);
+    return registry;
+}
+/** Called when a connection closes: its browser's clients go with it. */
+export async function disposeWorkerTargetRegistry(host, port) {
+    const key = `${host}:${port}`;
+    const registry = registries.get(key);
+    if (!registry)
+        return;
+    registries.delete(key);
+    await registry.dispose();
+}
+//# sourceMappingURL=worker-targets.js.map

package/build/worker-targets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-targets.js","sourceRoot":"","sources":["../src/worker-targets.ts"],"names":[],"mappings":"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"}

package/build/worker-targets.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A worker's script runs in its own target, so a reference has to name exactly
+ * one. A substring matching two targets resolved to the first would evaluate
+ * inside a worker the caller did not choose, and a client left open holds its
+ * worker alive past the browser that owned it - these pin both.
+ */
+export {};
+//# sourceMappingURL=worker-targets.test.d.ts.map

package/build/worker-targets.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-targets.test.d.ts","sourceRoot":"","sources":["../src/worker-targets.test.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/build/worker-targets.test.js

@@ -0,0 +1,118 @@
+/**
+ * A worker's script runs in its own target, so a reference has to name exactly
+ * one. A substring matching two targets resolved to the first would evaluate
+ * inside a worker the caller did not choose, and a client left open holds its
+ * worker alive past the browser that owned it - these pin both.
+ */
+import { describe, it, expect } from 'vitest';
+import { WorkerTargetRegistry, WorkerTargetNotFoundError, WorkerTargetAmbiguousError, WorkerEvaluateError, } from './worker-targets.js';
+const TARGETS = [
+    { id: 'page-1', type: 'page', url: 'http://localhost:5173/' },
+    { id: 'sw-1', type: 'service_worker', url: 'http://localhost:5173/sw.js' },
+    { id: 'w-1', type: 'worker', url: 'http://localhost:5173/worker.js' },
+    { id: 'w-2', type: 'worker', url: 'http://localhost:5173/second-worker.js' },
+];
+function fakeClient(evaluate) {
+    const client = {
+        closed: false,
+        handlers: {},
+        Runtime: {
+            enable: async () => { },
+            evaluate: async (params) => (evaluate ? evaluate(params) : { result: { value: 'ok' } }),
+            consoleAPICalled: (h) => { client.handlers.console = h; },
+            exceptionThrown: (h) => { client.handlers.exception = h; },
+        },
+        close: async () => { client.closed = true; },
+    };
+    return client;
+}
+function registry(options = {}) {
+    const clients = [];
+    const connect = async () => {
+        const client = fakeClient(options.evaluate);
+        clients.push(client);
+        return client;
+    };
+    const instance = new WorkerTargetRegistry('localhost', 9222, async () => options.targets ?? TARGETS, connect);
+    return { instance, clients };
+}
+describe('WorkerTargetRegistry.list', () => {
+    it('lists only targets that run script outside the page', async () => {
+        const { instance } = registry();
+        const types = (await instance.list()).map((t) => t.type);
+        expect(types).toEqual(['service_worker', 'worker', 'worker']);
+    });
+    it('marks a target attached once a client is open on it', async () => {
+        const { instance } = registry();
+        await instance.evaluate('sw-1', '1');
+        const sw = (await instance.list()).find((t) => t.targetId === 'sw-1');
+        expect(sw?.attached).toBe(true);
+    });
+});
+describe('WorkerTargetRegistry.resolve', () => {
+    it('takes a target id', async () => {
+        const { instance } = registry();
+        expect((await instance.resolve('sw-1')).url).toBe('http://localhost:5173/sw.js');
+    });
+    it('takes a URL substring that matches one target', async () => {
+        const { instance } = registry();
+        expect((await instance.resolve('sw.js')).targetId).toBe('sw-1');
+    });
+    it('refuses a substring matching more than one, naming both', async () => {
+        const { instance } = registry();
+        await expect(instance.resolve('worker.js')).rejects.toBeInstanceOf(WorkerTargetAmbiguousError);
+        const error = await instance.resolve('worker.js').catch((e) => e);
+        expect(error.matches.map((t) => t.targetId)).toEqual(['w-1', 'w-2']);
+    });
+    it('refuses a reference matching nothing, listing what there is', async () => {
+        const { instance } = registry();
+        const error = await instance.resolve('absent.js').catch((e) => e);
+        expect(error).toBeInstanceOf(WorkerTargetNotFoundError);
+        expect(error.available.map((t) => t.targetId)).toEqual(['sw-1', 'w-1', 'w-2']);
+    });
+});
+describe('WorkerTargetRegistry.evaluate', () => {
+    it('returns the by-value result', async () => {
+        const { instance } = registry({ evaluate: () => ({ result: { value: 'ServiceWorkerGlobalScope' } }) });
+        expect(await instance.evaluate('sw-1', 'self.constructor.name')).toBe('ServiceWorkerGlobalScope');
+    });
+    it('raises what the worker threw', async () => {
+        const { instance } = registry({
+            evaluate: () => ({ exceptionDetails: { text: 'Uncaught', exception: { description: 'TypeError: nope' } } }),
+        });
+        await expect(instance.evaluate('sw-1', 'nope()')).rejects.toBeInstanceOf(WorkerEvaluateError);
+    });
+    it('opens one client per target, however many evaluations', async () => {
+        const { instance, clients } = registry();
+        await instance.evaluate('sw-1', '1');
+        await instance.evaluate('sw-1', '2');
+        expect(clients).toHaveLength(1);
+    });
+});
+describe('WorkerTargetRegistry console', () => {
+    it('records console output from the target', async () => {
+        const { instance, clients } = registry();
+        await instance.evaluate('sw-1', '1');
+        clients[0].handlers.console({ type: 'log', args: [{ value: 'inside' }, { value: 42 }] });
+        const messages = await instance.messages('sw-1');
+        expect(messages.map((m) => m.text)).toEqual(['inside 42']);
+    });
+    it('records an exception thrown in the target as an error', async () => {
+        const { instance, clients } = registry();
+        await instance.evaluate('sw-1', '1');
+        clients[0].handlers.exception({ exceptionDetails: { exception: { description: 'TypeError: nope' } } });
+        const messages = await instance.messages('sw-1');
+        expect(messages[0]).toMatchObject({ type: 'error', text: 'TypeError: nope' });
+    });
+});
+describe('WorkerTargetRegistry.dispose', () => {
+    it('closes every client it opened', async () => {
+        const { instance, clients } = registry();
+        await instance.evaluate('sw-1', '1');
+        await instance.evaluate('w-1', '1');
+        await instance.dispose();
+        expect(clients.map((c) => c.closed)).toEqual([true, true]);
+        expect((await instance.list()).every((t) => !t.attached)).toBe(true);
+    });
+});
+//# sourceMappingURL=worker-targets.test.js.map

package/build/worker-targets.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-targets.test.js","sourceRoot":"","sources":["../src/worker-targets.test.ts"],"names":[],"mappings":"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"}

package/docs/instructions.md

@@ -59,6 +59,9 @@ Chrome DevTools Protocol debugging for JavaScript/TypeScript in Chrome, Node.js,
 - Note: DOM breakpoints use nodeIds which are invalidated on page reload
 
 **Code search:**
+- `inspect({ action: 'listTargets' })`: List worker targets (service, dedicated, shared)
+- `inspect({ action: 'evaluateExpression', target })`: Evaluate inside a worker, addressed by target id or a URL substring
+- `console({ action: 'list', target })`: Read a worker's console, which reaches no page listener
 - `inspect({ action: 'searchCode' })`: Find patterns
 - `inspect({ action: 'searchFunctions' })`: Locate definitions
 - `getSourceCode`: View context
@@ -120,28 +123,31 @@ 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
+## The event stream
 
-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`:
+Everything devharness pushes - a guard block, a message from another session - appends one JSON line to `~/.devharness/events/<sessionId>.jsonl`. One file per session, so one watch covers every kind, including kinds added later.
 
-```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:
+Installed as a plugin, a `SessionStart` hook (`plugin/hooks/session-start.mjs`) creates that file and prints the `Monitor` call as session context before the first turn. In Claude Code, arm 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
 })
 ```
 
-Any other client can watch the same file. `-n0` skips existing history so you only see blocks from that point on.
+Nothing is lost without a watch - blocks and messages still surface on the next tool call. The watch is what makes them arrive while the session is doing something else.
+
+Line kinds:
+
+```json
+{"ts":"...","kind":"block","guard":"pendingStartup","tool":"navigate","detail":"died before port detected: \"web\"","resolve":"server({ action: 'acknowledgeStartup', serverId: 'web' })"}
+{"ts":"...","kind":"message","from":"66ba2d65","id":"d94924a8-...","detail":"Message from 66ba2d65: ...","resolve":"message({ action: 'read' })"}
+```
+
+`guard` is one of `port`, `breakpoint`, `pendingStartup`, `bug`, `duplicateSession`. Blocks are deduplicated: one line per *new* block, not one per blocked call. Any client can tail the file.
 
 ## Restarting devharness
 
@@ -218,6 +224,11 @@ runs against (see Quick Start).
 - **GitHub** (via the `gh` CLI; only `publish` and `sync` use the network): `publish` shows a draft and posts nothing until `confirm: true`; `sync` reconciles both ways and reports a conflict rather than overwriting when both sides changed; `import` materialises a GitHub-only issue locally; `link` stamps an existing number with no network call; `pullSequence` writes a sequence out of an issue body to disk (one authored by another GitHub account needs a person to read it and pass `confirm: true`)
 - A sequence pulled from an issue is **never run automatically**, and one using `execution`, `saveToDisk`, `server`, `request` or `download` is refused unless you pass `allowPrivilegedSteps: true`. Read it 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
+- Transport is one append-only JSONL file per session under `~/.devharness/messages/`, which is what makes it work across project roots. A busy session needs a Monitor armed on its mailbox file to be interrupted; otherwise messages surface on its 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

package/docs/messages.md

@@ -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:** To receive a message while doing other work, arm a Monitor on this session's mailbox file - it appends one JSON line per message, so a `tail -f` style watch fires the moment one lands. Without a Monitor, messages surface only when `message({ action: 'read' })` runs.
+
+---
+
+## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devharness",
-  "version": "0.9.8",
+  "version": "0.9.9",
   "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.9
 ---
 
 # 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