@framers/agentos-ext-browser-automation 0.1.0 → 0.2.1

package/dist/attach/backends/raw-cdp.js

@@ -0,0 +1,213 @@
+/**
+ * @fileoverview Raw-CDP attach backend over Node's built-in WebSocket.
+ *
+ * Replaces the playwright `connectOverCDP` backend, which live-failed against
+ * a ~29-tab daily Chrome (whole-browser attach enumerates every tab and hangs)
+ * and used the `127.0.0.1` host Chrome's DNS-rebinding guard 403s. This
+ * backend opens ONE ws to the browser endpoint (host `localhost`, from
+ * `DevToolsActivePort`), creates ONE agent tab, attaches flattened to that
+ * single target, and can close only that tab. Requires Node >= 22 (built-in
+ * `WebSocket`); `daemon-main` guards this at startup.
+ *
+ * @module browser-automation/attach/backends/raw-cdp
+ */
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { AttachError } from '../errors.js';
+import { parseDevToolsActivePort } from '../devtools-port.js';
+const DEFAULT_PROFILE_ROOT = join(homedir(), 'Library', 'Application Support', 'Google', 'Chrome');
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * Raw single-target CDP backend (see fileoverview for the contract).
+ *
+ * Never sends `Browser.close`; `Target.closeTarget` is only ever issued for
+ * the tab this instance created.
+ */
+export class RawCdpBackend {
+    kind = 'cdp';
+    opts;
+    ws = null;
+    nextId = 0;
+    pending = new Map();
+    sessionId = null;
+    createdTargetId = null;
+    /** Invoked once when the transport drops unexpectedly (daemon schedules backoff reconnect). */
+    onUnexpectedClose = null;
+    constructor(options = {}) {
+        this.opts = {
+            profileRoot: options.profileRoot ?? DEFAULT_PROFILE_ROOT,
+            identityProbeUrl: options.identityProbeUrl ?? 'mail.google.com',
+            settleMs: options.settleMs ?? 1800,
+            commandTimeoutMs: options.commandTimeoutMs ?? 20_000,
+            connectTimeoutMs: options.connectTimeoutMs ?? 15_000,
+            evalMaxChars: options.evalMaxChars ?? 512 * 1024,
+        };
+    }
+    /** Open the ws to the browser endpoint. Creates/focuses NOTHING. Idempotent while connected. */
+    async connect() {
+        if (this.ws)
+            return;
+        let raw;
+        try {
+            raw = readFileSync(join(this.opts.profileRoot, 'DevToolsActivePort'), 'utf8');
+        }
+        catch {
+            throw new AttachError('CDP_UNAVAILABLE', 'DevToolsActivePort absent — remote debugging is not enabled on the target browser');
+        }
+        let wsUrl;
+        try {
+            wsUrl = parseDevToolsActivePort(raw).wsUrl;
+        }
+        catch (err) {
+            throw new AttachError('STALE_PORT_FILE', `DevToolsActivePort unusable: ${err.message}`);
+        }
+        const ws = new WebSocket(wsUrl);
+        ws.addEventListener('message', (ev) => this.onMessage(String(ev.data)));
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                try {
+                    ws.close();
+                }
+                catch {
+                    /* already dead */
+                }
+                reject(new AttachError('CDP_TIMEOUT', `ws open timed out after ${this.opts.connectTimeoutMs}ms`));
+            }, this.opts.connectTimeoutMs);
+            ws.addEventListener('open', () => {
+                clearTimeout(timer);
+                resolve();
+            }, { once: true });
+            ws.addEventListener('error', () => {
+                clearTimeout(timer);
+                reject(new AttachError('CDP_UNAVAILABLE', 'ws connection refused or failed'));
+            }, { once: true });
+        });
+        // Persistent drop handlers attach only AFTER a successful open, so a refused
+        // connection rejects connect() without also firing onUnexpectedClose.
+        this.ws = ws;
+        ws.addEventListener('close', () => this.failAllPending('transport closed'));
+        ws.addEventListener('error', () => this.failAllPending('transport error'));
+    }
+    /** Close ONLY our created tab (if any), then the ws. Never `Browser.close`. */
+    async disconnectTransport() {
+        if (this.ws && this.createdTargetId) {
+            await this.send('Target.closeTarget', { targetId: this.createdTargetId }).catch(() => {
+                /* tab may already be gone */
+            });
+        }
+        this.createdTargetId = null;
+        this.sessionId = null;
+        const ws = this.ws;
+        this.ws = null; // cleared FIRST so the close listener cannot report an unexpected drop
+        if (ws) {
+            try {
+                ws.close();
+            }
+            catch {
+                /* already closed */
+            }
+        }
+    }
+    /** Create the agent tab, attach flattened to it alone, enable Page/Runtime on that session only. */
+    async claimAgentTab() {
+        const created = (await this.send('Target.createTarget', { url: 'about:blank' }));
+        this.createdTargetId = created.targetId;
+        const attached = (await this.send('Target.attachToTarget', {
+            targetId: created.targetId,
+            flatten: true,
+        }));
+        this.sessionId = attached.sessionId;
+        await this.send('Page.enable', {}, this.sessionId);
+        await this.send('Runtime.enable', {}, this.sessionId);
+        return created.targetId;
+    }
+    /** Metadata-only identity read: matching page targets' titles/urls. No attach, no navigation. */
+    async probeIdentity() {
+        const { targetInfos } = (await this.send('Target.getTargets'));
+        return targetInfos
+            .filter((t) => t.type === 'page' && t.url.includes(this.opts.identityProbeUrl))
+            .map((t) => `${t.title} ${t.url}`)
+            .join(' | ');
+    }
+    /** Navigate the agent tab, settle, return the landed URL. */
+    async gotoTab(tab, url) {
+        this.requireTab(tab);
+        await this.send('Page.navigate', { url }, this.sessionId);
+        if (this.opts.settleMs > 0)
+            await sleep(this.opts.settleMs);
+        return String(await this.evalInTab(tab, 'location.href'));
+    }
+    /** innerText read, optional selector scope, capped. */
+    async readTab(tab, selector, maxChars = 6000) {
+        this.requireTab(tab);
+        const expr = `(() => { const el = ${selector ? `document.querySelector(${JSON.stringify(selector)})` : 'document.body'}; return el ? (el.innerText || '').slice(0, ${Math.max(1, maxChars)}) : ''; })()`;
+        return String((await this.evalInTab(tab, expr)) ?? '');
+    }
+    /** Runtime.evaluate in the agent tab (optional backend capability used by extract/evaluate). */
+    async evalInTab(tab, expression, timeoutMs) {
+        this.requireTab(tab);
+        const res = (await this.send('Runtime.evaluate', { expression, returnByValue: true, awaitPromise: true }, this.sessionId, timeoutMs ?? 30_000));
+        if (res.exceptionDetails) {
+            throw new AttachError('UNKNOWN', `page evaluation failed: ${res.exceptionDetails.text ?? 'exception'}`);
+        }
+        const value = res.result?.value;
+        if (typeof value === 'string' && value.length > this.opts.evalMaxChars) {
+            throw new AttachError('UNKNOWN', `eval result exceeds ${this.opts.evalMaxChars} chars`);
+        }
+        return value;
+    }
+    requireTab(tab) {
+        if (!this.sessionId || tab !== this.createdTargetId) {
+            throw new AttachError('TAB_CLOSED', 'agent tab is not claimed on this transport');
+        }
+    }
+    onMessage(data) {
+        let m;
+        try {
+            m = JSON.parse(data);
+        }
+        catch {
+            return;
+        }
+        if (!m.id || !this.pending.has(m.id))
+            return;
+        const p = this.pending.get(m.id);
+        this.pending.delete(m.id);
+        clearTimeout(p.timer);
+        if (m.error)
+            p.reject(new AttachError('UNKNOWN', m.error.message));
+        else
+            p.resolve(m.result);
+    }
+    failAllPending(reason) {
+        const err = new AttachError('CDP_UNAVAILABLE', reason);
+        for (const [, p] of this.pending) {
+            clearTimeout(p.timer);
+            p.reject(err);
+        }
+        this.pending.clear();
+        if (this.ws) {
+            this.ws = null;
+            this.sessionId = null;
+            this.onUnexpectedClose?.(err);
+        }
+    }
+    send(method, params = {}, sessionId, timeoutMs) {
+        const ws = this.ws;
+        if (!ws)
+            return Promise.reject(new AttachError('CDP_UNAVAILABLE', 'transport is not connected'));
+        const id = ++this.nextId;
+        const deadline = timeoutMs ?? this.opts.commandTimeoutMs;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                if (this.pending.delete(id)) {
+                    reject(new AttachError('CDP_TIMEOUT', `${method} timed out after ${deadline}ms`));
+                }
+            }, deadline);
+            this.pending.set(id, { resolve, reject, timer });
+            ws.send(JSON.stringify(sessionId ? { id, method, params, sessionId } : { id, method, params }));
+        });
+    }
+}
+//# sourceMappingURL=raw-cdp.js.map

