@zeph-to/cli 2.12.0 → 2.13.0

package/README.md

@@ -200,8 +200,11 @@ block here.
 ### Setup
 
 1. **Install tmux.** The listener uses `send-keys`; the wrapper spawns
-   named sessions. `brew install tmux` on macOS, `apt install tmux` on
-   Debian/Ubuntu.
+   named sessions. `zeph install` checks for it and, on macOS with Homebrew,
+   offers to run `brew install tmux` for you. Elsewhere it prints the line to
+   run — `sudo apt install tmux` on Debian/Ubuntu, and so on — because
+   installing with `sudo` is not something an installer should do on your
+   behalf. tmux has no Windows build, so `zeph cc` needs WSL there.
 
 2. **Add `wsUrl` to `~/.zeph/config.json`** (the WebSocket endpoint of
    your Zeph backend — CDK output `WsApiUrl`):
@@ -527,7 +530,7 @@ zeph notify --title "Hello" --json
 | `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 — reattaches a detached session of that project (newest suffix first) when there is one, else auto-suffixes `-2`, `-3`, …. Auto-spawns the background listener on first invocation so the phone picker just works. Trailing args pass through to the agent (`zeph cc --resume "..."`) |
+| `cc` · `codex` · `gemini` | Run the agent in a `zeph-<project>` tmux session — reattaches a detached session of that project (newest suffix first) when there is one, else auto-suffixes `-2`, `-3`, …. Auto-spawns the background listener on first invocation so the phone picker just works. Trailing args pass through to the agent (`zeph cc --resume "..."`). On node 22.15+ the wrapper hands its process to tmux rather than waiting on it, so a running session shows no `zeph cc` of its own in `ps` — older runtimes and Windows keep the waiting wrapper |
 | `mcp` | Run the MCP server on stdio, in this process. What agent MCP configs launch — `zeph install` registers it and you never type it. Replaces the old `npx -y @zeph-to/mcp-server` registration, which left an `npm exec` launcher resident alongside the server for the life of the session. `@zeph-to/mcp-server` ships as a dependency now, so it updates with the CLI rather than being re-fetched by `npx` on every launch — `zeph check-update` reports the version you actually have |
 | `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/agents.d.ts

@@ -3,6 +3,13 @@ export interface Agent {
     id: string;
     detected: boolean;
 }
+/**
+ * Absolute path of a command on PATH, or null when it isn't there.
+ * `execFileSync`, not a shell: `process.execve` needs a real path (it does no
+ * PATH lookup of its own), and building `which ${cmd}` as a shell string would
+ * let a path containing a space split into two words.
+ */
+export declare const resolveCommand: (cmd: string) => string | null;
 export declare const hasCommand: (cmd: string) => boolean;
 export declare const detectAgents: () => Agent[];
 //# sourceMappingURL=agents.d.ts.map

package/dist/agents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,KAAK;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,OAAO,CAAC;CACrB;AAID,eAAO,MAAM,UAAU,GAAI,KAAK,MAAM,KAAG,OAOxC,CAAC;AAEF,eAAO,MAAM,YAAY,QAAO,KAAK,EAWpC,CAAC"}
+{"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,KAAK;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,OAAO,CAAC;CACrB;AAID;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,IAMrD,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,KAAK,MAAM,KAAG,OAAuC,CAAC;AAEjF,eAAO,MAAM,YAAY,QAAO,KAAK,EAWpC,CAAC"}

package/dist/agents.js

@@ -1,20 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.detectAgents = exports.hasCommand = void 0;
+exports.detectAgents = exports.hasCommand = exports.resolveCommand = void 0;
 const child_process_1 = require("child_process");
 const fs_1 = require("fs");
 const os_1 = require("os");
 const path_1 = require("path");
 const HOME = (0, os_1.homedir)();
