@hwip/cli 0.0.1 → 0.1.0

package/dist/opencode-transcript.js

@@ -0,0 +1,390 @@
+"use strict";
+/**
+ * opencode's session store, read into the events the timeline draws.
+ *
+ * opencode keeps no transcript file. 2.x writes every session to SQLite
+ * (`opencode.db`, WAL), one `session_message` row per user message and per
+ * assistant step, and rewrites an assistant row in place while it streams. So
+ * this file is both halves the other agents split: a reader that asks the
+ * database what changed (`readOpencodeTranscript`, the `TranscriptReader`
+ * behind the opencode row) and a projector for what it hands back
+ * (`projectOpencodeEntries`).
+ *
+ * Shape measured 2026-10-10 against opencode 2.0.24 — the schema with
+ * `.schema`, the JSON with `json_each` key and type counts over 3,965 rows on
+ * this machine, and a scratch store written by sessions run for the purpose.
+ * No conversation text was opened.
+ *
+ *  - `session_message(id, session_id, type, seq, time_created, time_updated,
+ *    data)`, `seq` increasing per session. `type` is `user` · `assistant` ·
+ *    `system` · `synthetic` · `idle` · `compaction` · `*-switched`; only the
+ *    first two are drawn.
+ *  - user `data`: `{ text, time: { created }, files, agents, skills }`.
+ *  - assistant `data`: `{ model: { id, providerID }, content: [...], tokens:
+ *    { input, output, reasoning, cache: { read, write } }, time: { created,
+ *    completed?, streamed? }, finish, … }` — `time.completed` is set once the
+ *    step is over. `content` items are `{ type: "text", text }`,
+ *    `{ type: "reasoning", … }` and `{ type: "tool", id, name, state: { status,
+ *    input, content: [{ type: "text", text }], error }, time }`; a finished
+ *    call is `completed` or `error`.
+ *  - 1.x wrote `session` · `message` · `part` instead. 2.x leaves those alone
+ *    and this file does not read them.
+ *
+ * The lines the reader hands over are `TurnEvent`s already, one JSON object
+ * each, so the projector only checks them. The work of deciding what is new
+ * lives in `opencodeLinesOf`, which is pure and is where the tests point.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectOpencodeEntries = exports.readOpencodeTranscript = exports.opencodeLinesOf = exports.opencodeRowsSql = exports.OPENCODE_MIN_QUERY_MS = exports.OPENCODE_OPEN_WINDOW = exports.OPENCODE_ROWS_PER_READ = exports.OPENCODE_BACKFILL_ROWS = exports.opencodeSourcePath = exports.OPENCODE_SESSION_ID = exports.opencodeDbPath = void 0;
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const transcript_tail_js_1 = require("./transcript-tail.js");
+/** Where opencode 2.x keeps its store, by the rules opencode itself follows (`opencode debug paths db`, 2.0.24). */
+const opencodeDbPath = (env = process.env) => {
+    if (env.OPENCODE_DB && (0, path_1.isAbsolute)(env.OPENCODE_DB))
+        return env.OPENCODE_DB;
+    const data = env.XDG_DATA_HOME && (0, path_1.isAbsolute)(env.XDG_DATA_HOME) ? env.XDG_DATA_HOME : (0, path_1.join)((0, os_1.homedir)(), '.local', 'share');
+    return (0, path_1.join)(data, 'opencode', 'opencode.db');
+};
+exports.opencodeDbPath = opencodeDbPath;
+/**
+ * A session id as opencode mints them (`ses_` + base62, measured). The query
+ * below has nowhere to bind a parameter (`sqliteJson` runs the `sqlite3`
+ * binary), so an id goes into the SQL text only after it passes this.
+ */
+exports.OPENCODE_SESSION_ID = /^ses_[A-Za-z0-9]{1,64}$/;
+/**
+ * The transcript "path" an opencode pane resolves to: the store and the session
+ * in one string. A string because every consumer compares and logs paths, and
+ * because the session changing — a new one in the same pane — has to read as
+ * the path changing, which is what makes `turn-watch` start over on it.
+ */
+const opencodeSourcePath = (db, sessionId) => `${db}#${sessionId}`;
+exports.opencodeSourcePath = opencodeSourcePath;
+const parseSourcePath = (path) => {
+    const at = path.lastIndexOf('#');
+    if (at <= 0)
+        return null;
+    const sessionId = path.slice(at + 1);
+    const db = path.slice(0, at);
+    // The path also comes back from the recorder's state file, and goes to `sqlite3` as an argument:
+    // a relative one could start with `-` and read as an option.
+    return exports.OPENCODE_SESSION_ID.test(sessionId) && (0, path_1.isAbsolute)(db) ? { db, sessionId } : null;
+};
+/** A row the query could have returned — anything else is not drawn. */
+const isRow = (value) => {
+    if (!value || typeof value !== 'object')
+        return false;
+    const row = value;
+    return typeof row.id === 'string' && typeof row.type === 'string' && typeof row.seq === 'number' && Number.isSafeInteger(row.seq);
+};
+/** Rows read on the first look at a session — enough for the turn in flight and a screen above it. */
+exports.OPENCODE_BACKFILL_ROWS = 200;
+/** Rows read per look after that. */
+exports.OPENCODE_ROWS_PER_READ = 500;
+/** How far behind the newest row an unfinished one may hold the read position. */
+exports.OPENCODE_OPEN_WINDOW = 200;
+/** The fewest milliseconds between two queries for one session. */
+exports.OPENCODE_MIN_QUERY_MS = 1_000;
+/**
+ * Which `state.input` key reads as "what this call is about", first match
+ * wins. The keys are the ones 2.0.24's tools were seen to take (read, edit,
+ * write: `filePath`/`path`; glob, grep: `pattern`; webfetch: `url`; subagent,
+ * task: `description`). `command` is absent for the reason it is absent from
+ * every other projector — a command line is the argument most likely to carry
+ * a secret.
+ */
+const TARGET_KEYS = ['filePath', 'path', 'pattern', 'url', 'description'];
+/** Prose is cut in SQL a little above the event cap, so `clamp` still marks the cut. */
+const SQL_TEXT_CHARS = transcript_tail_js_1.MAX_EVENT_TEXT_CHARS + 1;
+/**
+ * The rows of one session from `from` on, or its last `OPENCODE_BACKFILL_ROWS`
+ * when `from` is null. Exported for the test that pins the id check.
+ */
+const opencodeRowsSql = (sessionId, from) => {
+    if (!exports.OPENCODE_SESSION_ID.test(sessionId))
+        throw new Error('not an opencode session id');
+    if (from !== null && !Number.isSafeInteger(from))
+        throw new Error('not a row position');
+    const item = (key) => `json_extract(c.value, '$.${key}')`;
+    const target = `substr(coalesce(${TARGET_KEYS.map((k) => item(`state.input.${k}`)).join(', ')}), 1, ${transcript_tail_js_1.MAX_EVENT_FIELD_CHARS + 1})`;
+    const lines = `(SELECT sum(length(json_extract(o.value, '$.text')) - length(replace(json_extract(o.value, '$.text'), char(10), '')) + 1)
+        FROM json_each(c.value, '$.state.content') o WHERE json_extract(o.value, '$.type') = 'text')`;
+    const items = `(SELECT json_group_array(json_object(
+        'type', ${item('type')}, 'id', ${item('id')}, 'name', ${item('name')},
+        'text', CASE WHEN ${item('type')} = 'text' THEN substr(${item('text')}, 1, ${SQL_TEXT_CHARS}) END,
+        'status', ${item('state.status')}, 'target', ${target}, 'lines', ${lines}, 'at', ${item('time.created')}))
+        FROM json_each(m.data, '$.content') c)`;
+    const select = `SELECT m.id AS id, m.seq AS seq, m.type AS type, m.time_created AS created,
+        json_extract(m.data, '$.time.completed') AS completed,
+        CASE WHEN m.type = 'user' THEN substr(json_extract(m.data, '$.text'), 1, ${SQL_TEXT_CHARS}) END AS text,
+        json_extract(m.data, '$.model.id') AS model,
+        json_extract(m.data, '$.tokens.output') AS out,
+        json_extract(m.data, '$.tokens.input') AS input,
+        json_extract(m.data, '$.tokens.cache.read') AS cacheRead,
+        json_extract(m.data, '$.tokens.cache.write') AS cacheWrite,
+        json_extract(m.data, '$.error.type') AS errorType,
+        substr(json_extract(m.data, '$.error.message'), 1, ${SQL_TEXT_CHARS}) AS errorText,
+        CASE WHEN m.type = 'assistant' THEN ${items} END AS items
+        FROM session_message m
+        WHERE m.session_id = '${sessionId}' AND m.type IN ('user', 'assistant')`;
+    return from === null
+        ? `SELECT * FROM (${select} ORDER BY m.seq DESC LIMIT ${exports.OPENCODE_BACKFILL_ROWS}) ORDER BY seq`
+        : `${select} AND m.seq >= ${from} ORDER BY m.seq LIMIT ${exports.OPENCODE_ROWS_PER_READ}`;
+};
+exports.opencodeRowsSql = opencodeRowsSql;
+const isoOf = (ms) => {
+    if (typeof ms !== 'number' || !Number.isFinite(ms))
+        return {};
+    const date = new Date(ms);
+    return Number.isNaN(date.getTime()) ? {} : { at: date.toISOString() };
+};
+/** The row's `content`, or null when the query handed back something that is not a list. */
+const itemsOf = (row) => {
+    if (row.items === undefined || row.items === null)
+        return [];
+    let parsed = row.items;
+    if (typeof parsed === 'string') {
+        try {
+            parsed = JSON.parse(parsed);
+        }
+        catch {
+            return null;
+        }
+    }
+    // Each item is checked field by field where it is drawn.
+    return Array.isArray(parsed) ? parsed : null;
+};
+const num = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : 0);
+/** A line the projector reads as "this kind of thing is not drawn". */
+const unknownLine = (what) => JSON.stringify({ unknown: what });
+/**
+ * What these rows add to what was already sent, and where the next read starts.
+ *
+ * Every piece of a row gets a key (`<seq>:<part><index>`), and a key sent once
+ * is never sent again. A user row is final when written. An assistant row is
+ * not: its text is sent once something follows it in the row or the row is
+ * closed, a tool call once it runs, its result once the call has one, and
+ * the step's token count and any error when the step is finished. A row is
+ * closed when it is finished, when a later assistant step exists (opencode
+ * starts one only after the last is over, so an unfinished one behind it died
+ * mid-stream), or when it falls out of the `OPENCODE_OPEN_WINDOW` rows behind
+ * the newest — closing is what sends a dead step's last words, which nothing
+ * would otherwise send. `from` stays on the oldest row still open, so the next
+ * read sees it again. `emitted` keeps only the keys at or after `from`;
+ * nothing before it is read again.
+ */
+const opencodeLinesOf = (rows, sent) => {
+    const seen = new Set(sent.emitted);
+    const lines = [];
+    const out = (key, event) => {
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        lines.push(JSON.stringify(event));
+    };
+    const once = (key, what) => {
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        lines.push(unknownLine(what));
+    };
+    let newest = sent.from - 1;
+    let lastStep = -1;
+    for (const row of rows) {
+        newest = Math.max(newest, row.seq);
+        if (row.type === 'assistant')
+            lastStep = Math.max(lastStep, row.seq);
+    }
+    let oldestOpen = null;
+    for (const row of rows) {
+        const stamp = isoOf(row.created);
+        if (row.type === 'user') {
+            // A prompt of attachments alone has no text, and still starts a turn.
+            const text = (typeof row.text === 'string' ? row.text : '').trim() || '(attachment)';
+            out(`${row.seq}:p`, { kind: 'prompt', text: (0, transcript_tail_js_1.clamp)(text, transcript_tail_js_1.MAX_EVENT_TEXT_CHARS), ...stamp });
+            continue;
+        }
+        if (row.type !== 'assistant')
+            continue;
+        const done = typeof row.completed === 'number';
+        const closed = done || row.seq < lastStep || row.seq < newest - exports.OPENCODE_OPEN_WINDOW;
+        if (!closed && oldestOpen === null)
+            oldestOpen = row.seq;
+        const items = itemsOf(row);
+        if (items === null)
+            once(`${row.seq}:x`, 'opencode content that is not a list');
+        let thinking = 0;
+        (items ?? []).forEach((item, i) => {
+            if (!item || typeof item !== 'object') {
+                once(`${row.seq}:x${i}`, 'opencode content item that is not an object');
+                return;
+            }
+            const at = item.at !== undefined && item.at !== null ? isoOf(item.at) : stamp;
+            if (item.type === 'reasoning') {
+                thinking += 1;
+                return;
+            }
+            if (item.type === 'text') {
+                const text = (item.text ?? '').trim();
+                const final = closed || i < (items ?? []).length - 1;
+                if (text && final)
+                    out(`${row.seq}:t${i}`, { kind: 'text', text: (0, transcript_tail_js_1.clamp)(text, transcript_tail_js_1.MAX_EVENT_TEXT_CHARS), ...at });
+                return;
+            }
+            if (item.type === 'tool') {
+                if (typeof item.id !== 'string' || typeof item.name !== 'string') {
+                    once(`${row.seq}:x${i}`, 'opencode tool call without an id or name');
+                    return;
+                }
+                // A call is first written while its input still streams in
+                // (measured on 2.0.24: a write seen then had no path yet), and a
+                // call sent once is never sent again — so wait until it runs.
+                const settled = item.status === 'running' || item.status === 'completed' || item.status === 'error';
+                if (!settled && !closed)
+                    return;
+                const line = (0, transcript_tail_js_1.oneLine)(typeof item.target === 'string' ? item.target : undefined);
+                const target = line ? (0, transcript_tail_js_1.clamp)(line) : undefined;
+                out(`${row.seq}:u${i}`, { kind: 'tool', id: (0, transcript_tail_js_1.clamp)(item.id), name: (0, transcript_tail_js_1.clamp)(item.name), ...(target ? { target } : {}), ...at });
+                if (item.status === 'completed' || item.status === 'error') {
+                    const count = num(item.lines);
+                    out(`${row.seq}:r${i}`, { kind: 'tool_result', id: (0, transcript_tail_js_1.clamp)(item.id), ok: item.status === 'completed', ...(count ? { lines: count } : {}), ...at });
+                }
+                return;
+            }
+            once(`${row.seq}:x${i}`, `opencode content type ${typeof item.type === 'string' ? item.type : '(none)'}`);
+        });
+        if (done && typeof row.errorType === 'string') {
+            // A failed step is finished like any other (measured: `time.completed`
+            // set beside `finish: "error"`), and its error is all it has to say.
+            const why = (0, transcript_tail_js_1.oneLine)(typeof row.errorText === 'string' ? row.errorText : undefined);
+            out(`${row.seq}:e`, { kind: 'text', text: (0, transcript_tail_js_1.clamp)(`opencode stopped: ${row.errorType}${why ? ` — ${why}` : ''}`, transcript_tail_js_1.MAX_EVENT_TEXT_CHARS), ...stamp });
+        }
+        if (done) {
+            out(`${row.seq}:m`, {
+                kind: 'msg',
+                mid: (0, transcript_tail_js_1.clamp)(row.id),
+                ...(typeof row.model === 'string' ? { model: (0, transcript_tail_js_1.clamp)(row.model) } : {}),
+                out: num(row.out),
+                // `input` excludes the cached prompt (measured: input 279 beside
+                // cache.read 140,145), so the context is the three together.
+                ctx: num(row.input) + num(row.cacheRead) + num(row.cacheWrite),
+                ...(thinking ? { thinking } : {}),
+                ...stamp,
+            });
+        }
+    }
+    let from = oldestOpen ?? newest + 1;
+    from = Math.max(from, newest - exports.OPENCODE_OPEN_WINDOW, sent.from);
+    // A full page of finished rows behind one open row would be read again
+    // forever; past the page is where the next read has to start.
+    if (rows.length >= exports.OPENCODE_ROWS_PER_READ && from <= sent.from)
+        from = newest + 1;
+    const emitted = [...seen].filter((key) => Number(key.slice(0, key.indexOf(':'))) >= from);
+    return { lines, from, emitted };
+};
+exports.opencodeLinesOf = opencodeLinesOf;
+const cursorOf = (prev, session) => {
+    const c = prev?.cursor;
+    if (!c || typeof c !== 'object')
+        return null;
+    const { session: s, from, emitted, stamp, queriedAt } = c;
+    if (s !== session || typeof from !== 'number' || !Number.isSafeInteger(from))
+        return null;
+    if (!Array.isArray(emitted) || typeof stamp !== 'string' || typeof queriedAt !== 'number')
+        return null;
+    return { session, from, emitted: emitted.filter((key) => typeof key === 'string'), stamp, queriedAt };
+};
+/**
+ * When a query last failed, per source path. A failure leaves no state to
+ * carry the time on (the reader returns null), and without it a store that
+ * cannot be read would be asked again on every 500 ms tick.
+ */
+const failedAt = new Map();
+const fileStamp = (db) => {
+    const parts = [];
+    for (const path of [db, `${db}-wal`]) {
+        try {
+            const s = (0, fs_1.statSync)(path);
+            parts.push(`${s.size}:${s.mtimeMs}`);
+        }
+        catch {
+            // No WAL file is a normal state (checkpointed, or opencode not running).
+            parts.push('-');
+        }
+    }
+    return parts[0] === '-' ? null : parts.join('|');
+};
+/**
+ * What changed in one opencode session since `prev`, or null when nothing did
+ * — the store's files have not moved, the last query was under
+ * `OPENCODE_MIN_QUERY_MS` ago, or the store cannot be read. The WAL moves on
+ * every write by every opencode session on this machine, so the time floor is
+ * what keeps a busy neighbour from turning a 500 ms poll into a `sqlite3`
+ * spawn per tick.
+ */
+const readOpencodeTranscript = (path, prev, deps) => {
+    const source = parseSourcePath(path);
+    if (!source)
+        return null;
+    const now = deps.now ?? Date.now;
+    const stamp = (deps.stamp ?? fileStamp)(source.db);
+    if (stamp === null)
+        return null;
+    const cursor = cursorOf(prev, source.sessionId);
+    if (cursor && cursor.stamp === stamp)
+        return null;
+    const last = Math.max(cursor?.queriedAt ?? -Infinity, failedAt.get(path) ?? -Infinity);
+    if (now() - last < exports.OPENCODE_MIN_QUERY_MS)
+        return null;
+    const rows = deps.query(source.db, (0, exports.opencodeRowsSql)(source.sessionId, cursor ? cursor.from : null));
+    if (rows === null) {
+        failedAt.set(path, now());
+        return null;
+    }
+    failedAt.delete(path);
+    const next = (0, exports.opencodeLinesOf)(rows.filter(isRow), cursor ?? { from: 0, emitted: [] });
+    const state = {
+        offset: next.from,
+        // `agent read` says there is more above when the read was a window:
+        // a backfill that came back full stands for a session longer than it.
+        size: !cursor && rows.length >= exports.OPENCODE_BACKFILL_ROWS ? transcript_tail_js_1.TRANSCRIPT_BACKFILL_BYTES + 1 : 0,
+        mtimeMs: 0,
+        ino: 0,
+        carry: '',
+        resyncing: false,
+        salvage: [],
+        cursor: { session: source.sessionId, from: next.from, emitted: next.emitted, stamp, queriedAt: now() },
+    };
+    return { lines: next.lines, state, bytesRead: 0, droppedLines: 0 };
+};
+exports.readOpencodeTranscript = readOpencodeTranscript;
+const EVENT_KINDS = new Set(['prompt', 'text', 'tool', 'tool_result', 'msg']);
+/**
+ * The reader's lines back into events. They were built as events, so this
+ * only refuses what is not one and names what the reader marked unknown.
+ */
+const projectOpencodeEntries = (lines, opts = {}) => {
+    const events = [];
+    for (const raw of lines) {
+        let entry;
+        try {
+            const parsed = JSON.parse(raw);
+            if (!parsed || typeof parsed !== 'object')
+                continue;
+            entry = parsed;
+        }
+        catch {
+            continue;
+        }
+        if (typeof entry.unknown === 'string') {
+            opts.onUnknown?.(entry.unknown);
+            continue;
+        }
+        if (typeof entry.kind === 'string' && EVENT_KINDS.has(entry.kind))
+            events.push(entry);
+    }
+    return (0, transcript_tail_js_1.sliceSinceLastPrompt)(events, opts);
+};
+exports.projectOpencodeEntries = projectOpencodeEntries;

