@hwip/cli 0.0.1 → 0.1.1

package/dist/turn-ring.d.ts

@@ -0,0 +1,93 @@
+import type { TurnEvent } from './transcript-tail.js';
+/**
+ * What the daemon has already sent a chat viewer, kept on disk so a
+ * re-subscribe can replay it.
+ *
+ * Why this exists at all: the live lane is ephemeral, and the transcript
+ * backfill deliberately replays only since the last prompt — finished turns are
+ * supposed to already exist in the chat as their completion pushes. Under the
+ * `quiet` push dial they do not exist, because that dial suppresses every
+ * auto-push without a `high` marker. A turn's closing words were therefore
+ * visible while it ran and gone the moment the viewer re-armed, with no record
+ * on the phone, on the server, or in the 256KB backfill window.
+ *
+ * Re-deriving those turns from the transcript is not an option: measured over
+ * this machine's transcripts larger than the window, the last 256KB holds a
+ * median of one human prompt and none at all in 8 of 19 files — a single
+ * `tool_result` line can be most of a megabyte. Projected events are a tool
+ * name, a short label and a verdict, so the same bytes hold turns rather than
+ * fragments of one.
+ *
+ * It lives beside `known-sessions.json` under `stateDir()` rather than in
+ * `~/.hwip`, for the same reason that file does: this is derived session state
+ * that expires, not configuration or keys.
+ *
+ * Everything here is best-effort. A ring that cannot be written costs the
+ * scrollback, never the live send — the daemon's job is to keep talking.
+ */
+/**
+ * One ring file. Trimming is by bytes and not by event count on purpose: a
+ * prose event carries up to `MAX_EVENT_TEXT_CHARS` (5000) while a tool event's
+ * label is clamped at `MAX_EVENT_FIELD_CHARS` (512), so a count would bound two
+ * things an order of magnitude apart.
+ */
+export declare const MAX_TURN_RING_BYTES: number;
+/** Sessions with a ring. Past this the oldest by mtime are dropped. */
+export declare const MAX_TURN_RING_FILES = 20;
+/**
+ * How long anything stays on disk: a day, for the ring and for each event in it.
+ *
+ * The ring holds prompts and replies in the clear (the live lane is sealed, this
+ * is not), so the retention window is the exposure window. What it has to
+ * cover is a viewer re-arming after a quiet stretch — overnight at the longest;
+ * the transcript backfill carries the current turn from there. A week kept
+ * seven times the plaintext for a need nobody measured past that.
+ */
+export declare const TURN_RING_TTL_MS: number;
+export declare const turnRingDir: () => string;
+/**
+ * The session name is chosen by whoever sent the watch request, so it never
+ * reaches the filesystem — a hash does. Same move as `hashListenerId`, at twice
+ * the width: 64 bits, because these names collide within one machine's
+ * directory rather than identifying one device.
+ */
+export declare const turnRingPath: (sessionName: string) => string;
+/**
+ * Record events this watch just sent. Call it with the same array that went out
+ * — the ring's whole meaning is "what the viewer already received", and a replay
+ * is that array sent again.
+ */
+export declare const appendTurnRing: (sessionName: string, events: readonly TurnEvent[]) => boolean;
+/**
+ * What this session's viewers have already been sent, oldest first.
+ *
+ * An expired ring is deleted here rather than merely ignored: returning an empty
+ * array and leaving the file would let the next append land on top of pre-expiry
+ * content, and the TTL would bound nothing.
+ */
+export declare const readTurnRing: (sessionName: string, now?: number) => TurnEvent[];
+/** Drop expired rings, then expired events, then the oldest rings past `MAX_TURN_RING_FILES`. */
+export declare const sweepTurnRings: (now?: number) => void;
+/**
+ * Forget one session's scrollback outright — the machine was told to forget the
+ * session. False when the file is still there, which the caller has to say out
+ * loud: answering "forgotten" while a day of prompts and tool targets sits on
+ * disk is the one wrong answer here.
+ */
+export declare const removeTurnRing: (sessionName: string) => boolean;
+/**
+ * The three operations a watcher needs, as one injectable surface.
+ *
+ * The watcher takes this rather than importing the module so its tests can hold
+ * the ring in memory — what the disk does is settled here, and re-proving it
+ * through a socket-and-transcript harness would only make those tests slower and
+ * no more truthful.
+ */
+export interface TurnRing {
+    read: (sessionName: string) => TurnEvent[];
+    /** False when nothing was written — a full disk, a directory that is not ours. */
+    append: (sessionName: string, events: readonly TurnEvent[]) => boolean;
+    sweep: () => void;
+}
+export declare const diskTurnRing: TurnRing;
+//# sourceMappingURL=turn-ring.d.ts.map

