@hwip/cli 0.0.1 → 0.1.1

package/dist/inventory-offload.d.ts

@@ -0,0 +1,49 @@
+import type { CollectResult } from './listener.js';
+export interface InventoryReply {
+    id: number;
+    result?: CollectResult;
+    error?: string;
+}
+export interface InventoryOffload {
+    /** Resolve one inventory sweep. Rejects when a working worker fails mid-sweep. */
+    collect: () => Promise<CollectResult>;
+    /** Stop the worker. Safe to call more than once. */
+    close: () => void;
+}
+/** Longer than any sane sweep (measured ~3s at 15 sessions), shorter than the
+ *  run of cycles a stuck worker would otherwise cost: the caller gates sweeps
+ *  one-at-a-time, so this bounds how long a hang can hold the inventory. */
+export declare const COLLECT_TIMEOUT_MS = 20000;
+/**
+ * Consecutive timed-out sweeps before the offload stops using workers.
+ *
+ * A sweep that overruns is terminated, and the next one starts a fresh worker
+ * from nothing — so on a host where a cold sweep cannot finish inside the
+ * timeout, retrying forever means the daemon never reports at all. Reporting
+ * slowly beats not reporting, and in-thread is exactly "slowly". Three in a row
+ * rather than one, so a single slow moment (a load spike, a machine waking) does
+ * not cost the offload straight away; the streak resets on any answered sweep.
+ */
+export declare const MAX_CONSECUTIVE_TIMEOUTS = 3;
+/**
+ * How long timed-out sweeps run in-thread before a worker is tried again.
+ *
+ * This used to be forever, which inverted the whole point of the offload: a
+ * load spike long enough to overrun three sweeps left the daemon running the
+ * blocking sweep on its own event loop for the rest of its life. Measured
+ * 2026-09-18 on this Mac — after the switch, a `setInterval(5_000)` fired at a
+ * median of 28.5 s, the WebSocket read loop went with it, and the heartbeat
+ * killed a healthy socket every 1-3 minutes.
+ *
+ * The load that overruns a sweep passes; the give-up must pass with it. Five
+ * minutes is long enough that a busy stretch is not spent respawning workers
+ * into the same wall, short enough that the degraded state is measured in
+ * minutes rather than days.
+ */
+export declare const IN_THREAD_COOLDOWN_MS: number;
+export declare const startInventoryOffload: (inThread: () => CollectResult, log: (msg: string) => void, workerPath?: string, 
+/** Overridable so a test can exercise the timeout path without waiting 20s. */
+timeoutMs?: number, 
+/** Overridable for the same reason as `timeoutMs`. */
+cooldownMs?: number) => InventoryOffload;
+//# sourceMappingURL=inventory-offload.d.ts.map

package/dist/inventory-offload.js