package/dist/optional-features.d.ts

@@ -0,0 +1,6 @@
+import type { HwipConfig } from './config.js';
+export declare const optionalFeatures: (args: Record<string, string | boolean>, config: Pick<HwipConfig, "turnHistory" | "keepAwake">) => {
+    turnHistory: boolean;
+    keepAwake: boolean;
+};
+//# sourceMappingURL=optional-features.d.ts.map

package/dist/optional-features.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.optionalFeatures = void 0;
+const args_js_1 = require("./args.js");
+/**
+ * The listener's opt-out features: on unless a flag or the config says no. Only an absent value or
+ * `true` keeps one on in the config: `"turnHistory": "false"`, `0` or `null` is someone's attempt to
+ * turn it off, and reading it as "not set" uploaded the conversations anyway. `loadConfig` reads a
+ * config.json it cannot use as every option off (`unreadableConfigDefaults`), so what this
+ * returns is the privacy-safe set then, with the flags unable to turn anything back on. A flag is
+ * read by `flagOn`: `--no-turn-history=true` and `=1` are as much a no as the bare form, and a
+ * value that is neither yes nor no throws `FlagValueError`.
+ */
+const configKeepsOn = (value) => value === undefined || value === true;
+const optionalFeatures = (args, config) => ({
+    turnHistory: !(0, args_js_1.flagOn)(args, 'no-turn-history') && configKeepsOn(config.turnHistory),
+    keepAwake: !(0, args_js_1.flagOn)(args, 'no-keep-awake') && configKeepsOn(config.keepAwake),
+});
+exports.optionalFeatures = optionalFeatures;