package/dist/turn-ring.js

@@ -0,0 +1,418 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diskTurnRing = exports.removeTurnRing = exports.sweepTurnRings = exports.readTurnRing = exports.appendTurnRing = exports.turnRingPath = exports.turnRingDir = exports.TURN_RING_TTL_MS = exports.MAX_TURN_RING_FILES = exports.MAX_TURN_RING_BYTES = void 0;
+const fs_1 = require("fs");
+const crypto_1 = require("crypto");
+const path_1 = require("path");
+const gate_js_1 = require("./gate.js");
+const private_files_js_1 = require("./private-files.js");
+/**
+ * What the daemon has already sent a chat viewer, kept on disk so a
+ * re-subscribe can replay it.
+ *
+ * Why this exists at all: the live lane is ephemeral, and the transcript
+ * backfill deliberately replays only since the last prompt — finished turns are
+ * supposed to already exist in the chat as their completion pushes. Under the
+ * `quiet` push dial they do not exist, because that dial suppresses every
+ * auto-push without a `high` marker. A turn's closing words were therefore
+ * visible while it ran and gone the moment the viewer re-armed, with no record
+ * on the phone, on the server, or in the 256KB backfill window.
+ *
+ * Re-deriving those turns from the transcript is not an option: measured over
+ * this machine's transcripts larger than the window, the last 256KB holds a
+ * median of one human prompt and none at all in 8 of 19 files — a single
+ * `tool_result` line can be most of a megabyte. Projected events are a tool
+ * name, a short label and a verdict, so the same bytes hold turns rather than
+ * fragments of one.
+ *
+ * It lives beside `known-sessions.json` under `stateDir()` rather than in
+ * `~/.hwip`, for the same reason that file does: this is derived session state
+ * that expires, not configuration or keys.
+ *
+ * Everything here is best-effort. A ring that cannot be written costs the
+ * scrollback, never the live send — the daemon's job is to keep talking.
+ */
+/**
+ * One ring file. Trimming is by bytes and not by event count on purpose: a
+ * prose event carries up to `MAX_EVENT_TEXT_CHARS` (5000) while a tool event's
+ * label is clamped at `MAX_EVENT_FIELD_CHARS` (512), so a count would bound two
+ * things an order of magnitude apart.
+ */
+exports.MAX_TURN_RING_BYTES = 256 * 1024;
+/** Sessions with a ring. Past this the oldest by mtime are dropped. */
+exports.MAX_TURN_RING_FILES = 20;
+/**
+ * How long anything stays on disk: a day, for the ring and for each event in it.
+ *
+ * The ring holds prompts and replies in the clear (the live lane is sealed, this
+ * is not), so the retention window is the exposure window. What it has to
+ * cover is a viewer re-arming after a quiet stretch — overnight at the longest;
+ * the transcript backfill carries the current turn from there. A week kept
+ * seven times the plaintext for a need nobody measured past that.
+ */
+exports.TURN_RING_TTL_MS = 24 * 60 * 60 * 1000;
+const turnRingDir = () => (0, path_1.join)((0, gate_js_1.stateDir)(), 'turns');
+exports.turnRingDir = turnRingDir;
+/**
+ * The session name is chosen by whoever sent the watch request, so it never
+ * reaches the filesystem — a hash does. Same move as `hashListenerId`, at twice
+ * the width: 64 bits, because these names collide within one machine's
+ * directory rather than identifying one device.
+ */
+const turnRingPath = (sessionName) => (0, path_1.join)((0, exports.turnRingDir)(), `${(0, crypto_1.createHash)('sha256').update(sessionName).digest('hex').slice(0, 16)}.jsonl`);
+exports.turnRingPath = turnRingPath;
+const sizeOf = (path) => {
+    try {
+        return (0, fs_1.statSync)(path).size;
+    }
+    catch {
+        return 0;
+    }
+};
+/**
+ * Whether an event is still inside the TTL by its own `at`. An event with no
+ * stamp (or one that does not parse) is kept: its age is unknown, and the file's
+ * mtime already bounds the ring as a whole.
+ */
+const eventInDate = (event, now) => {
+    const at = typeof event.at === 'string' ? Date.parse(event.at) : NaN;
+    return !Number.isFinite(at) || now - at <= exports.TURN_RING_TTL_MS;
+};
+const isExpired = (path, now) => {
+    try {
+        return now - (0, fs_1.statSync)(path).mtimeMs > exports.TURN_RING_TTL_MS;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Paths whose owner-only mode this process has already set. `mode` on
+ * mkdir/append applies only when the entry is created, so a directory or file
+ * that already existed keeps whatever it had — a pre-created 0755 `turns/` would
+ * never become 0700 on its own. One chmod on first touch fixes that; every later
+ * append writes to a file this process has already made private.
+ */
+const secured = new Set();
+/**
+ * The size each ring is known to have, kept so a tick does not stat the file.
+ * It starts from a real stat, grows by what this process appends, and is dropped
+ * whenever a file is removed, trimmed, rewritten or fails to append, so the next
+ * append reads the truth again. It counts only this process's bytes: a second
+ * writer on the same file would not be seen. The listener is the only writer
+ * today, and `forget` only deletes — which makes the estimate too high, so a
+ * trim comes early and nothing breaks.
+ *
+ * `secured` below is likewise per process: a mode loosened by the same user
+ * while the daemon runs is not re-tightened until it restarts.
+ */
+const sizes = new Map();
+const removeQuietly = (path) => {
+    sizes.delete(path);
+    try {
+        (0, fs_1.unlinkSync)(path);
+    }
+    catch {
+        /* already gone, or not ours to delete */
+    }
+};
+/**
+ * How far under the cap a trim cuts.
+ *
+ * Trimming exactly to the cap would leave the file one event below it, so the
+ * next append crosses again and rewrites the whole thing — a full read, split
+ * and rename per event for the rest of the session. Cutting deeper buys roughly
+ * a quarter of the ring's worth of appends between rewrites.
+ */
+const TRIM_TARGET_BYTES = Math.floor(exports.MAX_TURN_RING_BYTES * 0.75);
+/** Keep the newest lines that fit under `MAX_TURN_RING_BYTES`. False when the cap still stands broken. */
+const trimToCap = (path) => {
+    let raw;
+    try {
+        if ((0, fs_1.statSync)(path).size <= exports.MAX_TURN_RING_BYTES)
+            return true;
+        raw = (0, fs_1.readFileSync)(path, 'utf-8');
+    }
+    catch {
+        return false;
+    }
+    const lines = raw.split('\n').filter((line) => line.length > 0);
+    let bytes = 0;
+    let start = lines.length;
+    // Newest first, until the next line would not fit.
+    while (start > 0) {
+        const size = Buffer.byteLength(lines[start - 1], 'utf-8') + 1;
+        if (bytes + size > TRIM_TARGET_BYTES)
+            break;
+        bytes += size;
+        start--;
+    }
+    // A single line longer than the whole cap takes nothing, which would empty
+    // the ring — and empty it again on every later append. The newest line
+    // always survives; the one after it trims this one away in turn.
+    start = Math.min(start, lines.length - 1);
+    const kept = lines
+        .slice(start)
+        .map((line) => `${line}\n`)
+        .join('');
+    // Through a temp file, unlike the append: a kill mid-append costs the last
+    // line, a kill mid-rewrite would cost the whole ring.
+    // Random name, exclusive create: a predictable `${path}.tmp` is a file
+    // another process on this machine can pre-create as a symlink and have this
+    // write follow. `wx` fails instead of following one.
+    const tmp = `${path}.${(0, crypto_1.randomBytes)(6).toString('hex')}.tmp`;
+    try {
+        (0, fs_1.writeFileSync)(tmp, kept, { mode: 0o600, flag: 'wx' });
+        (0, private_files_js_1.handBackToSudoUser)(tmp);
+        (0, fs_1.renameSync)(tmp, path);
+        return true;
+    }
+    catch {
+        removeQuietly(tmp);
+        // The append landed but the cap did not. Saying the write succeeded
+        // would let the file grow past its bound with nothing ever noticing.
+        return false;
+    }
+};
+/**
+ * Record events this watch just sent. Call it with the same array that went out
+ * — the ring's whole meaning is "what the viewer already received", and a replay
+ * is that array sent again.
+ */
+const appendTurnRing = (sessionName, events) => {
+    if (!events.length)
+        return true;
+    // Empty until the name hashes: a catch before that has no ring to forget.
+    let path = '';
+    try {
+        // Inside the guard: the name arrives off the wire, and a non-string one
+        // makes `createHash().update()` throw where "best-effort" is the whole
+        // contract — a ring that cannot be written must never take a tick down.
+        path = (0, exports.turnRingPath)(sessionName);
+        const data = events.map((event) => `${JSON.stringify(event)}\n`).join('');
+        const dir = (0, exports.turnRingDir)();
+        const firstTouch = !secured.has(path);
+        if (firstTouch) {
+            (0, private_files_js_1.mkdirHandedBack)(dir, 0o700);
+            (0, fs_1.chmodSync)(dir, 0o700);
+        }
+        // Read before the append so a first write counts the file as it was.
+        const known = sizes.get(path) ?? sizeOf(path);
+        try {
+            (0, fs_1.appendFileSync)(path, data, { mode: 0o600 });
+        }
+        catch (err) {
+            // The directory was removed under a long-running daemon (a manual
+            // cleanup, a forget that took the folder). Make it again and retry
+            // once — a ring that stayed dead for the rest of the process would
+            // lose every later turn.
+            if (err?.code !== 'ENOENT')
+                throw err;
+            (0, private_files_js_1.mkdirHandedBack)(dir, 0o700);
+            (0, fs_1.chmodSync)(dir, 0o700);
+            (0, fs_1.appendFileSync)(path, data, { mode: 0o600 });
+        }
+        if (firstTouch) {
+            (0, fs_1.chmodSync)(path, 0o600);
+            (0, private_files_js_1.handBackToSudoUser)(path);
+            secured.add(path);
+        }
+        const size = known + Buffer.byteLength(data, 'utf-8');
+        if (size <= exports.MAX_TURN_RING_BYTES) {
+            sizes.set(path, size);
+            return true;
+        }
+    }
+    catch {
+        // A failed append can still have landed some bytes, so the tracked size
+        // is no longer known.
+        sizes.delete(path);
+        // The caller says so once per session rather than per tick: a full disk
+        // costs the scrollback, and silence about it costs the diagnosis.
+        return false;
+    }
+    // Over the cap by the tracked size: let the trim read the real one.
+    sizes.delete(path);
+    return trimToCap(path);
+};
+exports.appendTurnRing = appendTurnRing;
+/**
+ * What this session's viewers have already been sent, oldest first.
+ *
+ * An expired ring is deleted here rather than merely ignored: returning an empty
+ * array and leaving the file would let the next append land on top of pre-expiry
+ * content, and the TTL would bound nothing.
+ */
+const readTurnRing = (sessionName, now = Date.now()) => {
+    let raw;
+    let path;
+    try {
+        // Same reason as the append: the name is wire input, and hashing a
+        // non-string throws.
+        path = (0, exports.turnRingPath)(sessionName);
+        if (isExpired(path, now)) {
+            removeQuietly(path);
+            return [];
+        }
+        raw = (0, fs_1.readFileSync)(path, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    const events = [];
+    for (const line of raw.split('\n')) {
+        if (!line)
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            // `null`, `5`, `[]` and `{}` are all valid JSON. Without a shape
+            // check a hand-edited or planted ring hands slice 02 a non-event to
+            // seal and send. `kind` is what every branch downstream switches on,
+            // so that is what makes a line an event — the same row-level filter
+            // `session-registry.ts:52-62` applies to its own file.
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+                continue;
+            if (typeof parsed.kind !== 'string')
+                continue;
+            // The file's mtime moves on every append, so a ring that is still
+            // being written never expires as a whole — its old events do.
+            if (!eventInDate(parsed, now))
+                continue;
+            events.push(parsed);
+        }
+        catch {
+            // A line the daemon was killed halfway through: skip it, keep the
+            // rest — again the transcript reader's rule.
+        }
+    }
+    return events;
+};
+exports.readTurnRing = readTurnRing;
+/**
+ * Take events past the TTL off the disk, and with them any line `readTurnRing`
+ * would skip anyway (a torn write, a non-event). Every line is judged rather
+ * than a leading run: one line that cannot be judged at the front of the file
+ * would otherwise stop the prune for the rest of that ring's life, and the
+ * file's mtime — moved by every append — never expires it either. Reads and
+ * parses the whole ring, at most `MAX_TURN_RING_BYTES` of it. False when nothing
+ * is left of the ring — the file is gone.
+ */
+const pruneExpiredEvents = (path, now) => {
+    let raw;
+    try {
+        raw = (0, fs_1.readFileSync)(path, 'utf-8');
+    }
+    catch {
+        return false;
+    }
+    const lines = raw.split('\n').filter((line) => line.length > 0);
+    const kept = lines.filter((line) => {
+        try {
+            const event = JSON.parse(line);
+            return (!!event &&
+                typeof event === 'object' &&
+                !Array.isArray(event) &&
+                typeof event.kind === 'string' &&
+                eventInDate(event, now));
+        }
+        catch {
+            return false;
+        }
+    });
+    if (kept.length === lines.length)
+        return true;
+    if (kept.length === 0) {
+        removeQuietly(path);
+        return false;
+    }
+    // Same temp-and-rename as the trim, for the same reason: a kill mid-rewrite
+    // must not cost the whole ring.
+    const tmp = `${path}.${(0, crypto_1.randomBytes)(6).toString('hex')}.tmp`;
+    try {
+        (0, fs_1.writeFileSync)(tmp, kept.map((line) => `${line}\n`).join(''), { mode: 0o600, flag: 'wx' });
+        (0, private_files_js_1.handBackToSudoUser)(tmp);
+        (0, fs_1.renameSync)(tmp, path);
+        sizes.delete(path);
+        return true;
+    }
+    catch {
+        // Not rewritten, so what was there is still there — and still counts.
+        removeQuietly(tmp);
+        return true;
+    }
+};
+/** Drop expired rings, then expired events, then the oldest rings past `MAX_TURN_RING_FILES`. */
+const sweepTurnRings = (now = Date.now()) => {
+    const dir = (0, exports.turnRingDir)();
+    let names;
+    try {
+        names = (0, fs_1.readdirSync)(dir);
+    }
+    catch {
+        return;
+    }
+    const live = [];
+    for (const name of names) {
+        const path = (0, path_1.join)(dir, name);
+        // A kill between the trim's write and its rename strands a temp file.
+        // Nothing else would ever remove it, and left in place it counts
+        // against MAX_TURN_RING_FILES and evicts a live ring early. Matching the
+        // ring's own name shape rather than just the extension also means a
+        // stray file dropped in here is cleaned up rather than counted.
+        if (!/^[0-9a-f]{16}\.jsonl$/.test(name)) {
+            removeQuietly(path);
+            continue;
+        }
+        let mtimeMs;
+        try {
+            mtimeMs = (0, fs_1.statSync)(path).mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        if (now - mtimeMs > exports.TURN_RING_TTL_MS) {
+            removeQuietly(path);
+            continue;
+        }
+        if (pruneExpiredEvents(path, now))
+            live.push({ path, mtimeMs });
+    }
+    if (live.length <= exports.MAX_TURN_RING_FILES)
+        return;
+    live.sort((a, b) => a.mtimeMs - b.mtimeMs);
+    for (const stale of live.slice(0, live.length - exports.MAX_TURN_RING_FILES))
+        removeQuietly(stale.path);
+};
+exports.sweepTurnRings = sweepTurnRings;
+/**
+ * Forget one session's scrollback outright — the machine was told to forget the
+ * session. False when the file is still there, which the caller has to say out
+ * loud: answering "forgotten" while a day of prompts and tool targets sits on
+ * disk is the one wrong answer here.
+ */
+const removeTurnRing = (sessionName) => {
+    let path;
+    try {
+        path = (0, exports.turnRingPath)(sessionName);
+    }
+    catch {
+        return true; // a name that cannot even be hashed has no ring
+    }
+    sizes.delete(path);
+    try {
+        (0, fs_1.unlinkSync)(path);
+        return true;
+    }
+    catch (err) {
+        // Already gone is the outcome the caller asked for. Checking existence
+        // first and then unlinking would call a file that vanished in between a
+        // failure, and answer "your scrollback is still there" about nothing.
+        return err?.code === 'ENOENT';
+    }
+};
+exports.removeTurnRing = removeTurnRing;
+exports.diskTurnRing = {
+    read: (sessionName) => (0, exports.readTurnRing)(sessionName),
+    append: (sessionName, events) => (0, exports.appendTurnRing)(sessionName, events),
+    sweep: () => (0, exports.sweepTurnRings)(),
+};

package/dist/turn-watch.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Live agent-chat timeline: tail this machine's Claude Code transcripts and push
+ * the small events off them over the relay the daemon already holds open.
+ *
+ * Sibling of the tmux mirror in `listener.ts`, deliberately not the same thing.
+ * The mirror sends a picture of a terminal; this sends what the agent *did*, so
+ * a phone can read a session the way the Claude app reads one — without the
+ * viewer having to parse ANSI, and without any of it becoming a push (no quota,
+ * no notification).
+ *
+ * Registry, lifecycle and framing mirror `activeStreams`/`stopStream`, because
+ * a second shape for the same job is a second set of leaks to find. What differs
+ * is the source: a file that grows, not a pane that repaints. `transcript-tail`
+ * owns that difference and stays pure; this file owns the socket and the clock.
+ *
+ * Every dependency that touches the world arrives through `TurnWatchDeps`, so
+ * the tests drive real ticks with a fake transcript and no WebSocket at all.
+ */
+import { type TranscriptSource, type TurnEvent } from './transcript-tail.js';
+import type { TurnRing } from './turn-ring.js';
+/**
+ * Watchers this daemon will run at once — the same ceiling, for the same reason,
+ * as `MAX_CONCURRENT_STREAMS`. One machine can host a dozen tmux sessions, and
+ * a viewer that opened them all would otherwise have every one polling forever.
+ */
+export declare const MAX_TURN_WATCHERS = 3;
+/**
+ * Poll cadence. The plan's user-visible bar is "a tool call shows up within 2s";
+ * at 500 ms the read itself is never the reason it misses. Slower than the
+ * mirror's 400 ms on purpose — this loop answers "what happened", not "what does
+ * the screen look like", and nothing here is animated.
+ */
+export declare const TURN_POLL_INTERVAL_MS = 500;
+/**
+ * How long a watch survives without a renew.
+ *
+ * `watch.stop` is best-effort by construction: a swiped-away native sheet, a
+ * killed tab, or a dropped socket destroys the viewer before it can say
+ * anything. The lease — not the stop message — is what guarantees this daemon
+ * stops reading. Matches the terminal stream's `STREAM_SUB_TTL_SECONDS`.
+ */
+export declare const TURN_LEASE_MS = 60000;
+/**
+ * How often a live watch re-asks which transcript its session is writing.
+ *
+ * `/clear` and a compaction start a new session file under a new name; the old
+ * one simply stops growing, so a watcher pinned to the path it resolved at
+ * `start` goes quiet forever and looks exactly like an idle agent. Nothing in
+ * the file itself can signal this — the answer lives in the session registry —
+ * so it is asked for on a cadence rather than discovered.
+ *
+ * This is not a cheap question, and the number is chosen against its real cost:
+ * `resolveTranscript` runs `readPaneInfo`, an uncached blocking
+ * `spawnSync('tmux', …)` (`listener.ts`), and the pid-record memo behind it
+ * expires every 4s (`remote-agents.ts` SNAPSHOT_TTL_MS), so a recheck is one
+ * tmux spawn plus a real directory read — not a memo hit. At 10s per watcher and
+ * at most three watchers that stays under what the session report already spends
+ * on its own (`SESSION_REPORT_INTERVAL_MS` = 5s, one sweep for the whole
+ * machine), while keeping how long a cleared session stays dark to one interval.
+ */
+export declare const TRANSCRIPT_RECHECK_MS = 10000;
+/**
+ * Consecutive seal failures before the watch gives up and says so.
+ *
+ * Dropping a batch that will not seal is right; dropping every batch forever is
+ * an empty timeline the viewer cannot tell from an idle session. The mirror
+ * draws the same line with `STREAM_MAX_ENCRYPT_FAILURES`: fail closed, then stop
+ * and send an error the other side can render.
+ *
+ * A live tick stops at its first unsealable page (see `readAndEmit`), so one
+ * busy tick spends one failure; a replay's pages each spend one, as they did
+ * before live ticks were paged.
+ */
+export declare const MAX_TURN_SEAL_FAILURES = 3;
+/**
+ * Ceiling on one replay, in events.
+ *
+ * The viewer keeps a bounded window of live turns, and a replay that filled it
+ * on its own would push the turn actually in flight out of the very screen the
+ * replay exists to fill. Below the web cap on purpose, so the live tail still
+ * has room after a full replay.
+ */
+export declare const MAX_REPLAY_EVENTS = 400;
+/**
+ * Plaintext bytes per frame. Ephemeral frames ride API Gateway's 32KB WebSocket
+ * limit, and sealing base64-expands what goes in it — so this is deliberately
+ * below `SCREEN_PEEK_MAX_BYTES` (24KB, `listener.ts`), which bounds frames that
+ * are never sealed.
+ */
+export declare const MAX_TURN_FRAME_BYTES: number;
+/** Wire shape of one batch of timeline events. */
+export type TurnDeltaFrame = {
+    subtype: 'agent.turn.delta';
+    sessionName: string;
+    /** Incarnation of this watch. See `AgentTurnDeltaFrame` (hwip `libs/feed-ui`)
+     *  for why the pair exists; the mirror stamps frames the same way
+     *  (`StreamFramePayload.epoch`). */
+    epoch: number;
+    seq: number;
+    /** Plaintext batch — present only when the subscriber supplied no key. */
+    events?: TurnEvent[];
+    /** Sealed batch — the same array, encrypted for the subscriber. */
+    encrypted?: unknown;
+};
+/** What a viewer sends to start, keep, or end a watch. */
+export interface TurnWatchControl {
+    subtype?: string;
+    targetDeviceId?: string;
+    sessionName?: string;
+    /**
+     * The viewer's device public key. Present when that device can open what it
+     * asks to be sealed; absent on a device with no keypair, which then reads
+     * the same events in the clear — the convention `useAgentDiff` and
+     * `TerminalStreamView` already follow on the web side. Encryption is a paid
+     * feature, so refusing to serve an unsealed viewer would quietly make the
+     * whole timeline paid too.
+     */
+    subscriberPublicKey?: string;
+}
+export type SendTurnFrame = (data: Record<string, unknown>) => void;
+export interface TurnWatchDeps {
+    /** This machine's listener device id — control messages that name another are not ours. */
+    deviceId: () => string;
+    /**
+     * tmux session name → that session's transcript and the projector that reads
+     * it, or null when this agent has no transcript this daemon knows how to
+     * follow. Path and projector arrive together because they are one answer;
+     * see `TranscriptSource`.
+     *
+     * `onMiss` is the reason channel for the null. The resolver is the only side
+     * that knows *why* — whether the row carries no resolver at all, or carries
+     * one whose path rule came back empty-handed — and those two look identical
+     * from here and identical on the phone. The caller decides how often to ask
+     * for a reason: `handle` passes one because a viewer is waiting on the
+     * answer, the recheck does not because it runs every TRANSCRIPT_RECHECK_MS
+     * and would turn one unsupported agent into a line every ten seconds.
+     */
+    resolveTranscript: (sessionName: string, onMiss?: (reason: string) => void) => TranscriptSource | null;
+    /** Whether tmux still holds this session. A watch outlives its pane otherwise. */
+    sessionExists: (sessionName: string) => boolean;
+    /**
+     * Load-or-create this device's keypair. Rejecting means this daemon cannot
+     * seal at all, which a viewer that asked for a seal must be told about
+     * rather than discovering three dropped batches later.
+     */
+    initCrypto: () => Promise<void>;
+    /** Seal one batch for the watcher, bound to its session (envelope v2 `turn.batch`).
+     *  Rejecting drops the batch; it never falls back to plaintext. */
+    seal: (plaintext: string, subscriberPublicKey: string, sessionName: string) => Promise<unknown>;
+    log: (message: string) => void;
+    /** Where a watch's events are kept so a later watch can replay them. */
+    ring: TurnRing;
+    now?: () => number;
+}
+/**
+ * Cut a batch into frames of at most MAX_TURN_FRAME_BYTES of plaintext. One
+ * event bigger than the whole budget still goes, alone: prose is clamped at
+ * MAX_EVENT_TEXT_CHARS characters, not bytes, so a Korean paragraph can reach
+ * ~15KB — the budget keeps a *batch* inside the transport, it is not a promise
+ * about every single event.
+ */
+export declare const pagesOf: (events: readonly TurnEvent[]) => TurnEvent[][];
+/**
+ * A registry of transcript watchers plus the control handler that drives it.
+ *
+ * A factory rather than module state so a test can hold its own, and so two of
+ * them never share a clock or a socket by accident.
+ */
+export declare const createTurnWatchers: (deps: TurnWatchDeps) => {
+    handle: (req: TurnWatchControl, send: SendTurnFrame) => boolean;
+    stop: (sessionName: string, reason: string) => void;
+    stopAll: (reason: string) => void;
+    tick: (sessionName: string) => Promise<void>;
+    size: () => number;
+};
+export type TurnWatchers = ReturnType<typeof createTurnWatchers>;
+//# sourceMappingURL=turn-watch.d.ts.map