@hwip/cli 0.1.3 → 0.1.4

package/README.md

@@ -39,6 +39,17 @@ Codex / …). Safe to re-run: a saved login is reused untouched (no
 prompts), so a re-run just refreshes the agent integrations. To switch
 account, `hwip install --relogin` forces a fresh sign-in.
 
+**Auto session names.** Agents without a title of their own — Codex,
+Cursor, Windsurf, Gemini and pi — name their sessions after what they were
+asked, so the phone shows that instead of a tmux name. The registrations
+`hwip install` writes turn it on (`HWIP_AUTONAME=1` in the MCP entry, the
+`hwip_session_title` tool in the pi extension), so **after updating
+`@hwip/cli`, run `hwip install` once more** to get it on a machine
+installed before; `hwip verify` says which MCP agents still lack it. Claude
+Code and opencode title sessions themselves and are left as they are. To
+hide the names agents choose, turn off *Name sessions automatically* in
+the app's settings — names you set yourself always show.
+
 **Why global, not `npx`?** `hwip cc` (drive a session from your phone)
 needs `hwip` on your `PATH`, and the agent hooks this installs are
 `$(command -v hwip || npx …)` — a global binary skips an npx cold-start
@@ -432,17 +443,28 @@ block here.
    hwip sh --detach     # create it, print its name, exit
    ```
 
-   **The mirror fits a detached session to the phone.** A pane is as wide
-   as the terminal that last drew it, so a desktop's prompt rules and
-   right-aligned clocks fold in two on a phone. While the phone watches a
-   session no terminal is attached to (a `hwip sh --detach` shell, or an
-   agent whose terminal you closed), the listener resizes its window to the
-   phone's width and gives the old width back when the phone leaves. An
-   attached session keeps its size: shrinking it would shrink your desktop
-   terminal, so the phone wraps those rows instead. A window split into
-   panes is never resized, and one a terminal attaches to while the phone
-   watches is handed back within a renew (5 s). A listener that died while
-   a window was fitted restores it the next time it starts.
+   **The mirror fits a session to the phone.** A pane is as wide as the
+   terminal that last drew it, so a desktop's prompt rules and
+   right-aligned clocks fold in two on a phone. Whoever used the session
+   last decides its width, the way tmux's `window-size latest` does: typing
+   from the phone makes the phone the latest user, and the listener resizes
+   the window to the phone's width, and coming back to the mirror later
+   (a locked screen, a resubscribe) takes it again unless the desktop was
+   used since. Opening the mirror without typing does the same once
+   the desktop terminal has been idle for a minute, so a phone reconnecting
+   on its own never shrinks a terminal you are typing in. Pressing a key in
+   (or attaching) a desktop terminal makes it the latest user, and within a
+   renew (5 s) the window is handed back to tmux, which sizes it to that
+   terminal. Moving the mouse over a desktop pane or clicking another
+   pane is not using it: on macOS the listener reads when a key was last
+   pressed (the HID system clock, no permission needed) and counts a
+   desktop terminal as used no later than that key or its attach. Elsewhere
+   any tmux client activity counts. While the phone holds a session, a desktop terminal still
+   attached to it shows it narrower. When the phone leaves, a session no
+   terminal is attached to gets its old width back and an attached one is
+   sized to its terminal. A window split into panes is never resized. A
+   listener that died while a window was fitted restores it the next time
+   it starts.
 
    `hwip cursor` runs **`cursor-agent`**, Cursor's terminal agent — a
    separate install from the Cursor IDE (the bare `cursor` on your PATH

package/dist/agents.d.ts

@@ -10,6 +10,16 @@
  * pi 0.85.1): global is `~/.pi/agent/skills/` and `~/.agents/skills/`, while
  * `.pi/skills/` is the PROJECT dir — scanning `~/.pi/skills` found only three
  * dangling symlinks and reported pi as having no skills at all.
+ *
+ * codex reads `$CODEX_HOME/skills` and `~/.agents/skills` (codex-rs
+ * `ext/skills/src/host_roots.rs`), and keeps its bundled skills in the hidden
+ * `.codex/skills/.system`, which the scanner's dot-skip would otherwise pass
+ * over. opencode reads the claude and agents dirs as well as its own
+ * (opencode `docs/skills.mdx § Discovery`, 2.0.29). Measured against the agents'
+ * own reports on 2026-10-20: codex 59 of `codex app-server` `skills/list` 59;
+ * opencode 87 of `opencode serve` `/api/skill` 91 — the rest are two built-ins
+ * and two skills it reads out of `~/.claude/skills/.trash/`, which the scanner's
+ * dot-skip leaves out on purpose.
  */
 export declare const AGENT_SKILL_DIRS: Record<string, string[]>;
 export interface Agent {

package/dist/agents.js

@@ -20,10 +20,21 @@ const path_1 = require("path");
  * pi 0.85.1): global is `~/.pi/agent/skills/` and `~/.agents/skills/`, while
  * `.pi/skills/` is the PROJECT dir — scanning `~/.pi/skills` found only three
  * dangling symlinks and reported pi as having no skills at all.
+ *
+ * codex reads `$CODEX_HOME/skills` and `~/.agents/skills` (codex-rs
+ * `ext/skills/src/host_roots.rs`), and keeps its bundled skills in the hidden
+ * `.codex/skills/.system`, which the scanner's dot-skip would otherwise pass
+ * over. opencode reads the claude and agents dirs as well as its own
+ * (opencode `docs/skills.mdx § Discovery`, 2.0.29). Measured against the agents'
+ * own reports on 2026-10-20: codex 59 of `codex app-server` `skills/list` 59;
+ * opencode 87 of `opencode serve` `/api/skill` 91 — the rest are two built-ins
+ * and two skills it reads out of `~/.claude/skills/.trash/`, which the scanner's
+ * dot-skip leaves out on purpose.
  */
 exports.AGENT_SKILL_DIRS = {
     claude: ['.claude/skills'],
-    codex: ['.codex/skills'],
+    codex: ['.codex/skills', '.codex/skills/.system', '.agents/skills'],
+    opencode: ['.claude/skills', '.agents/skills', '.config/opencode/skills'],
     pi: ['.pi/agent/skills', '.agents/skills'],
 };
 const HOME = (0, os_1.homedir)();

package/dist/codex-config.d.ts

@@ -1,8 +1,8 @@
-/** The table hwip writes into a config that has none. No `env` block, unlike
- *  the Cursor/Windsurf JSON entry: codex is a terminal app, so the server
- *  inherits the shell's `HWIP_API_KEY`, and an unexpanded `"${HWIP_API_KEY}"`
- *  literal would shadow the ~/.hwip/config.json fallback with junk (the same
- *  reasoning as opencode's). */
+/** The table hwip writes into a config that has none. Its `env` holds only the
+ *  auto-name flag, unlike the Cursor/Windsurf JSON entry: codex is a terminal
+ *  app, so the server inherits the shell's `HWIP_API_KEY`, and an unexpanded
+ *  `"${HWIP_API_KEY}"` literal would shadow the ~/.hwip/config.json fallback
+ *  with junk (the same reasoning as opencode's). */
 export declare const CODEX_MCP_TABLE: string;
 /**
  * The config with hwip's entry present and current, leaving every other byte
@@ -10,6 +10,9 @@ export declare const CODEX_MCP_TABLE: string;
  * it, so nothing above can capture the keys.
  */
 export declare const upsertHwipMcpTable: (config: string) => string;
+/** Whether hwip's entry turns auto names on — what verify checks to tell an
+ *  install from before the flag existed. */
+export declare const hasHwipAutoName: (config: string) => boolean;
 /** The config with hwip's entry and its sub-tables gone, or null when it was
  *  never there (so the caller can report "nothing to remove" rather than
  *  rewriting an untouched file). */

package/dist/codex-config.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.readHwipMcpArgv = exports.removeHwipMcpTable = exports.upsertHwipMcpTable = exports.CODEX_MCP_TABLE = void 0;
+exports.readHwipMcpArgv = exports.removeHwipMcpTable = exports.hasHwipAutoName = exports.upsertHwipMcpTable = exports.CODEX_MCP_TABLE = void 0;
 /**
  * The hwip entry inside `~/.codex/config.toml`, which Codex CLI owns.
  *
@@ -18,8 +18,10 @@ exports.readHwipMcpArgv = exports.removeHwipMcpTable = exports.upsertHwipMcpTabl
  *    `[mcp_servers.hwip.tools.hwip_ask]` when the user picks "always allow".
  *    Removal takes them along (a child of a deleted server is dead config);
  *    re-install keeps them, since they are the user's answer, not ours.
- *  - **Only `command` and `args` are ours.** Any other key in the table —
- *    `cwd`, `startup_timeout_sec`, a comment — survives a re-install.
+ *  - **Only `command`, `args` and the `HWIP_AUTONAME` env pair are ours.** Any
+ *    other key in the table — `cwd`, `startup_timeout_sec`, a comment, the
+ *    user's own env pairs — survives a re-install; the flag joins whichever
+ *    env the user already keeps.
  *  - **Comments before the next table belong to that table**, not to ours, so
  *    the region we replace or delete stops short of them.
  *
@@ -31,6 +33,8 @@ const [MCP_BIN, ...MCP_SUBCOMMAND] = mcp_command_js_1.MCP_LAUNCH_ARGV;
 const HWIP_TABLE_HEADER = /^\[mcp_servers\.(?:hwip|"hwip")\]$/;
 /** A sub-table of ours: `[mcp_servers.hwip.tools.hwip_ask]` and friends. */
 const HWIP_SUBTABLE_HEADER = /^\[mcp_servers\.(?:hwip|"hwip")\..+\]$/;
+/** The user's own env table for hwip — where the flag goes when they keep one. */
+const HWIP_ENV_SUBTABLE_HEADER = /^\[mcp_servers\.(?:hwip|"hwip")\.(?:env|"env")\]$/;
 /**
  * The dotted/inline form — `mcp_servers.hwip = { command = "npx", … }` — which
  * is valid TOML and which older hand-written configs use. It has to be found,
@@ -44,12 +48,87 @@ const isHwipDefinition = (line) => HWIP_TABLE_HEADER.test(line.trim()) || HWIP_I
 const OWNED_KEY = /^(?:command|args)\s*=/;
 const commandLine = `command = "${MCP_BIN}"`;
 const argsLine = `args = [${MCP_SUBCOMMAND.map((a) => `"${a}"`).join(', ')}]`;
-/** The table hwip writes into a config that has none. No `env` block, unlike
- *  the Cursor/Windsurf JSON entry: codex is a terminal app, so the server
- *  inherits the shell's `HWIP_API_KEY`, and an unexpanded `"${HWIP_API_KEY}"`
- *  literal would shadow the ~/.hwip/config.json fallback with junk (the same
- *  reasoning as opencode's). */
-exports.CODEX_MCP_TABLE = ['[mcp_servers.hwip]', commandLine, argsLine].join('\n');
+const flagPair = `${mcp_command_js_1.AUTONAME_ENV} = "1"`;
+const envLine = `env = { ${flagPair} }`;
+/** `env = { … }` in hwip's table — known by its key, so a comment after it cannot hide it. */
+const INLINE_ENV = /^env\s*=\s*\{/;
+/** `env.KEY = …`, the dotted spelling of the same table. */
+const DOTTED_ENV = /^env\./;
+/** The flag's key, bare or quoted: TOML reads all three as one key. */
+const FLAG = `(?:${mcp_command_js_1.AUTONAME_ENV}|"${mcp_command_js_1.AUTONAME_ENV}"|'${mcp_command_js_1.AUTONAME_ENV}')`;
+const FLAG_KEY = new RegExp(`^${FLAG}\\s*=`);
+const DOTTED_FLAG_KEY = new RegExp(`^env\\.${FLAG}\\s*=`);
+const FLAG_ON = new RegExp(`(?:^|[\\s{,.])${FLAG}\\s*=\\s*["']1["']`);
+/** The table hwip writes into a config that has none. Its `env` holds only the
+ *  auto-name flag, unlike the Cursor/Windsurf JSON entry: codex is a terminal
+ *  app, so the server inherits the shell's `HWIP_API_KEY`, and an unexpanded
+ *  `"${HWIP_API_KEY}"` literal would shadow the ~/.hwip/config.json fallback
+ *  with junk (the same reasoning as opencode's). */
+exports.CODEX_MCP_TABLE = ['[mcp_servers.hwip]', commandLine, argsLine, envLine].join('\n');
+/**
+ * Walks a line of TOML outside its strings: `at(i, depth)` sees every character that is not
+ * inside one, with the brace depth before it, and stops the walk by returning true.
+ */
+const walkOutsideStrings = (text, from, at) => {
+    let depth = 0;
+    let quote = null;
+    for (let i = from; i < text.length; i += 1) {
+        const ch = text[i];
+        if (quote) {
+            if (ch === '\\' && quote === '"')
+                i += 1;
+            else if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            continue;
+        }
+        if (at(i, depth))
+            return;
+        if (ch === '{' || ch === '[')
+            depth += 1;
+        else if (ch === '}' || ch === ']')
+            depth -= 1;
+    }
+};
+/** The inline table's inside and what follows its closing brace (a comment), or null when it does
+ *  not close on this line. */
+const inlineParts = (line) => {
+    const open = line.indexOf('{');
+    let parts = null;
+    walkOutsideStrings(line, open, (i, depth) => {
+        if (line[i] !== '}' || depth !== 1)
+            return false;
+        parts = { inner: line.slice(open + 1, i), tail: line.slice(i + 1) };
+        return true;
+    });
+    return parts;
+};
+/** The pairs of an inline table, split at its own commas — never one inside a string or a nested value. */
+const inlinePairs = (inner) => {
+    const pairs = [];
+    let start = 0;
+    walkOutsideStrings(inner, 0, (i, depth) => {
+        if (inner[i] === ',' && depth === 0) {
+            pairs.push(inner.slice(start, i));
+            start = i + 1;
+        }
+        return false;
+    });
+    pairs.push(inner.slice(start));
+    return pairs.map((pair) => pair.trim()).filter(Boolean);
+};
+/** An inline env table with the flag on and first, the user's pairs and comment kept. One that
+ *  cannot be read is left alone: writing a second `env` beside it would break the whole file. */
+const withFlag = (line) => {
+    const parts = inlineParts(line);
+    if (!parts)
+        return line;
+    const rest = inlinePairs(parts.inner).filter((pair) => !FLAG_KEY.test(pair));
+    return `env = { ${[flagPair, ...rest].join(', ')} }${parts.tail}`;
+};
 /** CRLF in, CRLF out — a Windows config must not come back with mixed endings. */
 const eolOf = (config) => (config.includes('\r\n') ? '\r\n' : '\n');
 const splitLines = (config) => config.split(/\r?\n/);
@@ -109,18 +188,48 @@ const upsertHwipMcpTable = (config) => {
         const table = exports.CODEX_MCP_TABLE.split('\n');
         return rejoin([...lines.slice(0, start), ...table, ...lines.slice(start + 1)], eol);
     }
+    // A key defined twice makes codex refuse the whole file, so the flag goes
+    // into whichever env the user already keeps, and gets one only if none.
+    const envTable = lines.slice(bodyEnd(lines, start), entryEnd(lines, start))
+        .findIndex((line) => HWIP_ENV_SUBTABLE_HEADER.test(line.trim()));
+    const after = [...lines];
+    if (envTable !== -1) {
+        const header = bodyEnd(lines, start) + envTable;
+        const tableEnd = bodyEnd(lines, header);
+        const rows = lines.slice(header + 1, tableEnd).filter((line) => !FLAG_KEY.test(line.trim()));
+        after.splice(header, tableEnd - header, lines[header], flagPair, ...rows);
+    }
     const end = withoutTrailingPreamble(lines, start, bodyEnd(lines, start));
-    const kept = lines.slice(start + 1, end).filter((line) => !OWNED_KEY.test(line.trim()));
+    const kept = lines.slice(start + 1, end)
+        .filter((line) => !OWNED_KEY.test(line.trim()) && !DOTTED_FLAG_KEY.test(line.trim()));
+    const inline = kept.findIndex((line) => INLINE_ENV.test(line.trim()));
+    if (inline !== -1)
+        kept[inline] = withFlag(kept[inline].trim());
+    const ours = envTable !== -1 || inline !== -1 ? []
+        : kept.some((line) => DOTTED_ENV.test(line.trim())) ? [`env.${flagPair}`]
+            : [envLine];
     return rejoin([
-        ...lines.slice(0, start),
+        ...after.slice(0, start),
         '[mcp_servers.hwip]',
         commandLine,
         argsLine,
+        ...ours,
         ...kept,
-        ...lines.slice(end),
+        ...after.slice(end),
     ], eol);
 };
 exports.upsertHwipMcpTable = upsertHwipMcpTable;
+/** Whether hwip's entry turns auto names on — what verify checks to tell an
+ *  install from before the flag existed. */
+const hasHwipAutoName = (config) => {
+    const lines = splitLines(config);
+    const start = definitionIndex(lines);
+    if (start === -1)
+        return false;
+    const end = HWIP_INLINE_ENTRY.test(lines[start].trim()) ? start + 1 : entryEnd(lines, start);
+    return lines.slice(start, end).some((line) => !line.trim().startsWith('#') && FLAG_ON.test(line.trim()));
+};
+exports.hasHwipAutoName = hasHwipAutoName;
 /** The config with hwip's entry and its sub-tables gone, or null when it was
  *  never there (so the caller can report "nothing to remove" rather than
  *  rewriting an untouched file). */

package/dist/command-scan.d.ts

@@ -4,8 +4,9 @@
  * Payload discipline (plan PLAN-13-16-18): paths never leave this machine, so
  * the output carries skill names and nothing else.
  *
- * An entry is the slash command itself, so it carries whatever prefix the agent
- * registers the skill under (`AGENT_SKILL_PREFIX`, plugin names for Claude Code).
+ * An entry is the invocation token itself, so it carries whatever prefix the
+ * agent registers the skill under (`AGENT_SKILL_PREFIX`, plugin names for Claude
+ * Code) — including the `$`/`@` mention sigil of agents that take no slash.
  *
  * Names come from the directory, not from the file — an ASSUMPTION, not a rule
  * the agents enforce: pi resolves a skill's name as `frontmatter.name` and only
@@ -23,7 +24,10 @@
  * existence until a divergent skill is actually measured.
  */
 export interface AgentCommandEntry {
-    /** What the user types after `/` — see `AGENT_SKILL_PREFIX`. */
+    /**
+     * What the user types to run the skill: after a `/`, unless it starts with a
+     * mention sigil (`$`, `@`), which is typed as is — see `AGENT_SKILL_PREFIX`.
+     */
     name: string;
 }
 /** agentKind -> skill entries; agents with no skills are omitted. */

package/dist/command-scan.js

@@ -13,12 +13,24 @@ const agents_js_1 = require("./agents.js");
  * pi session was observed to abort rather than run the skill (2026-09-13).
  * Claude Code's user skills are `/<name>`; its PLUGIN skills are
  * `/<plugin>:<name>`, so those get their prefix from the install entry instead.
+ *
+ * codex and opencode do not run skills as slash commands at all. codex takes a
+ * `$name` mention (codex-rs `skills/src/selection.rs`; its `/skills` only opens a
+ * picker), and opencode 2.0 an `@name` mention (`docs/skills.mdx § Loading`; its
+ * `/api/command` lists no skills). Their entries carry that sigil, and a client
+ * inserts a name starting with `$` or `@` as typed, without the `/`.
  */
 const AGENT_SKILL_PREFIX = {
+    codex: '$',
+    opencode: '@',
     pi: 'skill:',
 };
-/** Agents that register skills filed under grouping folders — see `scanSkillDir`. */
-const AGENT_SKILL_RECURSIVE = new Set(['pi']);
+/**
+ * Agents that register skills filed under grouping folders — see `scanSkillDir`.
+ * opencode walks them too: it lists `~/.claude/skills/synced/<id>/<name>`, which
+ * Claude Code itself does not register (`/api/skill`, 2026-10-20).
+ */
+const AGENT_SKILL_RECURSIVE = new Set(['opencode', 'pi']);
 /** Serialized-catalog budget. Names-only measures ~2KB here; ws frames die at 128KB. */
 exports.PAYLOAD_LIMIT_BYTES = 64 * 1024;
 /**
@@ -88,28 +100,60 @@ const scanSkillDir = (dir, recursive = false, depth = 1) => {
     }
     return names;
 };
-/**
- * Plugin skills live at `<installPath>/skills/<name>/SKILL.md`. Only install paths
- * listed in `installed_plugins.json` are scanned — the plugin cache also holds
- * uninstalled marketplace entries (514 of 710 on this machine) that must not
- * appear.
- */
-const scanClaudePlugins = (home) => {
+/** A plain JSON object, as opposed to an array, a scalar or null. */
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** The object under `key` in a JSON file, or an empty one when the file is missing, not JSON, or holds another shape there. */
+const readJsonObject = (file, key) => {
     let parsed;
     try {
-        parsed = JSON.parse((0, fs_1.readFileSync)((0, path_1.join)(home, '.claude', 'plugins', 'installed_plugins.json'), 'utf-8'));
+        parsed = JSON.parse((0, fs_1.readFileSync)(file, 'utf-8'));
     }
     catch {
-        return [];
+        return {};
     }
+    const value = isObject(parsed) ? parsed[key] : undefined;
+    return isObject(value) ? value : {};
+};
+/**
+ * Plugin keys Claude Code loads: `enabledPlugins[key] === true` in the user's
+ * `~/.claude/settings.json`. Installed is not enabled — a key set to `false`, or
+ * absent, registers nothing (`claude -p` init `slash_commands`, 2026-10-20: 71
+ * skills of two disabled plugins and one unlisted plugin were missing). A
+ * project's own settings can enable more, but the catalog is device-level.
+ */
+const enabledClaudePlugins = (home) => {
+    const enabled = readJsonObject((0, path_1.join)(home, '.claude', 'settings.json'), 'enabledPlugins');
+    return new Set(Object.entries(enabled).filter(([, on]) => on === true).map(([key]) => key));
+};
+/** Command files of a plugin: `<installPath>/commands/<name>.md`. */
+const scanCommandFiles = (dir) => entriesOf(dir)
+    .filter((entry) => entry.endsWith('.md') && !entry.startsWith('.'))
+    .map((entry) => entry.slice(0, -'.md'.length));
+/**
+ * Plugin commands are `<installPath>/skills/<name>/SKILL.md` and
+ * `<installPath>/commands/<name>.md`, both registered as `/<plugin>:<name>`. Only
+ * install paths listed in `installed_plugins.json` are scanned — the plugin cache
+ * also holds uninstalled marketplace entries (514 of 710 on this machine) that
+ * must not appear — and of those only the enabled ones.
+ */
+const scanClaudePlugins = (home) => {
+    const installed = readJsonObject((0, path_1.join)(home, '.claude', 'plugins', 'installed_plugins.json'), 'plugins');
+    const enabled = enabledClaudePlugins(home);
     const names = [];
-    for (const [key, installs] of Object.entries(parsed.plugins ?? {})) {
+    for (const [key, installs] of Object.entries(installed)) {
+        if (!enabled.has(key) || !Array.isArray(installs))
+            continue;
         // Key is `<plugin>@<marketplace>`; the command prefix is the plugin half.
         const plugin = key.split('@')[0];
-        for (const install of installs ?? []) {
-            if (!install.installPath)
+        for (const install of installs) {
+            const installPath = isObject(install) ? install.installPath : undefined;
+            if (typeof installPath !== 'string' || !installPath)
                 continue;
-            names.push(...scanSkillDir((0, path_1.join)(install.installPath, 'skills')).map((name) => `${plugin}:${name}`));
+            const commands = [
+                ...scanSkillDir((0, path_1.join)(installPath, 'skills')),
+                ...scanCommandFiles((0, path_1.join)(installPath, 'commands')),
+            ];
+            names.push(...commands.map((name) => `${plugin}:${name}`));
         }
     }
     return names;

package/dist/installer.js

@@ -334,7 +334,13 @@ const installGemini = () => {
             ok('MCP server added (legacy gemini CLI)');
         }
         catch {
-            fail(`MCP add failed. Manual: ${mcp_command_js_1.GEMINI_MCP_ADD}`);
+            try {
+                (0, child_process_1.execSync)(mcp_command_js_1.GEMINI_MCP_ADD_BARE, { stdio: 'pipe' });
+                ok('MCP server added (legacy gemini CLI, without auto session names)');
+            }
+            catch {
+                fail(`MCP add failed. Manual: ${mcp_command_js_1.GEMINI_MCP_ADD}`);
+            }
         }
     }
     try {

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
@@ -274,6 +281,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

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");
@@ -328,7 +328,7 @@ 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 +588,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
@@ -2076,9 +2081,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 +2612,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 +2656,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 +3057,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 +3475,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 +3493,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),
@@ -4935,6 +4963,10 @@ const streamSession = (wsUrl, apiKey) => {
                 clearInterval(commandsTimer);
                 commandsTimer = null;
             }
+            if (paneFitTimer) {
+                clearInterval(paneFitTimer);
+                paneFitTimer = null;
+            }
             if (connectTimer) {
                 clearTimeout(connectTimer);
                 connectTimer = null;
@@ -4981,6 +5013,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 +5190,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();