package/dist/pane-fit.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Fit a detached tmux window to the phone that is watching it.
+ *
+ * A pane is as wide as the terminal that last drew it, usually a desktop's
+ * 120-odd columns. The phone mirror shows about 45, so every full-width row a
+ * prompt or TUI draws (a rule, a right-aligned clock, a status line) folds into
+ * two. Nobody else sees a DETACHED window, so while a phone watches one it is
+ * resized to the phone's width and the program redraws to fit; when the phone
+ * leaves, the old width comes back.
+ *
+ * An attached window is left alone: shrinking it would shrink the desktop
+ * terminal of whoever is attached. A window split into panes is left alone
+ * too, since the window width is not any one pane's width. And when a client
+ * attaches while the phone is watching, the next check hands the window back
+ * to tmux, which sizes it to that client.
+ *
+ * A fitted window carries its old width in `@hwip_fit_width`. A listener that
+ * died without releasing (a crash, a SIGKILL) leaves that mark behind, and
+ * the next one to start gives those windows back ({@link releaseStaleFits}).
+ */
+/** Runs one tmux command (socket-aware) and returns what it printed. */
+export type TmuxRun = (args: string[]) => {
+    status: number | null;
+    stdout: string;
+};
+export declare const PANE_FIT_MIN_COLS = 20;
+export declare const PANE_FIT_MAX_COLS = 400;
+/** A viewer's column count, or null when it did not send a usable one. */
+export declare const clampViewerCols: (cols: unknown) => number | null;
+/**
+ * Hand back every window a previous listener fitted and never released:
+ * restore its width when detached, then drop the manual size and the mark.
+ */
+export declare const releaseStaleFits: (run: TmuxRun) => number;
+export declare const createPaneFitter: (run: TmuxRun) => {
+    fit: (session: string, target: string, cols: unknown) => void;
+    release: (session: string) => void;
+    fitted: (session: string) => boolean;
+};
+//# sourceMappingURL=pane-fit.d.ts.map

