@hwip/cli 0.1.3 → 0.1.5

package/dist/listener.d.ts

@@ -24,6 +24,7 @@ import { type HwipConfig } from './config.js';
 import { type ShellAuditEntry } from './shell-audit.js';
 import { type KnownSession } from './session-registry.js';
 import { type AgentKind } from './remote-agents.js';
+import type { ProviderNameSource } from './session-title.js';
 import { type TranscriptSource } from './transcript-tail.js';
 import { type AgentState } from './agent-state.js';
 import { type SealedFileMeta, type SealedV2 } from './crypto.js';
@@ -121,6 +122,12 @@ interface AgentSession {
      * word for both would put the ambiguity in the type.
      */
     providerSessionName?: string | null;
+    /**
+     * Who chose `providerSessionName`: a person in the agent (`'user'`) or the
+     * agent itself (`'auto'`). Omitted when the agent's store cannot say. The
+     * account setting that hides agent-made names hides `'auto'` only.
+     */
+    providerSessionNameSource?: ProviderNameSource;
     createdAt?: string;
     /**
      * Which run of the name this is (hwip docs/session-runs.md): tmux
@@ -222,6 +229,9 @@ export interface ReportedKnownSession {
     lastSeq?: number;
     /** The later tmux sessions the run went on in (Q35): the server ends another run's push window at their start. */
     tmuxRunIds?: string[];
+    /** The last name the agent gave the run, and who gave it (hwip docs/session-runs.md Q39): what the phone calls it once ended. */
+    providerSessionName?: string;
+    providerSessionNameSource?: ProviderNameSource;
     lastSeenAt: string;
 }
 /** Each live run's first seq, for the report (Q24). A run that has recorded nothing yet has none. */
@@ -274,6 +284,8 @@ export declare const resolveKeys: (keys: string[]) => string[] | null;
 export { invalidateTmuxSocketCache, silenceListenerLog, tmuxArgs };
 export { liveSessionNames, sessionExists, sessionLiveness };
 export { detectRemoteAgent, isSubagentSessionName, recordSubagentTranscripts, recordTargets, subagentTranscriptFor, tmuxTargetFor };
+/** Test hook. */
+export declare const resetPaneFitClaims: () => void;
 /**
  * Parse a `hwip-*` tmux session name into `{project, label}`. The wrapper
  * emits `hwip-<project>` and, with `--label <x>`, `hwip-<project>-<x>`; the
@@ -631,6 +643,27 @@ export interface ScreenHistorySnapshot {
     error?: string;
     capturedAt: string;
 }
+/**
+ * What a sealed history page's envelope holds (as JSON): the page and every
+ * number a viewer pages by, bound to the request it answers and to the
+ * subscription it was sealed for. On a sealed stream the snapshot carries
+ * only `requestId` (for routing) beside this — a relay that hands an earlier
+ * page back under a new request, or rewrites where it sits, is caught on open.
+ */
+export type SealedHistoryPage = {
+    sessionName: string;
+    requestId: string;
+    nonce?: string;
+    epoch: number;
+    before: number;
+    lines: number;
+    hasMore: boolean;
+    truncated: boolean;
+    /** The pane's history size when this page was captured, so the viewer can
+     *  tell how much the history grew between its request and the capture. */
+    historySize: number;
+    content: 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

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.handleScreenRequest = 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.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.isInventoried = 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 = 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 = void 0;
+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;
 const child_process_1 = require("child_process");
 const crypto_1 = require("crypto");
 const fs_1 = require("fs");
@@ -319,16 +319,18 @@ const knownSessionsToReport = (live, now = Date.now(), seqs = (0, run_seqs_js_1.
         ...(e.startedAt ? { startedAt: e.startedAt } : {}),
         ...(e.runId ? seqs.get((0, run_seqs_js_1.runSeqsKey)(e.name, e.runId)) : undefined),
         ...(e.tmuxRunIds?.length ? { tmuxRunIds: e.tmuxRunIds } : {}),
+        ...(e.providerSessionName ? { providerSessionName: e.providerSessionName } : {}),
+        ...(e.providerSessionName && e.providerSessionNameSource ? { providerSessionNameSource: e.providerSessionNameSource } : {}),
         lastSeenAt: e.lastSeenAt,
     }));
 };
 exports.knownSessionsToReport = knownSessionsToReport;