-const hasCommand = (cmd) => {
+/**
+ * Absolute path of a command on PATH, or null when it isn't there.
+ * `execFileSync`, not a shell: `process.execve` needs a real path (it does no
+ * PATH lookup of its own), and building `which ${cmd}` as a shell string would
+ * let a path containing a space split into two words.
+ */
+const resolveCommand = (cmd) => {
     try {
-        (0, child_process_1.execSync)(`which ${cmd}`, { stdio: 'pipe' });
-        return true;
+        return (0, child_process_1.execFileSync)('which', [cmd], { encoding: 'utf-8' }).trim() || null;
     }
     catch {
-        return false;
+        return null;
     }
 };
+exports.resolveCommand = resolveCommand;
+const hasCommand = (cmd) => (0, exports.resolveCommand)(cmd) !== null;
 exports.hasCommand = hasCommand;
 const detectAgents = () => [
     { name: 'Claude Code', id: 'claude', detected: (0, exports.hasCommand)('claude') },

package/dist/installer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../src/installer.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AA+BzC;;;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;AAsCF;mEACmE;AACnE,eAAO,MAAM,cAAc,GAAI,UAAU,MAAM,EAAE,KAAK,MAAM,EAAE,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,IAQ9F,CAAC;AAmPF;;;;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"}
+{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../src/installer.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AA+BzC;;;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;AAsCF;mEACmE;AACnE,eAAO,MAAM,cAAc,GAAI,UAAU,MAAM,EAAE,KAAK,MAAM,EAAE,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,IAQ9F,CAAC;AAmPF;;;;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,CA0I1F,CAAC"}

package/dist/installer.js

@@ -10,6 +10,7 @@ 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 tmux_install_js_1 = require("./tmux-install.js");
 const mcp_command_js_1 = require("./mcp-command.js");
 const listener_service_js_1 = require("./listener-service.js");
 const templates_js_1 = require("./templates.js");
@@ -464,7 +465,7 @@ const applyServiceChoice = async (choice) => {
         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)',
+                message: 'Start the listener at every login, so the phone sees this machine after a reboot? (enter to confirm)',
                 default: true,
             });
         }
