@hwip/cli 0.0.1 → 0.1.0

package/dist/lan-sender.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tryLanDelivery = exports.lanUploadTimeoutMs = exports.LAN_PING_TIMEOUT_MS = exports.pickLanTarget = void 0;
+const node_crypto_1 = require("node:crypto");
+const lan_auth_js_1 = require("./lan-auth.js");
+/**
+ * The device a push can go to directly, or null for the relay: a push with
+ * no single target (a broadcast) never qualifies, nor does a target without
+ * a key, an endpoint, or a live connection.
+ */
+const pickLanTarget = (devices, targetDeviceId) => {
+    if (!targetDeviceId)
+        return null;
+    const device = devices.find((d) => d.deviceId === targetDeviceId);
+    if (!device?.publicKey || device.isOnline !== true || !device.lan)
+        return null;
+    const { host, port } = device.lan;
+    if (typeof host !== 'string' || host.length === 0 || typeof port !== 'number' || !Number.isInteger(port))
+        return null;
+    return { deviceId: device.deviceId, publicKey: device.publicKey, host, port };
+};
+exports.pickLanTarget = pickLanTarget;
+/** A receiver that is there answers a ping on the same network in milliseconds. */
+exports.LAN_PING_TIMEOUT_MS = 1_500;
+/** 30 s, plus one second per MiB — slower than any Wi-Fi a LAN transfer is worth trying on. */
+const lanUploadTimeoutMs = (bytes) => 30_000 + Math.ceil(bytes / 1_048_576) * 1_000;
+exports.lanUploadTimeoutMs = lanUploadTimeoutMs;
+const newTransferId = () => `lt_${(0, node_crypto_1.randomBytes)(12).toString('hex')}`;
+/** A ping answer is `{"deviceId": "..."}`; anything longer is not a receiver. */
+const PING_BODY_MAX_BYTES = 1024;
+const UPLOAD_CHUNK_BYTES = 1_048_576;
+/** Fires on the timeout or the caller's signal, whichever comes first
+ *  (`AbortSignal.any` is Node 20+; this package supports 20.17+). `release`
+ *  detaches from the caller's signal, which may outlive this request. */
+const deadline = (timeoutMs, external) => {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    if (!external)
+        return { signal: timeout, release: () => undefined };
+    const controller = new AbortController();
+    const onExternal = () => { controller.abort(external.reason); };
+    const onTimeout = () => { controller.abort(timeout.reason); };
+    external.addEventListener('abort', onExternal, { once: true });
+    timeout.addEventListener('abort', onTimeout, { once: true });
+    if (external.aborted)
+        onExternal();
+    return {
+        signal: controller.signal,
+        release: () => {
+            external.removeEventListener('abort', onExternal);
+            timeout.removeEventListener('abort', onTimeout);
+        },
+    };
+};
+/**
+ * The ciphertext as a stream of views into it. Node's fetch copies a
+ * `Uint8Array` body whole — measured at +2× the file for a buffered one — and
+ * the file may be a gigabyte already held twice (plaintext and ciphertext).
+ * Pulled one chunk at a time, only a chunk is ever in flight.
+ */
+const bodyStream = (buf) => {
+    let offset = 0;
+    return new ReadableStream({
+        pull(controller) {
+            if (offset >= buf.byteLength) {
+                controller.close();
+                return;
+            }
+            const end = Math.min(offset + UPLOAD_CHUNK_BYTES, buf.byteLength);
+            controller.enqueue(new Uint8Array(buf.buffer, buf.byteOffset + offset, end - offset));
+            offset = end;
+        },
+    });
+};
+/** Drop a body we will not read; a peer that never ends it must not hold us. */
+const discard = (res) => (res.body ? res.body.cancel().catch(() => undefined) : Promise.resolve());
+/** The body as text, or null past `max` bytes — read no further than that. */
+const readCapped = async (res, max) => {
+    if (!res.body)
+        return '';
+    const reader = res.body.getReader();
+    const chunks = [];
+    let size = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.byteLength;
+        if (size > max) {
+            await reader.cancel().catch(() => undefined);
+            return null;
+        }
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+};
+const reasonOf = (err) => {
+    if (err instanceof Error && (err.name === 'TimeoutError' || err.name === 'AbortError'))
+        return 'timed out';
+    return err instanceof Error ? err.message : String(err);
+};
+const tryLanDelivery = async (input) => {
+    const { target, file } = input;
+    const fetchFn = input.fetchFn ?? fetch;
+    const base = `http://${target.host}:${target.port}`;
+    let keys;
+    try {
+        keys = (0, lan_auth_js_1.deriveLanKeys)(await input.deriveSharedSecret(target.publicKey));
+    }
+    catch (err) {
+        return { delivered: false, reason: `key derivation failed: ${reasonOf(err)}` };
+    }
+    // Ping first: an address that has gone stale, or now belongs to another
+    // machine, costs the ping timeout — not an upload of the whole file.
+    const pingDeadline = deadline(input.pingTimeoutMs ?? exports.LAN_PING_TIMEOUT_MS, input.signal);
+    try {
+        const fields = { senderDeviceId: input.senderDeviceId, transferId: lan_auth_js_1.LAN_PING_TRANSFER_ID, timestamp: Date.now(), nonce: (0, lan_auth_js_1.newNonce)() };
+        const mac = (0, lan_auth_js_1.signLanRequest)(keys.macKey, { ...fields, method: 'GET', path: lan_auth_js_1.LAN_PATHS.ping, bodySha256: lan_auth_js_1.EMPTY_BODY_SHA256 });
+        const res = await fetchFn(`${base}${lan_auth_js_1.LAN_PATHS.ping}`, {
+            headers: (0, lan_auth_js_1.toLanAuthHeaders)(fields, mac),
+            signal: pingDeadline.signal,
+        });
+        // Status and receipt are headers: decide on them before reading a
+        // body whose size and end the peer controls.
+        if (res.status !== 200) {
+            await discard(res);
+            return { delivered: false, reason: `ping answered ${res.status}` };
+        }
+        if (!(0, lan_auth_js_1.verifyLanReceipt)(keys.macKey, mac, res.headers.get(lan_auth_js_1.LAN_HEADERS.receipt))) {
+            await discard(res);
+            return { delivered: false, reason: 'ping answered without a valid receipt' };
+        }
+        const body = await readCapped(res, PING_BODY_MAX_BYTES);
+        let answeredBy;
+        try {
+            answeredBy = JSON.parse(body ?? '').deviceId;
+        }
+        catch {
+            answeredBy = undefined;
+        }
+        if (answeredBy !== target.deviceId)
+            return { delivered: false, reason: 'ping answered by another device' };
+    }
+    catch (err) {
+        return { delivered: false, reason: input.signal?.aborted ? 'cancelled' : `ping failed: ${reasonOf(err)}` };
+    }
+    finally {
+        pingDeadline.release();
+    }
+    const transferId = newTransferId();
+    const uploadDeadline = deadline(input.uploadTimeoutMs ?? (0, exports.lanUploadTimeoutMs)(file.ciphertext.byteLength), input.signal);
+    try {
+        const fields = { senderDeviceId: input.senderDeviceId, transferId, timestamp: Date.now(), nonce: (0, lan_auth_js_1.newNonce)() };
+        const mac = (0, lan_auth_js_1.signLanRequest)(keys.macKey, { ...fields, method: 'POST', path: lan_auth_js_1.LAN_PATHS.upload, bodySha256: (0, lan_auth_js_1.sha256Hex)(file.ciphertext) });
+        const meta = { fileName: file.fileName, fileType: file.fileType, fileSize: file.fileSize, iv: file.iv, deviceKeyMap: file.deviceKeyMap, transferId };
+        const init = {
+            method: 'POST',
+            headers: {
+                ...(0, lan_auth_js_1.toLanAuthHeaders)(fields, mac),
+                [lan_auth_js_1.LAN_HEADERS.meta]: (0, lan_auth_js_1.sealMeta)(keys.metaKey, meta),
+                'content-type': 'application/octet-stream',
+                // Explicit, so a streamed body still goes with a length: the
+                // receiver refuses chunked uploads (411).
+                'content-length': String(file.ciphertext.byteLength),
+            },
+            body: bodyStream(file.ciphertext),
+            duplex: 'half',
+            signal: uploadDeadline.signal,
+        };
+        const res = await fetchFn(`${base}${lan_auth_js_1.LAN_PATHS.upload}`, init);
+        await discard(res);
+        if (res.status !== 201)
+            return { delivered: false, reason: `upload answered ${res.status}` };
+        if (!(0, lan_auth_js_1.verifyLanReceipt)(keys.macKey, mac, res.headers.get(lan_auth_js_1.LAN_HEADERS.receipt)))
+            return { delivered: false, reason: 'upload answered without a valid receipt' };
+        return { delivered: true, transferId };
+    }
+    catch (err) {
+        return { delivered: false, reason: input.signal?.aborted ? 'cancelled' : `upload failed: ${reasonOf(err)}` };
+    }
+    finally {
+        uploadDeadline.release();
+    }
+};
+exports.tryLanDelivery = tryLanDelivery;

