@hwip/cli 0.0.1 → 0.1.1

package/dist/listener.d.ts

@@ -0,0 +1,1325 @@
+/**
+ * `hwip listener` — resident daemon that watches the user's Hwip feed
+ * over a persistent WebSocket and injects matching messages into a
+ * named tmux session via `tmux send-keys`.
+ *
+ * Solves the MCP polling-window problem: an `hwip_ask` polling cycle
+ * times out (120–600 s) and the CC/Codex session becomes unaddressable
+ * from the phone. The listener stays subscribed indefinitely and can
+ * deliver to any named tmux session at any time.
+ *
+ * Wire format: pushes with `type='agent.command'` carry the tmux
+ * session name in `agentSessionName` and the message in `body`. The
+ * "AI Agent에게 명령" sheet on the phone builds these structured
+ * pushes from the listener-reported session inventory. Other push
+ * types (Stop-hook auto-pushes, hwip_ask responses, channel
+ * broadcasts) are ignored.
+ *
+ * Transport: WebSocket against the Hwip $connect endpoint with
+ * `?apiKey=<key>`. The server fan-out pushes `{ type: 'push.new', data }`
+ * messages as new pushes are created. Reconnects with exponential
+ * backoff on transient failures; gives up on auth failures (4001/4002/4003).
+ */
+import { type HwipConfig } from './config.js';
+import { type ShellAuditEntry } from './shell-audit.js';
+import { type AgentKind } from './remote-agents.js';
+import { type TranscriptSource } from './transcript-tail.js';
+import { type AgentState } from './agent-state.js';
+import { type SealedFileMeta, type SealedV2 } from './crypto.js';
+import { type RecordableSession } from './turn-recorder.js';
+import { type BlockedPromptWire, type PromptSealer } from './blocked-prompt-seal.js';
+import { type CommandRefusal } from './command-refusal.js';
+import { optionalFeatures } from './optional-features.js';
+import { type RefusalCode, type SubscriberTrust } from './subscriber-trust.js';
+import { type DesktopNotification } from './desktop-notify.js';
+import { type SendTurnFrame, type TurnWatchControl } from './turn-watch.js';
+import { type SequencedInput } from './input-sequencer.js';
+import { type AgentCommandCatalog } from './command-scan.js';
+import { silenceListenerLog } from './listener-log.js';
+import { invalidateTmuxSocketCache, tmuxArgs } from './tmux-socket.js';
+import { detectRemoteAgent, isSubagentSessionName, recordSubagentTranscripts, recordTargets, subagentTranscriptFor, tmuxTargetFor } from './tmux-pane.js';
+import { liveSessionNames, sessionExists, sessionLiveness } from './tmux-liveness.js';
+import { type PhoneScheduleDeps } from './schedule-remote.js';
+import { type ScheduleRunnerDeps } from './schedule-runner.js';
+export declare const PING_IDLE_MS = 240000;
+/** Whether the socket has been quiet on our side long enough that a ping is due. */
+export declare const pingDue: (lastSentAtMs: number, nowMs: number, idleMs?: number) => boolean;
+/** What the heartbeat concludes from one look at the socket. */
+export type HeartbeatVerdict = 'alive' | 'dead' | 'blocked';
+/**
+ * Is this socket still worth keeping, given how long the server has said
+ * nothing (`silentMs`) and how long this thread was unavailable to hear it
+ * (`blockedMs`)?
+ *
+ * Both questions are needed because only one of them is about the socket. The
+ * deadline used to be a per-ping `setTimeout`, which asked neither: it was
+ * cancelled by the next ping before it could ever fire on a quiet link, so a
+ * genuinely dead socket slipped past it, while a thread blocked long enough to
+ * delay its own ping fired it against a connection that was fine. Making the
+ * judgment a function of silence and of the judge's own availability is what
+ * lets the fast path (`dead` at PONG_TIMEOUT_MS) stay real while a stalled
+ * daemon is still forgiven up to the wall-clock ceiling.
+ *
+ * `blocked` is not a reprieve without end: past WS_STALL_TIMEOUT_MS the socket
+ * dies whatever this thread was doing, because at that point we cannot tell the
+ * two apart and a reconnect is cheap.
+ */
+export declare const heartbeatVerdict: (silentMs: number, blockedMs: number, pongTimeoutMs?: number, stallTimeoutMs?: number, blockedGraceMs?: number) => HeartbeatVerdict;
+export declare const SESSION_REPORT_INTERVAL_MS = 5000;
+export declare const SESSION_REPORT_HEARTBEAT_MS = 120000;
+/** How long a report may go unanswered before the socket is presumed dead and re-opened. */
+export declare const REPORT_ACK_TIMEOUT_MS = 30000;
+/**
+ * Whether what was sent is being answered. Every `listener.sessions` report gets an ack (or an error)
+ * back, so the oldest report still waiting for one says how long the server has been deaf to us —
+ * which a quiet link cannot tell from a dead one, and which the long silence limit
+ * (PONG_TIMEOUT_MS) no longer catches in time. Time this thread could not hear anything (its own
+ * blocking, as `loopStallMs` measures) is not counted against the server.
+ */
+export declare const createReportAckWatch: (timeoutMs?: number) => {
+    /** A report went out. The oldest one still unanswered is the one that counts. */
+    sent: (nowMs: number, stallMs?: number) => void;
+    /** An ack or an error came back: the server heard us. */
+    answered: () => void;
+    overdue: (nowMs: number, stallMs?: number) => boolean;
+};
+/** What a reported session runs: a registered agent, or a `hwip sh` shell. */
+export type SessionKind = AgentKind | 'shell';
+interface AgentSession {
+    name: string;
+    attached: boolean;
+    agentKind: SessionKind;
+    /** Set when this session is a SUBAGENT — an extra pane of the parent
+     *  session `parentName` (`hwip-hwip.48` belongs to `hwip-hwip`). Subagent
+     *  sessions are view-only: input, keys, exit, resume and forget are
+     *  refused, and the server never pushes agent.state transitions for them. */
+    parentName?: string;
+    /** Calls a subagent has made so far, from its own transcript. Only a
+     *  transcript subagent has one: a pane subagent is watched as a screen, and
+     *  nothing counts what happens on it. */
+    toolCount?: number;
+    /** Set on a subagent with no pane at all (Claude Code's `Agent` tool): there
+     *  is no screen to stream, only its transcript. Absent on a pane subagent —
+     *  which can run Claude Code too, so the kind cannot stand in for this. */
+    inProcess?: true;
+    agentSessionId?: string | null;
+    project: string;
+    label?: string | null;
+    /**
+     * The name the agent itself calls this session by, when its registry
+     * exposes one (Claude Code's `hwipit-95`). A live read, not user intent —
+     * the phone's rename still wins over it. Null where the agent has no name
+     * concept, where the pane's session could not be identified, or where the
+     * name is blank.
+     *
+     * Deliberately NOT `sessionName`: everywhere else in this file and on the
+     * wire that word means the tmux session name (`agentSessionName` in a
+     * push, `AgentWatchRecord.sessionName` on the server). Two names for a
+     * session is already the problem this field exists to solve; reusing the
+     * word for both would put the ambiguity in the type.
+     */
+    providerSessionName?: string | null;
+    createdAt?: string;
+    lastActivityAt?: string;
+    /**
+     * Detected agent state (wire contract — flows to the server and the
+     * phone's Agents tab). Absent when the pane can't be captured or
+     * detection is unavailable. `done` never appears here: it's derived
+     * client-side (SPEC-AGENT-AWARENESS §S1/§S6).
+     */
+    state?: AgentState;
+    stateChangedAt?: string;
+    stateRuleId?: string;
+    /**
+     * What a `blocked` session is waiting for, sealed for the trusted devices
+     * (hwip SERVER-API.md `blockedPrompt`). Only on a main session in a dialog
+     * this listener can read; absent otherwise, and the state alone is reported
+     * as before.
+     */
+    blockedPrompt?: BlockedPromptWire;
+}
+/**
+ * Change-fingerprint for the report gate. Mirrors the server's
+ * REPORTED_SESSION_FIELDS comparison (hwip ws.ts sameReportedSessions):
+ * same fields, order-independent, undefined/null collapsed — so the
+ * client-side skip can never suppress a report the server would have
+ * treated as a change. Keep the field list in sync with the server.
+ */
+/**
+ * Sessions this machine has run and is not running now, as the phone's "past
+ * sessions" list.
+ *
+ * The list used to be derived on the phone from a page of recent pushes, which
+ * answered a different question than the one being asked: not "which sessions
+ * existed on this machine" but "what is in the newest fifty pushes". A busy day
+ * pushed real sessions out of that window while sessions the daemon had never
+ * recorded stayed in it — so the list and the resume button disagreed in both
+ * directions, offering rows that could not start and hiding rows that could.
+ *
+ * The registry is the machine's own answer to that question, and the same
+ * record resume reads, so a row that appears here is a row that can start.
+ *
+ * `cwd` is deliberately left behind. The registry keeps it because resume needs
+ * somewhere to start the agent; nothing off this machine needs a filesystem
+ * path, and sending one would hand the relay a map of the user's disk for no
+ * behaviour in return.
+ *
+ * Live sessions are excluded, which the phone would do anyway — but doing it
+ * here also keeps the payload still. Their `lastSeenAt` moves every sweep, and
+ * a field that changes every five seconds would defeat the report's
+ * unchanged-inventory gate and write to the device record all day.
+ */
+/**
+ * Sockets dropped in a row because the server did not know them, reset by the
+ * first report that lands. The cap is what keeps a server-side "reconnect"
+ * that reconnecting cannot fix from turning into a connect loop.
+ */
+export declare const MAX_STALE_CONNECTION_DROPS = 3;
+/**
+ * Whether a `listener.sessions.error` is the server telling us this connection
+ * is not registered. Keyed on the instruction rather than the wording of the
+ * diagnosis: the server says what it wants the client to DO, and every other
+ * rejection (a malformed report, a payload too large) is not fixed by
+ * reconnecting and must not cause one.
+ */
+export declare const askedToReconnect: (message: unknown) => boolean;
+/** What to do about one `listener.sessions.error`. */
+export type StaleConnectionAction = 
+/** Drop the socket; the reconnect loop registers a fresh connection. */
+'drop'
+/** Not a connection problem — reconnecting would not fix it. */
+ | 'ignore'
+/** Dropped this many times already and the reports still bounce. */
+ | 'exhausted';
+/**
+ * The policy, separated from the socket it acts on so it can be read and
+ * tested as what it is: two guards around one lever.
+ */
+export declare const staleConnectionAction: (message: unknown, drops: number) => StaleConnectionAction;
+export declare const KNOWN_SESSIONS_REPORTED = 30;
+export interface ReportedKnownSession {
+    name: string;
+    agentKind: string;
+    project?: string;
+    label?: string;
+    lastSeenAt: string;
+}
+export declare const knownSessionsToReport: (live: readonly AgentSession[], now?: number) => ReportedKnownSession[];
+export declare const knownSessionsFingerprint: (known: ReportedKnownSession[]) => string;
+export declare const sessionsFingerprint: (sessions: AgentSession[]) => string;
+/** True when this cycle's inventory must be sent: it changed, or the
+ *  idle heartbeat is due. */
+export declare const sessionsReportDue: (fingerprint: string, lastSentFingerprint: string | null, lastSentAtMs: number, nowMs: number) => boolean;
+/** How often the skill catalog is rescanned for changes. Deliberately far
+ *  slower than the session poll: this cycle reads the filesystem, and the
+ *  5 s session loop must never do that. */
+export declare const COMMAND_SCAN_INTERVAL_MS = 60000;
+export declare const commandsFingerprint: (catalog: AgentCommandCatalog) => string;
+/** Skill catalogs have no idle heartbeat — the server persists them, so an
+ *  unchanged machine has nothing to say until a skill is installed or removed. */
+export declare const commandsReportDue: (fingerprint: string, lastSentFingerprint: string | null) => boolean;
+export declare const AUTH_FAILURE_CODES: ReadonlySet<number>;
+export declare const checkRateLimit: (session: string, now?: number, cost?: number) => boolean;
+/** What the inject guard learns from one probe of a session's pinned pane. */
+export interface PaneProbe {
+    /** `pane_current_command` — the foreground program. */
+    command: string;
+    /** The session carries `@hwip_shell` naming itself (`hwip sh`): a shell here may be typed into. */
+    shellMarked: boolean;
+}
+/**
+ * Read the foreground command on the named session's PINNED pane, verifying
+ * the pane still belongs to that session. A pane id is stable across restarts
+ * only within one tmux server: after a restart the same `%N` can name a pane
+ * in a different session, and typing into that pane would be RCE into someone
+ * else's shell. The owning session and its shell marker ride along in the same
+ * display-message — one spawn, no second probe — and a mismatch answers null
+ * ("no such session"), which refuses the inject until the next sweep re-pins.
+ * An unset option formats as the empty string, so an unmarked pane reads as
+ * `shellMarked: false`, never as an error. The marker must name this very
+ * session: a format reads a user option through pane → window → session →
+ * global inheritance, so a stray `set -g @hwip_shell 1` would otherwise mark
+ * every session on the server.
+ */
+export declare const probePane: (session: string) => PaneProbe | null;
+/**
+ * Translate a phone-supplied key list to tmux tokens. Returns null if ANY
+ * key is unknown — a partial injection (some keys land, one is dropped)
+ * leaves the pane in a worse mid-state than none, so the whole batch is
+ * rejected.
+ */
+export declare const resolveKeys: (keys: string[]) => string[] | null;
+export { invalidateTmuxSocketCache, silenceListenerLog, tmuxArgs };
+export { liveSessionNames, sessionExists, sessionLiveness };
+export { detectRemoteAgent, isSubagentSessionName, recordSubagentTranscripts, recordTargets, subagentTranscriptFor, tmuxTargetFor };
+/**
+ * Parse a `hwip-*` tmux session name into `{project, label}`. The wrapper
+ * emits `hwip-<project>` and, with `--label <x>`, `hwip-<project>-<x>`; the
+ * name alone cannot tell where the project ends, so the whole tail is the
+ * project. A labelled or worktree session also carries the answer in session
+ * options (`@hwip_project`, `@hwip_session_label` — wrapper
+ * `sessionSidecarArgs`), which win: the phone groups cards by project, and
+ * the tail would open a card per label and per worktree.
+ */
+export declare const parseSessionName: (name: string, sidecar?: {
+    project?: string;
+    label?: string;
+}) => {
+    project: string;
+    label: string | null;
+} | null;
+/** Test seam: how many directories have been looked up. */
+export declare const __checkoutCacheSize: () => number;
+/** Test hook. */
+export declare const resetSessionStates: () => void;
+/**
+ * Fold one pane capture into the per-session state machine and return
+ * the wire fields for this report cycle. Exported (with `paneText`
+ * injected) so tests can drive it without tmux.
+ *
+ * Hash short-circuit: an unchanged screen skips rule evaluation but
+ * still replays the previous observation through the debounce — cheap
+ * cycles stay cheap without wedging candidate promotion.
+ */
+export declare const deriveSessionState: (name: string, agentKind: AgentKind, paneText: string | null, now?: number) => Pick<AgentSession, "state" | "stateChangedAt" | "stateRuleId">;
+/** Test hook. */
+export declare const setPromptSealer: (sealer: PromptSealer | null) => void;
+/**
+ * The sealed prompt of each main session blocked in a dialog this listener can
+ * read, added to a sweep's sessions before they are published. Here and not in
+ * the sweep: the sweep runs on the inventory worker (inventory-offload.ts), a
+ * module instance of its own where no sealer is ever set, so a prompt sealed
+ * there would never be. A blocked session's pane is captured once more for it;
+ * the others pass no pane, which forgets any prompt they showed. Subagent rows
+ * and shells are left alone: nothing on the phone answers for them.
+ */
+export declare const withBlockedPrompts: ({ sessions, targets }: Pick<CollectResult, "sessions" | "targets">) => AgentSession[];
+/** How long a report waits for a prompt seal that started on it. Seals take milliseconds; this bounds a stuck key lookup. */
+export declare const PROMPT_SEAL_WAIT_MS = 3000;
+/**
+ * `withBlockedPrompts`, held until the seals it started are done (at most `PROMPT_SEAL_WAIT_MS`), then read again. The
+ * server pushes on the first report that says blocked and the phone fetches the prompt for the push's buttons right
+ * then: a prompt that rides only the next report, five seconds on, comes after the notification was drawn without them.
+ */
+export declare const withSettledPrompts: (inventory: Pick<CollectResult, "sessions" | "targets">) => Promise<AgentSession[]>;
+export interface PatternWatch {
+    sessionName: string;
+    pattern: string;
+}
+/** Ack payload → active watch list. Prunes fired-markers for dead watches. */
+export declare const setPatternWatches: (raw: unknown) => void;
+/** Test hook. */
+export declare const resetPatternWatches: () => void;
+export interface WatchHit {
+    sessionName: string;
+    pattern: string;
+    matchedLine: string;
+}
+/**
+ * Probe every un-fired watch whose session is live. `capture` is
+ * injectable for tests; production passes capturePaneText.
+ */
+export declare const collectWatchHits: (liveNames: ReadonlySet<string>, capture?: (session: string) => string | null) => WatchHit[];
+export interface ScreenRequest {
+    subtype?: string;
+    targetDeviceId?: string;
+    sessionName?: string;
+    requestId?: string;
+    /** The requesting device, stamped by the relay from the sending connection
+     *  (server ws.ts, `ephemeral.send`) — which device's registered key
+     *  `subscriberPublicKey` has to be. Relay JSON like the rest. */
+    deviceId?: string;
+    /** Asks for a sealed snapshot: the requester's device public key. */
+    subscriberPublicKey?: string;
+    /** The requester's nonce for this request, sealed with the pane. */
+    subscriberNonce?: string;
+}
+type ScreenSnapshotHead = {
+    subtype: 'agent.screen.snapshot';
+    requestId: string;
+    sessionName: string;
+    capturedAt: string;
+};
+/**
+ * One answer to a screen request: the pane in the clear, the pane sealed, or
+ * why there is none. Each arm rules the other arms' fields out (`?: never`),
+ * so a reply carrying both a sealed pane and a plaintext one does not
+ * type-check — `ScreenSnapshotIsOneWay` below is that claim, compiled.
+ */
+export type ScreenSnapshot = ScreenSnapshotHead & ({
+    content: string;
+    truncated: boolean;
+    encrypted?: never;
+    error?: never;
+}
+/** Envelope of a SealedScreenSnapshot. */
+ | {
+    encrypted: SealedV2;
+    truncated: boolean;
+    content?: never;
+    error?: never;
+} | {
+    error: string;
+    content?: never;
+    truncated?: never;
+    encrypted?: never;
+});
+type MustBeTrue<T extends true> = T;
+/** Fails to compile the day a snapshot may carry the pane both ways, or beside an error. */
+export type ScreenSnapshotIsOneWay = MustBeTrue<(ScreenSnapshotHead & {
+    content: string;
+    truncated: boolean;
+    encrypted: SealedV2;
+} extends ScreenSnapshot ? false : true) | (ScreenSnapshotHead & {
+    error: string;
+    content: string;
+    truncated: boolean;
+} extends ScreenSnapshot ? false : true) | (ScreenSnapshotHead & {
+    error: string;
+    encrypted: SealedV2;
+    truncated: boolean;
+} extends ScreenSnapshot ? false : true)>;
+/** What a sealed snapshot's envelope holds (JSON): the pane, the request it
+ *  answers and when it was read — so a snapshot moved onto another request,
+ *  or another session's, or held back and delivered late, is not taken for
+ *  this one. */
+export type SealedScreenSnapshot = {
+    requestId: string;
+    sessionName: string;
+    nonce?: string;
+    capturedAt: string;
+    content: string;
+    truncated: boolean;
+};
+export declare const setSubscriberTrust: (trust: SubscriberTrust | null) => void;
+/**
+ * Answer a phone's screen-peek request for one of OUR sessions.
+ * Returns null when the message isn't addressed to this machine (other
+ * ephemeral traffic — clipboard, mirrors — flows through constantly).
+ *
+ * Security posture: only sessions the inventory already exposes are
+ * readable — the phone can see exactly the panes it can already send
+ * commands into, nothing else. Rate-limited with the same per-session
+ * token bucket as command injection.
+ *
+ * A request carrying a key gets the pane sealed for that key, and only when
+ * the key checks out (subscriber-trust.ts); a request without one gets it in
+ * the clear only while this listener has never sealed. Either refusal answers
+ * with an error and no pane, decided before the pane is read.
+ */
+export declare const handleScreenRequest: (req: ScreenRequest) => Promise<ScreenSnapshot | null>;
+/** What a diff request carries in the clear: the routing fields a relay needs,
+ *  and the key the answer is sealed for. What it ASKS — which base, which file,
+ *  which page — is inside `encrypted`, so the relay sees none of it. */
+export interface DiffRequest {
+    subtype?: string;
+    targetDeviceId?: string;
+    sessionName?: string;
+    requestId?: string;
+    /** The phone's device public key: the answer is sealed for it once it checked out. */
+    subscriberPublicKey?: string;
+    /** The asking device, stamped by the relay: whose registered key the one above has to be. */
+    deviceId?: string;
+    /** The request, sealed by the phone for this listener (purpose `session.diff`). */
+    encrypted?: unknown;
+}
+/** D6: how much file content each session has read in the current window (blob text pages only). */
+export declare const fileViewBytes: import("./file-view-budget.js").ByteBudget;
+export declare const handleDiffFilesRequest: (req: DiffRequest, send: (data: Record<string, unknown>) => void) => boolean;
+export declare const handleDiffFileRequest: (req: DiffRequest, send: (data: Record<string, unknown>) => void) => boolean;
+export declare const handleFileTreeRequest: (req: DiffRequest, send: (data: Record<string, unknown>) => void) => boolean;
+export declare const handleFileBlobRequest: (req: DiffRequest, send: (data: Record<string, unknown>) => void) => boolean;
+/** What a list request carries: routing and the key the answer is sealed for. It asks for nothing else, so there is nothing to seal. */
+export interface ScheduleListRequest {
+    subtype?: string;
+    targetDeviceId?: string;
+    requestId?: string;
+    subscriberPublicKey?: string;
+    /** The asking device, stamped by the relay: whose registered key the one above has to be. */
+    deviceId?: string;
+}
+/**
+ * Answer a phone's request for the schedules on this machine (F8). The list holds prompts, so it
+ * follows the screen's rule: a request with a key gets it sealed once the key checks out (the seal
+ * is bound to this machine's device id), one without gets it in the clear only while this listener
+ * has never sealed, and any other outcome is an error and no schedule. A request that asked for a
+ * seal is never answered in the clear. Directories and agent arguments are not in the list at all.
+ */
+export declare const handleScheduleListRequest: (req: ScheduleListRequest, send: (data: Record<string, unknown>) => void) => boolean;
+export interface SessionResumeRequest {
+    subtype?: string;
+    targetDeviceId?: string;
+    sessionName?: string;
+    /**
+     * Which run of that name to start, when the slot has held more than one
+     * agent. Not authority the phone gains: it selects among runs THIS machine
+     * recorded, and a kind that matches nothing falls back to the newest run —
+     * the same answer a phone too old to send it gets.
+     */
+    agentKind?: string;
+    requestId?: string;
+}
+export interface SessionResumeResult {
+    subtype: 'agent.session.resume.result';
+    requestId: string;
+    sessionName: string;
+    resumed?: true;
+    error?: string;
+    at: string;
+}
+/**
+ * Start a remembered session again, detached, and tell the phone what happened.
+ * Returns true when the message was ours to answer.
+ *
+ * The refusals are the design. Unknown name: not in the registry, so there is
+ * nothing to start and nothing to guess from. Missing directory: the project
+ * moved or was deleted, and starting an agent in the wrong place is worse than
+ * not starting one. Unknown agent kind: the record names an agent this build
+ * has no binary for — a wire enum outlives installs, and a guess here would be
+ * a command nobody chose. Already running: the session is live and the phone
+ * should be watching it, not replacing it.
+ */
+export declare const handleSessionResumeRequest: (req: SessionResumeRequest, send: (data: Record<string, unknown>) => void) => boolean;
+export interface SessionExitRequest {
+    subtype?: string;
+    targetDeviceId?: string;
+    sessionName?: string;
+    requestId?: string;
+}
+export interface SessionExitResult {
+    subtype: 'agent.session.exit.result';
+    requestId: string;
+    sessionName: string;
+    exited?: true;
+    error?: string;
+    at: string;
+}
+/** Time given to each signal before the next one is tried. */
+export declare const SESSION_EXIT_STEP_MS = 1500;
+/**
+ * Ask a session to end, and report whether it did.
+ *
+ * Answers late on purpose: the whole point is to let the agent wind itself
+ * down, so the reply has to wait long enough to know whether it did. A session
+ * that is still there when the signals run out is reported as still there
+ * rather than forced — "I asked and it refused" is a true answer, and a phone
+ * that can silently destroy a working agent is a worse thing to have built.
+ */
+export declare const handleSessionExitRequest: (req: SessionExitRequest, send: (data: Record<string, unknown>) => void) => boolean;
+export interface SessionForgetRequest {
+    subtype?: string;
+    targetDeviceId?: string;
+    sessionName?: string;
+    /** Which run of that name to delete. A name can hold one run per agent, and
+     *  the phone deletes the row it is looking at. Absent (older phone) deletes
+     *  every run under the name, which is what the request used to mean. */
+    agentKind?: string;
+    requestId?: string;
+}
+export interface SessionForgetResult {
+    subtype: 'agent.session.forget.result';
+    requestId: string;
+    sessionName: string;
+    forgotten?: true;
+    /**
+     * Set when the record went but the chat scrollback file would not delete.
+     * The session is no longer resumable either way; this says the prompts and
+     * tool targets it collected are still on the machine, which a flat
+     * `forgotten: true` would have claimed otherwise.
+     */
+    scrollbackKept?: true;
+    error?: string;
+    at: string;
+}
+/**
+ * Delete one ended session from this machine's record, and say what happened.
+ * Returns true when the message was ours to answer.
+ *
+ * The mirror of resume, and destructive where that one is constructive: it
+ * takes the entry out of the registry, which is the same file resume reads its
+ * whitelist from. After this the session is neither offered nor startable, and
+ * nothing puts it back — `rememberSessions` only writes down sessions that are
+ * running, so only actually running that name again restores it.
+ *
+ * The refusals: unknown name is nothing to delete rather than something to
+ * guess at. Still running means it is not a past session at all — the phone is
+ * looking at a live one, and ending it is a different request that this must
+ * not quietly stand in for.
+ */
+export declare const handleSessionForgetRequest: (req: SessionForgetRequest, send: (data: Record<string, unknown>) => void) => boolean;
+/** Ceiling on one page. A page past the frame limit arrives truncated anyway,
+ *  so let the caller ask for less rather than pay for a capture we discard. */
+export declare const SCREEN_HISTORY_MAX_LINES = 200;
+export interface ScreenHistoryRequest {
+    subtype?: string;
+    targetDeviceId?: string;
+    /** The requesting device, stamped by the relay: which of the session's viewers is asking. */
+    deviceId?: string;
+    sessionName?: string;
+    requestId?: string;
+    /**
+     * How many lines of scrollback the caller already holds above the visible
+     * pane — the `historyLines` of its newest frame plus every history line it
+     * has pulled since. 0 asks for the page directly above the visible pane.
+     *
+     * The caller says this rather than the daemon assuming STREAM_CAPTURE_LINES,
+     * because the byte cap trims frames from the top and a caller holding fewer
+     * lines than the capture asked for would otherwise be handed a page that
+     * starts above its own content, with the gap unreachable forever after.
+     * Absent falls back to the constant — the untruncated case.
+     */
+    before?: number;
+    /** Page size. Clamped to SCREEN_HISTORY_MAX_LINES. */
+    lines?: number;
+}
+export interface ScreenHistorySnapshot {
+    subtype: 'agent.screen.history.snapshot';
+    requestId: string;
+    sessionName: string;
+    content?: string;
+    /** Echo of the request's offset, so a caller with several pages in flight
+     *  can tell which one this is. */
+    before?: number;
+    /** Lines actually returned — what the caller adds to `before` for the next
+     *  page. Smaller than asked when the payload cap trimmed the page. */
+    lines?: number;
+    /** Whether older lines still exist above this page. */
+    hasMore?: boolean;
+    truncated?: boolean;
+    /** The page sealed for the stream's subscriber (envelope v2
+     *  `screen.history`, bound to the session) — present INSTEAD of `content`
+     *  whenever the stream it belongs to is encrypted. */
+    encrypted?: SealedV2;
+    error?: string;
+    capturedAt: string;
+}
+/**
+ * Answer a phone's request for one page of scrollback above the live window.
+ * Returns true when the message was ours to answer, so the caller stops routing
+ * it; the reply goes out through `send`, after the seal when there is one.
+ *
+ * Same security posture as the one-shot peek it sits beside — addressed to this
+ * machine, only for sessions the inventory already exposes, charged to the same
+ * per-session token bucket, and reading the pane through tmux and nothing else —
+ * plus one the peek does not have: it answers ONLY under a live stream lease.
+ * That is what makes E2EE possible here. History is the same pane text the
+ * frames carry, so on an encrypted stream it is sealed for the same subscriber
+ * key and never falls back to plaintext; without a lease there is no key to
+ * seal for, and a pull that answered anyway would be the downgrade the stream
+ * half refuses.
+ */
+export declare const handleScreenHistoryRequest: (req: ScreenHistoryRequest, send: (data: Record<string, unknown>) => void) => boolean;
+/**
+ * One stream tick's read of the pane: the capture and where the cursor sits,
+ * in ONE tmux spawn (C18 — the tick runs every 120–400 ms).
+ *
+ * `capture-pane` gives cells and colors but no cursor, so the mirror has never
+ * drawn one — which makes an arrow key indistinguishable from a dropped one.
+ * tmux reports the position separately; `pane_height` is what turns a
+ * pane-relative row into a row of the captured text, since the capture reaches
+ * back into scrollback and the visible pane is only its last `pane_height`
+ * lines. `history_size` tells the viewer how deep the buffer under that window
+ * is. `display-message ; capture-pane` runs the two as consecutive commands in
+ * one client: the first output line is the geometry, the rest is the capture.
+ */
+export declare const STREAM_GEOMETRY_FORMAT = "#{cursor_x},#{cursor_y},#{pane_height},#{history_size}";
+export interface PaneGeometry {
+    x: number;
+    y: number;
+    height: number;
+    /** Lines of scrollback the pane holds above the visible rows. Tells the
+     *  viewer where this frame's window sits in the buffer, which is what lets
+     *  it record the lines that scroll past without matching text. Absent when
+     *  tmux did not answer with a usable number. */
+    historySize?: number;
+}
+/**
+ * Read the one tmux answer the frame path already asks for per tick.
+ *
+ * The depth is parsed separately from the cursor on purpose: a tmux that does
+ * not report `history_size` still reports the cursor, and refusing the whole
+ * answer over the missing field would cost every frame its cursor — a
+ * regression in exchange for a feature.
+ */
+export declare const parsePaneGeometry: (raw: string) => PaneGeometry | null;
+/**
+ * Translate the cursor into an index into the lines the frame carries.
+ *
+ * The visible pane is the tail of the capture, so the cursor's row counts back
+ * from the end — which also makes this correct after the byte cap has cut lines
+ * off the top. A cursor that falls outside what the frame carries returns null
+ * and simply is not drawn.
+ */
+export declare const cursorLineFor: (content: string, cursor: {
+    x: number;
+    y: number;
+    height: number;
+}) => {
+    line: number;
+    col: number;
+} | null;
+/**
+ * How many of a frame's lines are scrollback rather than the visible pane.
+ *
+ * This is the number the viewer hands back as `before` when it asks for
+ * history. STREAM_CAPTURE_LINES is only what the capture ASKED for: the byte
+ * cap trims from the top, and a coloured TUI pane hits that cap routinely, so
+ * assuming the viewer holds the full window would start the first history page
+ * above what it actually has — leaving a gap no later page can reach, since
+ * every later page walks further up.
+ */
+export declare const historyLinesIn: (content: string, paneHeight: number) => number;
+/**
+ * After the phone injects keys, push fresh frames instead of waiting for its
+ * next screen request — the phone's post-tap re-pull raced the key landing
+ * (its timer starts at tap time, the key lands a REST+WS hop later), so it
+ * often re-captured the pre-keypress screen and the next update was a full
+ * auto-refresh period away. Unsolicited frames carry no requestId; the phone
+ * matches them by deviceId + sessionName. A newer tap cancels pending
+ * captures so a burst of arrow presses yields frames after the LAST press.
+ */
+export declare const scheduleInjectSnapshots: (sessionName: string, send: (data: Record<string, unknown>) => void, delays?: number[]) => void;
+export interface StreamControl {
+    subtype?: string;
+    targetDeviceId?: string;
+    sessionName?: string;
+    /** Subscriber's device public key (Base64 SPKI) — presence turns on E2EE. */
+    subscriberPublicKey?: string;
+    /** The subscribing device, stamped by the relay: whose registered key the
+     *  one above has to be before a frame is sealed for it. */
+    deviceId?: string;
+    /**
+     * Subscriber's nonce for this subscription, sealed into every frame with
+     * the session and the capture stamp. The viewer checks all of them, so a
+     * relay cannot move a sealed frame to another stream or replay one from an
+     * earlier subscription. Ignored unless a short string (MAX_NONCE_LENGTH).
+     */
+    subscriberNonce?: string;
+    /**
+     * On a renew: the viewer's fresh random word, sealed back in the answer
+     * with the last frame sent (`agent.stream.renew.ok` `encrypted`). A relay
+     * cannot make that answer, or replay an old one, so a "live" badge kept
+     * up by renews says the listener is there — and its `seq` says whether
+     * frames were dropped on the way. Ignored unless a short string.
+     */
+    challenge?: unknown;
+    /**
+     * Subscriber promises to send `agent.stream.renew` while it's watching.
+     * Only such a subscriber gets the short lease; clients that predate the
+     * renew protocol keep the 5-minute orphan guard (see STREAM_LEASE_MS).
+     */
+    renew?: boolean;
+    /**
+     * How many terminal columns the viewer shows (on start and every renew).
+     * A detached, unsplit window is resized to it while watched — see
+     * pane-fit.ts. Absent from viewers that predate it: nothing is resized.
+     */
+    cols?: number;
+}
+export declare const STREAM_CAPTURE_LINES = 200;
+export declare const STREAM_INTERVAL_MS = 400;
+export declare const BURST_INTERVAL_MS = 120;
+export declare const BURST_WINDOW_MS = 2500;
+export declare const MAX_FRAMES_PER_SEC = 8;
+/**
+ * Delay before the next capture: burst while the last input is still echoing,
+ * idle otherwise. Exclusive at the boundary — exactly BURST_WINDOW_MS after
+ * the input is already idle, so the window can't stretch. A lastInputAt in the
+ * future (wall-clock jump) reads as fresh input rather than as an expired
+ * window: bursting is the recoverable side of that.
+ */
+export declare const streamCadence: (lastInputAt: number | null, now: number) => number;
+/** Rolling one-second send budget for a single stream. */
+export interface FrameBudget {
+    windowStartedAt: number;
+    sent: number;
+}
+/**
+ * Claim one send from the budget, rolling the window over when the second has
+ * passed. False means this tick must skip WITHOUT marking the frame as sent —
+ * the diff-gate would otherwise swallow that content for good.
+ */
+/** Is there budget left this second? A peek, so a tick can decline to pay for a
+ *  blocking capture it could not send anyway — spending the token here instead
+ *  would burn budget on ticks the diff-gate goes on to skip. */
+export declare const hasFrameBudget: (budget: FrameBudget, now: number) => boolean;
+export declare const claimFrameSend: (budget: FrameBudget, now: number) => boolean;
+export declare const STREAM_LEASE_MS = 15000;
+export declare const STREAM_RENEW_FRESH_MS = 8000;
+export declare const MAX_CONCURRENT_STREAMS = 3;
+/**
+ * The transcript a live chat watch should follow for one session name.
+ *
+ * Exported because the two branches here are where a subagent watch lives or
+ * dies, and a test that only reached the module's maps would pass while this
+ * asked tmux about a name tmux cannot parse.
+ */
+export declare const resolveWatchTranscript: (sessionName: string, onMiss?: (reason: string) => void) => TranscriptSource | null;
+/** One chat-timeline batch, sealed for the watcher and bound to its session. */
+export declare const sealTurnBatch: (plaintext: string, subscriberPublicKey: string, sessionName: string) => Promise<SealedV2>;
+/**
+ * Route a chat-timeline control message. A start is a request for the
+ * transcript, so it passes the same door as every other request for content
+ * (subscriber-trust.ts): one that asks for sealed batches waits for its key to
+ * check out, like a stream start, and one without a key is refused once this
+ * listener only seals. Everything else goes straight to the watchers.
+ */
+export declare const handleTurnWatch: (req: TurnWatchControl & {
+    deviceId?: string;
+}, send: SendTurnFrame) => boolean;
+/**
+ * Stop one viewer's stream: the (session, device) slot. The session's pane is handed back (width,
+ * input counters) only when it was the last viewer.
+ *
+ * `keepFit` is for the restart inside a start: the same viewer is subscribing
+ * again, and handing the window back only to shrink it a moment later would
+ * make the program redraw twice.
+ */
+export declare const stopStreamOf: (sessionName: string, deviceId: string | undefined, { keepFit }?: {
+    keepFit?: boolean;
+}) => void;
+/** Stop every viewer of a session. */
+export declare const stopStream: (sessionName: string, opts?: {
+    keepFit?: boolean;
+}) => void;
+export declare const stopAllStreams: () => void;
+/** Wire shape of one live-mirror data frame (before the relay's ephemeral wrap). */
+export type StreamFramePayload = {
+    subtype: 'agent.stream.frame';
+    sessionName: string;
+    capturedAt: string;
+    truncated: boolean;
+    /** Capture-order stamp — attached at send time; a sealed frame gets it from
+     *  buildStreamFrame too, and inside its envelope (SealedStreamFrame). */
+    seq?: number;
+    /** Stream incarnation (stats.startedAt) — lets the receiver reset its
+     *  seq high-water mark when the daemon restarts the stream. */
+    epoch?: number;
+    /** Where to draw the cursor: a 0-based index into the lines this frame
+     *  carries, and a 0-based CELL column (not a string index — a wide glyph
+     *  spans two cells, which is what the viewer positions by). Absent when the
+     *  cursor is outside the captured region. Kept in the clear for unsealed
+     *  streams and routing; a sealed frame carries the same values inside its
+     *  envelope (SealedStreamFrame), and a viewer of a sealed stream draws the
+     *  cursor, like the lines, only from there — the relay can rewrite these. */
+    cursorLine?: number;
+    cursorCol?: number;
+    /** How many of this frame's lines are scrollback rather than the visible
+     *  pane — what the viewer sends back as `before` when it pulls history.
+     *  Fewer than STREAM_CAPTURE_LINES whenever the byte cap trimmed the frame,
+     *  which is exactly the case a constant would get wrong. Absent when the
+     *  pane geometry could not be read; the viewer then falls back to the
+     *  constant. In the clear as the cursor is, and sealed the same way. */
+    historyLines?: number;
+    /** How much scrollback the PANE holds above its visible rows — the depth
+     *  this frame's window sits in, where `historyLines` is only the slice of
+     *  it the frame carries. Together they place the frame's top edge in the
+     *  buffer, which is what lets a viewer record the lines that scroll past
+     *  without matching text (a redrawing TUI defeats text matching), and lets
+     *  it see the buffer being cleared as the depth dropping. Absent when tmux
+     *  would not say. In the clear as the cursor is, and sealed the same way. */
+    historySize?: number;
+    /** Plaintext pane content — only on unencrypted streams. */
+    content?: string;
+    /** Envelope v2 (`stream.frame`, context = session) of a SealedStreamFrame —
+     *  replaces `content` on encrypted streams. */
+    encrypted?: SealedV2;
+};
+/**
+ * What a sealed frame's envelope holds (as JSON): the pane with everything a
+ * viewer draws from it, and the stamps the relay also sees in the clear plus
+ * the subscriber's nonce. The cleartext fields stay for routing and ordering;
+ * a viewer of a sealed stream trusts only these. What it is (a frame, not
+ * input or a snapshot) is the envelope's purpose, part of its key.
+ */
+export type SealedStreamFrame = {
+    sessionName: string;
+    seq?: number;
+    epoch?: number;
+    nonce?: string;
+    content: string;
+    truncated: boolean;
+    cursorLine?: number;
+    cursorCol?: number;
+    historyLines?: number;
+    historySize?: number;
+};
+/**
+ * Plaintext bytes of a sealed frame's JSON. Sealing base64-expands it by 4/3
+ * and the envelope and cleartext fields add about 1KB, so 20KB stays under API
+ * Gateway's 32KB WebSocket frame. Tighter than SCREEN_PEEK_MAX_BYTES because
+ * JSON escapes a `-e` capture's ESC bytes six-fold (`\u001b`).
+ */
+export declare const SEALED_FRAME_MAX_BYTES: number;
+/**
+ * Trim a sealed frame from the TOP until its JSON fits SEALED_FRAME_MAX_BYTES,
+ * as capToFrameLimit does for the capture. The cursor line and the scrollback
+ * count both count from the frame's first line, so each drops by the lines cut.
+ */
+export declare const fitSealedFrame: (frame: SealedStreamFrame, maxBytes?: number) => SealedStreamFrame;
+/** Wire shape of a live-mirror error frame — same subtype, no pane data.
+ *  `input_rejected` refuses an ephemeral `agent.command.input`; it rides this
+ *  frame so a viewer already handling stream errors can fall back to the REST
+ *  push path without a second error channel. */
+export type StreamErrorFrame = {
+    subtype: 'agent.stream.frame';
+    sessionName: string;
+    error: 'unknown_session' | 'e2ee_unavailable' | 'encrypt_failed' | 'stream_limit' | 'stream_gone' | 'input_rejected' | RefusalCode;
+    /** `input_rejected` only: the refused message's ordering stamp echoed back.
+     *  A sender with several keystrokes in flight can't tell which one was
+     *  refused without it. Absent when the message carried no usable stamp. */
+    seq?: number;
+    epoch?: number;
+    /** `input_rejected` only: the refused sender's deviceId, echoed so a second
+     *  device whose (seq, epoch) happens to collide doesn't claim the refusal
+     *  and fire a REST resend for an input that was never refused. */
+    inputDeviceId?: string;
+    /** `input_rejected` only, and only when one of this listener's checks refused
+     *  the input (command-refusal.ts codes). Absent when the lease was simply
+     *  gone or the message never got that far. A sealed sender never falls back to
+     *  REST, so this is the only place it hears why. */
+    reason?: CommandRefusal;
+};
+/**
+ * Per-listener concurrency guard, as a pure predicate so the boundary is
+ * unit-testable without touching the module-scope `activeStreams` map.
+ */
+export declare const isStreamCapReached: (activeCount: number) => boolean;
+/**
+ * Build the wire payload for one stream frame. With a subscriber public key
+ * the pane content rides ONLY inside the E2EE envelope; an encrypt failure
+ * (bad key, crypto not ready on the first tick) returns null so the caller
+ * drops the frame — an encrypted stream never leaks a plaintext frame.
+ */
+export declare const buildStreamFrame: (captured: {
+    content: string;
+    truncated: boolean;
+}, sessionName: string, subscriberPublicKey?: string, meta?: {
+    cursor?: {
+        line: number;
+        col: number;
+    } | null;
+    historyLines?: number;
+    historySize?: number;
+}, 
+/** Capture stamp and subscription nonce, sealed with the pane. A sealed
+ *  frame without it is dropped: the viewer could not check it. */
+stamp?: {
+    seq: number;
+    epoch: number;
+    nonce?: string;
+}) => Promise<StreamFramePayload | null>;
+/**
+ * Handle agent.stream.start / agent.stream.stop. Returns true when the message
+ * was a stream-control message (so the caller skips the one-shot screen-peek
+ * path). start is idempotent — a repeat restarts the loop.
+ */
+export declare const handleStreamControl: (req: StreamControl, send: (data: Record<string, unknown>) => void) => boolean;
+/** Wire shape of one inbound injection. Every field is optional, and none of
+ *  them is proven: this shape is an unchecked cast over relay JSON, so
+ *  validateInputMessage re-checks the types it acts on rather than trusting
+ *  the declaration. */
+export interface AgentCommandInput {
+    subtype?: string;
+    targetDeviceId?: string;
+    sessionName?: string;
+    /** Which device's seq/epoch run this is. Current relays stamp it from the
+     *  sending connection unconditionally; relays older than that overwrite
+     *  only a missing value, so a sender there can claim another device's id.
+     *  Treat it as an ordering namespace, never as authentication — the worst
+     *  a forged id buys is a different reorder lane for its own keystrokes. */
+    deviceId?: string;
+    /** Named keys, ALLOWED_KEYS-validated. Mutually exclusive with `body`/`insert`. */
+    keys?: string[];
+    /** Literal text; the injector appends the Enter, as on the REST path. */
+    body?: string;
+    /**
+     * Literal text delivered WITHOUT the submitting Enter — the phone
+     * answering a y/n prompt, or typing half a command so a TUI menu opens.
+     *
+     * A separate field rather than a `submit: false` flag on `body`, and that
+     * is the whole point: a daemon too old to know this field sees no `body`
+     * either, so it injects nothing. The flag spelling would have had the old
+     * daemon submit text the user never meant to send.
+     */
+    insert?: string;
+    /** Sender's monotonic counter, and the incarnation it counts within. */
+    seq?: number;
+    epoch?: number;
+    /** Type this only while the pane still shows the blocked prompt with this
+     *  id (`blockedPrompt.id` in the session report); otherwise refuse with
+     *  `prompt_changed`. A sealed message reads it from inside the envelope: this
+     *  plaintext field is not looked at beside one. */
+    ifPrompt?: string;
+    /** E2EE envelope sealing `{ keys | body }` plus a copy of the
+     *  `sessionName`/`seq`/`epoch` stamp as JSON — the only way in on an
+     *  encrypted stream, where `keys`/`body` above are refused. Present means
+     *  the plaintext pair is ignored entirely: on a message the relay can
+     *  append to, only the ciphertext decides what gets typed, and the sealed
+     *  stamp is what proves the plaintext one was not re-written for a replay. */
+    encrypted?: unknown;
+}
+/** Parity with the REST path, which refuses more than MAX_KEYS_PER_COMMAND per
+ *  agent.command (hwip apps/server/src/functions/pushes.ts). The lower-latency
+ *  door into the same pane must not also be the wider one. */
+export declare const MAX_INPUT_KEYS = 10;
+/** The REST path caps no body length, so this bound is ours alone: an
+ *  unbounded body is one tmux send-keys argv of unbounded size, and what it
+ *  lands in is an agent prompt, not a paste buffer. */
+export declare const MAX_INPUT_BODY_CHARS = 4096;
+/** The relay socket a message arrived on, and the only way back to its sender. */
+type SendEphemeral = (data: Record<string, unknown>) => void;
+/** One validated injection. */
+type ValidatedInput = SequencedInput & {
+    sessionName: string;
+    /** The blocked prompt this input answers; checked against a fresh capture at delivery. */
+    ifPrompt?: string;
+    /** Sender's device, when the relay stamped one — rides along so a refusal
+     *  frame can name whose input was refused (inputDeviceId). */
+    deviceId?: string;
+    /** Exactly one of these is set. */
+    tokens: string[] | null;
+    text: string | null;
+    /** Whether `text` carries its own submit. False for `insert` (and, vacuously,
+     *  for a key batch — the keys say for themselves what they are). */
+    submit: boolean;
+};
+type InputCheck = {
+    ok: true;
+    input: ValidatedInput;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Parse and whitelist an inbound input message. Pure — the lease gate and the
+ * tmux-side guards stay in the caller, so this is testable on its own.
+ */
+export declare const validateInputMessage: (msg: AgentCommandInput) => InputCheck;
+/** Ceiling on concurrent sender lanes. The lane key includes a relay-stamped
+ *  deviceId, but a relay older than the unconditional stamp lets a sender vary
+ *  it per message — without a cap that grows the map for the lease's whole
+ *  life. Real senders are one per device; 16 is generous. */
+export declare const MAX_INPUT_LANES = 16;
+/** Ceiling on queued decrypts. The subscriber-key binding is a string compare
+ *  against a public key the relay fanned out to every same-account connection,
+ *  so it gates WHO can enqueue an ECDH derive, not how many — a flooding
+ *  client would otherwise grow the chain without bound. Mirrors
+ *  MAX_PENDING_INPUTS' role on the plaintext side. */
+export declare const MAX_PENDING_DECRYPTS = 32;
+/** Resolves once every encrypted input accepted so far has been routed. */
+export declare const pendingInputDecrypts: () => Promise<void>;
+/**
+ * Handle agent.command.input. Returns true when the message was ours to
+ * answer, so the caller stops routing it. Encrypted messages finish
+ * asynchronously — the return value reports routing, not delivery, exactly as
+ * it already did for a message the sequencer holds.
+ */
+export declare const handleCommandInput: (msg: AgentCommandInput, send: SendEphemeral) => boolean;
+export interface CollectResult {
+    sessions: AgentSession[];
+    /** Diagnostic notes per rejected session — surfaced under `--verbose`. */
+    rejected: Array<{
+        name: string;
+        reason: string;
+    }>;
+    /** Local knowledge, NOT on the wire: every live session/subagent name →
+     *  the pane id every `-t` call for it must use (`tmuxTargetFor`). The main
+     *  thread stores it beside the snapshot (`recordTargets`). */
+    targets: Record<string, string>;
+    /** Also local: in-process subagent name → its transcript file. The sweep may
+     *  run on a worker, so a map built there has to travel back like `targets`
+     *  rather than live in module state the main thread cannot see. */
+    subagentTranscripts: Record<string, string>;
+    /** Also local, for the always-on recorder (`turn-recorder.ts`): main session
+     *  name → the transcript it writes and the agent kind whose projector reads
+     *  it. Only sessions this machine can actually read; no subagent rows. */
+    recordable: Record<string, RecordableSession>;
+}
+/**
+ * Inventory pass that also records *why* each `hwip-*` session was
+ * skipped. The verbose log uses the rejection notes to explain empty
+ * pickers (most common cause: tmux pane lost its start_command after a
+ * re-attach, and the current command is `node` rather than `claude`).
+ */
+export declare const collectSessionsVerbose: () => CollectResult;
+export declare const recordInventory: (sessions: ReadonlyArray<{
+    name: string;
+}> | null) => void;
+export declare const syncTmuxAgentNames: (sessions: ReadonlyArray<AgentSession>) => void;
+/**
+ * Is this session in the inventory? Answered from the last sweep when it can
+ * be: a full sweep is two tmux spawns per session on this thread, and it used
+ * to run again on every stream start and screen request (12% of daemon wall
+ * time, measured 2026-08-26). A miss still sweeps, so a session
+ * younger than one poll interval is not refused, and the inventory filter stays
+ * the security boundary: only hwip-* panes running an agent are reachable.
+ */
+export declare const isInventoried: (sessionName: string) => boolean;
+/**
+ * One file riding on a push — `libs/shared` `PushFileAttachment`, the
+ * fields this daemon reads.
+ *
+ * `agent.command` attachments are uploaded in *plaintext* (the phone has no
+ * key for this host's scratch space); an encrypted one is skipped there. A
+ * `type: 'file'` push is the opposite: encrypted per device, and this
+ * machine opens its own `deviceKeyMap` slot (ADR-0007). `lanDeliveredTo`
+ * marks bytes that never went to S3 — handed straight to that device over
+ * the LAN (ADR-0013) — so there is no `fileKey` to fetch.
+ */
+interface PushFileAttachment {
+    fileKey?: string;
+    fileName: string;
+    fileType?: string;
+    fileSize?: number;
+    iv?: string;
+    /** Legacy account-key wrap — nothing here can open it. */
+    encryptedKey?: string;
+    /** deviceId → JSON `{ encryptedKey, keyIv }` (per-device wrap). */
+    deviceKeyMap?: Record<string, string>;
+    lanDeliveredTo?: string;
+    transferId?: string;
+}
+interface PushItem {
+    pushId: string;
+    type?: string;
+    body?: string;
+    title?: string;
+    createdAt?: string;
+    isEncrypted?: boolean;
+    senderDeviceId?: string;
+    targetDeviceId?: string;
+    /** E2E: the sender's per-device public key, needed to open our slot. */
+    senderPublicKey?: string;
+    /** E2E: per-device wrapped message key for the push body. */
+    deviceKeyMap?: Record<string, string>;
+    /** Set when type='agent.command' — tmux session name to inject into. */
+    agentSessionName?: string;
+    /** Named keys (Esc/arrows/Enter) to inject instead of body text —
+     *  drives full-screen modals the phone can't escape with text. */
+    keys?: string[];
+    /** Literal text delivered WITHOUT the submitting Enter (see the same field
+     *  on AgentCommandInput for why it is a field and not a flag). */
+    insert?: string;
+    /** Type this only while the pane still shows the blocked prompt with this
+     *  id (`blockedPrompt.id`); otherwise refuse with `prompt_changed`. */
+    ifPrompt?: string;
+    /** Attachments: plaintext scratch files on `agent.command`, the delivered
+     *  file(s) on `type: 'file'`. */
+    files?: PushFileAttachment[];
+    /** A schedule request (F8): create or remove. On a sealed push the relay's copy is `{ op }` and the sealed
+     *  body holds the rest; `handlePushInner` swaps the sealed one in before anything reads it. */
+    schedule?: unknown;
+}
+interface HandlePushDeps {
+    paneProbe?: (session: string) => PaneProbe | null;
+    /** The pane's current text, for the `ifPrompt` check; defaults to a tmux capture. */
+    capturePane?: (session: string) => string | null;
+    /** Audit sink for input admitted into a marked shell; defaults to the state-dir log. */
+    shellAudit?: (entry: ShellAuditEntry) => boolean;
+    inject?: (session: string, text: string) => boolean;
+    /** Paste-only sibling of `inject` — text without the submitting Enter. */
+    insertText?: (session: string, text: string) => boolean;
+    sendKeys?: (session: string, tokens: string[]) => boolean;
+    rateLimit?: (session: string, now?: number, cost?: number) => boolean;
+    now?: () => number;
+    /** Injectable for tests; defaults to the REST-backed downloader. */
+    downloadAttachments?: (pushId: string, files: PushFileAttachment[], sealed?: SealedAttachments) => Promise<string[]>;
+    /** `type: 'file'` delivery: fetch, decrypt and save one attachment into
+     *  `~/Downloads/Hwip/`; resolves with the path written, or null when the
+     *  file was not wrapped for this device. Defaults to the streaming S3
+     *  downloader. */
+    /** `sealedSize`: the real size the sealed body gives (the bytes are padded
+     *  to it); absent for a file whose record is all there is. */
+    saveFile?: (push: PushItem, file: PushFileAttachment, sealedSize?: number, chunk?: number) => Promise<string | null>;
+    /** Move a finished local transfer out of the landing zone into
+     *  `~/Downloads/Hwip/`; null when it is not there. Defaults to the
+     *  filesystem move under `~/.hwip/attachments/lan`. */
+    claimLanFile?: (file: PushFileAttachment, sealedSize?: number) => Promise<string | null>;
+    /** Desktop banner after a save. Defaults to osascript / notify-send. */
+    notify?: (note: DesktopNotification) => Promise<boolean>;
+    /** This machine's device id — what `targetDeviceId` and `deviceKeyMap` are keyed by. */
+    deviceId?: () => string;
+    /** Pane cwd lookup for the remote-origin marker (ADR-0002). */
+    paneCwd?: (session: string) => string | null;
+    /** Fired after a successful named-key injection so the WS loop can push
+     *  fresh screen frames to the phone (scheduleInjectSnapshots). */
+    onKeysInjected?: (session: string) => void;
+    /** Why a command was refused — called at the refusal point, before the
+     *  `false` returns. The first call wins (see `handlePush`). */
+    noteRefusal?: (reason: CommandRefusal) => void;
+    /** An addressed command was refused: tell the phone (command-refusal.ts). */
+    reportRefusal?: (refusal: {
+        sessionName: string;
+        pushId: string;
+        reason: CommandRefusal;
+    }) => void;
+    /** What a schedule request reads and writes; defaults to this machine's registry and schedule files. */
+    schedule?: PhoneScheduleDeps;
+}
+/**
+ * Record a successful phone→pane text injection so a prompt-submit hook
+ * (Claude Code plugin's hwip-remote.sh, or `hwip remote-hook` for
+ * Gemini/Codex) can flag the matching prompt as remote-originated and
+ * enter sticky REMOTE mode (ADR-0002). One file per project dir,
+ * overwritten on every inject; the hook consumes it on an exact-text match.
+ * Best-effort: a write failure must never fail the injection itself.
+ */
+export declare const writeRemoteMarker: (paneCwd: string, text: string, now?: () => number) => boolean;
+/**
+ * Why text may not go into a marked shell, or null when it may. A shell runs
+ * what it reads, so the rules the agent prompt never needed apply here:
+ * attachment paths would arrive as lines of their own, each a command; ESC and
+ * other control bytes, C1 included, can leave a bracketed paste or drive the
+ * line editor;
+ * and an insert must not carry a newline, which a shell without bracketed
+ * paste (macOS `/bin/bash` 3.2, `dash`) would run.
+ */
+export declare const shellTextRefusal: (text: string, opts: {
+    submit: boolean;
+    files?: boolean;
+}) => string | null;
+export declare const setAttachmentContext: (ctx: {
+    apiKey: string;
+    baseUrl: string;
+}) => void;
+/** Test seam for the command-attachment downloads; production uses the defaults. */
+export interface AttachmentIo {
+    fetchFn?: typeof fetch;
+    timeoutMs?: number;
+}
+/** The attachments of a sealed command: opened with this device's slot of
+ *  each file, from the sender whose key checked out. */
+export interface SealedAttachments {
+    deviceId: string;
+    senderPublicKey: string;
+    /** What the sealed body says each attachment is, in the same order. */
+    files?: SealedFileMeta[];
+}
+/**
+ * Download every attachment to `~/.hwip/attachments/<pushId>/<fileName>` and
+ * return absolute paths. Files are kept (not deleted) so the agent can read
+ * them after injection.
+ *
+ * A plaintext command's attachments are best effort: an encrypted file is
+ * skipped (no key) and one file's failure is logged and skipped, so a
+ * partial download still injects whatever succeeded. A sealed command's
+ * (`sealed`) are all or nothing: each must open with this machine's slot,
+ * and the first that does not throws — half a command is not typed.
+ */
+export declare const downloadAttachments: (pushId: string, files: PushFileAttachment[], ctx: {
+    apiKey: string;
+    baseUrl: string;
+}, sealed?: SealedAttachments, io?: AttachmentIo) => Promise<string[]>;
+export interface SaveFileDeps {
+    ctx: {
+        apiKey: string;
+        baseUrl: string;
+    } | null;
+    fetchFn: typeof fetch;
+    deviceId: () => string;
+    downloadsDir: () => string;
+    idleTimeoutMs?: number;
+}
+/**
+ * Fetch one attachment and save it under `~/Downloads/Hwip/`, decrypting
+ * with this device's `deviceKeyMap` slot when the file is encrypted.
+ * Resolves with the path written; null when the file is encrypted for
+ * other devices only (a broadcast this machine is not a recipient of —
+ * not a failure); throws when the bytes cannot be fetched or opened.
+ * Exported with its deps so the real path is testable without S3.
+ */
+export declare const saveFileFromS3: (push: PushItem, file: PushFileAttachment, deps: SaveFileDeps, 
+/** The real size from the sealed body; the only size the bytes are cut back to. */
+sealedSize?: number, 
+/** What the sealed body says of the chunks (`chunkOf`): absent for a file sealed whole. */
+chunk?: number) => Promise<string | null>;
+/**
+ * Move a local-transfer file the receiver already decrypted into the
+ * Downloads folder, now that its push record has arrived. `link` + unlink
+ * keeps the never-overwrite rule (`resolveDownloadPath` picks a free name,
+ * link refuses a taken one); a Downloads folder on another volume gets a
+ * copy instead. Null when the transfer is not in the landing zone — already
+ * claimed by a duplicated push.new, or swept as an orphan.
+ *
+ * The receiver wrote the bytes as they were sealed, padding included: with
+ * `sealedSize` (the size the sealed body gives) the file is cut back to it
+ * first, as a file from the relay is, so Downloads never holds the padded one.
+ * That size was picked by the record's `iv`, and the record is the relay's
+ * word: it cuts only a file that landed under that same iv (the receiver left
+ * it beside the file), and a record that names another is refused whole. From
+ * the relay the same check is the decrypt itself, which fails under a wrong iv.
+ */
+export declare const claimLanFile: (file: {
+    fileName: string;
+    transferId: string;
+    sealedSize?: number;
+    iv?: string;
+}, landingDir?: string, downloads?: string) => string | null;
+/**
+ * The folder a saved file is in, as a person would type it: the home prefix
+ * shown as `~`. The title already carries the name — the one the file was
+ * actually saved under, ` (2)` included — so the body only has to say where.
+ */
+export declare const displayFolder: (dest: string, home?: string) => string;
+/**
+ * Remove attachment sub-directories whose mtime is older than `ttl`.
+ * Best-effort: an entry that can't be statted or removed is skipped, not
+ * fatal. Returns the count removed. `dir`/`ttl` are injectable for tests.
+ */
+export declare const gcAttachments: (now?: number, dir?: string, ttl?: number, landingDir?: string) => number;
+export declare const handlePush: (push: PushItem, deps?: HandlePushDeps) => Promise<boolean>;
+export declare const computeBackoff: (attempt: number) => number;
+interface SessionResult {
+    /** Resolved with the close code if the server closed cleanly. */
+    closeCode: number | null;
+    /** Resolved with reason text for logging. */
+    reason: string;
+    /** True if the socket ever reached `open` — resets reconnect backoff. */
+    connected: boolean;
+}
+export declare const computeListenerDeviceId: (host?: string) => string;
+interface StreamHandle {
+    done: Promise<SessionResult>;
+    terminate: () => void;
+    /** True once the socket reached `open` — the device record exists from then on. */
+    opened: () => boolean;
+    /** Send one frame; false when the socket is not open. Local transfer
+     *  publishes its endpoint and this machine's public key this way
+     *  (`listener.presence`) — the HTTP device route is JWT-only. */
+    send: (msg: object) => boolean;
+}
+/**
+ * Open one WebSocket and stream messages until it closes. `done` resolves
+ * when the connection is gone; the outer loop decides whether to reconnect.
+ * `terminate` lets a signal handler force-close from outside (otherwise
+ * SIGINT during an open WS would hang the loop until the server closed).
+ */
+export declare const streamSession: (wsUrl: string, apiKey: string) => StreamHandle;
+export { resolveWsUrl } from './ws-url.js';
+/**
+ * What the listener starts with that comes from the flags, the environment and `config.json`:
+ * the key, where it goes, and the opt-out options. A config.json that is there and cannot be used
+ * reads as every option off (`unreadableConfigDefaults`), and the listener keeps running (a clean
+ * exit takes the launchd service down, an unclean one restarts it every 30 s). Its own function so a
+ * test can drive it without a socket.
+ */
+export type ListenerSettings = {
+    exit: number;
+    message: string;
+} | {
+    config: HwipConfig;
+    apiKey: string;
+    baseUrl: string;
+    features: ReturnType<typeof optionalFeatures>;
+    ignored: string | null;
+};
+export declare const listenerSettings: (args: Record<string, string | boolean>) => ListenerSettings;
+/**
+ * What the schedule runner touches on this machine. A launch is `hwip <agent> --detach` run as a child of the
+ * listener, in the schedule's directory with argv as an array; the project-dir env vars are dropped so the
+ * child resolves its project from that directory, not from whatever shell started the listener.
+ */
+export declare const liveScheduleRunnerDeps: (notify: ScheduleRunnerDeps["notify"]) => ScheduleRunnerDeps;
+export declare const handleListener: (args: Record<string, string | boolean>) => Promise<number>;
+//# sourceMappingURL=listener.d.ts.map