@hwip/cli 0.0.1 → 0.1.1

package/dist/tmux-install.d.ts

@@ -0,0 +1,44 @@
+/**
+ * tmux is not optional for `hwip cc` — every remote-agent subcommand runs the
+ * agent inside a named tmux session so the listener (and the phone picker) can
+ * reach it. Nothing in the install flow used to mention that, so a machine
+ * without tmux looked fully set up until the first `hwip cc` failed with an
+ * error from a program the user was never told they needed.
+ */
+/** What this machine can do about a missing tmux. */
+export type TmuxInstallPlan = {
+    readonly kind: 'present';
+    readonly path: string;
+}
+/** Safe to run unattended — no root, user-writable prefix. */
+ | {
+    readonly kind: 'command';
+    readonly run: readonly string[];
+    readonly label: string;
+}
+/** Needs root, or there is no package manager we recognise. Tell, don't do. */
+ | {
+    readonly kind: 'manual';
+    readonly hint: string;
+};
+export declare const planTmuxInstall: (deps: {
+    resolve: (cmd: string) => string | null;
+    platform: NodeJS.Platform;
+}) => TmuxInstallPlan;
+/**
+ * Act on the plan. Everything the outside world touches is injected, because
+ * the interesting branch — "offer, then run a package manager" — is otherwise
+ * only reachable through an interactive install that no test can drive.
+ */
+export declare const ensureTmux: (deps: {
+    plan: TmuxInstallPlan;
+    nonInteractive: boolean;
+    askConfirm: (message: string) => Promise<boolean>;
+    run: (argv: readonly string[]) => void;
+    report: {
+        ok: (m: string) => void;
+        fail: (m: string) => void;
+        note: (m: string) => void;
+    };
+}) => Promise<void>;
+//# sourceMappingURL=tmux-install.d.ts.map

package/dist/tmux-install.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * tmux is not optional for `hwip cc` — every remote-agent subcommand runs the
+ * agent inside a named tmux session so the listener (and the phone picker) can
+ * reach it. Nothing in the install flow used to mention that, so a machine
+ * without tmux looked fully set up until the first `hwip cc` failed with an
+ * error from a program the user was never told they needed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureTmux = exports.planTmuxInstall = void 0;
+/** Package managers that need root, and the line to hand the user for each. */
+const ROOT_PACKAGE_MANAGERS = [
+    { bin: 'apt-get', hint: 'sudo apt install tmux' },
+    { bin: 'dnf', hint: 'sudo dnf install tmux' },
+    { bin: 'pacman', hint: 'sudo pacman -S tmux' },
+    { bin: 'zypper', hint: 'sudo zypper install tmux' },
+    { bin: 'apk', hint: 'sudo apk add tmux' },
+];
+const planTmuxInstall = (deps) => {
+    const path = deps.resolve('tmux');
+    if (path)
+        return { kind: 'present', path };
+    // tmux has no native Windows build. `hwip cc` is POSIX-only by way of tmux,
+    // so point at WSL rather than at a package that cannot be installed.
+    if (deps.platform === 'win32') {
+        return { kind: 'manual', hint: '`hwip cc` needs tmux, which has no Windows build — run it under WSL' };
+    }
+    if (deps.platform === 'darwin') {
+        return deps.resolve('brew')
+            ? { kind: 'command', run: ['brew', 'install', 'tmux'], label: 'brew install tmux' }
+            : { kind: 'manual', hint: 'install Homebrew (brew.sh), then: brew install tmux' };
+    }
+    const rootManager = ROOT_PACKAGE_MANAGERS.find((pm) => deps.resolve(pm.bin));
+    if (rootManager)
+        return { kind: 'manual', hint: rootManager.hint };
+    return { kind: 'manual', hint: 'install tmux with this system\'s package manager' };
+};
+exports.planTmuxInstall = planTmuxInstall;
+/**
+ * Act on the plan. Everything the outside world touches is injected, because
+ * the interesting branch — "offer, then run a package manager" — is otherwise
+ * only reachable through an interactive install that no test can drive.
+ */
+const ensureTmux = async (deps) => {
+    const { plan, report } = deps;
+    if (plan.kind === 'present')
+        return report.ok(`tmux found (${plan.path})`);
+    if (plan.kind === 'manual')
+        return report.fail(`tmux not found — \`hwip cc\` needs it. ${plan.hint}`);
+    if (deps.nonInteractive) {
+        return report.note(`tmux not found — \`hwip cc\` needs it. Run: ${plan.label}`);
+    }
+    const wanted = await deps.askConfirm(`tmux is missing and \`hwip cc\` needs it — run \`${plan.label}\`? (enter to confirm)`);
+    if (!wanted) {
+        return report.note(`tmux not installed — \`hwip cc\` will not work until you run: ${plan.label}`);
+    }
+    try {
+        deps.run(plan.run);
+        report.ok('tmux installed');
+    }
+    catch {
+        report.fail(`\`${plan.label}\` failed — run it by hand`);
+    }
+};
+exports.ensureTmux = ensureTmux;