package/dist/lan-transfer.d.ts

@@ -0,0 +1,36 @@
+import type { LanPublisher } from './lan-endpoint.js';
+import type { LanReceiver } from './lan-receiver.js';
+/**
+ * Local transfer (ADR-0013) — the listener's lifecycle for it, in one place.
+ *
+ * Order of events the daemon cannot control: the WebSocket may open before or
+ * after the receiver is bound, and SIGTERM may land while the keys are still
+ * loading. Every branch here ends the same way — the device record never
+ * points at a port nobody is listening on:
+ *
+ *   keys → bind → (socket already open? publish now) → watch the address
+ *   socket open  → force-publish (the record exists from $connect on)
+ *   stop         → stop the watch, `lan: null`, close the socket — or, if
+ *                  the bind has not finished yet, close it the moment it does
+ */
+export interface LanTransferDeps {
+    log: (msg: string) => void;
+    initCrypto: () => Promise<void>;
+    /** Bind the receiver; `onError` fires if the bound socket later dies. */
+    startReceiver: (hooks: {
+        onError: (err: Error) => void;
+    }) => Promise<LanReceiver>;
+    createPublisher: (port: number) => LanPublisher;
+    /** Whether the WebSocket has reached `open` right now. */
+    isOpen: () => boolean;
+}
+export interface LanTransfer {
+    /** Call on every WebSocket `open`. No-op until the receiver is bound. */
+    onOpen: () => void;
+    /** Retract the endpoint and release the port. Idempotent. Resolves once
+     *  the receiver's socket is closed; the retract itself is one frame on a
+     *  socket that is already closing, so it is sent and not waited on. */
+    stop: () => Promise<void>;
+}
+export declare const createLanTransfer: (deps: LanTransferDeps) => LanTransfer;
+//# sourceMappingURL=lan-transfer.d.ts.map

