@yolo-labs/yolobridge 0.29.0 → 0.30.0

package/dist/cli.js

@@ -35,6 +35,7 @@ import { runShare, runDeliver } from './share-cmd.js';
 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 { 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';
@@ -326,13 +327,6 @@ async function cmdAttach(args) {
         cliVersion: readOwnVersion(),
     });
     let mcpProxyHandle;
-    /**
-     * Serves terminals on 127.0.0.1 for the tile's "open terminal".
-     *
-     * ⚠️ SEPARATE FROM THE AGENT PTY. `startLocalAgent` owns the one agent
-     * session; this owns any shells the operator opens from the workspace. They
-     * share a lifetime — both die with the attach — and nothing else.
-     */
     // argv fragment pointing the spawned agent at the local MCP proxy, or
     // `[]` when MCP isn't wired in — see `agent-mcp-args.ts`. Nothing else is
     // tracked for cleanup any more: as of 2026-08-26 `attach` writes NOTHING
@@ -472,6 +466,24 @@ 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.
+                    // ⚠️ 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
+                    // remedy — which on macOS reached an operator as "failed to start
+                    // the local agent (posix_spawnp failed.)" and told them nothing
+                    // they could act on. Worse, the one fact they could see (`claude`
+                    // works when typed) argued that nothing was wrong, because a shell
+                    // alias or function resolves interactively and cannot be spawned.
+                    // This does not change WHETHER the attach fails — only whether the
+                    // operator can tell why.
+                    const resolvedBinary = resolveAgentBinary(agentBin ?? DEFAULT_AGENT_BIN, process.env);
+                    if (!resolvedBinary.ok) {
+                        process.stdout.write(`yolo-bridge: cannot start the agent — ${resolvedBinary.message}\n`);
+                        process.stdout.write('yolo-bridge: detaching...\n');
+                        stopRequested = true;
+                        await runDetach({ commonApiBaseUrl: apiUrl() }).catch(() => undefined);
+                        return;
+                    }
                     process.stdout.write('yolo-bridge: Ctrl+C goes to the agent · Ctrl-P Ctrl-Q to detach\n');
                     startLocalAgent({
                         agentBin,

package/dist/resolve-agent-binary.js

@@ -0,0 +1,105 @@
+/**
+ * Can the agent binary actually be spawned, and if not, WHY?
+ *
+ * ⚠️ THE FAILURE THIS EXISTS FOR. node-pty reports an unspawnable binary as
+ * the literal string `posix_spawnp failed.` — no binary name, no PATH, no
+ * errno, no remedy. On macOS that surfaced as:
+ *
+ *     yolo-bridge: failed to start the local agent (posix_spawnp failed.), detaching...
+ *
+ * which is true, useless, and indistinguishable from half a dozen unrelated
+ * causes. The operator cannot tell whether the agent is missing, installed but
+ * not executable, or whether `attach` even looked in the right place — and the
+ * one thing they CAN see (`claude` works when they type it) argues that
+ * nothing is wrong.
+ *
+ * ⚠️ THE MACOS TRAP THIS NAMES EXPLICITLY. `claude` working in the operator's
+ * terminal does NOT mean there is a binary to spawn: a shell alias or function
+ * from `.zshrc` resolves interactively and does not exist as a file, so
+ * `posix_spawnp` cannot find it however correct the PATH looks. A message that
+ * only says "not found" invites the reply "but it IS installed", so this says
+ * where it looked and offers the escape hatch.
+ *
+ * Resolution mirrors `posix_spawnp`: a name containing a separator is a path,
+ * anything else is searched across PATH in order.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const DEFAULT_FS = fs;
+function isExecutableFile(p, io) {
+    try {
+        if (!io.statSync(p).isFile())
+            return 'no';
+    }
+    catch {
+        return 'no';
+    }
+    try {
+        io.accessSync(p, io.constants.X_OK);
+        return 'yes';
+    }
+    catch {
+        return 'not-executable';
+    }
+}
+/**
+ * Where `bin` would be spawned from, or a sentence explaining why it cannot be.
+ *
+ * The message is the whole point: it is what the operator reads instead of
+ * `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) {
+    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.
+    if (bin.includes(path.sep) || bin.includes('/')) {
+        const abs = path.resolve(bin);
+        const state = isExecutableFile(abs, io);
+        if (state === 'yes')
+            return { ok: true, path: abs };
+        if (state === 'not-executable') {
+            return {
+                ok: false,
+                reason: 'not-executable',
+                message: `The agent at ${abs} exists but is not executable. \`chmod +x ${abs}\` and re-attach.`,
+            };
+        }
+        return { ok: false, reason: 'not-found', message: `No agent binary at ${abs}. ${escapeHatch}` };
+    }
+    const rawPath = env.PATH ?? '';
+    if (!rawPath.trim()) {
+        return {
+            ok: false,
+            reason: 'no-path',
+            message: `Cannot look for \`${bin}\`: PATH is empty in this process. ${escapeHatch}`,
+        };
+    }
+    const dirs = rawPath.split(path.delimiter).filter(Boolean);
+    let sawNonExecutable;
+    for (const dir of dirs) {
+        const candidate = path.join(dir, bin);
+        const state = isExecutableFile(candidate, io);
+        if (state === 'yes')
+            return { ok: true, path: candidate };
+        if (state === 'not-executable' && !sawNonExecutable)
+            sawNonExecutable = candidate;
+    }
+    if (sawNonExecutable) {
+        return {
+            ok: false,
+            reason: 'not-executable',
+            message: `Found \`${bin}\` at ${sawNonExecutable}, but it is not executable. `
+                + `\`chmod +x ${sawNonExecutable}\` and re-attach.`,
+        };
+    }
+    return {
+        ok: false,
+        reason: 'not-found',
+        message: `\`${bin}\` is not on this process's PATH (searched ${dirs.length} `
+            + `${dirs.length === 1 ? 'directory' : 'directories'}).\n`
+            + `  ⚠️ If \`${bin}\` works when you type it, it may be a shell alias or function rather than\n`
+            + `     a real binary — those cannot be spawned. Check with: type -a ${bin}\n`
+            + `  ${escapeHatch}`,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yolo-labs/yolobridge",
-  "version": "0.29.0",
+  "version": "0.30.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",