package/dist/pane-fit.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * Fit a detached tmux window to the phone that is watching it.
+ *
+ * A pane is as wide as the terminal that last drew it, usually a desktop's
+ * 120-odd columns. The phone mirror shows about 45, so every full-width row a
+ * prompt or TUI draws (a rule, a right-aligned clock, a status line) folds into
+ * two. Nobody else sees a DETACHED window, so while a phone watches one it is
+ * resized to the phone's width and the program redraws to fit; when the phone
+ * leaves, the old width comes back.
+ *
+ * An attached window is left alone: shrinking it would shrink the desktop
+ * terminal of whoever is attached. A window split into panes is left alone
+ * too, since the window width is not any one pane's width. And when a client
+ * attaches while the phone is watching, the next check hands the window back
+ * to tmux, which sizes it to that client.
+ *
+ * A fitted window carries its old width in `@hwip_fit_width`. A listener that
+ * died without releasing (a crash, a SIGKILL) leaves that mark behind, and
+ * the next one to start gives those windows back ({@link releaseStaleFits}).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPaneFitter = exports.releaseStaleFits = exports.clampViewerCols = exports.PANE_FIT_MAX_COLS = exports.PANE_FIT_MIN_COLS = void 0;
+exports.PANE_FIT_MIN_COLS = 20;
+exports.PANE_FIT_MAX_COLS = 400;
+/** A viewer's column count, or null when it did not send a usable one. */
+const clampViewerCols = (cols) => {
+    if (typeof cols !== 'number' || !Number.isFinite(cols))
+        return null;
+    return Math.min(exports.PANE_FIT_MAX_COLS, Math.max(exports.PANE_FIT_MIN_COLS, Math.floor(cols)));
+};
+exports.clampViewerCols = clampViewerCols;
+const SEP = '\u241f';
+const FIT_MARK = '@hwip_fit_width';
+/**
+ * Hand back every window a previous listener fitted and never released:
+ * restore its width when detached, then drop the manual size and the mark.
+ */
+const releaseStaleFits = (run) => {
+    const r = run(['list-windows', '-a', '-F', `#{window_id}${SEP}#{${FIT_MARK}}${SEP}#{session_attached}`]);
+    if (r.status !== 0)
+        return 0;
+    let released = 0;
+    for (const line of r.stdout.split('\n')) {
+        const [id, mark, attached] = line.split(SEP);
+        const width = Number(mark);
+        if (!id || !mark || !Number.isFinite(width))
+            continue;
+        if (attached === '0')
+            run(['resize-window', '-t', id, '-x', String(width)]);
+        run(['set-option', '-w', '-u', '-t', id, 'window-size']);
+        run(['set-option', '-w', '-u', '-t', id, FIT_MARK]);
+        released++;
+    }
+    return released;
+};
+exports.releaseStaleFits = releaseStaleFits;
+const readWindow = (run, target) => {
+    const r = run(['display-message', '-p', '-t', target,
+        `#{session_attached}${SEP}#{window_panes}${SEP}#{window_width}`]);
+    if (r.status !== 0)
+        return null;
+    const [attached, panes, width] = r.stdout.trim().split(SEP).map(Number);
+    if (![attached, panes, width].every(Number.isFinite))
+        return null;
+    return { attached, panes, width };
+};
+const createPaneFitter = (run) => {
+    const fits = new Map();
+    /**
+     * Give the window back: restore its width if nobody is attached, then drop
+     * the manual size `resize-window` set, so the next client to attach sizes
+     * it again. With a client attached, dropping the option alone resizes it to
+     * that client.
+     */
+    const release = (session) => {
+        const fit = fits.get(session);
+        if (!fit)
+            return;
+        fits.delete(session);
+        const win = readWindow(run, fit.target);
+        if (win && win.attached === 0)
+            run(['resize-window', '-t', fit.target, '-x', String(fit.width)]);
+        run(['set-option', '-w', '-u', '-t', fit.target, 'window-size']);
+        run(['set-option', '-w', '-u', '-t', fit.target, FIT_MARK]);
+    };
+    /**
+     * Size `session`'s window to `cols` if it is detached and unsplit. Safe to
+     * call on every renew: an unchanged width costs one display-message, and a
+     * window that gained a client since is released.
+     */
+    const fit = (session, target, cols) => {
+        const want = (0, exports.clampViewerCols)(cols);
+        if (want === null)
+            return;
+        const win = readWindow(run, target);
+        if (!win)
+            return;
+        const held = fits.get(session);
+        if (win.attached > 0 || win.panes !== 1) {
+            if (held)
+                release(session);
+            return;
+        }
+        if (held && held.cols === want && win.width === want)
+            return;
+        const width = held?.width ?? win.width;
+        // Mark first: a crash between the two must still be recoverable.
+        run(['set-option', '-w', '-t', target, FIT_MARK, String(width)]);
+        if (run(['resize-window', '-t', target, '-x', String(want)]).status !== 0) {
+            if (!held)
+                run(['set-option', '-w', '-u', '-t', target, FIT_MARK]);
+            return;
+        }
+        fits.set(session, { target, width, cols: want });
+    };
+    return { fit, release, fitted: (session) => fits.has(session) };
+};
+exports.createPaneFitter = createPaneFitter;