@@ -0,0 +1,209 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startInventoryOffload = exports.IN_THREAD_COOLDOWN_MS = exports.MAX_CONSECUTIVE_TIMEOUTS = exports.COLLECT_TIMEOUT_MS = void 0;
+/**
+ * Runs the tmux session inventory on a worker thread so the daemon's event
+ * loop stays free while `tmux` child processes are waited on.
+ *
+ * Why a thread and not async spawns: the inventory is a chain of synchronous
+ * `spawnSync` calls — one `list-sessions` plus `display-message` and
+ * `capture-pane` per session — and with 15 sessions a single sweep was measured
+ * at 3s on the main thread (57% of daemon wall time, measured 2026-08-26).
+ * Every one of those seconds the WebSocket was neither read nor written, so
+ * stream subscribes arrived late, frames left late, pongs were missed and leases
+ * lapsed. Moving the same synchronous code onto a worker keeps every tmux call
+ * exactly as it was — including the tests that stub `spawnSync` — and only
+ * changes which thread waits.
+ *
+ * The worker is optional. A worker that fails before it has ever answered
+ * (missing file, module error, immediate exit) is given up on: pending and
+ * future sweeps run in-thread as before, so a broken worker degrades to the old
+ * behaviour instead of an empty session list. A worker that dies after having
+ * worked is treated as transient — that sweep fails (the caller skips the
+ * cycle) and the next `collect()` starts a fresh one.
+ *
+ * A worker we killed ourselves is neither. `terminate()` (on timeout, on close)
+ * exits with code 1, indistinguishable from a crash, so the exit code cannot be
+ * read — what separates the two is whether that worker still owed an answer,
+ * which is why `Live` carries its own `owed` ids rather than sharing `pending`.
+ * Getting this wrong is expensive in one direction only: a timeout misread as
+ * "died before ever answering" is permanent, and it fires exactly when the host
+ * is slow enough for a sweep to overrun, which is when the offload matters most.
+ */
+const path_1 = require("path");
+const worker_threads_1 = require("worker_threads");
+/** Longer than any sane sweep (measured ~3s at 15 sessions), shorter than the
+ *  run of cycles a stuck worker would otherwise cost: the caller gates sweeps
+ *  one-at-a-time, so this bounds how long a hang can hold the inventory. */
+exports.COLLECT_TIMEOUT_MS = 20_000;
+/**
+ * Consecutive timed-out sweeps before the offload stops using workers.
+ *
+ * A sweep that overruns is terminated, and the next one starts a fresh worker
+ * from nothing — so on a host where a cold sweep cannot finish inside the
+ * timeout, retrying forever means the daemon never reports at all. Reporting
+ * slowly beats not reporting, and in-thread is exactly "slowly". Three in a row
+ * rather than one, so a single slow moment (a load spike, a machine waking) does
+ * not cost the offload straight away; the streak resets on any answered sweep.
+ */
+exports.MAX_CONSECUTIVE_TIMEOUTS = 3;
+/**
+ * How long timed-out sweeps run in-thread before a worker is tried again.
+ *
+ * This used to be forever, which inverted the whole point of the offload: a
+ * load spike long enough to overrun three sweeps left the daemon running the
+ * blocking sweep on its own event loop for the rest of its life. Measured
+ * 2026-09-18 on this Mac — after the switch, a `setInterval(5_000)` fired at a
+ * median of 28.5 s, the WebSocket read loop went with it, and the heartbeat
+ * killed a healthy socket every 1-3 minutes.
+ *
+ * The load that overruns a sweep passes; the give-up must pass with it. Five
+ * minutes is long enough that a busy stretch is not spent respawning workers
+ * into the same wall, short enough that the degraded state is measured in
+ * minutes rather than days.
+ */
+exports.IN_THREAD_COOLDOWN_MS = 5 * 60_000;
+const startInventoryOffload = (inThread, log, workerPath = (0, path_1.join)(__dirname, 'inventory-worker.js'), 
+/** Overridable so a test can exercise the timeout path without waiting 20s. */
+timeoutMs = exports.COLLECT_TIMEOUT_MS, 
+/** Overridable for the same reason as `timeoutMs`. */
+cooldownMs = exports.IN_THREAD_COOLDOWN_MS) => {
+    let worker = null;
+    let closed = false;
+    /** Set once a worker has answered; a failure before that is not transient. */
+    let everReplied = false;
+    /** Set when workers are given up on for good — a worker that never worked. */
+    let inThreadOnly = false;
+    /** While `Date.now()` is under this, timed-out sweeps run in-thread instead. */
+    let inThreadUntil = 0;
+    let nextId = 0;
+    /** Timed-out sweeps since the last answered one. */
+    let consecutiveTimeouts = 0;
+    const pending = new Map();
+    const settleAll = (outcome) => {
+        for (const [id, p] of pending) {
+            clearTimeout(p.timer);
+            pending.delete(id);
+            outcome(p);
+        }
+    };
+    const onFailure = (what) => {
+        if (closed)
+            return settleAll((p) => p.reject(new Error('inventory offload closed')));
+        if (everReplied)
+            return settleAll((p) => p.reject(new Error(what)));
+        inThreadOnly = true;
+        log(`! ${what} before its first sweep — running the inventory in-thread from now on`);
+        settleAll((p) => {
+            try {
+                p.resolve(inThread());
+            }
+            catch (err) {
+                p.reject(err instanceof Error ? err : new Error(String(err)));
+            }
+        });
+    };
+    const spawn = () => {
+        const w = new worker_threads_1.Worker(workerPath);
+        // Never keep the process alive on the worker's account: the daemon's
+        // own socket and timers decide when it exits.
+        w.unref();
+        const live = { w, owed: new Set() };
+        w.on('message', (msg) => {
+            live.owed.delete(msg.id);
+            const p = pending.get(msg.id);
+            if (!p)
+                return;
+            pending.delete(msg.id);
+            clearTimeout(p.timer);
+            everReplied = true;
+            consecutiveTimeouts = 0;
+            if (msg.error !== undefined)
+                p.reject(new Error(msg.error));
+            else
+                p.resolve(msg.result);
+        });
+        w.on('error', (err) => {
+            if (worker === live)
+                worker = null;
+            // Reported here, so the exit that follows is this same death and not
+            // a second one. An id leaves `owed` the moment its sweep is settled,
+            // whatever settled it — that is the invariant the exit handler reads.
+            live.owed.clear();
+            onFailure(`inventory worker error (${err instanceof Error ? err.message : String(err)})`);
+        });
+        w.on('exit', (code) => {
+            if (worker === live)
+                worker = null;
+            // Did THIS worker still owe an answer? `terminate()` exits with code
+            // 1 exactly like a crash, so the code says nothing; what separates a
+            // death we caused from one we did not is whether the sweep it was
+            // holding had already been settled. Asking the shared `pending` map
+            // instead judged a terminated worker against the NEXT worker's sweep
+            // — the timeout path nulls `worker`, so the following poll spawns a
+            // replacement and registers its id a second before this event lands.
+            // A routine timeout then read as "died before ever answering", which
+            // is permanent: `everReplied` is false, so the offload never
+            // recovers for the life of the daemon.
+            if (live.owed.size > 0)
+                onFailure(`inventory worker exited (${code})`);
+        });
+        return live;
+    };
+    const collect = () => {
+        if (closed || inThreadOnly)
+            return Promise.resolve(inThread());
+        if (inThreadUntil > 0) {
+            if (Date.now() < inThreadUntil)
+                return Promise.resolve(inThread());
+            inThreadUntil = 0;
+            // One strike, not three. The first degrade spends three sweeps
+            // finding out the host is too slow, and each of those costs a whole
+            // `timeoutMs` with no inventory at all (the caller skips the cycle
+            // and gates the next sweep behind this one). Paying that again on
+            // every cooldown expiry, on a host that is still loaded, is the
+            // "not reporting" this module exists to avoid.
+            consecutiveTimeouts = exports.MAX_CONSECUTIVE_TIMEOUTS - 1;
+            log('inventory: trying the worker again');
+        }
+        worker ??= spawn();
+        const live = worker;
+        const id = ++nextId;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                pending.delete(id);
+                // Settled here, so the terminate below is a death we caused and
+                // this worker's exit must not be reported as a failure.
+                live.owed.delete(id);
+                consecutiveTimeouts += 1;
+                if (consecutiveTimeouts >= exports.MAX_CONSECUTIVE_TIMEOUTS && !inThreadOnly && inThreadUntil === 0) {
+                    inThreadUntil = Date.now() + cooldownMs;
+                    const held = cooldownMs >= 60_000 ? `${Math.round(cooldownMs / 60_000)} min` : `${Math.round(cooldownMs / 1_000)}s`;
+                    log(`! inventory sweep timed out ${consecutiveTimeouts}× in a row — running the inventory in-thread for ${held}`);
+                }
+                reject(new Error(`inventory sweep exceeded ${timeoutMs / 1000}s`));
+                // A stuck worker is not coming back; the next call spawns a fresh one.
+                if (worker === live)
+                    worker = null;
+                void live.w.terminate();
+            }, timeoutMs);
+            timer.unref();
+            pending.set(id, { resolve, reject, timer });
+            live.owed.add(id);
+            live.w.postMessage(id);
+        });
+    };
+    const close = () => {
+        closed = true;
+        settleAll((p) => p.reject(new Error('inventory offload closed')));
+        const live = worker;
+        worker = null;
+        if (!live)
+            return;
+        // Settled above; clear what it owed for the same reason the timeout does.
+        live.owed.clear();
+        void live.w.terminate();
+    };
+    return { collect, close };
+};
+exports.startInventoryOffload = startInventoryOffload;