package/dist/lan-transfer.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLanTransfer = void 0;
+const createLanTransfer = (deps) => {
+    let live = null;
+    let stopping = false;
+    // A bound socket that dies later must not keep being re-affirmed by the
+    // watch: retract, release, and turn the feature off with one log line.
+    const onReceiverError = (err) => {
+        deps.log(`local transfer: off — receiver failed after bind (${err.message})`);
+        void teardown();
+    };
+    const ready = deps.initCrypto()
+        .then(() => deps.startReceiver({ onError: onReceiverError }))
+        .then((receiver) => {
+        if (stopping) {
+            // Bound after stop() was already called: nothing was published,
+            // so there is nothing to retract — just let the port go.
+            void receiver.stop();
+            return;
+        }
+        const publisher = deps.createPublisher(receiver.port);
+        live = { publisher, receiver };
+        publisher.startWatch(receiver.port);
+        if (deps.isOpen())
+            publisher.publish(receiver.port, { force: true });
+    })
+        .catch((err) => {
+        deps.log(`local transfer: off — ${err instanceof Error ? err.message : String(err)}`);
+    });
+    const onOpen = () => {
+        if (live)
+            live.publisher.publish(live.receiver.port, { force: true });
+    };
+    const teardown = async () => {
+        if (!live)
+            return;
+        const current = live;
+        live = null;
+        current.publisher.stopWatch();
+        current.publisher.clear();
+        await current.receiver.stop();
+    };
+    let stopped = null;
+    const stop = () => {
+        if (stopped)
+            return stopped;
+        stopping = true;
+        stopped = ready.then(() => teardown());
+        return stopped;
+    };
+    return { onOpen, stop };
+};
+exports.createLanTransfer = createLanTransfer;

