@phnx-labs/agents-cli 1.20.71 → 1.20.73

package/dist/lib/channels/registry.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Channel-provider registry for `agents send` / `agents notify`.
+ *
+ * One primitive, many channels. A provider knows how to deliver a message over
+ * exactly one channel — the agent mailbox, a rush-daemon gateway (telegram /
+ * imessage / slack / discord), openclaw, or a future "app". Providers register
+ * themselves at module load; the command layer only ever calls
+ * `resolveChannelProvider(name).send(...)` — no channel is special-cased above
+ * this seam, so new channels (apps) slot in without touching the command.
+ */
+export interface SendOptions {
+    /** Channel-specific recipient id: a chat id, a mailbox/agent id, a Slack C0…, etc. */
+    target: string;
+    /** Channel thread id / timestamp (slack/telegram threads). */
+    thread?: string;
+    /** Absolute paths to file attachments. */
+    attachments?: string[];
+    /** Sender label (used by the mailbox provider). */
+    from?: string;
+    /** Resolve + build the delivery but do not actually send. */
+    dryRun?: boolean;
+}
+export interface SendResult {
+    ok: boolean;
+    /** Channel/provider name as surfaced back to the caller. */
+    channel: string;
+    /** Resolved recipient id, echoed for --json parity with `rush send`. */
+    id: string;
+    error?: string;
+    /** Echoed attachment paths (rush shape parity). */
+    attachments?: string[];
+    /** Mailbox provider returns the enqueued message id. */
+    msgId?: string;
+}
+export interface ChannelProvider {
+    /** Stable name used in `--channel` and as a `notify.transports` value. */
+    name: string;
+    send(text: string, opts: SendOptions): Promise<SendResult>;
+}
+export declare function registerChannelProvider(p: ChannelProvider): void;
+export declare function resolveChannelProvider(name: string): ChannelProvider | undefined;
+export declare function listChannelProviders(): string[];

package/dist/lib/channels/registry.js

@@ -0,0 +1,20 @@
+/**
+ * Channel-provider registry for `agents send` / `agents notify`.
+ *
+ * One primitive, many channels. A provider knows how to deliver a message over
+ * exactly one channel — the agent mailbox, a rush-daemon gateway (telegram /
+ * imessage / slack / discord), openclaw, or a future "app". Providers register
+ * themselves at module load; the command layer only ever calls
+ * `resolveChannelProvider(name).send(...)` — no channel is special-cased above
+ * this seam, so new channels (apps) slot in without touching the command.
+ */
+const REGISTRY = new Map();
+export function registerChannelProvider(p) {
+    REGISTRY.set(p.name, p);
+}
+export function resolveChannelProvider(name) {
+    return REGISTRY.get(name);
+}
+export function listChannelProviders() {
+    return [...REGISTRY.keys()].sort();
+}

package/dist/lib/channels/resolve.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Transport resolution: map a user-facing channel name to the provider that
+ * actually delivers it, using `notify.transports` from agents.yaml.
+ *
+ * Default is name-identity (`--channel slack` -> `slack` provider) — NOT a
+ * fallback to a different transport. Only telegram is dual-homed (rush vs
+ * openclaw-telegram); config picks. An unmapped-to-unregistered name dies loud.
+ */
+import type { Meta } from '../types.js';
+import { type ChannelProvider } from './registry.js';
+export declare function resolveTransport(channel: string, meta: Meta): ChannelProvider;

package/dist/lib/channels/resolve.js

@@ -0,0 +1,12 @@
+import { die } from '../format.js';
+import { resolveChannelProvider, listChannelProviders } from './registry.js';
+export function resolveTransport(channel, meta) {
+    const providerName = meta.notify?.transports?.[channel] ?? channel;
+    const provider = resolveChannelProvider(providerName);
+    if (!provider) {
+        die(`No channel provider '${providerName}'` +
+            (providerName === channel ? '' : ` (mapped from channel '${channel}' via notify.transports)`) +
+            `. Registered: ${listChannelProviders().join(', ')}.`);
+    }
+    return provider;
+}