-const knownSessionsFingerprint = (known) => known.map((k) => `${k.name}${k.agentKind}${k.runId ?? ''}${k.lastSeenAt}${k.firstSeq ?? ''}${k.lastSeq ?? ''}${k.tmuxRunIds?.join(',') ?? ''}`).sort().join('|');
+const knownSessionsFingerprint = (known) => known.map((k) => `${k.name}${k.agentKind}${k.runId ?? ''}${k.lastSeenAt}${k.firstSeq ?? ''}${k.lastSeq ?? ''}${k.tmuxRunIds?.join(',') ?? ''} ${k.providerSessionNameSource ?? ''} ${k.providerSessionName ?? ''}`).sort().join('|');
 exports.knownSessionsFingerprint = knownSessionsFingerprint;
 const sessionsFingerprint = (sessions) => sessions
     .map((s) => JSON.stringify([
     s.name, s.attached, s.agentKind, s.agentSessionId ?? null,
-    s.project, s.label ?? null, s.providerSessionName ?? null, s.createdAt ?? null, s.runId ?? null, s.firstSeq ?? null,
+    s.project, s.label ?? null, s.providerSessionName ?? null, s.providerSessionNameSource ?? null, s.createdAt ?? null, s.runId ?? null, s.firstSeq ?? null,
     s.lastActivityAt ?? null, s.state ?? null,
     s.stateChangedAt ?? null, s.stateRuleId ?? null,
     s.blockedPrompt?.id ?? null, s.blockedPrompt?.at ?? null,
@@ -588,8 +590,13 @@ const worktreeCleanup = (0, listener_worktree_cleanup_js_1.createWorktreeCleanup
     notify: desktop_notify_js_1.notifyDesktop,
     tmux: (args, timeoutMs) => (0, worktree_js_1.tmuxRun)((0, tmux_socket_js_1.tmuxArgs)(args), timeoutMs),
 });
-/** Sizes a watched detached window to its viewer (pane-fit.ts). */
-const paneFitter = (0, pane_fit_js_1.createPaneFitter)(runTmux);
+/** Sizes a watched window to its viewer while the phone is its latest user (pane-fit.ts). */
+const paneFitter = (0, pane_fit_js_1.createPaneFitter)(runTmux, undefined, (0, pane_fit_js_1.macosLastKeyAt)());
+/** Test hook. */
+const resetPaneFitClaims = () => paneFitter.forgetClaims();
+exports.resetPaneFitClaims = resetPaneFitClaims;
+/** How often fitted windows are checked for a desktop that took them back; idle windows cost nothing. */
+const PANE_FIT_RECHECK_MS = 1_000;
 // ─── Session inventory ──────────────────────────────────────────────
 /**
  * Parse a `hwip-*` tmux session name into `{project, label}`. The wrapper
@@ -1745,11 +1752,11 @@ const handleScreenHistoryRequest = (req, send) => {
         return reply({ error: 'capture_failed' });
     // Everything below this line the caller already has.
     const held = before;
-    // Scrolled past the oldest line. An empty page rather than an error — the
-    // view stops, and stopping is not a failure. Nothing to seal either.
-    if (depth <= held)
-        return reply({ before, content: '', lines: 0, hasMore: false });
-    const captured = capturePaneRange(req.sessionName, -(held + lines), -(held + 1));
+    // Scrolled past the oldest line: an empty page rather than an error — the
+    // view stops, and stopping is not a failure.
+    const captured = depth <= held
+        ? { content: '', truncated: false }
+        : capturePaneRange(req.sessionName, -(held + lines), -(held + 1));
     if (!captured)
         return reply({ error: 'capture_failed' });
     const returned = countLines(captured.content);
@@ -1761,11 +1768,21 @@ const handleScreenHistoryRequest = (req, send) => {
     };
     if (!stream.subscriberPublicKey)
         return reply({ ...page, content: captured.content });
-    // Encrypted stream: the page rides ONLY inside the envelope, and a failed
-    // seal is an error rather than a plaintext page — the same rule the frame
-    // path follows when its encrypt fails.
-    (0, crypto_js_1.sealV2)('screen.history', captured.content, stream.subscriberPublicKey, req.sessionName)
-        .then((encrypted) => send({ ...base, ...page, encrypted }))
+    // Encrypted stream: the page and its numbers ride ONLY inside the envelope
+    // — the empty last page too, or a relay could end the paging with one — and
+    // a failed seal is an error rather than a plaintext page, the same rule the
+    // frame path follows when its encrypt fails.
+    const sealed = {
+        sessionName: req.sessionName,
+        requestId: req.requestId,
+        ...(stream.nonce ? { nonce: stream.nonce } : {}),
+        epoch: stream.epoch,
+        ...page,
+        historySize: depth,
+        content: captured.content,
+    };
+    (0, crypto_js_1.sealV2)('screen.history', JSON.stringify(sealed), stream.subscriberPublicKey, req.sessionName)
+        .then((encrypted) => send({ ...base, encrypted }))
         .catch((err) => {
         (0, listener_log_js_1.log)(`⧉ history ${req.sessionName}: seal failed (${err instanceof Error ? err.message : err})`);
         send({ ...base, error: 'encrypt_failed' });
@@ -2076,9 +2093,9 @@ const leaseFor = (renewing) => (renewing ? exports.STREAM_LEASE_MS : STREAM_MAX_
  * Live mirrors, one per (session, viewing device): every viewer keeps the whole of the machinery a
  * single viewer had — its own capture loop state, lease, nonce, epoch and seq, sealed frames — so
  * two devices watching one pane do not take each other's stream over. A viewer with no device id
- * (a web tab) shares the empty slot, one at a time, as before. The tmux pane is shared: its width
- * is whatever the last viewer to send input or `cols` asked for (pane-fit.ts), and every viewer
- * receives the pane at that width.
+ * (a web tab) shares the empty slot, one at a time, as before. The tmux pane is shared: while the
+ * phone is its latest user its width is whatever the last viewer to send input or `cols` asked for,
+ * and a desktop client used since takes it back (pane-fit.ts); every viewer receives the pane at that width.
  */
 const activeStreams = new Map();
 const streamKey = (sessionName, deviceId) => `${sessionName}\u0000${typeof deviceId === 'string' ? deviceId : ''}`;
@@ -2607,6 +2624,9 @@ const handleStreamControl = (req, send) => {
             const renewTarget = (0, tmux_pane_js_1.tmuxTargetFor)(req.sessionName);
             if (renewTarget !== null && (colsChanged || streamsOf(req.sessionName).length === 1))
                 paneFitter.fit(req.sessionName, renewTarget, req.cols);
+            // Otherwise keep the width the pane has, but still notice a desktop client used since (pane-fit.ts).
+            else
+                paneFitter.recheck(req.sessionName);
             return true;
         }
         // Addressed to us but we hold no such stream: it was reaped (lost
@@ -2648,6 +2668,8 @@ const handleStreamControl = (req, send) => {
         return true;
     }
     const fitTarget = (0, tmux_pane_js_1.tmuxTargetFor)(sessionName);
+    // Opening the mirror (or resubscribing) takes the width only from an idle desktop (pane-fit.ts).
+    paneFitter.open(sessionName);
     if (fitTarget !== null)
         paneFitter.fit(sessionName, fitTarget, req.cols);
     let lastContent = null;
@@ -3047,6 +3069,23 @@ 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
+        takeWidthBack(input.sessionName, input.deviceId);
+};
+/**
+ * Typing from the phone makes it the session's latest user again (pane-fit.ts): a window a desktop
+ * client took back is sized to the sender's width once more.
+ */
+const takeWidthBack = (sessionName, deviceId) => {
+    paneFitter.claim(sessionName);
+    const viewer = activeStreams.get(streamKey(sessionName, deviceId)) ?? streamsOf(sessionName)[0];
+    // Already at the sender's width: the claim is enough, and a keystroke costs no tmux round trip (renew rechecks).
+    if (!viewer || paneFitter.fitted(sessionName, viewer.cols))
+        return;
+    const target = (0, tmux_pane_js_1.tmuxTargetFor)(sessionName);
+    if (target === null)
+        return;
+    paneFitter.fit(sessionName, target, viewer.cols);
 };
 /** 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
@@ -3448,7 +3487,7 @@ const collectSessionsVerbose = () => {
         const agentSessionId = info.currentPath
             ? (main.agent.resolveSessionId?.(info.currentPath, info.panePid ?? undefined) ?? null)
             : null;
-        const providerSessionName = info.currentPath
+        const providerName = info.currentPath
             ? (main.agent.resolveSessionName?.(info.currentPath, info.panePid ?? undefined) ?? null)
             : null;
         if (info.currentPath)
@@ -3466,7 +3505,8 @@ const collectSessionsVerbose = () => {
             agentSessionId,
             project: parsed.project,
             label: parsed.label,
-            providerSessionName,
+            providerSessionName: providerName?.name ?? null,
+            ...(providerName?.source ? { providerSessionNameSource: providerName.source } : {}),
             createdAt: epochToIso(group.created),
             runId: (0, exports.runIdOfEpoch)(group.created),
             lastActivityAt: epochToIso(group.activity),
@@ -3611,6 +3651,8 @@ const collectSessionsVerbose = () => {
         startedAt: s.createdAt,
         tmuxRunId: runIdOfIso(s.createdAt),
         agentSessionId: ownResumeId(s.name),
+        providerSessionName: s.providerSessionName,
+        providerSessionNameSource: s.providerSessionNameSource,
     })));
     return { sessions, rejected, targets, subagentTranscripts, recordable };
 };
@@ -4589,7 +4631,7 @@ const openSealedCommand = async (push, deps) => {
     return { text: opened.body ?? '', sender: senderKey, files: named, keys, ifPrompt, schedule };
 };
 /**
- * A phone's request to make or remove a schedule (F8). The decisions are `applyPhoneSchedule`'s; this spends
+ * A phone's request to make, change or remove a schedule (F8). The decisions are `applyPhoneSchedule`'s; this spends
  * the session's rate budget the way a typed command does and reports a refusal the way every command does.
  * Never types anything. A push no one addressed to this machine is not acted on: it changes files, and a
  * push.new reaches every listener of the account.
@@ -4935,6 +4977,10 @@ const streamSession = (wsUrl, apiKey) => {
                 clearInterval(commandsTimer);
                 commandsTimer = null;
             }
+            if (paneFitTimer) {
+                clearInterval(paneFitTimer);
+                paneFitTimer = null;
+            }
             if (connectTimer) {
                 clearTimeout(connectTimer);
                 connectTimer = null;
@@ -4981,6 +5027,7 @@ const streamSession = (wsUrl, apiKey) => {
         // rescan changes it. The rescan has its own slow timer — it reads the
         // filesystem, so it must never ride the 5 s session loop.
         let commandsTimer = null;
+        let paneFitTimer = null;
         // Per connection, like the inventory gate above: `sock.send` returning
         // is not delivery, and a fingerprint that outlived the socket would let
         // one lost frame leave the server's catalog stale until the user next
@@ -5157,6 +5204,8 @@ const streamSession = (wsUrl, apiKey) => {
             sessionsTimer = setInterval(() => void reportSessions(), exports.SESSION_REPORT_INTERVAL_MS);
             void reportCommands();
             commandsTimer = setInterval(reportCommands, exports.COMMAND_SCAN_INTERVAL_MS);
+            // A desktop key takes a fitted window back within a second, not at the phone's next renew (5 s).
+            paneFitTimer = setInterval(() => paneFitter.recheckAll(), PANE_FIT_RECHECK_MS);
             loopSampleAt = Date.now();
             loopMeterTimer = setInterval(() => {
                 const now = Date.now();

package/dist/mcp-command.d.ts

@@ -11,6 +11,13 @@
  */
 /** What the agents run. `hwip` resolves out of the same global bin dir as `npx`. */
 export declare const MCP_LAUNCH_ARGV: readonly ["hwip", "mcp"];
+/**
+ * Turns on the MCP server's `hwip_session_title` (mcp-server config `autoName`),
+ * so an agent with no title of its own names its session after its task. Set
+ * for Codex, Cursor, Windsurf and Gemini only: Claude Code and opencode title
+ * their sessions themselves, and the instruction would cost every turn.
+ */
+export declare const AUTONAME_ENV = "HWIP_AUTONAME";
 /**
  * `mcpServers.hwip` — what the installer writes for Cursor and Windsurf.
  * The env block is deliberate: both spawn the MCP server from a graphical
@@ -18,13 +25,15 @@ export declare const MCP_LAUNCH_ARGV: readonly ["hwip", "mcp"];
  * explicitly rather than left to inheritance.
  *
  * `hwipit/plugin`'s `.mcp.json` holds the same shape but is a HAND-KEPT COPY —
- * it lives in another repo and cannot import this. Change one, change both.
+ * it lives in another repo and cannot import this. Change one, change both —
+ * except AUTONAME_ENV, which the plugin (Claude Code) leaves out on purpose.
  */
 export declare const MCP_SERVERS_ENTRY: {
     command: "hwip";
     args: "mcp"[];
     env: {
         HWIP_API_KEY: string;
+        HWIP_AUTONAME: string;
     };
 };
 /**
@@ -36,10 +45,13 @@ export declare const MCP_SERVERS_ENTRY: {
  */
 export declare const OPENCODE_MCP_ENTRY: {
     type: string;
-    command: ("mcp" | "hwip")[];
+    command: ("hwip" | "mcp")[];
     enabled: boolean;
 };
 export declare const GEMINI_MCP_ADD: string;
 /** Older gemini CLIs only accept `mcp add <name> -- <command…>`, with no scope flag. */
 export declare const GEMINI_MCP_ADD_LEGACY: string;
+/** The legacy form without `-e`, last: should a gemini that old refuse `-e`, the tools still load,
+ *  and `hwip verify` says auto session names are off. */
+export declare const GEMINI_MCP_ADD_BARE: string;
 //# sourceMappingURL=mcp-command.d.ts.map

package/dist/mcp-command.js

@@ -11,10 +11,17 @@
  * itself. Everything below is derived from MCP_LAUNCH_ARGV.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GEMINI_MCP_ADD_LEGACY = exports.GEMINI_MCP_ADD = exports.OPENCODE_MCP_ENTRY = exports.MCP_SERVERS_ENTRY = exports.MCP_LAUNCH_ARGV = void 0;
+exports.GEMINI_MCP_ADD_BARE = exports.GEMINI_MCP_ADD_LEGACY = exports.GEMINI_MCP_ADD = exports.OPENCODE_MCP_ENTRY = exports.MCP_SERVERS_ENTRY = exports.AUTONAME_ENV = exports.MCP_LAUNCH_ARGV = void 0;
 /** What the agents run. `hwip` resolves out of the same global bin dir as `npx`. */
 exports.MCP_LAUNCH_ARGV = ['hwip', 'mcp'];
 const [MCP_BIN, ...MCP_SUBCOMMAND] = exports.MCP_LAUNCH_ARGV;
+/**
+ * Turns on the MCP server's `hwip_session_title` (mcp-server config `autoName`),
+ * so an agent with no title of its own names its session after its task. Set
+ * for Codex, Cursor, Windsurf and Gemini only: Claude Code and opencode title
+ * their sessions themselves, and the instruction would cost every turn.
+ */
+exports.AUTONAME_ENV = 'HWIP_AUTONAME';
 /**
  * `mcpServers.hwip` — what the installer writes for Cursor and Windsurf.
  * The env block is deliberate: both spawn the MCP server from a graphical
@@ -22,12 +29,13 @@ const [MCP_BIN, ...MCP_SUBCOMMAND] = exports.MCP_LAUNCH_ARGV;
  * explicitly rather than left to inheritance.
  *
  * `hwipit/plugin`'s `.mcp.json` holds the same shape but is a HAND-KEPT COPY —
- * it lives in another repo and cannot import this. Change one, change both.
+ * it lives in another repo and cannot import this. Change one, change both —
+ * except AUTONAME_ENV, which the plugin (Claude Code) leaves out on purpose.
  */
 exports.MCP_SERVERS_ENTRY = {
     command: MCP_BIN,
     args: [...MCP_SUBCOMMAND],
-    env: { HWIP_API_KEY: '${HWIP_API_KEY}' },
+    env: { HWIP_API_KEY: '${HWIP_API_KEY}', [exports.AUTONAME_ENV]: '1' },
 };
 /**
  * opencode.json's own MCP schema — top-level `mcp` key (not `mcpServers`),
@@ -45,6 +53,11 @@ exports.OPENCODE_MCP_ENTRY = {
 // server NAME and the BINARY are both "hwip" here, so the doubled word below
 // is correct, not a copy-paste slip. Default scope is "project" (cwd-local
 // .gemini/), so user scope is pinned for a machine-wide install.
-exports.GEMINI_MCP_ADD = `gemini mcp add -s user hwip ${MCP_BIN} -- ${MCP_SUBCOMMAND.join(' ')}`;
+// `-e` lands in the entry's env. That a reinstall replaces an existing hwip entry whole, and so
+// adds the flag to it, is unverified (gemini CLI behaviour); `hwip verify` reports it if not.
+exports.GEMINI_MCP_ADD = `gemini mcp add -s user -e ${exports.AUTONAME_ENV}=1 hwip ${MCP_BIN} -- ${MCP_SUBCOMMAND.join(' ')}`;
 /** Older gemini CLIs only accept `mcp add <name> -- <command…>`, with no scope flag. */
-exports.GEMINI_MCP_ADD_LEGACY = `gemini mcp add hwip -- ${exports.MCP_LAUNCH_ARGV.join(' ')}`;
+exports.GEMINI_MCP_ADD_LEGACY = `gemini mcp add -e ${exports.AUTONAME_ENV}=1 hwip -- ${exports.MCP_LAUNCH_ARGV.join(' ')}`;
+/** The legacy form without `-e`, last: should a gemini that old refuse `-e`, the tools still load,
+ *  and `hwip verify` says auto session names are off. */
+exports.GEMINI_MCP_ADD_BARE = `gemini mcp add hwip -- ${exports.MCP_LAUNCH_ARGV.join(' ')}`;

package/dist/pane-fit.d.ts

@@ -1,18 +1,30 @@
+import { spawnSync } from 'child_process';
 /**
- * Fit a detached tmux window to the phone that is watching it.
+ * Fit a tmux window to the phone that is watching it.
  *
  * A pane is as wide as the terminal that last drew it, usually a desktop's
  * 120-odd columns. The phone mirror shows about 45, so every full-width row a
  * prompt or TUI draws (a rule, a right-aligned clock, a status line) folds into
- * two. Nobody else sees a DETACHED window, so while a phone watches one it is
- * resized to the phone's width and the program redraws to fit; when the phone
- * leaves, the old width comes back.
+ * two. So while a phone watches a window it is resized to the phone's width
+ * and the program redraws to fit; when the phone leaves, the old width comes
+ * back.
  *
- * An attached window is left alone: shrinking it would shrink the desktop
- * terminal of whoever is attached. A window split into panes is left alone
- * too, since the window width is not any one pane's width. And when a client
- * attaches while the phone is watching, the next check hands the window back
- * to tmux, which sizes it to that client.
+ * A window with a desktop client attached is shared, and whoever used it last
+ * decides its width — the rule tmux's own `window-size latest` follows. The
+ * phone uses a window when it types into it ({@link claim}); a client uses it
+ * when it attaches or a key is pressed in it, which is what
+ * `#{client_activity}` records. tmux also moves that time on a mouse move
+ * over the window and on a focus change (herdr sends one to a pane whenever
+ * another pane is clicked), which are not using it. Where the time of the
+ * desktop's last key press is known ({@link macosLastKeyAt}), a client counts
+ * as used no later than that key, or than when it attached. Opening the mirror ({@link open}) is a weaker
+ * claim: it also covers an automatic resubscribe nobody asked for, so it only
+ * takes a window whose desktop has been idle for {@link DESKTOP_IDLE_SECONDS}.
+ * While the phone is the later of the two, the
+ * window is the phone's width (the desktop terminal shows it narrower); once a
+ * client is newer, the next check hands the window back to tmux, which sizes
+ * it to that client. A window split into panes is left alone, since the
+ * window width is not any one pane's width.
  *
  * A fitted window carries its old width in `@hwip_fit_width`. A listener that
  * died without releasing (a crash, a SIGKILL) leaves that mark behind, and
@@ -24,6 +36,8 @@ export type TmuxRun = (args: string[]) => {
     stdout: string;
 };
 export declare const PANE_FIT_MIN_COLS = 20;
+/** How long a desktop client must sit idle before opening the mirror takes its window. */
+export declare const DESKTOP_IDLE_SECONDS = 60;
 export declare const PANE_FIT_MAX_COLS = 400;
 /** A viewer's column count, or null when it did not send a usable one. */
 export declare const clampViewerCols: (cols: unknown) => number | null;
@@ -32,9 +46,23 @@ export declare const clampViewerCols: (cols: unknown) => number | null;
  * restore its width when detached, then drop the manual size and the mark.
  */
 export declare const releaseStaleFits: (run: TmuxRun) => number;
-export declare const createPaneFitter: (run: TmuxRun) => {
+/** When the desktop behind the tmux client `clientPid` last pressed a key, in seconds since the epoch, or null when it cannot tell. */
+export type LastKeyAt = (clientPid: number) => number | null;
+/**
+ * The Mac's last key press, from the HID system's own clock (no Input Monitoring permission needed), read
+ * through `osascript` at most once a second and not again for half a minute after a failed read. A client
+ * that came in over SSH types on another machine, so the Mac's clock says nothing about it: null, as off macOS.
+ */
+export declare const macosLastKeyAt: (now?: () => number, spawn?: typeof spawnSync, platform?: NodeJS.Platform) => LastKeyAt;
+/** `now` is in ms, as `Date.now`; tmux reports client use in whole seconds. */
+export declare const createPaneFitter: (run: TmuxRun, now?: () => number, lastKeyAt?: LastKeyAt) => {
     fit: (session: string, target: string, cols: unknown) => void;
+    recheck: (session: string) => void;
+    recheckAll: () => void;
+    claim: (session: string) => void;
+    open: (session: string) => void;
     release: (session: string) => void;
-    fitted: (session: string) => boolean;
+    fitted: (session: string, cols?: unknown) => boolean;
+    forgetClaims: () => void;
 };
 //# sourceMappingURL=pane-fit.d.ts.map