@openagents-org/agent-launcher 0.2.190 → 0.2.192

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openagents-org/agent-launcher",
-  "version": "0.2.190",
+  "version": "0.2.192",
   "description": "OpenAgents Launcher \u2014 install, configure, and run AI coding agents from your terminal",
   "main": "src/index.js",
   "bin": {

package/src/adapters/codex.js

@@ -343,6 +343,13 @@ class CodexAdapter extends BaseAdapter {
 
         if (result.responseText) {
           await this.sendResponse(msgChannel, result.responseText);
+          // A run that said something and then died (turn.failed, non-zero
+          // exit) used to post only that opening line as the finished reply,
+          // so it read as "Codex says one sentence and stops" with the real
+          // error left in daemon.log. Say it stopped, and why.
+          if (CodexAdapter._endedEarly(result)) {
+            await this._sendRunFailure(msgChannel, result, { partial: true });
+          }
           return;
         } else if (result.exitCode !== 0 && threadId && attempt === 0) {
           // Stale thread — clear and retry fresh
@@ -384,6 +391,7 @@ class CodexAdapter extends BaseAdapter {
       let lineBuffer = '';
       let stderrBuf = '';
       let lastErrorMessage = '';
+      let turnFailed = false;
       let _pendingLines = Promise.resolve();
 
       if (proc.stderr) {
@@ -433,7 +441,11 @@ class CodexAdapter extends BaseAdapter {
             this._log(`Command: ${cmdText} → exit ${exitCode}`);
           } else if (item.type === 'file_change') {
             hasToolUseSinceLastText = true;
-            const filename = item.filename || '';
+            // codex reports the edited files in `changes`; `filename` is the
+            // legacy shape and was always empty on current CLIs.
+            const filename = Array.isArray(item.changes) && item.changes.length
+              ? item.changes.map((c) => c && c.path).filter(Boolean).join(', ')
+              : (item.filename || '');
             try { await this.sendStatus(msgChannel, `**Editing:** \`${filename}\``); } catch {}
             this._log(`File change: ${filename}`);
           }
@@ -441,6 +453,7 @@ class CodexAdapter extends BaseAdapter {
           const error = event.error || {};
           const errMsg = error.message || JSON.stringify(error);
           lastErrorMessage = errMsg;
+          turnFailed = true;
           this._log(`Turn failed: ${errMsg}`);
         } else if (eventType === 'error') {
           const errMsg = event.message || JSON.stringify(event);
@@ -481,6 +494,7 @@ class CodexAdapter extends BaseAdapter {
           exitCode: code,
           stderr: stderrBuf,
           errorMessage: lastErrorMessage,
+          turnFailed,
         });
       });
 
@@ -569,14 +583,31 @@ class CodexAdapter extends BaseAdapter {
    * Post a user-visible failure carrying the actual reason a run produced no
    * reply, instead of a generic "No response generated".
    */
-  async _sendRunFailure(msgChannel, result) {
+  async _sendRunFailure(msgChannel, result, { partial = false } = {}) {
     const detail = CodexAdapter._failureDetail(result);
+    if (partial) {
+      const body = detail
+        ? `It stopped before finishing this task.\n\n> ${detail}`
+        : 'It stopped before finishing this task. Please try again.';
+      await this.sendError(msgChannel, `⚠️ **Codex stopped partway** — ${body}`);
+      return;
+    }
     const body = detail
       ? `Codex failed to complete this run.\n\n> ${detail}`
       : 'Codex finished without producing a reply. Please try again.';
     await this.sendError(msgChannel, `⚠️ **Codex couldn't run** — ${body}`);
   }
 
+  /**
+   * True when a run that produced some text did not actually finish. Only a
+   * turn.failed or a non-zero exit counts: codex also emits `error` events
+   * for retries it recovers from ("Reconnecting... 2/5"), and a run that
+   * reconnected and then completed is fine.
+   */
+  static _endedEarly({ exitCode, turnFailed } = {}) {
+    return Boolean(turnFailed) || (exitCode !== 0 && exitCode !== undefined);
+  }
+
   /**
    * Pick the most informative failure detail from a run result:
    * turn.failed / error event message → stderr tail → exit code. Redacted.

package/src/adapters/kimi.js

@@ -38,6 +38,7 @@ const { spawn } = require('../wsl');
 const LlmDirectAdapter = require('./llm-direct');
 const { formatAttachmentsForPrompt, SESSION_DEFAULT_RE, generateSessionTitle } = require('./utils');
 const { defaultAgentWorkdir, whichBinary, whereBinary } = require('../paths');
+const { fixSpawnHelpersFor } = require('../node-pty-perms');
 const {
   KimiStreamParser,
   interpretKimiMessage,
@@ -70,6 +71,7 @@ const WATCHDOG_MAX = 20;         // ~5 min of silence → kill
 // don't re-spawn `kimi --version`, yet an install/upgrade is re-detected.
 const VERSION_CACHE_TTL_MS = 5 * 60 * 1000;
 const _kimiVersionCache = new Map(); // binPath -> { version, product, at }
+const _ptyFixedBins = new Set(); // binPaths whose node-pty spawn-helper was checked
 
 /** Newest mtime (ms) of a directory and everything under it, `depth` levels deep. */
 function newestMtimeMs(dir, depth) {
@@ -522,6 +524,15 @@ class KimiAdapter extends LlmDirectAdapter {
       return;
     }
 
+    // An install from before the installer restored node-pty's spawn-helper
+    // (or one the user made) still has it at 0644, and every terminal Kimi
+    // opens fails with "posix_spawnp failed." Once per binary per daemon.
+    if (!_ptyFixedBins.has(kimiBin)) {
+      _ptyFixedBins.add(kimiBin);
+      const fixed = fixSpawnHelpersFor(kimiBin);
+      if (fixed.length) this._log(`Made node-pty spawn-helper executable: ${fixed.join(', ')}`);
+    }
+
     await this._handleMessageCli(msg, kimiBin);
   }
 

package/src/adapters/pi.js

@@ -24,7 +24,8 @@
  *
  * Verified against pi 0.83.0 (engines.node >= 22.19.0). Because that engine
  * floor is above what a user's ambient Node may satisfy, a resolved JS entry
- * point is launched with the launcher's own portable Node (v22.22.3) and
+ * point is launched with the launcher's own portable Node (v24, or v22 on
+ * macOS before 13.5) and
  * preflight refuses to start on anything older.
  */
 

package/src/cli.js

@@ -582,7 +582,17 @@ async function cmdNode(connector, flags, positional) {
       process.exitCode = 1;
       return;
     }
-    const info = nodeCfg.gatherDeviceInfo();
+    let info;
+    try {
+      info = nodeCfg.gatherDeviceInfo();
+    } catch (e) {
+      // Pairing on top of an unreadable node.json would replace the pairings
+      // it holds; stop instead, so nothing is lost while it is sorted out.
+      print(`Could not read ${nodeCfg.NODE_FILE}: ${e.message}`);
+      print('Close anything that may have it open and try again.');
+      process.exitCode = 1;
+      return;
+    }
     if (flags.type) info.deviceType = flags.type;   // server | laptop | desktop
     if (flags.name) info.name = flags.name;
 

package/src/config.js

@@ -180,48 +180,62 @@ class Config {
 
   getLogs(agentName, lines = 200) {
     try {
-      if (!fs.existsSync(this.logFile)) return [];
-      const content = fs.readFileSync(this.logFile, 'utf-8');
-      let allLines = content.split('\n').filter(Boolean);
-      if (agentName) {
-        allLines = allLines.filter(
-          (l) => l.includes(agentName) || l.includes('daemon') || l.includes('Daemon')
-        );
-      }
-      return allLines.slice(-lines);
+      return this.tailLogs({ agent: agentName, lines }).lines;
     } catch {
       return [];
     }
   }
 
   /**
-   * Tail log file with optional filter. Returns { lines, size }.
+   * Tail log file with optional filter. Returns { lines, size, reset }.
+   * Reads only the end of the file (or what was appended since `offset`), so
+   * the cost tracks what is returned rather than how large daemon.log grew.
    * @param {Object} opts - { agent, lines, offset }
    * @param {string} [opts.agent] - Filter by agent name
    * @param {number} [opts.lines=100] - Number of lines to return
    * @param {number} [opts.offset=0] - Byte offset for incremental reads (0 = from end)
+   * @returns {{ lines: string[], size: number, reset: boolean }} `size` is the
+   *   offset for the next call; `reset` means the file shrank (cleared or
+   *   replaced) and `lines` replace what the caller had.
    */
   tailLogs(opts = {}) {
     const { agent, lines = 100, offset = 0 } = opts;
+    const keep = agent
+      ? (l) => l.includes(agent) || l.includes('daemon') || l.includes('Daemon')
+      : () => true;
+    let size;
     try {
-      if (!fs.existsSync(this.logFile)) return { lines: [], size: 0 };
-      const stat = fs.statSync(this.logFile);
-      if (offset > 0 && offset < stat.size) {
-        // Incremental read from offset
-        const fd = fs.openSync(this.logFile, 'r');
-        const buf = Buffer.alloc(stat.size - offset);
-        fs.readSync(fd, buf, 0, buf.length, offset);
-        fs.closeSync(fd);
-        let newLines = buf.toString('utf-8').split('\n').filter(Boolean);
-        if (agent) {
-          newLines = newLines.filter(l => l.includes(agent) || l.includes('Daemon'));
+      size = fs.statSync(this.logFile).size;
+    } catch {
+      return { lines: [], size: 0, reset: offset > 0 };
+    }
+    // Nothing appended since the last read.
+    if (offset > 0 && offset === size) return { lines: [], size, reset: false };
+
+    try {
+      const fd = fs.openSync(this.logFile, 'r');
+      try {
+        if (offset > 0 && offset < size) {
+          const start = Math.max(offset, size - MAX_INCREMENT_BYTES);
+          const buf = readRange(fd, start, size);
+          const lastNewline = buf.lastIndexOf(0x0a);
+          // A line still being written is left for the next read.
+          if (lastNewline < 0) {
+            return { lines: [], size: start > offset ? size : offset, reset: false };
+          }
+          let body = buf.subarray(0, lastNewline + 1);
+          // Skipped part of the backlog: drop the fragment the read landed in.
+          if (start > offset) body = body.subarray(body.indexOf(0x0a) + 1);
+          return { lines: splitLines(body, keep), size: start + lastNewline + 1, reset: false };
         }
-        return { lines: newLines, size: stat.size };
+        // First read, or the file shrank under us (cleared, replaced).
+        const tail = readLastLines(fd, size, lines, keep);
+        return { lines: tail.lines, size: tail.end, reset: offset > 0 };
+      } finally {
+        fs.closeSync(fd);
       }
-      // Full read, return last N
-      return { lines: this.getLogs(agent, lines), size: stat.size };
     } catch {
-      return { lines: [], size: 0 };
+      return { lines: [], size: 0, reset: offset > 0 };
     }
   }
 
@@ -323,6 +337,62 @@ function parseYaml(text) {
   return result;
 }
 
+/** Bytes read per step when walking back from the end of the log. */
+const TAIL_CHUNK = 64 * 1024;
+/** How far back a first read may walk looking for lines matching the agent filter. */
+const MAX_SCAN_BYTES = 16 * 1024 * 1024;
+/** The most an incremental read takes in one go; older backlog is skipped. */
+const MAX_INCREMENT_BYTES = 4 * 1024 * 1024;
+
+function readRange(fd, start, end) {
+  const buf = Buffer.alloc(end - start);
+  let read = 0;
+  while (read < buf.length) {
+    const n = fs.readSync(fd, buf, read, buf.length - read, start + read);
+    if (n === 0) break;
+    read += n;
+  }
+  return read === buf.length ? buf : buf.subarray(0, read);
+}
+
+function splitLines(buf, keep) {
+  return buf.toString('utf-8').split('\n').filter((l) => l && keep(l));
+}
+
+/**
+ * The last `count` matching lines, read backwards in chunks. Stops at the last
+ * newline: a line still being written is left for the next incremental read.
+ */
+function readLastLines(fd, size, count, keep) {
+  const lastChunk = readRange(fd, Math.max(0, size - TAIL_CHUNK), size);
+  const lastNewline = lastChunk.lastIndexOf(0x0a);
+  const end = lastNewline >= 0 ? size - lastChunk.length + lastNewline + 1 : size;
+
+  let lines = [];
+  let pos = end;
+  let carry = Buffer.alloc(0);
+  while (pos > 0 && lines.length < count && end - pos < MAX_SCAN_BYTES) {
+    const start = Math.max(0, pos - TAIL_CHUNK);
+    const block = Buffer.concat([readRange(fd, start, pos), carry]);
+    pos = start;
+    let body = block;
+    if (pos > 0) {
+      // The block starts mid-line; that fragment joins the next block.
+      const firstNewline = block.indexOf(0x0a);
+      if (firstNewline < 0) {
+        carry = block;
+        continue;
+      }
+      carry = block.subarray(0, firstNewline);
+      body = block.subarray(firstNewline + 1);
+    } else {
+      carry = Buffer.alloc(0);
+    }
+    lines = [...splitLines(body, keep), ...lines];
+  }
+  return { lines: lines.slice(-count), end };
+}
+
 function normalizeTimeValue(value) {
   if (value instanceof Date) {
     return Number.isNaN(value.getTime()) ? null : value;

package/src/daemon.js

@@ -86,6 +86,15 @@ function _sentKey(args) {
   return present && !args.useDeviceCredentials;
 }
 
+/**
+ * Whether a node heartbeat failure is the workspace saying the node is gone:
+ * a 404 carrying the backend's own message (routers/nodes.py), not any 404.
+ */
+const NODE_GONE_MESSAGES = new Set(['Node not found', 'Workspace not found']);
+function _nodeGone(err) {
+  return !!err && err.status === 404 && NODE_GONE_MESSAGES.has(err.message);
+}
+
 class Daemon {
   constructor(config, envManager, registry) {
     this.config = config;
@@ -206,7 +215,9 @@ class Daemon {
     const nodeCfg = require('./node-config');
     const pairings = nodeCfg.listPairings().filter((p) => p && p.node_id && p.token);
     if (!pairings.length) return;  // no node connected
-    const info = { ...nodeCfg.gatherDeviceInfo(), runtimes: this._runtimes || [], fs: this._buildFs() };
+    // deviceInfo, not gatherDeviceInfo: the heartbeat sends no device key, and
+    // must never be the thing that writes node.json.
+    const info = { ...nodeCfg.deviceInfo(), runtimes: this._runtimes || [], fs: this._buildFs() };
     await Promise.all(pairings.map((p) => this._nodeHeartbeatOne(nodeCfg, p, info)));
   }
 
@@ -264,8 +275,12 @@ class Daemon {
       // Without this the launcher kept showing "connected" long after a remote
       // removal, since node.json was only ever reconciled by the UI on demand.
       // Transient failures (timeouts, 5xx, auth blips) say nothing about the
-      // row's existence, so those are swallowed and retried next tick.
-      if (err && err.status === 404) {
+      // row's existence, so those are swallowed and retried next tick. So is a
+      // 404 the backend did not write: the hosting platform answers every
+      // request with its own 404 ("Application not found") while the service
+      // is unreachable, and taking that as the workspace's word unpaired every
+      // workspace on the device at once.
+      if (_nodeGone(err)) {
         try { nodeCfg.clearPairing(n.workspace_id); } catch {}
         this._nodeClients.delete(n.workspace_id);
         this._log(`node ${n.node_id} no longer recognized by workspace ${n.workspace_slug || n.workspace_id} — pairing cleared`);

package/src/installer.js

@@ -23,6 +23,7 @@ const { nodeDistUrls, installRegistry } = require('./mirrors');
 const { readinessReason, REASON } = require('./adapters/health-status');
 const { checkInstallPrereqs, missingPrereqError } = require('./install-preflight');
 const { detectShadowedNodeShims, shadowedNodeWarning } = require('./node-shims');
+const { fixSpawnHelpers } = require('./node-pty-perms');
 
 const STATUS_CACHE_TTL_MS = 10000;
 const statusCache = new Map();
@@ -1130,14 +1131,16 @@ class Installer {
     await this._bootstrapManagedUv(agentType, bootstrapEnv, null);
 
     // Use bundled node/npm if system npm not available
-    if (cmd.startsWith('npm install')) {
-      const prefixDir = getRuntimePrefix(agentType);
+    const npmPrefix = cmd.startsWith('npm install') ? getRuntimePrefix(agentType) : null;
+    if (npmPrefix) {
+      const prefixDir = npmPrefix;
       fs.mkdirSync(prefixDir, { recursive: true });
       const args = cmd.replace('npm install', 'install --save').replace(' -g ', ` --prefix "${prefixDir}" `);
       cmd = this._resolveNpmCommand(args);
     }
 
     const output = await this._execShell(cmd, 300000, installEnv);
+    if (npmPrefix) fixSpawnHelpers(npmPrefix);
 
     // Aider-only: the curl/uv/pipx installer can exit 0 without landing a
     // runnable (or genuine) binary, so verify the real CLI exists BEFORE
@@ -1419,6 +1422,10 @@ class Installer {
             }
             if (onData) onData(`\nCursor CLI resolved: ${cursor.path}\n`);
           }
+          if (rawCmd.startsWith('npm install')) {
+            const fixed = fixSpawnHelpers(installCwd);
+            if (fixed.length && onData) onData(`\nMade ${fixed.length} node-pty spawn-helper(s) executable.\n`);
+          }
           this._markInstalled(agentType);
           if (onData) onData(`\nDone! ${agentType} is now installed.\n`);
           resolve({ success: true, command: displayCmd });
@@ -2153,6 +2160,20 @@ class Installer {
     return false;
   }
 
+  /**
+   * The Node.js the portable runtime gets — the same pin as the launcher's
+   * bootstrap/node-version.ts, which owns upgrading an existing runtime; this
+   * copy only ever installs onto a machine with no Node at all. Node 24 needs
+   * macOS 13.5 (Darwin 22.6), so older Macs get the last Node 22 instead.
+   */
+  static portableNodeVersion(platform = process.platform, release = require('os').release()) {
+    if (platform === 'darwin') {
+      const [major, minor] = String(release).split('.').map(Number);
+      if (major < 22 || (major === 22 && minor < 6)) return 'v22.22.3';
+    }
+    return 'v24.21.0';
+  }
+
   /**
    * Download and install Node.js LTS. Streams progress via onData callback.
    * After install, updates PATH so npm is available for subsequent commands.
@@ -2163,14 +2184,15 @@ class Installer {
     const { spawn: spawnProc } = require('child_process');
     const https = require('https');
     const os = require('os');
-    const nodeVersion = 'v22.22.3';
     const plat = Installer.platform();
+    const nodeVersion = Installer.portableNodeVersion();
 
     if (onData) onData(`Node.js not found. Installing Node.js ${nodeVersion}...\n\n`);
 
     if (plat === 'windows') {
       // Download portable zip — no admin required
-      const arch = os.arch() === 'x64' ? 'x64' : 'x86';
+      // No 32-bit Windows build exists past Node 22.
+      const arch = os.arch() === 'arm64' ? 'arm64' : 'x64';
       const zipPath = path.join(os.tmpdir(), `node-${nodeVersion}.zip`);
 
       await this._downloadFirst(

package/src/node-config.js

@@ -16,30 +16,64 @@ const crypto = require('crypto');
 const NODE_DIR = path.join(os.homedir(), '.openagents');
 const NODE_FILE = path.join(NODE_DIR, 'node.json');
 
-function loadNode() {
+/**
+ * The record on disk: null when there is no file, and a throw when there is
+ * one that cannot be read or parsed (half-written by another process, or held
+ * by an antivirus scan on Windows). Every writer reads through this, so an
+ * unreadable file is left alone rather than rebuilt from nothing — which
+ * dropped every pairing and minted a new device key.
+ */
+function readNode() {
+  let raw;
   try {
-    if (fs.existsSync(NODE_FILE)) return JSON.parse(fs.readFileSync(NODE_FILE, 'utf-8'));
-  } catch {}
-  return null;
+    raw = fs.readFileSync(NODE_FILE, 'utf-8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+  return JSON.parse(raw);
 }
 
+/** Lenient read for display and heartbeat: an unreadable file counts as none. */
+function loadNode() {
+  try { return readNode(); } catch { return null; }
+}
+
+/**
+ * Written through a temp file and a rename, so a reader in the other process
+ * (launcher or daemon) sees the old record or the new one, never a torn one.
+ */
 function saveNode(data) {
   try {
     fs.mkdirSync(NODE_DIR, { recursive: true });
-    fs.writeFileSync(NODE_FILE, JSON.stringify(data, null, 2));
-    try { fs.chmodSync(NODE_FILE, 0o600); } catch {}  // holds the workspace token
+    const tmp = `${NODE_FILE}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(data, null, 2), { mode: 0o600 });  // holds the workspace token
+    try {
+      fs.renameSync(tmp, NODE_FILE);
+    } catch {
+      // Windows refuses the rename while another process holds the target.
+      try { fs.unlinkSync(tmp); } catch {}
+      fs.writeFileSync(NODE_FILE, JSON.stringify(data, null, 2));
+    }
+    try { fs.chmodSync(NODE_FILE, 0o600); } catch {}
   } catch {}
 }
 
-/** Stable per-device id, generated once and persisted. */
+/** Stable per-device id, generated once and persisted. Throws if node.json is unreadable. */
 function getOrCreateNodeKey() {
-  const existing = loadNode();
+  const existing = readNode();
   if (existing && existing.node_key) return existing.node_key;
   const key = (crypto.randomUUID && crypto.randomUUID()) || crypto.randomBytes(16).toString('hex');
   saveNode({ ...(existing || {}), node_key: key });
   return key;
 }
 
+function pairingsOf(record) {
+  if (!record) return [];
+  if (record.pairings && record.pairings.length) return record.pairings;
+  return record.workspace_id ? [record] : [];
+}
+
 /**
  * Every workspace this device is paired to, most recent first.
  *
@@ -49,10 +83,7 @@ function getOrCreateNodeKey() {
  * existed carry a single top-level pairing, which is reconstructed here.
  */
 function listPairings() {
-  const record = loadNode();
-  if (!record) return [];
-  if (record.pairings && record.pairings.length) return record.pairings;
-  return record.workspace_id ? [record] : [];
+  return pairingsOf(loadNode());
 }
 
 /**
@@ -67,7 +98,7 @@ function recordPairing(nodeKey, pairing) {
   const stamped = { ...pairing, paired_at: new Date().toISOString() };
   const pairings = [
     stamped,
-    ...listPairings().filter((p) => p.workspace_id !== pairing.workspace_id),
+    ...pairingsOf(readNode()).filter((p) => p.workspace_id !== pairing.workspace_id),
   ];
   saveNode({ node_key: nodeKey, ...stamped, pairings });
 }
@@ -86,12 +117,12 @@ function recordPairing(nodeKey, pairing) {
  * @returns the pairing that was dropped, or null if there was no such pairing.
  */
 function clearPairing(workspaceId) {
-  const record = loadNode();
+  const record = readNode();
   if (!record) return null;
   const target = workspaceId || record.workspace_id;
   if (!target) return null;
 
-  const pairings = listPairings();
+  const pairings = pairingsOf(record);
   const dropped = pairings.find((p) => p.workspace_id === target);
   if (!dropped) return null;
 
@@ -114,12 +145,11 @@ function inferDeviceType() {
   return 'server';  // linux is typically a server/VM in this context
 }
 
-/** Device info sent on redeem/heartbeat. */
-function gatherDeviceInfo() {
+/** Device info sent on every heartbeat. Reads and writes nothing on disk. */
+function deviceInfo() {
   let launcherVersion = '';
   try { launcherVersion = require('../package.json').version; } catch {}
   return {
-    nodeKey: getOrCreateNodeKey(),
     hostname: os.hostname(),
     os: os.platform(),
     deviceType: inferDeviceType(),
@@ -127,7 +157,13 @@ function gatherDeviceInfo() {
   };
 }
 
+/** Device info sent on redeem, with the device key (minted on first pairing). */
+function gatherDeviceInfo() {
+  return { nodeKey: getOrCreateNodeKey(), ...deviceInfo() };
+}
+
 module.exports = {
+  readNode,
   loadNode,
   saveNode,
   listPairings,
@@ -135,6 +171,7 @@ module.exports = {
   clearPairing,
   getOrCreateNodeKey,
   inferDeviceType,
+  deviceInfo,
   gatherDeviceInfo,
   NODE_FILE,
   NODE_DIR,

package/src/node-pty-perms.js

@@ -0,0 +1,111 @@
+/**
+ * Restore the execute bit on node-pty's `spawn-helper`.
+ *
+ * node-pty 1.1.0 publishes its macOS/Linux prebuilds with
+ * `prebuilds/<platform>/spawn-helper` at mode 0644, and npm does not fix it
+ * (the package has no install script to). pty.spawn() execs that helper, so
+ * every terminal the CLI opens dies with "posix_spawnp failed." — seen with
+ * Kimi Code, whose optional `node-pty` dependency resolves to 1.1.0. Every
+ * node-pty fork that ships a spawn-helper is treated the same, so the next CLI
+ * that pulls one in is covered too.
+ *
+ * Nothing to do on Windows: there is no spawn-helper and no mode bits.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const IS_WINDOWS = process.platform === 'win32';
+
+/** Nested node_modules deeper than this are not worth walking. */
+const MAX_DEPTH = 6;
+
+/** Packages whose spawn-helper this module restores. */
+const PTY_PACKAGES = [
+  'node-pty',
+  // @lydell keeps its prebuilds in a per-platform package.
+  `@lydell/node-pty-${process.platform}-${process.arch}`,
+];
+
+function readDir(dir) {
+  try { return fs.readdirSync(dir); } catch { return []; }
+}
+
+/**
+ * chmod +x every spawn-helper inside one package directory.
+ * @returns {string[]} the helpers that were fixed
+ */
+function fixPackage(pkgDir) {
+  const helpers = [path.join(pkgDir, 'build', 'Release', 'spawn-helper')];
+  const prebuilds = path.join(pkgDir, 'prebuilds');
+  for (const plat of readDir(prebuilds)) {
+    helpers.push(path.join(prebuilds, plat, 'spawn-helper'));
+  }
+  const fixed = [];
+  for (const helper of helpers) {
+    try {
+      const { mode } = fs.statSync(helper);
+      if ((mode & 0o111) === 0o111) continue;
+      fs.chmodSync(helper, mode | 0o755);
+      fixed.push(helper);
+    } catch {}
+  }
+  return fixed;
+}
+
+/**
+ * Walk an npm prefix's node_modules (nested ones included) and fix every
+ * package that carries a spawn-helper. Run after an npm install.
+ * @param {string} prefixDir - the `--prefix` the agent was installed into
+ * @returns {string[]} the helpers that were fixed
+ */
+function fixSpawnHelpers(prefixDir) {
+  if (IS_WINDOWS) return [];
+  const fixed = [];
+  const visit = (modulesDir, depth) => {
+    if (depth > MAX_DEPTH) return;
+    for (const entry of readDir(modulesDir)) {
+      if (entry.startsWith('.')) continue;
+      const dirs = entry.startsWith('@')
+        ? readDir(path.join(modulesDir, entry)).map((s) => path.join(modulesDir, entry, s))
+        : [path.join(modulesDir, entry)];
+      for (const pkgDir of dirs) {
+        fixed.push(...fixPackage(pkgDir));
+        visit(path.join(pkgDir, 'node_modules'), depth + 1);
+      }
+    }
+  };
+  visit(path.join(prefixDir, 'node_modules'), 0);
+  return fixed;
+}
+
+/**
+ * Fix the node-pty a CLI would load, resolved the way Node resolves it from
+ * the CLI's own location — for an install that predates fixSpawnHelpers, or
+ * one the user made themselves.
+ * @param {string} fromPath - the CLI binary or entry script
+ * @returns {string[]} the helpers that were fixed
+ */
+function fixSpawnHelpersFor(fromPath) {
+  if (IS_WINDOWS || !fromPath) return [];
+  let start;
+  try { start = path.dirname(fs.realpathSync(fromPath)); } catch { return []; }
+  // Node's lookup by hand: the nearest node_modules/<name> going up. Not
+  // require.resolve — a package with an `exports` map refuses package.json.
+  const fixed = [];
+  for (const name of PTY_PACKAGES) {
+    for (let dir = start; ; dir = path.dirname(dir)) {
+      const pkgDir = path.join(dir, 'node_modules', name);
+      if (fs.existsSync(path.join(pkgDir, 'package.json'))) {
+        fixed.push(...fixPackage(pkgDir));
+        break;
+      }
+      if (path.dirname(dir) === dir) break;
+    }
+  }
+  return fixed;
+}
+
+module.exports = { fixSpawnHelpers, fixSpawnHelpersFor };