package/dist/lib/cli-resources.d.ts

@@ -110,6 +110,24 @@ export interface InstallResult {
     /** Set when the install runner threw or exited non-zero. */
     error?: string;
 }
+/**
+ * Resolve the directory a `binary` install method downloads/extracts into.
+ *
+ * `/usr/local/bin` used to be hardcoded here, which fails on Apple Silicon
+ * Macs where that directory is root-owned and not user-writable (Homebrew
+ * moved on to /opt/homebrew but left /usr/local/bin behind). Resolution
+ * order:
+ *  1. `AGENTS_CLI_BIN_DIR` — explicit override, used as-is when set.
+ *  2. `~/.local/bin` — the XDG user-bin dir already used for shims (see
+ *     posixpath.ts / shims.ts); created with mkdir -p if missing.
+ *  3. `/usr/local/bin` — last resort, for hosts where it's still writable.
+ *     When it isn't either, throw an actionable error naming the env var and
+ *     ~/.local/bin instead of letting curl/tar fail with a bare EACCES.
+ *
+ * Called once per install/dry-run so the same directory is used everywhere
+ * that method is described or executed.
+ */
+export declare function resolveBinDir(): string;
 /**
  * Display-only rendering of how a method would be run, for `--dry-run` and
  * status output. Not used by installCli — execution goes through runInstallMethod

package/dist/lib/cli-resources.js

@@ -22,6 +22,7 @@ import { spawnSync } from 'child_process';
 import * as yaml from 'yaml';
 import { listResources, resolveResource } from './resources.js';
 import { composeWin32CommandLine } from './platform/index.js';
+import { localBinDir } from './platform/posixpath.js';
 // ─── Validation primitives ───────────────────────────────────────────────────
 /** Token allowed inside `check:` strings — letters, digits, underscore, dot, slash, dash. */
 const SAFE_CHECK_TOKEN = /^[a-zA-Z0-9_./-]+$/;
@@ -340,6 +341,52 @@ export function describeMethod(method) {
     const spec = method.binary[key];
     return spec ? `download ${spec.url}` : 'binary download';
 }
