@zeph-to/cli 2.12.0 → 2.12.1

package/README.md

@@ -527,7 +527,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/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.12.1",
   "description": "Zeph CLI + push notification SDK for AI agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",