@zeph-to/cli 1.22.0 → 1.24.0

package/README.md

@@ -5,31 +5,19 @@
 [![node](https://img.shields.io/node/v/@zeph-to/cli.svg)](https://nodejs.org)
 [![license](https://img.shields.io/npm/l/@zeph-to/cli.svg)](./LICENSE)
 
-Push notification SDK + CLI for [Zeph](https://zeph.to) — the terminal
-side of the round trip: your agent works, hits a decision, and asks your
-phone; you tap a button (or type a reply), and the answer lands back in
-the live session so the agent keeps going.
-
-- `ZephHook` SDK — native `fetch`, no runtime deps. Send/list/dismiss pushes.
-- `zeph` CLI — one-command setup for 8 AI agents, push sending, and an
-  optional resident listener that **drives Claude Code / Codex / Gemini
-  sessions from your phone** by injecting messages into named tmux
-  sessions.
-
-Part of the Zeph toolchain:
-[`@zeph-to/mcp-server`](https://github.com/zeph-to/mcp-server) (the MCP
-tools your agent calls, e.g. `zeph_ask`) ·
-[`zeph-to/plugin`](https://github.com/zeph-to/plugin) (Claude Code plugin
-bundling hooks + MCP + rules) · the [Zeph app](https://zeph.to) on your
-phone.
-
-## Installation
+**Your agent works, hits a decision, and asks your phone. You tap a button (or type a reply), and the answer lands back in the live session — so the agent keeps going.**
 
-```bash
-npm install -g @zeph-to/cli
-# or for one-off use
-npx @zeph-to/cli notify --title "Hello"
-```
+`@zeph-to/cli` is the terminal side of that round trip: a zero-dependency push SDK, a `zeph` CLI that wires up 8 AI agents in one command, and a resident listener that lets your phone **drive Claude Code / Codex / Gemini sessions** by typing straight into named tmux sessions.
+
+<p align="center">
+  <img src="https://zeph.to/readme/demo.gif" alt="Agent asks 'Deploy to prod?' on your phone; you tap Deploy; the session ships" width="560"><br>
+  <sub><em>Your agent asks on your phone → you tap <b>Deploy</b> → the session ships. No terminal.</em></sub>
+</p>
+
+- **`ZephHook` SDK** — native `fetch`, no runtime deps. Send / list / dismiss pushes.
+- **`zeph` CLI** — one-command setup for 8 agents, push sending, and the resident listener for phone-driven remote control.
+
+Part of the Zeph toolchain: [`@zeph-to/mcp-server`](https://github.com/zeph-to/mcp-server) (the MCP tools your agent calls, e.g. `zeph_ask`) · [`zeph-to/plugin`](https://github.com/zeph-to/plugin) (Claude Code plugin bundling hooks + MCP + rules) · the [Zeph app](https://zeph.to) on your phone.
 
 ## Quick Start
 
@@ -92,6 +80,10 @@ To **drive a Claude Code / Codex / Gemini session from your phone**, see
 > Send messages from your phone *into* a live Claude Code / Codex /
 > Gemini session — even after a `zeph_ask` polling window has expired.
 
+<p align="center">
+  <img src="https://zeph.to/readme/ask-phone.png" alt="A Zeph hook on the phone: a question with tappable answer buttons and a text field" width="300">
+</p>
+
 The MCP tools `zeph_ask` / `zeph_prompt` / `zeph_input` wait on a fixed
 timeout (120–600 s). Once that window closes the
 session becomes unaddressable from the phone, even though it's still
@@ -323,6 +315,10 @@ zeph list --limit 10 --type note
 zeph dismiss push_01JXY...
 zeph dismiss --all
 
+# Rename the current agent session (shows in the app's Agents list)
+zeph rename "Prod deploy"
+zeph rename --clear                # reset to the default name
+
 # Test connection
 zeph test
 
@@ -351,6 +347,7 @@ zeph notify --title "Hello" --json
 | `notify` | Send a push notification |
 | `list` | List recent push notifications |
 | `dismiss <id>` | Dismiss a push (or `--all`) |
+| `rename <name>` | Set the current agent session's display name in the app — run inside a `zeph cc` session (`--clear` resets). Auto-detects the tmux session + this machine's listener device id, so the alias lands on the right device |
 | `test` | Verify connection and API key |
 | `cc` · `codex` · `gemini` | Run the agent in a `zeph-<project>` tmux session (auto-suffixed `-2`, `-3`, … on attached collisions). Auto-spawns the background listener on first invocation so the phone picker just works. Trailing args pass through to the agent (`zeph cc --resume "..."`) |
 | `listener` | (Usually unnecessary — `zeph cc` autospawns it.) Resident daemon: subscribes via WebSocket, reports tmux session inventory every 5 s, injects `agent.command` pushes into the matching session. Run in the foreground for SDK development; otherwise let `zeph cc` manage it |

package/dist/cli.js

@@ -70,6 +70,8 @@ Commands:
   notify          Send a push notification
   list            List recent push notifications
   dismiss <id>    Dismiss a push notification (or --all)
+  rename <name>   Set this agent session's display name in the app
+                  (run inside a zeph cc session; --clear resets it)
   test            Send a test notification to verify setup
 ${usageAgentLines()}
                   (auto-suffixed -2/-3/… when another zeph cc is already
@@ -163,6 +165,53 @@ const createHook = (args) => {
         ...(baseUrl && { baseUrl }),
     });
 };
+/** Current tmux session name (the rename key), or null when not inside tmux. */
+const detectCurrentTmuxSession = () => {
+    if (!process.env.TMUX)
+        return null;
+    try {
+        const name = (0, child_process_1.execFileSync)('tmux', ['display-message', '-p', '#S'], { encoding: 'utf-8' }).trim();
+        return name || null;
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * `zeph rename "<name>"` — set THIS agent session's display name in the app.
+ * Auto-detects the current tmux session + this machine's listener device id
+ * (`computeListenerDeviceId`, the same id the listener registers, so the
+ * rename lands on the right device). `--clear` resets to the computed label.
+ */
+const handleRename = async (args) => {
+    const isJson = args.json === true;
+    const clearing = args.clear === true;
+    const alias = args._arg1 || '';
+    if (!alias && !clearing) {
+        printError('Usage: zeph rename "New name"  (or --clear to reset to default)', isJson);
+        return 2;
+    }
+    const sessionName = args.session || detectCurrentTmuxSession();
+    if (!sessionName) {
+        printError('No tmux session detected. Run inside a `zeph cc` session, or pass --session <name>.', isJson);
+        return 2;
+    }
+    const deviceId = args.device || (0, listener_js_1.computeListenerDeviceId)();
+    const hook = createHook(args);
+    if (!hook)
+        return 3;
+    try {
+        await hook.renameAgentSession(deviceId, sessionName, clearing ? '' : alias);
+        if (isJson)
+            printJson({ session: sessionName, alias: clearing ? null : alias, status: 'ok' });
+        else
+            console.log(clearing ? `Reset name for ${sessionName}` : `Renamed ${sessionName} → ${alias}`);
+        return 0;
+    }
+    catch (err) {
+        return handleError(err, isJson);
+    }
+};
 /** Parse a gate count flag; garbage input falls back to the default (never accidentally silences). */
 const gateCount = (raw, fallback) => {
     const n = typeof raw === 'string' ? Number(raw) : NaN;
@@ -408,6 +457,8 @@ const main = async () => {
             return handleList(args);
         case 'dismiss':
             return handleDismiss(args);
+        case 'rename':
+            return handleRename(args);
         case 'test':
             return handleTest(args);
         case 'listener':

package/dist/crypto.d.ts

@@ -27,6 +27,12 @@
  *   key). That refactor is on the roadmap; until then, treat push bodies as
  *   sensitive-but-not-secret.
  */
+interface EncryptedPayload {
+    ciphertext: string;
+    iv: string;
+    encryptedKey: string;
+    keyIv: string;
+}
 /**
  * Initialize crypto: sync keys with server, then fallback to local/generate.
  * Server is source of truth for per-user key pair.
@@ -80,4 +86,25 @@ export declare const encryptFileForSelf: (content: string) => Promise<{
     iv: string;
     encryptedKey: string;
 }>;
+/**
+ * Flat ephemeral envelope — field-for-field what the web's decrypt()
+ * (libs/crypto) consumes, with the sender public key riding along so the
+ * receiver needs no out-of-band key lookup.
+ */
+export interface EncryptedEphemeralPayload extends EncryptedPayload {
+    senderPublicKey: string;
+}
+/**
+ * Load-or-create the per-device keypair. Local-only — no server round-trip,
+ * no upload. Safe to call concurrently (dedupes to one init). Returns the
+ * exported public key (Base64 SPKI).
+ */
+export declare const initDeviceCrypto: () => Promise<string>;
+export declare const getDevicePublicKey: () => string | null;
+/**
+ * Encrypt an ephemeral payload (e.g. a stream frame) for one recipient
+ * device. Requires initDeviceCrypto() to have completed.
+ */
+export declare const encryptEphemeral: (plaintext: string, recipientPublicKeyRaw: string) => Promise<EncryptedEphemeralPayload>;
+export {};
 //# sourceMappingURL=crypto.d.ts.map

package/dist/crypto.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAiKH;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,SAAS,MAAM,EAAE,UAAU,MAAM,KAAG,OAAO,CAAC,MAAM,CAsE5E,CAAC;AA2CF,eAAO,MAAM,UAAU,QAAO,aAAa,GAAG,IAAqB,CAAC;AACpE,eAAO,MAAM,YAAY,QAAO,MAAM,GAAG,IAA+B,CAAC;AAEzE;;;GAGG;AACH,eAAO,MAAM,eAAe,GAC1B,OAAO;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,EACtD,uBAAuB,MAAM,KAC5B,OAAO,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,IAAI,CAAC;CACnB,CAeA,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,sBAAsB,GACjC,OAAO;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,KACrD,OAAO,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,IAAI,CAAC;CACnB,CAaA,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GAClC,SAAS,MAAM,EACf,uBAAuB,MAAM,KAC5B,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CASlE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAC7B,SAAS,MAAM,KACd,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAQlE,CAAC"}
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AA+EH,UAAU,gBAAgB;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AA6ED;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,SAAS,MAAM,EAAE,UAAU,MAAM,KAAG,OAAO,CAAC,MAAM,CAsE5E,CAAC;AA2CF,eAAO,MAAM,UAAU,QAAO,aAAa,GAAG,IAAqB,CAAC;AACpE,eAAO,MAAM,YAAY,QAAO,MAAM,GAAG,IAA+B,CAAC;AAEzE;;;GAGG;AACH,eAAO,MAAM,eAAe,GAC1B,OAAO;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,EACtD,uBAAuB,MAAM,KAC5B,OAAO,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,IAAI,CAAC;CACnB,CAeA,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,sBAAsB,GACjC,OAAO;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,KACrD,OAAO,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,IAAI,CAAC;CACnB,CAaA,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,uBAAuB,GAClC,SAAS,MAAM,EACf,uBAAuB,MAAM,KAC5B,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CASlE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAC7B,SAAS,MAAM,KACd,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAQlE,CAAC;AAWF;;;;GAIG;AACH,MAAM,WAAW,yBAA0B,SAAQ,gBAAgB;IACjE,eAAe,EAAE,MAAM,CAAC;CACzB;AAsBD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,QAAO,OAAO,CAAC,MAAM,CAoBjD,CAAC;AAEF,eAAO,MAAM,kBAAkB,QAAO,MAAM,GAAG,IAA+B,CAAC;AAE/E;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAC3B,WAAW,MAAM,EACjB,uBAAuB,MAAM,KAC5B,OAAO,CAAC,yBAAyB,CAKnC,CAAC"}

package/dist/crypto.js

@@ -29,7 +29,7 @@
  *   sensitive-but-not-secret.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.encryptFileForSelf = exports.encryptFileForRecipient = exports.encryptPushBodyForSelf = exports.encryptPushBody = exports.getPublicKey = exports.getKeyPair = exports.initCrypto = void 0;
+exports.encryptEphemeral = exports.getDevicePublicKey = exports.initDeviceCrypto = exports.encryptFileForSelf = exports.encryptFileForRecipient = exports.encryptPushBodyForSelf = exports.encryptPushBody = exports.getPublicKey = exports.getKeyPair = exports.initCrypto = void 0;
 /// <reference lib="dom" />
 const fs_1 = require("fs");
 const os_1 = require("os");
@@ -301,3 +301,62 @@ const encryptFileForSelf = async (content) => {
     };
 };
 exports.encryptFileForSelf = encryptFileForSelf;
+const DEVICE_KEYS_DIR = (0, path_1.join)((0, os_1.homedir)(), '.zeph');
+const DEVICE_KEYS_PATH = (0, path_1.join)(DEVICE_KEYS_DIR, 'device-keys.json');
+let deviceKeyPair = null;
+let deviceExportedPublicKey = null;
+let deviceInitPromise = null;
+const loadStoredDeviceKeys = () => {
+    try {
+        return JSON.parse((0, fs_1.readFileSync)(DEVICE_KEYS_PATH, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+};
+const storeDeviceKeys = (exported) => {
+    (0, fs_1.mkdirSync)(DEVICE_KEYS_DIR, { recursive: true, mode: 0o700 });
+    (0, fs_1.writeFileSync)(DEVICE_KEYS_PATH, JSON.stringify(exported, null, 2), { mode: 0o600 });
+};
+/**
+ * Load-or-create the per-device keypair. Local-only — no server round-trip,
+ * no upload. Safe to call concurrently (dedupes to one init). Returns the
+ * exported public key (Base64 SPKI).
+ */
+const initDeviceCrypto = () => {
+    if (deviceInitPromise)
+        return deviceInitPromise;
+    deviceInitPromise = (async () => {
+        const stored = loadStoredDeviceKeys();
+        if (stored) {
+            deviceKeyPair = await importKeyPair(stored);
+            deviceExportedPublicKey = stored.publicKey;
+            return stored.publicKey;
+        }
+        const keyPair = await generateKeyPair();
+        const exported = await exportKeyPair(keyPair);
+        storeDeviceKeys(exported);
+        deviceKeyPair = keyPair;
+        deviceExportedPublicKey = exported.publicKey;
+        return exported.publicKey;
+    })().catch((err) => {
+        deviceInitPromise = null;
+        throw err;
+    });
+    return deviceInitPromise;
+};
+exports.initDeviceCrypto = initDeviceCrypto;
+const getDevicePublicKey = () => deviceExportedPublicKey;
+exports.getDevicePublicKey = getDevicePublicKey;
+/**
+ * Encrypt an ephemeral payload (e.g. a stream frame) for one recipient
+ * device. Requires initDeviceCrypto() to have completed.
+ */
+const encryptEphemeral = async (plaintext, recipientPublicKeyRaw) => {
+    if (!deviceKeyPair || !deviceExportedPublicKey)
+        throw new Error('Device crypto not initialized');
+    const recipientKey = await importPublicKey(recipientPublicKeyRaw);
+    const payload = await encrypt(plaintext, deviceKeyPair.privateKey, recipientKey);
+    return { ...payload, senderPublicKey: deviceExportedPublicKey };
+};
+exports.encryptEphemeral = encryptEphemeral;

package/dist/listener-device-id.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Listener device id, resolved READ-ONLY — MUST equal what `listener.ts`
+ * `computeListenerDeviceId()` registers, so pushes tagged with this id land
+ * under the listener's device (otherwise a hook/notify reaches the feed but
+ * never threads into the agent chat). Hash the platform machine id first, then
+ * the sticky file the listener persisted, then a hostname hash — the same order
+ * as the writer, but never writing the file here.
+ */
+export declare const listenerDeviceId: () => string;
+//# sourceMappingURL=listener-device-id.d.ts.map

package/dist/listener-device-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listener-device-id.d.ts","sourceRoot":"","sources":["../src/listener-device-id.ts"],"names":[],"mappings":"AAuCA;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,QAAO,MAQnC,CAAC"}

package/dist/listener-device-id.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listenerDeviceId = void 0;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const node_crypto_1 = require("node:crypto");
+// The listener daemon writes this file (see listener.ts computeListenerDeviceId);
+// non-listener processes in the CLI (zeph-hook's agent-session context) only
+// READ it, so both resolve the same id without racing the write.
+const LISTENER_ID_FILE = (0, node_path_1.join)((0, node_os_1.homedir)(), '.zeph', 'listener-device-id');
+const hashListenerId = (seed) => `dev_listener_${(0, node_crypto_1.createHash)('sha256').update(seed).digest('hex').slice(0, 8)}`;
+/** Platform machine id (macOS IOPlatformUUID / Linux machine-id), or null. */
+const readMachineId = () => {
+    try {
+        if (process.platform === 'darwin') {
+            // stdio: swallow ioreg's stderr so a one-off `zeph rename` / hook
+            // never leaks ioreg warnings to the terminal (matches listener.ts).
+            const out = (0, node_child_process_1.execFileSync)('ioreg', ['-rd1', '-c', 'IOPlatformExpertDevice'], {
+                encoding: 'utf-8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+            });
+            const m = out.match(/"IOPlatformUUID"\s*=\s*"([^"]+)"/);
+            if (m)
+                return m[1];
+        }
+        if (process.platform === 'linux') {
+            for (const p of ['/etc/machine-id', '/var/lib/dbus/machine-id']) {
+                try {
+                    const v = (0, node_fs_1.readFileSync)(p, 'utf-8').trim();
+                    if (v)
+                        return v;
+                }
+                catch { /* try next path */ }
+            }
+        }
+    }
+    catch { /* no machine id readable — fall through */ }
+    return null;
+};
+/**
+ * Listener device id, resolved READ-ONLY — MUST equal what `listener.ts`
+ * `computeListenerDeviceId()` registers, so pushes tagged with this id land
+ * under the listener's device (otherwise a hook/notify reaches the feed but
+ * never threads into the agent chat). Hash the platform machine id first, then
+ * the sticky file the listener persisted, then a hostname hash — the same order
+ * as the writer, but never writing the file here.
+ */
+const listenerDeviceId = () => {
+    const machineId = readMachineId();
+    if (machineId)
+        return hashListenerId(machineId);
+    try {
+        const saved = (0, node_fs_1.readFileSync)(LISTENER_ID_FILE, 'utf-8').trim();
+        if (/^dev_listener_[0-9a-f]{8}$/.test(saved))
+            return saved;
+    }
+    catch { /* no sticky file — fall back to hostname */ }
+    return hashListenerId((0, node_os_1.hostname)());
+};
+exports.listenerDeviceId = listenerDeviceId;

package/dist/listener.d.ts

@@ -22,6 +22,7 @@
  */
 import { type AgentKind, type RegisteredRemoteAgent } from './remote-agents.js';
 import { type AgentState } from './agent-state.js';
+import { type EncryptedEphemeralPayload } from './crypto.js';
 export declare const SESSION_REPORT_HEARTBEAT_MS = 30000;
 interface AgentSession {
     name: string;
@@ -167,6 +168,59 @@ export declare const handleScreenRequest: (req: ScreenRequest) => ScreenSnapshot
  * captures so a burst of arrow presses yields frames after the LAST press.
  */
 export declare const scheduleInjectSnapshots: (sessionName: string, send: (data: Record<string, unknown>) => void, delays?: number[]) => void;
+export interface StreamControl {
+    subtype?: string;
+    targetDeviceId?: string;
+    sessionName?: string;
+    /** Subscriber's device public key (Base64 SPKI) — presence turns on E2EE. */
+    subscriberPublicKey?: string;
+}
+export declare const MAX_CONCURRENT_STREAMS = 3;
+export declare const stopStream: (sessionName: string) => void;
+export declare const stopAllStreams: () => void;
+/** Wire shape of one live-mirror data frame (before the relay's ephemeral wrap). */
+export type StreamFramePayload = {
+    subtype: 'agent.stream.frame';
+    sessionName: string;
+    capturedAt: string;
+    truncated: boolean;
+    /** Capture-order stamp — attached at send time, not by buildStreamFrame. */
+    seq?: number;
+    /** Stream incarnation (stats.startedAt) — lets the receiver reset its
+     *  seq high-water mark when the daemon restarts the stream. */
+    epoch?: number;
+    /** Plaintext pane content — only on unencrypted streams. */
+    content?: string;
+    /** E2EE envelope — replaces `content` on encrypted streams. */
+    encrypted?: EncryptedEphemeralPayload;
+};
+/** Wire shape of a live-mirror error frame — same subtype, no pane data. */
+export type StreamErrorFrame = {
+    subtype: 'agent.stream.frame';
+    sessionName: string;
+    error: 'unknown_session' | 'e2ee_unavailable' | 'encrypt_failed' | 'stream_limit';
+};
+/**
+ * Per-listener concurrency guard, as a pure predicate so the boundary is
+ * unit-testable without touching the module-scope `activeStreams` map.
+ */
+export declare const isStreamCapReached: (activeCount: number) => boolean;
+/**
+ * Build the wire payload for one stream frame. With a subscriber public key
+ * the pane content rides ONLY inside the E2EE envelope; an encrypt failure
+ * (bad key, crypto not ready on the first tick) returns null so the caller
+ * drops the frame — an encrypted stream never leaks a plaintext frame.
+ */
+export declare const buildStreamFrame: (captured: {
+    content: string;
+    truncated: boolean;
+}, sessionName: string, subscriberPublicKey?: string) => Promise<StreamFramePayload | null>;
+/**
+ * Handle agent.stream.start / agent.stream.stop. Returns true when the message
+ * was a stream-control message (so the caller skips the one-shot screen-peek
+ * path). start is idempotent — a repeat restarts the loop.
+ */
+export declare const handleStreamControl: (req: StreamControl, send: (data: Record<string, unknown>) => void) => boolean;
 export interface CollectResult {
     sessions: AgentSession[];
     /** Diagnostic notes per rejected session — surfaced under `--verbose`. */

package/dist/listener.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"listener.d.ts","sourceRoot":"","sources":["../src/listener.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"listener.d.ts","sourceRoot":"","sources":["../src/listener.ts"],"names":[],"mappings":"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"}

package/dist/listener.js

@@ -25,7 +25,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handleListener = exports.resolveWsUrl = exports.computeListenerDeviceId = exports.computeBackoff = exports.handlePush = exports.gcAttachments = exports.setAttachmentContext = exports.writeRemoteMarker = exports.collectSessions = exports.collectSessionsVerbose = exports.scheduleInjectSnapshots = exports.handleScreenRequest = exports.collectWatchHits = exports.resetPatternWatches = exports.setPatternWatches = exports.deriveSessionState = exports.resetSessionStates = exports.detectRemoteAgent = exports.parseSessionName = exports.invalidateTmuxSocketCache = exports.resolveKeys = exports.paneCurrentCommand = exports.checkRateLimit = exports.AUTH_FAILURE_CODES = exports.sessionsReportDue = exports.sessionsFingerprint = exports.SESSION_REPORT_HEARTBEAT_MS = void 0;
+exports.handleListener = exports.resolveWsUrl = exports.computeListenerDeviceId = exports.computeBackoff = exports.handlePush = exports.gcAttachments = exports.setAttachmentContext = exports.writeRemoteMarker = exports.collectSessions = exports.collectSessionsVerbose = exports.handleStreamControl = exports.buildStreamFrame = exports.isStreamCapReached = exports.stopAllStreams = exports.stopStream = exports.MAX_CONCURRENT_STREAMS = exports.scheduleInjectSnapshots = exports.handleScreenRequest = exports.collectWatchHits = exports.resetPatternWatches = exports.setPatternWatches = exports.deriveSessionState = exports.resetSessionStates = exports.detectRemoteAgent = exports.parseSessionName = exports.invalidateTmuxSocketCache = exports.resolveKeys = exports.paneCurrentCommand = exports.checkRateLimit = exports.AUTH_FAILURE_CODES = exports.sessionsReportDue = exports.sessionsFingerprint = exports.SESSION_REPORT_HEARTBEAT_MS = void 0;
 const child_process_1 = require("child_process");
 const crypto_1 = require("crypto");
 const fs_1 = require("fs");
@@ -37,6 +37,7 @@ const gate_js_1 = require("./gate.js");
 const remote_agents_js_1 = require("./remote-agents.js");
 const agent_state_js_1 = require("./agent-state.js");
 const agent_rules_fetch_js_1 = require("./agent-rules-fetch.js");
+const crypto_js_1 = require("./crypto.js");
 const PING_INTERVAL_MS = 25_000;
 const PONG_TIMEOUT_MS = 10_000;
 const RECONNECT_BASE_MS = 1_000;
@@ -164,6 +165,11 @@ const ALLOWED_KEYS = {
     left: 'Left',
     right: 'Right',
     enter: 'Enter',
+    tab: 'Tab',
+    backtab: 'BTab',
+    backspace: 'BSpace',
+    delete: 'DC',
+    space: 'Space',
 };
 /**
  * Translate a phone-supplied key list to tmux tokens. Returns null if ANY
@@ -692,8 +698,16 @@ const handleScreenRequest = (req) => {
 exports.handleScreenRequest = handleScreenRequest;
 /** Raw pane capture + size cap. Shared by the request path and the
  *  post-injection auto-snapshot. */
-const capturePane = (sessionName) => {
-    const r = (0, child_process_1.spawnSync)('tmux', tmuxArgs(['capture-pane', '-p', '-t', sessionName, '-S', `-${SCREEN_PEEK_LINES}`]), {
+const capturePane = (sessionName, escapes = false, lines = SCREEN_PEEK_LINES) => {
+    // `-e` keeps ANSI/color escapes for the xterm.js live stream. The
+    // screen-peek path leaves it off so its <pre> renderer stays plain text.
+    // `lines` sets how far back the capture reaches — the live stream grabs
+    // more history so the mirror has room to scroll; SCREEN_PEEK_MAX_BYTES
+    // still caps the payload below.
+    const captureArgs = escapes
+        ? ['capture-pane', '-p', '-e', '-t', sessionName, '-S', `-${lines}`]
+        : ['capture-pane', '-p', '-t', sessionName, '-S', `-${lines}`];
+    const r = (0, child_process_1.spawnSync)('tmux', tmuxArgs(captureArgs), {
         encoding: 'utf-8',
         stdio: ['ignore', 'pipe', 'pipe'],
     });
@@ -743,6 +757,221 @@ const scheduleInjectSnapshots = (sessionName, send, delays = INJECT_SNAPSHOT_DEL
     pendingInjectSnapshots.set(sessionName, timers);
 };
 exports.scheduleInjectSnapshots = scheduleInjectSnapshots;
+// ~2.5 fps ceiling. Cadence + diff-gating are the ONLY bound on API Gateway
+// WS cost (the $default route has no per-message limit), so keep it modest
+// and let unchanged frames drop.
+// How far back the live-stream capture reaches — more than the screen-peek
+// window so the mirror has scrollback to scroll through. SCREEN_PEEK_MAX_BYTES
+// still caps the actual payload, so very wide panes get top-truncated.
+const STREAM_CAPTURE_LINES = 200;
+const STREAM_INTERVAL_MS = 400;
+// Orphan guard: a phone that dies without sending agent.stream.stop must not
+// leak an interval forever. Auto-stop after this long; the phone re-subscribes
+// on reopen.
+const STREAM_MAX_MS = 5 * 60_000;
+// Per-listener concurrency guard: the API Gateway WS stage throttle (50 rps)
+// is SHARED across every user, so a runaway machine (many sessions, or a
+// client re-subscribe bug) streaming at 2.5 fps each can starve push delivery
+// and presence for everyone. One phone watches one session at a time; 3 leaves
+// headroom for multiple devices while capping the blast radius of one host.
+exports.MAX_CONCURRENT_STREAMS = 3;
+// Fail-closed guard: consecutive encrypt failures (malformed subscriber key)
+// stop the stream with an error frame instead of retrying forever.
+const STREAM_MAX_ENCRYPT_FAILURES = 3;
+// R2 instrumentation: the daemon's outbound send() IS the API Gateway $default
+// inbound message (1 Lambda + DDB ops + N PostToConnection each), so counting
+// frames/bytes HERE measures the real cloud cost of a live stream. Rolled up to
+// the log every STREAM_LOG_INTERVAL_MS and summarized on stop — the data that
+// decides cloud-throttled (B-lite) vs direct/Tailscale (B-full).
+const STREAM_LOG_INTERVAL_MS = 5_000;
+const activeStreams = new Map();
+const maybeLogStreamStats = (sessionName, stats) => {
+    const elapsed = Date.now() - stats.lastLogAt;
+    if (elapsed < STREAM_LOG_INTERVAL_MS)
+        return;
+    const secs = elapsed / 1000;
+    const fps = (stats.frames - stats.lastLogFrames) / secs;
+    const kbps = (stats.bytes - stats.lastLogBytes) / 1024 / secs;
+    log(`⧉ stream ${sessionName}: ${fps.toFixed(1)} fps, ${kbps.toFixed(1)} KB/s (${stats.frames} sent, ${stats.skipped} diff-skipped)`);
+    stats.lastLogAt = Date.now();
+    stats.lastLogFrames = stats.frames;
+    stats.lastLogBytes = stats.bytes;
+};
+const stopStream = (sessionName) => {
+    const entry = activeStreams.get(sessionName);
+    if (!entry)
+        return;
+    clearInterval(entry.timer);
+    activeStreams.delete(sessionName);
+    const { stats } = entry;
+    const secs = Math.max(0.001, (Date.now() - stats.startedAt) / 1000);
+    log(`⧉ stream ${sessionName} stopped: ${stats.frames} frames / ` +
+        `${(stats.bytes / 1024).toFixed(1)} KB over ${secs.toFixed(1)}s ` +
+        `(${(stats.frames / secs).toFixed(1)} fps avg, ${stats.skipped} diff-skipped)`);
+};
+exports.stopStream = stopStream;
+const stopAllStreams = () => {
+    // Route through stopStream so each stream emits its summary line.
+    for (const sessionName of [...activeStreams.keys()])
+        (0, exports.stopStream)(sessionName);
+};
+exports.stopAllStreams = stopAllStreams;
+/**
+ * Per-listener concurrency guard, as a pure predicate so the boundary is
+ * unit-testable without touching the module-scope `activeStreams` map.
+ */
+const isStreamCapReached = (activeCount) => activeCount >= exports.MAX_CONCURRENT_STREAMS;
+exports.isStreamCapReached = isStreamCapReached;
+const streamErrorFrame = (sessionName, error) => ({
+    subtype: 'agent.stream.frame',
+    sessionName,
+    error,
+});
+/**
+ * Build the wire payload for one stream frame. With a subscriber public key
+ * the pane content rides ONLY inside the E2EE envelope; an encrypt failure
+ * (bad key, crypto not ready on the first tick) returns null so the caller
+ * drops the frame — an encrypted stream never leaks a plaintext frame.
+ */
+const buildStreamFrame = async (captured, sessionName, subscriberPublicKey) => {
+    const base = {
+        subtype: 'agent.stream.frame',
+        sessionName,
+        capturedAt: new Date().toISOString(),
+        truncated: captured.truncated,
+    };
+    if (!subscriberPublicKey)
+        return { ...base, content: captured.content };
+    try {
+        const encrypted = await (0, crypto_js_1.encryptEphemeral)(captured.content, subscriberPublicKey);
+        return { ...base, encrypted };
+    }
+    catch (err) {
+        log(`⧉ stream ${sessionName}: frame encrypt failed (${err instanceof Error ? err.message : err}) — frame dropped`);
+        return null;
+    }
+};
+exports.buildStreamFrame = buildStreamFrame;
+/**
+ * Handle agent.stream.start / agent.stream.stop. Returns true when the message
+ * was a stream-control message (so the caller skips the one-shot screen-peek
+ * path). start is idempotent — a repeat restarts the loop.
+ */
+const handleStreamControl = (req, send) => {
+    if (req.subtype === 'agent.stream.stop') {
+        if (req.sessionName)
+            (0, exports.stopStream)(req.sessionName);
+        return true;
+    }
+    if (req.subtype !== 'agent.stream.start')
+        return false;
+    // Not addressed to this machine — let other listeners answer.
+    if (req.targetDeviceId !== (0, exports.computeListenerDeviceId)())
+        return false;
+    const sessionName = req.sessionName;
+    if (!sessionName)
+        return true;
+    if (!(0, exports.collectSessions)().some((s) => s.name === sessionName)) {
+        send(streamErrorFrame(sessionName, 'unknown_session'));
+        return true;
+    }
+    (0, exports.stopStream)(sessionName); // idempotent restart (frees this session's slot first)
+    // Concurrency guard AFTER the restart-stop: re-subscribing to an already
+    // active session doesn't count against the cap, only a genuinely new one
+    // does. Refuse the new stream instead of adding to the shared-throttle load.
+    if ((0, exports.isStreamCapReached)(activeStreams.size)) {
+        log(`⧉ stream ${sessionName}: refused — ${activeStreams.size}/${exports.MAX_CONCURRENT_STREAMS} streams already active on this listener`);
+        send(streamErrorFrame(sessionName, 'stream_limit'));
+        return true;
+    }
+    let lastContent = null;
+    const stats = {
+        startedAt: Date.now(),
+        frames: 0,
+        bytes: 0,
+        skipped: 0,
+        lastLogAt: Date.now(),
+        lastLogFrames: 0,
+        lastLogBytes: 0,
+    };
+    // E2EE handshake: load-or-create this device's keypair up front. The
+    // subscriber asked for encryption, so key failure is FAIL-CLOSED: refuse
+    // to stream rather than downgrade to plaintext — a silent downgrade is
+    // exactly the signal a key-stripping relay would produce. The phone sees
+    // the error frame and can choose to re-subscribe without a key.
+    const subscriberPublicKey = req.subscriberPublicKey;
+    if (subscriberPublicKey) {
+        (0, crypto_js_1.initDeviceCrypto)().catch((err) => {
+            // Stream stopped or replaced while init was in flight — the
+            // failure belongs to the old incarnation, not the current one.
+            if (activeStreams.get(sessionName)?.stats !== stats)
+                return;
+            log(`⧉ stream ${sessionName}: device crypto init failed (${err instanceof Error ? err.message : err}) — refusing to stream (fail-closed)`);
+            send(streamErrorFrame(sessionName, 'e2ee_unavailable'));
+            (0, exports.stopStream)(sessionName);
+        });
+    }
+    let wireSeq = 0;
+    let encryptFailures = 0;
+    const timer = setInterval(() => {
+        const captured = capturePane(sessionName, true, STREAM_CAPTURE_LINES);
+        if (!captured || captured.content === lastContent) {
+            stats.skipped++;
+            return; // diff-gate
+        }
+        lastContent = captured.content;
+        // Stamp the sequence in CAPTURE order, synchronously — frame assembly
+        // is async (encryption) and fire-and-forget, so resolve order is not
+        // guaranteed under load; the receiver drops any seq it has already
+        // painted past.
+        const seq = ++wireSeq;
+        void (0, exports.buildStreamFrame)(captured, sessionName, subscriberPublicKey).then((frame) => {
+            // Stream stopped or restarted while this frame was in flight —
+            // `stats` is unique per start, so it doubles as the identity
+            // token. Don't send into a dead/replaced stream or skew its stats.
+            if (activeStreams.get(sessionName)?.stats !== stats)
+                return;
+            if (!frame) {
+                // Encrypt failure — frame dropped, diff-gate un-marked so the
+                // next tick retries. A key that keeps failing (malformed
+                // subscriber key) never recovers: fail closed after a few
+                // strikes instead of retrying every 400ms for 5 minutes.
+                lastContent = null;
+                // Init still in flight (or failed — its own path fail-closes):
+                // a not-yet-ready key is not a malformed key, don't strike.
+                if ((0, crypto_js_1.getDevicePublicKey)() === null)
+                    return;
+                encryptFailures++;
+                if (encryptFailures >= STREAM_MAX_ENCRYPT_FAILURES) {
+                    send(streamErrorFrame(sessionName, 'encrypt_failed'));
+                    (0, exports.stopStream)(sessionName);
+                }
+                return;
+            }
+            encryptFailures = 0;
+            stats.frames++;
+            // Measure the actual wire payload (the encrypted envelope is
+            // ~1.4× the plaintext; base fields now count too, so plaintext
+            // streams read slightly higher than the pre-E2EE content-only
+            // metric) — this feeds the R2 cost instrumentation.
+            stats.bytes += Buffer.byteLength(JSON.stringify(frame), 'utf-8');
+            // seq = capture order; epoch = this stream incarnation, so the
+            // receiver's ordering guard resets across daemon-side restarts.
+            send({ ...frame, seq, epoch: stats.startedAt });
+            maybeLogStreamStats(sessionName, stats);
+        }).catch((err) => {
+            // A long-lived daemon must never crash on an unhandled rejection
+            // from send()/logging — report and let the next tick carry on.
+            log(`⧉ stream ${sessionName}: frame send failed (${err instanceof Error ? err.message : err})`);
+        });
+    }, STREAM_INTERVAL_MS);
+    timer.unref?.();
+    activeStreams.set(sessionName, { timer, stats });
+    const expiry = setTimeout(() => (0, exports.stopStream)(sessionName), STREAM_MAX_MS);
+    expiry.unref?.();
+    return true;
+};
+exports.handleStreamControl = handleStreamControl;
 /**
  * Inventory pass that also records *why* each `zeph-*` session was
  * skipped. The verbose log uses the rejection notes to explain empty
@@ -1356,9 +1585,18 @@ const streamSession = (wsUrl, apiKey) => {
                 // Screen peek (§S4): the phone asks for this machine's live
                 // pane content over the ephemeral relay; the reply rides the
                 // same channel. Nothing is persisted server-side.
-                const reply = (0, exports.handleScreenRequest)(m.data);
-                if (reply && sock.readyState === ws_1.default.OPEN) {
-                    sock.send(JSON.stringify({ type: 'ephemeral', data: reply }));
+                const sendEphemeral = (data) => {
+                    if (sock.readyState === ws_1.default.OPEN) {
+                        sock.send(JSON.stringify({ type: 'ephemeral', data }));
+                    }
+                };
+                // Live mirror (PoC): agent.stream.start/stop drives a
+                // continuous, diff-gated frame loop; falls through to the
+                // one-shot screen-peek when it isn't a stream-control message.
+                if (!(0, exports.handleStreamControl)(m.data, sendEphemeral)) {
+                    const reply = (0, exports.handleScreenRequest)(m.data);
+                    if (reply)
+                        sendEphemeral(reply);
                 }
             }
             // Surface server-side errors from listener.sessions reports.
@@ -1380,6 +1618,7 @@ const streamSession = (wsUrl, apiKey) => {
             log(`! ws error: ${err.message}`);
         });
         sock.on('close', (code, reasonBuf) => {
+            (0, exports.stopAllStreams)();
             cleanup();
             resolve({ closeCode: code, reason: reasonBuf?.toString('utf-8') ?? '', connected: opened });
         });

package/dist/zeph-hook.d.ts

@@ -17,6 +17,14 @@ export declare class ZephHook {
     list(params?: ListParams): Promise<ListResult>;
     dismiss(pushId: string): Promise<DismissOneResult>;
     dismissAll(): Promise<DismissAllResult>;
+    /**
+     * Set (or clear, with an empty alias) the display name for an agent session,
+     * keyed by its tmux `name` on `deviceId`. The alias overrides the app's
+     * computed session label; it survives listener re-reports (server-side).
+     */
+    renameAgentSession(deviceId: string, name: string, alias: string): Promise<{
+        deviceId: string;
+    }>;
     private request;
     private parseError;
 }

package/dist/zeph-hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"zeph-hook.d.ts","sourceRoot":"","sources":["../src/zeph-hook.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAY,gBAAgB,EAAE,gBAAgB,EAAoB,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAkCxL,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,OAAO,CAAC,iBAAiB,CAAS;gBAEtB,OAAO,EAAE,WAAW;YASlB,YAAY;IAYpB,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;YAmC7C,cAAc;IAsDtB,aAAa,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAK7G,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcrF,IAAI,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAmB9C,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAKlD,UAAU,IAAI,OAAO,CAAC,gBAAgB,CAAC;YAK/B,OAAO;IAiCrB,OAAO,CAAC,UAAU;CASnB"}
+{"version":3,"file":"zeph-hook.d.ts","sourceRoot":"","sources":["../src/zeph-hook.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,UAAU,EAAY,gBAAgB,EAAE,gBAAgB,EAAoB,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAoCxL,qBAAa,QAAQ;IACnB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC,OAAO,CAAC,iBAAiB,CAAS;gBAEtB,OAAO,EAAE,WAAW;YASlB,YAAY;IAYpB,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;YAmC7C,cAAc;IAsDtB,aAAa,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAK7G,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcrF,IAAI,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAmB9C,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAKlD,UAAU,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAK7C;;;;OAIG;IACG,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;YASxF,OAAO;IAiCrB,OAAO,CAAC,UAAU;CASnB"}

package/dist/zeph-hook.js

@@ -1,9 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZephHook = void 0;
-const node_crypto_1 = require("node:crypto");
-const node_os_1 = require("node:os");
 const node_child_process_1 = require("node:child_process");
+const listener_device_id_js_1 = require("./listener-device-id.js");
 const errors_js_1 = require("./errors.js");
 const crypto_js_1 = require("./crypto.js");
 const DEFAULT_BASE_URL = 'https://api.zeph.to/v1';
@@ -14,7 +13,10 @@ const PREVIEW_LENGTH = 200;
  * Stable agent-session grouping when running inside a tmux agent session, so a
  * hook/notify (e.g. the Stop-hook recap) files under the same session key as
  * the listener's pushes — surviving Claude session-UUID rotation. The device id
- * MUST match cli `computeListenerDeviceId` (`dev_listener_<sha8(hostname)>`).
+ * MUST equal the listener's `computeListenerDeviceId`, so it's resolved the same
+ * way (machine-id hash → sticky file → hostname) via the shared read-only
+ * helper — NOT a bare hostname hash, which drifts from the listener's id when a
+ * machine id is readable and files the push under a non-matching session key.
  */
 const agentSessionContext = () => {
     if (!process.env.TMUX)
@@ -28,8 +30,7 @@ const agentSessionContext = () => {
     }
     if (!name)
         return null;
-    const h = (0, node_crypto_1.createHash)('sha256').update((0, node_os_1.hostname)()).digest('hex').slice(0, 8);
-    return { agentDeviceId: `dev_listener_${h}`, agentSessionName: name };
+    return { agentDeviceId: (0, listener_device_id_js_1.listenerDeviceId)(), agentSessionName: name };
 };
 const inferMimeType = (fileName) => {
     const ext = fileName.split('.').pop()?.toLowerCase();
@@ -184,6 +185,15 @@ class ZephHook {
         const json = await this.request('POST', '/pushes/dismiss-all');
         return { dismissed: json.data?.dismissed ?? 0 };
     }
+    /**
+     * Set (or clear, with an empty alias) the display name for an agent session,
+     * keyed by its tmux `name` on `deviceId`. The alias overrides the app's
+     * computed session label; it survives listener re-reports (server-side).
+     */
+    async renameAgentSession(deviceId, name, alias) {
+        const res = await this.request('PATCH', `/devices/${encodeURIComponent(deviceId)}/agent-sessions/${encodeURIComponent(name)}`, { alias });
+        return { deviceId: res.data.deviceId };
+    }
     async request(method, path, body) {
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), this.timeoutMs);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeph-to/cli",
-  "version": "1.22.0",
+  "version": "1.24.0",
   "description": "Zeph CLI + push notification SDK for AI agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",