+/** Env var that overrides where `binary` installs write their downloaded file(s). */
+const BIN_DIR_ENV = 'AGENTS_CLI_BIN_DIR';
+/** Historical default install dir — kept only as a last-resort fallback. */
+const LEGACY_BIN_DIR = '/usr/local/bin';
+function isWritableDir(dir, opts) {
+    try {
+        if (opts.create)
+            fs.mkdirSync(dir, { recursive: true });
+        fs.accessSync(dir, fs.constants.W_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve the directory a `binary` install method downloads/extracts into.
+ *
+ * `/usr/local/bin` used to be hardcoded here, which fails on Apple Silicon
+ * Macs where that directory is root-owned and not user-writable (Homebrew
+ * moved on to /opt/homebrew but left /usr/local/bin behind). Resolution
+ * order:
+ *  1. `AGENTS_CLI_BIN_DIR` — explicit override, used as-is when set.
+ *  2. `~/.local/bin` — the XDG user-bin dir already used for shims (see
+ *     posixpath.ts / shims.ts); created with mkdir -p if missing.
+ *  3. `/usr/local/bin` — last resort, for hosts where it's still writable.
+ *     When it isn't either, throw an actionable error naming the env var and
+ *     ~/.local/bin instead of letting curl/tar fail with a bare EACCES.
+ *
+ * Called once per install/dry-run so the same directory is used everywhere
+ * that method is described or executed.
+ */
+export function resolveBinDir() {
+    const override = process.env[BIN_DIR_ENV];
+    if (override && override.trim())
+        return override.trim();
+    const local = localBinDir();
+    if (isWritableDir(local, { create: true }))
+        return local;
+    if (isWritableDir(LEGACY_BIN_DIR, { create: false }))
+        return LEGACY_BIN_DIR;
+    throw new Error(`${LEGACY_BIN_DIR} is not writable (EACCES) and ~/.local/bin could not be created or ` +
+        `written to either. Set ${BIN_DIR_ENV} to a writable directory, e.g.:\n` +
+        `  export ${BIN_DIR_ENV}="$HOME/.local/bin"\n` +
+        `then re-run the install.`);
+}
 /**
  * Display-only rendering of how a method would be run, for `--dry-run` and
  * status output. Not used by installCli — execution goes through runInstallMethod
@@ -359,9 +406,10 @@ export function buildInstallCommand(method) {
     const spec = method.binary[key];
     if (!spec)
         return 'binary download';
+    const binDir = resolveBinDir();
     return spec.extract
-        ? `curl -fsSL ${spec.url} -o /tmp/agents-cli-bin.tgz && tar -xzf /tmp/agents-cli-bin.tgz -C /usr/local/bin ${spec.extract}`
-        : `curl -fsSL ${spec.url} -o /usr/local/bin/agents-cli-downloaded`;
+        ? `curl -fsSL ${spec.url} -o /tmp/agents-cli-bin.tgz && tar -xzf /tmp/agents-cli-bin.tgz -C ${binDir} ${spec.extract}`
+        : `curl -fsSL ${spec.url} -o ${path.join(binDir, 'agents-cli-downloaded')}`;
 }
 /**
  * Execute an install method via spawnSync with argv arrays. Each branch
@@ -425,6 +473,7 @@ function runInstallMethod(method) {
         if (!spec)
             throw new Error(`no binary declared for ${key}`);
         assertHttpsUrl(spec.url);
+        const binDir = resolveBinDir();
         if (spec.extract) {
             assertSafePathSegment(spec.extract);
             const tmp = path.join(os.tmpdir(), `agents-cli-bin-${process.pid}-${Date.now()}.tgz`);
@@ -433,7 +482,7 @@ function runInstallMethod(method) {
                 if (dl.status !== 0) {
                     throw new Error(`binary download failed (status ${dl.status ?? 'unknown'})`);
                 }
-                const x = spawnSync('tar', ['-xzf', tmp, '-C', '/usr/local/bin', spec.extract], {
+                const x = spawnSync('tar', ['-xzf', tmp, '-C', binDir, spec.extract], {
                     stdio: 'inherit',
                 });
                 if (x.status !== 0) {
@@ -448,7 +497,7 @@ function runInstallMethod(method) {
             }
         }
         else {
-            const r = spawnSync('curl', ['-fsSL', spec.url, '-o', '/usr/local/bin/agents-cli-downloaded'], { stdio: 'inherit' });
+            const r = spawnSync('curl', ['-fsSL', spec.url, '-o', path.join(binDir, 'agents-cli-downloaded')], { stdio: 'inherit' });
             if (r.status !== 0) {
                 throw new Error(`binary download failed (status ${r.status ?? 'unknown'})`);
             }

package/dist/lib/cloud/codex.js

@@ -30,12 +30,15 @@ function codexAvailable() {
     return findCodexBinary() !== null;
 }
 /** Spawn the codex CLI with the given arguments and capture its output. */
-function runCodex(args) {
+function runCodex(args, env) {
     const bin = findCodexBinary();
     if (!bin)
         return Promise.resolve({ stdout: '', stderr: 'codex not found', code: 127 });
     return new Promise((resolve) => {
-        const proc = spawn(bin, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+        const proc = spawn(bin, args, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: env ? { ...process.env, ...env } : process.env,
+        });
         let stdout = '';
         let stderr = '';
         proc.stdout.on('data', (d) => { stdout += d.toString(); });
@@ -120,7 +123,7 @@ export class CodexCloudProvider {
         if (options.branch)
             args.push('--branch', options.branch);
         args.push(options.prompt);
-        const { stdout, stderr, code } = await runCodex(args);
+        const { stdout, stderr, code } = await runCodex(args, options.env);
         if (code !== 0) {
             throw new Error(`codex cloud exec failed: ${stderr || stdout}`);
         }

package/dist/lib/cloud/factory.d.ts

@@ -53,6 +53,7 @@ export declare function buildSshArgs(computer: string, remoteBin: string, remote
     droidBin: string;
     user: string;
     port?: string;
+    env?: Record<string, string>;
 }): string[];
 /** Map a droid stream-json `result.subtype` / `is_error` to a CloudTaskStatus. */
 export declare function mapResultStatus(line: {

package/dist/lib/cloud/factory.js

@@ -22,6 +22,7 @@
 import { spawn, execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
+import { controlOpts, sshConnectOpts } from '../ssh-exec.js';
 import { MissingTargetError } from './types.js';
 import { getShimsDir } from '../state.js';
 const SHIMS_DIR = getShimsDir();
@@ -105,11 +106,16 @@ export function buildExecArgs(prompt, opts) {
  * shell-quoted into a single remote command string.
  */
 export function buildSshArgs(computer, remoteBin, remoteArgv, opts) {
-    const remoteCmd = [remoteBin, ...remoteArgv].map(shellQuote).join(' ');
+    const envPrefix = Object.entries(opts.env ?? {}).map(([key, value]) => {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+            throw new Error(`Invalid runtime env key for Factory dispatch: ${key}`);
+        }
+        return `${key}=${shellQuote(value)}`;
+    });
+    const remoteCmd = [...envPrefix, remoteBin, ...remoteArgv].map((part, idx) => idx < envPrefix.length ? part : shellQuote(part)).join(' ');
     const proxy = `ProxyCommand=${opts.droidBin} computer ssh ${computer} --proxy --port %p`;
     return [
-        '-o', proxy,
-        '-o', 'StrictHostKeyChecking=accept-new',
+        ...sshConnectOpts(controlOpts(), ['-o', proxy]),
         '-p', opts.port ?? '22',
         `${opts.user}@${computer}`,
         remoteCmd,
@@ -247,7 +253,7 @@ export class FactoryCloudProvider {
         const autonomy = resolveAutonomy(options.providerOptions?.autonomy ?? options.providerOptions?.mode, this.defaultAutonomy);
         const user = options.providerOptions?.user ?? 'droid';
         const execArgs = buildExecArgs(options.prompt, { autonomy });
-        const sshArgs = buildSshArgs(computer, 'droid', execArgs, { droidBin, user });
+        const sshArgs = buildSshArgs(computer, 'droid', execArgs, { droidBin, user, env: options.env });
         const { events, status, summary, sessionId } = await this.runRemote(sshArgs);
         const now = new Date().toISOString();
         const id = sessionId ?? `droid-${Date.now()}`;

package/dist/lib/cloud/rush.d.ts

@@ -64,7 +64,7 @@ export declare function accountTokensFingerprint(tokens: AccountTokenEntry[]): s
  * Build the POST body for /api/v1/cloud-runs. Exported so tests can verify
  * the back-compat shape (singular fields + repos[]) without needing real
  * GitHub installations or a live Rush session. `findInstallation` is the
- * only other I/O and it's tested by the halo/proxy integration suite.
+ * only other I/O and it's tested by the cloud proxy integration suite.
  */
 export declare function buildDispatchBody(input: {
     agent?: string;
@@ -89,6 +89,8 @@ export declare function buildDispatchBody(input: {
      * MAX_IMAGES_PER_DISPATCH — extras are dropped, never sent. Omitted when empty.
      */
     images?: ImageAttachment[] | null;
+    /** Runtime env vars mounted into the cloud agent process. */
+    env?: Record<string, string> | null;
 }): Record<string, unknown>;
 export declare class RushCloudProvider implements CloudProvider {
     id: "rush";

package/dist/lib/cloud/rush.js

@@ -255,7 +255,7 @@ export function accountTokensFingerprint(tokens) {
  * Build the POST body for /api/v1/cloud-runs. Exported so tests can verify
  * the back-compat shape (singular fields + repos[]) without needing real
  * GitHub installations or a live Rush session. `findInstallation` is the
- * only other I/O and it's tested by the halo/proxy integration suite.
+ * only other I/O and it's tested by the cloud proxy integration suite.
  */
 export function buildDispatchBody(input) {
     if (input.resolvedRepos.length === 0) {
@@ -286,6 +286,9 @@ export function buildDispatchBody(input) {
     if (input.images && input.images.length > 0) {
         body.images = input.images.slice(0, MAX_IMAGES_PER_DISPATCH);
     }
+    if (input.env && Object.keys(input.env).length > 0) {
+        body.env = input.env;
+    }
     return body;
 }
 export class RushCloudProvider {
@@ -358,6 +361,7 @@ export class RushCloudProvider {
             strategy,
             skills: options.skills,
             images: options.images,
+            env: options.env,
         });
         let res = await api('POST', '/api/v1/cloud-runs', token, body);
         // Server detects drift (new account or rotated token) by comparing the
@@ -402,6 +406,7 @@ export class RushCloudProvider {
                     accountTokens,
                     skills: options.skills,
                     images: options.images,
+                    env: options.env,
                 });
                 res = await api('POST', '/api/v1/cloud-runs', token, retryBody);
                 // Persist consent on first successful upload so we don't re-prompt

package/dist/lib/cloud/types.d.ts

@@ -181,6 +181,8 @@ export interface DispatchOptions {
     images?: ImageAttachment[];
     /** Provider-specific options (e.g., codex env ID, factory computer name). */
     providerOptions?: Record<string, unknown>;
+    /** Runtime env vars to inject into the remote agent process when the provider supports it. */
+    env?: Record<string, string>;
 }
 /**
  * Collapse `repo` + `repos` into a single deduped list. Exported so callers,

package/dist/lib/codex-home.d.ts

@@ -0,0 +1,35 @@
+/** macOS Unix-domain socket path cap: `sizeof(sockaddr_un.sun_path)` in <sys/un.h>. */
+export declare const SUN_LEN = 104;
+/** Suffix codex appends to CODEX_HOME to reach its app-server control socket. */
+export declare const CODEX_CONTROL_SOCKET_SUFFIX = "/app-server-control/app-server-control.sock";
+/**
+ * True when this CODEX_HOME's derived control-socket path would overflow
+ * SUN_LEN on macOS.
+ */
+export declare function codexHomeOverflowsSunLen(home: string): boolean;
+/**
+ * The short, per-version codex home used when the versioned home overflows.
+ * `~/.agents/.codex-homes/<version>/.codex` keeps the socket path well under
+ * SUN_LEN while staying stable across reboots (unlike $TMPDIR) and per-version
+ * isolated.
+ */
+export declare function shortCodexHome(agentsUserDir: string, version: string): string;
+/**
+ * Resolve a macOS SUN_LEN-safe CODEX_HOME for the given versioned home,
+ * migrating the home to a short real path (once, idempotently) when needed.
+ *
+ * On non-darwin platforms, or when the versioned home already fits, the
+ * versioned home is returned unchanged. If migration fails for any reason the
+ * versioned home is returned (no worse than the pre-fix behavior).
+ */
+export declare function resolveCodexHome(versionedHome: string, agentsUserDir: string, version: string, platform?: NodeJS.Platform): string;
+/**
+ * Emit the bash block that a generated codex shim uses to export a
+ * SUN_LEN-safe CODEX_HOME. Mirrors {@link resolveCodexHome}.
+ *
+ * @param homeExpr      shell expression for the versioned codex home
+ *                      (e.g. `$VERSION_DIR/home/.codex`)
+ * @param shortBaseExpr shell expression for the per-version short base dir
+ *                      (e.g. `$AGENTS_USER_DIR/.codex-homes/$VERSION`)
+ */
+export declare function codexHomeShimBash(homeExpr: string, shortBaseExpr: string): string;

package/dist/lib/codex-home.js

@@ -0,0 +1,136 @@
+/**
+ * macOS SUN_LEN-safe CODEX_HOME resolution.
+ *
+ * Codex reads its config (approval_policy, sandbox_mode, MCP servers, rules)
+ * from CODEX_HOME and, for its app-server daemon, binds a Unix-domain control
+ * socket at `$CODEX_HOME/app-server-control/app-server-control.sock`. macOS
+ * caps Unix socket paths at 104 bytes (SUN_LEN — `sizeof(sockaddr_un.sun_path)`
+ * in `<sys/un.h>`). agents-cli points CODEX_HOME at the deep versioned home
+ * (`~/.agents/.history/versions/codex/<version>/home/.codex`), which for a
+ * typical user is long enough that the derived socket path exceeds 104 bytes.
+ * `codex app-server daemon start` then fails with `path must be shorter than
+ * SUN_LEN`, and every codex spawn on macOS dies (this took down all OpenClaw
+ * agents on mac-mini — RUSH-1866).
+ *
+ * Codex exposes no socket-path override and resolves symlinks before binding,
+ * so a short symlink pointing at the deep home does NOT help (the socket lives
+ * at the resolved target). The only fix is to make the *real* CODEX_HOME short.
+ * On macOS, when the versioned home's socket path would overflow, we relocate
+ * the home once to a short real directory under `~/.agents/.codex-homes/` and
+ * leave a symlink behind at the versioned path, then point CODEX_HOME at the
+ * short real path. Config, auth, and state migrate intact; there is no socket
+ * or sqlite fragmentation because a single physical home simply moves.
+ *
+ * This module is the single source of truth for that logic. `exec.ts` calls
+ * the TS resolver for `agents run`/`agents exec`; `shims.ts` emits the bash
+ * equivalent (`codexHomeShimBash`) into the generated codex shims. Keep the two
+ * in lockstep.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+/** macOS Unix-domain socket path cap: `sizeof(sockaddr_un.sun_path)` in <sys/un.h>. */
+export const SUN_LEN = 104;
+/** Suffix codex appends to CODEX_HOME to reach its app-server control socket. */
+export const CODEX_CONTROL_SOCKET_SUFFIX = '/app-server-control/app-server-control.sock';
+/**
+ * True when this CODEX_HOME's derived control-socket path would overflow
+ * SUN_LEN on macOS.
+ */
+export function codexHomeOverflowsSunLen(home) {
+    return home.length + CODEX_CONTROL_SOCKET_SUFFIX.length > SUN_LEN;
+}
+/**
+ * The short, per-version codex home used when the versioned home overflows.
+ * `~/.agents/.codex-homes/<version>/.codex` keeps the socket path well under
+ * SUN_LEN while staying stable across reboots (unlike $TMPDIR) and per-version
+ * isolated.
+ */
+export function shortCodexHome(agentsUserDir, version) {
+    return path.join(agentsUserDir, '.codex-homes', version, '.codex');
+}
+/**
+ * Resolve a macOS SUN_LEN-safe CODEX_HOME for the given versioned home,
+ * migrating the home to a short real path (once, idempotently) when needed.
+ *
+ * On non-darwin platforms, or when the versioned home already fits, the
+ * versioned home is returned unchanged. If migration fails for any reason the
+ * versioned home is returned (no worse than the pre-fix behavior).
+ */
+export function resolveCodexHome(versionedHome, agentsUserDir, version, platform = process.platform) {
+    if (platform !== 'darwin')
+        return versionedHome;
+    if (!codexHomeOverflowsSunLen(versionedHome))
+        return versionedHome;
+    const short = shortCodexHome(agentsUserDir, version);
+    try {
+        if (!fs.existsSync(short)) {
+            fs.mkdirSync(path.dirname(short), { recursive: true });
+            const st = fs.lstatSync(versionedHome, { throwIfNoEntry: false });
+            if (st && st.isDirectory() && !st.isSymbolicLink()) {
+                // Migrate the existing deep home so config/auth/state stay intact,
+                // then leave a symlink so anything referencing the versioned path
+                // still resolves.
+                fs.renameSync(versionedHome, short);
+                fs.symlinkSync(short, versionedHome);
+            }
+            else if (!st) {
+                // Fresh install: create the short home and link the versioned path to it.
+                fs.mkdirSync(short, { recursive: true });
+                fs.symlinkSync(short, versionedHome);
+            }
+            // If versionedHome is already a symlink (migrated by a prior run or the
+            // shim), leave it; `short` will be populated below.
+        }
+    }
+    catch {
+        // Migration lost a race or hit a permission error. Fall back to the
+        // versioned home rather than crash the invocation.
+        if (!fs.existsSync(short))
+            return versionedHome;
+    }
+    return fs.existsSync(short) ? short : versionedHome;
+}
+/**
+ * Emit the bash block that a generated codex shim uses to export a
+ * SUN_LEN-safe CODEX_HOME. Mirrors {@link resolveCodexHome}.
+ *
+ * @param homeExpr      shell expression for the versioned codex home
+ *                      (e.g. `$VERSION_DIR/home/.codex`)
+ * @param shortBaseExpr shell expression for the per-version short base dir
+ *                      (e.g. `$AGENTS_USER_DIR/.codex-homes/$VERSION`)
+ */
+export function codexHomeShimBash(homeExpr, shortBaseExpr) {
+    return `
+# Codex reads its config (approval_policy, sandbox_mode, MCP servers, rules)
+# from CODEX_HOME and binds a Unix control socket at
+# "\$CODEX_HOME/app-server-control/app-server-control.sock" for its app-server
+# daemon. macOS caps Unix socket paths at 104 bytes (SUN_LEN); the deep
+# versioned home overflows, so "codex app-server daemon start" fails with
+# "path must be shorter than SUN_LEN" and every codex spawn dies (RUSH-1866).
+# Codex has no socket-path override and resolves symlinks before binding, so a
+# short symlink to the deep home does NOT help. On macOS, when the derived
+# socket path would overflow, relocate the home once to a short real dir and
+# leave a symlink behind, then point CODEX_HOME at the short real path. A
+# caller-provided CODEX_HOME always wins.
+if [ -z "\${CODEX_HOME:-}" ]; then
+  CODEX_HOME="${homeExpr}"
+  # 43 = length of "/app-server-control/app-server-control.sock"; 104 = SUN_LEN.
+  if [ "\$(uname -s)" = "Darwin" ] && [ "\$(( \${#CODEX_HOME} + 43 ))" -gt 104 ]; then
+    _codex_short="${shortBaseExpr}/.codex"
+    if [ ! -e "\$_codex_short" ]; then
+      mkdir -p "${shortBaseExpr}"
+      if [ -d "\$CODEX_HOME" ] && [ ! -L "\$CODEX_HOME" ]; then
+        if mv "\$CODEX_HOME" "\$_codex_short" 2>/dev/null; then
+          ln -snf "\$_codex_short" "\$CODEX_HOME"
+        fi
+      elif [ ! -e "\$CODEX_HOME" ]; then
+        mkdir -p "\$_codex_short"
+        ln -snf "\$_codex_short" "\$CODEX_HOME"
+      fi
+    fi
+    [ -d "\$_codex_short" ] && CODEX_HOME="\$_codex_short"
+  fi
+fi
+export CODEX_HOME="\$CODEX_HOME"
+`;
+}

package/dist/lib/crabbox/cli.d.ts

@@ -26,6 +26,10 @@ export interface CrabboxBox {
     state: string;
     /** Public IPv4, when the provider exposes one. */
     ip?: string;
+    /** Tailnet IPv4 (100.x), when the box was leased with `--network tailscale`. */
+    tailscaleIPv4?: string;
+    /** Tailnet MagicDNS FQDN, when the box joined the tailnet. */
+    tailscaleFQDN?: string;
     profile?: string;
     class?: string;
     /** True when running + bootstrap-complete. */
@@ -49,6 +53,13 @@ export interface CrabboxOptions {
      * `crabbox login` credentials.
      */
     secretsBundle?: string;
+    /**
+     * Hard cap (ms) on a single crabbox invocation that hits the provider API
+     * (`list`). Prevents a slow/unreachable provider from hanging an ambient
+     * command like `agents devices`. Defaults to 8s; callers on a fast/interactive
+     * path (devices list, `agents ssh` fall-through) pass a shorter bound.
+     */
+    timeoutMs?: number;
 }
 /** Locate the crabbox binary, or throw an actionable error. */
 export declare function findCrabbox(): string;
@@ -61,6 +72,17 @@ export declare function findCrabbox(): string;
 export declare const LEASE_PROVIDER_TOKEN_KEYS: string[];
 /** The first bundle that declares a provider token key, or undefined. Pure over `bundles`. */
 export declare function pickLeaseBundleFromList(bundles: SecretsBundle[]): string | undefined;
+/**
+ * Env keys a bundle may use for a Tailscale auth key. crabbox reads
+ * `CRABBOX_TAILSCALE_AUTH_KEY` to join a leased box to the tailnet; we accept the
+ * common alternate names too and rename to that canonical key on injection.
+ */
+export declare const TAILSCALE_AUTH_KEY_NAMES: string[];
+/** The first bundle + key that declares a Tailscale auth key, or undefined. Pure over `bundles`. */
+export declare function pickTailscaleBundleFromList(bundles: SecretsBundle[]): {
+    name: string;
+    key: string;
+} | undefined;
 /** A resolved lease bundle: its name, plus (auto-detect only) the exact keys to inject. */
 export interface ResolvedLeaseBundle {
     name: string;
@@ -97,6 +119,13 @@ export interface WarmupOptions extends CrabboxOptions {
     code?: boolean;
     /** Cloud backend override (crabbox provider id, e.g. hetzner/aws/do). */
     provider?: string;
+    /**
+     * Network mode for the leased box. `'public'` (default) leases with a public
+     * IP; `'tailscale'` joins the box to the tailnet (`--network tailscale`,
+     * tagged `tag:crabbox`) so it is reachable only over Tailscale. The caller
+     * (command layer) decides WHEN to enable this — F5 here is plumbing only.
+     */
+    netMode?: 'public' | 'tailscale';
 }
 /**
  * Lease a box and block until it is ready. Returns the leased box.
@@ -137,6 +166,21 @@ export declare function crabboxRun(slug: string, remoteCmd: string, opts?: Crabb
  * Streams combined output; resolves with the remote exit code (null on dispatch failure).
  */
 export declare function crabboxRunScript(slug: string, script: string, opts?: CrabboxRunOptions): Promise<number | null>;
+/**
+ * Parse crabbox's shell-quoted `ssh` command (`'ssh' '-i' '<key>' … 'crabbox@ip'`)
+ * into an argv array. Exported for testing.
+ */
+export declare function parseCrabboxSshArgv(stdout: string): string[] | null;
+/**
+ * The concrete `ssh` argv crabbox uses to reach box `slug` — including the
+ * per-lease identity key and known_hosts crabbox provisions under its own config
+ * dir. A raw `ssh crabbox@ip` fails `publickey`; this is the only auth that works.
+ * `crabbox ssh --id` PRINTS the command (it doesn't connect — that's `crabbox
+ * connect`), and `--reclaim` makes it resolve regardless of which repo holds the
+ * lease claim (matching `crabboxRunScript`). Returns null when crabbox can't
+ * resolve the box (caller treats setup-copy / `agents ssh` as best-effort).
+ */
+export declare function crabboxSshArgv(slug: string, opts?: CrabboxOptions): string[] | null;
 /** Release the lease / delete the box. Best-effort; never throws. */
 export declare function crabboxStop(slug: string, opts?: CrabboxOptions): boolean;
 /** Never reap a box touched within this many seconds, regardless of idle-timeout. */