@peekdev/mcp 0.1.0-alpha.12 → 0.1.0-alpha.14

package/README.md

@@ -30,7 +30,7 @@ Read on if you're configuring the MCP server manually, building tooling against
 ## What this is NOT
 
 - Not a remote MCP server. Peek is **local-only**: stdio transport over a child-process pipe. There is no HTTP listener, no SSE endpoint, no remote auth. The MCP transport spec's Streamable HTTP variant is out of scope by design.
-- Not a write-by-default tool. Read tools are unauthenticated. The write tools (`execute_action`, `request_authorization`) are defined on the MCP surface and gated by the permission model + destructive blocklist + audit-log writer — but the cross-process IPC that delivers them to the browser native host is **in development**. Calling `execute_action` against `peek-mcp@0.1.0-alpha.10` returns `bridge not wired in this MCP process`; peek is effectively read-only until that bridge lands.
+- Not a write-by-default tool. Read tools are unauthenticated. The write tools (`execute_action`, `request_authorization`) are gated by the per-origin permission model (off by default) + the destructive blocklist + the audit-log writer. The cross-process IPC that delivers them to the browser native host (`LocalSocketHostBridge` ↔ `HostSocketServer` over `~/.peek/host.sock`) is now wired: at **Level 3** every action prompts the side-panel confirm banner before it runs. The real-browser MAIN-world dispatch + banner UX are covered by the Playwright E2E (`e2e/smoke.spec.ts`); the bridge, relay, dispatcher, and confirm logic are unit-tested.
 - Not a wrapper around Chrome DevTools Protocol. The server reads recorded events from SQLite; the extension owns capture. No live `chrome.debugger` access from the MCP server.
 
 ## Manual MCP-client config
@@ -95,7 +95,7 @@ At **Level 3** every `execute_action` call prompts the user via the side-panel b
 
 Every `execute_action` and `request_authorization` call is appended to `~/.peek/audit.log` (JSONL, mode 0600 — `peek audit log --json` prints it), including denied ones.
 
-**Shipped today (alpha.10) vs queued for a follow-up alpha:** the five-level model, the destructive blocklist, and the audit-log writer all ship — they're enforced inside `peek-mcp` and observable via `~/.peek/audit.log`. The cross-process IPC that lets `execute_action` actually fire a click in the browser (`LocalSocketHostBridge`) is **not yet wired**; calling `execute_action` against alpha.10 returns the `bridge not wired in this MCP process` error. Track the bridge work via [issues on the rrweb-stack repo](https://github.com/Cubenest/rrweb-stack/issues).
+**The write-path is wired end to end:** the five-level model, the destructive blocklist, and the audit-log writer are enforced inside `peek-mcp` (observable via `~/.peek/audit.log`), and the cross-process IPC that lets `execute_action` fire a click in the browser now lands — a `LocalSocketHostBridge` (MCP process) ↔ `HostSocketServer` (native host) over `~/.peek/host.sock`, a MAIN-world action dispatcher (click/type/navigate/scroll), and a side-panel confirm banner. Both write levels are implemented: **Level 3** (act-with-confirm — every action prompts the banner) and **Level 4** (YOLO — non-destructive actions auto-allow, destructive ones still prompt via the blocklist override). Both are opt-in per origin; the default stays Level 1 (read-only). Level 2 highlight and the remaining action types are queued. The real-browser dispatch + banner are covered by the Playwright E2E (`e2e/smoke.spec.ts`).
 
 ## Database
 

package/dist/mcp/host-bridge.d.ts

@@ -77,4 +77,53 @@ export declare class RegistryBackedHostBridge implements HostBridge {
     /** Test helper: reject the first pending request. */
     rejectNext(reason: unknown): boolean;
 }
+/** The minimal duplex surface the bridge needs — injectable for tests. */
+interface SocketLike {
+    write(data: string): void;
+    on(ev: string, h: (...a: unknown[]) => void): void;
+    end(): void;
+    /** Optional: decode inbound bytes as UTF-8 (real net.Socket has it). */
+    setEncoding?(encoding: string): void;
+    /**
+     * Optional: forcibly close the underlying socket (item G). Real net.Socket
+     * has it. `#reset` calls this so the orphaned socket doesn't stay open.
+     */
+    destroy?(): void;
+    /**
+     * Optional: detach the data/error/close listeners (item G) so a dropped
+     * socket doesn't leak its handlers. Real net.Socket (EventEmitter) has it.
+     */
+    removeAllListeners?(): void;
+}
+export interface LocalSocketHostBridgeDeps {
+    /** Override the socket / named-pipe path (tests + alternate PEEK_HOME). */
+    socketPath?: string;
+    /** Injectable connection factory; defaults to `net.connect(path)`. */
+    connect?: (path: string) => SocketLike;
+    /** Injectable correlation registry (tests). */
+    registry?: RequestRegistry;
+    /** Max bytes for a single inbound line before the connection is dropped. */
+    maxLineBytes?: number;
+}
+/**
+ * The production bridge: a newline-delimited-JSON client over the local
+ * `~/.peek/host.sock` (Unix domain socket) / `\\.\pipe\peek-host` (Windows).
+ *
+ * Wire frame (both directions): one JSON object per line, `\n`-terminated.
+ *   client → host:  { kind: 'act.request',  id, payload: HostActionRequest }
+ *   host → client:  { kind: 'act.response', id, payload: HostActionResponse }
+ *
+ * Correlation reuses {@link RequestRegistry} (id ↔ pending promise) exactly like
+ * {@link RegistryBackedHostBridge}; only the transport differs. The connection
+ * is opened lazily on the first request and reused. A connect throw, a socket
+ * `error`, or a timeout all resolve to a structured `deny`/`error` response —
+ * fail-closed — so the MCP tool handler never sees a raw throw and the audit
+ * log still records the attempt.
+ */
+export declare class LocalSocketHostBridge implements HostBridge {
+    #private;
+    constructor(deps?: LocalSocketHostBridgeDeps);
+    request(req: HostActionRequest): Promise<HostActionResponse>;
+}
+export {};
 //# sourceMappingURL=host-bridge.d.ts.map

package/dist/mcp/host-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host-bridge.d.ts","sourceRoot":"","sources":["../../src/mcp/host-bridge.ts"],"names":[],"mappings":"AA8BA,OAAO,EAAE,eAAe,EAAE,KAAK,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAC/F,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAKjD,mDAAmD;AACnD,MAAM,WAAW,iBAAiB;IAChC,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,uBAAuB,CAAC;IAC1D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,uDAAuD;AACvD,MAAM,WAAW,kBAAkB;IACjC,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,IAAI,GAAG,QAAQ,GAAG,OAAO,CAAC;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,GAAG,cAAc,CAAC;IAChE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CAC9D;AAED;;;;;;;GAOG;AACH,qBAAa,iBAAkB,YAAW,UAAU;;gBAEtC,MAAM,SAAqD;IAGjE,OAAO,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAQpE;AAED;;;;;GAKG;AACH,qBAAa,wBAAyB,YAAW,UAAU;;IAEzD,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,iBAAiB,CAAA;KAAE,CAAC,CAAM;gBAEzD,QAAQ,CAAC,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,mBAAmB;IAI5D,OAAO,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IAQlE,sDAAsD;IACtD,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO;IAMjD,qDAAqD;IACrD,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO;CAKrC"}
+{"version":3,"file":"host-bridge.d.ts","sourceRoot":"","sources":["../../src/mcp/host-bridge.ts"],"names":[],"mappings":"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"}