package/dist/peer-key.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Which key to believe for a device that signs something with its own key.
+ *
+ * An envelope that opens only shows its sender held *a* key (push v1 carries
+ * the sender's public key unsigned), so the reader must say whose key it
+ * expects. This answers that for one device id: the key the account's device
+ * list registers for it. The device is pinned on the way (`observeDevices`) — a first
+ * sight pins it, a key that changed replaces the pin with one warning and a record
+ * (`key-changes.ts`). The pin is a record for a person (`hwip trust`) and for the
+ * listener; it does not decide here, the list does.
+ */
+export type PeerKeyRefusal = 
+/** Not a device id, or not in the account's device list. */
+'unlisted'
+/** The device list could not be fetched. */
+ | 'devices_unavailable';
+export type PeerKey = {
+    key: string;
+} | {
+    refused: PeerKeyRefusal;
+};
+export interface PeerKeyDeps {
+    /** The key the account's device list registers for `deviceId`: null when none is listed, a rejection when the list cannot be had. */
+    registeredKey: (deviceId: string) => Promise<string | null>;
+    /** The listener's state file (`~/.hwip/trusted-devices.json`). */
+    trustPath: string;
+    /** This computer's own id: it never pins itself. */
+    selfId?: string;
+    /** One line for a person, as `observeDevices` words it. */
+    warn?: (line: string) => void;
+}
+export declare const peerKeyOf: (deviceId: string, deps: PeerKeyDeps) => Promise<PeerKey>;
+//# sourceMappingURL=peer-key.d.ts.map

package/dist/peer-key.js

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * Which key to believe for a device that signs something with its own key.
+ *
+ * An envelope that opens only shows its sender held *a* key (push v1 carries
+ * the sender's public key unsigned), so the reader must say whose key it
+ * expects. This answers that for one device id: the key the account's device
+ * list registers for it. The device is pinned on the way (`observeDevices`) — a first
+ * sight pins it, a key that changed replaces the pin with one warning and a record
+ * (`key-changes.ts`). The pin is a record for a person (`hwip trust`) and for the
+ * listener; it does not decide here, the list does.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.peerKeyOf = void 0;
+const crypto_js_1 = require("./crypto.js");
+const subscriber_trust_js_1 = require("./subscriber-trust.js");
+const trust_pins_js_1 = require("./trust-pins.js");
+const peerKeyOf = async (deviceId, deps) => {
+    if (!subscriber_trust_js_1.DEVICE_ID.test(deviceId))
+        return { refused: 'unlisted' };
+    let registered;
+    try {
+        registered = await deps.registeredKey(deviceId);
+    }
+    catch {
+        return { refused: 'devices_unavailable' };
+    }
+    // A listed key that is no device key in the one spelling is as good as none.
+    if (!registered || !(0, crypto_js_1.samePublicKey)(registered, registered))
+        return { refused: 'unlisted' };
+    (0, trust_pins_js_1.observeDevices)(deps.trustPath, [{ deviceId, publicKey: registered }], { selfId: deps.selfId, warn: deps.warn ?? (() => undefined) });
+    return { key: registered };
+};
+exports.peerKeyOf = peerKeyOf;