@hwip/cli 0.1.7 → 0.1.9

package/dist/listener.d.ts

@@ -283,6 +283,36 @@ export declare const probePane: (session: string) => PaneProbe | null;
  * rejected.
  */
 export declare const resolveKeys: (keys: string[]) => string[] | null;
+type WheelDirection = 'up' | 'down';
+/** A batch of wheel keys as directions; null unless every key is one. */
+export declare const resolveWheel: (keys: string[]) => WheelDirection[] | null;
+/** What a wheel tick needs from the pane, read when the tick arrives rather than from the frame the phone saw. */
+export declare const WHEEL_STATE_FORMAT = "#{alternate_on},#{mouse_any_flag},#{mouse_sgr_flag},#{pane_width},#{pane_height},#{pane_current_command}";
+/** Wheel keys a pane has taken toward its next event, kept across batches. */
+export type WheelCarry = {
+    direction: WheelDirection;
+    lines: number;
+};
+/**
+ * The phone's per-line wheel keys as wheel events for the pane's command:
+ * one event per WHEEL_LINES_PER_EVENT lines, the rest carried into the next
+ * batch. Turning back drops the carry, as the phone drops what it did not send.
+ */
+export declare const wheelEvents: (keys: WheelDirection[], command: string, carry?: WheelCarry) => {
+    events: WheelDirection[];
+    carry?: WheelCarry;
+};
+/**
+ * The `send-keys` arguments that scroll the TUI by `ticks`, from the pane's
+ * WHEEL_STATE_FORMAT answer. A TUI that reports the mouse in SGR gets wheel
+ * events at the pane centre (button 64 up, 65 down), written as bytes with
+ * `-H`; one that does not gets PPage/NPage. Every byte is built here from
+ * tmux's numbers, never from the wire.
+ *
+ * Null when the pane is not on the alternate screen: the phone's flag can be a
+ * frame stale, and a PgUp into a shell or a prompt prints junk.
+ */
+export declare const wheelInput: (ticks: WheelDirection[], state: string) => string[] | null;
 export { invalidateTmuxSocketCache, silenceListenerLog, tmuxArgs };
 export { liveSessionNames, sessionExists, sessionLiveness };
 export { detectRemoteAgent, isSubagentSessionName, recordSubagentTranscripts, recordTargets, subagentTranscriptFor, tmuxTargetFor };