@@ -551,6 +552,7 @@ const handleInstall = async (args) => {
         if (selected.length === 0) {
             console.log('    (no agents selected — only the config file will be saved)');
         }
+        console.log('    - Check tmux (`zeph cc` runs agents inside it)');
         if ((0, exports.serviceInstallChoice)(args, nonInteractive) !== 'no') {
             console.log('    - Offer to start the listener at every login');
         }
@@ -577,10 +579,28 @@ const handleInstall = async (args) => {
         if (installer)
             installer();
     }
-    // 7. Login-time service — the only thing that makes the phone see this
+    // 7. tmux — `zeph cc` is tmux or nothing, so check before claiming success.
+    console.log('\n  Checking tmux...');
+    await (0, tmux_install_js_1.ensureTmux)({
+        plan: (0, tmux_install_js_1.planTmuxInstall)({ resolve: agents_js_1.resolveCommand, platform: process.platform }),
+        nonInteractive,
+        askConfirm: async (message) => {
+            try {
+                const { confirm } = await import('@inquirer/prompts');
+                return await confirm({ message, default: true });
+            }
+            catch {
+                // Ctrl-C or no TTY — an unanswered question is not a yes.
+                return false;
+            }
+        },
+        run: (argv) => { (0, child_process_1.execFileSync)(argv[0], argv.slice(1), { stdio: 'inherit' }); },
+        report: { ok, fail, note: skipNote },
+    });
+    // 8. 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
+    // 9. Test connection
     console.log('\n  Testing connection...');
     await testConnection(apiKey, baseUrl);
     console.log('\n  Done! Restart your agents.\n');

package/dist/tmux-install.d.ts

@@ -0,0 +1,44 @@
+/**
+ * tmux is not optional for `zeph cc` — every remote-agent subcommand runs the
+ * agent inside a named tmux session so the listener (and the phone picker) can
+ * reach it. Nothing in the install flow used to mention that, so a machine
+ * without tmux looked fully set up until the first `zeph cc` failed with an
+ * error from a program the user was never told they needed.
+ */
+/** What this machine can do about a missing tmux. */
+export type TmuxInstallPlan = {
+    readonly kind: 'present';
+    readonly path: string;
+}
+/** Safe to run unattended — no root, user-writable prefix. */
+ | {
+    readonly kind: 'command';
+    readonly run: readonly string[];
+    readonly label: string;
+}
+/** Needs root, or there is no package manager we recognise. Tell, don't do. */
+ | {
+    readonly kind: 'manual';
+    readonly hint: string;
+};
+export declare const planTmuxInstall: (deps: {
+    resolve: (cmd: string) => string | null;
+    platform: NodeJS.Platform;
+}) => TmuxInstallPlan;
+/**
+ * Act on the plan. Everything the outside world touches is injected, because
+ * the interesting branch — "offer, then run a package manager" — is otherwise
+ * only reachable through an interactive install that no test can drive.
+ */
+export declare const ensureTmux: (deps: {
+    plan: TmuxInstallPlan;
+    nonInteractive: boolean;
+    askConfirm: (message: string) => Promise<boolean>;
+    run: (argv: readonly string[]) => void;
+    report: {
+        ok: (m: string) => void;
+        fail: (m: string) => void;
+        note: (m: string) => void;
+    };
+}) => Promise<void>;
+//# sourceMappingURL=tmux-install.d.ts.map

package/dist/tmux-install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tmux-install.d.ts","sourceRoot":"","sources":["../src/tmux-install.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,qDAAqD;AACrD,MAAM,MAAM,eAAe,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AACrD,8DAA8D;GAC5D;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AACvF,+EAA+E;GAC7E;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAWzD,eAAO,MAAM,eAAe,GAAI,MAAM;IAClC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACxC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC7B,KAAG,eAoBH,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,UAAU,GAAU,MAAM;IACnC,IAAI,EAAE,eAAe,CAAC;IACtB,cAAc,EAAE,OAAO,CAAC;IACxB,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAClD,GAAG,EAAE,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAC;IACvC,MAAM,EAAE;QAAE,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;QAAC,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;QAAC,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;CAC7F,KAAG,OAAO,CAAC,IAAI,CAsBf,CAAC"}

package/dist/tmux-install.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * tmux is not optional for `zeph cc` — every remote-agent subcommand runs the
+ * agent inside a named tmux session so the listener (and the phone picker) can
+ * reach it. Nothing in the install flow used to mention that, so a machine
+ * without tmux looked fully set up until the first `zeph cc` failed with an
+ * error from a program the user was never told they needed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureTmux = exports.planTmuxInstall = void 0;
+/** Package managers that need root, and the line to hand the user for each. */
+const ROOT_PACKAGE_MANAGERS = [
+    { bin: 'apt-get', hint: 'sudo apt install tmux' },
+    { bin: 'dnf', hint: 'sudo dnf install tmux' },
+    { bin: 'pacman', hint: 'sudo pacman -S tmux' },
+    { bin: 'zypper', hint: 'sudo zypper install tmux' },
+    { bin: 'apk', hint: 'sudo apk add tmux' },
+];
+const planTmuxInstall = (deps) => {
+    const path = deps.resolve('tmux');
+    if (path)
+        return { kind: 'present', path };
+    // tmux has no native Windows build. `zeph cc` is POSIX-only by way of tmux,
+    // so point at WSL rather than at a package that cannot be installed.
+    if (deps.platform === 'win32') {
+        return { kind: 'manual', hint: '`zeph cc` needs tmux, which has no Windows build — run it under WSL' };
+    }
+    if (deps.platform === 'darwin') {
+        return deps.resolve('brew')
+            ? { kind: 'command', run: ['brew', 'install', 'tmux'], label: 'brew install tmux' }
+            : { kind: 'manual', hint: 'install Homebrew (brew.sh), then: brew install tmux' };
+    }
+    const rootManager = ROOT_PACKAGE_MANAGERS.find((pm) => deps.resolve(pm.bin));
+    if (rootManager)
+        return { kind: 'manual', hint: rootManager.hint };
+    return { kind: 'manual', hint: 'install tmux with this system\'s package manager' };
+};
+exports.planTmuxInstall = planTmuxInstall;
+/**
+ * Act on the plan. Everything the outside world touches is injected, because
+ * the interesting branch — "offer, then run a package manager" — is otherwise
+ * only reachable through an interactive install that no test can drive.
+ */
+const ensureTmux = async (deps) => {
+    const { plan, report } = deps;
+    if (plan.kind === 'present')
+        return report.ok(`tmux found (${plan.path})`);
+    if (plan.kind === 'manual')
+        return report.fail(`tmux not found — \`zeph cc\` needs it. ${plan.hint}`);
+    if (deps.nonInteractive) {
+        return report.note(`tmux not found — \`zeph cc\` needs it. Run: ${plan.label}`);
+    }
+    const wanted = await deps.askConfirm(`tmux is missing and \`zeph cc\` needs it — run \`${plan.label}\`? (enter to confirm)`);
+    if (!wanted) {
+        return report.note(`tmux not installed — \`zeph cc\` will not work until you run: ${plan.label}`);
+    }
+    try {
+        deps.run(plan.run);
+        report.ok('tmux installed');
+    }
+    catch {
+        report.fail(`\`${plan.label}\` failed — run it by hand`);
+    }
+};
+exports.ensureTmux = ensureTmux;

package/dist/verify.d.ts

@@ -8,10 +8,10 @@
 export declare const registeredMcpArgv: (filePath: string, key: string) => string[] | null;
 /**
  * Can this launch binary actually be run? Registered commands come out of a
- * config file, so they can be an absolute path with spaces in it — the shared
- * `hasCommand` interpolates into `which ${cmd}`, where such a path splits into
- * two words and reports a perfectly good binary as missing (and where any `;`
- * in the file would reach the shell). Nothing here touches a shell.
+ * config file, so unlike everywhere else in the CLI they can be an absolute
+ * path — `which` is the wrong question for one of those, hence the split.
+ * The bare-name half is `resolveCommand`; neither half touches a shell, so a
+ * path with a space in it stays one word and a `;` in the file stays inert.
  */
 export declare const binaryResolves: (bin: string) => boolean;
 /**

package/dist/verify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AA6DA;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,MAAM,EAAE,KAAK,MAAM,KAAG,MAAM,EAAE,GAAG,IAa5E,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,KAAK,MAAM,KAAG,OAQ5C,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GACrB;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GAC7B;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAElE,wFAAwF;AACxF,eAAO,MAAM,uBAAuB,GAChC,MAAM,MAAM,EAAE,GAAG,IAAI,EACrB,UAAU,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,KACnC,eAAe,GAAG,IAMpB,CAAC;AAYF,eAAO,MAAM,YAAY,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CA+GzF,CAAC"}
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AA4DA;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,MAAM,EAAE,KAAK,MAAM,KAAG,MAAM,EAAE,GAAG,IAa5E,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,KAAK,MAAM,KAAG,OAQ5C,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GACrB;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;CAAE,GAC7B;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAElE,wFAAwF;AACxF,eAAO,MAAM,uBAAuB,GAChC,MAAM,MAAM,EAAE,GAAG,IAAI,EACrB,UAAU,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,KACnC,eAAe,GAAG,IAMpB,CAAC;AAYF,eAAO,MAAM,YAAY,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CA+GzF,CAAC"}

package/dist/verify.js

@@ -4,7 +4,6 @@ exports.handleVerify = exports.classifyMcpRegistration = exports.binaryResolves
 const fs_1 = require("fs");
 const os_1 = require("os");
 const path_1 = require("path");
-const child_process_1 = require("child_process");
 const agents_js_1 = require("./agents.js");
 const config_js_1 = require("./config.js");
 const listener_service_js_1 = require("./listener-service.js");
@@ -85,17 +84,16 @@ const registeredMcpArgv = (filePath, key) => {
 exports.registeredMcpArgv = registeredMcpArgv;
 /**
  * Can this launch binary actually be run? Registered commands come out of a
- * config file, so they can be an absolute path with spaces in it — the shared
- * `hasCommand` interpolates into `which ${cmd}`, where such a path splits into
- * two words and reports a perfectly good binary as missing (and where any `;`
- * in the file would reach the shell). Nothing here touches a shell.
+ * config file, so unlike everywhere else in the CLI they can be an absolute
+ * path — `which` is the wrong question for one of those, hence the split.
+ * The bare-name half is `resolveCommand`; neither half touches a shell, so a
+ * path with a space in it stays one word and a `;` in the file stays inert.
  */
 const binaryResolves = (bin) => {
+    if (!bin.includes('/'))
+        return (0, agents_js_1.resolveCommand)(bin) !== null;
     try {
-        if (bin.includes('/'))
-            (0, fs_1.accessSync)(bin, fs_1.constants.X_OK);
-        else
-            (0, child_process_1.execFileSync)('which', [bin], { stdio: 'pipe' });
+        (0, fs_1.accessSync)(bin, fs_1.constants.X_OK);
         return true;
     }
     catch {

package/dist/wrapper.d.ts

@@ -27,6 +27,19 @@ export declare const tmuxSessionName: (project: string) => string;
  * this" from "the user closed the terminal and will come back".
  */
 export declare const findAvailableSession: (base: string) => string;
+interface SpawnTarget {
+    /**
+     * `tmux-new` opens (or reattaches) a session and needs a terminal to
+     * attach to; `direct` runs the agent in the pane we are already in and
+     * does not. Several decisions downstream turn on which one this is, so
+     * `targetForAgent` states it rather than letting them re-derive it from
+     * `cmd === 'tmux'`.
+     */
+    kind: 'direct' | 'tmux-new';
+    cmd: string;
+    args: string[];
+}
+export declare const targetForAgent: (agent: string, extra: string[]) => SpawnTarget;
 /**
  * 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
@@ -58,5 +71,27 @@ export declare const ensureListenerRunning: () => Promise<void>;
  * `zeph cc --resume foo` runs `claude --resume foo` inside the session.
  * Returns when the agent exits.
  */
+/** `process.execve` with the optionality resolved — see handOffExec. */
+export type ProcessHandOff = NonNullable<typeof process.execve>;
+/**
+ * The exec that replaces this process with the child, or null when the wrapper
+ * has to stay and wait instead. Returning the function rather than a boolean
+ * keeps one check where two would otherwise drift: the platform gate and the
+ * policy are the same answer.
+ *
+ * `process.execve` is declared optional by @types/node, and is absent on node
+ * <22.15 (added there) and on Windows (its doc: "not available on Windows or
+ * IBM i"), so its presence covers both without a version check. `engines.node`
+ * is `>=18`, so the spawn path below is not a transitional fallback — it stays.
+ *
+ * `isTTY` is `undefined` rather than `false` on a pipe, hence every `=== true`.
+ */
+export declare const handOffExec: (deps: {
+    execve: ProcessHandOff | undefined;
+    kind: SpawnTarget["kind"];
+    stdinTTY: boolean | undefined;
+    stdoutTTY: boolean | undefined;
+}) => ProcessHandOff | null;
 export declare const handleAgentSession: (agent: RemoteAgent, extra?: string[]) => Promise<number>;
+export {};
 //# sourceMappingURL=wrapper.d.ts.map

package/dist/wrapper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wrapper.d.ts","sourceRoot":"","sources":["../src/wrapper.ts"],"names":[],"mappings":"AAuBA,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;AAkC9E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,KAAG,MAOnD,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,CAgC1D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAU,OAAO,WAAW,EAAE,QAAO,MAAM,EAAO,KAAG,OAAO,CAAC,MAAM,CAmCjG,CAAC"}
+{"version":3,"file":"wrapper.d.ts","sourceRoot":"","sources":["../src/wrapper.ts"],"names":[],"mappings":"AAwBA,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;AAkC9E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM,MAAM,KAAG,MAOnD,CAAC;AAEF,UAAU,WAAW;IACjB;;;;;;OAMG;IACH,IAAI,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,EAAE,CAAC;CAClB;AAOD,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,EAAE,OAAO,MAAM,EAAE,KAAG,WAmB/D,CAAC;AAIF;;;;;;;;;;;;;;;;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,CAgC1D,CAAC;AAEF;;;;;GAKG;AACH,wEAAwE;AACxE,MAAM,MAAM,cAAc,GAAG,WAAW,CAAC,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC;AAEhE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM;IAC9B,MAAM,EAAE,cAAc,GAAG,SAAS,CAAC;IACnC,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1B,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IAC9B,SAAS,EAAE,OAAO,GAAG,SAAS,CAAC;CAClC,KAAG,cAAc,GAAG,IASpB,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAU,OAAO,WAAW,EAAE,QAAO,MAAM,EAAO,KAAG,OAAO,CAAC,MAAM,CA+DjG,CAAC"}

package/dist/wrapper.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handleAgentSession = exports.ensureListenerRunning = exports.listenerVersionDrifted = exports.findAvailableSession = exports.tmuxSessionName = exports.detectProjectName = void 0;
+exports.handleAgentSession = exports.handOffExec = exports.ensureListenerRunning = exports.listenerVersionDrifted = exports.targetForAgent = 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
@@ -14,6 +14,7 @@ exports.handleAgentSession = exports.ensureListenerRunning = exports.listenerVer
  */
 const child_process_1 = require("child_process");
 const path_1 = require("path");
+const agents_js_1 = require("./agents.js");
 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");
@@ -114,7 +115,7 @@ const targetForAgent = (agent, extra) => {
     // current pane. Nested tmux prefix collisions are confusing and the
     // listener can't reach a session it didn't name anyway.
     if (process.env.TMUX) {
-        return { cmd: agent, args: extra };
+        return { kind: 'direct', cmd: agent, args: extra };
     }
     const base = (0, exports.tmuxSessionName)((0, exports.detectProjectName)());
     // Reattach a detached session of this project when there is one,
@@ -127,8 +128,9 @@ const targetForAgent = (agent, extra) => {
     // `--resume` would be eaten by tmux's own parser. Build one quoted
     // shell string instead, which tmux passes through verbatim.
     const shellCmd = [agent, ...extra].map(shellQuote).join(' ');
-    return { cmd: 'tmux', args: ['new', '-A', '-s', session, shellCmd] };
+    return { kind: 'tmux-new', cmd: 'tmux', args: ['new', '-A', '-s', session, shellCmd] };
 };
+exports.targetForAgent = targetForAgent;
 // ── Background listener auto-start ────────────────────────────────────
 /**
  * Whether the daemon on record is running a different build than the one
@@ -193,27 +195,74 @@ const ensureListenerRunning = async () => {
 };
 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.
+ * The exec that replaces this process with the child, or null when the wrapper
+ * has to stay and wait instead. Returning the function rather than a boolean
+ * keeps one check where two would otherwise drift: the platform gate and the
+ * policy are the same answer.
+ *
+ * `process.execve` is declared optional by @types/node, and is absent on node
+ * <22.15 (added there) and on Windows (its doc: "not available on Windows or
+ * IBM i"), so its presence covers both without a version check. `engines.node`
+ * is `>=18`, so the spawn path below is not a transitional fallback — it stays.
+ *
+ * `isTTY` is `undefined` rather than `false` on a pipe, hence every `=== true`.
  */
+const handOffExec = (deps) => {
+    if (!deps.execve)
+        return null;
+    // execve runs no cleanup handler, and node only writes stdout synchronously
+    // to a TTY on POSIX — anything buffered to a pipe would vanish with us.
+    if (deps.stdoutTTY !== true)
+        return null;
+    // `tmux new` additionally needs a terminal of its own to attach to. That is
+    // the failure the spawn path below exists to explain, so send it there.
+    if (deps.kind === 'tmux-new' && deps.stdinTTY !== true)
+        return null;
+    return deps.execve;
+};
+exports.handOffExec = handOffExec;
 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)();
+    const { kind, cmd, args } = (0, exports.targetForAgent)(agent.binary, extra);
+    // Hand the terminal over and stop existing. Waiting on the child is all
+    // this process does for the rest of the session, and it holds a whole node
+    // heap to do it — one resident process per `zeph cc`, purely to forward an
+    // exit code that execve gives us for free by being the same process.
+    const handOff = (0, exports.handOffExec)({
+        execve: process.execve,
+        kind,
+        stdinTTY: process.stdin.isTTY,
+        stdoutTTY: process.stdout.isTTY,
+    });
+    if (handOff) {
+        const file = (0, agents_js_1.resolveCommand)(cmd);
+        // execve does no PATH lookup, so resolving is mandatory — and the
+        // resolve failing is the same fact the spawn path learns from ENOENT.
+        if (!file) {
+            console.error(`zeph: '${cmd}' not found on PATH`);
+            return 127;
+        }
+        // Nothing buffered survives: execve runs no cleanup handler and fires
+        // no exit event. Safe here only because stdout is a TTY, which node
+        // writes synchronously on POSIX — every `zeph:` line above is already out.
+        // The env argument is left off: it defaults to process.env.
+        handOff(file, [cmd, ...args]);
+    }
     return new Promise((resolve) => {
-        const { cmd, args } = targetForAgent(agent.binary, extra);
         const start = Date.now();
         const child = (0, child_process_1.spawn)(cmd, args, { stdio: 'inherit' });
         child.on('exit', (code) => {
             const dur = Date.now() - start;
             // Short-lived non-zero exits are the symptom of "ran from a
-            // pane that isn't a real TTY" (iTerm tmux integration pane,
-            // some IDE terminals). The user otherwise just sees their
-            // shell return with `[exited]` and no clue what went wrong.
-            if (code && code !== 0 && dur < 2000) {
+            // pane that isn't a real TTY" (some IDE terminals). The user
+            // otherwise just sees their shell return with `[exited]` and no
+            // clue what went wrong. Only `tmux new` fails that way — telling
+            // someone whose agent died inside a perfectly good pane to "run
+            // from a plain shell pane" would send them after the wrong thing.
+            if (kind === 'tmux-new' && code && code !== 0 && dur < 2000) {
                 console.error(`zeph: ${cmd} ${args.join(' ')} exited ${code} after ${dur}ms.\n` +
                     `  If this terminal is itself inside tmux (or an iTerm/Warp\n` +
                     `  tmux-integration pane), run \`zeph cc\` from a plain shell\n` +

package/package.json

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