@hwip/cli 0.0.1 → 0.1.0

package/dist/worktree.js

@@ -0,0 +1,310 @@
+"use strict";
+/**
+ * `hwip <agent> --wt <name>`: a git worktree made for a session, and taken back
+ * when the session is over and nothing in it would be lost.
+ *
+ * hwip only ever removes a worktree it made itself — the rows in
+ * `<stateDir>/worktrees.json` are the whole list. A worktree the user made by
+ * hand, or one `--wt` merely found at the path, has no row and no code path
+ * here that removes it. Every doubt about a worktree (a git call that fails or
+ * times out, a count that does not parse) reads as "keep it": the cost of a
+ * leftover directory is a line in `hwip worktree`, the cost of a wrong removal
+ * is somebody's work. `--force`, `rm -rf` and `branch -D` are not used anywhere.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readPaneCwds = exports.worktreeStatuses = exports.reconcileWorktrees = exports.inspectWorktree = exports.ensureWorktree = exports.isValidBranchName = exports.worktreeDirName = exports.updateWorktreeRows = exports.readWorktreeRows = exports.tmuxRun = exports.gitRun = exports.commandRunner = void 0;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const config_js_1 = require("./config.js");
+const gate_js_1 = require("./gate.js");
+const private_files_js_1 = require("./private-files.js");
+const replace_file_js_1 = require("./replace-file.js");
+const GIT_TIMEOUT_MS = 10_000;
+const firstLine = (text) => text.trim().split('\n')[0] ?? '';
+/** `execFile` of one command with argv (no shell: branch names and paths are user input), as a `GitRun`. */
+const commandRunner = (cmd) => (args, timeoutMs = GIT_TIMEOUT_MS) => new Promise((resolve) => {
+    (0, child_process_1.execFile)(cmd, args, { encoding: 'utf-8', timeout: timeoutMs }, (err, stdout, stderr) => {
+        if (!err)
+            return resolve({ ok: true, stdout });
+        if ('code' in err && err.code === 'ENOENT')
+            return resolve({ ok: false, error: `${cmd} not found` });
+        const timedOut = 'killed' in err && err.killed;
+        resolve({ ok: false, error: timedOut ? `${cmd} timed out` : firstLine(stderr) || err.message });
+    });
+});
+exports.commandRunner = commandRunner;
+exports.gitRun = (0, exports.commandRunner)('git');
+exports.tmuxRun = (0, exports.commandRunner)('tmux');
+const registryPath = () => (0, path_1.join)((0, gate_js_1.stateDir)(), 'worktrees.json');
+const isRow = (e) => {
+    if (!e || typeof e !== 'object')
+        return false;
+    const row = e; // shape-checked field by field below
+    return ['path', 'root', 'branch', 'baseSha', 'createdAt'].every((k) => typeof row[k] === 'string')
+        && typeof row.createdBranch === 'boolean'
+        && (row.reasons === undefined || (Array.isArray(row.reasons) && row.reasons.every((r) => typeof r === 'string')));
+};
+/** Rows that still make sense: a half-written or hand-edited file must not stop a launch. */
+const parseRows = (text) => {
+    if (!text)
+        return [];
+    try {
+        const parsed = JSON.parse(text);
+        return Array.isArray(parsed) ? parsed.filter(isRow) : [];
+    }
+    catch {
+        return [];
+    }
+};
+const readWorktreeRows = () => {
+    try {
+        return parseRows((0, fs_1.readFileSync)(registryPath(), 'utf-8'));
+    }
+    catch {
+        return [];
+    }
+};
+exports.readWorktreeRows = readWorktreeRows;
+/**
+ * Read, change, write. A row that cannot be written is a worktree that is not
+ * cleaned up automatically — the launch goes on. `expected` turns a write by
+ * the other process (wrapper vs listener) since the read into an error, which
+ * lands here too: a lost row only ever means "kept".
+ */
+const updateWorktreeRows = (change) => {
+    const path = registryPath();
+    try {
+        const text = (0, replace_file_js_1.readTextIfExists)(path);
+        (0, replace_file_js_1.replaceFile)(path, JSON.stringify(change(parseRows(text)), null, 2), text, 0o600);
+        (0, private_files_js_1.handBackToSudoUser)(path);
+    }
+    catch {
+        /* the registry is a convenience, not a gate */
+    }
+};
+exports.updateWorktreeRows = updateWorktreeRows;
+const refuse = (error, usage = false) => ({ ok: false, error, usage });
+/** The worktrees `git worktree list --porcelain` knows: realpath → branch ref (null when detached). */
+const listWorktrees = async (root, run) => {
+    const out = await run(['-C', root, 'worktree', 'list', '--porcelain']);
+    if (!out.ok)
+        return null;
+    const found = new Map();
+    for (const block of out.stdout.split('\n\n')) {
+        const lines = block.split('\n');
+        const path = lines.find((l) => l.startsWith('worktree '))?.slice('worktree '.length);
+        if (!path)
+            continue;
+        found.set(path, lines.find((l) => l.startsWith('branch '))?.slice('branch '.length) ?? null);
+    }
+    return found;
+};
+const realOrSelf = (path) => {
+    try {
+        return (0, fs_1.realpathSync)(path);
+    }
+    catch {
+        return path;
+    }
+};
+/**
+ * The directory name of the worktree for branch `name` of the repo at `root`: `<repo>-wt-<name with separators as dashes>`.
+ * Null when nothing but separators is left. `hwip schedule add` names its session from this, so the two cannot drift.
+ */
+const worktreeDirName = (root, name) => {
+    const slug = name.replace(/[/.:;\s]+/g, '-');
+    return slug.replace(/-/g, '') ? `${(0, path_1.basename)(root)}-wt-${slug}` : null;
+};
+exports.worktreeDirName = worktreeDirName;
+/** Whether `name` is a branch name git accepts as it stands (`--branch` also expands `@{-1}`-style names; one that changes is not what was typed). */
+const isValidBranchName = async (root, name, run = exports.gitRun) => {
+    const checked = await run(['-C', root, 'check-ref-format', '--branch', name]);
+    return checked.ok && checked.stdout.trim() === name;
+};
+exports.isValidBranchName = isValidBranchName;
+/**
+ * The worktree for branch `name` next to the main checkout of the repo `dir` is
+ * in — made, or found already made by this same command. Anything else at the
+ * path is refused and left alone.
+ */
+const ensureWorktree = async ({ dir, name }, run = exports.gitRun) => {
+    const root = (0, config_js_1.checkoutOf)(dir)?.root;
+    if (!root)
+        return refuse('--wt needs a git checkout with a main worktree');
+    if (!name || name.startsWith('-'))
+        return refuse(`--wt needs a branch name (got '${name}')`, true);
+    if (!(await (0, exports.isValidBranchName)(root, name, run)))
+        return refuse(`'${name}' is not a valid branch name`, true);
+    const dirName = (0, exports.worktreeDirName)(root, name);
+    if (!dirName)
+        return refuse(`'${name}' is not a usable worktree name`, true);
+    const path = (0, path_1.join)((0, path_1.dirname)(root), dirName);
+    const known = await listWorktrees(root, run);
+    if (!known)
+        return refuse(`could not list worktrees of ${root}`);
+    const there = [...known].find(([listed]) => realOrSelf(listed) === realOrSelf(path));
+    const present = (0, fs_1.lstatSync)(path, { throwIfNoEntry: false }) !== undefined;
+    if (present && there?.[1] === `refs/heads/${name}`)
+        return { ok: true, path: realOrSelf(path), branch: name, created: false };
+    // Registered but gone, a plain directory, a file, a worktree of another branch: none of them is ours to touch.
+    if (present || there)
+        return refuse(`${path} exists and is not the worktree for ${name}`);
+    const branchExists = (await run(['-C', root, 'show-ref', '--verify', '--quiet', `refs/heads/${name}`])).ok;
+    // A new branch starts where the command was typed; one that exists is checked out as it is.
+    const added = branchExists
+        ? await run(['-C', root, 'worktree', 'add', path, name], 0)
+        : await run(['-C', dir, 'worktree', 'add', '-b', name, path], 0);
+    if (!added.ok)
+        return refuse(added.error);
+    const made = realOrSelf(path);
+    const head = await run(['-C', made, 'rev-parse', 'HEAD']);
+    if (head.ok) {
+        const row = {
+            path: made, root, branch: name, baseSha: head.stdout.trim(),
+            createdBranch: !branchExists, createdAt: new Date().toISOString(),
+        };
+        (0, exports.updateWorktreeRows)((rows) => [...rows.filter((r) => r.path !== made), row]);
+    }
+    return { ok: true, path: made, branch: name, created: true };
+};
+exports.ensureWorktree = ensureWorktree;
+const plural = (n, noun) => `${n} ${noun}${n === 1 ? '' : 's'}`;
+/**
+ * Whether this worktree can go without losing anything. Asked in git's own
+ * terms rather than left to `git worktree remove`, which deletes a worktree
+ * holding only ignored files (a hand-written `.env`) and one whose commits
+ * were never pushed (measured, git 2.47.0). Both checks always run, so the
+ * reasons are the whole list; a check that cannot be answered is a reason too.
+ */
+const inspectWorktree = async (row, run = exports.gitRun) => {
+    const reasons = [];
+    // A row ties a worktree to its path only. If the user removed this one and made their own at the same path, it is theirs.
+    const known = await listWorktrees(row.root, run);
+    const listed = known ? [...known].find(([path]) => realOrSelf(path) === realOrSelf(row.path)) : undefined;
+    if (!known)
+        reasons.push('could not check: worktrees not listed');
+    else if (!listed)
+        reasons.push('not a worktree git knows any more');
+    else if (listed[1] !== `refs/heads/${row.branch}`)
+        reasons.push(`no longer on branch ${row.branch}`);
+    // Explicit, because `status.showUntrackedFiles=no` and `diff.ignoreSubmodules` would otherwise hide what `worktree remove` deletes.
+    const status = await run(['-C', row.path, 'status', '--porcelain', '--ignored', '--untracked-files=normal', '--ignore-submodules=none']);
+    if (!status.ok) {
+        reasons.push(`could not check: ${status.error}`);
+    }
+    else {
+        const lines = status.stdout.split('\n').filter(Boolean);
+        const ignored = lines.filter((l) => l.startsWith('!!')).length;
+        if (lines.length > ignored)
+            reasons.push(`${lines.length - ignored} uncommitted or untracked`);
+        if (ignored)
+            reasons.push(`${ignored} ignored`);
+    }
+    // Not `--all`: that includes this worktree's own HEAD and always counts it.
+    const ahead = await run(['-C', row.path, 'rev-list', '--count', 'HEAD', '--not', row.baseSha, '--remotes']);
+    const count = ahead.ok ? Number(ahead.stdout.trim()) : NaN;
+    if (!ahead.ok)
+        reasons.push(`could not check: ${ahead.error}`);
+    else if (!Number.isInteger(count))
+        reasons.push('could not check: unreadable commit count');
+    else if (count > 0)
+        reasons.push(`${plural(count, 'unpushed commit')}`);
+    const distinct = [...new Set(reasons)];
+    return distinct.length ? { removable: false, reasons: distinct } : { removable: true };
+};
+exports.inspectWorktree = inspectWorktree;
+const within = (cwd, path) => cwd === path || cwd.startsWith(path + path_1.sep);
+/**
+ * Which of the worktrees hwip made to take back, and which to keep and say why.
+ *
+ * Automatic (`manual` off): a worktree is judged once, after a pane was last
+ * seen inside it and none is now. Judging again later would delete a directory
+ * somebody went back into and pushed from, so a worktree that was kept stays
+ * kept until `hwip worktree clean`, or until a session uses it again.
+ *
+ * Rows are re-read when written, so a row the wrapper added while git was
+ * being asked about is not lost.
+ */
+const reconcileWorktrees = async (input, run = exports.gitRun) => {
+    const { manual = false, dryRun = false } = input;
+    const now = (input.now ?? new Date()).toISOString();
+    const panes = input.paneCwds.map(realOrSelf);
+    const report = { removed: [], kept: [], inUse: [], gone: [] };
+    const drop = new Set();
+    const patch = new Map();
+    for (const row of (0, exports.readWorktreeRows)()) {
+        if ((0, fs_1.lstatSync)(row.path, { throwIfNoEntry: false }) === undefined) {
+            report.gone.push(row.path);
+            drop.add(row.path);
+            continue;
+        }
+        if (panes.some((cwd) => within(cwd, row.path))) {
+            report.inUse.push(row.path);
+            patch.set(row.path, { sessionSeenAt: now, keptAt: undefined, reasons: undefined });
+            continue;
+        }
+        if (!manual && (!row.sessionSeenAt || row.keptAt))
+            continue;
+        const verdict = await (0, exports.inspectWorktree)(row, run);
+        if (!verdict.removable) {
+            report.kept.push({ path: row.path, branch: row.branch, reasons: verdict.reasons, removeFailed: false });
+            if (!manual)
+                patch.set(row.path, { keptAt: now, reasons: verdict.reasons });
+            continue;
+        }
+        if (dryRun) {
+            report.removed.push({ path: row.path, branch: row.branch, branchDeleted: false });
+            continue;
+        }
+        // No `--force`: git refuses a worktree that gained a change since the check.
+        const removed = await run(['-C', row.root, 'worktree', 'remove', row.path]);
+        if (!removed.ok) {
+            report.kept.push({ path: row.path, branch: row.branch, reasons: [removed.error], removeFailed: true });
+            if (!manual)
+                patch.set(row.path, { keptAt: now, reasons: [removed.error] });
+            continue;
+        }
+        // `-d`, never `-D`: git refuses a branch that is not merged, and that branch stays.
+        const branchDeleted = row.createdBranch && (await run(['-C', row.root, 'branch', '-d', row.branch])).ok;
+        report.removed.push({ path: row.path, branch: row.branch, branchDeleted });
+        drop.add(row.path);
+    }
+    if (!dryRun && (drop.size || patch.size)) {
+        (0, exports.updateWorktreeRows)((rows) => rows
+            .filter((r) => !drop.has(r.path))
+            .map((r) => (patch.has(r.path) ? { ...r, ...patch.get(r.path) } : r)));
+    }
+    return report;
+};
+exports.reconcileWorktrees = reconcileWorktrees;
+/** What `hwip worktree` shows: every row with its state now. Read-only. */
+const worktreeStatuses = async (paneCwds, run = exports.gitRun) => {
+    const panes = paneCwds.map(realOrSelf);
+    return Promise.all((0, exports.readWorktreeRows)().map(async (row) => {
+        if ((0, fs_1.lstatSync)(row.path, { throwIfNoEntry: false }) === undefined)
+            return { row, state: 'directory gone' };
+        if (panes.some((cwd) => within(cwd, row.path)))
+            return { row, state: 'in use' };
+        const verdict = await (0, exports.inspectWorktree)(row, run);
+        if (!verdict.removable)
+            return { row, state: verdict.reasons.join(', ') };
+        return { row, state: row.sessionSeenAt ? 'clean' : 'never used' };
+    }));
+};
+exports.worktreeStatuses = worktreeStatuses;
+// Measured on tmux 3.5a: a server that is not there says `no server running on <socket>` (stale socket file) or
+// `error connecting to <socket> (No such file or directory)`; `(Permission denied)` and the rest are not "no panes".
+const NO_TMUX_SERVER = /^(no server running on |error connecting to .+ \(No such file or directory\)$)/;
+/**
+ * The cwd of every live tmux pane, `[]` when there is no tmux server, null when
+ * tmux could not be asked. The difference matters: an unreadable list read as
+ * empty would make every worktree in use look abandoned.
+ */
+const readPaneCwds = async (tmux = exports.tmuxRun) => {
+    const out = await tmux(['list-panes', '-a', '-F', '#{pane_current_path}']);
+    if (out.ok)
+        return out.stdout.split('\n').filter(Boolean);
+    return NO_TMUX_SERVER.test(out.error) ? [] : null;
+};
+exports.readPaneCwds = readPaneCwds;

