@zeph-to/cli 2.6.0 → 2.8.0

package/README.md

@@ -244,7 +244,8 @@ block here.
    `zeph listener` by hand — every `zeph cc` checks the PID file and
    skips the spawn when one is already alive, so opening a dozen
    terminals doesn't create a dozen daemons. The daemon survives
-   between `zeph cc` invocations.
+   between `zeph cc` invocations — but not a reboot, which is what the
+   login-time service below is for.
 
    Project name resolves from `CLAUDE_PROJECT_DIR` /
    `CURSOR_PROJECT_DIR` / `WINDSURF_PROJECT_DIR` if set, else the git
@@ -271,6 +272,43 @@ block here.
    listener can't target an unnamed session that way, but you keep your
    existing multiplexer setup.
 
+### Starting the listener at login (macOS)
+
+A reboot ends the daemon, and nothing starts it again until you open a
+terminal and run `zeph cc`. Until you do, the phone shows **no agents** —
+the machine is on, the past sessions are on disk, and the app has no one
+to hear from.
+
+```bash
+zeph listener --install-service
+```
+
+That registers a launchd LaunchAgent (`to.zeph.listener`) that starts the
+listener at every login. `--uninstall-service` removes it and
+`--service-status` shows what the installed one points at; `zeph install`
+offers it during setup and `zeph uninstall` takes it away again.
+
+What you get back after a reboot is your **past sessions**, ready to
+resume from the phone — not live agents. tmux does not survive a reboot
+either, and this doesn't try to bring those sessions back to life.
+
+Two details worth knowing:
+
+- It fires at **user login**, not at boot. Without automatic login, the
+  machine stays silent while it sits on the login screen.
+- The plist bakes in absolute paths for node and the CLI, a `PATH` that
+  can reach tmux, and a UTF-8 `LANG`. launchd gives a job
+  `/usr/bin:/bin:/usr/sbin:/sbin` and no locale at all: without the PATH
+  the daemon exits 127 at every login, and without the locale tmux
+  escapes the separator the session list is split on, so every session is
+  silently dropped while everything else looks healthy. If any of that
+  drifts — a version-manager node upgrade, say — `zeph verify` names it,
+  and re-running `--install-service` repoints the plist.
+
+With the service installed, launchd owns the process: `zeph cc` and
+`zeph listener --stop|--restart` ask launchd rather than signalling the
+PID, so there is never a second daemon racing the first.
+
 ### Diagnostics
 
 The auto-spawned listener writes to three files under `~/.zeph/`:

package/dist/ask.js

