@zeph-to/cli 2.11.0 → 2.12.1

package/README.md

@@ -179,10 +179,15 @@ way. `zeph install` does not wire Hermes either — add the MCP server to
 ```yaml
 mcp_servers:
   zeph:
-    command: "npx"
-    args: ["-y", "@zeph-to/mcp-server"]
+    command: "zeph"
+    args: ["mcp"]
 ```
 
+`zeph mcp` runs the MCP server inside the CLI process. The older
+`command: "npx"` / `args: ["-y", "@zeph-to/mcp-server"]` form still works,
+but leaves an `npm exec` launcher resident beside the server for as long as
+the session lives — `zeph verify` flags a config still on it.
+
 Add the entry; do not replace the file. `mcp_servers` is shared with
 every other server you have configured, and nothing under `~/.hermes` is
 in version control. Then `/reload-mcp` inside Hermes.
@@ -522,7 +527,8 @@ 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 |
 
 ### Notify Options

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/check-update.d.ts

@@ -1,4 +1,11 @@
 /** Semver-ish compare: returns true when `latest` is strictly newer than `current`. */
 export declare const isNewer: (latest: string, current: string) => boolean;
+/**
+ * The mcp-server version this CLI will actually run. It ships as a dependency
+ * (see mcp.ts), so it is pinned at install time — no longer "whatever npx
+ * fetched last". Returns null on a broken install rather than throwing; the
+ * report degrades to "latest is vX" the way it always did for this package.
+ */
+export declare const installedMcpServerVersion: () => string | null;
 export declare const handleCheckUpdate: (args: Record<string, string | boolean>) => Promise<number>;
 //# sourceMappingURL=check-update.d.ts.map

package/dist/check-update.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check-update.d.ts","sourceRoot":"","sources":["../src/check-update.ts"],"names":[],"mappings":"AAsBA,uFAAuF;AACvF,eAAO,MAAM,OAAO,GAAI,QAAQ,MAAM,EAAE,SAAS,MAAM,KAAG,OAQzD,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CA4C9F,CAAC"}
+{"version":3,"file":"check-update.d.ts","sourceRoot":"","sources":["../src/check-update.ts"],"names":[],"mappings":"AAuBA,uFAAuF;AACvF,eAAO,MAAM,OAAO,GAAI,QAAQ,MAAM,EAAE,SAAS,MAAM,KAAG,OAQzD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,QAAO,MAAM,GAAG,IASrD,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CA4C9F,CAAC"}

package/dist/check-update.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handleCheckUpdate = exports.isNewer = void 0;
+exports.handleCheckUpdate = exports.installedMcpServerVersion = exports.isNewer = void 0;
+const fs_1 = require("fs");
 const config_js_1 = require("./config.js");
 // Compares installed versions against the npm registry. Pure read-only —
 // never installs anything; just tells the user if a newer release exists.
@@ -34,19 +35,35 @@ const isNewer = (latest, current) => {
     return false;
 };
 exports.isNewer = isNewer;