@@ -702,7 +732,7 @@ export declare const handleScreenHistoryRequest: (req: ScreenHistoryRequest, sen
  * 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 declare const STREAM_GEOMETRY_FORMAT = "#{cursor_x},#{cursor_y},#{pane_height},#{history_size},#{alternate_on}";
 export interface PaneGeometry {
     x: number;
     y: number;
@@ -712,6 +742,11 @@ export interface PaneGeometry {
      *  it record the lines that scroll past without matching text. Absent when
      *  tmux did not answer with a usable number. */
     historySize?: number;
+    /** The pane is on the alternate screen: a full-screen program (Claude Code's
+     *  fullscreen renderer, an editor) draws there, and tmux keeps no scrollback
+     *  of it — older output exists only inside the program, which scrolls it
+     *  itself. Absent when tmux did not say. */
+    alternateScreen?: boolean;
 }
 /**
  * Read the one tmux answer the frame path already asks for per tick.
@@ -899,6 +934,11 @@ export type StreamFramePayload = {
      *  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;
+    /** The pane is on the alternate screen, where tmux keeps no scrollback: a
+     *  viewer scrolls the program (wheel keys) instead of asking for history.
+     *  Absent when tmux would not say. In the clear as the cursor is, and
+     *  sealed the same way. */
+    alternateScreen?: boolean;
     /** Plaintext pane content — only on unencrypted streams. */
     content?: string;
     /** Envelope v2 (`stream.frame`, context = session) of a SealedStreamFrame —
@@ -923,6 +963,7 @@ export type SealedStreamFrame = {
     cursorCol?: number;
     historyLines?: number;
     historySize?: number;
+    alternateScreen?: boolean;
 };
 /**
  * Plaintext bytes of a sealed frame's JSON. Sealing base64-expands it by 4/3
@@ -981,6 +1022,7 @@ export declare const buildStreamFrame: (captured: {
     } | null;
     historyLines?: number;
     historySize?: number;
+    alternateScreen?: boolean;
 }, 
 /** Capture stamp and subscription nonce, sealed with the pane. A sealed
  *  frame without it is dropped: the viewer could not check it. */
@@ -1057,9 +1099,10 @@ type ValidatedInput = SequencedInput & {
     /** 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. */
+    /** Exactly one of tokens, text and wheel is set. */
     tokens: string[] | null;
     text: string | null;
+    wheel?: WheelDirection[];
     /** 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;

package/dist/listener.js

@@ -25,9 +25,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.setSubscriberTrust = exports.collectWatchHits = exports.resetPatternWatches = exports.setPatternWatches = exports.withSettledPrompts = exports.PROMPT_SEAL_WAIT_MS = exports.withBlockedPrompts = exports.setPromptSealer = exports.deriveSessionState = exports.resetSessionStates = exports.continueRuns = exports.runIdOfEpoch = exports.__checkoutCacheSize = exports.parseSessionName = exports.resetPaneFitClaims = exports.tmuxTargetFor = exports.subagentTranscriptFor = exports.recordTargets = exports.recordSubagentTranscripts = exports.isSubagentSessionName = exports.detectRemoteAgent = exports.sessionLiveness = exports.sessionExists = exports.liveSessionNames = exports.tmuxArgs = exports.silenceListenerLog = exports.invalidateTmuxSocketCache = exports.resolveKeys = exports.probePane = exports.checkRateLimit = exports.AUTH_FAILURE_CODES = exports.commandsReportDue = exports.commandsFingerprint = exports.COMMAND_SCAN_INTERVAL_MS = exports.sessionsReportDue = exports.sessionsFingerprint = exports.knownSessionsFingerprint = exports.knownSessionsToReport = exports.withRunSeqs = exports.KNOWN_SESSIONS_REPORTED = exports.staleConnectionAction = exports.askedToReconnect = exports.MAX_STALE_CONNECTION_DROPS = exports.createReportAckWatch = exports.REPORT_ACK_TIMEOUT_MS = exports.SESSION_REPORT_HEARTBEAT_MS = exports.SESSION_REPORT_INTERVAL_MS = exports.heartbeatVerdict = exports.pingDue = exports.PING_IDLE_MS = void 0;
-exports.syncTmuxAgentNames = exports.recordInventory = exports.collectSessionsVerbose = exports.handleCommandInput = exports.pendingInputDecrypts = exports.MAX_PENDING_DECRYPTS = exports.MAX_INPUT_LANES = exports.validateInputMessage = exports.MAX_INPUT_BODY_CHARS = exports.MAX_INPUT_KEYS = exports.handleStreamControl = exports.buildStreamFrame = exports.isStreamCapReached = exports.fitSealedFrame = exports.SEALED_FRAME_MAX_BYTES = exports.stopAllStreams = exports.stopStream = exports.stopStreamOf = exports.handleTurnWatch = exports.sealTurnBatch = exports.resolveWatchTranscript = exports.MAX_CONCURRENT_STREAMS = exports.STREAM_RENEW_FRESH_MS = exports.STREAM_LEASE_MS = exports.claimFrameSend = exports.hasFrameBudget = exports.streamCadence = exports.MAX_FRAMES_PER_SEC = exports.BURST_WINDOW_MS = exports.BURST_INTERVAL_MS = exports.STREAM_INTERVAL_MS = exports.STREAM_CAPTURE_LINES = exports.scheduleInjectSnapshots = exports.historyLinesIn = exports.cursorLineFor = exports.parsePaneGeometry = exports.STREAM_GEOMETRY_FORMAT = exports.handleScreenHistoryRequest = exports.SCREEN_HISTORY_MAX_LINES = exports.handleSessionForgetRequest = exports.handleSessionExitRequest = exports.SESSION_EXIT_STEP_MS = exports.handleSessionResumeRequest = exports.handleScheduleListRequest = exports.handleFileBlobRequest = exports.handleFileTreeRequest = exports.handleDiffFileRequest = exports.handleDiffFilesRequest = exports.fileViewBytes = exports.handleScreenRequest = void 0;
-exports.handleListener = exports.liveScheduleRunnerDeps = exports.listenerSettings = exports.resolveWsUrl = exports.streamSession = exports.computeListenerDeviceId = exports.computeBackoff = exports.handlePush = exports.gcAttachments = exports.displayFolder = exports.claimLanFile = exports.saveFileFromS3 = exports.downloadSealedEach = exports.answerFileBound = exports.downloadAttachments = exports.setAttachmentContext = exports.shellTextRefusal = exports.writeRemoteMarker = exports.isInventoried = void 0;
+exports.withSettledPrompts = exports.PROMPT_SEAL_WAIT_MS = exports.withBlockedPrompts = exports.setPromptSealer = exports.deriveSessionState = exports.resetSessionStates = exports.continueRuns = exports.runIdOfEpoch = exports.__checkoutCacheSize = exports.parseSessionName = exports.resetPaneFitClaims = exports.tmuxTargetFor = exports.subagentTranscriptFor = exports.recordTargets = exports.recordSubagentTranscripts = exports.isSubagentSessionName = exports.detectRemoteAgent = exports.sessionLiveness = exports.sessionExists = exports.liveSessionNames = exports.tmuxArgs = exports.silenceListenerLog = exports.invalidateTmuxSocketCache = exports.wheelInput = exports.wheelEvents = exports.WHEEL_STATE_FORMAT = exports.resolveWheel = exports.resolveKeys = exports.probePane = exports.checkRateLimit = exports.AUTH_FAILURE_CODES = exports.commandsReportDue = exports.commandsFingerprint = exports.COMMAND_SCAN_INTERVAL_MS = exports.sessionsReportDue = exports.sessionsFingerprint = exports.knownSessionsFingerprint = exports.knownSessionsToReport = exports.withRunSeqs = exports.KNOWN_SESSIONS_REPORTED = exports.staleConnectionAction = exports.askedToReconnect = exports.MAX_STALE_CONNECTION_DROPS = exports.createReportAckWatch = exports.REPORT_ACK_TIMEOUT_MS = exports.SESSION_REPORT_HEARTBEAT_MS = exports.SESSION_REPORT_INTERVAL_MS = exports.heartbeatVerdict = exports.pingDue = exports.PING_IDLE_MS = void 0;
+exports.pendingInputDecrypts = exports.MAX_PENDING_DECRYPTS = exports.MAX_INPUT_LANES = exports.validateInputMessage = exports.MAX_INPUT_BODY_CHARS = exports.MAX_INPUT_KEYS = exports.handleStreamControl = exports.buildStreamFrame = exports.isStreamCapReached = exports.fitSealedFrame = exports.SEALED_FRAME_MAX_BYTES = exports.stopAllStreams = exports.stopStream = exports.stopStreamOf = exports.handleTurnWatch = exports.sealTurnBatch = exports.resolveWatchTranscript = exports.MAX_CONCURRENT_STREAMS = exports.STREAM_RENEW_FRESH_MS = exports.STREAM_LEASE_MS = exports.claimFrameSend = exports.hasFrameBudget = exports.streamCadence = exports.MAX_FRAMES_PER_SEC = exports.BURST_WINDOW_MS = exports.BURST_INTERVAL_MS = exports.STREAM_INTERVAL_MS = exports.STREAM_CAPTURE_LINES = exports.scheduleInjectSnapshots = exports.historyLinesIn = exports.cursorLineFor = exports.parsePaneGeometry = exports.STREAM_GEOMETRY_FORMAT = exports.handleScreenHistoryRequest = exports.SCREEN_HISTORY_MAX_LINES = exports.handleSessionForgetRequest = exports.handleSessionExitRequest = exports.SESSION_EXIT_STEP_MS = exports.handleSessionResumeRequest = exports.handleScheduleListRequest = exports.handleFileBlobRequest = exports.handleFileTreeRequest = exports.handleDiffFileRequest = exports.handleDiffFilesRequest = exports.fileViewBytes = exports.handleScreenRequest = exports.setSubscriberTrust = exports.collectWatchHits = exports.resetPatternWatches = exports.setPatternWatches = void 0;
+exports.handleListener = exports.liveScheduleRunnerDeps = exports.listenerSettings = exports.resolveWsUrl = exports.streamSession = exports.computeListenerDeviceId = exports.computeBackoff = exports.handlePush = exports.gcAttachments = exports.displayFolder = exports.claimLanFile = exports.saveFileFromS3 = exports.downloadSealedEach = exports.answerFileBound = exports.downloadAttachments = exports.setAttachmentContext = exports.shellTextRefusal = exports.writeRemoteMarker = exports.isInventoried = exports.syncTmuxAgentNames = exports.recordInventory = exports.collectSessionsVerbose = exports.handleCommandInput = void 0;
 const child_process_1 = require("child_process");
 const crypto_1 = require("crypto");
 const fs_1 = require("fs");
@@ -571,6 +571,83 @@ const resolveKeys = (keys) => {
     return out.length ? out : null;
 };
 exports.resolveKeys = resolveKeys;
+/**
+ * The phone's scroll for a pane on the alternate screen, where a full-screen
+ * TUI draws and tmux keeps no scrollback to page. Not in ALLOWED_KEYS, so only
+ * stream input takes them: the REST path stores a command and shows it as a
+ * bubble, and a wheel tick means nothing without a live view of the pane.
+ */
+const WHEEL_KEYS = new Map([
+    ['wheelup', 'up'],
+    ['wheeldown', 'down'],
+]);
+/** A batch of wheel keys as directions; null unless every key is one. */
+const resolveWheel = (keys) => {
+    const out = [];
+    for (const k of keys) {
+        const direction = WHEEL_KEYS.get(k.toLowerCase().trim());
+        if (!direction)
+            return null;
+        out.push(direction);
+    }
+    return out.length ? out : null;
+};
+exports.resolveWheel = resolveWheel;
+/** What a wheel tick needs from the pane, read when the tick arrives rather than from the frame the phone saw. */
+exports.WHEEL_STATE_FORMAT = '#{alternate_on},#{mouse_any_flag},#{mouse_sgr_flag},#{pane_width},#{pane_height},#{pane_current_command}';
+/**
+ * Lines a TUI scrolls for one wheel event, by the pane's command, where that is
+ * not one. The phone sends a wheel key per line of drag; measured 2026-10-22
+ * with SGR wheel bytes into live panes, Claude Code and pi (`node`) scroll a
+ * line an event and OpenCode three.
+ */
+const WHEEL_LINES_PER_EVENT = new Map([['opencode', 3]]);
+/**
+ * The phone's per-line wheel keys as wheel events for the pane's command:
+ * one event per WHEEL_LINES_PER_EVENT lines, the rest carried into the next
+ * batch. Turning back drops the carry, as the phone drops what it did not send.
+ */
+const wheelEvents = (keys, command, carry) => {
+    const perEvent = WHEEL_LINES_PER_EVENT.get(command) ?? 1;
+    const events = [];
+    let held = carry;
+    for (const direction of keys) {
+        const lines = (held?.direction === direction ? held.lines : 0) + 1;
+        if (lines >= perEvent) {
+            events.push(direction);
+            held = undefined;
+        }
+        else {
+            held = { direction, lines };
+        }
+    }
+    return { events, carry: held };
+};
+exports.wheelEvents = wheelEvents;
+/**
+ * The `send-keys` arguments that scroll the TUI by `ticks`, from the pane's
+ * WHEEL_STATE_FORMAT answer. A TUI that reports the mouse in SGR gets wheel
+ * events at the pane centre (button 64 up, 65 down), written as bytes with
+ * `-H`; one that does not gets PPage/NPage. Every byte is built here from
+ * tmux's numbers, never from the wire.
+ *
+ * Null when the pane is not on the alternate screen: the phone's flag can be a
+ * frame stale, and a PgUp into a shell or a prompt prints junk.
+ */
+const wheelInput = (ticks, state) => {
+    const [alternate, mouseAny, mouseSgr, width, height] = state.trim().split(',');
+    if (alternate !== '1')
+        return null;
+    const cols = Number(width);
+    const rows = Number(height);
+    if (mouseAny === '1' && mouseSgr === '1' && Number.isSafeInteger(cols) && Number.isSafeInteger(rows) && cols > 0 && rows > 0) {
+        const at = `${Math.floor(cols / 2) + 1};${Math.floor(rows / 2) + 1}M`;
+        const bytes = ticks.map((t) => `\x1b[<${t === 'up' ? 64 : 65};${at}`).join('');
+        return ['-H', ...Array.from(Buffer.from(bytes, 'ascii'), (b) => b.toString(16).padStart(2, '0'))];
+    }
+    return ticks.map((t) => (t === 'up' ? 'PPage' : 'NPage'));
+};
+exports.wheelInput = wheelInput;
 /**
  * Send named keys as keys (NOT `-l`), so tmux interprets Escape/Up/Enter as
  * key presses rather than literal text. One send-keys call carries the
@@ -1888,7 +1965,7 @@ const capturePane = (sessionName, escapes = false, lines = SCREEN_PEEK_LINES) =>
  * 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.
  */
-exports.STREAM_GEOMETRY_FORMAT = '#{cursor_x},#{cursor_y},#{pane_height},#{history_size}';
+exports.STREAM_GEOMETRY_FORMAT = '#{cursor_x},#{cursor_y},#{pane_height},#{history_size},#{alternate_on}';
 /**
  * The last capture of each mirrored session, kept for `STREAM_SHARE_MS`: viewers of one session tick
  * together (see the start of a stream), and the first one's capture serves the rest — a tmux spawn
@@ -1925,6 +2002,8 @@ const captureStreamPaneNow = (sessionName) => {
         return null;
     return { captured: capToFrameLimit(out.slice(split + 1)), geometry: (0, exports.parsePaneGeometry)(out.slice(0, split)) };
 };
+/** A tmux flag field: `1`/`0`, or undefined for an empty or unknown answer. */
+const tmuxFlag = (field) => field === '1' ? true : field === '0' ? false : undefined;
 /**
  * Read the one tmux answer the frame path already asks for per tick.
  *
@@ -1944,9 +2023,14 @@ const parsePaneGeometry = (raw) => {
     // clear; letting an empty answer arrive as one would fake the clear and
     // make the viewer re-record output it already holds.
     const depth = fields.length > 3 && fields[3] !== '' ? Number(fields[3]) : NaN;
-    if (!Number.isSafeInteger(depth) || depth < 0)
-        return { x, y, height };
-    return { x, y, height, historySize: depth };
+    const alternateScreen = tmuxFlag(fields[4]);
+    return {
+        x,
+        y,
+        height,
+        ...(Number.isSafeInteger(depth) && depth >= 0 ? { historySize: depth } : {}),
+        ...(alternateScreen === undefined ? {} : { alternateScreen }),
+    };
 };
 exports.parsePaneGeometry = parsePaneGeometry;
 /**
@@ -2573,6 +2657,7 @@ stamp) => {
         ...(cursor ? { cursorLine: cursor.line, cursorCol: cursor.col } : {}),
         ...(meta?.historyLines === undefined ? {} : { historyLines: meta.historyLines }),
         ...(meta?.historySize === undefined ? {} : { historySize: meta.historySize }),
+        ...(meta?.alternateScreen === undefined ? {} : { alternateScreen: meta.alternateScreen }),
     };
     const head = { subtype: 'agent.stream.frame', sessionName, capturedAt: new Date().toISOString() };
     if (!subscriberPublicKey)
@@ -2720,12 +2805,14 @@ const handleStreamControl = (req, send) => {
     if (fitTarget !== null)
         paneFitter.fit(sessionName, fitTarget, req.cols);
     let lastContent = null;
-    // The cursor's last reported place, as `line,col`. Part of the diff-gate
-    // because moving the cursor is a change the CAPTURE cannot show: an arrow
-    // key inside a prompt leaves every character where it was, so gating on the
-    // text alone means the mirror's cursor never moves — which is precisely the
-    // feedback the cursor exists to give.
-    let lastCursor = null;
+    // The cursor's last reported place and the screen the pane was on, as
+    // `line,col|alternate`. Part of the diff-gate because both change without
+    // the CAPTURE showing it: an arrow key inside a prompt leaves every
+    // character where it was, so gating on the text alone means the mirror's
+    // cursor never moves — which is precisely the feedback the cursor exists to
+    // give; and a program opening its alternate screen over an identical paint
+    // would leave the viewer paging a scrollback that is gone.
+    let lastView = null;
     const stats = {
         startedAt: Date.now(),
         frames: 0,
@@ -2850,8 +2937,9 @@ const handleStreamControl = (req, send) => {
             ? (0, exports.historyLinesIn)(captured.content, cursorAt.height)
             : undefined;
         const historySize = cursorAt?.historySize;
-        const cursorKey = cursor ? `${cursor.line},${cursor.col}` : '';
-        if (captured.content === lastContent && cursorKey === lastCursor) {
+        const alternateScreen = cursorAt?.alternateScreen;
+        const viewKey = `${cursor ? `${cursor.line},${cursor.col}` : ''}|${alternateScreen ?? ''}`;
+        if (captured.content === lastContent && viewKey === lastView) {
             stats.skipped++;
             return true; // diff-gate
         }
@@ -2870,14 +2958,14 @@ const handleStreamControl = (req, send) => {
         // fps by one frame per episode in the R2 numbers.
         const inBurst = armedDelay === exports.BURST_INTERVAL_MS;
         lastContent = captured.content;
-        lastCursor = cursorKey;
+        lastView = viewKey;
         // Stamp the sequence in CAPTURE order, synchronously — frame assembly
         // is async (encryption) and fire-and-forget, so resolve order is not
         // guaranteed under load; the receiver drops any seq it has already
         // painted past.
         const seq = ++wireSeq;
         const stamp = { seq, epoch: stats.startedAt, nonce };
-        void (0, exports.buildStreamFrame)(captured, sessionName, subscriberPublicKey, { cursor, historyLines, historySize }, stamp).then((frame) => {
+        void (0, exports.buildStreamFrame)(captured, sessionName, subscriberPublicKey, { cursor, historyLines, historySize, alternateScreen }, stamp).then((frame) => {
             // Stream stopped or restarted while this frame was in flight —
             // `stats` is unique per start, so it doubles as the identity
             // token. Don't send into a dead/replaced stream or skew its stats.
@@ -2889,7 +2977,7 @@ const handleStreamControl = (req, send) => {
                 // subscriber key) never recovers: fail closed after a few
                 // strikes instead of retrying every tick for 5 minutes.
                 lastContent = null;
-                lastCursor = null;
+                lastView = null;
                 // Init still in flight (or failed — its own path fail-closes):
                 // a not-yet-ready key is not a malformed key, don't strike.
                 if ((0, crypto_js_1.getDevicePublicKey)() === null)
@@ -3067,6 +3155,10 @@ const validateInputMessage = (msg) => {
         if (msg.body !== undefined || msg.insert !== undefined) {
             return { ok: false, reason: 'keys are mutually exclusive with body/insert' };
         }
+        // A batch is all wheel or all named keys: a mix fails both lookups and is refused whole.
+        const wheel = (0, exports.resolveWheel)(msg.keys);
+        if (wheel)
+            return { ok: true, input: { ...base, tokens: null, text: null, wheel, submit: false } };
         const tokens = (0, exports.resolveKeys)(msg.keys);
         if (!tokens)
             return { ok: false, reason: `unknown key(s) [${msg.keys.join(' ')}]` };
@@ -3106,9 +3198,11 @@ const deliverInput = (input) => {
         reason = 'prompt_changed';
     const injected = bound && hasStream(input.sessionName)
         // Stream input arrives on this listener's own subscription: addressed.
-        && (input.tokens
-            ? tryInjectKeys(input.sessionName, input.tokens, deps, true)
-            : tryInject(input.sessionName, input.text ?? '', deps, { submit: input.submit, addressed: true }));
+        && (input.wheel
+            ? tryScroll(input.sessionName, input.wheel, deps)
+            : input.tokens
+                ? tryInjectKeys(input.sessionName, input.tokens, deps, true)
+                : tryInject(input.sessionName, input.text ?? '', deps, { submit: input.submit, addressed: true }));
     // Every refusal reachable from here — dead lease, shell pane, rate limit,
     // a failed send-keys — used to be silent, which contradicts the contract
     // above: the sender would keep waiting on a keystroke that never lands
@@ -3116,7 +3210,8 @@ const deliverInput = (input) => {
     // Only a reason that does not depend on the text: this input may be sealed.
     if (!injected)
         input.send(streamErrorFrame(input.sessionName, 'input_rejected', input, reason && (0, command_refusal_js_1.isSessionStateRefusal)(reason) ? reason : undefined));
-    else
+    // Scrolling is looking, not typing: it does not size a window a desktop took back.
+    else if (!input.wheel)
         takeWidthBack(input.sessionName, input.deviceId);
 };
 /**
@@ -3829,7 +3924,7 @@ exports.isInventoried = isInventoried;
  *
  * Returns what the probe saw when the input is admitted, null when refused.
  */
-const passesInjectGuards = (session, deps, addressed, cost = 1) => {
+const passesInjectGuards = (session, deps, addressed, cost = 1, bucket = session) => {
     // Subagent panes are view-only: the phone reads them but the agent
     // itself answers at the terminal. This sits above the rate bucket so a
     // flood of refused subagent writes costs nothing and spawns nothing —
@@ -3843,7 +3938,7 @@ const passesInjectGuards = (session, deps, addressed, cost = 1) => {
     // Rate bucket first: the pane probe below is a blocking tmux spawnSync,
     // and the sequencer can flush several held messages back-to-back — an
     // empty bucket must refuse before paying that probe N times, not after.
-    if (!(deps.rateLimit ?? exports.checkRateLimit)(session, Date.now(), cost)) {
+    if (!(deps.rateLimit ?? exports.checkRateLimit)(bucket, Date.now(), cost)) {
         (0, listener_log_js_1.log)(`! ${session}: rate-limited — drop`);
         deps.noteRefusal?.('rate_limited');
         return null;
@@ -4008,6 +4103,51 @@ const tryInjectKeys = (session, tokens, deps, addressed) => {
         deps.noteRefusal?.('inject_failed');
     return ok;
 };
+/**
+ * Wheel sibling of tryInjectKeys, under the same pane/shell guards. Its own
+ * rate bucket: the phone sends a tick batch every few hundred ms while a
+ * finger drags, and a minute of scrolling must not spend the typing budget.
+ * A pane that left the alternate screen takes nothing and is not a refusal —
+ * the scroll simply has nowhere to go.
+ */
+const wheelCarry = new Map();
+const tryScroll = (session, ticks, deps) => {
+    const probe = passesInjectGuards(session, deps, true, 1, `wheel:${session}`);
+    if (!probe)
+        return false;
+    const target = (0, tmux_pane_js_1.tmuxTargetFor)(session);
+    if (target === null)
+        return false;
+    const names = ticks.map((t) => `wheel${t}`).join(' ');
+    const state = runTmux(['display-message', '-p', '-t', target, exports.WHEEL_STATE_FORMAT]);
+    const command = state.stdout.trim().split(',').slice(5).join(',');
+    const { events, carry } = (0, exports.wheelEvents)(ticks, command, wheelCarry.get(session));
+    const args = state.status === 0 ? (0, exports.wheelInput)(events, state.stdout) : undefined;
+    if (args === null) {
+        wheelCarry.delete(session);
+        (0, listener_log_js_1.log)(`· ${session}: wheel for a pane off the alternate screen — skip`);
+        return true;
+    }
+    if (carry)
+        wheelCarry.set(session, carry);
+    else
+        wheelCarry.delete(session);
+    if (args !== undefined && events.length === 0) {
+        (0, listener_log_js_1.log)(`· ${session}: [${names}] held toward ${command}'s next wheel event`);
+        return true;
+    }
+    const ok = args !== undefined
+        && (0, child_process_1.spawnSync)('tmux', (0, tmux_socket_js_1.tmuxArgs)(['send-keys', '-t', target, ...args]), { stdio: ['ignore', 'ignore', 'pipe'] }).status === 0;
+    if (ok) {
+        noteStreamInput(session);
+        if (probe.shellMarked)
+            auditShellInput({ session, probe, kind: 'keys', text: names }, deps);
+    }
+    (0, listener_log_js_1.log)(`${ok ? '⌨' : '✗'} ${session}: [${names}]`);
+    if (!ok)
+        deps.noteRefusal?.('inject_failed');
+    return ok;
+};
 // ─── Attachment download (agent.command files[]) ────────────────────
 const ATTACHMENTS_DIR = (0, path_1.join)((0, os_1.homedir)(), '.hwip', 'attachments');
 /** Local-transfer landing zone: `lan/<transferId>/<fileName>` until its push record arrives. */

package/dist/templates.js

@@ -789,6 +789,17 @@ const LOOKUP_TIMEOUT_MS = 5000;
 const RESUBSCRIBE_MIN_MS = 1000;
 const RESUBSCRIBE_MAX_MS = 30000;
 
+// The newest instance per directory. 2.x evicts a directory's instance after an
+// idle hour (\`experimental.location_idle_timeout\`) and runs \`setup\` again on the
+// next request, but hands \`setup\` no way to learn of the eviction — and the
+// evicted instance's stream keeps delivering. Each eviction would leave one more
+// loop pushing every turn. The module is evaluated afresh per instance (2.1.2,
+// 2026-10-22), so only \`globalThis\` outlives one; an outdated loop stops at its
+// next event.
+const CURRENT_KEY = Symbol.for("hwip.opencode.current");
+const currentByDirectory = (): Map<string, object> =>
+  ((globalThis as Record<symbol, Map<string, object> | undefined>)[CURRENT_KEY] ??= new Map());
+
 const setup = (ctx: V2Context): void => {
   // 1.18 calls \`setup\` as well as \`server\`, with a context that has no event
   // stream. Its hooks are \`server\`'s, so there is nothing to do here.
@@ -797,6 +808,10 @@ const setup = (ctx: V2Context): void => {
   const subscribe = stream.subscribe.bind(stream);
   const here = ctx.location?.directory;
   const turns = createTurns();
+  const instance = {};
+  const key = here ?? "";
+  currentByDirectory().set(key, instance);
+  const outdated = (): boolean => currentByDirectory().get(key) !== instance;
 
   // One server runs an instance of this plugin per directory and hands every
   // instance every session's events, so the session's own directory decides
@@ -854,9 +869,10 @@ const setup = (ctx: V2Context): void => {
   // \`notify\` drops them — there is no channel the user would read.
   const consume = async (): Promise<void> => {
     let wait = RESUBSCRIBE_MIN_MS;
-    for (;;) {
+    while (!outdated()) {
       try {
         for await (const event of subscribe()) {
+          if (outdated()) return;
           wait = RESUBSCRIBE_MIN_MS;
           try {
             await handle(event);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hwip/cli",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Hwip CLI + push notification SDK for AI agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",