package/dist/tmux-liveness.d.ts

@@ -0,0 +1,45 @@
+import type { SessionLiveness } from './session-registry.js';
+/**
+ * Every session name the tmux server currently holds, or null when there was no
+ * server to ask — the binary is missing, or nothing answers on the socket this
+ * process resolved.
+ *
+ * Null is not an empty list. `has-session` cannot tell the two apart: against a
+ * socket with nobody behind it it exits 1 — the same answer it gives for a name
+ * that ended (measured 2026-09-18). That matters because socket discovery falls
+ * back to the default socket, and a cron or launchd process that cannot see the
+ * user's server would otherwise call every live session an ended one.
+ */
+export declare const liveSessionNames: () => string[] | null;
+/**
+ * The three-state answer, for callers that destroy something on "ended".
+ *
+ * "tmux says no such session" and "no tmux answered" are not the same fact, and
+ * only one of them means the session is over. Collapsing them lets a missing
+ * binary or a socket nobody is behind read as "everything has ended" — which,
+ * on the delete path, is an irreversible deletion justified by a failure to ask.
+ *
+ * Asking for the whole list rather than `has-session -t =<name>` is what makes
+ * the distinction available at all, and the name comparison is then exact by
+ * construction — a tmux TARGET falls back to prefix and fnmatch matching, so
+ * with `hwip-hwipit` running an ended `hwip-hwip` used to answer "running".
+ */
+export declare const sessionLiveness: (name: string) => SessionLiveness;
+/**
+ * Whether this machine currently holds a session by this name. A subagent
+ * pane cannot be asked with has-session: tmux would parse `hwip-x.48` as
+ * session `hwip-x`, pane index 48 and answer for the WRONG thing (or exit 1
+ * for a missing index) — so subs are answered from the sweep's target map,
+ * which is exactly what "a pane we can address without ambiguity" means.
+ *
+ * An in-process subagent has no pane to address at all, so it is answered from
+ * the transcript map instead. Both maps are the same statement — the last sweep
+ * saw this thing — and the split is which of the two the sweep could record.
+ */
+/** Exported for the same reason as `sessionLiveness` above: the subagent branch is
+ *  the load-bearing one, and a test has to be able to reach it.
+ *  Unknown means "not running" here, which is what its callers — resume,
+ *  exit, stream targeting — already do with a session they cannot find. The
+ *  paths that DELETE ask `sessionLiveness` instead and refuse on unknown. */
+export declare const sessionExists: (name: string) => boolean;
+//# sourceMappingURL=tmux-liveness.d.ts.map