+/**
+ * The mcp-server version this CLI will actually run. It ships as a dependency
+ * (see mcp.ts), so it is pinned at install time — no longer "whatever npx
+ * fetched last". Returns null on a broken install rather than throwing; the
+ * report degrades to "latest is vX" the way it always did for this package.
+ */
+const installedMcpServerVersion = () => {
+    try {
+        const pkg = JSON.parse((0, fs_1.readFileSync)(require.resolve('@zeph-to/mcp-server/package.json'), 'utf-8'));
+        return pkg.version ?? null;
+    }
+    catch {
+        return null;
+    }
+};
+exports.installedMcpServerVersion = installedMcpServerVersion;
 const handleCheckUpdate = async (args) => {
     const isJson = args.json === true;
-    // The CLI's own installed version is known from package.json.
-    // mcp-server's installed version isn't reliably knowable from here
-    // (it's a separate package, often run via npx), so we only report its
-    // latest — the user compares against whatever they have.
-    const results = [];
-    for (const pkg of PACKAGES) {
-        const latest = await fetchLatest(pkg);
-        const current = pkg === '@zeph-to/cli' ? config_js_1.VERSION : null;
-        const outdated = !!(latest && current && (0, exports.isNewer)(latest, current));
-        results.push({ pkg, current, latest, outdated });
-    }
+    // Both installed versions are knowable: the CLI's from its own
+    // package.json, and mcp-server's because `zeph mcp` runs it in-process,
+    // which makes it a dependency rather than an npx download of unknown age.
+    // Two unrelated registry round-trips — awaiting them one after the other
+    // doubled the command's wall time for nothing.
+    const latestVersions = await Promise.all(PACKAGES.map(fetchLatest));
+    const results = PACKAGES.map((pkg, i) => {
+        const latest = latestVersions[i];
+        const current = pkg === '@zeph-to/cli' ? config_js_1.VERSION : (0, exports.installedMcpServerVersion)();
+        return { pkg, current, latest, outdated: !!(latest && current && (0, exports.isNewer)(latest, current)) };
+    });
     if (isJson) {
         console.log(JSON.stringify({ results }, null, 2));
         return 0;

package/dist/cli.js

@@ -11,6 +11,7 @@ const verify_js_1 = require("./verify.js");
 const check_update_js_1 = require("./check-update.js");
 const ask_js_1 = require("./ask.js");
 const wrapper_js_1 = require("./wrapper.js");
+const mcp_js_1 = require("./mcp.js");
 const listener_js_1 = require("./listener.js");
 const config_js_1 = require("./config.js");
 const gate_js_1 = require("./gate.js");
@@ -84,6 +85,9 @@ ${usageAgentLines()}
                    -2/-3/… only when every existing one has a client
                    attached. Any args after the subcommand are forwarded
                    verbatim, e.g. 'zeph cc --resume')
+  mcp             Run the MCP server on stdio. This is what agent MCP
+                  configs launch — 'zeph install' registers it, you
+                  never type it
   listener        Resident daemon — receives 'agent.command' pushes from
                   the phone picker and injects them into the matching
                   tmux session.
@@ -491,6 +495,8 @@ const main = async () => {
             return handleRename(args);
         case 'test':
             return handleTest(args);
+        case 'mcp':
+            return (0, mcp_js_1.handleMcp)();
         case 'listener':
             return (0, listener_js_1.handleListener)(args);
         case 'remote-hook':

package/dist/installer.d.ts

@@ -12,18 +12,6 @@ export declare const shouldReauth: (currentKey: string | undefined, relogin: boo
 /** Exported for tests (installGemini shells out to the real `gemini` binary,
  *  so the merge semantics can't be covered through it deterministically). */
 export declare const mergeJsonFile: (filePath: string, patch: Record<string, unknown>) => void;
-/**
- * opencode.json's own MCP schema — top-level `mcp` key (not `mcpServers`),
- * `command` as ARRAY (binary + args), `type: "local"`. No `environment` —
- * opencode is a terminal app that inherits shell env, and the MCP server
- * falls back to ~/.zeph/config.json anyway (an unexpanded "${ZEPH_API_KEY}"
- * literal would shadow that fallback with junk). Exported for tests (shape pin).
- */
-export declare const OPENCODE_MCP_ENTRY: {
-    type: string;
-    command: string[];
-    enabled: boolean;
-};
 /** Add the zeph entry under `key` in an MCP registry JSON file, preserving
  *  everything else in it. Exported for tests (merge semantics). */
 export declare const injectMcpEntry: (filePath: string, key: string, entry: Record<string, unknown>) => void;

package/dist/installer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../src/installer.ts"],"names":[],"mappings":"AAWA,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;AAgDF;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB;;;;CAI9B,CAAC;AAEF;mEACmE;AACnE,eAAO,MAAM,cAAc,GAAI,UAAU,MAAM,EAAE,KAAK,MAAM,EAAE,OAAO,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAG,IAQ9F,CAAC;AAqPF;;;;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":"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"}

package/dist/installer.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handleInstall = exports.serviceInstallChoice = exports.filterAgentsByIds = exports.injectMcpEntry = exports.OPENCODE_MCP_ENTRY = exports.mergeJsonFile = exports.shouldReauth = void 0;
+exports.handleInstall = exports.serviceInstallChoice = exports.filterAgentsByIds = exports.injectMcpEntry = exports.mergeJsonFile = exports.shouldReauth = void 0;
 const child_process_1 = require("child_process");
 const fs_1 = require("fs");
 const os_1 = require("os");
@@ -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 mcp_command_js_1 = require("./mcp-command.js");
 const listener_service_js_1 = require("./listener-service.js");
 const templates_js_1 = require("./templates.js");
 const HOME = (0, os_1.homedir)();
@@ -104,27 +105,6 @@ const addAiderReadDirective = (confPath, conventionsPath) => {
     (0, fs_1.writeFileSync)(confPath, (base ? `${base}\n\n` : '') + line);
 };
 // ── Per-Agent Installers ─────────────────────────────────────────
-// Pass through env explicitly so the MCP server doesn't have to rely on
-// process-env inheritance (which behaves differently per IDE — Cursor and
-// Windsurf spawn the MCP from a graphical context that may not inherit
-// shell env). Mirrors plugin/.mcp.json.
-const MCP_SERVERS_ENTRY = {
-    command: 'npx',
-    args: ['-y', '@zeph-to/mcp-server'],
-    env: { ZEPH_API_KEY: '${ZEPH_API_KEY}' },
-};
-/**
- * opencode.json's own MCP schema — top-level `mcp` key (not `mcpServers`),
- * `command` as ARRAY (binary + args), `type: "local"`. No `environment` —
- * opencode is a terminal app that inherits shell env, and the MCP server
- * falls back to ~/.zeph/config.json anyway (an unexpanded "${ZEPH_API_KEY}"
- * literal would shadow that fallback with junk). Exported for tests (shape pin).
- */
-exports.OPENCODE_MCP_ENTRY = {
-    type: 'local',
-    command: ['npx', '-y', '@zeph-to/mcp-server'],
-    enabled: true,
-};
 /** Add the zeph entry under `key` in an MCP registry JSON file, preserving
  *  everything else in it. Exported for tests (merge semantics). */
 const injectMcpEntry = (filePath, key, entry) => {
@@ -153,7 +133,7 @@ const installClaude = () => {
 };
 const installCursor = () => {
     try {
-        (0, exports.injectMcpEntry)((0, path_1.join)(HOME, '.cursor', 'mcp.json'), 'mcpServers', MCP_SERVERS_ENTRY);
+        (0, exports.injectMcpEntry)((0, path_1.join)(HOME, '.cursor', 'mcp.json'), 'mcpServers', mcp_command_js_1.MCP_SERVERS_ENTRY);
         ok('MCP server added');
     }
     catch {
@@ -176,7 +156,7 @@ const installCursor = () => {
 };
 const installWindsurf = () => {
     try {
-        (0, exports.injectMcpEntry)((0, path_1.join)(HOME, '.codeium', 'windsurf', 'mcp_config.json'), 'mcpServers', MCP_SERVERS_ENTRY);
+        (0, exports.injectMcpEntry)((0, path_1.join)(HOME, '.codeium', 'windsurf', 'mcp_config.json'), 'mcpServers', mcp_command_js_1.MCP_SERVERS_ENTRY);
         ok('MCP server added');
     }
     catch {
@@ -201,20 +181,18 @@ const installWindsurf = () => {
 };
 const installGemini = () => {
     try {
-        // gemini ≥0.26 syntax: `mcp add [-s scope] <name> <command> [args…]` —
-        // the default scope is "project" (cwd-local .gemini/), so pin user
-        // scope for a machine-wide install. Older gemini CLIs only accept the
-        // legacy `mcp add zeph -- npx …` form; fall back for those.
-        (0, child_process_1.execSync)('gemini mcp add -s user zeph npx -- -y @zeph-to/mcp-server', { stdio: 'pipe' });
+        // Both forms are built in mcp-command.ts; older gemini CLIs only accept
+        // the legacy one, so try the modern form first and fall back.
+        (0, child_process_1.execSync)(mcp_command_js_1.GEMINI_MCP_ADD, { stdio: 'pipe' });
         ok('MCP server added');
     }
     catch {
         try {
-            (0, child_process_1.execSync)('gemini mcp add zeph -- npx -y @zeph-to/mcp-server', { stdio: 'pipe' });
+            (0, child_process_1.execSync)(mcp_command_js_1.GEMINI_MCP_ADD_LEGACY, { stdio: 'pipe' });
             ok('MCP server added (legacy gemini CLI)');
         }
         catch {
-            fail('MCP add failed. Manual: gemini mcp add -s user zeph npx -- -y @zeph-to/mcp-server');
+            fail(`MCP add failed. Manual: ${mcp_command_js_1.GEMINI_MCP_ADD}`);
         }
     }
     try {
@@ -320,7 +298,7 @@ const installPi = () => {
 };
 const installOpencode = () => {
     try {
-        (0, exports.injectMcpEntry)((0, path_1.join)(HOME, '.config', 'opencode', 'opencode.json'), 'mcp', exports.OPENCODE_MCP_ENTRY);
+        (0, exports.injectMcpEntry)((0, path_1.join)(HOME, '.config', 'opencode', 'opencode.json'), 'mcp', mcp_command_js_1.OPENCODE_MCP_ENTRY);
         ok('MCP server added');
     }
     catch {

package/dist/mcp-command.d.ts

@@ -0,0 +1,45 @@
+/**
+ * How every agent launches the Zeph MCP server — one source, three schemas.
+ *
+ * Registrations used to say `npx -y @zeph-to/mcp-server`, which left an
+ * `npm exec` launcher resident beside the server for the life of the session.
+ * `zeph mcp` (see mcp.ts) runs the server in the CLI's own process instead.
+ *
+ * Cursor/Windsurf, Gemini and OpenCode each want that launch in a different
+ * shape, and the shapes drifted apart when each site spelled the command out
+ * itself. Everything below is derived from MCP_LAUNCH_ARGV.
+ */
+/** What the agents run. `zeph` resolves out of the same global bin dir as `npx`. */
+export declare const MCP_LAUNCH_ARGV: readonly ["zeph", "mcp"];
+/**
+ * `mcpServers.zeph` — what the installer writes for Cursor and Windsurf.
+ * The env block is deliberate: both spawn the MCP server from a graphical
+ * context that may not inherit shell env, so the key is passed through
+ * explicitly rather than left to inheritance.
+ *
+ * `zeph-to/plugin`'s `.mcp.json` holds the same shape but is a HAND-KEPT COPY —
+ * it lives in another repo and cannot import this. Change one, change both.
+ */
+export declare const MCP_SERVERS_ENTRY: {
+    command: "zeph";
+    args: "mcp"[];
+    env: {
+        ZEPH_API_KEY: string;
+    };
+};
+/**
+ * opencode.json's own MCP schema — top-level `mcp` key (not `mcpServers`),
+ * `command` as ARRAY (binary + args), `type: "local"`. No `environment` —
+ * opencode is a terminal app that inherits shell env, and the MCP server
+ * falls back to ~/.zeph/config.json anyway (an unexpanded "${ZEPH_API_KEY}"
+ * literal would shadow that fallback with junk).
+ */
+export declare const OPENCODE_MCP_ENTRY: {
+    type: string;
+    command: ("zeph" | "mcp")[];
+    enabled: boolean;
+};
+export declare const GEMINI_MCP_ADD: string;
+/** Older gemini CLIs only accept `mcp add <name> -- <command…>`, with no scope flag. */
+export declare const GEMINI_MCP_ADD_LEGACY: string;
+//# sourceMappingURL=mcp-command.d.ts.map

package/dist/mcp-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-command.d.ts","sourceRoot":"","sources":["../src/mcp-command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,oFAAoF;AACpF,eAAO,MAAM,eAAe,0BAA2B,CAAC;AAIxD;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB;;;;;;CAI7B,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB;;;;CAI9B,CAAC;AAMF,eAAO,MAAM,cAAc,QAA0E,CAAC;AAEtG,wFAAwF;AACxF,eAAO,MAAM,qBAAqB,QAAwD,CAAC"}

package/dist/mcp-command.js

@@ -0,0 +1,50 @@
+"use strict";
+/**
+ * How every agent launches the Zeph MCP server — one source, three schemas.
+ *
+ * Registrations used to say `npx -y @zeph-to/mcp-server`, which left an
+ * `npm exec` launcher resident beside the server for the life of the session.
+ * `zeph mcp` (see mcp.ts) runs the server in the CLI's own process instead.
+ *
+ * Cursor/Windsurf, Gemini and OpenCode each want that launch in a different
+ * shape, and the shapes drifted apart when each site spelled the command out
+ * itself. Everything below is derived from MCP_LAUNCH_ARGV.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GEMINI_MCP_ADD_LEGACY = exports.GEMINI_MCP_ADD = exports.OPENCODE_MCP_ENTRY = exports.MCP_SERVERS_ENTRY = exports.MCP_LAUNCH_ARGV = void 0;
+/** What the agents run. `zeph` resolves out of the same global bin dir as `npx`. */
+exports.MCP_LAUNCH_ARGV = ['zeph', 'mcp'];
+const [MCP_BIN, ...MCP_SUBCOMMAND] = exports.MCP_LAUNCH_ARGV;
+/**
+ * `mcpServers.zeph` — what the installer writes for Cursor and Windsurf.
+ * The env block is deliberate: both spawn the MCP server from a graphical
+ * context that may not inherit shell env, so the key is passed through
+ * explicitly rather than left to inheritance.
+ *
+ * `zeph-to/plugin`'s `.mcp.json` holds the same shape but is a HAND-KEPT COPY —
+ * it lives in another repo and cannot import this. Change one, change both.
+ */
+exports.MCP_SERVERS_ENTRY = {
+    command: MCP_BIN,
+    args: [...MCP_SUBCOMMAND],
+    env: { ZEPH_API_KEY: '${ZEPH_API_KEY}' },
+};
+/**
+ * opencode.json's own MCP schema — top-level `mcp` key (not `mcpServers`),
+ * `command` as ARRAY (binary + args), `type: "local"`. No `environment` —
+ * opencode is a terminal app that inherits shell env, and the MCP server
+ * falls back to ~/.zeph/config.json anyway (an unexpanded "${ZEPH_API_KEY}"
+ * literal would shadow that fallback with junk).
+ */
+exports.OPENCODE_MCP_ENTRY = {
+    type: 'local',
+    command: [...exports.MCP_LAUNCH_ARGV],
+    enabled: true,
+};
+// gemini ≥0.26 syntax: `mcp add [-s scope] <name> <command> [args…]`. The
+// server NAME and the BINARY are both "zeph" here, so the doubled word below
+// is correct, not a copy-paste slip. Default scope is "project" (cwd-local
+// .gemini/), so user scope is pinned for a machine-wide install.
+exports.GEMINI_MCP_ADD = `gemini mcp add -s user zeph ${MCP_BIN} -- ${MCP_SUBCOMMAND.join(' ')}`;
+/** Older gemini CLIs only accept `mcp add <name> -- <command…>`, with no scope flag. */
+exports.GEMINI_MCP_ADD_LEGACY = `gemini mcp add zeph -- ${exports.MCP_LAUNCH_ARGV.join(' ')}`;

package/dist/mcp.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `zeph mcp` — run the Zeph MCP server inside THIS process.
+ *
+ * Every registration used to say `npx -y @zeph-to/mcp-server`, which left an
+ * `npm exec` launcher resident for the whole session on top of the server it
+ * spawned — two node processes where one does the work. `@zeph-to/mcp-server`
+ * is a dependency of this package now, so agents register `zeph mcp` and get
+ * exactly one process.
+ */
+/**
+ * Importing `@zeph-to/mcp-server` IS starting it: the package is a bin entry
+ * whose module body wires an McpServer to a StdioServerTransport and exports
+ * nothing. Verified against 2.3.0 (`dist/index.js` ends in `main().catch(…)`).
+ * Injectable so tests don't need the real package resolvable.
+ */
+type McpServerLoader = () => Promise<unknown>;
+export declare const handleMcp: (load?: McpServerLoader) => Promise<number>;
+export {};
+//# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,KAAK,eAAe,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;AAI9C,eAAO,MAAM,SAAS,GAAU,OAAM,eAAiC,KAAG,OAAO,CAAC,MAAM,CAcvF,CAAC"}

package/dist/mcp.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * `zeph mcp` — run the Zeph MCP server inside THIS process.
+ *
+ * Every registration used to say `npx -y @zeph-to/mcp-server`, which left an
+ * `npm exec` launcher resident for the whole session on top of the server it
+ * spawned — two node processes where one does the work. `@zeph-to/mcp-server`
+ * is a dependency of this package now, so agents register `zeph mcp` and get
+ * exactly one process.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleMcp = void 0;
+const importMcpServer = () => import('@zeph-to/mcp-server');
+const handleMcp = async (load = importMcpServer) => {
+    try {
+        await load();
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        console.error(`zeph: could not start the MCP server (@zeph-to/mcp-server): ${reason}`);
+        console.error('zeph: reinstall the CLI with `npm i -g @zeph-to/cli`.');
+        return 1;
+    }
+    // The server owns this process from here: it holds stdio open and decides
+    // when to exit. Resolving would hand cli.ts a code for `process.exit()`,
+    // killing the server the line above just started.
+    return new Promise(() => { });
+};
+exports.handleMcp = handleMcp;

package/dist/verify.d.ts

@@ -1,2 +1,36 @@
+/**
+ * The launch argv a registry file records for zeph, verbatim — null when the
+ * file is absent, unparseable, or has no zeph entry. Two schemas in the wild:
+ * `command` + `args` (Cursor/Windsurf/Gemini) and `command` as a whole array
+ * (opencode). Returned as-is on purpose: a stale entry is only detectable if
+ * the reader does not normalize it into the shape it expects.
+ */
+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 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;
+/**
+ * What a recorded registration is worth right now. `unresolvable` outranks
+ * `stale`: a stale entry still starts a server (through the npm launcher this
+ * release exists to delete), an unresolvable one starts nothing at all and
+ * takes the agent's whole zeph toolset down with it, silently — the config is
+ * read once at install time and never checked again.
+ */
+export type McpRegistration = {
+    readonly state: 'current';
+} | {
+    readonly state: 'stale';
+    readonly argv: string[];
+} | {
+    readonly state: 'unresolvable';
+    readonly argv: string[];
+};
+/** null = this agent has no zeph registration at all, so there is nothing to report. */
+export declare const classifyMcpRegistration: (argv: string[] | null, isOnPath: (bin: string) => boolean) => McpRegistration | null;
 export declare const handleVerify: (args: Record<string, string | boolean>) => Promise<number>;
 //# sourceMappingURL=verify.d.ts.map

package/dist/verify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../src/verify.ts"],"names":[],"mappings":"AA4CA,eAAO,MAAM,YAAY,GAAU,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,KAAG,OAAO,CAAC,MAAM,CAiFzF,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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handleVerify = void 0;
+exports.handleVerify = exports.classifyMcpRegistration = exports.binaryResolves = exports.registeredMcpArgv = void 0;
 const fs_1 = require("fs");
 const os_1 = require("os");
 const path_1 = require("path");
@@ -8,6 +8,7 @@ const agents_js_1 = require("./agents.js");
 const config_js_1 = require("./config.js");
 const listener_service_js_1 = require("./listener-service.js");
 const zeph_hook_js_1 = require("./zeph-hook.js");
+const mcp_command_js_1 = require("./mcp-command.js");
 const HOME = (0, os_1.homedir)();
 const pass = (msg) => console.log(`    ✓ ${msg}`);
 const warn = (msg) => console.log(`    ! ${msg}`);
@@ -41,6 +42,82 @@ const AGENT_RULE_PRESENT = {
     pi: () => hasManagedBlock((0, path_1.join)(HOME, '.pi', 'agent', 'AGENTS.md')),
     opencode: () => hasManagedBlock((0, path_1.join)(HOME, '.config', 'opencode', 'AGENTS.md')),
 };
+/**
+ * Where each agent records the MCP launch, and under which container key.
+ * `agent` matches the label `detectAgents` uses so one report never names the
+ * same agent two ways. Cursor/Windsurf/OpenCode are files the installer writes
+ * itself; the Gemini row is READ-ONLY — `zeph install` shells out to
+ * `gemini mcp add`, so this path is the gemini CLI's own storage layout,
+ * confirmed by reading the file it produced, not something Zeph chose.
+ */
+const MCP_REGISTRIES = [
+    { agent: 'Cursor', path: (0, path_1.join)(HOME, '.cursor', 'mcp.json'), key: 'mcpServers' },
+    { agent: 'Windsurf', path: (0, path_1.join)(HOME, '.codeium', 'windsurf', 'mcp_config.json'), key: 'mcpServers' },
+    { agent: 'Gemini CLI', path: (0, path_1.join)(HOME, '.gemini', 'settings.json'), key: 'mcpServers' },
+    { agent: 'OpenCode', path: (0, path_1.join)(HOME, '.config', 'opencode', 'opencode.json'), key: 'mcp' },
+];
+/**
+ * The launch argv a registry file records for zeph, verbatim — null when the
+ * file is absent, unparseable, or has no zeph entry. Two schemas in the wild:
+ * `command` + `args` (Cursor/Windsurf/Gemini) and `command` as a whole array
+ * (opencode). Returned as-is on purpose: a stale entry is only detectable if
+ * the reader does not normalize it into the shape it expects.
+ */
+const registeredMcpArgv = (filePath, key) => {
+    let data;
+    try {
+        data = JSON.parse((0, fs_1.readFileSync)(filePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+    const container = data[key];
+    const entry = container?.zeph;
+    if (!entry)
+        return null;
+    if (Array.isArray(entry.command))
+        return entry.command.map(String);
+    if (typeof entry.command !== 'string')
+        return null;
+    return [entry.command, ...(Array.isArray(entry.args) ? entry.args.map(String) : [])];
+};
+exports.registeredMcpArgv = registeredMcpArgv;
+/**
+ * Can this launch binary actually be run? Registered commands come out of a
+ * 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 {
+        (0, fs_1.accessSync)(bin, fs_1.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+exports.binaryResolves = binaryResolves;
+/** null = this agent has no zeph registration at all, so there is nothing to report. */
+const classifyMcpRegistration = (argv, isOnPath) => {
+    if (!argv || argv.length === 0)
+        return null;
+    if (!isOnPath(argv[0]))
+        return { state: 'unresolvable', argv };
+    const isCanonical = argv.length === mcp_command_js_1.MCP_LAUNCH_ARGV.length
+        && argv.every((token, i) => token === mcp_command_js_1.MCP_LAUNCH_ARGV[i]);
+    return isCanonical ? { state: 'current' } : { state: 'stale', argv };
+};
+exports.classifyMcpRegistration = classifyMcpRegistration;
+/** The registries that actually hold a zeph entry, classified. Agents that were
+ *  never installed drop out here so the report has no row for them. */
+const activeMcpRegistrations = (isOnPath) => MCP_REGISTRIES.flatMap((registry) => {
+    const result = (0, exports.classifyMcpRegistration)((0, exports.registeredMcpArgv)(registry.path, registry.key), isOnPath);
+    return result ? [{ agent: registry.agent, result }] : [];
+});
 const handleVerify = async (args) => {
     const doPing = args.ping === true;
     const checks = [];
@@ -64,12 +141,28 @@ const handleVerify = async (args) => {
         ? 'ZEPH_HOOK_ID is set (two-way zeph_ask/prompt/input enabled)'
         : 'ZEPH_HOOK_ID not set (notify-only — set it for remote control)', hookId ? 'pass' : 'warn');
     // ── Runtime ──────────────────────────────────────────────────
+    // One resolution per binary: `zeph` alone was being looked up five times
+    // (twice here, once per registry below), and each lookup is a spawn.
+    const resolved = new Map();
+    const resolves = (bin) => {
+        const cached = resolved.get(bin);
+        if (cached !== undefined)
+            return cached;
+        const found = (0, exports.binaryResolves)(bin);
+        resolved.set(bin, found);
+        return found;
+    };
     console.log('\n  Runtime:');
-    record((0, agents_js_1.hasCommand)('node') ? 'node available' : 'node not found', (0, agents_js_1.hasCommand)('node') ? 'pass' : 'fail');
-    record((0, agents_js_1.hasCommand)('npx') ? 'npx available (MCP server runs via npx)' : 'npx not found', (0, agents_js_1.hasCommand)('npx') ? 'pass' : 'fail');
-    record((0, agents_js_1.hasCommand)('zeph')
-        ? 'zeph CLI on PATH'
-        : 'zeph CLI not on PATH (hooks fall back to npx — slower first call)', (0, agents_js_1.hasCommand)('zeph') ? 'pass' : 'warn');
+    const hasNode = resolves('node');
+    const hasNpx = resolves('npx');
+    const hasZeph = resolves('zeph');
+    record(hasNode ? 'node available' : 'node not found', hasNode ? 'pass' : 'fail');
+    record(hasNpx ? 'npx available (hook fallback when zeph is off PATH)' : 'npx not found', hasNpx ? 'pass' : 'warn');
+    // Not a warning any more: `zeph mcp` IS the MCP server, so a zeph that
+    // isn't on PATH means no MCP tools at all, not just a slower first call.
+    record(hasZeph
+        ? 'zeph CLI on PATH (runs the MCP server and the hooks)'
+        : 'zeph CLI not on PATH — MCP tools will not start. Reinstall: npm i -g @zeph-to/cli', hasZeph ? 'pass' : 'fail');
     // ── Login-time service ───────────────────────────────────────
     // Optional, so a missing one is a warning. A broken one is not: every way
     // it breaks still looks installed from the outside.
@@ -79,6 +172,21 @@ const handleVerify = async (args) => {
         for (const row of serviceRows)
             record(row.label, row.state);
     }
+    // ── MCP registrations ────────────────────────────────────────
+    const registrations = activeMcpRegistrations(resolves);
+    if (registrations.length > 0) {
+        console.log('\n  MCP registrations:');
+        for (const { agent, result } of registrations) {
+            if (result.state === 'current')
+                record(`${agent}: launches \`${mcp_command_js_1.MCP_LAUNCH_ARGV.join(' ')}\``, 'pass');
+            else if (result.state === 'stale') {
+                record(`${agent}: still launches \`${result.argv.join(' ')}\` — one extra resident process per session. Re-run: zeph install`, 'warn');
+            }
+            else {
+                record(`${agent}: launches \`${result.argv[0]}\`, which is not on PATH — zeph tools will not load. Re-run: zeph install`, 'fail');
+            }
+        }
+    }
     // ── Per-agent config ─────────────────────────────────────────
     console.log('\n  Agents:');
     const detected = (0, agents_js_1.detectAgents)().filter((a) => a.detected);

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.11.0",
+  "version": "2.12.1",
   "description": "Zeph CLI + push notification SDK for AI agents",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -72,6 +72,7 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.4.3",
+    "@zeph-to/mcp-server": "^2.3.0",
     "ws": "^8.21.0"
   }
 }