package/dist/listener-device-id.d.ts

@@ -0,0 +1,20 @@
+import { execFileSync } from 'node:child_process';
+export declare const hashListenerId: (seed: string) => string;
+/** The id the sticky file holds, or null when it is missing or not an id. */
+export declare const readStickyListenerId: () => string | null;
+/**
+ * Leave `id` in the sticky file (0600, in the 0700 `~/.hwip`) so a later process that cannot
+ * read the machine id — `ioreg` stalled past its timeout — still gets this one. The writer is
+ * `computeListenerDeviceId` (the listener, `hwip rename`). A file that already holds `id` is left
+ * alone; one that holds another is replaced (an id a stalled start wrote down earlier). The new
+ * content goes in by rename, so a hook reading in the middle sees the old id or the new one, never
+ * an empty file. Best-effort: the id in memory stands.
+ */
+export declare const rememberListenerId: (id: string) => void;
+/** Platform machine id (macOS IOPlatformUUID / Linux machine-id), or null. */
+export declare const readMachineId: (deps?: {
+    platform?: NodeJS.Platform;
+    exec?: typeof execFileSync;
+}) => string | null;
+export declare const listenerDeviceId: () => string;
+//# sourceMappingURL=listener-device-id.d.ts.map

package/dist/listener-device-id.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listenerDeviceId = exports.readMachineId = exports.rememberListenerId = exports.readStickyListenerId = exports.hashListenerId = void 0;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const node_crypto_1 = require("node:crypto");
+const private_files_js_1 = require("./private-files.js");
+// The listener daemon writes this file (see listener.ts computeListenerDeviceId; `hwip rename`
+// reaches the same function, and writes the same value); the other processes in the CLI
+// (hwip-hook's agent-session context) only READ it, so both resolve the same id.
+const LISTENER_ID_FILE = (0, node_path_1.join)((0, node_os_1.homedir)(), '.hwip', 'listener-device-id');
+const hashListenerId = (seed) => `dev_listener_${(0, node_crypto_1.createHash)('sha256').update(seed).digest('hex').slice(0, 8)}`;
+exports.hashListenerId = hashListenerId;
+/** The id the sticky file holds, or null when it is missing or not an id. */
+const readStickyListenerId = () => {
+    try {
+        const saved = (0, node_fs_1.readFileSync)(LISTENER_ID_FILE, 'utf-8').trim();
+        return /^dev_listener_[0-9a-f]{8}$/.test(saved) ? saved : null;
+    }
+    catch {
+        return null;
+    }
+};
+exports.readStickyListenerId = readStickyListenerId;
+/**
+ * Leave `id` in the sticky file (0600, in the 0700 `~/.hwip`) so a later process that cannot
+ * read the machine id — `ioreg` stalled past its timeout — still gets this one. The writer is
+ * `computeListenerDeviceId` (the listener, `hwip rename`). A file that already holds `id` is left
+ * alone; one that holds another is replaced (an id a stalled start wrote down earlier). The new
+ * content goes in by rename, so a hook reading in the middle sees the old id or the new one, never
+ * an empty file. Best-effort: the id in memory stands.
+ */
+const rememberListenerId = (id) => {
+    if ((0, exports.readStickyListenerId)() === id)
+        return;
+    // Random name, exclusive create: a predictable name is one another process could pre-create as a symlink.
+    const tmp = `${LISTENER_ID_FILE}.${(0, node_crypto_1.randomBytes)(6).toString('hex')}.tmp`;
+    try {
+        (0, private_files_js_1.ensurePrivateDir)((0, node_path_1.dirname)(LISTENER_ID_FILE));
+        (0, node_fs_1.writeFileSync)(tmp, `${id}\n`, { mode: 0o600, flag: 'wx' });
+        // After the write: the create mode is cut by the umask, and an older file's mode is not this one's.
+        (0, node_fs_1.chmodSync)(tmp, 0o600);
+        (0, private_files_js_1.handBackToSudoUser)(tmp);
+        (0, node_fs_1.renameSync)(tmp, LISTENER_ID_FILE);
+    }
+    catch {
+        try {
+            (0, node_fs_1.unlinkSync)(tmp);
+        }
+        catch { /* never created, or already renamed */ }
+        /* not writable: nothing is lost that was not already */
+    }
+};
+exports.rememberListenerId = rememberListenerId;
+/**
+ * ioreg by its absolute path: it lives in /usr/sbin, which a PATH from an IDE or a
+ * hook environment may lack, and a failed lookup falls back to a hostname hash —
+ * the same Mac registered as another device. launchd's own PATH has it; nothing
+ * else is promised. Shared by the listener, which registers the id, and the
+ * read-only reader here, so both read the same machine id.
+ */
+const IOREG = '/usr/sbin/ioreg';
+/**
+ * A stalled ioreg (IOKit wedged) used to hold every hook, `hwip rename` and the
+ * listener's start for as long as it hung. A timed-out run throws, which the
+ * caller reads as "no machine id" and falls back to the sticky file, then the
+ * hostname hash. mcp-server (config.ts IOREG_TIMEOUT_MS) gives up at the same
+ * 5 s and falls back the same way. The two run ioreg at different moments, so
+ * agreeing on the id still rests on ioreg being fast; this only keeps a wedged
+ * one from deciding who waits longest. A listener whose FIRST start (no sticky
+ * file yet) stalls keeps the hostname id until it restarts; on macOS that id is
+ * not written down, so the restart recovers (C109).
+ */
+const IOREG_TIMEOUT_MS = 5_000;
+/** Platform machine id (macOS IOPlatformUUID / Linux machine-id), or null. */
+const readMachineId = (deps = {}) => {
+    const platform = deps.platform ?? process.platform;
+    const exec = deps.exec ?? node_child_process_1.execFileSync;
+    try {
+        if (platform === 'darwin') {
+            // stdio: swallow ioreg's stderr so a one-off `hwip rename` / hook
+            // never leaks ioreg warnings to the terminal.
+            const out = exec(IOREG, ['-rd1', '-c', 'IOPlatformExpertDevice'], {
+                encoding: 'utf-8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+                timeout: IOREG_TIMEOUT_MS,
+            });
+            const m = out.match(/"IOPlatformUUID"\s*=\s*"([^"]+)"/);
+            if (m)
+                return m[1];
+        }
+        if (platform === 'linux') {
+            for (const p of ['/etc/machine-id', '/var/lib/dbus/machine-id']) {
+                try {
+                    const v = (0, node_fs_1.readFileSync)(p, 'utf-8').trim();
+                    if (v)
+                        return v;
+                }
+                catch { /* try next path */ }
+            }
+        }
+    }
+    catch { /* no machine id readable — fall through */ }
+    return null;
+};
+exports.readMachineId = readMachineId;
+/**
+ * Listener device id, resolved READ-ONLY — MUST equal what `listener.ts`
+ * `computeListenerDeviceId()` registers, so pushes tagged with this id land
+ * under the listener's device (otherwise a hook/notify reaches the feed but
+ * never threads into the agent chat). Hash the platform machine id first, then
+ * the sticky file the listener persisted, then a hostname hash — the same order
+ * as the writer, but never writing the file here.
+ */
+let cached;
+const listenerDeviceId = () => {
+    // The machine id does not change under a running process, and on macOS
+    // reading it is an `ioreg` spawn — once per process is enough.
+    cached ??= resolveListenerDeviceId();
+    return cached;
+};
+exports.listenerDeviceId = listenerDeviceId;
+const resolveListenerDeviceId = () => {
+    const machineId = (0, exports.readMachineId)();
+    if (machineId)
+        return (0, exports.hashListenerId)(machineId);
+    const saved = (0, exports.readStickyListenerId)();
+    if (saved)
+        return saved;
+    return (0, exports.hashListenerId)((0, node_os_1.hostname)());
+};

