devharness 0.9.8 → 0.9.10

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

@@ -0,0 +1 @@
+{"version":3,"file":"worker-targets.d.ts","sourceRoot":"","sources":["../src/worker-targets.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,+DAA+D;AAC/D,QAAA,MAAM,YAAY,wDAAyD,CAAC;AAE5E,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,gBAAgB,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,gEAAgE;IAChE,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,yBAA0B,SAAQ,KAAK;IAC/B,GAAG,EAAE,MAAM;IAAS,SAAS,EAAE,YAAY,EAAE;gBAA7C,GAAG,EAAE,MAAM,EAAS,SAAS,EAAE,YAAY,EAAE;CAIjE;AAED,qBAAa,0BAA2B,SAAQ,KAAK;IAChC,GAAG,EAAE,MAAM;IAAS,OAAO,EAAE,YAAY,EAAE;gBAA3C,GAAG,EAAE,MAAM,EAAS,OAAO,EAAE,YAAY,EAAE;CAI/D;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IACR,OAAO,CAAC,EAAE,MAAM;gBAAxC,OAAO,EAAE,MAAM,EAAS,OAAO,CAAC,EAAE,MAAM,YAAA;CAIrD;AAUD;;;GAGG;AACH,qBAAa,oBAAoB;IAI7B,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,IAAI;IACZ,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,OAAO;IANjB,OAAO,CAAC,QAAQ,CAA0C;gBAGhD,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,WAAW,GAAE,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,GAAG,EAAE,CAAY,EACnF,OAAO,GAAE,CAAC,OAAO,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAO;IAGjD,IAAI,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAYrC;;;;OAIG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAUjD;;;OAGG;IACG,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,UAAO,GAAG,OAAO,CAAC,GAAG,CAAC;IAkBlF,oEAAoE;IAC9D,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC;YAM9C,MAAM;IAsBpB,sEAAsE;IAChE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAW/B;AASD,0EAA0E;AAC1E,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,oBAAoB,CAOxF;AAED,yEAAyE;AACzE,wBAAsB,2BAA2B,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAM3F"}

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/README.md

@@ -33,7 +33,7 @@ You don't have to set this up by hand: on startup, the server checks whether the
 
 ```bash
 # Claude Code CLI
-claude mcp add cdp-tools -- npx -y devharness
+claude mcp add devharness -- npx -y devharness
 ```
 
 ```javascript
@@ -61,7 +61,7 @@ devharness supports multiple simultaneous connections:
 
 ### Smart Element Caching
 
-When you navigate to a page, cdp-tools automatically:
+When you navigate to a page, devharness automatically:
 
 1. **Caches all clickable elements** - Links, buttons, and inputs are discovered and stored
 2. **Records viewport positions** - Tracks which elements are visible

package/docs/automation.md

@@ -500,7 +500,7 @@ server({ action: 'stop', serverId: 'my-app', global: true })
 
 ## Configuration Management
 
-Manage cdp-tools configuration across projects:
+Manage devharness configuration across projects:
 
 ```javascript
 // Check where config is loaded from

package/docs/installation.md

@@ -3,7 +3,7 @@
 ## Claude Code CLI
 
 ```bash
-claude mcp add cdp-tools -- npx -y devharness
+claude mcp add devharness -- npx -y devharness
 ```
 
 ## Claude Desktop
@@ -17,7 +17,7 @@ Add to your config file:
 ```json
 {
   "mcpServers": {
-    "cdp-tools": {
+    "devharness": {
       "command": "npx",
       "args": ["-y", "devharness"]
     }
@@ -71,7 +71,7 @@ The `defaultDebugPort` sets the starting port for Chrome debugging. If the port
 
 ### Idle Sessions
 
-An editor window left open for days keeps its cdp-tools server alive, holding
+An editor window left open for days keeps its devharness server alive, holding
 Chrome instances, dev servers and monitor buffers nobody is using. Two things
 stop that:
 
@@ -90,7 +90,7 @@ stop that:
 - **Abandoned dev servers are collected.** A window closed for good used to
   leave its dev servers running until reboot. The next session in that
   directory now stops any whose owning sessions are all gone.
-- **Orphan reaping.** When the client that launched cdp-tools is gone, the
+- **Orphan reaping.** When the client that launched devharness is gone, the
   server tree shuts itself down, rather than waiting for a stdin EOF that never
   arrives when an `npm exec` wrapper is holding the pipe open.
 

package/docs/instructions.md

@@ -1,4 +1,4 @@
-# cdp-tools Debugger Usage
+# devharness Debugger Usage
 
 Chrome DevTools Protocol debugging for JavaScript/TypeScript in Chrome, Node.js, or CDP-compatible environments.
 
@@ -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,9 +224,14 @@ 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
+- 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
@@ -247,6 +258,6 @@ runs against (see 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 devharness" 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

package/docs/message-system.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-The cdp-tools debugger uses a centralized message system to provide consistent, markdown-formatted responses to all tool calls. This guide explains how to use the system and when to use different patterns.
+The devharness debugger uses a centralized message system to provide consistent, markdown-formatted responses to all tool calls. This guide explains how to use the system and when to use different patterns.
 
 ## Architecture