package/dist/mcp/host-bridge.js

@@ -27,7 +27,9 @@
 //
 //   When the IPC layer lands (3d-4 or 3e) we add a concrete
 //   `LocalSocketHostBridge` here; nothing else changes.
+import * as net from 'node:net';
 import { RequestRegistry } from '../native-host/request-registry.js';
+import { hostSocketPath } from '../native-host/socket-path.js';
 // 5 minutes — longer than any plausible Level-3 banner-decision window.
 const DEFAULT_BRIDGE_TIMEOUT_MS = 5 * 60_000;
 /**
@@ -85,4 +87,135 @@ export class RegistryBackedHostBridge {
         return this.#registry.reject(entry.id, reason);
     }
 }
+/**
+ * Cap for a single newline-delimited frame on the bridge's read side. A
+ * well-behaved native host never sends a frame near this; the cap is a
+ * local-DoS guard so a malformed / hostile peer can't make the bridge buffer
+ * unbounded. 1 MiB mirrors the native-messaging host→ext frame cap.
+ */
+const DEFAULT_MAX_LINE_BYTES = 1024 * 1024;
+/**
+ * The production bridge: a newline-delimited-JSON client over the local
+ * `~/.peek/host.sock` (Unix domain socket) / `\\.\pipe\peek-host` (Windows).
+ *
+ * Wire frame (both directions): one JSON object per line, `\n`-terminated.
+ *   client → host:  { kind: 'act.request',  id, payload: HostActionRequest }
+ *   host → client:  { kind: 'act.response', id, payload: HostActionResponse }
+ *
+ * Correlation reuses {@link RequestRegistry} (id ↔ pending promise) exactly like
+ * {@link RegistryBackedHostBridge}; only the transport differs. The connection
+ * is opened lazily on the first request and reused. A connect throw, a socket
+ * `error`, or a timeout all resolve to a structured `deny`/`error` response —
+ * fail-closed — so the MCP tool handler never sees a raw throw and the audit
+ * log still records the attempt.
+ */
+export class LocalSocketHostBridge {
+    #registry;
+    #path;
+    #connect;
+    #maxLineBytes;
+    #sock;
+    #buf = '';
+    constructor(deps = {}) {
+        this.#registry = deps.registry ?? new RequestRegistry();
+        this.#path = deps.socketPath ?? hostSocketPath();
+        this.#connect = deps.connect ?? ((p) => net.connect(p));
+        this.#maxLineBytes = deps.maxLineBytes ?? DEFAULT_MAX_LINE_BYTES;
+    }
+    /**
+     * Drop the cached socket + clear the read buffer (reconnect on next request).
+     *
+     * Item G: DESTROY the live socket + remove its listeners BEFORE nulling the
+     * reference — otherwise the orphaned socket stays open with its
+     * data/error/close listeners attached (a socket + listener leak on every
+     * reconnect, and a late event from the dead socket could still mutate state).
+     * Item H: fail every in-flight request with a structured error so a closed /
+     * errored transport rejects awaiting tool calls PROMPTLY rather than leaving
+     * them hanging until the 5-minute registry timeout.
+     */
+    #reset(reason) {
+        const sock = this.#sock;
+        this.#sock = undefined;
+        this.#buf = '';
+        if (sock) {
+            try {
+                sock.removeAllListeners?.();
+                sock.destroy?.();
+            }
+            catch {
+                // A destroy/removeListeners throw must not mask the reset.
+            }
+        }
+        // Item H: reject all pending requests now (fail-closed) instead of waiting
+        // out the per-request timeout.
+        this.#registry.rejectAll(new Error(reason ?? 'peek: host socket connection closed'));
+    }
+    /** Open (once) + wire the framing reader. Throws if the connect throws. */
+    #ensure() {
+        if (this.#sock)
+            return this.#sock;
+        const s = this.#connect(this.#path);
+        // Item F: decode inbound bytes as UTF-8 (matches the server side) so a
+        // multibyte char split across two reads can't corrupt a frame. Real
+        // net.Socket has setEncoding; injected fakes may not.
+        s.setEncoding?.('utf8');
+        s.on('data', (chunk) => {
+            this.#buf += String(chunk);
+            // Item F: local-DoS guard. If the buffer grows past the cap WITHOUT a
+            // frame delimiter, a hostile/malformed peer is trying to make us buffer
+            // unbounded — drop the connection + clear the buffer (in-flight requests
+            // time out via the registry → fail-closed).
+            if (this.#buf.length > this.#maxLineBytes && this.#buf.indexOf('\n') < 0) {
+                this.#reset('peek: host socket frame exceeded the line cap');
+                return;
+            }
+            let nl;
+            // biome-ignore lint/suspicious/noAssignInExpressions: idiomatic frame-drain loop
+            while ((nl = this.#buf.indexOf('\n')) >= 0) {
+                const line = this.#buf.slice(0, nl);
+                this.#buf = this.#buf.slice(nl + 1);
+                if (!line.trim())
+                    continue;
+                if (line.length > this.#maxLineBytes)
+                    continue; // oversized frame — drop it
+                try {
+                    const m = JSON.parse(line);
+                    if (m.kind === 'act.response' && typeof m.id === 'string') {
+                        this.#registry.resolve(m.id, m.payload);
+                    }
+                }
+                catch {
+                    // Drop a malformed frame; a single bad line must not wedge the bridge.
+                }
+            }
+        });
+        s.on('error', (err) => {
+            // Item H: drop the cached socket so the next request reconnects AND fail
+            // every in-flight request now (via #reset → registry.rejectAll), instead
+            // of letting them hang until the 5-minute per-request timeout.
+            this.#reset(`peek: host socket error — ${err instanceof Error ? err.message : 'connection error'}`);
+        });
+        s.on('close', () => {
+            this.#reset('peek: host socket closed');
+        });
+        this.#sock = s;
+        return s;
+    }
+    async request(req) {
+        try {
+            const sock = this.#ensure();
+            const { id, response } = this.#registry.create(req.timeoutMs ?? DEFAULT_BRIDGE_TIMEOUT_MS);
+            sock.write(`${JSON.stringify({ kind: 'act.request', id, payload: req })}\n`);
+            return await response;
+        }
+        catch (err) {
+            return {
+                verdict: 'deny',
+                result: 'error',
+                approver: 'user',
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+}
 //# sourceMappingURL=host-bridge.js.map

package/dist/mcp/host-bridge.js.map

@@ -1 +1 @@
-{"version":3,"file":"host-bridge.js","sourceRoot":"","sources":["../../src/mcp/host-bridge.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,EAAE;AACF,qDAAqD;AACrD,EAAE;AACF,oEAAoE;AACpE,2EAA2E;AAC3E,yEAAyE;AACzE,+DAA+D;AAC/D,yEAAyE;AACzE,2DAA2D;AAC3D,4EAA4E;AAC5E,4EAA4E;AAC5E,yEAAyE;AACzE,0EAA0E;AAC1E,8CAA8C;AAC9C,EAAE;AACF,yBAAyB;AACzB,uEAAuE;AACvE,gEAAgE;AAChE,6EAA6E;AAC7E,yEAAyE;AACzE,0EAA0E;AAC1E,iBAAiB;AACjB,yEAAyE;AACzE,wEAAwE;AACxE,gCAAgC;AAChC,EAAE;AACF,4DAA4D;AAC5D,wDAAwD;AAExD,OAAO,EAAE,eAAe,EAA4B,MAAM,oCAAoC,CAAC;AAG/F,wEAAwE;AACxE,MAAM,yBAAyB,GAAG,CAAC,GAAG,MAAM,CAAC;AAiD7C;;;;;;;GAOG;AACH,MAAM,OAAO,iBAAiB;IACnB,OAAO,CAAS;IACzB,YAAY,MAAM,GAAG,kDAAkD;QACrE,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IACD,KAAK,CAAC,OAAO,CAAC,IAAuB;QACnC,OAAO;YACL,OAAO,EAAE,MAAM;YACf,MAAM,EAAE,QAAQ;YAChB,QAAQ,EAAE,MAAM;YAChB,KAAK,EAAE,IAAI,CAAC,OAAO;SACpB,CAAC;IACJ,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,wBAAwB;IAC1B,SAAS,CAAkB;IACpC,6EAA6E;IACpE,OAAO,GAAkD,EAAE,CAAC;IAErE,YAAY,QAA0B,EAAE,IAA0B;QAChE,IAAI,CAAC,SAAS,GAAG,QAAQ,IAAI,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC;IACzD,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,GAAsB;QAClC,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAC5C,GAAG,CAAC,SAAS,IAAI,yBAAyB,CAC3C,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;QAC/B,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,sDAAsD;IACtD,WAAW,CAAC,OAA2B;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACnC,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QACzB,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IACnD,CAAC;IAED,qDAAqD;IACrD,UAAU,CAAC,MAAe;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACnC,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QACzB,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IACjD,CAAC;CACF"}
+{"version":3,"file":"host-bridge.js","sourceRoot":"","sources":["../../src/mcp/host-bridge.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,EAAE;AACF,qDAAqD;AACrD,EAAE;AACF,oEAAoE;AACpE,2EAA2E;AAC3E,yEAAyE;AACzE,+DAA+D;AAC/D,yEAAyE;AACzE,2DAA2D;AAC3D,4EAA4E;AAC5E,4EAA4E;AAC5E,yEAAyE;AACzE,0EAA0E;AAC1E,8CAA8C;AAC9C,EAAE;AACF,yBAAyB;AACzB,uEAAuE;AACvE,gEAAgE;AAChE,6EAA6E;AAC7E,yEAAyE;AACzE,0EAA0E;AAC1E,iBAAiB;AACjB,yEAAyE;AACzE,wEAAwE;AACxE,gCAAgC;AAChC,EAAE;AACF,4DAA4D;AAC5D,wDAAwD;AAExD,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAChC,OAAO,EAAE,eAAe,EAA4B,MAAM,oCAAoC,CAAC;AAC/F,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAG/D,wEAAwE;AACxE,MAAM,yBAAyB,GAAG,CAAC,GAAG,MAAM,CAAC;AAiD7C;;;;;;;GAOG;AACH,MAAM,OAAO,iBAAiB;IACnB,OAAO,CAAS;IACzB,YAAY,MAAM,GAAG,kDAAkD;QACrE,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IACD,KAAK,CAAC,OAAO,CAAC,IAAuB;QACnC,OAAO;YACL,OAAO,EAAE,MAAM;YACf,MAAM,EAAE,QAAQ;YAChB,QAAQ,EAAE,MAAM;YAChB,KAAK,EAAE,IAAI,CAAC,OAAO;SACpB,CAAC;IACJ,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,wBAAwB;IAC1B,SAAS,CAAkB;IACpC,6EAA6E;IACpE,OAAO,GAAkD,EAAE,CAAC;IAErE,YAAY,QAA0B,EAAE,IAA0B;QAChE,IAAI,CAAC,SAAS,GAAG,QAAQ,IAAI,IAAI,eAAe,CAAC,IAAI,CAAC,CAAC;IACzD,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,GAAsB;QAClC,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAC5C,GAAG,CAAC,SAAS,IAAI,yBAAyB,CAC3C,CAAC;QACF,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;QAC/B,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,sDAAsD;IACtD,WAAW,CAAC,OAA2B;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACnC,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QACzB,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IACnD,CAAC;IAED,qDAAqD;IACrD,UAAU,CAAC,MAAe;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACnC,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QACzB,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IACjD,CAAC;CACF;AAqBD;;;;;GAKG;AACH,MAAM,sBAAsB,GAAG,IAAI,GAAG,IAAI,CAAC;AAa3C;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,qBAAqB;IACvB,SAAS,CAAkB;IAC3B,KAAK,CAAS;IACd,QAAQ,CAA+B;IACvC,aAAa,CAAS;IAC/B,KAAK,CAAyB;IAC9B,IAAI,GAAG,EAAE,CAAC;IAEV,YAAY,OAAkC,EAAE;QAC9C,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,QAAQ,IAAI,IAAI,eAAe,EAAE,CAAC;QACxD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,UAAU,IAAI,cAAc,EAAE,CAAC;QACjD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAA0B,CAAC,CAAC;QACjF,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,YAAY,IAAI,sBAAsB,CAAC;IACnE,CAAC;IAED;;;;;;;;;;OAUG;IACH,MAAM,CAAC,MAAe;QACpB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC;QACxB,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,EAAE,CAAC;QACf,IAAI,IAAI,EAAE,CAAC;YACT,IAAI,CAAC;gBACH,IAAI,CAAC,kBAAkB,EAAE,EAAE,CAAC;gBAC5B,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC;YACnB,CAAC;YAAC,MAAM,CAAC;gBACP,2DAA2D;YAC7D,CAAC;QACH,CAAC;QACD,2EAA2E;QAC3E,+BAA+B;QAC/B,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,MAAM,IAAI,qCAAqC,CAAC,CAAC,CAAC;IACvF,CAAC;IAED,2EAA2E;IAC3E,OAAO;QACL,IAAI,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC,KAAK,CAAC;QAClC,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpC,uEAAuE;QACvE,oEAAoE;QACpE,sDAAsD;QACtD,CAAC,CAAC,WAAW,EAAE,CAAC,MAAM,CAAC,CAAC;QACxB,CAAC,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAc,EAAE,EAAE;YAC9B,IAAI,CAAC,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC;YAC3B,sEAAsE;YACtE,wEAAwE;YACxE,yEAAyE;YACzE,4CAA4C;YAC5C,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,aAAa,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBACzE,IAAI,CAAC,MAAM,CAAC,+CAA+C,CAAC,CAAC;gBAC7D,OAAO;YACT,CAAC;YACD,IAAI,EAAU,CAAC;YACf,iFAAiF;YACjF,OAAO,CAAC,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBACpC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;gBACpC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;oBAAE,SAAS;gBAC3B,IAAI,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,aAAa;oBAAE,SAAS,CAAC,4BAA4B;gBAC5E,IAAI,CAAC;oBACH,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAsD,CAAC;oBAChF,IAAI,CAAC,CAAC,IAAI,KAAK,cAAc,IAAI,OAAO,CAAC,CAAC,EAAE,KAAK,QAAQ,EAAE,CAAC;wBAC1D,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;oBAC1C,CAAC;gBACH,CAAC;gBAAC,MAAM,CAAC;oBACP,uEAAuE;gBACzE,CAAC;YACH,CAAC;QACH,CAAC,CAAC,CAAC;QACH,CAAC,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAY,EAAE,EAAE;YAC7B,yEAAyE;YACzE,yEAAyE;YACzE,+DAA+D;YAC/D,IAAI,CAAC,MAAM,CACT,6BAA6B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,kBAAkB,EAAE,CACvF,CAAC;QACJ,CAAC,CAAC,CAAC;QACH,CAAC,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YACjB,IAAI,CAAC,MAAM,CAAC,0BAA0B,CAAC,CAAC;QAC1C,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;QACf,OAAO,CAAC,CAAC;IACX,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,GAAsB;QAClC,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;YAC5B,MAAM,EAAE,EAAE,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAC5C,GAAG,CAAC,SAAS,IAAI,yBAAyB,CAC3C,CAAC;YACF,IAAI,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;YAC7E,OAAO,MAAM,QAAQ,CAAC;QACxB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO;gBACL,OAAO,EAAE,MAAM;gBACf,MAAM,EAAE,OAAO;gBACf,QAAQ,EAAE,MAAM;gBAChB,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;aACxD,CAAC;QACJ,CAAC;IACH,CAAC;CACF"}

package/dist/mcp/index.d.ts

@@ -2,6 +2,12 @@ import { type CreatePeekMcpServerOptions } from './server.js';
 /**
  * Start the peek MCP stdio server and resolve when the transport closes (the
  * client disconnected — stdin EOF). The DB handle is released on close.
+ *
+ * In MCP mode we wire the {@link LocalSocketHostBridge} so act-tool calls reach
+ * the co-running native host over ~/.peek/host.sock (replacing the
+ * MissingHostBridge default that returns "bridge not wired"). The bridge
+ * fail-closes when the socket is unavailable — every act-tool call still goes
+ * through the audit log. A caller-supplied `hostBridge` (tests) wins.
  */
 export declare function runMcpServer(options?: CreatePeekMcpServerOptions): Promise<void>;
 export { createPeekMcpServer, PEEK_MCP_TOOLS, SERVER_NAME, type CreatePeekMcpServerOptions, type PeekMcpServer, } from './server.js';

package/dist/mcp/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,KAAK,0BAA0B,EAAuB,MAAM,aAAa,CAAC;AAEnF;;;GAGG;AACH,wBAAsB,YAAY,CAAC,OAAO,GAAE,0BAA+B,GAAG,OAAO,CAAC,IAAI,CAAC,CAsB1F;AAED,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,WAAW,EACX,KAAK,0BAA0B,EAC/B,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,KAAK,0BAA0B,EAAuB,MAAM,aAAa,CAAC;AAEnF;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,OAAO,GAAE,0BAA+B,GAAG,OAAO,CAAC,IAAI,CAAC,CAyB1F;AAED,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,WAAW,EACX,KAAK,0BAA0B,EAC/B,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC"}

package/dist/mcp/index.js

@@ -3,13 +3,23 @@
 // exposes in v1. Invoked from src/index.ts when `peek-mcp` runs without
 // --native-host and without a chrome-extension:// origin arg.
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { LocalSocketHostBridge } from './host-bridge.js';
 import { createPeekMcpServer } from './server.js';
 /**
  * Start the peek MCP stdio server and resolve when the transport closes (the
  * client disconnected — stdin EOF). The DB handle is released on close.
+ *
+ * In MCP mode we wire the {@link LocalSocketHostBridge} so act-tool calls reach
+ * the co-running native host over ~/.peek/host.sock (replacing the
+ * MissingHostBridge default that returns "bridge not wired"). The bridge
+ * fail-closes when the socket is unavailable — every act-tool call still goes
+ * through the audit log. A caller-supplied `hostBridge` (tests) wins.
  */
 export async function runMcpServer(options = {}) {
-    const peek = createPeekMcpServer(options);
+    const peek = createPeekMcpServer({
+        hostBridge: new LocalSocketHostBridge(),
+        ...options,
+    });
     const transport = new StdioServerTransport();
     // Resolve when the client disconnects (stdin EOF). McpServer.connect
     // (Protocol.connect) PRESERVES and chains a pre-existing transport.onclose:

package/dist/mcp/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,0EAA0E;AAC1E,wEAAwE;AACxE,8DAA8D;AAE9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAmC,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEnF;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,UAAsC,EAAE;IACzE,MAAM,IAAI,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC1C,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAE7C,qEAAqE;IACrE,4EAA4E;IAC5E,yEAAyE;IACzE,4EAA4E;IAC5E,8EAA8E;IAC9E,iCAAiC;IACjC,MAAM,MAAM,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAC3C,SAAS,CAAC,OAAO,GAAG,GAAG,EAAE;YACvB,IAAI,CAAC,KAAK,EAAE,CAAC;YACb,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAErC,8EAA8E;IAC9E,uEAAuE;IACvE,MAAM,MAAM,CAAC;AACf,CAAC;AAED,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,WAAW,GAGZ,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,0EAA0E;AAC1E,wEAAwE;AACxE,8DAA8D;AAE9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,EAAmC,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEnF;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,UAAsC,EAAE;IACzE,MAAM,IAAI,GAAG,mBAAmB,CAAC;QAC/B,UAAU,EAAE,IAAI,qBAAqB,EAAE;QACvC,GAAG,OAAO;KACX,CAAC,CAAC;IACH,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAE7C,qEAAqE;IACrE,4EAA4E;IAC5E,yEAAyE;IACzE,4EAA4E;IAC5E,8EAA8E;IAC9E,iCAAiC;IACjC,MAAM,MAAM,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAC3C,SAAS,CAAC,OAAO,GAAG,GAAG,EAAE;YACvB,IAAI,CAAC,KAAK,EAAE,CAAC;YACb,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAErC,8EAA8E;IAC9E,uEAAuE;IACvE,MAAM,MAAM,CAAC;AACf,CAAC;AAED,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,WAAW,GAGZ,MAAM,aAAa,CAAC"}

package/dist/native-host/action-protocol.d.ts

@@ -19,6 +19,12 @@ export interface ActionResultMessage {
     details?: unknown;
     /** Error message when `result === 'error'` or 'denied'. */
     error?: string;
+    /**
+     * A one-shot confirm token issued on a `request_authorization` reply. The
+     * relay carries it back to the MCP process so the AI can pass it to a later
+     * `execute_action` (mirrors the extension-side ActionResultMessage).
+     */
+    confirmToken?: string;
 }
 /** host → SW: please execute / authorize this action. */
 export interface ActionRequestMessage {
@@ -36,6 +42,13 @@ export interface ActionRequestMessage {
     };
     /** Optional pinning to a specific tab id (SW picks active when omitted). */
     tabId?: number;
+    /**
+     * Pre-issued one-shot token from a prior `request_authorization` call. When
+     * present and valid (matching this request's sessionId + action.type), the SW
+     * consumes it and skips the side-panel banner. NULL/undefined → no token; the
+     * banner runs.
+     */
+    confirmToken?: string;
 }
 /** SW → host: the banner is now visible to the user (timing signal). */
 export interface ActionConfirmShownMessage {

package/dist/native-host/action-protocol.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action-protocol.d.ts","sourceRoot":"","sources":["../../src/native-host/action-protocol.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,6EAA6E;AAC7E,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,eAAe,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,IAAI,EAAE,gBAAgB,GAAG,uBAAuB,CAAC;IACjD,mEAAmE;IACnE,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;IAC1B,oEAAoE;IACpE,MAAM,EAAE,IAAI,GAAG,QAAQ,GAAG,OAAO,CAAC;IAClC,oDAAoD;IACpD,QAAQ,EAAE,MAAM,GAAG,kBAAkB,GAAG,cAAc,CAAC;IACvD,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,yDAAyD;AACzD,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,gBAAgB,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,gBAAgB,GAAG,uBAAuB,CAAC;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,sFAAsF;IACtF,MAAM,EAAE;QACN,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;QACvB,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;KAC3B,CAAC;IACF,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wEAAwE;AACxE,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,eAAe,GAAG,oBAAoB,CAAC;AACnD,MAAM,MAAM,eAAe,GAAG,mBAAmB,GAAG,yBAAyB,CAAC"}
+{"version":3,"file":"action-protocol.d.ts","sourceRoot":"","sources":["../../src/native-host/action-protocol.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,6EAA6E;AAC7E,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,eAAe,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,IAAI,EAAE,gBAAgB,GAAG,uBAAuB,CAAC;IACjD,mEAAmE;IACnE,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;IAC1B,oEAAoE;IACpE,MAAM,EAAE,IAAI,GAAG,QAAQ,GAAG,OAAO,CAAC;IAClC,oDAAoD;IACpD,QAAQ,EAAE,MAAM,GAAG,kBAAkB,GAAG,cAAc,CAAC;IACvD,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0EAA0E;IAC1E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,yDAAyD;AACzD,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,gBAAgB,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,gBAAgB,GAAG,uBAAuB,CAAC;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,sFAAsF;IACtF,MAAM,EAAE;QACN,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;QACvB,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;KAC3B,CAAC;IACF,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wEAAwE;AACxE,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,sBAAsB,CAAC;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,eAAe,GAAG,oBAAoB,CAAC;AACnD,MAAM,MAAM,eAAe,GAAG,mBAAmB,GAAG,yBAAyB,CAAC"}

package/dist/native-host/host-socket.d.ts

@@ -0,0 +1,105 @@
+import type { ActionConfirmShownMessage, ActionRequestMessage, ActionResultMessage } from './action-protocol.js';
+import { type LoadedPolicy } from './policy.js';
+/**
+ * Item E + I: unlink a Unix-domain-socket file ONLY when it's safe to do so —
+ * the path is a socket inode (never a regular file the user owns). This is the
+ * pure filesystem guard; the LIVE-vs-stale decision (item I) is made by the
+ * caller via {@link probeSocketAlive} BEFORE calling this, because the mere
+ * existence of a socket inode does NOT mean it's stale — a live host could be
+ * listening on it. Clobbering a live host's socket would silently break it.
+ *
+ * A missing path is a no-op. Windows named pipes aren't filesystem paths, so
+ * this is skipped there. Best-effort: any stat/unlink error is swallowed.
+ */
+export declare function cleanupStaleSocket(path: string): void;
+/**
+ * Item I: probe whether a LIVE server is listening at `path`. Connects with a
+ * short timeout: a successful connect → a live host owns the socket (do NOT
+ * unlink it); a refused/ENOENT/timeout → the inode is stale (safe to unlink and
+ * retry the bind). Windows named pipes are probed the same way (net.connect
+ * accepts the pipe path). Resolves false on any error so a probe failure can't
+ * wedge startup.
+ */
+export declare function probeSocketAlive(path: string, timeoutMs?: number): Promise<boolean>;
+/** Minimal duplex surface a connection must provide — injectable for tests. */
+export interface ConnectionLike {
+    write(data: string): void;
+    on(ev: string, h: (...a: unknown[]) => void): void;
+    /** Optional: forcibly close the connection (item J — over-cap line drop). */
+    destroy?(): void;
+    /** Optional: gracefully end the connection (fallback when destroy is absent). */
+    end?(): void;
+}
+/** Minimal server surface — injectable for tests (real impl is net.Server). */
+export interface NetServerLike {
+    listen(): void;
+    close(): void;
+    /**
+     * Item I: subscribe to the server's async 'error' event (EADDRINUSE/EACCES are
+     * emitted here, NOT thrown from listen()). Optional so existing fakes that
+     * never error don't need it.
+     */
+    on?(ev: 'error', handler: (err: Error & {
+        code?: string;
+    }) => void): void;
+}
+export interface HostSocketServerDeps {
+    /** Forward an `action.request` to the SW over the native port. */
+    postToSw(message: ActionRequestMessage): void;
+    /** Read ~/.peek/policy.json (per request — cheap). Defaults to {@link loadPolicy}. */
+    loadPolicy?: () => LoadedPolicy;
+    /** Generate a fresh native-port requestId. Defaults to crypto.randomUUID. */
+    generateRequestId?: () => string;
+    /** Override the socket / named-pipe path. */
+    socketPath?: string;
+    /**
+     * Build the underlying server given the per-connection handler. Defaults to
+     * `net.createServer`; tests inject a fake that drives connections directly.
+     */
+    createServer?: (onConnection: (conn: ConnectionLike) => void) => NetServerLike;
+    /**
+     * Item J: max bytes for a single inbound line before the connection is
+     * dropped. Defaults to 1 MiB (matches the bridge side).
+     */
+    maxLineBytes?: number;
+    /**
+     * Item I: probe whether a LIVE server owns the socket path. Defaults to
+     * {@link probeSocketAlive}; injectable so the bind-failure policy is testable.
+     */
+    probeSocketAlive?: (path: string) => Promise<boolean>;
+    /**
+     * Item I: unlink the (confirmed-stale) socket inode. Defaults to
+     * {@link cleanupStaleSocket}; injectable for tests.
+     */
+    unlinkSocket?: (path: string) => void;
+    /**
+     * Item I: called when the socket fails to bind even after the stale-unlink
+     * retry (e.g. a LIVE owner, or EACCES). The caller (startNativeHost) uses
+     * this to degrade — set `socketServer = undefined` — instead of crashing.
+     */
+    onListenError?: (err: Error) => void;
+}
+export declare class HostSocketServer {
+    #private;
+    constructor(deps: HostSocketServerDeps);
+    /**
+     * Start listening for MCP-process connections. Item I: bind failures
+     * (EADDRINUSE/EACCES) surface ASYNC via the server 'error' event, not a throw,
+     * so we attach an error handler and run the stale-vs-live policy:
+     *   • EADDRINUSE + probe says LIVE → another host owns it: report + stay down.
+     *   • EADDRINUSE + probe says stale → unlink + retry listen ONCE.
+     *   • any other bind error (e.g. EACCES) or a second EADDRINUSE → report + down.
+     * "Report" calls onListenError so startNativeHost degrades gracefully.
+     */
+    listen(): void;
+    /** Stop the server (best-effort). */
+    close(): void;
+    /**
+     * Inbound from the SW over the native port. For a terminal `action.result`,
+     * find the originating connection by requestId and write back the mapped
+     * `act.response`. `action.confirm.shown` is a non-terminal timing signal —
+     * the verdict still arrives in a later `action.result` — so we drop it here.
+     */
+    onSwMessage(message: ActionResultMessage | ActionConfirmShownMessage): void;
+}
+//# sourceMappingURL=host-socket.d.ts.map

package/dist/native-host/host-socket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-socket.d.ts","sourceRoot":"","sources":["../../src/native-host/host-socket.ts"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EACV,yBAAyB,EACzB,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,KAAK,YAAY,EAAc,MAAM,aAAa,CAAC;AAG5D;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAUrD;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,SAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAmBhF;AAED,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IACnD,6EAA6E;IAC7E,OAAO,CAAC,IAAI,IAAI,CAAC;IACjB,iFAAiF;IACjF,GAAG,CAAC,IAAI,IAAI,CAAC;CACd;AAED,+EAA+E;AAC/E,MAAM,WAAW,aAAa;IAC5B,MAAM,IAAI,IAAI,CAAC;IACf,KAAK,IAAI,IAAI,CAAC;IACd;;;;OAIG;IACH,EAAE,CAAC,CAAC,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,GAAG;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,GAAG,IAAI,CAAC;CAC3E;AAKD,MAAM,WAAW,oBAAoB;IACnC,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAC9C,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,YAAY,CAAC;IAChC,6EAA6E;IAC7E,iBAAiB,CAAC,EAAE,MAAM,MAAM,CAAC;IACjC,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,YAAY,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,KAAK,aAAa,CAAC;IAC/E;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACtD;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,CAAC;CACtC;AA6BD,qBAAa,gBAAgB;;gBAUf,IAAI,EAAE,oBAAoB;IAiCtC;;;;;;;;OAQG;IACH,MAAM,IAAI,IAAI;IAoCd,qCAAqC;IACrC,KAAK,IAAI,IAAI;IAMb;;;;;OAKG;IACH,WAAW,CAAC,OAAO,EAAE,mBAAmB,GAAG,yBAAyB,GAAG,IAAI;CAkG5E"}

package/dist/native-host/host-socket.js

@@ -0,0 +1,300 @@
+// Native-host-side IPC relay (Task 3.24 IPC layer).
+//
+// The MCP-server process talks to this server over the local socket
+// (`~/.peek/host.sock`) using the {@link LocalSocketHostBridge}. This server
+// runs INSIDE the native-host process — the one that owns the
+// `chrome.runtime.connectNative` port to the service worker. It relays:
+//
+//   socket  act.request   →  native-port  action.request   (host → SW)
+//   native-port action.result / action.confirm.shown  →  socket act.response
+//
+// Correlation has TWO id spaces that must not be conflated:
+//   • the socket wire `id` (the LocalSocketHostBridge's RequestRegistry id) —
+//     the MCP process correlates `act.response` back to its awaiting tool call.
+//   • the native-port `requestId` (UUID) — the SW echoes it on its reply so we
+//     find the originating socket connection.
+// We hold a `Map<requestId, { conn, wireId }>` so an `action.result` resolves
+// to the right connection AND echoes the right wire id.
+//
+// Security / robustness: per-connection newline-JSON framing (reused shape from
+// the bridge); a malformed frame is dropped, never crashes the loop; an
+// `action.result` for an unknown requestId is dropped (a stale reply after a
+// timeout must not throw). The policy deltas are loaded per request (the file
+// is tiny) and forwarded so the SW's destructive matcher merges them.
+import { statSync, unlinkSync } from 'node:fs';
+import * as net from 'node:net';
+import { platform } from 'node:os';
+import { setTimeout as delay } from 'node:timers/promises';
+import { loadPolicy } from './policy.js';
+import { hostSocketPath } from './socket-path.js';
+/**
+ * Item E + I: unlink a Unix-domain-socket file ONLY when it's safe to do so —
+ * the path is a socket inode (never a regular file the user owns). This is the
+ * pure filesystem guard; the LIVE-vs-stale decision (item I) is made by the
+ * caller via {@link probeSocketAlive} BEFORE calling this, because the mere
+ * existence of a socket inode does NOT mean it's stale — a live host could be
+ * listening on it. Clobbering a live host's socket would silently break it.
+ *
+ * A missing path is a no-op. Windows named pipes aren't filesystem paths, so
+ * this is skipped there. Best-effort: any stat/unlink error is swallowed.
+ */
+export function cleanupStaleSocket(path) {
+    if (platform() === 'win32')
+        return; // named pipe — not a filesystem inode
+    try {
+        const st = statSync(path);
+        if (!st.isSocket())
+            return; // never clobber a regular file / dir
+        unlinkSync(path);
+    }
+    catch {
+        // ENOENT (nothing there) or any other stat/unlink error — leave it for the
+        // bind to report. Don't throw; cleanup is best-effort.
+    }
+}
+/**
+ * Item I: probe whether a LIVE server is listening at `path`. Connects with a
+ * short timeout: a successful connect → a live host owns the socket (do NOT
+ * unlink it); a refused/ENOENT/timeout → the inode is stale (safe to unlink and
+ * retry the bind). Windows named pipes are probed the same way (net.connect
+ * accepts the pipe path). Resolves false on any error so a probe failure can't
+ * wedge startup.
+ */
+export function probeSocketAlive(path, timeoutMs = 500) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const done = (alive) => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                client.destroy();
+            }
+            catch {
+                // ignore
+            }
+            resolve(alive);
+        };
+        const client = net.connect(path);
+        client.setTimeout?.(timeoutMs);
+        client.on('connect', () => done(true)); // a live server accepted us
+        client.on('error', () => done(false)); // ECONNREFUSED / ENOENT → stale
+        client.on('timeout', () => done(false));
+    });
+}
+/** Default cap for a single inbound newline-delimited frame (item J). 1 MiB. */
+const DEFAULT_MAX_LINE_BYTES = 1024 * 1024;
+/**
+ * Map a terminal {@link ActionResultMessage} to the wire `payload` the bridge
+ * expects (a {@link HostActionResponse}). Drops the wire-protocol envelope
+ * fields (`type`, `requestId`, `tool`) and keeps the verdict/result data —
+ * INCLUDING `confirmToken` when the SW issued one (request_authorization).
+ */
+function toResponsePayload(result) {
+    const payload = {
+        verdict: result.verdict,
+        result: result.result,
+        approver: result.approver,
+    };
+    if (result.approvalMs !== undefined)
+        payload.approvalMs = result.approvalMs;
+    if (result.destructiveTerm !== undefined)
+        payload.destructiveTerm = result.destructiveTerm;
+    if (result.details !== undefined)
+        payload.details = result.details;
+    if (result.error !== undefined)
+        payload.error = result.error;
+    if (result.confirmToken !== undefined)
+        payload.confirmToken = result.confirmToken;
+    return payload;
+}
+export class HostSocketServer {
+    #deps;
+    #inFlight = new Map();
+    #server;
+    /** Whether we've already done the one stale-unlink retry (item I). */
+    #retriedAfterUnlink = false;
+    constructor(deps) {
+        this.#deps = {
+            postToSw: deps.postToSw,
+            loadPolicy: deps.loadPolicy ?? (() => loadPolicy()),
+            generateRequestId: deps.generateRequestId ?? (() => globalThis.crypto.randomUUID()),
+            socketPath: deps.socketPath ?? hostSocketPath(),
+            maxLineBytes: deps.maxLineBytes ?? DEFAULT_MAX_LINE_BYTES,
+            probeSocketAlive: deps.probeSocketAlive ?? ((p) => probeSocketAlive(p)),
+            unlinkSocket: deps.unlinkSocket ?? ((p) => cleanupStaleSocket(p)),
+            ...(deps.onListenError ? { onListenError: deps.onListenError } : {}),
+            createServer: deps.createServer ??
+                ((onConnection) => {
+                    const server = net.createServer((socket) => {
+                        socket.setEncoding('utf8');
+                        onConnection(socket);
+                    });
+                    let errorHandler;
+                    server.on('error', (err) => errorHandler?.(err));
+                    return {
+                        // Item I: do NOT blindly unlink before binding (that could clobber a
+                        // LIVE host's socket). Bind directly; if it emits EADDRINUSE the
+                        // listen() orchestration probes live-vs-stale and only then unlinks.
+                        listen: () => server.listen(this.#deps.socketPath),
+                        close: () => server.close(),
+                        on: (_ev, handler) => {
+                            errorHandler = handler;
+                        },
+                    };
+                }),
+        };
+    }
+    /**
+     * Start listening for MCP-process connections. Item I: bind failures
+     * (EADDRINUSE/EACCES) surface ASYNC via the server 'error' event, not a throw,
+     * so we attach an error handler and run the stale-vs-live policy:
+     *   • EADDRINUSE + probe says LIVE → another host owns it: report + stay down.
+     *   • EADDRINUSE + probe says stale → unlink + retry listen ONCE.
+     *   • any other bind error (e.g. EACCES) or a second EADDRINUSE → report + down.
+     * "Report" calls onListenError so startNativeHost degrades gracefully.
+     */
+    listen() {
+        if (this.#server)
+            return;
+        const server = this.#deps.createServer((conn) => this.#onConnection(conn));
+        this.#server = server;
+        server.on?.('error', (err) => {
+            void this.#handleListenError(err);
+        });
+        server.listen();
+    }
+    async #handleListenError(err) {
+        // Only EADDRINUSE is recoverable via the stale-unlink dance; everything else
+        // (EACCES, etc.) is reported as-is.
+        if (err.code !== 'EADDRINUSE' || this.#retriedAfterUnlink) {
+            this.#reportListenFailure(err);
+            return;
+        }
+        const alive = await this.#deps.probeSocketAlive(this.#deps.socketPath).catch(() => false);
+        if (alive) {
+            // A live host already owns this socket — DO NOT clobber it. Degrade.
+            this.#reportListenFailure(err);
+            return;
+        }
+        // Stale inode: unlink it and retry the bind exactly once.
+        this.#retriedAfterUnlink = true;
+        this.#deps.unlinkSocket(this.#deps.socketPath);
+        // A short beat so the unlink settles before rebind (mostly belt-and-braces).
+        await delay(0);
+        this.#server?.listen();
+    }
+    #reportListenFailure(err) {
+        this.#server = undefined;
+        this.#deps.onListenError?.(err);
+    }
+    /** Stop the server (best-effort). */
+    close() {
+        this.#server?.close();
+        this.#server = undefined;
+        this.#inFlight.clear();
+    }
+    /**
+     * Inbound from the SW over the native port. For a terminal `action.result`,
+     * find the originating connection by requestId and write back the mapped
+     * `act.response`. `action.confirm.shown` is a non-terminal timing signal —
+     * the verdict still arrives in a later `action.result` — so we drop it here.
+     */
+    onSwMessage(message) {
+        if (message.type !== 'action.result')
+            return; // confirm.shown: timing only
+        const inFlight = this.#inFlight.get(message.requestId);
+        if (!inFlight)
+            return; // stale reply after a timeout — drop, don't throw
+        this.#inFlight.delete(message.requestId);
+        const frame = {
+            kind: 'act.response',
+            id: inFlight.wireId,
+            payload: toResponsePayload(message),
+        };
+        try {
+            inFlight.conn.write(`${JSON.stringify(frame)}\n`);
+        }
+        catch {
+            // The MCP process closed the socket mid-flight; its tool call will time
+            // out. Nothing else to do here.
+        }
+    }
+    #onConnection(conn) {
+        let buf = '';
+        let dropped = false;
+        conn.on('data', (chunk) => {
+            if (dropped)
+                return; // connection already torn down for an over-cap line
+            buf += String(chunk);
+            // Item J: local-DoS guard (mirrors the bridge). If the buffer grows past
+            // the cap WITHOUT a frame delimiter, a hostile/malformed peer is trying to
+            // make us buffer unbounded — drop the connection + clear the buffer.
+            if (buf.length > this.#deps.maxLineBytes && buf.indexOf('\n') < 0) {
+                dropped = true;
+                buf = '';
+                try {
+                    conn.destroy?.();
+                    conn.end?.();
+                }
+                catch {
+                    // best-effort teardown
+                }
+                return;
+            }
+            let nl;
+            // biome-ignore lint/suspicious/noAssignInExpressions: idiomatic frame-drain loop
+            while ((nl = buf.indexOf('\n')) >= 0) {
+                const line = buf.slice(0, nl);
+                buf = buf.slice(nl + 1);
+                if (!line.trim())
+                    continue;
+                if (line.length > this.#deps.maxLineBytes)
+                    continue; // oversized framed line — drop it
+                this.#handleFrame(conn, line);
+            }
+        });
+        // A connection error / close leaves any of its in-flight entries dangling;
+        // they'll never be resolved (the MCP tool call times out). Drop them so the
+        // map doesn't grow unbounded.
+        const drop = () => {
+            for (const [requestId, entry] of this.#inFlight.entries()) {
+                if (entry.conn === conn)
+                    this.#inFlight.delete(requestId);
+            }
+        };
+        conn.on('error', drop);
+        conn.on('close', drop);
+        conn.on('end', drop);
+    }
+    #handleFrame(conn, line) {
+        let frame;
+        try {
+            frame = JSON.parse(line);
+        }
+        catch {
+            return; // malformed — drop, keep the loop alive
+        }
+        if (frame.kind !== 'act.request' || typeof frame.id !== 'string')
+            return;
+        const payload = frame.payload;
+        if (!payload || payload.tool === undefined || payload.action === undefined)
+            return;
+        const requestId = this.#deps.generateRequestId();
+        this.#inFlight.set(requestId, { conn, wireId: frame.id });
+        const policy = this.#deps.loadPolicy().destructiveTerms;
+        const request = {
+            type: 'action.request',
+            requestId,
+            tool: payload.tool,
+            sessionId: payload.sessionId ?? '',
+            action: payload.action,
+            client: payload.client ?? 'unknown',
+            policy: { add: policy.add, remove: policy.remove },
+            ...(payload.tabId !== undefined ? { tabId: payload.tabId } : {}),
+            ...(payload.confirmToken !== undefined ? { confirmToken: payload.confirmToken } : {}),
+        };
+        this.#deps.postToSw(request);
+    }
+}
+//# sourceMappingURL=host-socket.js.map

package/dist/native-host/host-socket.js.map

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

package/dist/native-host/host.d.ts

@@ -20,6 +20,17 @@ export interface NativeHostOptions {
     readonly input?: Readable;
     /** Override the output stream (default: process.stdout). */
     readonly output?: Writable;
+    /**
+     * Override the IPC socket / named-pipe path the {@link HostSocketServer}
+     * listens on (tests + alternate PEEK_HOME). Defaults to ~/.peek/host.sock.
+     */
+    readonly socketPath?: string;
+    /**
+     * When false, skip starting the {@link HostSocketServer}. Defaults to true.
+     * Tests that only exercise the ingest/handshake path set this false to avoid
+     * binding a real socket.
+     */
+    readonly startSocketServer?: boolean;
 }
 /**
  * Start the native messaging host: open the DB (running migrations) and begin

package/dist/native-host/host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/native-host/host.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAKtD,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,mCAAmC;IACnC,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC;CAC5B;AAUD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,iBAAsB,GAAG,gBAAgB,CA4EjF"}
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/native-host/host.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAQtD,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,mCAAmC;IACnC,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CACtC;AAaD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,iBAAsB,GAAG,gBAAgB,CAmIjF"}

package/dist/native-host/host.js

@@ -9,8 +9,12 @@
 // network.append / shadow.report). The act-tool action-protocol dispatch
 // (request/result correlation through the SW) lands alongside the IPC bridge.
 import { openDb, peekHomeDir, schemaVersion } from '../db/open.js';
+import { HostSocketServer } from './host-socket.js';
 import { ingest } from './ingest.js';
+import { hostSocketPath } from './socket-path.js';
 import { readMessages, writeMessage } from './transport.js';
+/** Message types the SW sends back on the action-request correlation channel. */
+const ACTION_REPLY_TYPES = new Set(['action.result', 'action.confirm.shown']);
 /** Message-type strings the ingest handler claims. */
 const INGEST_TYPES = new Set([
     'session.append',
@@ -35,6 +39,47 @@ export function startNativeHost(options = {}) {
     };
     if (options.input !== undefined)
         readOptions.input = options.input;
+    // IPC relay to the MCP-server process (Task 3.24). The MCP process's
+    // LocalSocketHostBridge connects here; the server relays `act.request` →
+    // native-port `action.request` (via `write`, the host → SW direction) and
+    // `action.result` (inbound, see handleMessage) → `act.response`.
+    let socketServer;
+    if (options.startSocketServer !== false) {
+        // Resolve the socket path: explicit option wins; else derive from the
+        // (possibly test-overridden) peek data dir via hostSocketPath(home). This
+        // is the SAME function the MCP-process bridge dials, so both sides agree —
+        // including under a custom $PEEK_HOME (item D). On Windows it's the fixed
+        // named pipe; a test `home` binds its own socket and never collides.
+        const socketPath = options.socketPath ?? hostSocketPath(home);
+        socketServer = new HostSocketServer({
+            // postToSw writes the action.request out the native port (host → SW).
+            postToSw: (message) => {
+                void write(message).catch((err) => {
+                    console.error(`native host: action.request post failed — ${err instanceof Error ? err.message : String(err)}`);
+                });
+            },
+            socketPath,
+            // Item I/J: bind failures (EADDRINUSE/EACCES) are emitted ASYNC via the
+            // server 'error' event, so a try/catch around listen() can't catch them.
+            // The server probes live-vs-stale + retries once on a stale socket; if it
+            // still can't bind it calls this. Degrade — the action write-path is down,
+            // but ingest/capture still flows — never crash the host.
+            onListenError: (err) => {
+                console.error(`native host: IPC socket failed to listen — ${err.message}`);
+                socketServer = undefined;
+            },
+        });
+        // listen() is async-internally (the bind-error/probe/retry path); it never
+        // throws synchronously, but keep the try/catch for a defensive construct-time
+        // failure.
+        try {
+            socketServer.listen();
+        }
+        catch (err) {
+            console.error(`native host: IPC socket listen threw — ${err instanceof Error ? err.message : String(err)}`);
+            socketServer = undefined;
+        }
+    }
     const done = readMessages((message) => {
         // A reply-write failure (e.g. the browser closed the port mid-reply) must
         // not become an unhandled rejection that tears down the host.
@@ -45,6 +90,7 @@ export function startNativeHost(options = {}) {
     return {
         done,
         close() {
+            socketServer?.close();
             db.close();
         },
     };
@@ -60,6 +106,14 @@ export function startNativeHost(options = {}) {
             });
             return;
         }
+        // Action-request correlation replies from the SW (Task 3.24). Forward to
+        // the IPC relay, which writes the mapped `act.response` back to the
+        // originating MCP-process socket connection. These are NOT acked over the
+        // native port (the MCP process is the one awaiting, over the socket).
+        if (type !== undefined && ACTION_REPLY_TYPES.has(type)) {
+            socketServer?.onSwMessage(message);
+            return;
+        }
         if (type !== undefined && INGEST_TYPES.has(type)) {
             // ingest() catches its own throws + returns a structured reply. The
             // try/catch here is defense in depth: if a future regression introduces

package/dist/native-host/host.js.map

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

package/dist/native-host/socket-path.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The local socket / named-pipe path the {@link LocalSocketHostBridge} connects
+ * to and the {@link HostSocketServer} listens on.
+ *
+ * @param peekHome the peek data dir (defaults to {@link peekHomeDir}, which
+ *   honors `$PEEK_HOME`). On win32 the named pipe is a fixed namespace path and
+ *   this argument is ignored.
+ */
+export declare function hostSocketPath(peekHome?: string): string;
+//# sourceMappingURL=socket-path.d.ts.map

package/dist/native-host/socket-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket-path.d.ts","sourceRoot":"","sources":["../../src/native-host/socket-path.ts"],"names":[],"mappings":"AAkBA;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,QAAQ,SAAgB,GAAG,MAAM,CAI/D"}

package/dist/native-host/socket-path.js

@@ -0,0 +1,31 @@
+// Local IPC endpoint path for the MCP-process ↔ native-host bridge (Task 3.24
+// IPC layer). The two `peek-mcp` processes share the peek data dir; the
+// simplest cross-platform local-only IPC is a Unix domain socket on
+// macOS/Linux (`<peekHome>/host.sock`) and a named pipe on Windows.
+//
+// Item D: the socket lives DIRECTLY inside the peek data dir (peekHomeDir(),
+// which honors $PEEK_HOME) as `host.sock`. The native host binds at the same
+// `join(peekHomeDir(), 'host.sock')`, so a user who relocates the store via
+// PEEK_HOME gets the bridge and the host on ONE path — not the bridge dialing
+// ~/.peek/host.sock while the host listens elsewhere.
+//
+// Pure path derivation — no `node:net`, no filesystem — so it unit-tests
+// cleanly. The peek-home dir is injectable for tests.
+import { platform } from 'node:os';
+import { join } from 'node:path';
+import { peekHomeDir } from '../db/open.js';
+/**
+ * The local socket / named-pipe path the {@link LocalSocketHostBridge} connects
+ * to and the {@link HostSocketServer} listens on.
+ *
+ * @param peekHome the peek data dir (defaults to {@link peekHomeDir}, which
+ *   honors `$PEEK_HOME`). On win32 the named pipe is a fixed namespace path and
+ *   this argument is ignored.
+ */
+export function hostSocketPath(peekHome = peekHomeDir()) {
+    // Windows named pipes live in the `\\.\pipe\` namespace, not the filesystem.
+    if (platform() === 'win32')
+        return '\\\\.\\pipe\\peek-host';
+    return join(peekHome, 'host.sock');
+}
+//# sourceMappingURL=socket-path.js.map

package/dist/native-host/socket-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"socket-path.js","sourceRoot":"","sources":["../../src/native-host/socket-path.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,wEAAwE;AACxE,oEAAoE;AACpE,oEAAoE;AACpE,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,4EAA4E;AAC5E,8EAA8E;AAC9E,sDAAsD;AACtD,EAAE;AACF,yEAAyE;AACzE,sDAAsD;AAEtD,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACnC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAAC,QAAQ,GAAG,WAAW,EAAE;IACrD,6EAA6E;IAC7E,IAAI,QAAQ,EAAE,KAAK,OAAO;QAAE,OAAO,wBAAwB,CAAC;IAC5D,OAAO,IAAI,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;AACrC,CAAC"}

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@peekdev/mcp",
-  "version": "0.1.0-alpha.12",
+  "version": "0.1.0-alpha.14",
+  "mcpName": "io.github.Cubenest/peek-mcp",
   "description": "peek native messaging host + stdio MCP server. Owns ~/.peek/sessions.db (better-sqlite3) and bridges the browser extension, CLI, and AI tools to a single local source of truth.",
   "keywords": [
     "peek",