@hwip/cli 0.0.1 → 0.1.1

package/dist/session-registry.d.ts

@@ -0,0 +1,143 @@
+/**
+ * What a session WAS, kept so it can be started again.
+ *
+ * tmux is the only record of a live session, and it forgets one the moment it
+ * ends — which is exactly when the phone wants it back. So the listener writes
+ * down what it saw while the session was alive: where it ran and which agent it
+ * ran, keyed by the tmux name the phone already addresses it by **and** the
+ * agent that ran under it — tmux hands the same name out again, and one row per
+ * name meant the next occupant erased the last one's record (`runKey`).
+ *
+ * This file is the whitelist that makes remote resume safe. A resume request
+ * carries a session NAME and nothing else; the directory and the binary come
+ * from here, from what this machine observed itself. Nothing a phone (or a
+ * relay posing as one) sends can point the daemon at another directory or
+ * another program.
+ */
+export interface KnownSession {
+    /** tmux session name — the key the phone addresses. */
+    name: string;
+    /** Pane cwd while it was alive. Where a resume starts the agent again. */
+    cwd: string;
+    /** RemoteAgent `kind` (claude/codex/…), resolved to a binary at resume time. */
+    agentKind: string;
+    project?: string;
+    label?: string;
+    /** Last time this machine saw the session running. */
+    lastSeenAt: string;
+}
+/**
+ * Ceiling on remembered sessions. tmux names come from a small reused pool
+ * (`hwip-<project>`, `-2`, …), so this holds far more distinct projects than it
+ * looks; the cap only stops the file from growing without bound on a machine
+ * that has run agents for years.
+ */
+export declare const MAX_KNOWN_SESSIONS = 100;
+/** Forgotten after this long unseen — a directory from months ago is more
+ *  likely to have moved than to be what the user meant. */
+export declare const KNOWN_SESSION_TTL_MS: number;
+/**
+ * What makes two sightings the same remembered run: the tmux name AND the
+ * agent that was running under it.
+ *
+ * Keyed by name alone, a `hwip cc` in a project erased whatever pi had done in
+ * the same slot — the ended run left no row to resume and no row to read, and
+ * the past list silently answered with the newest occupant instead. tmux hands
+ * a name back out; the record of what ran under it is not the name's to lose.
+ *
+ * NUL rather than a printable separator: a project directory can be called
+ * almost anything, and a name holding the separator must not be able to forge
+ * another run's key.
+ */
+export declare const runKey: (name: string, agentKind: string) => string;
+/** Sessions this machine has seen, newest first, expired ones dropped. */
+export declare const knownSessions: (now?: number) => KnownSession[];
+/** One remembered session, or null when this machine never saw that name.
+ *  The newest run under that name — which is the one a bare resume means. */
+export declare const recallSession: (name: string, now?: number) => KnownSession | null;
+/**
+ * One specific run: the newest under this name that ran THIS agent.
+ *
+ * A tmux name is a slot several agents pass through, so "resume hwip-web" is
+ * ambiguous the moment the slot has held both pi and claude. The phone knows
+ * which row was tapped and says so; this is how that answer is honoured.
+ * Null when this machine never saw that agent under that name — the caller
+ * decides whether to fall back to the newest run or refuse.
+ */
+export declare const recallRun: (name: string, agentKind: string, now?: number) => KnownSession | null;
+/**
+ * Make this process a reader of the registry: `rememberSessions` writes nothing from here on. For the
+ * CLI commands that look at the sweep (`hwip agent list|read`) — the file is the listener's resume
+ * whitelist, written in place (not renamed over), so a second writer can leave the listener's reader a
+ * half-written file. Never called in the listener's own process, which stays the one writer.
+ */
+export declare const keepRegistryUntouched: () => void;
+/**
+ * Write down the sessions running right now, replacing what was known about
+ * each. Called from the inventory sweep, so the record follows a session that
+ * moves directory or changes agent rather than pinning its first sighting.
+ *
+ * A session with no readable cwd is skipped rather than remembered without
+ * one: an entry that cannot say where to start the agent is not a resume
+ * target, only a row that would fail when tapped.
+ */
+export declare const rememberSessions: (live: Array<{
+    name: string;
+    cwd: string | null;
+    agentKind: string;
+    project?: string | null;
+    label?: string | null;
+}>, now?: number) => void;
+/**
+ * Forget one session, by name. Returns false when this machine never knew it.
+ *
+ * This is what deleting a past session means on the machine that ran it: the
+ * entry leaves the file, so the phone stops being offered the session AND —
+ * since this file is the resume whitelist — stops being able to start it.
+ * That is the intended pair, not a side effect.
+ *
+ * It stays forgotten: `rememberSessions` only writes down sessions that are
+ * running, so nothing re-adds an entry for a session that has ended. Running
+ * that name again is what brings it back, which is also the only way back.
+ */
+export type ForgetOutcome = 
+/** This machine never had a record under that name. */
+'unknown'
+/** Registry entry and chat scrollback both gone. */
+ | 'forgotten'
+/** Registry entry gone, but the scrollback file would not delete. */
+ | 'scrollback_kept';
+export declare const forgetSession: (name: string, agentKind?: string) => ForgetOutcome;
+/**
+ * What the caller was able to find out about a name. `unknown` is not a
+ * synonym for ended: it is the terminal failing to answer at all — no tmux to
+ * run, or no server behind the socket it resolved — and a sweep that deletes on
+ * `ended` must not delete on that. Deciding this is the caller's job; this
+ * module owns the file, not the terminal.
+ */
+export type SessionLiveness = 'running' | 'ended' | 'unknown';
+/** What one sweep did. `scrollbackKept` is a subset of `forgotten`: the row is
+ *  gone either way, and these are the ones whose chat history stayed behind. */
+export type EndedSweep = {
+    forgotten: string[];
+    scrollbackKept: string[];
+    kept: string[];
+    unreachable: string[];
+};
+/**
+ * Forget every remembered name that no longer runs, and report each side.
+ *
+ * The unit is the NAME, not the run: `forgetSession(name)` takes every run of
+ * the name, and a name tmux still holds is one the next inventory sweep writes
+ * straight back — so a name with a live run is left alone, its ended runs
+ * included. Each name is judged, deleted and reported once, however many runs
+ * sit under it.
+ */
+export declare const forgetEnded: (liveness: (name: string) => SessionLiveness, now?: number) => EndedSweep;
+/** Whether the registry knows this name — the resume whitelist check. */
+export declare const isKnownSession: (name: string, now?: number) => boolean;
+/** Test seam: the file this module reads and writes. */
+export declare const knownSessionsPath: () => string;
+/** True when the recorded directory still exists to start an agent in. */
+export declare const sessionDirectoryExists: (entry: KnownSession) => boolean;
+//# sourceMappingURL=session-registry.d.ts.map