package/dist/attach/backends/raw-cdp.js.map

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

package/dist/attach/daemon/client.d.ts

@@ -0,0 +1,64 @@
+import { type DaemonStatusFile } from './protocol.js';
+/** Client options. */
+export interface AttachDaemonClientOptions {
+    ipcDir?: string;
+    /** Client name prefix used in ids and claimant identity (default `client`). */
+    client?: string;
+    /** Response poll cadence ms (default 400). */
+    pollMs?: number;
+    /** Base per-op timeout ms before per-op margins (default 45000). */
+    opTimeoutMs?: number;
+}
+/** See fileoverview. All failures throw {@link AttachError} with a structured code. */
+export declare class AttachDaemonClient {
+    readonly ipcDir: string;
+    readonly client: string;
+    private readonly pollMs;
+    private readonly opTimeoutMs;
+    constructor(opts?: AttachDaemonClientOptions);
+    /** Fast, round-trip-free snapshot of status.json (undefined when absent). */
+    statusFile(): DaemonStatusFile | undefined;
+    /** True when status.json shows a fresh heartbeat or a live recorded pid. */
+    daemonLooksAlive(): boolean;
+    /** Liveness echo through the queue. */
+    ping(): Promise<{
+        pong: boolean;
+        pid: number;
+    }>;
+    /** Controller + daemon status snapshot via the queue. */
+    status(): Promise<Record<string, unknown>>;
+    /** Acquire driving rights (and trigger the controller claim on first use). */
+    claim(ttlMs?: number): Promise<Record<string, unknown>>;
+    /** Navigate the agent tab (daemon settles for `settle` ms, default 1800). */
+    goto(url: string, o?: {
+        settle?: number;
+    }): Promise<{
+        url: string;
+    }>;
+    /** Read visible text (untrusted page content). */
+    read(o?: {
+        selector?: string;
+        maxChars?: number;
+    }): Promise<{
+        untrusted: true;
+        text: string;
+    }>;
+    /** Structured extraction via a selector map (untrusted page content). */
+    extract(fields?: Record<string, string>): Promise<{
+        untrusted: true;
+        data: unknown;
+    }>;
+    /** USER LANE ONLY: arbitrary page evaluation for user-authored scripts. */
+    evaluate(expression: string, timeoutMs?: number): Promise<{
+        untrusted: true;
+        value: unknown;
+    }>;
+    /** Give up driving rights (daemon parks the tab; its session persists). */
+    release(): Promise<void>;
+    /** Runtime session controls. */
+    control(action: 'pause' | 'resume' | 'dry_run_on' | 'dry_run_off' | 'status'): Promise<Record<string, unknown>>;
+    /** Full daemon shutdown (parks tab, releases lease; Chrome untouched). */
+    quit(): Promise<void>;
+    private request;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/attach/daemon/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/attach/daemon/client.ts"],"names":[],"mappings":"AAgBA,OAAO,EAWL,KAAK,gBAAgB,EACtB,MAAM,eAAe,CAAC;AAEvB,sBAAsB;AACtB,MAAM,WAAW,yBAAyB;IACxC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAID,uFAAuF;AACvF,qBAAa,kBAAkB;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,IAAI,GAAE,yBAA8B;IAOhD,6EAA6E;IAC7E,UAAU,IAAI,gBAAgB,GAAG,SAAS;IAI1C,4EAA4E;IAC5E,gBAAgB,IAAI,OAAO;IAY3B,uCAAuC;IACjC,IAAI,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAIrD,yDAAyD;IACnD,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAIhD,8EAA8E;IACxE,KAAK,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAI7D,6EAA6E;IACvE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAI9E,kDAAkD;IAC5C,IAAI,CAAC,CAAC,GAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAIxG,yEAAyE;IACnE,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC;IAI3F,2EAA2E;IACrE,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;IAOpG,2EAA2E;IACrE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAI9B,gCAAgC;IAC1B,OAAO,CAAC,MAAM,EAAE,OAAO,GAAG,QAAQ,GAAG,YAAY,GAAG,aAAa,GAAG,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAIrH,0EAA0E;IACpE,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAIb,OAAO;CA6BtB"}

package/dist/attach/daemon/client.js

@@ -0,0 +1,120 @@
+/**
+ * @fileoverview Typed client for the attach daemon's file queue.
+ *
+ * No network, no child processes: writes `cmd-<id>.json`, polls for
+ * `resp-<id>.json`, deletes the response after reading. Used by user scripts
+ * (`wunderland attach run`), the declarative runner, and the tools'
+ * DaemonAttachSurface. `evaluate` is the user lane; no agent tool reaches it.
+ *
+ * Liveness: a daemon mid-op can miss heartbeats (the loop is serial), so
+ * {@link AttachDaemonClient.daemonLooksAlive} accepts a fresh heartbeat OR a
+ * live recorded pid.
+ *
+ * @module browser-automation/attach/daemon/client
+ */
+import { unlinkSync, existsSync } from 'node:fs';
+import { AttachError } from '../errors.js';
+import { resolveIpcDir, newCmdId, writeAtomicJson, readJson, cmdPath, respPath, statusPath, HEARTBEAT_STALE_MS, } from './protocol.js';
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** See fileoverview. All failures throw {@link AttachError} with a structured code. */
+export class AttachDaemonClient {
+    ipcDir;
+    client;
+    pollMs;
+    opTimeoutMs;
+    constructor(opts = {}) {
+        this.ipcDir = resolveIpcDir(opts.ipcDir);
+        this.client = `${opts.client ?? 'client'}-${process.pid}`;
+        this.pollMs = opts.pollMs ?? 400;
+        this.opTimeoutMs = opts.opTimeoutMs ?? 45_000;
+    }
+    /** Fast, round-trip-free snapshot of status.json (undefined when absent). */
+    statusFile() {
+        return readJson(statusPath(this.ipcDir));
+    }
+    /** True when status.json shows a fresh heartbeat or a live recorded pid. */
+    daemonLooksAlive() {
+        const s = this.statusFile();
+        if (!s || s.state === 'stopped' || s.state === 'failed')
+            return false;
+        if (Date.now() - s.t <= HEARTBEAT_STALE_MS)
+            return true;
+        try {
+            process.kill(s.pid, 0);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Liveness echo through the queue. */
+    async ping() {
+        return (await this.request('ping'));
+    }
+    /** Controller + daemon status snapshot via the queue. */
+    async status() {
+        return (await this.request('status'));
+    }
+    /** Acquire driving rights (and trigger the controller claim on first use). */
+    async claim(ttlMs) {
+        return (await this.request('claim', ttlMs ? { ttlMs } : {}));
+    }
+    /** Navigate the agent tab (daemon settles for `settle` ms, default 1800). */
+    async goto(url, o = {}) {
+        return (await this.request('goto', { url, ...o }, this.opTimeoutMs + (o.settle ?? 1800)));
+    }
+    /** Read visible text (untrusted page content). */
+    async read(o = {}) {
+        return (await this.request('read', o));
+    }
+    /** Structured extraction via a selector map (untrusted page content). */
+    async extract(fields) {
+        return (await this.request('extract', fields ? { fields } : {}));
+    }
+    /** USER LANE ONLY: arbitrary page evaluation for user-authored scripts. */
+    async evaluate(expression, timeoutMs) {
+        return (await this.request('eval', { expression, timeoutMs }, this.opTimeoutMs + (timeoutMs ?? 30_000)));
+    }
+    /** Give up driving rights (daemon parks the tab; its session persists). */
+    async release() {
+        await this.request('release');
+    }
+    /** Runtime session controls. */
+    async control(action) {
+        return (await this.request('control', { action }));
+    }
+    /** Full daemon shutdown (parks tab, releases lease; Chrome untouched). */
+    async quit() {
+        await this.request('quit');
+    }
+    async request(op, args = {}, timeoutMs) {
+        if (!this.daemonLooksAlive()) {
+            throw new AttachError('DAEMON_UNAVAILABLE', 'no live attach daemon behind this IPC dir; run `wunderland attach start`');
+        }
+        const id = newCmdId(this.client);
+        const cmdFile = cmdPath(this.ipcDir, id);
+        const respFile = respPath(this.ipcDir, id);
+        writeAtomicJson(cmdFile, { id, client: this.client, op, args });
+        const deadline = Date.now() + (timeoutMs ?? this.opTimeoutMs);
+        while (Date.now() < deadline) {
+            await sleep(this.pollMs);
+            const resp = readJson(respFile);
+            if (!resp)
+                continue;
+            try {
+                unlinkSync(respFile);
+            }
+            catch {
+                /* raced with GC */
+            }
+            if (resp.ok)
+                return resp.data;
+            throw new AttachError(resp.error.code, resp.error.message);
+        }
+        const consumed = !existsSync(cmdFile);
+        throw new AttachError(consumed ? 'CDP_TIMEOUT' : 'DAEMON_UNAVAILABLE', consumed
+            ? `${op} timed out awaiting the daemon's response`
+            : `${op} was never consumed — daemon gone; run \`wunderland attach start\``);
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/attach/daemon/client.js.map

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

package/dist/attach/daemon/daemon-lock.d.ts

@@ -0,0 +1,19 @@
+/** A held daemon lock. */
+export interface DaemonLock {
+    /** Absolute pidfile path backing the lock. */
+    readonly pidFile: string;
+    /** Remove the pidfile iff this process still owns it. Never throws. */
+    release(): void;
+}
+/**
+ * Acquire the daemon singleton atomically.
+ *
+ * Creates `pidFile` with the `wx` flag (fails when it exists). On EEXIST the
+ * holder is inspected: a live pid refuses acquisition with `DAEMON_RUNNING`;
+ * a dead pid or an unreadable body reclaims the file once. Concurrent
+ * acquirers race safely on the atomic create — exactly one wins.
+ *
+ * @throws {AttachError} `DAEMON_RUNNING` when another live daemon holds the lock.
+ */
+export declare function acquireDaemonLock(pidFile: string): DaemonLock;
+//# sourceMappingURL=daemon-lock.d.ts.map

package/dist/attach/daemon/daemon-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-lock.d.ts","sourceRoot":"","sources":["../../../src/attach/daemon/daemon-lock.ts"],"names":[],"mappings":"AAmBA,0BAA0B;AAC1B,MAAM,WAAW,UAAU;IACzB,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,OAAO,IAAI,IAAI,CAAC;CACjB;AAkBD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAsC7D"}

package/dist/attach/daemon/daemon-lock.js

@@ -0,0 +1,84 @@
+/**
+ * @fileoverview Atomic daemon singleton via an O_EXCL pidfile.
+ *
+ * Mutual exclusion for the attach daemon: exactly one daemon may hold one
+ * Chrome session, or concurrent `attach start`s would open two CDP sockets
+ * and raise two macOS Local Network prompts. NOTE: `../singleton-lock.ts` is,
+ * despite its name, a parser for Chrome's own SingletonLock symlink (JXA pid
+ * addressing) and provides no locking — this module is the daemon's lock.
+ *
+ * Reclaim policy is pid-liveness, not age: a lock whose recorded pid is dead
+ * (or whose body is unreadable/torn) is reclaimed; a live pid refuses the
+ * acquisition no matter how old the file is.
+ *
+ * @module browser-automation/attach/daemon/daemon-lock
+ */
+import { openSync, writeSync, closeSync, readFileSync, unlinkSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { AttachError } from '../errors.js';
+/** True when `pid` refers to a live process we may signal (EPERM counts as alive). */
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+/**
+ * Acquire the daemon singleton atomically.
+ *
+ * Creates `pidFile` with the `wx` flag (fails when it exists). On EEXIST the
+ * holder is inspected: a live pid refuses acquisition with `DAEMON_RUNNING`;
+ * a dead pid or an unreadable body reclaims the file once. Concurrent
+ * acquirers race safely on the atomic create — exactly one wins.
+ *
+ * @throws {AttachError} `DAEMON_RUNNING` when another live daemon holds the lock.
+ */
+export function acquireDaemonLock(pidFile) {
+    mkdirSync(dirname(pidFile), { recursive: true, mode: 0o700 });
+    const body = { pid: process.pid, startedAt: Date.now() };
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const fd = openSync(pidFile, 'wx', 0o600);
+            writeSync(fd, JSON.stringify(body));
+            closeSync(fd);
+            return {
+                pidFile,
+                release() {
+                    try {
+                        const cur = JSON.parse(readFileSync(pidFile, 'utf8'));
+                        if (cur.pid === process.pid)
+                            unlinkSync(pidFile);
+                    }
+                    catch {
+                        /* released best-effort: file gone or owned by a newer daemon */
+                    }
+                },
+            };
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+            let holder;
+            try {
+                holder = JSON.parse(readFileSync(pidFile, 'utf8'));
+            }
+            catch {
+                /* torn or unreadable body: treat as reclaimable */
+            }
+            if (holder && pidAlive(holder.pid)) {
+                throw new AttachError('DAEMON_RUNNING', `daemon already running (pid ${holder.pid})`);
+            }
+            try {
+                unlinkSync(pidFile);
+            }
+            catch {
+                /* raced with another reclaimer; the retry create decides the winner */
+            }
+        }
+    }
+    throw new AttachError('DAEMON_RUNNING', 'daemon lock contention: another process reclaimed the pidfile first');
+}
+//# sourceMappingURL=daemon-lock.js.map

package/dist/attach/daemon/daemon-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-lock.js","sourceRoot":"","sources":["../../../src/attach/daemon/daemon-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC9F,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAgB3C,sFAAsF;AACtF,SAAS,QAAQ,CAAC,GAAW;IAC3B,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAQ,GAA6B,CAAC,IAAI,KAAK,OAAO,CAAC;IACzD,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC9D,MAAM,IAAI,GAAa,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;IACnE,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC;QAC7C,IAAI,CAAC;YACH,MAAM,EAAE,GAAG,QAAQ,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;YAC1C,SAAS,CAAC,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;YACpC,SAAS,CAAC,EAAE,CAAC,CAAC;YACd,OAAO;gBACL,OAAO;gBACP,OAAO;oBACL,IAAI,CAAC;wBACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAa,CAAC;wBAClE,IAAI,GAAG,CAAC,GAAG,KAAK,OAAO,CAAC,GAAG;4BAAE,UAAU,CAAC,OAAO,CAAC,CAAC;oBACnD,CAAC;oBAAC,MAAM,CAAC;wBACP,gEAAgE;oBAClE,CAAC;gBACH,CAAC;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;gBAAE,MAAM,GAAG,CAAC;YAChE,IAAI,MAA4B,CAAC;YACjC,IAAI,CAAC;gBACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAa,CAAC;YACjE,CAAC;YAAC,MAAM,CAAC;gBACP,mDAAmD;YACrD,CAAC;YACD,IAAI,MAAM,IAAI,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;gBACnC,MAAM,IAAI,WAAW,CAAC,gBAAgB,EAAE,+BAA+B,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC;YACxF,CAAC;YACD,IAAI,CAAC;gBACH,UAAU,CAAC,OAAO,CAAC,CAAC;YACtB,CAAC;YAAC,MAAM,CAAC;gBACP,uEAAuE;YACzE,CAAC;QACH,CAAC;IACH,CAAC;IACD,MAAM,IAAI,WAAW,CAAC,gBAAgB,EAAE,qEAAqE,CAAC,CAAC;AACjH,CAAC"}

package/dist/attach/daemon/daemon-main.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Build and run the daemon from an environment map. Returns the process exit
+ * code (0 clean stop, 2 failure). Exported for tests and for the CLI.
+ */
+export declare function main(env?: Record<string, string | undefined>): Promise<number>;
+/**
+ * True when `moduleUrl` is the script Node was started with (`node <entryPath>`).
+ *
+ * Both sides resolve to a real path before the comparison: a file URL
+ * percent-encodes characters such as spaces, Node follows symlinks when it
+ * builds `import.meta.url` for the entry script but keeps them under
+ * `--preserve-symlinks-main`, and the entry path may be relative. A missing
+ * or unreadable entry path, or a module URL that is not a file, is not this
+ * module. Exported for tests.
+ */
+export declare function isEntryPoint(moduleUrl: string, entryPath: string | undefined): boolean;
+//# sourceMappingURL=daemon-main.d.ts.map

package/dist/attach/daemon/daemon-main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-main.d.ts","sourceRoot":"","sources":["../../../src/attach/daemon/daemon-main.ts"],"names":[],"mappings":"AAmBA;;;GAGG;AACH,wBAAsB,IAAI,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAoDjG;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAOtF"}