package/dist/listener-log.d.ts

@@ -0,0 +1,4 @@
+/** The listener's timestamped log line, and the switch that silences it for a CLI command. */
+export declare const silenceListenerLog: () => void;
+export declare const log: (msg: string) => void;
+//# sourceMappingURL=listener-log.d.ts.map

package/dist/listener-log.js

@@ -0,0 +1,23 @@
+"use strict";
+/** The listener's timestamped log line, and the switch that silences it for a CLI command. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.log = exports.silenceListenerLog = void 0;
+const stamp = () => new Date().toISOString().slice(11, 19);
+/**
+ * The daemon's log is stdout, which its supervisor redirects to a file. A CLI
+ * command that borrows these helpers has no such redirect — `hwip forget` calls
+ * `sessionExists`, and socket discovery logs from there — so the chatter would
+ * land in that command's own output, and inside a `--json` line it would break
+ * the parse.
+ */
+let logSilenced = false;
+const silenceListenerLog = () => {
+    logSilenced = true;
+};
+exports.silenceListenerLog = silenceListenerLog;
+const log = (msg) => {
+    if (logSilenced)
+        return;
+    console.log(`[${stamp()}] ${msg}`);
+};
+exports.log = log;

package/dist/listener-process.d.ts

@@ -0,0 +1,200 @@
+import { type ChildProcess } from 'node:child_process';
+export declare const LISTENER_PID_FILE: string;
+/** CLI version the running daemon booted from. Absent ⇒ pre-stamp build. */
+export declare const LISTENER_VERSION_FILE: string;
+/**
+ * The socket the running daemon actually connected to. A stamp rather than a
+ * line in listener.log, because the log rotates at 5MB and a long-lived daemon
+ * — exactly the one whose config edit has been outlived — loses its own startup
+ * line to that rotation, which would silently switch the staleness check off.
+ */
+export declare const LISTENER_WS_URL_FILE: string;
+export declare const LISTENER_LOG_FILE: string;
+export declare const sleep: (ms: number) => Promise<void>;
+/**
+ * PID of the listener on record, or null when the file is missing or stale.
+ * Stale PID files (process gone) read as "no listener" so a crashed daemon
+ * never blocks the next autostart.
+ */
+export declare const runningListenerPid: () => number | null;
+/**
+ * CLI version the running daemon started from, or null when unknown.
+ * null is meaningful: every build before the stamp existed predates the
+ * live-terminal protocol, so callers treat "unknown" as "stale".
+ */
+export declare const runningListenerVersion: () => string | null;
+/** Claim the singleton slot for THIS process and stamp the version with it. */
+export declare const writeListenerRuntime: (version: string, wsUrl?: string) => void;
+/** The socket the running daemon connected to, or null when it is unknown. */
+export declare const runningListenerWsUrl: () => string | null;
+/**
+ * Drop the PID/version stamps, but only when they still name `pid` — a
+ * successor that already claimed the slot must not be trampled by a
+ * predecessor's exit handler.
+ */
+export declare const clearListenerRuntime: (pid: number) => void;
+/**
+ * Drop stamps left behind by a daemon that died without running its exit
+ * handler (crash, SIGKILL, reboot-era leftovers). No-op while one is alive.
+ */
+export declare const clearStaleListenerRuntime: () => void;
+/** What `ps` says about a pid. */
+export type PidCommand = {
+    readonly kind: 'running';
+    readonly command: string;
+} | {
+    readonly kind: 'gone';
+} | {
+    readonly kind: 'unchecked';
+    readonly reason: string;
+};
+export declare const commandOfPid: (pid: number) => PidCommand;
+/**
+ * True when a command line is hwip's listener daemon: the word before
+ * `listener` is hwip's own script — the bin shim (`…/hwip`), the published
+ * package's entry (`…/@hwip/cli/dist/cli.js`: global install, npx), or this
+ * CLI's own file (a dev checkout). Any other `…/cli.js listener` (Zeph's runs
+ * on the same machines), or a file that only sits under a `hwip*` directory,
+ * does not pass. Exported for tests, which pass `ownCliPath`.
+ */
+export declare const isHwipListenerCommand: (command: string, ownCliPath?: string | null) => boolean;
+/** Whether the pid in the pid file is still hwip's listener. */
+export type ListenerPidCheck = {
+    readonly kind: 'ours';
+} | {
+    readonly kind: 'gone';
+}
+/** Another process holds the pid — only its program name, since its
+ *  arguments can hold secrets. */
+ | {
+    readonly kind: 'foreign';
+    readonly program: string;
+}
+/** hwip's listener from another checkout or worktree
+ *  (`…/cli-wt-x/dist/cli.js listener`), which `isHwipListenerCommand`
+ *  cannot vouch for. Left running with its stamps — clearing them would
+ *  let a second daemon start and answer every push twice. */
+ | {
+    readonly kind: 'other-listener';
+    readonly script: string;
+} | {
+    readonly kind: 'unchecked';
+    readonly reason: string;
+};
+/**
+ * The pid file can outlive a crashed daemon and its pid be reused by any
+ * process, so a pid is only ours while its command line says so.
+ */
+export declare const checkListenerPid: (pid: number, commandOf?: (pid: number) => PidCommand, isHwipScript?: (script: string) => boolean) => ListenerPidCheck;
+/** What every caller says about an `other-listener`. */
+export declare const otherListenerNote: (pid: number, script: string) => string;
+/**
+ * Whether the pid on record should be treated as a live listener: hwip's own
+ * or listener-shaped command line, or one `ps` could not check — two daemons
+ * answering the same pushes is the worse failure. `hwip verify` and the
+ * startup guard ask the same question.
+ */
+export declare const isListenerPid: (pid: number, commandOf?: (pid: number) => PidCommand) => boolean;
+/**
+ * The pid of another hwip listener holding the singleton slot, or null. A pid
+ * the OS handed to an unrelated process is not a listener: deferring to it
+ * would end launchd's or `hwip cc`'s daemon with exit 0 and leave no listener
+ * at all, so its stamps are cleared and the slot is free.
+ */
+export declare const otherListenerPid: (selfPid?: number, commandOf?: (pid: number) => PidCommand) => number | null;
+export type ListenerStop = {
+    readonly kind: 'stopped';
+}
+/** It outlived the grace window and took SIGKILL. */
+ | {
+    readonly kind: 'killed';
+} | Exclude<ListenerPidCheck, {
+    kind: 'ours';
+}>;
+/**
+ * Stop the daemon and wait for the process to actually go away — but only a
+ * process that is still hwip's listener (`checkListenerPid`); anything else is
+ * left alone and reported, and a pid file pointing at a stranger is cleared.
+ * SIGTERM first so its exit handler clears the stamps, SIGKILL once the grace
+ * window expires.
+ *
+ * Waiting matters: the caller's next move is spawning a replacement, and two
+ * live daemons on one machine both answer the same pushes.
+ */
+export declare const stopListener: (pid: number, commandOf?: (pid: number) => PidCommand, timeoutMs?: number) => Promise<ListenerStop>;
+/**
+ * Set by the listener on the `hwip <agent> --detach` it runs for a schedule. That child is the listener's own: when its
+ * build is newer than the running listener's (after an upgrade) `ensureListenerRunning` would restart the listener, and
+ * the restart would end the launch's own parent. With this set it leaves the listener alone, and removes the variable from
+ * its environment so that nothing the launch starts after it (the tmux server, the agent) inherits it.
+ */
+export declare const LISTENER_LAUNCH_ENV = "HWIP_LISTENER_LAUNCH";
+/**
+ * Path to the running cli.js entry. wrapper.js/listener.js sit next to cli.js
+ * in dist/, so __dirname resolves it directly — independent of how the user
+ * invoked us.
+ *
+ * `process.argv[1]` is unreliable here: when `hwip` runs via the npm-installed
+ * bin shim (`/usr/local/bin/hwip` → cli.js via a wrapper script), argv[1] is
+ * the shim path (`.../bin/hwip`), NOT `cli.js`. That made the original
+ * `/cli\.(js|ts|mjs|cjs)$/` check silently reject the entry and the autospawn
+ * never fired — the bug only surfaced once the user switched to the global
+ * npm install.
+ *
+ * Fall back to argv[1] only when the __dirname-relative file doesn't exist
+ * (some packaging where dist layout differs).
+ */
+export declare const resolveCliPath: () => string | null;
+export declare const rotateListenerLogIfLarge: () => void;
+/**
+ * How long a daemon `hwip cc` just spawned gets to fail. The fast deaths — no
+ * key, no tmux, no socket URL — come before the daemon writes its pid file;
+ * a rejected key closes the first socket within about a second.
+ */
+export declare const LISTENER_START_GRACE_MS = 1500;
+export type ListenerStart = {
+    readonly kind: 'running';
+}
+/** It exited 0: another daemon won the singleton slot, so one is running. */
+ | {
+    readonly kind: 'deferred';
+}
+/** It died inside the grace window; `line` is the last line it logged. */
+ | {
+    readonly kind: 'died';
+    readonly code: number | null;
+    readonly line: string | null;
+}
+/** launchd started it, and after the grace window it is not running. */
+ | {
+    readonly kind: 'not-up';
+    readonly line: string | null;
+} | {
+    readonly kind: 'not-spawned';
+};
+/** Why a start failed, in one line for the user; null when a listener is up. */
+export declare const startFailure: (started: ListenerStart) => string | null;
+/** Where the log ends now: what a start writes after this is that start's. */
+export declare const listenerLogSize: () => number;
+/**
+ * Spawn the daemon and watch it through the grace window. A daemon that dies
+ * on a missing key, a missing tmux or a rejected key only says so in the log,
+ * so `hwip cc` used to print "listener autostarted" over a dead one and the
+ * phone silently lost control.
+ */
+export declare const startListenerDetached: (spawnChild?: () => Pick<ChildProcess, "once" | "exitCode"> | null, graceMs?: number) => Promise<ListenerStart>;
+/** How long launchd gets to bring a kickstarted daemon as far as its pid file. */
+export declare const LISTENER_SERVICE_START_MS = 5000;
+/**
+ * After `launchctl kickstart`: launchd starts the daemon, so there is no child
+ * to watch — only the pid file it writes once its key, tmux and socket URL
+ * check out, and the log it says why in. A daemon that dies there is restarted
+ * by launchd on a loop, and `hwip cc` used to report it "started". Waits for a
+ * pid other than `previousPid` (the daemon `kickstart -k` replaced may still
+ * be shutting down), then for the grace window a rejected key needs.
+ */
+export declare const awaitServiceListener: (logOffset: number, previousPid: number | null, deps?: {
+    sleep: (ms: number) => Promise<void>;
+    runningPid: () => number | null;
+}, graceMs?: number, startMs?: number) => Promise<ListenerStart>;
+//# sourceMappingURL=listener-process.d.ts.map