@yolo-labs/yolobridge 0.30.0 → 0.32.0

package/dist/check-pty-helper.js

@@ -0,0 +1,217 @@
+/**
+ * Can node-pty spawn ITS OWN helper? On macOS this is what usually failed.
+ *
+ * ⚠️ NODE-PTY DOES NOT SPAWN YOUR BINARY. On unix it spawns `spawn-helper`
+ * and passes the real command as an argument (`pty.cc`: `argv[0] =
+ * helper_path`). When that spawn fails it throws the literal string
+ * `posix_spawnp failed.` — which names neither the helper nor your agent, and
+ * is the same message you get when the agent genuinely is missing.
+ *
+ * So an operator can have a perfectly good `claude`, pass every check in
+ * `resolve-agent-binary.ts`, and still see:
+ *
+ *     yolo-bridge: failed to start the local agent (posix_spawnp failed.)
+ *
+ * because the thing that could not be spawned was node-pty's own helper. That
+ * is exactly what happened on macOS with `claude` installed twice and both
+ * copies healthy.
+ *
+ * ⚠️ macOS ONLY, deliberately. The helper is a darwin build artifact; Linux
+ * has no `spawn-helper` on disk at all, so probing for one there would report
+ * a missing file on every healthy install — a false alarm in the one direction
+ * a diagnostic must never fire.
+ *
+ * Common causes: npm dropping the executable bit when unpacking, Gatekeeper
+ * quarantine on a downloaded prebuild, or a partially-restored node_modules.
+ */
+import { createRequire } from 'node:module';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const DEFAULT_FS = {
+    loadsNative(p) {
+        // node-pty has already loaded successfully by the time this runs (the CLI
+        // imports it), so for the winning path this is a require-cache hit with no
+        // side effects; for a stale or ABI-incompatible one it throws, exactly as
+        // it does inside node-pty's own loader.
+        try {
+            createRequire(import.meta.url)(p);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    existsSync: (p) => fs.existsSync(p),
+    statSync: (p) => fs.statSync(p),
+    accessSync: (p, mode) => fs.accessSync(p, mode),
+    constants: { X_OK: fs.constants.X_OK },
+};
+/** node-pty's package root, or undefined when it cannot be located. */
+export function findNodePtyRoot(resolveFrom, io = DEFAULT_FS) {
+    try {
+        const require_ = createRequire(resolveFrom);
+        let dir = path.dirname(require_.resolve('node-pty'));
+        for (let i = 0; i < 8; i++) {
+            if (io.existsSync(path.join(dir, 'package.json')) && path.basename(dir) === 'node-pty')
+                return dir;
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    return undefined;
+}
+/**
+ * Where node-pty will look for its native module — and therefore its helper.
+ *
+ * ⚠️ NOT `build/Release`. That was the first version of this check and it was
+ * wrong in the worst direction: node-pty 1.1.0 ships PREBUILDS, and
+ * `scripts/prebuild.js` only verifies they exist — it never copies them into
+ * `build/Release`. So a healthy macOS install loads from
+ * `prebuilds/darwin-arm64/` and has no `build/Release` at all, and hardcoding
+ * that path would have aborted EVERY attach on EVERY healthy Mac. (codex P1.)
+ *
+ * This mirrors node-pty's own order from `lib/utils.js` — Release, Debug, then
+ * the platform/arch prebuild — and identifies the live directory by the
+ * presence of `pty.node`, the same file node-pty itself requires. Both the
+ * package root and its `lib/` are checked, matching node-pty's unbundled and
+ * bundled relative lookups.
+ */
+export function findHelperPath(root, platform, arch, io) {
+    return findHelperCandidates(root, platform, arch, io)[0];
+}
+/**
+ * EVERY directory node-pty might load from, in its own order.
+ *
+ * ⚠️ EXISTENCE IS NOT SELECTION, and neither is "any usable helper wins".
+ * Two review rounds pushed this in opposite directions, and both were right
+ * about the version they saw:
+ *
+ *   · stopping at the first pty.node that merely EXISTS inspects a stale or
+ *     ABI-incompatible `build/Release` that node-pty skips at runtime — and
+ *     aborts an attach that works;
+ *   · accepting ANY usable helper among the candidates passes an install where
+ *     node-pty loads a Release module whose OWN helper is broken, while a
+ *     complete prebuild sits unused behind it — and reports health while the
+ *     spawn fails.
+ *
+ * Neither is fixable by ordering, because the question is which module
+ * actually LOADS. So `loadsNative` mirrors node-pty's require()-and-catch and
+ * the winner is the first candidate that genuinely loads; its paired helper is
+ * the only one that matters.
+ */
+export function findHelperCandidates(root, platform, arch, io) {
+    // ⚠️ BUILD TYPE OUTER, BASE INNER — node-pty's `loadNativeModule` tries each
+    // build type across BOTH relative bases before advancing to the next type.
+    // Inverting these loops picks the root prebuild over a bundled
+    // `lib/build/Release` that node-pty would actually load, so the check would
+    // inspect a different helper than the one being executed. (codex P2.)
+    const dirs = ['build/Release', 'build/Debug', `prebuilds/${platform}-${arch}`];
+    const found = [];
+    for (const d of dirs) {
+        for (const base of [root, path.join(root, 'lib')]) {
+            const dir = path.join(base, ...d.split('/'));
+            const native = path.join(dir, 'pty.node');
+            if (io.existsSync(native) && io.loadsNative(native))
+                found.push(path.join(dir, 'spawn-helper'));
+        }
+    }
+    return found;
+}
+/** Whether one candidate helper is a real, executable file. */
+function helperUsable(helperPath, io) {
+    if (!io.existsSync(helperPath))
+        return false;
+    try {
+        if (!io.statSync(helperPath).isFile())
+            return false;
+        io.accessSync(helperPath, io.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether node-pty's spawn-helper is present and executable.
+ *
+ * Returns `not-applicable` off darwin and whenever the helper cannot be
+ * located — an inconclusive probe must not manufacture a failure, because the
+ * cost of a false alarm here is sending someone to chmod a file that was never
+ * meant to exist.
+ */
+export function checkPtyHelper(opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    if (platform !== 'darwin')
+        return { ok: true, reason: 'not-applicable' };
+    const io = opts.io ?? DEFAULT_FS;
+    const root = opts.nodePtyRoot ?? findNodePtyRoot(opts.resolveFrom ?? import.meta.url, io);
+    if (!root)
+        return { ok: true, reason: 'not-applicable' };
+    const candidates = findHelperCandidates(root, platform, opts.arch ?? process.arch, io);
+    // Could not tell where node-pty loads from: stay silent rather than invent a
+    // fault. Same rule as an unlocatable package.
+    if (candidates.length === 0)
+        return { ok: true, reason: 'not-applicable' };
+    // ⚠️ THE FIRST CANDIDATE THAT ACTUALLY LOADS IS THE ONE NODE-PTY USES, and
+    // only ITS helper matters. A complete prebuild sitting behind a loadable
+    // Release module is never reached, so it cannot excuse a broken helper
+    // there. (codex P2, correcting the previous round's over-correction.)
+    const helperPath = candidates[0];
+    if (helperUsable(helperPath, io))
+        return { ok: true, reason: 'healthy' };
+    if (!io.existsSync(helperPath)) {
+        return {
+            ok: false,
+            reason: 'missing',
+            helperPath,
+            message: `node-pty's spawn-helper is missing at ${helperPath}.\n`
+                + `  ⚠️ This is NOT a problem with your agent. node-pty spawns this helper rather than\n`
+                + `     your binary directly, so its absence surfaces as the same "posix_spawnp failed."\n`
+                + `     you would see if the agent itself were missing.\n`
+                + `  Reinstall to restore it: npm i -g @yolo-labs/yolobridge`,
+        };
+    }
+    // ⚠️ A DIRECTORY PASSES X_OK. `accessSync(dir, X_OK)` succeeds for any
+    // searchable directory, so a corrupt or partially-restored install with a
+    // directory at this path would be waved through as healthy while node-pty
+    // cannot execute it. (codex P2.)
+    let isFile;
+    try {
+        isFile = io.statSync(helperPath).isFile();
+    }
+    catch {
+        isFile = false;
+    }
+    if (!isFile) {
+        return {
+            ok: false,
+            reason: 'missing',
+            helperPath,
+            message: `node-pty's spawn-helper at ${helperPath} is not a file.\n`
+                + `  ⚠️ This is NOT a problem with your agent — node-pty spawns this helper rather than\n`
+                + `     your binary directly, so it fails with the same "posix_spawnp failed."\n`
+                + `  Reinstall to restore it: npm i -g @yolo-labs/yolobridge`,
+        };
+    }
+    try {
+        io.accessSync(helperPath, io.constants.X_OK);
+    }
+    catch {
+        return {
+            ok: false,
+            reason: 'not-executable',
+            helperPath,
+            message: `node-pty's spawn-helper at ${helperPath} is not executable.\n`
+                + `  ⚠️ This is NOT a problem with your agent. node-pty spawns this helper rather than\n`
+                + `     your binary directly, so it fails with the same "posix_spawnp failed." you would\n`
+                + `     see if the agent itself were missing. npm can drop the executable bit on unpack.\n`
+                + `  Fix it with: chmod +x ${helperPath}`,
+        };
+    }
+    return { ok: true, reason: 'healthy' };
+}

package/dist/cli.js

@@ -36,6 +36,7 @@ import { runAllow } from './approved-paths.js';
 import { runDetach } from './detach-cmd.js';
 import { getStatus, formatStatus } from './status-cmd.js';
 import { resolveAgentBinary } from './resolve-agent-binary.js';
+import { checkPtyHelper } from './check-pty-helper.js';
 import { startLocalAgent, stopLocalAgent, DEFAULT_AGENT_BIN } from './local-agent.js';
 import { runListWorkspaces, formatWorkspacesTable } from './workspaces-cmd.js';
 import { startMcpProxy, mcpUrl, SECRET_ENV_VAR } from './mcp-proxy.js';
@@ -466,6 +467,22 @@ async function cmdAttach(args) {
                     // Say where Ctrl+C goes BEFORE the agent takes over the screen.
                     // Without this the operator presses it expecting to quit, nothing
                     // happens, and there is no way to discover why.
+                    // ⚠️ THE HELPER FIRST, BEFORE THE AGENT. node-pty does not spawn
+                    // your binary — on unix it spawns its own `spawn-helper` and passes
+                    // the real command as an argument (`pty.cc`: argv[0] = helper_path).
+                    // A broken helper therefore fails with the SAME
+                    // `posix_spawnp failed.` as a missing agent, and checking the agent
+                    // first would report it healthy and leave the operator debugging a
+                    // binary that was never at fault — which is exactly what happened on
+                    // macOS with two working `claude` installs on PATH.
+                    const helper = checkPtyHelper();
+                    if (!helper.ok) {
+                        process.stdout.write(`yolo-bridge: cannot start the agent — ${helper.message}\n`);
+                        process.stdout.write('yolo-bridge: detaching...\n');
+                        stopRequested = true;
+                        await runDetach({ commonApiBaseUrl: apiUrl() }).catch(() => undefined);
+                        return;
+                    }
                     // ⚠️ RESOLVE THE BINARY BEFORE SPAWNING IT, so a failure can be
                     // EXPLAINED. node-pty reports an unspawnable binary as the bare
                     // string `posix_spawnp failed.` — no binary name, no PATH, no

package/dist/resolve-agent-binary.js

@@ -25,7 +25,246 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-const DEFAULT_FS = fs;
+const DEFAULT_FS = {
+    statSync: (p) => fs.statSync(p),
+    accessSync: (p, mode) => fs.accessSync(p, mode),
+    constants: { X_OK: fs.constants.X_OK },
+    readFirstLine(p) {
+        // Only the shebang is wanted, and the file may be a multi-megabyte binary,
+        // so this reads a small prefix rather than slurping it.
+        let fd;
+        try {
+            fd = fs.openSync(p, 'r');
+            const buf = Buffer.alloc(512);
+            const read = fs.readSync(fd, buf, 0, 512, 0);
+            const text = buf.subarray(0, read).toString('utf-8');
+            const nl = text.indexOf('\n');
+            return nl === -1 ? text : text.slice(0, nl);
+        }
+        catch {
+            return null;
+        }
+        finally {
+            if (fd !== undefined) {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch { /* already gone */ }
+            }
+        }
+    },
+};
+/**
+ * The interpreter a `#!` line names, resolved the way the kernel would.
+ *
+ * ⚠️ THIS IS THE CASE EVERY OTHER CHECK PASSES. An executable script whose
+ * interpreter is missing fails with ENOENT — the kernel reports the absent
+ * INTERPRETER, and it is indistinguishable from the script itself not
+ * existing. So a binary can be on PATH, be a real file, and be +x, and still
+ * be unspawnable. That is precisely the macOS report this was written for:
+ * `type -a claude` listed two real installs while node-pty said only
+ * `posix_spawnp failed.`
+ *
+ * `#!/usr/bin/env node` delegates the search back to PATH, so the argument is
+ * resolved recursively rather than treated as a literal path.
+ */
+function checkInterpreter(scriptPath, env, io, depth = 0) {
+    if (depth > 4)
+        return { ok: true }; // pathological chain; let the spawn speak
+    const first = io.readFirstLine(scriptPath);
+    if (!first || !first.startsWith('#!'))
+        return { ok: true }; // a real binary, not a script
+    const parts = tokenizeShebang(first.slice(2).trim());
+    if (parts.length === 0)
+        return { ok: true };
+    const [interpreter, ...rest] = parts;
+    // ⚠️ THE INTERPRETER ITSELF FIRST, ALWAYS. `#!/missing/env node` must fail on
+    // `/missing/env` even when `node` is perfectly available: the kernel execs
+    // the interpreter, and delegating straight to env's argument would report a
+    // clean bill of health for a script that cannot spawn. (codex P2.)
+    const interpreterFound = resolveAgentBinary(interpreter, env, io, depth + 1);
+    if (!interpreterFound.ok) {
+        // ⚠️ DO NOT BLAME THE OUTER INTERPRETER FOR AN INNER FAULT. If the
+        // interpreter EXISTS but is itself a script with a missing interpreter
+        // (claude -> /usr/bin/node -> /missing/runtime), its own message already
+        // names the file that is actually absent. Overwriting it here would state
+        // that /usr/bin/node cannot be found — about a file that is right there —
+        // which is the same misdirection this whole check exists to end.
+        // (codex P2.)
+        if (interpreterFound.reason === 'bad-interpreter') {
+            return { ok: false, nested: interpreterFound.message };
+        }
+        return { ok: false, interpreter, via: scriptPath };
+    }
+    // `env` hands the search back to PATH, so the command it delegates to is a
+    // second thing that must exist.
+    if (path.basename(interpreter) === 'env' && rest.length > 0) {
+        const { command, env: envForCommand } = envInvocation(rest, env);
+        if (!command)
+            return { ok: true };
+        // ⚠️ `envForCommand`, not `env`: the lookup must use the environment env
+        // will have BUILT by the time it resolves the command.
+        const resolved = resolveAgentBinary(command, envForCommand, io, depth + 1);
+        if (resolved.ok)
+            return { ok: true };
+        if (resolved.reason === 'bad-interpreter')
+            return { ok: false, nested: resolved.message };
+        return { ok: false, interpreter: command, via: scriptPath };
+    }
+    return { ok: true };
+}
+/**
+ * Split a shebang tail the way a shell would, not on raw whitespace.
+ *
+ * ⚠️ KNOWN LIMIT, ACCEPTED DELIBERATELY. This is shell-style tokenization, and
+ * the kernel's rules differ by platform: macOS splits a shebang tail on
+ * whitespace (so this matches it closely — and macOS is where the report that
+ * prompted this came from), while Linux hands the whole tail to the
+ * interpreter as ONE literal argument. So an exotic line like
+ * `#!/usr/bin/env NODE_ENV="a b" node` can be called spawnable here and still
+ * fail to exec on Linux.
+ *
+ * That residual gap is the RIGHT direction to leave open. Missing a broken
+ * script costs nothing new — the spawn then fails exactly as it does today,
+ * with node-pty's opaque message, which is the status quo this file improves
+ * on rather than a regression it introduces. Falsely REJECTING a working
+ * agent, by contrast, would block a working setup and be strictly worse than
+ * the silence being replaced. Every fix in review has closed a false-reject;
+ * this one would trade a small class of false-accepts for the risk of new
+ * false-rejects by emulating two kernels' exec semantics, which is not a
+ * trade a diagnostic helper should make.
+ *
+ * ⚠️ QUOTED VALUES CONTAIN SPACES. `env -S NODE_OPTIONS="--require /tmp/h.js"
+ * node` is a valid, spawnable shebang; splitting it on whitespace picks
+ * `/tmp/h.js"` as the command and declares a working agent broken. Rejecting
+ * something that works is a worse outcome than the silence this file replaces,
+ * so quotes and backslash escapes are honoured. (codex P2.)
+ */
+export function tokenizeShebang(tail) {
+    const out = [];
+    let cur = '';
+    let quote = null;
+    let started = false;
+    for (let i = 0; i < tail.length; i++) {
+        const c = tail[i];
+        if (c === '\\' && quote !== "'" && i + 1 < tail.length) {
+            cur += tail[++i];
+            started = true;
+            continue;
+        }
+        if (quote) {
+            if (c === quote)
+                quote = null;
+            else
+                cur += c;
+            started = true;
+            continue;
+        }
+        if (c === '"' || c === "'") {
+            quote = c;
+            started = true;
+            continue;
+        }
+        if (/\s/.test(c)) {
+            if (started) {
+                out.push(cur);
+                cur = '';
+                started = false;
+            }
+            continue;
+        }
+        cur += c;
+        started = true;
+    }
+    if (started)
+        out.push(cur);
+    return out;
+}
+/**
+ * The command `env` will run, AND the environment it will run it in.
+ *
+ * ⚠️ BOTH HALVES MATTER. `env` constructs the environment first and resolves
+ * the command second, so `#!/usr/bin/env PATH=/opt/runtime/bin node` looks for
+ * `node` in `/opt/runtime/bin` — not wherever the daemon's own PATH points.
+ * Resolving against the daemon's PATH would reject a spawnable agent whose
+ * runtime lives only in the assigned path, and accept one that will fail the
+ * moment env replaces PATH. (codex P2.)
+ *
+ * ⚠️ The command is NOT "the first token without a leading dash". Every one of
+ * these is valid and its command is `node`, and that naive rule picks the
+ * wrong token in three:
+ *
+ *   env node                              -> node
+ *   env -S node --flag                    -> node   (-S splits the rest)
+ *   env -u NODE_OPTIONS node              -> node   (-u CONSUMES an operand)
+ *   env NODE_ENV=production node          -> node   (NAME=VALUE assignment)
+ *   env PATH=/opt/runtime/bin node        -> node, looked up in /opt/runtime/bin
+ */
+export function envInvocation(args, base) {
+    const TAKES_OPERAND = new Set(['-u', '--unset', '-C', '--chdir']);
+    let env = { ...base };
+    let i = 0;
+    while (i < args.length) {
+        const a = args[i];
+        if (a === '--') {
+            i += 1;
+            break;
+        }
+        // `-i` starts from an EMPTY environment, which means no PATH at all — the
+        // delegated lookup then has nothing to search, and saying so is more use
+        // than guessing.
+        if (a === '-i' || a === '--ignore-environment' || a === '-') {
+            env = {};
+            i += 1;
+            continue;
+        }
+        if (a === '-u' || a === '--unset') {
+            if (args[i + 1])
+                delete env[args[i + 1]];
+            i += 2;
+            continue;
+        }
+        if (a.startsWith('-u') && a.length > 2) {
+            delete env[a.slice(2)];
+            i += 1;
+            continue;
+        }
+        if (TAKES_OPERAND.has(a)) {
+            i += 2;
+            continue;
+        }
+        if (a.startsWith('-')) {
+            i += 1;
+            continue;
+        }
+        const assignment = /^([A-Za-z_][A-Za-z0-9_]*)=([\s\S]*)$/.exec(a);
+        if (assignment) {
+            env[assignment[1]] = assignment[2];
+            i += 1;
+            continue;
+        }
+        return { command: a, env };
+    }
+    return { command: args[i], env };
+}
+/** A found binary, unless its shebang interpreter is the thing that is missing. */
+function withInterpreter(found, env, io, depth) {
+    const interp = checkInterpreter(found, env, io, depth);
+    if (interp.ok)
+        return { ok: true, path: found };
+    if ('nested' in interp)
+        return { ok: false, reason: 'bad-interpreter', message: interp.nested };
+    return {
+        ok: false,
+        reason: 'bad-interpreter',
+        message: `\`${found}\` exists and is executable, but it is a script whose interpreter\n`
+            + `  \`${interp.interpreter}\` cannot be found. The spawn fails with a "not found" error that\n`
+            + `  names the SCRIPT rather than the missing interpreter, which is why this looks like\n`
+            + `  the agent is missing when it plainly is not.\n`
+            + `  Reinstall the agent against a current runtime, or point yolo-bridge at another copy\n`
+            + `  with \`--agent /full/path\` (or YOLOBRIDGE_AGENT_BIN).`,
+    };
+}
 function isExecutableFile(p, io) {
     try {
         if (!io.statSync(p).isFile())
@@ -49,7 +288,7 @@ function isExecutableFile(p, io) {
  * `posix_spawnp failed.`, so it names the binary, says where the search
  * looked, and gives the two ways out.
  */
-export function resolveAgentBinary(bin, env = process.env, io = DEFAULT_FS) {
+export function resolveAgentBinary(bin, env = process.env, io = DEFAULT_FS, depth = 0) {
     const escapeHatch = `Point yolo-bridge at it explicitly with \`--agent /full/path/to/${bin}\` `
         + `(or set YOLOBRIDGE_AGENT_BIN).`;
     // An explicit path is taken at its word — no PATH search, same as execve.
@@ -57,7 +296,7 @@ export function resolveAgentBinary(bin, env = process.env, io = DEFAULT_FS) {
         const abs = path.resolve(bin);
         const state = isExecutableFile(abs, io);
         if (state === 'yes')
-            return { ok: true, path: abs };
+            return withInterpreter(abs, env, io, depth);
         if (state === 'not-executable') {
             return {
                 ok: false,
@@ -81,7 +320,7 @@ export function resolveAgentBinary(bin, env = process.env, io = DEFAULT_FS) {
         const candidate = path.join(dir, bin);
         const state = isExecutableFile(candidate, io);
         if (state === 'yes')
-            return { ok: true, path: candidate };
+            return withInterpreter(candidate, env, io, depth);
         if (state === 'not-executable' && !sawNonExecutable)
             sawNonExecutable = candidate;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yolo-labs/yolobridge",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "description": "YoloBridge \u2014 local coding-agent daemon that attaches a user's own Claude Code/Codex session to a YOLO Studio workspace as a first-class tile (docs/YOLOBRIDGE_PLAN.md, build-order Phase 5).",
   "license": "MIT",
   "type": "module",