package/dist/tmux-liveness.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sessionExists = exports.sessionLiveness = exports.liveSessionNames = void 0;
+const child_process_1 = require("child_process");
+const tmux_pane_js_1 = require("./tmux-pane.js");
+const tmux_socket_js_1 = require("./tmux-socket.js");
+/**
+ * Every session name the tmux server currently holds, or null when there was no
+ * server to ask — the binary is missing, or nothing answers on the socket this
+ * process resolved.
+ *
+ * Null is not an empty list. `has-session` cannot tell the two apart: against a
+ * socket with nobody behind it it exits 1 — the same answer it gives for a name
+ * that ended (measured 2026-09-18). That matters because socket discovery falls
+ * back to the default socket, and a cron or launchd process that cannot see the
+ * user's server would otherwise call every live session an ended one.
+ */
+const liveSessionNames = () => {
+    const probe = (0, child_process_1.spawnSync)('tmux', (0, tmux_socket_js_1.tmuxArgs)(['list-sessions', '-F', '#{session_name}']), {
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    // A server with zero sessions does not exist — tmux exits with the last one
+    // — so a non-zero status here is always "no server answered", never "none".
+    if (probe.error || probe.status !== 0)
+        return null;
+    return (probe.stdout ?? '').split('\n').map((line) => line.trim()).filter(Boolean);
+};
+exports.liveSessionNames = liveSessionNames;
+/**
+ * The three-state answer, for callers that destroy something on "ended".
+ *
+ * "tmux says no such session" and "no tmux answered" are not the same fact, and
+ * only one of them means the session is over. Collapsing them lets a missing
+ * binary or a socket nobody is behind read as "everything has ended" — which,
+ * on the delete path, is an irreversible deletion justified by a failure to ask.
+ *
+ * Asking for the whole list rather than `has-session -t =<name>` is what makes
+ * the distinction available at all, and the name comparison is then exact by
+ * construction — a tmux TARGET falls back to prefix and fnmatch matching, so
+ * with `hwip-hwipit` running an ended `hwip-hwip` used to answer "running".
+ */
+const sessionLiveness = (name) => {
+    if ((0, tmux_pane_js_1.isSubagentSessionName)(name)) {
+        const known = tmux_pane_js_1.targetsBySession.has(name) || tmux_pane_js_1.subagentTranscriptsBySession.has(name);
+        return known ? 'running' : 'ended';
+    }
+    const names = (0, exports.liveSessionNames)();
+    if (names === null)
+        return 'unknown';
+    return names.includes(name) ? 'running' : 'ended';
+};
+exports.sessionLiveness = sessionLiveness;
+/**
+ * Whether this machine currently holds a session by this name. A subagent
+ * pane cannot be asked with has-session: tmux would parse `hwip-x.48` as
+ * session `hwip-x`, pane index 48 and answer for the WRONG thing (or exit 1
+ * for a missing index) — so subs are answered from the sweep's target map,
+ * which is exactly what "a pane we can address without ambiguity" means.
+ *
+ * An in-process subagent has no pane to address at all, so it is answered from
+ * the transcript map instead. Both maps are the same statement — the last sweep
+ * saw this thing — and the split is which of the two the sweep could record.
+ */
+/** Exported for the same reason as `sessionLiveness` above: the subagent branch is
+ *  the load-bearing one, and a test has to be able to reach it.
+ *  Unknown means "not running" here, which is what its callers — resume,
+ *  exit, stream targeting — already do with a session they cannot find. The
+ *  paths that DELETE ask `sessionLiveness` instead and refuse on unknown. */
+const sessionExists = (name) => (0, exports.sessionLiveness)(name) === 'running';
+exports.sessionExists = sessionExists;

package/dist/tmux-pane.d.ts

@@ -0,0 +1,55 @@
+import { type RegisteredRemoteAgent } from './remote-agents.js';
+export interface PaneInfo {
+    currentCommand: string | null;
+    startCommand: string | null;
+    currentPath: string | null;
+    panePid: number | null;
+}
+export declare const FIELD_SEP = "\u241F";
+/** Session name → pinned pane id, replaced wholesale by each inventory sweep. */
+export declare let targetsBySession: Map<string, string>;
+/**
+ * A subagent session name: `<session>.<pane id digits>` (`hwip-hwip.48`).
+ * tmux forbids `.` in session names, so the shape cannot collide; `#` would
+ * break the server's stream-sub keys and `:` is the web key separator.
+ */
+export declare const isSubagentSessionName: (name: string) => boolean;
+/** Store the latest sweep's name → pane-id map (see `CollectResult.targets`). */
+export declare const recordTargets: (targets: Record<string, string> | null | undefined) => void;
+/**
+ * Subagent name → the transcript it writes, for the ones that have no pane
+ * (`CollectResult.subagentTranscripts`). The addressing map above answers for
+ * pane subagents; this one answers for in-process ones, and it is deliberately
+ * NOT `targets`: a row in there is a pane every write path may address, and
+ * these rows have nothing to address.
+ */
+export declare let subagentTranscriptsBySession: Map<string, string>;
+export declare const recordSubagentTranscripts: (paths: Record<string, string> | null | undefined) => void;
+/** The transcript of an in-process subagent, or null for anything else. */
+export declare const subagentTranscriptFor: (name: string) => string | null;
+/**
+ * The tmux target for a wire session name: its pinned pane id when the last
+ * sweep saw the session, else the name itself (a session younger than one
+ * sweep, or tmux unreachable at startup — today's resolution, active pane).
+ *
+ * A SUBAGENT name is the one exception: it resolves ONLY through the map, and
+ * an unknown one is null — because tmux parses `hwip-hwip.48` as session
+ * `hwip-hwip`, pane INDEX 48, and silently falls back to the active pane when
+ * that index is missing (measured: `display -t hwip-hwip.99` → main pane,
+ * exit 0). Every caller treats null as "gone": no spawn, refusal, or capture
+ * failure — never a write to whichever pane happens to be focused.
+ */
+export declare const tmuxTargetFor: (name: string) => string | null;
+export declare const readPaneInfo: (session: string) => PaneInfo;
+/**
+ * Identify the agent from the tmux pane. Prefer `pane_start_command`
+ * because the foreground process is usually `node`/`python3` (the
+ * interpreter), which doesn't tell us *what* was launched. Fall back to
+ * `pane_current_command` when start_command is empty — tmux clears
+ * start_command in some re-attach cases, especially when a pre-existing
+ * session was joined via `tmux new -A` instead of being created fresh.
+ * That fallback is safe because only the literal binaries registered in
+ * remote-agents.ts are accepted as a match.
+ */
+export declare const detectRemoteAgent: (info: PaneInfo) => RegisteredRemoteAgent | null;
+//# sourceMappingURL=tmux-pane.d.ts.map

package/dist/tmux-pane.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectRemoteAgent = exports.readPaneInfo = exports.tmuxTargetFor = exports.subagentTranscriptFor = exports.recordSubagentTranscripts = exports.subagentTranscriptsBySession = exports.recordTargets = exports.isSubagentSessionName = exports.targetsBySession = exports.FIELD_SEP = void 0;
+const child_process_1 = require("child_process");
+const path_1 = require("path");
+const remote_agents_js_1 = require("./remote-agents.js");
+const tmux_socket_js_1 = require("./tmux-socket.js");
+// U+241F "Symbol for Unit Separator" — a *printable* Unicode glyph
+// (3-byte UTF-8) that visually represents the C0 Unit Separator but is
+// itself a normal character. Critical detail: tmux 3.5a's `-F` format
+// escapes raw control bytes (0x00-0x1F) like `\037` for terminal safety,
+// which broke an earlier `'\x1f'` separator — the byte we passed never
+// arrived at the consumer end. A printable Unicode char passes through
+// verbatim and won't appear in any real session name or filesystem path.
+exports.FIELD_SEP = '␟';
+// ─── Pane targets ───────────────────────────────────────────────────
+// A bare `-t <session>` resolves to whichever pane has FOCUS, so the moment a
+// second pane exists in a `hwip-*` session (pi-interactive-subagents splits
+// one off for every subagent), capture and input silently follow the user's
+// focus instead of the agent. The inventory sweep pins each session to its
+// main pane id, and every `-t` call site goes through `tmuxTargetFor` so the
+// pinning cannot be bypassed by one call site forgetting it.
+/** Session name → pinned pane id, replaced wholesale by each inventory sweep. */
+exports.targetsBySession = new Map();
+/**
+ * A subagent session name: `<session>.<pane id digits>` (`hwip-hwip.48`).
+ * tmux forbids `.` in session names, so the shape cannot collide; `#` would
+ * break the server's stream-sub keys and `:` is the web key separator.
+ */
+const isSubagentSessionName = (name) => /^hwip-.+\.\d+$/.test(name);
+exports.isSubagentSessionName = isSubagentSessionName;
+/** Store the latest sweep's name → pane-id map (see `CollectResult.targets`). */
+const recordTargets = (targets) => {
+    exports.targetsBySession = new Map(Object.entries(targets ?? {}));
+};
+exports.recordTargets = recordTargets;
+/**
+ * Subagent name → the transcript it writes, for the ones that have no pane
+ * (`CollectResult.subagentTranscripts`). The addressing map above answers for
+ * pane subagents; this one answers for in-process ones, and it is deliberately
+ * NOT `targets`: a row in there is a pane every write path may address, and
+ * these rows have nothing to address.
+ */
+exports.subagentTranscriptsBySession = new Map();
+const recordSubagentTranscripts = (paths) => {
+    exports.subagentTranscriptsBySession = new Map(Object.entries(paths ?? {}));
+};
+exports.recordSubagentTranscripts = recordSubagentTranscripts;
+/** The transcript of an in-process subagent, or null for anything else. */
+const subagentTranscriptFor = (name) => exports.subagentTranscriptsBySession.get(name) ?? null;
+exports.subagentTranscriptFor = subagentTranscriptFor;
+/**
+ * The tmux target for a wire session name: its pinned pane id when the last
+ * sweep saw the session, else the name itself (a session younger than one
+ * sweep, or tmux unreachable at startup — today's resolution, active pane).
+ *
+ * A SUBAGENT name is the one exception: it resolves ONLY through the map, and
+ * an unknown one is null — because tmux parses `hwip-hwip.48` as session
+ * `hwip-hwip`, pane INDEX 48, and silently falls back to the active pane when
+ * that index is missing (measured: `display -t hwip-hwip.99` → main pane,
+ * exit 0). Every caller treats null as "gone": no spawn, refusal, or capture
+ * failure — never a write to whichever pane happens to be focused.
+ */
+const tmuxTargetFor = (name) => {
+    const hit = exports.targetsBySession.get(name);
+    if (hit !== undefined)
+        return hit;
+    return (0, exports.isSubagentSessionName)(name) ? null : name;
+};
+exports.tmuxTargetFor = tmuxTargetFor;
+const readPaneInfo = (session) => {
+    const target = (0, exports.tmuxTargetFor)(session);
+    if (target === null)
+        return { currentCommand: null, startCommand: null, currentPath: null, panePid: null };
+    const r = (0, child_process_1.spawnSync)('tmux', (0, tmux_socket_js_1.tmuxArgs)(['display-message', '-p', '-t', target,
+        `#{pane_current_command}${exports.FIELD_SEP}#{pane_start_command}${exports.FIELD_SEP}#{pane_current_path}${exports.FIELD_SEP}#{pane_pid}`]), {
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    if (r.status !== 0)
+        return { currentCommand: null, startCommand: null, currentPath: null, panePid: null };
+    const parts = (r.stdout ?? '').trim().split(exports.FIELD_SEP);
+    if (parts.length !== 4)
+        return { currentCommand: null, startCommand: null, currentPath: null, panePid: null };
+    const [current, start, path, pid] = parts;
+    const parsedPid = Number(pid);
+    return {
+        currentCommand: current || null,
+        startCommand: start || null,
+        currentPath: path || null,
+        panePid: Number.isInteger(parsedPid) && parsedPid > 0 ? parsedPid : null,
+    };
+};
+exports.readPaneInfo = readPaneInfo;
+/**
+ * Strip the surrounding quotes tmux uses when serialising commands
+ * with spaces. `tmux display-message -p '#{pane_start_command}'`
+ * outputs `"claude --resume xxx"` (literal double-quotes around the
+ * whole shell-command form the wrapper passed). Without unwrapping,
+ * the leading `"` made the basename check fail and the listener
+ * skipped the session as 'no agent in pane'.
+ */
+const unwrapQuotes = (cmd) => {
+    const m = cmd.match(/^"(.+)"$/) || cmd.match(/^'(.+)'$/);
+    return m ? m[1] : cmd;
+};
+const firstTokenBasename = (cmd) => {
+    if (!cmd)
+        return '';
+    const stripped = unwrapQuotes(cmd.trim());
+    return (0, path_1.basename)(stripped.split(/\s+/)[0] || '');
+};
+/**
+ * Identify the agent from the tmux pane. Prefer `pane_start_command`
+ * because the foreground process is usually `node`/`python3` (the
+ * interpreter), which doesn't tell us *what* was launched. Fall back to
+ * `pane_current_command` when start_command is empty — tmux clears
+ * start_command in some re-attach cases, especially when a pre-existing
+ * session was joined via `tmux new -A` instead of being created fresh.
+ * That fallback is safe because only the literal binaries registered in
+ * remote-agents.ts are accepted as a match.
+ */
+const detectRemoteAgent = (info) => (0, remote_agents_js_1.matchAgentByPaneCommand)(firstTokenBasename(info.startCommand))
+    ?? (0, remote_agents_js_1.matchAgentByPaneCommand)(firstTokenBasename(info.currentCommand))
+    ?? null;
+exports.detectRemoteAgent = detectRemoteAgent;

package/dist/tmux-socket.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Mark the cached socket as no longer trustworthy — call this when a
+ * tmux command fails against the cached path. The next findTmuxSocket()
+ * will redo full discovery (default probe → /var/folders walk → lsof
+ * fallback) instead of returning a stale answer. Without this the
+ * listener wedged at "reported 0 session(s)" forever after a tmux
+ * server restart, even when a new server was live and discoverable.
+ */
+export declare const invalidateTmuxSocketCache: () => void;
+/**
+ * One name per socket file: the path with its symlinks resolved, or the path
+ * as given when nothing is there to resolve. macOS reaches the same directory
+ * as `/tmp/…` and `/private/tmp/…`, and as `/var/folders/…` and
+ * `/private/var/folders/…`; without this each dead socket there is probed
+ * once per spelling.
+ */
+export declare const socketKey: (path: string) => string;
+/** Prepend `-S <socket>` when we've discovered a non-default tmux server. */
+export declare const tmuxArgs: (args: string[]) => string[];
+//# sourceMappingURL=tmux-socket.d.ts.map