@@ -141,7 +141,7 @@ const handleAsk = async (args) => {
     // hook maps that to DENY — a command blocked for a reason that has nothing
     // to do with the user. Every other command in cli.ts resolves env this way.
     const apiKey = args['api-key'] || (0, config_js_1.resolvedEnv)('ZEPH_API_KEY') || config.apiKey;
-    const hookId = args.hook || (0, config_js_1.resolvedEnv)('ZEPH_HOOK_ID') || config.hookId;
+    const hookId = args.hook || (0, config_js_1.resolveHookId)();
     const title = args.title || '';
     if (!apiKey || !hookId || !title) {
         const missing = [!title && '--title', !apiKey && 'an API key', !hookId && 'a hook id']

package/dist/cli.js

@@ -90,6 +90,15 @@ ${usageAgentLines()}
                   --restart  stop it and relaunch in the background
                              (needed after an upgrade: 'npm i -g' swaps
                               the package but never the live process)
+                  --install-service
+                             start the listener at every login (macOS
+                             launchd). Without it the daemon only exists
+                             after a 'zeph cc', so a reboot leaves the
+                             phone picker empty until you open a terminal
+                  --uninstall-service
+                             remove the login-time service
+                  --service-status
+                             show what the installed service points at
 
 Notify options:
   --title <text>     Push title
@@ -126,6 +135,10 @@ Install options:
    to manual key entry)
   --key <api-key>    API key (non-interactive; skips browser login)
   --hook <hook-id>   Hook ID (non-interactive)
+  --service          Install the login-time listener service without
+                     asking (macOS). Interactive runs offer it anyway;
+                     scripted runs need this flag
+  --no-service       Never install it
   --base-url <url>   Base URL (non-interactive)
   --relogin          Force a fresh browser sign-in even if a login is
                      already saved (switch account)

package/dist/config.d.ts

@@ -7,7 +7,13 @@ export interface ZephConfig {
     wsUrl?: string;
     deviceId?: string;
 }
-export declare const resolvedEnv: (key: string) => string | undefined;
+export declare const resolvedEnv: (key: string, env?: NodeJS.ProcessEnv) => string | undefined;
+/**
+ * The two-way hook id: `ZEPH_HOOK_ID` when it carries a real value, else
+ * `hookId` from ~/.zeph/config.json — what `zeph setup` writes. The plugin's
+ * gate.sh `zeph_hook_id` and the MCP server resolve it in the same order.
+ */
+export declare const resolveHookId: (env?: NodeJS.ProcessEnv) => string | undefined;
 export declare const PROJECT_DIR_ENV_VARS: readonly ["CLAUDE_PROJECT_DIR", "CURSOR_PROJECT_DIR", "WINDSURF_PROJECT_DIR"];
 /** First set project-dir env (unresolved `${VAR}` placeholders ignored), else cwd. */
 export declare const detectProjectDir: () => string;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,UAAU,QAA2B,CAAC;AACnD,eAAO,MAAM,WAAW,QAAkC,CAAC;AAE3D,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,SAGlD,CAAC;AAMF,eAAO,MAAM,oBAAoB,+EAAgF,CAAC;AAElH,sFAAsF;AACtF,eAAO,MAAM,gBAAgB,QAAO,MAMnC,CAAC;AAEF,eAAO,MAAM,UAAU,QAAO,UAM7B,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,QAAQ,UAAU,KAAG,IAM/C,CAAC;AAEF,eAAO,MAAM,OAAO,QAOhB,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,UAAU,QAA2B,CAAC;AACnD,eAAO,MAAM,WAAW,QAAkC,CAAC;AAE3D,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,EAAE,MAAK,MAAM,CAAC,UAAwB,KAAG,MAAM,GAAG,SAGxF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,MAAK,MAAM,CAAC,UAAwB,KAAG,MAAM,GAAG,SACrB,CAAC;AAM1D,eAAO,MAAM,oBAAoB,+EAAgF,CAAC;AAElH,sFAAsF;AACtF,eAAO,MAAM,gBAAgB,QAAO,MAMnC,CAAC;AAEF,eAAO,MAAM,UAAU,QAAO,UAM7B,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,QAAQ,UAAU,KAAG,IAM/C,CAAC;AAEF,eAAO,MAAM,OAAO,QAOhB,CAAC"}

package/dist/config.js

@@ -1,16 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VERSION = exports.saveConfig = exports.loadConfig = exports.detectProjectDir = exports.PROJECT_DIR_ENV_VARS = exports.resolvedEnv = exports.CONFIG_FILE = exports.CONFIG_DIR = void 0;
+exports.VERSION = exports.saveConfig = exports.loadConfig = exports.detectProjectDir = exports.PROJECT_DIR_ENV_VARS = exports.resolveHookId = exports.resolvedEnv = exports.CONFIG_FILE = exports.CONFIG_DIR = void 0;
 const fs_1 = require("fs");
 const os_1 = require("os");
 const path_1 = require("path");
 exports.CONFIG_DIR = (0, path_1.join)((0, os_1.homedir)(), '.zeph');
 exports.CONFIG_FILE = (0, path_1.join)(exports.CONFIG_DIR, 'config.json');
-const resolvedEnv = (key) => {
-    const val = process.env[key];
+const resolvedEnv = (key, env = process.env) => {
+    const val = env[key];
     return val && !val.startsWith('${') ? val : undefined;
 };
 exports.resolvedEnv = resolvedEnv;
+/**
+ * The two-way hook id: `ZEPH_HOOK_ID` when it carries a real value, else
+ * `hookId` from ~/.zeph/config.json — what `zeph setup` writes. The plugin's
+ * gate.sh `zeph_hook_id` and the MCP server resolve it in the same order.
+ */
+const resolveHookId = (env = process.env) => (0, exports.resolvedEnv)('ZEPH_HOOK_ID', env) || (0, exports.loadConfig)().hookId;
+exports.resolveHookId = resolveHookId;
 // Per-agent project-dir env vars, in precedence order. Deliberately NOT part
 // of the remote-agent registry: Cursor/Windsurf carry project-dir envs but
 // are not remote-controllable via tmux — the two tables have different

package/dist/installer.d.ts

@@ -18,5 +18,16 @@ export declare const mergeJsonFile: (filePath: string, patch: Record<string, unk
  * unit testing.
  */
 export declare const filterAgentsByIds: (detected: Agent[], only: string) => Agent[];
+/**
+ * Whether this install should register the LaunchAgent that starts the
+ * listener at login.
+ *
+ * Interactive installs offer it and default to yes: an empty phone picker
+ * after every reboot is precisely the kind of thing a default should fix.
+ * Scripted installs (`--key`, CI, provisioning) get it only when asked —
+ * planting a background job on a machine whose operator only wanted an API
+ * key written is a surprise, not a convenience.
+ */
+export declare const serviceInstallChoice: (args: Record<string, string | boolean>, nonInteractive: boolean) => "yes" | "no" | "ask";
 export declare const handleInstall: (args: Record<string, string | boolean>) => Promise<number>;
 //# sourceMappingURL=installer.d.ts.map

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,CAgH1F,CAAC"}
+{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../src/installer.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AA6BzC;;;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;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,GAC/B,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,EACtC,gBAAgB,OAAO,KACtB,KAAK,GAAG,IAAI,GAAG,KAKjB,CAAC;AAgCF,eAAO,MAAM,aAAa,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CAuH1F,CAAC"}

package/dist/installer.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handleInstall = exports.filterAgentsByIds = exports.mergeJsonFile = exports.shouldReauth = void 0;
+exports.handleInstall = exports.serviceInstallChoice = exports.filterAgentsByIds = exports.mergeJsonFile = exports.shouldReauth = void 0;
 const child_process_1 = require("child_process");
 const fs_1 = require("fs");
 const os_1 = require("os");
@@ -10,11 +10,13 @@ const zeph_hook_js_1 = require("./zeph-hook.js");
 const config_js_1 = require("./config.js");
 const login_js_1 = require("./login.js");
 const agents_js_1 = require("./agents.js");
+const listener_service_js_1 = require("./listener-service.js");
 const templates_js_1 = require("./templates.js");
 const HOME = (0, os_1.homedir)();
 // ── Helpers ──────────────────────────────────────────────────────
 const ok = (msg) => console.log(`    + ${msg}`);
 const fail = (msg) => console.log(`    - ${msg}`);
+const skipNote = (msg) => console.log(`    · ${msg}`);
 /**
  * True when install should auto-open browser login (ADR 0002): interactive
  * context with no existing credential (--key/env/config all absent).
@@ -392,6 +394,57 @@ const collectCredentials = async (args, installArgs, nonInteractive, existing) =
     const hookInput = await promptInput('  Hook ID (optional, for prompt/input): ');
     return { apiKey, hookId: hookInput || undefined, baseUrl: existing.baseUrl };
 };
+// ── Login-time service ───────────────────────────────────────────
+/**
+ * Whether this install should register the LaunchAgent that starts the
+ * listener at login.
+ *
+ * Interactive installs offer it and default to yes: an empty phone picker
+ * after every reboot is precisely the kind of thing a default should fix.
+ * Scripted installs (`--key`, CI, provisioning) get it only when asked —
+ * planting a background job on a machine whose operator only wanted an API
+ * key written is a surprise, not a convenience.
+ */
+const serviceInstallChoice = (args, nonInteractive) => {
+    if (args['no-service'] === true)
+        return 'no';
+    if (!(0, listener_service_js_1.serviceSupported)())
+        return 'no';
+    if (args.service === true)
+        return 'yes';
+    return nonInteractive ? 'no' : 'ask';
+};
+exports.serviceInstallChoice = serviceInstallChoice;
+/** Run the choice: ask when it should be asked, then install if wanted. */
+const applyServiceChoice = async (choice) => {
+    if (choice === 'no')
+        return;
+    let wanted = choice === 'yes';
+    if (choice === 'ask') {
+        try {
+            const { confirm } = await import('@inquirer/prompts');
+            wanted = await confirm({
+                message: 'Start the listener at every login? (so the phone sees this machine after a reboot)',
+                default: true,
+            });
+        }
+        catch {
+            // Ctrl-C or no TTY — an unanswered question is not a yes.
+            wanted = false;
+        }
+    }
+    if (!wanted) {
+        skipNote('login-time service not installed (add it later: zeph listener --install-service)');
+        return;
+    }
+    const result = await (0, listener_service_js_1.installService)();
+    for (const note of result.notes)
+        ok(note);
+    if (result.ok)
+        ok('listener starts at every login');
+    else
+        fail(`login-time service: ${result.reason}`);
+};
 // ── Main Install Flow ────────────────────────────────────────────
 const handleInstall = async (args) => {
     const installArgs = {
@@ -458,6 +511,9 @@ const handleInstall = async (args) => {
         if (selected.length === 0) {
             console.log('    (no agents selected — only the config file will be saved)');
         }
+        if ((0, exports.serviceInstallChoice)(args, nonInteractive) !== 'no') {
+            console.log('    - Offer to start the listener at every login');
+        }
         console.log('    - Test connection');
     }
     // 5. Save config — merge over the latest on-disk config (re-read, since a
@@ -481,7 +537,10 @@ const handleInstall = async (args) => {
         if (installer)
             installer();
     }
-    // 7. Test connection
+    // 7. Login-time service — the only thing that makes the phone see this
+    //    machine after a reboot without a terminal being opened first.
+    await applyServiceChoice((0, exports.serviceInstallChoice)(args, nonInteractive));
+    // 8. Test connection
     console.log('\n  Testing connection...');
     await testConnection(apiKey, baseUrl);
     console.log('\n  Done! Restart your agents.\n');

package/dist/listener-process.d.ts

@@ -2,6 +2,7 @@ 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;
+export declare const sleep: (ms: number) => Promise<void>;
 /**
  * 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

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

@@ -1 +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"}
+{"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;AAEhE,eAAO,MAAM,KAAK,GAAI,IAAI,MAAM,KAAG,OAAO,CAAC,IAAI,CAAsD,CAAC;AAEtG;;;;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;AAgBF,eAAO,MAAM,wBAAwB,QAAO,IAO3C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,QAAO,OAgBxC,CAAC"}

package/dist/listener-process.js

@@ -1,6 +1,6 @@
 "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;
+exports.spawnListenerDetached = exports.rotateListenerLogIfLarge = exports.resolveCliPath = exports.stopListener = exports.clearStaleListenerRuntime = exports.clearListenerRuntime = exports.writeListenerRuntime = exports.runningListenerVersion = exports.runningListenerPid = exports.sleep = 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");
@@ -28,6 +28,7 @@ exports.LISTENER_PID_FILE = (0, node_path_1.join)(ZEPH_DIR, 'listener.pid');
 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));
+exports.sleep = sleep;
 /**
  * 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
@@ -121,7 +122,7 @@ const stopListener = async (pid, timeoutMs = 3_000) => {
     }
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
-        await sleep(50);
+        await (0, exports.sleep)(50);
         try {
             process.kill(pid, 0);
         }
@@ -166,7 +167,14 @@ 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`.
+ * into the tens of megabytes. Keep the previous window under `.old`.
+ *
+ * Copy-truncate rather than rename, because the writer is not always ours.
+ * Under the login-time LaunchAgent, launchd opens `StandardOutPath` itself
+ * and holds that fd for the life of the job: a rename moves the directory
+ * entry and leaves launchd appending to the very same inode, now called
+ * `.old`. The log the user tails would never shrink. Emptying the file in
+ * place keeps the inode — and the fd — valid.
  */
 const LISTENER_LOG_MAX_BYTES = 5 * 1024 * 1024;
 const rotateListenerLogIfLarge = () => {
@@ -175,7 +183,8 @@ const rotateListenerLogIfLarge = () => {
             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');
+        (0, node_fs_1.copyFileSync)(exports.LISTENER_LOG_FILE, exports.LISTENER_LOG_FILE + '.old');
+        (0, node_fs_1.truncateSync)(exports.LISTENER_LOG_FILE, 0);
     }
     catch { /* best-effort */ }
 };
@@ -192,7 +201,6 @@ const spawnListenerDetached = () => {
         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,

package/dist/listener-service.d.ts

@@ -0,0 +1,165 @@
+/**
+ * The listener as an OS service: a launchd LaunchAgent that starts it at user
+ * login so the phone's picker is populated without anyone opening a terminal.
+ *
+ * Until this existed, the only thing that ever started the daemon was
+ * `zeph cc` (wrapper.ts → spawnListenerDetached). After a reboot that means an
+ * empty picker until the user happens to launch an agent — the machine is
+ * online, the past sessions are on disk, and the app says "no agents".
+ *
+ * Two constraints shape this file:
+ *
+ * 1. **Node builtins only.** wrapper.ts reads `serviceInstalled()` on the
+ *    `zeph cc` hot path, and the same rule that keeps listener.ts out of
+ *    wrapper.ts (ws + the crypto stack on every agent launch) applies here.
+ *    listener-process.ts is the one import, and it is builtins-only too.
+ *
+ * 2. **Everything the job needs is resolved at install time and baked into
+ *    the plist.** launchd hands a job `/usr/bin:/bin:/usr/sbin:/sbin` and
+ *    nothing else — no shell profile, no homebrew prefix. `verifyTmux()`
+ *    (listener.ts) exits 127 when tmux is not on PATH, so a plist without a
+ *    baked PATH produces a service that dies at every login and is restarted
+ *    forever by KeepAlive. The interpreter is baked for the same reason.
+ */
+/** Reverse-DNS launchd label. Lives on the user's machine once installed —
+ *  renaming it orphans every plist already out there. */
+export declare const SERVICE_LABEL = "to.zeph.listener";
+export interface ServiceSpec {
+    readonly nodePath: string;
+    readonly cliPath: string;
+    readonly tmuxPath: string;
+    readonly logPath: string;
+    /** PATH baked into the job: tmux dir, node dir, then launchd's own. */
+    readonly pathEnv: string;
+    /** UTF-8 locale baked into the job. Always UTF-8 — see resolveServiceSpec. */
+    readonly lang: string;
+}
+export type SpecResolution = {
+    readonly ok: true;
+    readonly value: ServiceSpec;
+    readonly warning?: string;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/** The machine facts spec resolution needs, injectable so tests describe a
+ *  machine instead of inheriting the developer's own. */
+export interface ServiceEnv {
+    readonly exists: (path: string) => boolean;
+    /** Major version of the node at `path`, or null when it won't run. */
+    readonly nodeMajor: (path: string) => number | null;
+    /** Absolute tmux path from the invoking shell's PATH, or null. */
+    readonly whichTmux: () => string | null;
+    readonly cliPath: () => string | null;
+    /** The invoking shell's LANG, or undefined when it has none. */
+    readonly lang: () => string | undefined;
+}
+export interface ServiceStatus {
+    readonly supported: boolean;
+    readonly installed: boolean;
+    readonly label: string;
+    readonly plistPath: string;
+    /** Read back from the installed plist — null when nothing is installed. */
+    readonly nodePath: string | null;
+    readonly cliPath: string | null;
+    readonly pathEnv: string | null;
+    readonly langEnv: string | null;
+    /** Programs the plist names that are no longer on disk. The shape a node
+     *  upgrade leaves behind: registered, listed by launchctl, unable to run. */
+    readonly missing: readonly string[];
+}
+/** launchd only exists on macOS. Every other platform is an explicit refusal,
+ *  never a quiet success. */
+export declare const serviceSupported: () => boolean;
+export declare const servicePlistPath: () => string;
+export declare const serviceInstalled: () => boolean;
+export declare const defaultServiceEnv: ServiceEnv;
+/**
+ * Decide what to bake into the plist, or say why we can't. Nothing is written
+ * and nothing is registered — a caller that gets `ok: false` has touched
+ * nothing on the machine.
+ */
+export declare const resolveServiceSpec: (env?: ServiceEnv) => SpecResolution;
+export declare const renderLaunchAgentPlist: (spec: ServiceSpec) => string;
+/**
+ * What is registered on this machine and whether it can still run. The single
+ * source `verify`, `--service-status` and the `zeph cc` branch all read, so
+ * they can never disagree about whether a service is installed.
+ */
+export declare const serviceStatus: () => ServiceStatus;
+/**
+ * Side effects the service operations need, injectable so tests can drive the
+ * launchd sequence without a launchd.
+ */
+export interface ServiceOpDeps {
+    readonly supported: () => boolean;
+    readonly resolveSpec: () => SpecResolution;
+    /** PID of a listener running right now, or null. */
+    readonly runningPid: () => number | null;
+    readonly stopListener: (pid: number) => Promise<boolean>;
+    readonly launchctl: (args: string[]) => {
+        ok: boolean;
+        stderr: string;
+    };
+    readonly settle: (ms: number) => Promise<void>;
+}
+export type ServiceOpResult = {
+    readonly ok: true;
+    readonly notes: readonly string[];
+} | {
+    readonly ok: false;
+    readonly reason: string;
+    readonly notes: readonly string[];
+};
+export declare const defaultServiceOpDeps: ServiceOpDeps;
+/**
+ * Register the LaunchAgent and get the daemon running under it.
+ *
+ * The order is load-bearing, not incidental:
+ *
+ * - **Any listener already running is stopped first.** `handleListener` exits
+ *   **0** when it finds another listener alive, and it only does so quietly
+ *   under ZEPH_LISTENER_AUTOSTART, which a launchd job does not have. So a
+ *   kickstart into a live `zeph cc` daemon produces a clean exit, and
+ *   `KeepAlive:{SuccessfulExit:false}` reads a clean exit as "stay down" —
+ *   for the whole login session. `launchctl list` shows the job; nothing runs.
+ * - **Nothing is written until the spec resolves.** A refusal leaves the
+ *   machine exactly as it was.
+ * - **The daemon is confirmed alive afterwards.** Without that check the
+ *   failure above ships silently.
+ */
+export declare const installService: (deps?: ServiceOpDeps) => Promise<ServiceOpResult>;
+/** Unregister the job and remove the plist. Doing only one of the two leaves
+ *  either a running service with no plist or a plist launchd ignores. */
+export declare const uninstallService: (deps?: ServiceOpDeps) => Promise<ServiceOpResult>;
+/**
+ * Stop the service until the next login.
+ *
+ * `bootout` and not `disable`: disable writes to launchd's persistent disabled
+ * database, survives logins, and leaves no obvious way back — a `--stop` that
+ * quietly becomes permanent. Session-scoped is what stopping should mean.
+ */
+export declare const stopService: (deps?: ServiceOpDeps) => ServiceOpResult;
+/** Restart the service in place. `-k` kills the running instance first, so this
+ *  is also how a version-drifted daemon is replaced. */
+export declare const restartService: (deps?: ServiceOpDeps) => ServiceOpResult;
+export interface ServiceHealthRow {
+    readonly label: string;
+    readonly state: 'pass' | 'warn' | 'fail';
+}
+/** The two live facts a health check can't read off the plist. */
+export interface ServiceProbe {
+    /** Can a process started with this PATH find tmux? */
+    readonly tmuxOnPath: (pathEnv: string) => boolean;
+    /** Is launchd actually running the job right now? */
+    readonly loaded: () => boolean;
+}
+export declare const defaultServiceProbe: ServiceProbe;
+/**
+ * Why this exists: every way the service breaks leaves it looking installed.
+ * `launchctl list` shows the job whether or not its interpreter still exists,
+ * and a PATH without tmux makes the daemon exit 127 at every login while the
+ * registration sits there unchanged. None of that is visible without asking.
+ */
+export declare const serviceHealthChecks: (status: ServiceStatus, probe?: ServiceProbe) => ServiceHealthRow[];
+//# sourceMappingURL=listener-service.d.ts.map

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

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