@zeph-to/cli 1.24.0 → 1.26.0

package/README.md

@@ -43,6 +43,12 @@ on *every* notification. For notifications only, with no phone control,
 `npx @zeph-to/cli install` is a lighter alternative that skips the global
 binary.
 
+Once installed, the hooks fire in **every** session of each configured
+agent — `zeph cc` is the phone-control bridge, not the notification
+switch. Turn the volume down without uninstalling: `/zeph-quiet --global`
+(blockers only, all projects), `/zeph-mute` (silence, current project),
+`/zeph-status` (what's in effect). See [Mute & push mode](#mute--push-mode).
+
 `~/.zeph/config.json` is the single source of truth — the CLI, the MCP
 server, the plugin hooks, and the listener all read it. You never need
 `ZEPH_API_KEY`-style env vars for a normal setup; they exist as overrides
@@ -196,12 +202,22 @@ can never false-flag. Muted projects are never flagged.
 
 ### Diagnostics
 
-The auto-spawned listener writes to two files under `~/.zeph/`:
+The auto-spawned listener writes to three files under `~/.zeph/`:
 
 - `listener.pid` — the running daemon's PID. `cat ~/.zeph/listener.pid`
   + `ps -p <pid>` to confirm it's alive.
+- `listener.version` — the CLI version the daemon booted from. This is
+  what `zeph cc` compares against the installed package to spot a stale
+  daemon (see below).
 - `listener.log` — stdout + stderr from the daemon. `tail -f` to watch.
 
+The daemon logs its version on the first line, which is the only
+reliable way to tell which build a long-running process is on:
+
+```
+[xx:xx:xx] zeph listener starting — v1.26.0 — wss://ws.zeph.to
+```
+
 A healthy listener log shows one line per cycle:
 
 ```
@@ -213,12 +229,31 @@ If you see `! server rejected listener.sessions: ...` instead, the
 message points at the failure (auth, missing device record, etc.) so
 you can fix the actual problem instead of guessing.
 
-To force a restart — e.g. after upgrading `@zeph-to/cli`:
+To force a restart:
+
+```bash
+zeph listener --restart
+```
+
+**After upgrading `@zeph-to/cli` you normally don't have to.** `npm i -g`
+replaces the package on disk but never the daemon already running from
+the old build — that daemon keeps answering pushes (so agent chat looks
+fine) while silently ignoring every message subtype added since it
+booted. `zeph cc` compares `listener.version` against the installed
+version and restarts the daemon for you when the installed one is newer
+(a daemon *newer* than the `zeph cc` you ran is left alone, so several
+installs on one machine don't fight over it):
+
+```
+zeph: listener 1.25.0 is stale — restarting on 1.26.0
+```
+
+If the PID file is missing (a different account started the daemon, or
+it was removed by hand) the singleton guard can't see it. Find the real
+process instead:
 
 ```bash
-kill $(cat ~/.zeph/listener.pid)
-rm ~/.zeph/listener.pid
-zeph cc        # autospawns the new build
+ps aux | grep '[c]li.js listener'
 ```
 
 To run it in the foreground (for development of the SDK itself):
@@ -363,7 +398,7 @@ zeph notify --title "Hello" --json
 | `--priority <p>` | Priority: `low`, `normal`, `high`, `urgent` |
 | `--device <id>` | Target device ID |
 | `--session <id>` | AI session ID so the push threads into that session's chat (or `ZEPH_SESSION_ID` env) |
-| `--auto` | Apply the push gate before sending — honors the `/zeph-quiet` / `/zeph-loud` push-mode dial; gated-out exits silently with code 0 |
+| `--auto` | Apply the push gate before sending — honors the `/zeph-quiet` / `/zeph-loud` push-mode dial, per project or machine-wide (`--global`); gated-out exits silently with code 0 |
 | `--marker <m>` | Push Signal marker for `--auto`: `skip`, `push`, `high` |
 | `--tools <n>`, `--nonreadonly <n>` | Turn tool counts feeding `--auto`'s heuristic (defaults assume real work) |
 
@@ -379,6 +414,8 @@ which project + branch finished without writing per-IDE wrappers. Pass
 | `--ws-url <url>` | WebSocket endpoint (or set `ZEPH_WS_URL` env, or `wsUrl` in `~/.zeph/config.json`) |
 | `--key <api-key>` | API key (or set `ZEPH_API_KEY` env) |
 | `--base-url <url>` | REST API base URL (or set `ZEPH_BASE_URL` env, or `baseUrl` in `~/.zeph/config.json`) |
+| `--stop` | Stop the running daemon and clear its PID/version stamps |
+| `--restart` | Stop it and relaunch detached (logs to `~/.zeph/listener.log`) |
 
 The listener reconnects with exponential backoff + jitter (1 s → 30 s
 cap). Heartbeat is ping every 25 s with a 10 s pong timeout. On an
@@ -401,23 +438,45 @@ code 3 instead of looping forever — fix the key and restart.
 | `--json` | Output JSON format |
 | `--version` | Print version |
 
-### Mute
+### Mute & push mode
 
-Mute is project-scoped (uses project directory hash). Created by Claude
-Code `/zeph-mute` command.
+Both live as state files under `${XDG_STATE_HOME:-~/.local/state}/zeph`,
+keyed by a `cksum` hash of the project directory. Claude Code's
+`/zeph-mute` / `/zeph-quiet` / `/zeph-loud` / `/zeph-normal` write them;
+the CLI reads them (mute on every `notify`, push mode on `--auto`).
 
 Notifications are silently skipped when a mute file exists for the
 current project:
 
 ```bash
-# Mute (created by /zeph-mute in Claude Code plugin)
-HASH=$(echo -n "$PROJECT_DIR" | cksum | cut -d' ' -f1)
-touch /tmp/zeph-muted-$HASH
+STATE_DIR="${XDG_STATE_HOME:-$HOME/.local/state}/zeph"
+HASH=$(printf '%s' "$PROJECT_DIR" | cksum | cut -d' ' -f1)
+
+# Mute (created by /zeph-mute in the Claude Code plugin)
+mkdir -p "$STATE_DIR" && touch "$STATE_DIR/muted-$HASH"
 
 # Unmute
-rm /tmp/zeph-muted-$HASH
+rm -f "$STATE_DIR/muted-$HASH"
 ```
 
+Push mode is a one-word file (`quiet` / `loud` / `normal`) resolved in
+this order — first hit wins:
+
+| Order | File | Set by |
+|-------|------|--------|
+| 1 | `$STATE_DIR/pushmode-<hash>` | `/zeph-quiet` · `/zeph-loud` · `/zeph-normal` |
+| 2 | `/tmp/zeph-pushmode-<hash>` | older versions (honored only when you own the file) |
+| 3 | `$STATE_DIR/pushmode-default` | `/zeph-quiet --global` — the machine-wide default |
+| 4 | *(none)* | `normal` |
+
+So `/zeph-quiet --global` quiets every project that has no dial of its
+own, and a per-project dial always overrides it. Mute has no `-default`
+form on purpose: it is keyed on presence, not content, so a global mute
+could never be lifted for a single project.
+
+Legacy `/tmp/zeph-muted-<hash>` files are still honored when owned by the
+current user (the state dir moved out of world-writable `/tmp`).
+
 The CLI checks `CLAUDE_PROJECT_DIR`, `CURSOR_PROJECT_DIR`,
 `WINDSURF_PROJECT_DIR`, and falls back to `cwd`.
 

package/dist/cli.js

@@ -81,6 +81,10 @@ ${usageAgentLines()}
   listener        Resident daemon — receives 'agent.command' pushes from
                   the phone picker and injects them into the matching
                   tmux session.
+                  --stop     stop the running daemon
+                  --restart  stop it and relaunch in the background
+                             (needed after an upgrade: 'npm i -g' swaps
+                              the package but never the live process)
 
 Notify options:
   --title <text>     Push title

package/dist/gate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AAyBA,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAC3D,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEvD,MAAM,WAAW,SAAS;IACxB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,gBAAgB,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,YAAY,EAAE,OAAO,CAAC;IACtB,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,YAAY,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAAC;CAC7B;AAED;;;;;GAKG;AACH,eAAO,MAAM,aAAa;;;;CAIhB,CAAC;AAEX,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,GAAG,SAAS,KAAG,UACS,CAAC;AAEpE,eAAO,MAAM,iBAAiB,GAAI,KAAK,MAAM,GAAG,SAAS,KAAG,YACR,CAAC;AAErD,eAAO,MAAM,UAAU,GAAI,OAAO,SAAS,KAAG,WAW7C,CAAC;AAeF,eAAO,MAAM,QAAQ,QAAO,MACoD,CAAC;AAmBjF,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,IAOlD,CAAC;AAWF,+EAA+E;AAC/E,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG,MAA4C,CAAC;AAE7F;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,KAAG,MAG1B,CAAC;AAEnB,0DAA0D;AAC1D,eAAO,MAAM,OAAO,GAAI,KAAK,MAAM,KAAG,OAGrC,CAAC;AAEF,oFAAoF;AACpF,eAAO,MAAM,YAAY,GAAI,KAAK,MAAM,KAAG,YAU1C,CAAC"}
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../src/gate.ts"],"names":[],"mappings":"AAyBA,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAC3D,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEvD,MAAM,WAAW,SAAS;IACxB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,gBAAgB,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,YAAY,EAAE,OAAO,CAAC;IACtB,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,YAAY,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAAC;CAC7B;AAED;;;;;GAKG;AACH,eAAO,MAAM,aAAa;;;;CAIhB,CAAC;AAEX,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,GAAG,SAAS,KAAG,UACS,CAAC;AAEpE,eAAO,MAAM,iBAAiB,GAAI,KAAK,MAAM,GAAG,SAAS,KAAG,YACR,CAAC;AAErD,eAAO,MAAM,UAAU,GAAI,OAAO,SAAS,KAAG,WAW7C,CAAC;AAeF,eAAO,MAAM,QAAQ,QAAO,MACoD,CAAC;AA2BjF,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,IAOlD,CAAC;AAWF,+EAA+E;AAC/E,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG,MAA4C,CAAC;AAE7F;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,KAAG,MAG1B,CAAC;AAEnB,0DAA0D;AAC1D,eAAO,MAAM,OAAO,GAAI,KAAK,MAAM,KAAG,OAGrC,CAAC;AAEF,oFAAoF;AACpF,eAAO,MAAM,YAAY,GAAI,KAAK,MAAM,KAAG,YAU1C,CAAC"}

package/dist/gate.js

@@ -78,13 +78,23 @@ const ownedByCurrentUser = (path) => {
         return false;
     }
 };
-/** Resolve a state file: current location first, then user-owned legacy /tmp. */
+/**
+ * Resolve a state file: current location first, then user-owned legacy /tmp,
+ * then — for `pushmode` only — the machine-wide default written by
+ * `/zeph-quiet --global`. Mirrors plugin/hooks/gate.sh zeph_state_present,
+ * including the deliberate absence of a global mute (see the comment there).
+ */
 const findStateFile = (kind, hash) => {
     const current = (0, path_1.join)((0, exports.stateDir)(), `${kind}-${hash}`);
     if ((0, fs_1.existsSync)(current))
         return current;
     const legacy = `/tmp/zeph-${kind}-${hash}`;
-    return ownedByCurrentUser(legacy) ? legacy : null;
+    if (ownedByCurrentUser(legacy))
+        return legacy;
+    if (kind !== 'pushmode')
+        return null;
+    const globalDefault = (0, path_1.join)((0, exports.stateDir)(), 'pushmode-default');
+    return (0, fs_1.existsSync)(globalDefault) ? globalDefault : null;
 };
 const projectHash = (dir) => {
     try {

package/dist/installer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../src/installer.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AA4BzC;;;GAGG;AACH;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,YAAY,MAAM,GAAG,SAAS,EAAE,SAAS,OAAO,KAAG,OACxD,CAAC;AAoBzB;6EAC6E;AAC7E,eAAO,MAAM,aAAa,GAAI,UAAU,MAAM,EAAE,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,IAqBhF,CAAC;AAgQF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,KAAK,EAAE,EAAE,MAAM,MAAM,KAAG,KAAK,EAKxE,CAAC;AA8EF,eAAO,MAAM,aAAa,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CAkG1F,CAAC"}
+{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../src/installer.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AA4BzC;;;GAGG;AACH;;;;GAIG;AACH,eAAO,MAAM,YAAY,GAAI,YAAY,MAAM,GAAG,SAAS,EAAE,SAAS,OAAO,KAAG,OACxD,CAAC;AAoBzB;6EAC6E;AAC7E,eAAO,MAAM,aAAa,GAAI,UAAU,MAAM,EAAE,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,IAqBhF,CAAC;AAgQF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,KAAK,EAAE,EAAE,MAAM,MAAM,KAAG,KAAK,EAKxE,CAAC;AA8EF,eAAO,MAAM,aAAa,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CA4G1F,CAAC"}

package/dist/installer.js

@@ -485,6 +485,15 @@ const handleInstall = async (args) => {
     console.log('\n  Testing connection...');
     await testConnection(apiKey, baseUrl);
     console.log('\n  Done! Restart your agents.\n');
+    // The single most-reported surprise: pushes are not scoped to `zeph cc`.
+    // Hooks fire for every session of every configured agent, so say it here —
+    // at the moment the hooks get installed — together with the volume dials.
+    console.log('  Notifications now fire for EVERY session of each agent above');
+    console.log('  (not only sessions launched with `zeph cc`). Dial the volume');
+    console.log('  any time — in Claude Code:');
+    console.log('    /zeph-quiet --global   only blockers + high-priority, all projects');
+    console.log('    /zeph-mute             full silence, current project');
+    console.log('    /zeph-status           show what is in effect\n');
     return 0;
 };
 exports.handleInstall = handleInstall;

package/dist/listener-process.d.ts

@@ -0,0 +1,63 @@
+export declare const LISTENER_PID_FILE: string;
+/** CLI version the running daemon booted from. Absent ⇒ pre-stamp build. */
+export declare const LISTENER_VERSION_FILE: string;
+export declare const LISTENER_LOG_FILE: string;
+/**
+ * PID of the listener on record, or null when the file is missing or stale.
+ * Stale PID files (process gone) read as "no listener" so a crashed daemon
+ * never blocks the next autostart.
+ */
+export declare const runningListenerPid: () => number | null;
+/**
+ * CLI version the running daemon started from, or null when unknown.
+ * null is meaningful: every build before the stamp existed predates the
+ * live-terminal protocol, so callers treat "unknown" as "stale".
+ */
+export declare const runningListenerVersion: () => string | null;
+/** Claim the singleton slot for THIS process and stamp the version with it. */
+export declare const writeListenerRuntime: (version: string) => void;
+/**
+ * Drop the PID/version stamps, but only when they still name `pid` — a
+ * successor that already claimed the slot must not be trampled by a
+ * predecessor's exit handler.
+ */
+export declare const clearListenerRuntime: (pid: number) => void;
+/**
+ * Drop stamps left behind by a daemon that died without running its exit
+ * handler (crash, SIGKILL, reboot-era leftovers). No-op while one is alive.
+ */
+export declare const clearStaleListenerRuntime: () => void;
+/**
+ * Stop the daemon and wait for the process to actually go away. SIGTERM
+ * first so its exit handler clears the stamps, SIGKILL once the grace window
+ * expires. Resolves true when the process is confirmed gone.
+ *
+ * Waiting matters: the caller's next move is spawning a replacement, and two
+ * live daemons on one machine both answer the same pushes.
+ */
+export declare const stopListener: (pid: number, timeoutMs?: number) => Promise<boolean>;
+/**
+ * Path to the running cli.js entry. wrapper.js/listener.js sit next to cli.js
+ * in dist/, so __dirname resolves it directly — independent of how the user
+ * invoked us.
+ *
+ * `process.argv[1]` is unreliable here: when `zeph` runs via the npm-installed
+ * bin shim (`/usr/local/bin/zeph` → cli.js via a wrapper script), argv[1] is
+ * the shim path (`.../bin/zeph`), NOT `cli.js`. That made the original
+ * `/cli\.(js|ts|mjs|cjs)$/` check silently reject the entry and the autospawn
+ * never fired — the bug only surfaced once the user switched to the global
+ * npm install.
+ *
+ * Fall back to argv[1] only when the __dirname-relative file doesn't exist
+ * (some packaging where dist layout differs).
+ */
+export declare const resolveCliPath: () => string | null;
+export declare const rotateListenerLogIfLarge: () => void;
+/**
+ * Launch `zeph listener` detached, with output appended to the listener log
+ * so nothing is lost once we let go of it. Returns false when the cli entry
+ * couldn't be resolved or the spawn failed — the caller decides how loud that
+ * is (autostart is best-effort, an explicit `--restart` is not).
+ */
+export declare const spawnListenerDetached: () => boolean;
+//# sourceMappingURL=listener-process.d.ts.map

package/dist/listener-process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listener-process.d.ts","sourceRoot":"","sources":["../src/listener-process.ts"],"names":[],"mappings":"AAwBA,eAAO,MAAM,iBAAiB,QAAiC,CAAC;AAChE,4EAA4E;AAC5E,eAAO,MAAM,qBAAqB,QAAqC,CAAC;AACxE,eAAO,MAAM,iBAAiB,QAAiC,CAAC;AAIhE;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,QAAO,MAAM,GAAG,IAS9C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,QAAO,MAAM,GAAG,IAMlD,CAAC;AAEF,+EAA+E;AAC/E,eAAO,MAAM,oBAAoB,GAAI,SAAS,MAAM,KAAG,IAItD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,GAAI,KAAK,MAAM,KAAG,IASlD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,yBAAyB,QAAO,IAQ5C,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GAAU,KAAK,MAAM,EAAE,kBAAiB,KAAG,OAAO,CAAC,OAAO,CAqBlF,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc,QAAO,MAAM,GAAG,IAM1C,CAAC;AASF,eAAO,MAAM,wBAAwB,QAAO,IAM3C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,QAAO,OAiBxC,CAAC"}

package/dist/listener-process.js

@@ -0,0 +1,209 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spawnListenerDetached = exports.rotateListenerLogIfLarge = exports.resolveCliPath = exports.stopListener = exports.clearStaleListenerRuntime = exports.clearListenerRuntime = exports.writeListenerRuntime = exports.runningListenerVersion = exports.runningListenerPid = exports.LISTENER_LOG_FILE = exports.LISTENER_VERSION_FILE = exports.LISTENER_PID_FILE = 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");
+/**
+ * Process-level facts about the resident `zeph listener` daemon: where its
+ * PID/version stamps live, whether one is alive, how to stop it and how to
+ * respawn it detached.
+ *
+ * This lives OUTSIDE listener.ts on purpose. `wrapper.ts` (the `zeph cc` hot
+ * path) needs all of it, and importing listener.ts there would drag `ws` +
+ * the crypto stack into every agent launch. Same split as
+ * listener-device-id.ts — one small module both sides can read.
+ *
+ * Why a version stamp at all: `npm i -g @zeph-to/cli` replaces the package on
+ * disk but NOT the daemon already running from the old dist. That daemon
+ * keeps answering pushes (so chat looks fine) while silently ignoring every
+ * subtype added since it started — which is exactly how a pre-1.24 listener
+ * left the phone's live terminal spinning until the machine was rebooted.
+ * Stamping the version next to the PID makes that drift detectable.
+ */
+const ZEPH_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), '.zeph');
+exports.LISTENER_PID_FILE = (0, node_path_1.join)(ZEPH_DIR, 'listener.pid');
+/** CLI version the running daemon booted from. Absent ⇒ pre-stamp build. */
+exports.LISTENER_VERSION_FILE = (0, node_path_1.join)(ZEPH_DIR, 'listener.version');
+exports.LISTENER_LOG_FILE = (0, node_path_1.join)(ZEPH_DIR, 'listener.log');
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * PID of the listener on record, or null when the file is missing or stale.
+ * Stale PID files (process gone) read as "no listener" so a crashed daemon
+ * never blocks the next autostart.
+ */
+const runningListenerPid = () => {
+    try {
+        const pid = Number((0, node_fs_1.readFileSync)(exports.LISTENER_PID_FILE, 'utf-8').trim());
+        if (!Number.isFinite(pid) || pid <= 0)
+            return null;
+        process.kill(pid, 0); // signal 0 = existence check, throws when gone
+        return pid;
+    }
+    catch {
+        return null;
+    }
+};
+exports.runningListenerPid = runningListenerPid;
+/**
+ * CLI version the running daemon started from, or null when unknown.
+ * null is meaningful: every build before the stamp existed predates the
+ * live-terminal protocol, so callers treat "unknown" as "stale".
+ */
+const runningListenerVersion = () => {
+    try {
+        return (0, node_fs_1.readFileSync)(exports.LISTENER_VERSION_FILE, 'utf-8').trim() || null;
+    }
+    catch {
+        return null;
+    }
+};
+exports.runningListenerVersion = runningListenerVersion;
+/** Claim the singleton slot for THIS process and stamp the version with it. */
+const writeListenerRuntime = (version) => {
+    (0, node_fs_1.mkdirSync)(ZEPH_DIR, { recursive: true });
+    (0, node_fs_1.writeFileSync)(exports.LISTENER_PID_FILE, String(process.pid));
+    (0, node_fs_1.writeFileSync)(exports.LISTENER_VERSION_FILE, version);
+};
+exports.writeListenerRuntime = writeListenerRuntime;
+/**
+ * Drop the PID/version stamps, but only when they still name `pid` — a
+ * successor that already claimed the slot must not be trampled by a
+ * predecessor's exit handler.
+ */
+const clearListenerRuntime = (pid) => {
+    try {
+        if (!(0, node_fs_1.existsSync)(exports.LISTENER_PID_FILE))
+            return;
+        if (Number((0, node_fs_1.readFileSync)(exports.LISTENER_PID_FILE, 'utf-8').trim()) !== pid)
+            return;
+        (0, node_fs_1.unlinkSync)(exports.LISTENER_PID_FILE);
+        try {
+            (0, node_fs_1.unlinkSync)(exports.LISTENER_VERSION_FILE);
+        }
+        catch { /* best-effort — a missing stamp is already the desired state */ }
+    }
+    catch { /* best-effort */ }
+};
+exports.clearListenerRuntime = clearListenerRuntime;
+/**
+ * Drop stamps left behind by a daemon that died without running its exit
+ * handler (crash, SIGKILL, reboot-era leftovers). No-op while one is alive.
+ */
+const clearStaleListenerRuntime = () => {
+    if ((0, exports.runningListenerPid)() !== null)
+        return;
+    try {
+        (0, node_fs_1.unlinkSync)(exports.LISTENER_PID_FILE);
+    }
+    catch { /* nothing to clear */ }
+    try {
+        (0, node_fs_1.unlinkSync)(exports.LISTENER_VERSION_FILE);
+    }
+    catch { /* nothing to clear */ }
+};
+exports.clearStaleListenerRuntime = clearStaleListenerRuntime;
+/**
+ * Stop the daemon and wait for the process to actually go away. SIGTERM
+ * first so its exit handler clears the stamps, SIGKILL once the grace window
+ * expires. Resolves true when the process is confirmed gone.
+ *
+ * Waiting matters: the caller's next move is spawning a replacement, and two
+ * live daemons on one machine both answer the same pushes.
+ */
+const stopListener = async (pid, timeoutMs = 3_000) => {
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch {
+        return true; // already gone
+    }
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        await sleep(50);
+        try {
+            process.kill(pid, 0);
+        }
+        catch {
+            (0, exports.clearListenerRuntime)(pid);
+            return true;
+        }
+    }
+    try {
+        process.kill(pid, 'SIGKILL');
+    }
+    catch { /* raced us to exit */ }
+    (0, exports.clearListenerRuntime)(pid);
+    return false;
+};
+exports.stopListener = stopListener;
+/**
+ * Path to the running cli.js entry. wrapper.js/listener.js sit next to cli.js
+ * in dist/, so __dirname resolves it directly — independent of how the user
+ * invoked us.
+ *
+ * `process.argv[1]` is unreliable here: when `zeph` runs via the npm-installed
+ * bin shim (`/usr/local/bin/zeph` → cli.js via a wrapper script), argv[1] is
+ * the shim path (`.../bin/zeph`), NOT `cli.js`. That made the original
+ * `/cli\.(js|ts|mjs|cjs)$/` check silently reject the entry and the autospawn
+ * never fired — the bug only surfaced once the user switched to the global
+ * npm install.
+ *
+ * Fall back to argv[1] only when the __dirname-relative file doesn't exist
+ * (some packaging where dist layout differs).
+ */
+const resolveCliPath = () => {
+    const local = (0, node_path_1.join)(__dirname, 'cli.js');
+    if ((0, node_fs_1.existsSync)(local))
+        return local;
+    const entry = process.argv[1];
+    if (entry && /cli\.(js|ts|mjs|cjs)$/.test(entry))
+        return entry;
+    return null;
+};
+exports.resolveCliPath = resolveCliPath;
+/**
+ * Rotate the listener log once it grows past 5 MB. The daemon runs for days
+ * and writes 2-3 lines per 5-s cycle, so without rotation the file climbs
+ * into the tens of megabytes. Keep the previous run's tail under `.old`.
+ */
+const LISTENER_LOG_MAX_BYTES = 5 * 1024 * 1024;
+const rotateListenerLogIfLarge = () => {
+    try {
+        if (!(0, node_fs_1.existsSync)(exports.LISTENER_LOG_FILE))
+            return;
+        if ((0, node_fs_1.statSync)(exports.LISTENER_LOG_FILE).size <= LISTENER_LOG_MAX_BYTES)
+            return;
+        (0, node_fs_1.renameSync)(exports.LISTENER_LOG_FILE, exports.LISTENER_LOG_FILE + '.old');
+    }
+    catch { /* best-effort */ }
+};
+exports.rotateListenerLogIfLarge = rotateListenerLogIfLarge;
+/**
+ * Launch `zeph listener` detached, with output appended to the listener log
+ * so nothing is lost once we let go of it. Returns false when the cli entry
+ * couldn't be resolved or the spawn failed — the caller decides how loud that
+ * is (autostart is best-effort, an explicit `--restart` is not).
+ */
+const spawnListenerDetached = () => {
+    const cliPath = (0, exports.resolveCliPath)();
+    if (!cliPath)
+        return false;
+    try {
+        (0, node_fs_1.mkdirSync)(ZEPH_DIR, { recursive: true });
+        (0, exports.rotateListenerLogIfLarge)();
+        const out = (0, node_fs_1.openSync)(exports.LISTENER_LOG_FILE, 'a');
+        const child = (0, node_child_process_1.spawn)(process.execPath, [cliPath, 'listener'], {
+            detached: true,
+            stdio: ['ignore', out, out],
+            env: { ...process.env, ZEPH_LISTENER_AUTOSTART: '1' },
+        });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+exports.spawnListenerDetached = spawnListenerDetached;

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":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAoBH,OAAO,EAA2B,KAAK,SAAS,EAAE,KAAK,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AACzG,OAAO,EAAiD,KAAK,UAAU,EAA4C,MAAM,kBAAkB,CAAC;AAE5I,OAAO,EAA0D,KAAK,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAmCrH,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAElD,UAAU,YAAY;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,SAAS,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAAI,UAAU,YAAY,EAAE,KAAG,MAS7C,CAAC;AAEnB;6BAC6B;AAC7B,eAAO,MAAM,iBAAiB,GAC1B,aAAa,MAAM,EACnB,qBAAqB,MAAM,GAAG,IAAI,EAClC,cAAc,MAAM,EACpB,OAAO,MAAM,KACd,OAEoD,CAAC;AAYxD,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAA+B,CAAC;AAenF,eAAO,MAAM,cAAc,GAAI,SAAS,MAAM,EAAE,MAAK,MAAmB,KAAG,OAgB1E,CAAC;AAEF,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,GAAI,SAAS,MAAM,KAAG,MAAM,GAAG,IAO7D,CAAC;AAsCF;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,EAAE,KAAG,MAAM,EAAE,GAAG,IAQvD,CAAC;AA0CF;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,QAAO,IAG5C,CAAC;AA8NF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,IAK3F,CAAC;AAEF,UAAU,QAAQ;IACd,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAiDD;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,QAAQ,KAAG,qBAAqB,GAAG,IAGhE,CAAC;AA0BZ,iBAAiB;AACjB,eAAO,MAAM,kBAAkB,QAAO,IAErC,CAAC;AAWF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAC3B,MAAM,MAAM,EACZ,WAAW,SAAS,EACpB,UAAU,MAAM,GAAG,IAAI,EACvB,MAAK,MAAmB,KACzB,IAAI,CAAC,YAAY,EAAE,OAAO,GAAG,gBAAgB,GAAG,aAAa,CAmB/D,CAAC;AAWF,MAAM,WAAW,YAAY;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACnB;AASD,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB,GAAI,KAAK,OAAO,KAAG,IAWhD,CAAC;AAEF,iBAAiB;AACjB,eAAO,MAAM,mBAAmB,QAAO,IAGtC,CAAC;AAEF,MAAM,WAAW,QAAQ;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GACzB,WAAW,WAAW,CAAC,MAAM,CAAC,EAC9B,UAAS,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,IAAsB,KAC9D,QAAQ,EAgBV,CAAC;AAWF,MAAM,WAAW,aAAa;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC3B,OAAO,EAAE,uBAAuB,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,GAAI,KAAK,aAAa,KAAG,cAAc,GAAG,IAmBzE,CAAC;AAyCF;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,GAChC,aAAa,MAAM,EACnB,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,EAC7C,SAAQ,MAAM,EAA8B,KAC7C,IAiBF,CAAC;AAcF,MAAM,WAAW,aAAa;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAChC;AAmBD,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAyCxC,eAAO,MAAM,UAAU,GAAI,aAAa,MAAM,KAAG,IAYhD,CAAC;AAEF,eAAO,MAAM,cAAc,QAAO,IAGjC,CAAC;AAEF,oFAAoF;AACpF,MAAM,MAAM,kBAAkB,GAAG;IAC7B,OAAO,EAAE,oBAAoB,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;mEAC+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,SAAS,CAAC,EAAE,yBAAyB,CAAC;CACzC,CAAC;AAEF,4EAA4E;AAC5E,MAAM,MAAM,gBAAgB,GAAG;IAC3B,OAAO,EAAE,oBAAoB,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,iBAAiB,GAAG,kBAAkB,GAAG,gBAAgB,GAAG,cAAc,CAAC;CACrF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,aAAa,MAAM,KAAG,OAChB,CAAC;AAQ1C;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GACzB,UAAU;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,EACjD,aAAa,MAAM,EACnB,sBAAsB,MAAM,KAC7B,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAenC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAC5B,KAAK,aAAa,EAClB,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,KAC9C,OA0GF,CAAC;AAEF,MAAM,WAAW,aAAa;IAC1B,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,0EAA0E;IAC1E,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrD;AAED;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,QAAO,aAiEzC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,QAAO,YAAY,EAAuC,CAAC;AAIvF;;;;;GAKG;AACH,UAAU,kBAAkB;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,UAAU,QAAQ;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;sEACkE;IAClE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,uEAAuE;IACvE,KAAK,CAAC,EAAE,kBAAkB,EAAE,CAAC;CAChC;AAED,UAAU,cAAc;IACpB,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACjD,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACpD,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC;IAC1D,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IACzC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,oEAAoE;IACpE,mBAAmB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,EAAE,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACzF,+DAA+D;IAC/D,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IAC7C;sEACkE;IAClE,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9C;AAwBD;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,GAC1B,SAAS,MAAM,EACf,MAAM,MAAM,EACZ,MAAK,MAAM,MAAiB,KAC7B,OAUF,CAAC;AAwCF,eAAO,MAAM,oBAAoB,GAAI,KAAK;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,KAAG,IAE/E,CAAC;AA2FF;;;;GAIG;AACH,eAAO,MAAM,aAAa,GACtB,MAAK,MAAmB,EACxB,MAAK,MAAwB,EAC7B,MAAK,MAA0B,KAChC,MAaF,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,GACnB,MAAM,QAAQ,EACd,OAAM,cAAmB,KAC1B,OAAO,CAAC,OAAO,CAoCjB,CAAC;AAcF,eAAO,MAAM,cAAc,GAAI,SAAS,MAAM,KAAG,MAIhD,CAAC;AA4DF,eAAO,MAAM,uBAAuB,GAAI,OAAO,MAAM,KAAG,MA2BvD,CAAC;AAgPF;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GACrB,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,EACtC,QAAQ;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EAC1B,SAAS,MAAM,KAChB,MAAM,GAAG,IAIX,CAAC;AA0DF,eAAO,MAAM,cAAc,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CAsI3F,CAAC"}

package/dist/listener.js

@@ -33,6 +33,7 @@ const os_1 = require("os");
 const path_1 = require("path");
 const ws_1 = __importDefault(require("ws"));
 const config_js_1 = require("./config.js");
+const listener_process_js_1 = require("./listener-process.js");
 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");
@@ -1644,8 +1645,6 @@ const resolveWsUrl = (args, config, baseUrl) => {
 };
 exports.resolveWsUrl = resolveWsUrl;
 // ── Singleton guard (PID file) ──────────────────────────────────────
-const ZEPH_DIR = (0, path_1.join)((0, os_1.homedir)(), '.zeph');
-const LISTENER_PID_FILE = (0, path_1.join)(ZEPH_DIR, 'listener.pid');
 /**
  * Whether another `zeph listener` is already running on this machine.
  * The wrapper's autostart and a user typing `zeph listener` by hand can
@@ -1656,38 +1655,54 @@ const LISTENER_PID_FILE = (0, path_1.join)(ZEPH_DIR, 'listener.pid');
  * wrapper can recover from crashes without manual cleanup.
  */
 const otherListenerAlive = () => {
-    try {
-        const pid = Number((0, fs_1.readFileSync)(LISTENER_PID_FILE, 'utf-8').trim());
-        if (!Number.isFinite(pid) || pid <= 0 || pid === process.pid)
-            return null;
-        process.kill(pid, 0); // existence check, throws if dead
-        return pid;
-    }
-    catch {
-        return null;
-    }
+    const pid = (0, listener_process_js_1.runningListenerPid)();
+    return pid === null || pid === process.pid ? null : pid;
 };
 const writeListenerPid = () => {
     try {
-        (0, fs_1.mkdirSync)(ZEPH_DIR, { recursive: true });
-        (0, fs_1.writeFileSync)(LISTENER_PID_FILE, String(process.pid));
+        // Stamp the version alongside the pid: `npm i -g` swaps the package
+        // on disk without touching this already-running process, and the
+        // stamp is how `zeph cc` notices the drift and restarts us.
+        (0, listener_process_js_1.writeListenerRuntime)(config_js_1.VERSION);
     }
     catch (err) {
-        log(`! could not write ${LISTENER_PID_FILE}: ${err.message}`);
+        log(`! could not write ${listener_process_js_1.LISTENER_PID_FILE}: ${err.message}`);
     }
 };
-const removeListenerPid = () => {
-    try {
-        if (!(0, fs_1.existsSync)(LISTENER_PID_FILE))
-            return;
-        // Only remove our own pid file — don't trample a successor's.
-        const pid = Number((0, fs_1.readFileSync)(LISTENER_PID_FILE, 'utf-8').trim());
-        if (pid === process.pid)
-            (0, fs_1.unlinkSync)(LISTENER_PID_FILE);
+const removeListenerPid = () => (0, listener_process_js_1.clearListenerRuntime)(process.pid);
+/**
+ * `--stop` / `--restart`: the daemon is a background service, so the only
+ * way to replace a stale one used to be hunting its pid by hand. `--restart`
+ * relaunches detached (not in the caller's foreground) because restarting is
+ * an ops action — the user wants their shell back, not a new daemon pinned
+ * to it.
+ */
+const handleListenerLifecycle = async (restart) => {
+    const pid = otherListenerAlive();
+    if (pid) {
+        const stopped = await (0, listener_process_js_1.stopListener)(pid);
+        console.log(`zeph listener: stopped pid ${pid}${stopped ? '' : ' (forced)'}`);
     }
-    catch { /* best-effort */ }
+    else {
+        console.log('zeph listener: no listener running');
+        // A pid file left behind by a crashed daemon would otherwise keep
+        // tripping the singleton guard on the next start.
+        (0, listener_process_js_1.clearStaleListenerRuntime)();
+    }
+    if (!restart)
+        return 0;
+    if (!(0, listener_process_js_1.spawnListenerDetached)()) {
+        console.error('zeph listener: could not resolve the cli entry to respawn — run `zeph listener` manually.');
+        return 1;
+    }
+    console.log(`zeph listener: restarted in background (log: ${listener_process_js_1.LISTENER_LOG_FILE})`);
+    return 0;
 };
 const handleListener = async (args) => {
+    // Lifecycle flags run before verifyTmux — stopping a daemon shouldn't
+    // require a healthy tmux.
+    if (args.stop === true || args.restart === true)
+        return handleListenerLifecycle(args.restart === true);
     verifyTmux();
     // Refuse to start when another listener is already running. The
     // wrapper's autostart calls us blindly on every `zeph cc`; the user
@@ -1723,7 +1738,10 @@ const handleListener = async (args) => {
     }
     writeListenerPid();
     process.on('exit', removeListenerPid);
-    log(`zeph listener starting — ${wsUrl}`);
+    // Version on the first line: the only way to tell which build a
+    // long-lived daemon is actually running (an `npm i -g` days ago says
+    // nothing about the process that's been up since before it).
+    log(`zeph listener starting — v${config_js_1.VERSION} — ${wsUrl}`);
     log(`device=${(0, exports.computeListenerDeviceId)()} host=${(0, os_1.hostname)()} pid=${process.pid}`);
     log("Waiting for 'agent.command' pushes from the phone picker. Ctrl-C to stop.");
     // Heartbeat memory log — once an hour. Lets the user (and us) spot

package/dist/wrapper.d.ts

@@ -17,6 +17,31 @@ export declare const tmuxSessionName: (project: string) => string;
  * dependency-free against the user's running tmux server.
  */
 export declare const findAvailableSession: (base: string) => string;
+/**
+ * Whether the daemon on record is running a different build than the one
+ * we're launching from. `npm i -g @zeph-to/cli` swaps dist/ but leaves the
+ * live process untouched, so a daemon can stay days behind the installed
+ * package — answering pushes (chat looks fine) while silently ignoring every
+ * message subtype added since it booted. That is exactly how a pre-1.24
+ * listener left the phone's live terminal spinning until a reboot.
+ *
+ * A missing stamp means the daemon predates version stamping, which puts it
+ * behind by definition — treat unknown as drifted.
+ *
+ * Strictly "installed is newer", never a plain inequality: one account can
+ * have several installs at different versions (nvm node versions, a repo
+ * build alongside the global one), and `!==` would make each `zeph cc` kill
+ * and respawn the other's daemon forever. An older `zeph cc` leaves a newer
+ * daemon alone — downgrading it would reintroduce the very gap this closes.
+ */
+export declare const listenerVersionDrifted: (running: string | null, installed: string) => boolean;
+/**
+ * Make sure the phone-bridge daemon is running AND is the build we just
+ * launched from. `zeph cc` is the right moment to replace a drifted one: the
+ * user is starting fresh work rather than mid-task, so the ~1s restart window
+ * (in which a push would be dropped — WS fan-out has no queue) costs nothing.
+ */
+export declare const ensureListenerRunning: () => Promise<void>;
 /**
  * Launch the agent in a named tmux session (or directly if nested) and
  * forward its exit code. `extra` is appended to the agent invocation, so

package/dist/wrapper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wrapper.d.ts","sourceRoot":"","sources":["../src/wrapper.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAOtD,kFAAkF;AAClF,eAAO,MAAM,iBAAiB,QAAO,MAapC,CAAC;AAEF,+DAA+D;AAC/D,eAAO,MAAM,eAAe,GAAI,SAAS,MAAM,KAAG,MAA2B,CAAC;AAI9E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,KAAG,MAenD,CAAC;AA6HF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,WAAW,EAAE,QAAO,MAAM,EAAO,KAAG,OAAO,CAAC,MAAM,CAmC3F,CAAC"}
+{"version":3,"file":"wrapper.d.ts","sourceRoot":"","sources":["../src/wrapper.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAOtD,kFAAkF;AAClF,eAAO,MAAM,iBAAiB,QAAO,MAapC,CAAC;AAEF,+DAA+D;AAC/D,eAAO,MAAM,eAAe,GAAI,SAAS,MAAM,KAAG,MAA2B,CAAC;AAI9E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,KAAG,MAenD,CAAC;AAmCF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,sBAAsB,GAAI,SAAS,MAAM,GAAG,IAAI,EAAE,WAAW,MAAM,KAAG,OAChC,CAAC;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,QAAa,OAAO,CAAC,IAAI,CAa1D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAU,OAAO,WAAW,EAAE,QAAO,MAAM,EAAO,KAAG,OAAO,CAAC,MAAM,CAmCjG,CAAC"}

package/dist/wrapper.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handleAgentSession = exports.findAvailableSession = exports.tmuxSessionName = exports.detectProjectName = void 0;
+exports.handleAgentSession = exports.ensureListenerRunning = exports.listenerVersionDrifted = exports.findAvailableSession = exports.tmuxSessionName = exports.detectProjectName = void 0;
 /**
  * `zeph cc` / `zeph codex` / `zeph gemini` — spawn an agent inside a named
  * tmux session so the resident listener (`zeph listener`) can address it
@@ -13,10 +13,10 @@ exports.handleAgentSession = exports.findAvailableSession = exports.tmuxSessionN
  * agent directly — letting power users keep their own multiplexer setup.
  */
 const child_process_1 = require("child_process");
-const fs_1 = require("fs");
-const os_1 = require("os");
 const path_1 = require("path");
+const check_update_js_1 = require("./check-update.js");
 const config_js_1 = require("./config.js");
+const listener_process_js_1 = require("./listener-process.js");
 const FALLBACK_NAME = 'project';
 /** basename(), with a stable fallback for edge paths like `/`. */
 const safeBasename = (path) => (0, path_1.basename)(path) || FALLBACK_NAME;
@@ -99,111 +99,60 @@ const targetForAgent = (agent, extra) => {
     return { cmd: 'tmux', args: ['new', '-A', '-s', session, shellCmd] };
 };
 // ── Background listener auto-start ────────────────────────────────────
-const ZEPH_DIR = (0, path_1.join)((0, os_1.homedir)(), '.zeph');
-const LISTENER_PID_FILE = (0, path_1.join)(ZEPH_DIR, 'listener.pid');
-const LISTENER_LOG_FILE = (0, path_1.join)(ZEPH_DIR, 'listener.log');
-/** True when the PID file points at a still-alive process. */
-const listenerAlive = () => {
-    try {
-        const pid = Number((0, fs_1.readFileSync)(LISTENER_PID_FILE, 'utf-8').trim());
-        if (!Number.isFinite(pid) || pid <= 0)
-            return false;
-        // Signal 0 = existence check; throws when the process is gone.
-        process.kill(pid, 0);
-        return true;
-    }
-    catch {
-        return false;
-    }
-};
 /**
- * Path to the running cli.js entry. wrapper.js sits next to cli.js in
- * dist/, so __dirname resolves it directly — independent of how the
- * user invoked us.
+ * Whether the daemon on record is running a different build than the one
+ * we're launching from. `npm i -g @zeph-to/cli` swaps dist/ but leaves the
+ * live process untouched, so a daemon can stay days behind the installed
+ * package — answering pushes (chat looks fine) while silently ignoring every
+ * message subtype added since it booted. That is exactly how a pre-1.24
+ * listener left the phone's live terminal spinning until a reboot.
  *
- * `process.argv[1]` is unreliable here: when `zeph` runs via the
- * npm-installed bin shim (`/usr/local/bin/zeph` → cli.js via a wrapper
- * script), argv[1] is the shim path (`.../bin/zeph`), NOT `cli.js`.
- * That made the original `/cli\\.(js|ts|mjs|cjs)$/` check silently
- * reject the entry and the autospawn never fired — exactly the bug
- * the user hit ('원래 싱글톤으로 됐었잖아' — yes, on the local alias
- * path where argv[1] IS cli.js; the bug only surfaced once the user
- * switched to the global npm install).
+ * A missing stamp means the daemon predates version stamping, which puts it
+ * behind by definition — treat unknown as drifted.
  *
- * Fall back to argv[1] only when the __dirname-relative file doesn't
- * exist (some packaging where dist layout differs).
+ * Strictly "installed is newer", never a plain inequality: one account can
+ * have several installs at different versions (nvm node versions, a repo
+ * build alongside the global one), and `!==` would make each `zeph cc` kill
+ * and respawn the other's daemon forever. An older `zeph cc` leaves a newer
+ * daemon alone — downgrading it would reintroduce the very gap this closes.
  */
-const resolveCliPath = () => {
-    const local = (0, path_1.join)(__dirname, 'cli.js');
-    if ((0, fs_1.existsSync)(local))
-        return local;
-    const entry = process.argv[1];
-    if (entry && /cli\.(js|ts|mjs|cjs)$/.test(entry))
-        return entry;
-    return null;
-};
+const listenerVersionDrifted = (running, installed) => running === null || (0, check_update_js_1.isNewer)(installed, running);
+exports.listenerVersionDrifted = listenerVersionDrifted;
 /**
- * Spawn `zeph listener` in the background if it isn't already running on
- * this machine. The intent is that the user only ever has to know about
- * `zeph cc` — the phone-to-tmux bridge tags along automatically. Output
- * goes to `~/.zeph/listener.log` so it isn't lost on detach; the listener
- * itself writes its own PID to `~/.zeph/listener.pid` on startup and
- * removes it on graceful exit, so subsequent `zeph cc` invocations skip
- * the spawn when a listener is already up.
- *
- * Failure here is non-fatal — `zeph cc` still launches the agent. The
- * user just loses the phone-bridge feature until they restart.
+ * Make sure the phone-bridge daemon is running AND is the build we just
+ * launched from. `zeph cc` is the right moment to replace a drifted one: the
+ * user is starting fresh work rather than mid-task, so the ~1s restart window
+ * (in which a push would be dropped — WS fan-out has no queue) costs nothing.
  */
-/**
- * Rotate the listener log once it grows past 5 MB. The daemon runs for
- * days and writes 2-3 lines per 5-s cycle, so without rotation the file
- * climbs into the tens of megabytes range pretty quickly. We keep the
- * previous run's tail under `.old` for post-mortem and start fresh.
- */
-const LISTENER_LOG_MAX_BYTES = 5 * 1024 * 1024;
-const rotateListenerLogIfLarge = () => {
-    try {
-        if (!(0, fs_1.existsSync)(LISTENER_LOG_FILE))
-            return;
-        if ((0, fs_1.statSync)(LISTENER_LOG_FILE).size <= LISTENER_LOG_MAX_BYTES)
+const ensureListenerRunning = async () => {
+    const pid = (0, listener_process_js_1.runningListenerPid)();
+    if (pid !== null) {
+        const running = (0, listener_process_js_1.runningListenerVersion)();
+        if (!(0, exports.listenerVersionDrifted)(running, config_js_1.VERSION))
             return;
-        (0, fs_1.renameSync)(LISTENER_LOG_FILE, LISTENER_LOG_FILE + '.old');
+        console.log(`zeph: listener ${running ?? '(pre-1.26)'} is stale — restarting on ${config_js_1.VERSION}`);
+        await (0, listener_process_js_1.stopListener)(pid);
     }
-    catch { /* best-effort */ }
-};
-const ensureListenerRunning = () => {
-    if (listenerAlive())
-        return;
-    const cliPath = resolveCliPath();
-    if (!cliPath || !(0, fs_1.existsSync)(cliPath))
-        return;
-    try {
-        (0, fs_1.mkdirSync)(ZEPH_DIR, { recursive: true });
-        rotateListenerLogIfLarge();
-        const out = (0, fs_1.openSync)(LISTENER_LOG_FILE, 'a');
-        const child = (0, child_process_1.spawn)(process.execPath, [cliPath, 'listener'], {
-            detached: true,
-            stdio: ['ignore', out, out],
-            env: { ...process.env, ZEPH_LISTENER_AUTOSTART: '1' },
-        });
-        child.unref();
-        console.log(`zeph: listener autostarted in background (log: ${LISTENER_LOG_FILE})`);
+    if ((0, listener_process_js_1.spawnListenerDetached)()) {
+        if (pid === null)
+            console.log(`zeph: listener autostarted in background (log: ${listener_process_js_1.LISTENER_LOG_FILE})`);
     }
-    catch (err) {
-        console.error(`zeph: listener autostart failed: ${err.message}`);
+    else {
+        console.error('zeph: listener autostart failed — run `zeph listener` manually.');
     }
 };
+exports.ensureListenerRunning = ensureListenerRunning;
 /**
  * Launch the agent in a named tmux session (or directly if nested) and
  * forward its exit code. `extra` is appended to the agent invocation, so
  * `zeph cc --resume foo` runs `claude --resume foo` inside the session.
  * Returns when the agent exits.
  */
-const handleAgentSession = (agent, extra = []) => {
-    // Best-effort: make sure the phone-bridge daemon is running before we
-    // launch the agent. The user shouldn't need to remember a second
-    // command for the picker on their phone to work.
-    ensureListenerRunning();
+const handleAgentSession = async (agent, extra = []) => {
+    // Best-effort: make sure the phone-bridge daemon is running, and running
+    // the build we were launched from. The user shouldn't need to remember a
+    // second command for the picker on their phone to work.
+    await (0, exports.ensureListenerRunning)();
     return new Promise((resolve) => {
         const { cmd, args } = targetForAgent(agent.binary, extra);
         const start = Date.now();

package/package.json

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