package/dist/inventory-worker.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=inventory-worker.d.ts.map

package/dist/inventory-worker.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Worker-thread entry for the tmux session inventory (see inventory-offload.ts).
+ * One sweep per request; the sweep itself is the unchanged synchronous
+ * `collectSessionsVerbose` — it only runs on this thread now.
+ */
+const worker_threads_1 = require("worker_threads");
+const agent_rules_fetch_js_1 = require("./agent-rules-fetch.js");
+const listener_js_1 = require("./listener.js");
+const port = worker_threads_1.parentPort;
+if (!port)
+    throw new Error('inventory-worker must be started as a worker thread');
+port.on('message', (id) => {
+    let reply;
+    try {
+        // Own module instance: pick up the OTA rules the main thread cached, else
+        // every non-claude session reports `unknown` (see syncManifestFromCache).
+        // Inside the try: a throw here must become an error reply, not a timeout.
+        (0, agent_rules_fetch_js_1.syncManifestFromCache)();
+        reply = { id, result: (0, listener_js_1.collectSessionsVerbose)() };
+    }
+    catch (err) {
+        reply = { id, error: err instanceof Error ? err.message : String(err) };
+    }
+    port.postMessage(reply);
+});

package/dist/jsonc-doc.d.ts

@@ -0,0 +1,106 @@
+import { type JSONPath } from 'jsonc-parser';
+/**
+ * An agent's settings file read as JSONC — comments and trailing commas allowed,
+ * the way the agents themselves read them — and changed by small edits to its
+ * text, so what the user wrote around hwip's entries (comments, their ordering,
+ * their indentation) stays exactly as it was. `jsonc-parser` (Microsoft, the
+ * parser VS Code uses for its own settings) does the parsing and the edits;
+ * this file only fixes the conventions hwip needs on top of it.
+ *
+ * Plain JSON is a subset, so a file without comments is read and edited the
+ * same way. A file with a syntax error is not read at all (`JsoncSyntaxError`):
+ * editing around a broken part could write something worse.
+ *
+ * Every edit is checked: the text after it must read back as exactly the value
+ * the edit was meant to produce. The library gets that wrong in places — removing
+ * an item of an array whose last two items share a line joins them into one or
+ * breaks the brackets — and a settings file that agents read must never be left
+ * like that. A file with
+ * no comments is then written whole from the intended value (nothing of the
+ * user's is lost); one with comments is left unchanged and the edit throws
+ * (`JsoncEditError`).
+ */
+export declare class JsoncSyntaxError extends Error {
+    constructor();
+}
+/** Valid JSONC, but the value is a list, a string, `null` — not a settings object. */
+export declare class JsoncNotObjectError extends Error {
+    constructor();
+}
+/** An edit the library could not apply correctly to a file whose comments a rewrite would lose. */
+export declare class JsoncEditError extends Error {
+    constructor();
+}
+/** The value of a JSONC text, or `undefined` when it has a syntax error. An empty text is `{}`. */
+export declare const parseJsonc: (text: string) => unknown;
+export declare class JsoncDoc {
+    private readonly bom;
+    private body;
+    private readonly formatting;
+    /** What the file held when it was read (null: there was no file), for `replaceFile` to check before it writes. */
+    readonly expected: string | null;
+    /**
+     * `text` is a settings file's content; throws `JsoncSyntaxError`, or `JsoncNotObjectError` when it is valid but not an object.
+     * `existed` is false for a file that was not there (`text` is then empty).
+     */
+    constructor(text: string, existed?: boolean);
+    /** The text without an entry that shares its line (a compact array or object), or null when a comment sits in the way. */
+    private withoutInline;
+    /** Would removing the entry at `path` take a comment with it (one inside the entry, or at the end of its last line)? */
+    removalTakesComment(path: JSONPath): boolean;
+    /** Does the text hold a comment? (Not one inside a string: the scanner knows tokens.) */
+    hasComments(): boolean;
+    /** Every comment in `text` with where it starts, in order. */
+    private static commentsIn;
+    /**
+     * Did `next` lose a comment of the current text that was not inside `allowed`
+     * (a range of the current text: what the edit may take with it)? The library
+     * drops comments around a removed entry it has no right to; a copy of the same
+     * text elsewhere does not stand in for a lost one.
+     */
+    private losesComment;
+    /** Take `next` as the new text if it reads back as `expected` and loses no comment but those in `allowed`; else see the class comment. */
+    private commit;
+    /** The current value, read again after every edit. */
+    get data(): Record<string, unknown>;
+    /** Set `path` to `value`, creating what is missing on the way. */
+    set(path: JSONPath, value: unknown): void;
+    /** Remove the property or array item at `path`. A comment right next to it goes with it. */
+    remove(path: JSONPath): void;
+    /**
+     * What removing the entry at `path` may take with it: the entry itself and the
+     * comment at the end of its last line — not one above it, nor one after the
+     * closing bracket of its container, which are not this entry's.
+     */
+    private removalZone;
+    /**
+     * The text without the lines of the entry at `path`, when it stands on lines of
+     * its own: its own comment and comma go with it, and so does the comma before it
+     * when it was the last one. A comment on another line, or on the line of the
+     * entry before, stays — the library would take the comment next to the entry
+     * along. An entry that shares its line with others goes through `withoutInline`.
+     */
+    private withoutLines;
+    /** Add `value` at the end of the array at `path`, after the comment on the last item's line. */
+    append(path: JSONPath, value: unknown): void;
+    /**
+     * The library's insert can leave a comment of the user's on the line of the new
+     * entry, and an uninstall would take it away with the entry (it is the entry's
+     * "own" comment by position). A new entry must have no comment in its removal
+     * zone; otherwise fail now, naming the file, and leave the text alone.
+     */
+    private refuseAdoptedComment;
+    /** `value` as JSON text in the file's own indentation unit. */
+    private render;
+    /**
+     * The text with `childText` put after the last child of an object or array, on a
+     * line of its own at the last child's indentation; null for an empty container
+     * or one whose last child shares its line with something else (the caller falls
+     * back). The library's insert would re-indent the siblings and move a comment at
+     * the end of the last child's line onto the new child.
+     */
+    private insertLast;
+    /** The file's new text: its byte order mark kept, one line ending at the end. */
+    text(): string;
+}
+//# sourceMappingURL=jsonc-doc.d.ts.map