@hwip/cli 0.1.3 → 0.1.4

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;
     };
 };
 /**
@@ -42,4 +51,7 @@ export declare const OPENCODE_MCP_ENTRY: {
 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

package/dist/pane-fit.js

@@ -1,27 +1,10 @@
 "use strict";
-/**
- * Fit a detached 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.
- *
- * 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 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
- * the next one to start gives those windows back ({@link releaseStaleFits}).
- */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createPaneFitter = exports.releaseStaleFits = exports.clampViewerCols = exports.PANE_FIT_MAX_COLS = exports.PANE_FIT_MIN_COLS = void 0;
+exports.createPaneFitter = exports.macosLastKeyAt = exports.releaseStaleFits = exports.clampViewerCols = exports.PANE_FIT_MAX_COLS = exports.DESKTOP_IDLE_SECONDS = exports.PANE_FIT_MIN_COLS = void 0;
+const child_process_1 = require("child_process");
 exports.PANE_FIT_MIN_COLS = 20;
+/** How long a desktop client must sit idle before opening the mirror takes its window. */
+exports.DESKTOP_IDLE_SECONDS = 60;
 exports.PANE_FIT_MAX_COLS = 400;
 /** A viewer's column count, or null when it did not send a usable one. */
 const clampViewerCols = (cols) => {
@@ -55,6 +38,74 @@ const releaseStaleFits = (run) => {
     return released;
 };
 exports.releaseStaleFits = releaseStaleFits;
+/**
+ * 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.
+ */
+const macosLastKeyAt = (now = () => Date.now(), spawn = child_process_1.spawnSync, platform = process.platform) => {
+    let cached;
+    const remote = new Map();
+    const overSsh = (clientPid) => {
+        const known = remote.get(clientPid);
+        if (known !== undefined)
+            return known;
+        let found = false;
+        for (let pid = clientPid, depth = 0; pid > 1 && depth < 32; depth++) {
+            const r = spawn('ps', ['-o', 'ppid=,comm=', '-p', String(pid)], { encoding: 'utf8', timeout: 2000 });
+            const m = r.status === 0 ? /^\s*(\d+)\s+(.*)$/.exec(String(r.stdout).trim()) : null;
+            if (!m)
+                break;
+            if (/(^|\/)sshd\b/.test(m[2])) {
+                found = true;
+                break;
+            }
+            pid = Number(m[1]);
+        }
+        remote.set(clientPid, found);
+        return found;
+    };
+    const keyAt = () => {
+        const readAt = now();
+        if (cached && readAt < cached.until)
+            return cached.keyAt;
+        // kCGEventSourceStateHIDSystemState = 1, kCGEventKeyDown = 10.
+        const r = spawn('osascript', ['-l', 'JavaScript', '-e',
+            "ObjC.import('CoreGraphics'); $.CGEventSourceSecondsSinceLastEventType(1, 10)"], { encoding: 'utf8', timeout: 2000 });
+        const out = String(r.stdout ?? '').trim();
+        const idle = Number(out);
+        const read = r.status === 0 && out !== '' && Number.isFinite(idle) ? Math.floor(readAt / 1000 - idle) : null;
+        // A hung or failing osascript blocks the listener for its timeout: do not ask again soon.
+        cached = { until: now() + (read === null ? 30_000 : 1000), keyAt: read };
+        return read;
+    };
+    return (clientPid) => {
+        if (platform !== 'darwin')
+            return null;
+        if (Number.isFinite(clientPid) && overSsh(clientPid))
+            return null;
+        return keyAt();
+    };
+};
+exports.macosLastKeyAt = macosLastKeyAt;
+/** The clients on `target`'s session, or null when tmux cannot tell. */
+const readClients = (run, target) => {
+    const r = run(['list-clients', '-t', target, '-F', `#{client_activity}${SEP}#{client_created}${SEP}#{client_pid}`]);
+    if (r.status !== 0)
+        return null;
+    return r.stdout.split('\n').filter(Boolean).flatMap((line) => {
+        const [activity, created, pid] = line.split(SEP).map(Number);
+        return Number.isFinite(activity) ? [{ activity, created: Number.isFinite(created) ? created : 0, pid }] : [];
+    });
+};
+/**
+ * When a client was last used (seconds). With the desktop's key clock, its activity counts only up to the last
+ * key press, or when it attached: a mouse move or focus change after the last key is not use.
+ */
+const clientUse = (client, lastKeyAt) => {
+    const keyAt = lastKeyAt(client.pid);
+    return keyAt === null ? client.activity : Math.max(Math.min(client.activity, keyAt), client.created);
+};
 const readWindow = (run, target) => {
     const r = run(['display-message', '-p', '-t', target,
         `#{session_attached}${SEP}#{window_panes}${SEP}#{window_width}`]);
@@ -65,15 +116,30 @@ const readWindow = (run, target) => {
         return null;
     return { attached, panes, width };
 };
-const createPaneFitter = (run) => {
+/** `now` is in ms, as `Date.now`; tmux reports client use in whole seconds. */
+const createPaneFitter = (run, now = () => Date.now(), lastKeyAt = () => null) => {
     const fits = new Map();
+    /** When the phone last typed into and last opened each session, in tmux's seconds. */
+    const claims = new Map();
+    const seconds = () => Math.floor(now() / 1000);
+    /** The phone typed into `session` just now: it is the latest user until a client is used after it. */
+    const claim = (session) => {
+        claims.set(session, { ...claims.get(session), typedAt: seconds() });
+    };
+    /**
+     * The phone opened the mirror of `session` just now: it takes the window once the desktop is idle. The time
+     * the phone last typed is kept: a reconnect is not a reason to hand an untouched desktop its width back.
+     */
+    const open = (session) => {
+        claims.set(session, { ...claims.get(session), openedAt: seconds() });
+    };
     /**
      * Give the window back: restore its width if nobody is attached, then drop
      * the manual size `resize-window` set, so the next client to attach sizes
      * it again. With a client attached, dropping the option alone resizes it to
      * that client.
      */
-    const release = (session) => {
+    const unfit = (session) => {
         const fit = fits.get(session);
         if (!fit)
             return;
@@ -85,9 +151,50 @@ const createPaneFitter = (run) => {
         run(['set-option', '-w', '-u', '-t', fit.target, FIT_MARK]);
     };
     /**
-     * Size `session`'s window to `cols` if it is detached and unsplit. Safe to
-     * call on every renew: an unchanged width costs one display-message, and a
-     * window that gained a client since is released.
+     * The window is not the phone's to size: it is split, or an attached client was used at or after the
+     * phone's claim, or — when the phone only opened the mirror — within the last {@link DESKTOP_IDLE_SECONDS}.
+     * A tie goes to the desktop: tmux counts in whole seconds, and shrinking a terminal in use is the worse mistake.
+     */
+    const notOurs = (session, target, win) => {
+        if (win.panes !== 1)
+            return true;
+        if (win.attached === 0)
+            return false;
+        const clients = readClients(run, target);
+        if (!clients || clients.length === 0)
+            return true;
+        const claimed = claims.get(session);
+        const desktops = (use) => {
+            const typedSince = claimed?.typedAt !== undefined && use < claimed.typedAt;
+            const openedOnIdle = claimed?.openedAt !== undefined && use < claimed.openedAt
+                && seconds() - use >= exports.DESKTOP_IDLE_SECONDS;
+            return !typedSince && !openedOnIdle;
+        };
+        // A use is never later than the raw activity: when that already leaves the window to the phone, the key
+        // clock (an osascript on macOS) is not read.
+        if (!desktops(Math.max(...clients.map((c) => c.activity))))
+            return false;
+        return desktops(Math.max(...clients.map((c) => clientUse(c, lastKeyAt))));
+    };
+    /**
+     * The phone left: give the window back. When it typed, that is kept: the phone comes and goes (a screen
+     * locks, the app is left a moment, the mirror resubscribes), and on its return it is still the latest user
+     * unless the desktop was used since — the same test a renew applies.
+     */
+    const release = (session) => {
+        const typedAt = claims.get(session)?.typedAt;
+        if (typedAt === undefined)
+            claims.delete(session);
+        else
+            claims.set(session, { typedAt });
+        unfit(session);
+    };
+    /**
+     * Size `session`'s window to `cols` if it is unsplit and the phone used it
+     * after every attached client. Safe to call on every renew: an unchanged
+     * width costs one display-message (and one list-clients when attached), and
+     * a window a client used since is handed back. The first call for a session
+     * counts as opening the mirror when nothing claimed it yet.
      */
     const fit = (session, target, cols) => {
         const want = (0, exports.clampViewerCols)(cols);
@@ -97,9 +204,12 @@ const createPaneFitter = (run) => {
         if (!win)
             return;
         const held = fits.get(session);
-        if (win.attached > 0 || win.panes !== 1) {
+        if (!claims.has(session))
+            open(session);
+        if (notOurs(session, target, win)) {
+            // Only the fit goes: the claim stays, so the desktop keeps the window until the phone uses it again.
             if (held)
-                release(session);
+                unfit(session);
             return;
         }
         if (held && held.cols === want && win.width === want)
@@ -114,6 +224,29 @@ const createPaneFitter = (run) => {
         }
         fits.set(session, { target, width, cols: want });
     };
-    return { fit, release, fitted: (session) => fits.has(session) };
+    /** Hand a held window back if a client was used since or it was split, without touching its width otherwise. */
+    const recheck = (session) => {
+        const held = fits.get(session);
+        if (!held)
+            return;
+        const win = readWindow(run, held.target);
+        if (win && notOurs(session, held.target, win))
+            unfit(session);
+    };
+    /** {@link recheck} every fitted window: a desktop key is answered within a tick, not a renew. */
+    const recheckAll = () => {
+        for (const session of [...fits.keys()])
+            recheck(session);
+    };
+    /** Whether `session`'s window is fitted — at `cols`, when given. */
+    const fitted = (session, cols) => {
+        const held = fits.get(session);
+        if (!held)
+            return false;
+        return cols === undefined || held.cols === (0, exports.clampViewerCols)(cols);
+    };
+    /** Test hook: forget every claim, as a new listener starts with none. */
+    const forgetClaims = () => claims.clear();
+    return { fit, recheck, recheckAll, claim, open, release, fitted, forgetClaims };
 };
 exports.createPaneFitter = createPaneFitter;

package/dist/remote-agents.d.ts

@@ -1,5 +1,6 @@
 import { spawnSync } from 'child_process';
 import { type TranscriptProjector, type TranscriptReader } from './transcript-tail.js';
+import { type ProviderName } from './session-title.js';
 export interface RemoteAgent {
     /** Wire value for AgentSession.agentKind (server/phone contract). */
     kind: string;
@@ -57,8 +58,11 @@ export interface RemoteAgent {
      * carries this only once that agent's name store is confirmed. Cursor and
      * Gemini never will — their state files hold ids, cwds and timestamps and no
      * name at all, so there is nothing to read and the computed label stands.
+     *
+     * The answer says who chose the name (`source`) when the store can tell:
+     * the user setting that hides agent-made names hides `'auto'` only.
      */
-    resolveSessionName?: (paneCwd: string, panePid?: number) => string | null;
+    resolveSessionName?: (paneCwd: string, panePid?: number) => ProviderName | null;
     /**
      * Resolve the file this agent is writing its session transcript to, for the
      * live chat timeline (`turn-watch`).
@@ -117,6 +121,11 @@ export interface PidSessionRecord {
      * without it, and a record without a name is still a valid id match.
      */
     name?: string;
+    /**
+     * Who chose `name`: `"derived"` (from the cwd — CC's placeholder) or
+     * `"user"` (`/rename`). Absent from an older CC, which cannot say.
+     */
+    nameSource?: string;
 }
 export interface ProcTable {
     /** ppid → its direct children, for walking a pane's process tree. */
@@ -208,12 +217,21 @@ export declare const pidSessionRecordsExist: () => boolean;
 export declare const detectClaudeSessionByPid: (panePid: number, paneCwd: string | null, deps?: PidResolveDeps) => PidSessionRecord | null;
 export declare const detectClaudeSessionIdByPid: (panePid: number, paneCwd: string | null, deps?: PidResolveDeps) => string | null;
 /**
- * The name of the session running in this pane. No mtime fallback exists here:
- * the transcript filenames the heuristic walks carry a UUID and nothing else,
- * so an older CC without `~/.claude/sessions` yields no name and the phone
- * keeps the computed label.
+ * What the phone should call the Claude Code session in this pane, and who
+ * chose it.
+ *
+ * A `/rename` (`nameSource: "user"`) wins. Otherwise the newest `ai-title` CC
+ * wrote into the transcript — its own summary of the work, which is what tells
+ * parallel sessions apart. A derived name (`hybrid-shell-8f`, from the cwd)
+ * is never sent: it says no more than the tmux name the phone falls back to.
+ * A record from an older CC carries a name but no `nameSource`; that one is
+ * sent as before, with no source, ahead of any ai-title, since it may be the
+ * user's rename. No mtime
+ * fallback: only the pid match says which session this pane is.
  */
-export declare const detectClaudeSessionNameByPid: (panePid: number, paneCwd: string | null, deps?: PidResolveDeps) => string | null;
+export declare const detectClaudeProviderName: (panePid: number, paneCwd: string | null, deps?: PidResolveDeps & {
+    transcriptOf?: (cwd: string, sessionId: string) => string | null;
+}) => ProviderName | null;
 /**
  * The transcript file for the Claude Code session running in a tmux pane.
  *
@@ -241,6 +259,15 @@ export declare const claudeTranscriptPath: (paneCwd: string | null, panePid?: nu
  * until the TTL ran out.
  */
 export declare const piTranscriptPath: (paneCwd: string | null, panePid?: number) => string | null;
+/**
+ * The name a pi pane's session goes by, and who chose it: the newest
+ * `session_info` name, which is the agent's (`'auto'`) when the hwip
+ * extension's tool set it — the tool leaves a marker entry with the same name
+ * (`PI_TITLE_MARKER`) — and the user's (`/name`) otherwise. Read from the
+ * transcript tail, so a name written before the last 256 KB of a session the
+ * listener first meets late is not found until the next one is written.
+ */
+export declare const detectPiSessionName: (paneCwd: string, panePid: number | undefined, transcriptOf?: (paneCwd: string, panePid?: number) => string | null) => ProviderName | null;
 /**
  * The row whose timestamp is closest to when one of the pane's processes started,
  * within {@link PROC_MATCH_TOLERANCE_MS}. Null when nothing qualifies — including
@@ -248,6 +275,18 @@ export declare const piTranscriptPath: (paneCwd: string | null, panePid?: number
  * are collected before any row is compared rather than defaulted to zero.
  */
 export declare const pickRowByProcStart: <T>(rows: readonly T[], tsMsOf: (row: T) => number | null, startTimes: Map<number, number>, pids: Set<number>) => T | null;
+/**
+ * From when a conversation written to is this pane's: its earliest process start, less {@link PANE_WRITE_MARGIN_MS}. A
+ * resume writes to the conversation it picked back up, so that one is written to after the start; a fresh start
+ * has not written yet, so the folder's older conversations are all before it. Null when no start is known.
+ */
+export declare const paneSince: (panePid: number, deps?: StoreResolveDeps) => number | null;
+/**
+ * The conversation a transcript file holds — its name without `.jsonl` — when it was written to since `since`.
+ * For the agents whose resume appends to the file it picks back up (pi `-c`, Codex `resume`, Gemini `--resume`,
+ * measured 2026-10-20): the file is the conversation.
+ */
+export declare const transcriptIdSince: (path: string | null, since: number | null) => string | null;
 /**
  * Read rows from a SQLite file as JSON. Null on every failure — no `sqlite3` on
  * PATH, a locked or corrupt database, a schema that moved — because a missing
@@ -267,7 +306,12 @@ export interface StoreResolveDeps {
     startTimes?: Map<number, number>;
     descendants?: Set<number>;
 }
-export declare const detectHermesSessionName: (paneCwd: string, panePid?: number, deps?: StoreResolveDeps) => string | null;
+export declare const detectHermesSessionName: (paneCwd: string, panePid?: number, deps?: StoreResolveDeps) => ProviderName | null;
+/**
+ * The Hermes session this pane carries on: in its directory, with a message since the pane started — the newest.
+ * A `-c` picks back up a session started long before the pane, which the start-time match above cannot see.
+ */
+export declare const detectHermesResumeId: (paneCwd: string, panePid?: number, deps?: StoreResolveDeps) => string | null;
 /**
  * The highest-numbered match, numerically. Codex versions its state file
  * (`state_5.sqlite` today) and moves to the next number on a schema migration,
@@ -286,7 +330,7 @@ export declare const newestVersionedDb: (entries: readonly string[], pattern: Re
  * AND a creation time within the tolerance of a process in this pane. Add the
  * filter once the values can be observed.
  */
-export declare const detectCodexSessionName: (paneCwd: string, panePid?: number, deps?: StoreResolveDeps) => string | null;
+export declare const detectCodexSessionName: (paneCwd: string, panePid?: number, deps?: StoreResolveDeps) => ProviderName | null;
 export declare const codexTranscriptPath: (paneCwd: string | null, panePid?: number) => string | null;
 /**
  * The transcript a Gemini pane is writing, or null when there is none to follow.
@@ -322,7 +366,7 @@ declare const REMOTE_AGENT_TABLE: readonly [{
     readonly subcommands: readonly ["cc", "claude"];
     readonly quitCommand: "/exit";
     readonly resolveSessionId: (paneCwd: string, panePid: number | undefined) => string | null;
-    readonly resolveSessionName: (paneCwd: string, panePid: number | undefined) => string | null;
+    readonly resolveSessionName: (paneCwd: string, panePid: number | undefined) => ProviderName | null;
     readonly resolveTranscript: (paneCwd: string, panePid: number | undefined) => string | null;
     readonly projectTranscript: TranscriptProjector;
     readonly resolveResumeId: (paneCwd: string, panePid: number | undefined) => string | null;
@@ -332,9 +376,10 @@ declare const REMOTE_AGENT_TABLE: readonly [{
     readonly displayName: "Codex CLI";
     readonly binary: "codex";
     readonly subcommands: readonly ["codex"];
-    readonly resolveSessionName: (paneCwd: string, panePid?: number, deps?: StoreResolveDeps) => string | null;
+    readonly resolveSessionName: (paneCwd: string, panePid?: number, deps?: StoreResolveDeps) => ProviderName | null;
     readonly resolveTranscript: (paneCwd: string, panePid: number | undefined) => string | null;
     readonly projectTranscript: TranscriptProjector;
+    readonly resolveResumeId: (paneCwd: string, panePid: number | undefined) => string | null;
 }, {
     readonly kind: "cursor";
     readonly displayName: "Cursor CLI";
@@ -347,12 +392,14 @@ declare const REMOTE_AGENT_TABLE: readonly [{
     readonly subcommands: readonly ["gemini"];
     readonly resolveTranscript: (paneCwd: string, panePid: number | undefined) => string | null;
     readonly projectTranscript: TranscriptProjector;
+    readonly resolveResumeId: (paneCwd: string, panePid: number | undefined) => string | null;
 }, {
     readonly kind: "hermes";
     readonly displayName: "Hermes";
     readonly binary: "hermes";
     readonly subcommands: readonly ["hermes"];
-    readonly resolveSessionName: (paneCwd: string, panePid?: number, deps?: StoreResolveDeps) => string | null;
+    readonly resolveSessionName: (paneCwd: string, panePid?: number, deps?: StoreResolveDeps) => ProviderName | null;
+    readonly resolveResumeId: (paneCwd: string, panePid?: number, deps?: StoreResolveDeps) => string | null;
 }, {
     readonly kind: "pi";
     readonly displayName: "Pi";
@@ -360,6 +407,8 @@ declare const REMOTE_AGENT_TABLE: readonly [{
     readonly subcommands: readonly ["pi"];
     readonly resolveTranscript: (paneCwd: string, panePid: number | undefined) => string | null;
     readonly projectTranscript: TranscriptProjector;
+    readonly resolveResumeId: (paneCwd: string, panePid: number | undefined) => string | null;
+    readonly resolveSessionName: (paneCwd: string, panePid: number | undefined) => ProviderName | null;
 }, {
     readonly kind: "opencode";
     readonly displayName: "OpenCode";
@@ -367,7 +416,10 @@ declare const REMOTE_AGENT_TABLE: readonly [{
     readonly subcommands: readonly ["opencode"];
     readonly quitCommand: "/exit";
     readonly resolveSessionId: (paneCwd: string, panePid: number | undefined) => string | null;
-    readonly resolveSessionName: (paneCwd: string, panePid: number | undefined) => string | null;
+    readonly resolveSessionName: (paneCwd: string, panePid: number | undefined) => {
+        name: string;
+        source: "auto";
+    } | null;
     readonly resolveTranscript: (paneCwd: string, panePid: number | undefined) => string | null;
     readonly projectTranscript: TranscriptProjector;
     readonly readTranscript: (path: string, prev: import("./transcript-tail.js").TailState | null) => import("./transcript-tail.js").TailRead | null;