package/dist/session-registry.js

@@ -0,0 +1,216 @@
+"use strict";
+/**
+ * What a session WAS, kept so it can be started again.
+ *
+ * tmux is the only record of a live session, and it forgets one the moment it
+ * ends — which is exactly when the phone wants it back. So the listener writes
+ * down what it saw while the session was alive: where it ran and which agent it
+ * ran, keyed by the tmux name the phone already addresses it by **and** the
+ * agent that ran under it — tmux hands the same name out again, and one row per
+ * name meant the next occupant erased the last one's record (`runKey`).
+ *
+ * This file is the whitelist that makes remote resume safe. A resume request
+ * carries a session NAME and nothing else; the directory and the binary come
+ * from here, from what this machine observed itself. Nothing a phone (or a
+ * relay posing as one) sends can point the daemon at another directory or
+ * another program.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sessionDirectoryExists = exports.knownSessionsPath = exports.isKnownSession = exports.forgetEnded = exports.forgetSession = exports.rememberSessions = exports.keepRegistryUntouched = exports.recallRun = exports.recallSession = exports.knownSessions = exports.runKey = exports.KNOWN_SESSION_TTL_MS = exports.MAX_KNOWN_SESSIONS = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const turn_ring_js_1 = require("./turn-ring.js");
+const gate_js_1 = require("./gate.js");
+const private_files_js_1 = require("./private-files.js");
+/**
+ * Ceiling on remembered sessions. tmux names come from a small reused pool
+ * (`hwip-<project>`, `-2`, …), so this holds far more distinct projects than it
+ * looks; the cap only stops the file from growing without bound on a machine
+ * that has run agents for years.
+ */
+exports.MAX_KNOWN_SESSIONS = 100;
+/** Forgotten after this long unseen — a directory from months ago is more
+ *  likely to have moved than to be what the user meant. */
+exports.KNOWN_SESSION_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+const registryPath = () => (0, path_1.join)((0, gate_js_1.stateDir)(), 'known-sessions.json');
+const readAll = () => {
+    try {
+        const raw = (0, fs_1.readFileSync)(registryPath(), 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        // Written by this process, but a half-written or hand-edited file must
+        // not take the listener down — keep the rows that still make sense.
+        return parsed.filter((e) => !!e &&
+            typeof e === 'object' &&
+            typeof e.name === 'string' &&
+            typeof e.cwd === 'string' &&
+            typeof e.agentKind === 'string' &&
+            typeof e.lastSeenAt === 'string');
+    }
+    catch {
+        return [];
+    }
+};
+const writeAll = (entries) => {
+    const path = registryPath();
+    try {
+        (0, private_files_js_1.mkdirHandedBack)((0, path_1.dirname)(path), 0o700);
+        // 0600: it names the user's project directories, which is not something
+        // every account on the machine needs to read.
+        (0, fs_1.writeFileSync)(path, JSON.stringify(entries, null, 2), { mode: 0o600 });
+        (0, private_files_js_1.handBackToSudoUser)(path);
+    }
+    catch {
+        // A registry that cannot be written costs the resume affordance, not
+        // the daemon — every other path keeps working.
+    }
+};
+/**
+ * What makes two sightings the same remembered run: the tmux name AND the
+ * agent that was running under it.
+ *
+ * Keyed by name alone, a `hwip cc` in a project erased whatever pi had done in
+ * the same slot — the ended run left no row to resume and no row to read, and
+ * the past list silently answered with the newest occupant instead. tmux hands
+ * a name back out; the record of what ran under it is not the name's to lose.
+ *
+ * NUL rather than a printable separator: a project directory can be called
+ * almost anything, and a name holding the separator must not be able to forge
+ * another run's key.
+ */
+const runKey = (name, agentKind) => `${name}\u0000${agentKind}`;
+exports.runKey = runKey;
+/** Sessions this machine has seen, newest first, expired ones dropped. */
+const knownSessions = (now = Date.now()) => readAll()
+    .filter((e) => now - Date.parse(e.lastSeenAt) < exports.KNOWN_SESSION_TTL_MS)
+    .sort((a, b) => b.lastSeenAt.localeCompare(a.lastSeenAt));
+exports.knownSessions = knownSessions;
+/** One remembered session, or null when this machine never saw that name.
+ *  The newest run under that name — which is the one a bare resume means. */
+const recallSession = (name, now = Date.now()) => (0, exports.knownSessions)(now).find((e) => e.name === name) ?? null;
+exports.recallSession = recallSession;
+/**
+ * One specific run: the newest under this name that ran THIS agent.
+ *
+ * A tmux name is a slot several agents pass through, so "resume hwip-web" is
+ * ambiguous the moment the slot has held both pi and claude. The phone knows
+ * which row was tapped and says so; this is how that answer is honoured.
+ * Null when this machine never saw that agent under that name — the caller
+ * decides whether to fall back to the newest run or refuse.
+ */
+const recallRun = (name, agentKind, now = Date.now()) => (0, exports.knownSessions)(now).find((e) => e.name === name && e.agentKind === agentKind) ?? null;
+exports.recallRun = recallRun;
+let readOnly = false;
+/**
+ * Make this process a reader of the registry: `rememberSessions` writes nothing from here on. For the
+ * CLI commands that look at the sweep (`hwip agent list|read`) — the file is the listener's resume
+ * whitelist, written in place (not renamed over), so a second writer can leave the listener's reader a
+ * half-written file. Never called in the listener's own process, which stays the one writer.
+ */
+const keepRegistryUntouched = () => {
+    readOnly = true;
+};
+exports.keepRegistryUntouched = keepRegistryUntouched;
+/**
+ * Write down the sessions running right now, replacing what was known about
+ * each. Called from the inventory sweep, so the record follows a session that
+ * moves directory or changes agent rather than pinning its first sighting.
+ *
+ * A session with no readable cwd is skipped rather than remembered without
+ * one: an entry that cannot say where to start the agent is not a resume
+ * target, only a row that would fail when tapped.
+ */
+const rememberSessions = (live, now = Date.now()) => {
+    if (readOnly)
+        return;
+    const usable = live.filter((s) => !!s.name && !!s.cwd);
+    if (usable.length === 0)
+        return;
+    const seenAt = new Date(now).toISOString();
+    const byRun = new Map((0, exports.knownSessions)(now).map((e) => [(0, exports.runKey)(e.name, e.agentKind), e]));
+    for (const s of usable) {
+        byRun.set((0, exports.runKey)(s.name, s.agentKind), {
+            name: s.name,
+            cwd: s.cwd,
+            agentKind: s.agentKind,
+            ...(s.project ? { project: s.project } : {}),
+            ...(s.label ? { label: s.label } : {}),
+            lastSeenAt: seenAt,
+        });
+    }
+    const entries = [...byRun.values()]
+        .sort((a, b) => b.lastSeenAt.localeCompare(a.lastSeenAt))
+        .slice(0, exports.MAX_KNOWN_SESSIONS);
+    writeAll(entries);
+};
+exports.rememberSessions = rememberSessions;
+const forgetSession = (name, agentKind) => {
+    const entries = readAll();
+    // With a kind, only that run goes — the phone deletes the row it is looking
+    // at, and a name that held both pi and claude shows two rows. Without one
+    // (an older phone, which sends no kind), the name goes entirely: that is
+    // what the request meant when a name could only mean one run.
+    const kept = entries.filter((e) => e.name !== name || (agentKind ? e.agentKind !== agentKind : false));
+    if (kept.length === entries.length)
+        return 'unknown';
+    // The chat's scrollback for that session goes with it. Forgetting a session
+    // everywhere except the one file that holds a day of its prompts and tool
+    // targets is not forgetting it — and a failure to delete that file has to
+    // reach the person who asked, not stay in a swallowed catch.
+    //
+    // Except while another run still answers to the name: the scrollback is per
+    // NAME, so deleting the pi row would take the claude row's history with it.
+    // The record is gone either way; the file waits for the last run to go.
+    const nameStillHeld = kept.some((e) => e.name === name);
+    writeAll(kept);
+    if (nameStillHeld)
+        return 'forgotten';
+    return (0, turn_ring_js_1.removeTurnRing)(name) ? 'forgotten' : 'scrollback_kept';
+};
+exports.forgetSession = forgetSession;
+/**
+ * Forget every remembered name that no longer runs, and report each side.
+ *
+ * The unit is the NAME, not the run: `forgetSession(name)` takes every run of
+ * the name, and a name tmux still holds is one the next inventory sweep writes
+ * straight back — so a name with a live run is left alone, its ended runs
+ * included. Each name is judged, deleted and reported once, however many runs
+ * sit under it.
+ */
+const forgetEnded = (liveness, now = Date.now()) => {
+    const names = [...new Set((0, exports.knownSessions)(now).map((e) => e.name))];
+    const sweep = { forgotten: [], scrollbackKept: [], kept: [], unreachable: [] };
+    for (const name of names) {
+        const state = liveness(name);
+        if (state === 'running')
+            sweep.kept.push(name);
+        else if (state === 'unknown')
+            sweep.unreachable.push(name);
+        else
+            sweep.forgotten.push(name);
+    }
+    if (sweep.forgotten.length === 0)
+        return sweep;
+    // One read and one write for the whole sweep. Calling `forgetSession` per
+    // name would rewrite the file once per name — N chances for the daemon's
+    // inventory sweep to write in between and put a deleted row back.
+    const doomed = new Set(sweep.forgotten);
+    writeAll(readAll().filter((e) => !doomed.has(e.name)));
+    // Every run of these names has gone, so — unlike `forgetSession`, which
+    // spares a ring another run still answers to — each ring goes with them.
+    for (const name of sweep.forgotten) {
+        if (!(0, turn_ring_js_1.removeTurnRing)(name))
+            sweep.scrollbackKept.push(name);
+    }
+    return sweep;
+};
+exports.forgetEnded = forgetEnded;
+/** Whether the registry knows this name — the resume whitelist check. */
+const isKnownSession = (name, now = Date.now()) => (0, exports.recallSession)(name, now) !== null;
+exports.isKnownSession = isKnownSession;
+/** Test seam: the file this module reads and writes. */
+exports.knownSessionsPath = registryPath;
+/** True when the recorded directory still exists to start an agent in. */
+const sessionDirectoryExists = (entry) => (0, fs_1.existsSync)(entry.cwd);
+exports.sessionDirectoryExists = sessionDirectoryExists;

package/dist/sessions-report.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The `listener.sessions` report, cut to fit the one message size this socket
+ * can carry.
+ *
+ * API Gateway closes a WebSocket whose frame is over 32 KB (close code 1009;
+ * "WebSocket frame size", a quota that cannot be raised). `ws` sends a message
+ * as one frame, and the report grows by about 290 bytes a session, so a machine
+ * with around a hundred sessions would see its connection dropped on every
+ * report and the inventory would never arrive.
+ *
+ * A report that fits goes out exactly as it always did. A larger one goes as
+ * (the server's contract, `server/SERVER-API.md`):
+ *
+ *   - parts of at most `SESSIONS_REPORT_MAX_BYTES`, each `listener.sessions`
+ *     with `partial: true` and some of the sessions — the server upserts what
+ *     it is given, by name, and acks each part. The first part also carries
+ *     `knownSessions` (once is enough);
+ *   - then `listener.sessions.names` with every session name in the report, so
+ *     the server can drop the sessions that are no longer there — what a
+ *     whole-list report does by replacing the list.
+ *
+ * The next message waits for the previous part's ack (`sendSessionsReport`):
+ * the server merges overlapping parts safely, but overlapping ones can fire a
+ * blocked-session push twice. Parts also say their place (`part` of `parts`,
+ * one `reportId`); the server ignores those, they are for the log.
+ *
+ * A server that predates parts reads each part as a whole report (the last
+ * part would win) and does not know `listener.sessions.names`: the inventory is
+ * wrong there, but the connection stays up, which one oversized message did not.
+ */
+/** Under API Gateway's 32 KB frame, with room for the envelope and a long session or two. */
+export declare const SESSIONS_REPORT_MAX_BYTES: number;
+export interface SessionsReportPlan {
+    /** The JSON messages to send, in order: one when the report fits, else the parts and then `names`. */
+    messages: string[];
+    /** Sessions in the report. */
+    sessionCount: number;
+    /** Bytes of the report sent as one message — what it would have been uncut. */
+    wholeBytes: number;
+    /** Sessions whose own JSON is bigger than a part can hold: sent alone, over the limit. */
+    oversized: string[];
+    /** The `names` message is bigger than a message can hold (about 900 sessions): sent anyway. */
+    namesOversized: boolean;
+    /** Identifies a report in parts; the server echoes it (and `part`) in each ack. Absent for one message. */
+    reportId?: string;
+}
+export declare const planSessionsReport: (sessions: readonly {
+    name: string;
+}[], knownSessions: readonly unknown[], maxBytes?: number, reportId?: () => string) => SessionsReportPlan;
+/** How long a part waits for its ack before the report is given up (and tried again on the next poll). */
+export declare const SESSIONS_ACK_TIMEOUT_MS = 10000;
+/**
+ * Send a plan's messages in order. With parts, every message but the last (`names`) waits for its
+ * ack before the next goes — `awaitAck(part)` is asked for before the send, so a quick answer is not
+ * missed, and `names` (which removes whatever it does not list) only goes once every part landed.
+ * False when an ack did not come: the rest is not sent, and the caller treats the report as unsent.
+ */
+export declare const sendSessionsReport: (messages: readonly string[], send: (message: string) => void, awaitAck: (part: number) => Promise<boolean>) => Promise<boolean>;
+//# sourceMappingURL=sessions-report.d.ts.map

package/dist/sessions-report.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * The `listener.sessions` report, cut to fit the one message size this socket
+ * can carry.
+ *
+ * API Gateway closes a WebSocket whose frame is over 32 KB (close code 1009;
+ * "WebSocket frame size", a quota that cannot be raised). `ws` sends a message
+ * as one frame, and the report grows by about 290 bytes a session, so a machine
+ * with around a hundred sessions would see its connection dropped on every
+ * report and the inventory would never arrive.
+ *
+ * A report that fits goes out exactly as it always did. A larger one goes as
+ * (the server's contract, `server/SERVER-API.md`):
+ *
+ *   - parts of at most `SESSIONS_REPORT_MAX_BYTES`, each `listener.sessions`
+ *     with `partial: true` and some of the sessions — the server upserts what
+ *     it is given, by name, and acks each part. The first part also carries
+ *     `knownSessions` (once is enough);
+ *   - then `listener.sessions.names` with every session name in the report, so
+ *     the server can drop the sessions that are no longer there — what a
+ *     whole-list report does by replacing the list.
+ *
+ * The next message waits for the previous part's ack (`sendSessionsReport`):
+ * the server merges overlapping parts safely, but overlapping ones can fire a
+ * blocked-session push twice. Parts also say their place (`part` of `parts`,
+ * one `reportId`); the server ignores those, they are for the log.
+ *
+ * A server that predates parts reads each part as a whole report (the last
+ * part would win) and does not know `listener.sessions.names`: the inventory is
+ * wrong there, but the connection stays up, which one oversized message did not.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sendSessionsReport = exports.SESSIONS_ACK_TIMEOUT_MS = exports.planSessionsReport = exports.SESSIONS_REPORT_MAX_BYTES = void 0;
+const node_crypto_1 = require("node:crypto");
+/** Under API Gateway's 32 KB frame, with room for the envelope and a long session or two. */
+exports.SESSIONS_REPORT_MAX_BYTES = 24 * 1024;
+const bytes = (text) => Buffer.byteLength(text, 'utf-8');
+const planSessionsReport = (sessions, knownSessions, maxBytes = exports.SESSIONS_REPORT_MAX_BYTES, reportId = node_crypto_1.randomUUID) => {
+    const whole = JSON.stringify({ type: 'listener.sessions', data: { sessions, knownSessions } });
+    const wholeBytes = bytes(whole);
+    if (wholeBytes <= maxBytes) {
+        return { messages: [whole], sessionCount: sessions.length, wholeBytes, oversized: [], namesOversized: false };
+    }
+    const id = reportId();
+    const knownBytes = bytes(JSON.stringify({ knownSessions }));
+    const envelopeBytes = bytes(JSON.stringify({
+        type: 'listener.sessions',
+        data: { sessions: [], partial: true, reportId: id, part: 999, parts: 999 },
+    }));
+    // Greedy: a session goes in the current part while it fits. The first part gives up room for
+    // `knownSessions`; no part gives up less than one session.
+    const groups = [];
+    const oversized = [];
+    let current = [];
+    let budget = Math.max(maxBytes - envelopeBytes - knownBytes, 0);
+    let used = 0;
+    for (const session of sessions) {
+        // +1 for the comma between sessions in the array.
+        const size = bytes(JSON.stringify(session)) + 1;
+        if (current.length > 0 && used + size > budget) {
+            groups.push(current);
+            current = [];
+            used = 0;
+            budget = Math.max(maxBytes - envelopeBytes, 0);
+        }
+        if (size > budget)
+            oversized.push(session.name);
+        current.push(session);
+        used += size;
+    }
+    groups.push(current);
+    const parts = groups.length;
+    const messages = groups.map((group, index) => JSON.stringify({
+        type: 'listener.sessions',
+        data: { sessions: group, partial: true, reportId: id, part: index + 1, parts, ...(index === 0 ? { knownSessions } : {}) },
+    }));
+    const names = JSON.stringify({ type: 'listener.sessions.names', data: { names: sessions.map((s) => s.name), reportId: id } });
+    messages.push(names);
+    return { messages, sessionCount: sessions.length, wholeBytes, oversized, namesOversized: bytes(names) > maxBytes, reportId: id };
+};
+exports.planSessionsReport = planSessionsReport;
+/** How long a part waits for its ack before the report is given up (and tried again on the next poll). */
+exports.SESSIONS_ACK_TIMEOUT_MS = 10_000;
+/**
+ * Send a plan's messages in order. With parts, every message but the last (`names`) waits for its
+ * ack before the next goes — `awaitAck(part)` is asked for before the send, so a quick answer is not
+ * missed, and `names` (which removes whatever it does not list) only goes once every part landed.
+ * False when an ack did not come: the rest is not sent, and the caller treats the report as unsent.
+ */
+const sendSessionsReport = async (messages, send, awaitAck) => {
+    for (let i = 0; i < messages.length; i++) {
+        const acked = messages.length > 1 && i < messages.length - 1 ? awaitAck(i + 1) : null;
+        send(messages[i]);
+        if (acked && !(await acked))
+            return false;
+    }
+    return true;
+};
+exports.sendSessionsReport = sendSessionsReport;

package/dist/shell-audit.d.ts

@@ -0,0 +1,34 @@
+/** One phone → shell-session injection, as the listener admitted it. */
+export interface ShellAuditEntry {
+    at: Date;
+    session: string;
+    /** The pane the guard probed — the one the input was typed into. */
+    target: string;
+    kind: 'body' | 'insert' | 'keys';
+    /** `pane_current_command` when the input landed. */
+    foreground: string;
+    /** The foreground is the shell itself, so the text is a command line. */
+    atShell: boolean;
+    /** The text, or the key names joined by spaces. */
+    text: string;
+}
+export declare const shellAuditPath: () => string;
+/** Past this size the log moves to `shell-audit.log.1`, replacing the one before. */
+export declare const SHELL_AUDIT_MAX_BYTES: number;
+/**
+ * One tab-separated line. The text is kept only when it was typed at the shell
+ * prompt: anything else went to a program running in the pane — a `sudo`
+ * password prompt, an `ssh` login — and is recorded by length alone. Key names
+ * are never secret, so they are kept whatever the foreground is. The payload
+ * and every name are JSON-quoted, so a tab or newline in any of them cannot
+ * forge a field or a line.
+ */
+export declare const formatShellAuditLine: (e: ShellAuditEntry) => string;
+/**
+ * Append one entry to the audit log, a 0600 file (the state dir it sits in is
+ * shared, and whichever writer creates it first sets its mode). Returns false
+ * instead of throwing: the log answers "what did the phone run", and a full
+ * disk must not also stop the phone from running it.
+ */
+export declare const appendShellAudit: (entry: ShellAuditEntry, path?: string) => boolean;
+//# sourceMappingURL=shell-audit.d.ts.map

package/dist/shell-audit.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appendShellAudit = exports.formatShellAuditLine = exports.SHELL_AUDIT_MAX_BYTES = exports.shellAuditPath = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const gate_js_1 = require("./gate.js");
+const private_files_js_1 = require("./private-files.js");
+const shellAuditPath = () => (0, path_1.join)((0, gate_js_1.stateDir)(), 'shell-audit.log');
+exports.shellAuditPath = shellAuditPath;
+/** Past this size the log moves to `shell-audit.log.1`, replacing the one before. */
+exports.SHELL_AUDIT_MAX_BYTES = 1024 * 1024;
+/**
+ * One tab-separated line. The text is kept only when it was typed at the shell
+ * prompt: anything else went to a program running in the pane — a `sudo`
+ * password prompt, an `ssh` login — and is recorded by length alone. Key names
+ * are never secret, so they are kept whatever the foreground is. The payload
+ * and every name are JSON-quoted, so a tab or newline in any of them cannot
+ * forge a field or a line.
+ */
+const formatShellAuditLine = (e) => {
+    const payload = e.atShell || e.kind === 'keys'
+        ? JSON.stringify(e.text)
+        : `[${[...e.text].length} chars → ${JSON.stringify(e.foreground)}]`;
+    const q = JSON.stringify;
+    return [e.at.toISOString(), q(e.session), q(e.target), e.kind, q(e.foreground), payload].join('\t') + '\n';
+};
+exports.formatShellAuditLine = formatShellAuditLine;
+/**
+ * Append one entry to the audit log, a 0600 file (the state dir it sits in is
+ * shared, and whichever writer creates it first sets its mode). Returns false
+ * instead of throwing: the log answers "what did the phone run", and a full
+ * disk must not also stop the phone from running it.
+ */
+const appendShellAudit = (entry, path = (0, exports.shellAuditPath)()) => {
+    try {
+        (0, private_files_js_1.mkdirHandedBack)((0, gate_js_1.stateDir)(), 0o700);
+        if (((0, fs_1.statSync)(path, { throwIfNoEntry: false })?.size ?? 0) >= exports.SHELL_AUDIT_MAX_BYTES)
+            (0, fs_1.renameSync)(path, `${path}.1`);
+        (0, fs_1.appendFileSync)(path, (0, exports.formatShellAuditLine)(entry), { mode: 0o600 });
+        (0, private_files_js_1.handBackToSudoUser)(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+exports.appendShellAudit = appendShellAudit;