package/dist/wrapper.d.ts

@@ -0,0 +1,254 @@
+import { type TmuxInstallPlan } from './tmux-install.js';
+import type { RemoteAgent } from './remote-agents.js';
+/** basename(), with a stable fallback for edge paths like `/`. */
+export declare const safeBasename: (path: string) => string;
+/** The directory the session is named for: env > git root > cwd. Null when git is the answer and there is no repo. */
+export declare const detectProjectDir: () => string;
+/** Resolve a project name for the tmux session: env > git root > cwd basename. */
+export declare const detectProjectName: () => string;
+/**
+ * tmux commands, chained after `new`, that tell the listener which project
+ * the session belongs to when its name does not say so: a `--label` tail and a
+ * worktree's directory name both read as part of the project otherwise, and
+ * each opened a card of its own. Nothing when the name already says it all, so
+ * a plain family session is reported exactly as before. The rule is config
+ * `groupOf`, which the listener also applies to sessions started without these.
+ *
+ * Each option names its session (`-t =<session>:`). An untargeted `set-option`
+ * applies to the client's current session, and a launch from inside tmux (a
+ * `--detach` from an agent's pane) would relabel the caller instead of the new
+ * session (measured on tmux 3.5a).
+ */
+export declare const sessionSidecarArgs: (session: string, projectDir: string, label?: string) => string[];
+/**
+ * tmux commands, chained after `new -A`, that point config
+ * `HERDR_SESSION_OPTIONS` at the herdr pane this attach runs in, or clear them
+ * outside herdr.
+ */
+export declare const herdrSessionArgs: (session: string, env?: NodeJS.ProcessEnv) => string[];
+/**
+ * `hwip-<project>` — the canonical tmux session base name. tmux itself turns
+ * `.` and `:` into `_` when it creates a session (3.5a: `hwip-foo.bar` becomes
+ * `hwip-foo_bar`), so the name is written that way up front: every later
+ * `-t =<name>` must match what tmux actually holds. `;` goes too — an argv
+ * element ending in one is a tmux command separator.
+ */
+export declare const tmuxSessionName: (project: string) => string;
+/** The first name in the family no live session holds — for a launch that can only create. */
+export declare const firstFreeSession: (base: string) => string;
+/**
+ * Pick a tmux session name that won't steal focus from another live
+ * `hwip cc`. Strategy:
+ *   - Reuse the **highest-numbered detached** session in the family.
+ *   - Otherwise take the lowest name that doesn't exist yet (create new),
+ *     so an all-attached family gets an independent `<base>-N`.
+ *
+ * Highest-detached rather than lowest is what keeps the family reachable.
+ * The old scan walked the family in order and returned the first session that
+ * was missing *or* detached, which meant a detached `<base>` ended the scan
+ * every time: `<base>-2` could not be reached by any later `hwip cc`, not even
+ * after `<base>` was used and exited (a missing `<base>` is taken fresh). A
+ * session nobody can reach still holds a live agent — a Claude Code CLI plus
+ * its MCP fleet, 250-550MB measured — so stranding one leaks memory the user
+ * can neither see nor reclaim. Draining from the tail makes every suffix
+ * reachable again: the tail goes first, and `<base>` is picked on the run
+ * after that. Reuse also wins over a gap in the numbering, for the same
+ * reason — a free `<base>-2` must not hide a detached `<base>-3`.
+ *
+ * Reclaiming is deliberately all this does. Killing a detached session would
+ * take a live agent with it, and nothing here can tell "the user is done with
+ * this" from "the user closed the terminal and will come back".
+ */
+export declare const findAvailableSession: (base: string, 
+/** The agent about to be started. A detached session that is running a
+ *  different one is not a slot for it — see `sameAgent` below. Omitted by
+ *  callers that have no kind to match, which keeps the old behaviour. */
+agentKind?: string, 
+/** Test seam: what this machine recorded about a session name. */
+recall?: (name: string) => {
+    agentKind: string;
+} | null) => string;
+export interface SpawnTarget {
+    /**
+     * `tmux-new` opens (or reattaches) a session and needs a terminal to
+     * attach to; `direct` runs the agent in the pane we are already in and
+     * does not. Several decisions downstream turn on which one this is, so
+     * `targetForAgent` states it rather than letting them re-derive it from
+     * `cmd === 'tmux'`.
+     */
+    kind: 'direct' | 'tmux-new' | 'tmux-detached';
+    cmd: string;
+    args: string[];
+    /** The tmux session name for the two tmux kinds — carried, not re-read off argv. */
+    session?: string;
+}
+/**
+ * `hwip <agent> --detach --label <x> --wt <name> …` — the wrapper-owned flags. They
+ * are read off the FRONT of the passthrough only, so an agent's own flags
+ * (`pi -n`, `claude --resume`) and its positional messages pass untouched.
+ */
+export interface AgentLaunchOptions {
+    /** Create the tmux session without attaching, print its name, exit 0. */
+    detach?: boolean;
+    /** Name the session `hwip-<project>-<label>` instead of the `-2/-3` family. */
+    label?: string;
+    /** `--wt <name>`: run in the git worktree for this branch, made next to the repo if it is not there. */
+    worktree?: string;
+    /** Set by `handleAgentSession` once the worktree exists — not a flag. The directory the session is named for, in place of `detectProjectDir()`. */
+    projectDir?: string;
+}
+/**
+ * tmux forbids `.` and `:` in session names; whitespace would split the target;
+ * and an argv element ending in `;` is a tmux command separator.
+ */
+export declare const sanitizeLabel: (label: string) => string;
+export declare const splitAgentOptions: (extra: string[]) => {
+    opts: AgentLaunchOptions;
+    rest: string[];
+    error?: string;
+};
+export declare const targetForAgent: (agent: string, extra: string[], agentKind?: string, opts?: AgentLaunchOptions) => SpawnTarget;
+/**
+ * Whether the daemon on record is running a different build than the one
+ * we're launching from. `npm i -g @hwip/cli` swaps dist/ but leaves the
+ * live process untouched, so a daemon can stay days behind the installed
+ * package — answering pushes (chat looks fine) while silently ignoring every
+ * message subtype added since it booted. That is exactly how a pre-1.24
+ * listener left the phone's live terminal spinning until a reboot.
+ *
+ * A missing stamp means the daemon predates version stamping, which puts it
+ * behind by definition — treat unknown as drifted.
+ *
+ * Strictly "installed is newer", never a plain inequality: one account can
+ * have several installs at different versions (nvm node versions, a repo
+ * build alongside the global one), and `!==` would make each `hwip cc` kill
+ * and respawn the other's daemon forever. An older `hwip cc` leaves a newer
+ * daemon alone — downgrading it would reintroduce the very gap this closes.
+ */
+export declare const listenerVersionDrifted: (running: string | null, installed: string) => boolean;
+/**
+ * Whether the listener started this process for a schedule (`LISTENER_LAUNCH_ENV`), and the marker used up: left in the
+ * environment it would reach the git hooks of a `--wt` worktree and the tmux server this launch may start, and so every pane after it.
+ */
+export declare const takeListenerLaunchMarker: () => boolean;
+/**
+ * Make sure the phone-bridge daemon is running AND is the build we just
+ * launched from. `hwip cc` is the right moment to replace a drifted one: the
+ * user is starting fresh work rather than mid-task, so the ~1s restart window
+ * (in which a push would be dropped — WS fan-out has no queue) costs nothing.
+ */
+export declare const ensureListenerRunning: (launchedByListener?: boolean) => Promise<void>;
+/**
+ * Launch the agent in a named tmux session (or directly if nested) and
+ * forward its exit code. `extra` is appended to the agent invocation, so
+ * `hwip cc --resume foo` runs `claude --resume foo` inside the session.
+ * Returns when the agent exits.
+ */
+/** `process.execve` with the optionality resolved — see handOffExec. */
+export type ProcessHandOff = NonNullable<typeof process.execve>;
+/** The hand-off handOffExec returns: execve with the environment already bound. */
+type HandOff = (file: string, argv: string[]) => never;
+/**
+ * The exec that replaces this process with the child, or null when the wrapper
+ * has to stay and wait instead. Returning the function rather than a boolean
+ * keeps one check where two would otherwise drift: the platform gate and the
+ * policy are the same answer.
+ *
+ * `process.execve` is declared optional by @types/node, and is absent on node
+ * <22.15 (added there) and on Windows (its doc: "not available on Windows or
+ * IBM i"), so its presence covers both without a version check. `engines.node`
+ * still allows 20.x, 22.13–22.14 and 23.5–23.10 (added in 22.15 and 23.11, per
+ * the Node docs), so the spawn path below is not a transitional fallback — it
+ * stays.
+ *
+ * `isTTY` is `undefined` rather than `false` on a pipe, hence every `=== true`.
+ *
+ * The environment is bound here rather than left to execve's default: node
+ * 22.15.1 execs with an empty environment when the argument is omitted
+ * (measured — 22.23.2 and 24.x inherit process.env), and a tmux started without
+ * TERM dies with "open terminal failed: terminal does not support clear".
+ */
+export declare const handOffExec: (deps: {
+    execve: ProcessHandOff | undefined;
+    env: NodeJS.ProcessEnv;
+    kind: SpawnTarget["kind"];
+    stdinTTY: boolean | undefined;
+    stdoutTTY: boolean | undefined;
+}) => HandOff | null;
+/**
+ * Inside tmux the agent runs in the current pane, and the listener reports
+ * only `hwip-*` sessions — so unless this pane already sits in one, the phone
+ * never sees the agent. Say so, and name the two ways to a session it does
+ * see. `session` is this pane's tmux session, null when tmux would not say.
+ */
+export declare const inPaneNote: (subcommand: string, session: string | null) => string | undefined;
+/**
+ * What to say when tmux is missing — the install hint `hwip install` gives,
+ * not just "not found". Undefined when tmux is there. Exported for tests.
+ */
+export declare const tmuxMissingMessage: (command: string, plan: TmuxInstallPlan) => string | undefined;
+/** What `handleAgentSession` does to the machine, swappable in tests. */
+export interface AgentSessionDeps {
+    startListener?: () => Promise<void>;
+    launch?: (target: SpawnTarget, what: string) => Promise<number>;
+}
+export declare const handleAgentSession: (agent: RemoteAgent, extra?: string[], opts?: AgentLaunchOptions, deps?: AgentSessionDeps) => Promise<number>;
+/** What tmux holds under a `hwip sh` session name. */
+export type ShellSessionState = 'none' | 'marked' | 'unmarked';
+/** A tmux call, injectable for tests. */
+type RunTmux = (args: string[]) => {
+    status: number | null;
+    stdout: string;
+    stderr?: string;
+};
+/**
+ * How `hwip sh` proceeds, given what tmux holds under the name. `create` is
+ * the detached target, `attach` the attaching one (null for `--detach`).
+ *
+ * A missing session is created with `new -d` and `@hwip_shell` set to its own
+ * name in the same tmux call, so no sweep ever sees it unmarked, and `new -d`
+ * fails on a taken name: a session that appeared since the probe is never
+ * attached to and marked. The listener accepts the marker only when it names
+ * the session, so a stray `set -g @hwip_shell …` cannot mark anything. A
+ * session this command opened before is reattached (or, detached, left as it
+ * is — running `!hwip sh --detach` twice from the phone must not fail). Any
+ * other session under that name is refused: the marker would turn it into a
+ * typable shell.
+ */
+export declare const planShellSession: (create: SpawnTarget, attach: SpawnTarget | null, state: ShellSessionState) => {
+    kind: "create";
+    args: string[];
+    attach: SpawnTarget | null;
+} | {
+    kind: "attach";
+    target: SpawnTarget;
+} | {
+    kind: "running";
+} | {
+    kind: "refuse";
+    reason: string;
+};
+/**
+ * Read the marker off the session itself. `show-options` without `-A` shows
+ * only what is set on that session, never an inherited global value. A failed
+ * `has-session` reads as "none", which is safe: creation is `new -d`, and it
+ * fails on a name that does exist.
+ */
+export declare const readShellSessionState: (session: string, run?: RunTmux) => ShellSessionState;
+/**
+ * The two targets `hwip sh` works with. Inside tmux there is no attaching —
+ * `new -A` would nest and exit 1 after the session already exists — so the
+ * run is a detached one, as `--detach` is.
+ */
+export declare const shellTargets: (shell: string, opts: AgentLaunchOptions, inTmux?: boolean) => {
+    create: SpawnTarget;
+    attach: SpawnTarget | null;
+};
+/**
+ * `hwip sh [--label x] [--detach]` — open (or reattach) `hwip-<project>-sh`
+ * running the login shell, marked so the phone may type into it. The label
+ * always pins a tmux session, so this never runs in the current pane.
+ */
+export declare const handleShellSession: (opts: AgentLaunchOptions) => Promise<number>;
+export {};
+//# sourceMappingURL=wrapper.d.ts.map