@shardflux/cli 0.22.0 → 0.23.1

package/dist/t3-proxy.d.ts

@@ -0,0 +1,81 @@
+import type { TomlTable } from 'smol-toml';
+import type { CellClient, Workspace } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+type Env = Record<string, string | undefined>;
+export interface ProxyRoute {
+    /** The proxy's base URL as the setup names it. */
+    url: string;
+    /** It points at this computer. */
+    local: boolean;
+    /** Its port (the scheme's default when the URL names none). */
+    port: number;
+}
+export interface ClaudeProxy extends ProxyRoute {
+    /** The `ANTHROPIC_*` variables (and `API_TIMEOUT_MS`) Claude Code runs with. */
+    env: Record<string, string>;
+    /** The setup brings its own credential (`ANTHROPIC_AUTH_TOKEN` or `ANTHROPIC_API_KEY`). */
+    credential: boolean;
+}
+export interface CodexProxy extends ProxyRoute {
+    /** The variables the provider names (`env_key`, `env_http_headers`), or `OPENAI_BASE_URL` and `OPENAI_API_KEY`. */
+    env: Record<string, string>;
+    /** `model_provider` and its `model_providers.<id>` table; null when `OPENAI_BASE_URL` names the proxy. */
+    config: TomlTable | null;
+}
+export interface T3ProxySetup {
+    claude: ClaudeProxy | null;
+    codex: CodexProxy | null;
+}
+export interface ProxyReadOptions {
+    env: Env;
+    /** A file's text, null when it is missing or unreadable (tests replace it). */
+    read?: (path: string) => string | null;
+}
+/** A URL whose host is this computer: 127.0.0.0/8, localhost, ::1 (and 0.0.0.0, which a local listener answers on). */
+export declare function onThisComputer(url: string): boolean;
+/** The proxy each app of T3 Code's own providers uses on this computer (null: it talks to its provider directly). */
+export declare function readT3ProxySetup(opts: ProxyReadOptions): T3ProxySetup;
+export interface VmProxy {
+    /** Variables for each app's agent in the VM, with proxy URLs as the VM reaches them. */
+    env: {
+        claude: Record<string, string>;
+        codex: Record<string, string>;
+    };
+    /** Keys for the VM's ~/.codex/config.toml (null: it stays as it is). */
+    codexConfig: TomlTable | null;
+    /** The VM forwarder's hub info, when a proxy on this computer is reached through the hosted CLIProxyAPI. */
+    hubInfo: string | null;
+    /** Claude Code goes through the proxy with the setup's own credential: no Shardflux Claude sign-in is needed. */
+    claudeCredential: boolean;
+    /** Apps whose proxy only this computer reaches: their VM agents use Shardflux's sign-ins. */
+    unreachable: Array<'claude' | 'codex'>;
+    /** Of those, the apps whose proxy is a CLIProxyAPI address here: VMs reach it once it is in the account (import). */
+    importable: Array<'claude' | 'codex'>;
+}
+/** The proxy URL as a VM reaches it: one on this computer becomes the VM forwarder's address (same path). */
+export declare function vmProxyUrl(url: string): string;
+/**
+ * What a conversation VM needs to follow the setup. `hubInfo` is the account's VM hub info (vmHubInfoText), if any;
+ * `hubPorts` are the ports a CLIProxyAPI on this computer answers on (8317, and the one the import recorded).
+ */
+export declare function vmProxy(setup: T3ProxySetup, hubInfo: string | null, hubPorts?: readonly number[]): VmProxy;
+/** The T3 Code proxy setup as this account's VMs follow it (read again on every call: settings change). */
+export declare function accountVmProxy(ctx: Pick<Ctx, 'io' | 'store' | 'apiUrl' | 'addSecret'>): VmProxy;
+/**
+ * Puts what the VM's agents need in place before they start: the forwarder's hub info (0600), and the Codex provider in
+ * ~/.codex/config.toml (its other settings kept). Writes only what differs.
+ */
+export declare function prepareVmProxy(cell: Pick<CellClient, 'files'>, plan: VmProxy): Promise<void>;
+/**
+ * The VM's own T3 Code (SSH and the T3 app through T3 Connect) runs its Claude Code and Codex providers with the setup's
+ * variables, stored as T3 stores them: plain values in its settings.json, credentials in its secret store
+ * (`secrets/provider-env-<base64url instance>-<base64url name>.bin`, 0600) with `valueRedacted` in the settings. The
+ * instances' other variables and the file's other settings stay. Also places prepareVmProxy's files.
+ */
+export declare function prepareVmT3(cell: Pick<CellClient, 'files'>, plan: VmProxy): Promise<void>;
+/**
+ * Before T3 Code opens a project VM (`shard agents new|open --in t3`): its T3 Code follows the user's proxy setup. A
+ * proxy on this computer without the hosted copy is named with the import; nothing here fails the open.
+ */
+export declare function followT3ProxyInVm(ctx: Ctx, ws: Workspace): Promise<void>;
+export {};

package/dist/t3-proxy.js

@@ -0,0 +1,325 @@
+/**
+ * A T3 Code user's proxy setup (CLIProxyAPI, or any Claude- or OpenAI-compatible proxy), read the way T3 Code's own
+ * Claude Code and Codex providers run, so a Shardflux conversation in T3 Code sends its model traffic the same way
+ * (0.23.0+):
+ *
+ * - Claude Code: T3's Claude provider (its default instance `claudeAgent`, else another enabled one) runs with its
+ *   environment variables over T3's own, and Claude Code applies its settings.json `env` over both. `ANTHROPIC_BASE_URL`
+ *   names the proxy; the `ANTHROPIC_*` variables (base URL, token, models, headers) go to the VM's Claude Code.
+ * - Codex: config.toml in the provider's home (`CODEX_HOME`, default ~/.codex): a `model_provider` (the active
+ *   profile's first) with a `base_url`, else `OPENAI_BASE_URL`. The provider's table and the variables it names
+ *   (`env_key`, `env_http_headers`) go to the VM's Codex.
+ *
+ * A CLIProxyAPI on this computer (127.0.0.1, localhost or ::1 at port 8317, or the port the import recorded) is reached
+ * from VMs through the account's hosted copy (`shard cli-proxy import`), whose VM forwarder answers on
+ * http://127.0.0.1:8317. Another service on this computer stays here (the VM uses Shardflux's sign-ins); any other URL
+ * is used as written. T3 Code's default provider instance is the one followed while it is enabled.
+ * Sensitive T3 variables come from T3's secret store (`<T3 home>/userdata/secrets/*.bin`); none is ever printed.
+ */
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { parse, stringify } from 'smol-toml';
+import { ShardfluxApiError } from '@shardflux/sdk';
+import { CLI_PROXY_PORT, readHubInfo, vmHubInfoText } from "./cli-proxy-hub.js";
+import { VM_HUB_INFO_PATH } from "./cli-proxy.js";
+import { t3HomeDir } from "./t3-provider.js";
+import { AgentStateStore } from "./agent-state.js";
+const readText = (path) => { try {
+    return readFileSync(path, 'utf8');
+}
+catch {
+    return null;
+} };
+const object = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? v : {});
+const text = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null);
+const json = (t) => { try {
+    return object(JSON.parse(t ?? ''));
+}
+catch {
+    return {};
+} };
+const httpUrl = (v) => { try {
+    return ['http:', 'https:'].includes(new URL(v).protocol);
+}
+catch {
+    return false;
+} };
+const b64 = (s) => Buffer.from(s, 'utf8').toString('base64url');
+/** A URL whose host is this computer: 127.0.0.0/8, localhost, ::1 (and 0.0.0.0, which a local listener answers on). */
+export function onThisComputer(url) {
+    let host;
+    try {
+        host = new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        return false;
+    }
+    return host === 'localhost' || host.endsWith('.localhost') || host === '[::1]' || host === '0.0.0.0' || /^127\.\d+\.\d+\.\d+$/.test(host);
+}
+const portOf = (url) => { const u = new URL(url); return Number(u.port) || (u.protocol === 'https:' ? 443 : 80); };
+const route = (url) => ({ url, local: onThisComputer(url), port: portOf(url) });
+/**
+ * T3's enabled instances of a driver, its default one (the driver's own id) first. The default runs on the legacy
+ * `providers.<driver>` settings when it has no entry of its own. Variables marked sensitive are read from T3's secret
+ * store, as T3 does before it starts the provider.
+ */
+function t3Instances(t3, driver, read) {
+    const settings = json(read(join(t3, 'userdata', 'settings.json')));
+    const all = object(settings.providerInstances), legacy = object(object(settings.providers)[driver]);
+    const ids = Object.keys(all).filter((id) => object(all[id]).driver === driver && object(all[id]).enabled !== false);
+    if (!(driver in all) && legacy.enabled !== false)
+        ids.push(driver);
+    ids.sort((a, b) => Number(b === driver) - Number(a === driver));
+    return ids.map((id) => {
+        const entry = object(all[id]), env = {};
+        for (const v of Array.isArray(entry.environment) ? entry.environment : []) {
+            const variable = object(v), name = text(variable.name);
+            if (!name)
+                continue;
+            env[name] = variable.sensitive === true && variable.valueRedacted === true
+                ? read(join(t3, 'userdata', 'secrets', `provider-env-${b64(id)}-${b64(name)}.bin`)) ?? ''
+                : typeof variable.value === 'string' ? variable.value : '';
+        }
+        return { id, env, homePath: text(object(entry.config).homePath) ?? (id === driver ? text(legacy.homePath) : null) };
+    });
+}
+const expand = (path, home) => (path === '~' ? home : path.startsWith('~/') ? join(home, path.slice(2)) : path);
+const pick = (env, names) => {
+    const out = {};
+    for (const n of names) {
+        const v = env[n];
+        if (typeof v === 'string' && v !== '')
+            out[n] = v;
+    }
+    return out;
+};
+function claudeProxy(instance, base, home, read) {
+    const env = { ...base, ...instance?.env };
+    const dir = instance?.homePath ? expand(instance.homePath, home) : text(env.CLAUDE_CONFIG_DIR) ? expand(text(env.CLAUDE_CONFIG_DIR), home) : join(home, '.claude');
+    // Claude Code applies its settings' env over the environment it was started with.
+    for (const [k, v] of Object.entries(object(json(read(join(dir, 'settings.json'))).env)))
+        if (typeof v === 'string')
+            env[k] = v;
+    const url = text(env.ANTHROPIC_BASE_URL);
+    if (!url || !httpUrl(url))
+        return null;
+    const vars = pick(env, Object.keys(env).filter((k) => k.startsWith('ANTHROPIC_') || k === 'API_TIMEOUT_MS'));
+    return { ...route(url), env: vars, credential: Boolean(vars.ANTHROPIC_AUTH_TOKEN || vars.ANTHROPIC_API_KEY) };
+}
+function codexProxy(instance, base, home, read) {
+    const env = { ...base, ...instance?.env };
+    const dir = instance?.homePath ? expand(instance.homePath, home) : text(env.CODEX_HOME) ? expand(text(env.CODEX_HOME), home) : join(home, '.codex');
+    let config = {};
+    try {
+        config = parse(read(join(dir, 'config.toml')) ?? '');
+    }
+    catch { /* not TOML: Codex refuses it too */ }
+    const profile = object(object(config.profiles)[text(config.profile) ?? '']);
+    const id = text(profile.model_provider) ?? text(config.model_provider);
+    const provider = id ? object(object(config.model_providers)[id]) : {};
+    const url = text(provider.base_url);
+    if (id && id !== 'openai' && url && httpUrl(url)) {
+        const names = [text(provider.env_key), ...Object.values(object(provider.env_http_headers)).map(text)].filter((n) => n !== null);
+        return { ...route(url), env: pick(env, names), config: { model_provider: id, model_providers: { [id]: provider } } };
+    }
+    const openai = text(env.OPENAI_BASE_URL);
+    if (openai && httpUrl(openai))
+        return { ...route(openai), env: pick(env, ['OPENAI_BASE_URL', 'OPENAI_API_KEY']), config: null };
+    return null;
+}
+/** The proxy each app of T3 Code's own providers uses on this computer (null: it talks to its provider directly). */
+export function readT3ProxySetup(opts) {
+    const read = opts.read ?? readText, home = opts.env.HOME || homedir(), t3 = t3HomeDir(opts.env);
+    const first = (driver, fn) => {
+        // T3 Code's default instance while it is enabled; otherwise its other enabled instances, the first with a proxy.
+        const list = t3Instances(t3, driver, read);
+        for (const i of list[0]?.id === driver ? [list[0]] : list.length ? list : [null]) {
+            const found = fn(i);
+            if (found)
+                return found;
+        }
+        return null;
+    };
+    return {
+        claude: first('claudeAgent', (i) => claudeProxy(i, opts.env, home, read)),
+        codex: first('codex', (i) => codexProxy(i, opts.env, home, read)),
+    };
+}
+// ---- the VM side ---------------------------------------------------------------------------------------------------
+const VM_CODEX_CONFIG = '/home/user/.codex/config.toml';
+/** The proxy URL as a VM reaches it: one on this computer becomes the VM forwarder's address (same path). */
+export function vmProxyUrl(url) {
+    const u = new URL(url);
+    return `http://127.0.0.1:${CLI_PROXY_PORT}${u.pathname === '/' && !url.endsWith('/') ? '' : u.pathname}${u.search}`;
+}
+/**
+ * What a conversation VM needs to follow the setup. `hubInfo` is the account's VM hub info (vmHubInfoText), if any;
+ * `hubPorts` are the ports a CLIProxyAPI on this computer answers on (8317, and the one the import recorded).
+ */
+export function vmProxy(setup, hubInfo, hubPorts = [CLI_PROXY_PORT]) {
+    const out = { env: { claude: {}, codex: {} }, codexConfig: null, hubInfo: null, claudeCredential: false, unreachable: [], importable: [] };
+    const reach = (app, r) => {
+        if (!r.local)
+            return r.url;
+        if (!hubPorts.includes(r.port)) {
+            out.unreachable.push(app);
+            return null;
+        }
+        if (!hubInfo) {
+            out.unreachable.push(app);
+            out.importable.push(app);
+            return null;
+        }
+        out.hubInfo = hubInfo;
+        return vmProxyUrl(r.url);
+    };
+    if (setup.claude) {
+        const url = reach('claude', setup.claude);
+        if (url) {
+            out.env.claude = { ...setup.claude.env, ANTHROPIC_BASE_URL: url };
+            out.claudeCredential = setup.claude.credential;
+        }
+    }
+    if (setup.codex) {
+        const url = reach('codex', setup.codex);
+        if (url && setup.codex.config) {
+            const id = setup.codex.config.model_provider;
+            const provider = object(object(setup.codex.config.model_providers)[id]);
+            out.codexConfig = { model_provider: id, model_providers: { [id]: { ...provider, base_url: url } } };
+            out.env.codex = setup.codex.env;
+        }
+        else if (url)
+            out.env.codex = { ...setup.codex.env, OPENAI_BASE_URL: url };
+    }
+    return out;
+}
+/** The variables that carry a credential: kept out of every message, and in T3's secret store in a VM. */
+function secretVar(app, name) {
+    return app === 'codex' ? name !== 'OPENAI_BASE_URL' : /KEY|TOKEN|SECRET|PASSWORD|HEADER|AUTH|CREDENTIAL/i.test(name);
+}
+/** The T3 Code proxy setup as this account's VMs follow it (read again on every call: settings change). */
+export function accountVmProxy(ctx) {
+    const info = readHubInfo(ctx.store.dir, ctx.apiUrl);
+    // The port the imported CLIProxyAPI listened on here (tools that used it reach the hosted copy the same way).
+    const imported = object(new AgentStateStore(ctx.store.dir).read().cli_proxy_local);
+    const ports = [CLI_PROXY_PORT, ...(imported.api_url === ctx.apiUrl && typeof imported.port === 'number' ? [imported.port] : [])];
+    const plan = vmProxy(readT3ProxySetup({ env: ctx.io.env }), info ? vmHubInfoText(info) : null, ports);
+    for (const app of ['claude', 'codex'])
+        for (const [name, value] of Object.entries(plan.env[app]))
+            if (secretVar(app, name))
+                ctx.addSecret(value);
+    if (plan.hubInfo && info?.vm_callback_url)
+        ctx.addSecret(info.vm_callback_url);
+    return plan;
+}
+const missing = (e) => e instanceof ShardfluxApiError && e.status === 404;
+async function remoteText(cell, path) {
+    try {
+        return await cell.files.readText(path);
+    }
+    catch (error) {
+        if (missing(error))
+            return null;
+        throw error;
+    }
+}
+/**
+ * Puts what the VM's agents need in place before they start: the forwarder's hub info (0600), and the Codex provider in
+ * ~/.codex/config.toml (its other settings kept). Writes only what differs.
+ */
+export async function prepareVmProxy(cell, plan) {
+    // The VM's copy stays when it is this hub's with an address at least as new (another computer may have renewed it).
+    const hub = async (info) => {
+        const current = await remoteText(cell, VM_HUB_INFO_PATH);
+        if (current === info)
+            return;
+        const mine = json(info), theirs = json(current);
+        if (current !== null && theirs.workspace_id === mine.workspace_id && Date.parse(String(theirs.callback_created_at)) >= Date.parse(String(mine.callback_created_at)))
+            return;
+        await cell.files.write(VM_HUB_INFO_PATH, info, { mode: '0600', createParents: true });
+    };
+    const codex = async (keys) => {
+        const current = await remoteText(cell, VM_CODEX_CONFIG);
+        let config;
+        try {
+            config = parse(current ?? '');
+        }
+        catch {
+            return; /* the VM's own config is not TOML: Codex reports it there */
+        }
+        const id = keys.model_provider;
+        const next = { ...config, model_provider: id, model_providers: { ...object(config.model_providers), ...object(keys.model_providers) } };
+        // An active profile's own model_provider would win over the top-level one.
+        const active = text(config.profile), profiles = object(config.profiles);
+        if (active && active in profiles)
+            next.profiles = { ...profiles, [active]: { ...object(profiles[active]), model_provider: id } };
+        const out = stringify(next);
+        if (current === null || stringify(config) !== out)
+            await cell.files.write(VM_CODEX_CONFIG, out, { mode: '0600', createParents: true });
+    };
+    await Promise.all([plan.hubInfo ? hub(plan.hubInfo) : undefined, plan.codexConfig ? codex(plan.codexConfig) : undefined]);
+}
+const VM_T3 = '/home/user/.t3/userdata';
+/**
+ * The VM's own T3 Code (SSH and the T3 app through T3 Connect) runs its Claude Code and Codex providers with the setup's
+ * variables, stored as T3 stores them: plain values in its settings.json, credentials in its secret store
+ * (`secrets/provider-env-<base64url instance>-<base64url name>.bin`, 0600) with `valueRedacted` in the settings. The
+ * instances' other variables and the file's other settings stay. Also places prepareVmProxy's files.
+ */
+export async function prepareVmT3(cell, plan) {
+    await prepareVmProxy(cell, plan);
+    const wanted = [['claudeAgent', 'claude', plan.env.claude], ['codex', 'codex', plan.env.codex]];
+    if (wanted.every(([, , vars]) => !Object.keys(vars).length))
+        return;
+    const path = `${VM_T3}/settings.json`, current = await remoteText(cell, path);
+    let doc = {};
+    try {
+        if (current !== null)
+            doc = JSON.parse(current);
+    }
+    catch {
+        return; /* T3 reports its own unreadable settings */
+    }
+    if (!doc || typeof doc !== 'object' || Array.isArray(doc))
+        return;
+    const instances = { ...object(doc.providerInstances) }, secrets = [];
+    for (const [id, app, vars] of wanted) {
+        if (!Object.keys(vars).length)
+            continue;
+        const entry = object(instances[id]);
+        const kept = (Array.isArray(entry.environment) ? entry.environment : []).filter((v) => !(String(object(v).name) in vars));
+        const added = Object.entries(vars).map(([name, value]) => {
+            if (!secretVar(app, name))
+                return { name, value, sensitive: false };
+            secrets.push([`${VM_T3}/secrets/provider-env-${b64(id)}-${b64(name)}.bin`, value]);
+            return { name, value: '', sensitive: true, valueRedacted: true };
+        });
+        instances[id] = { ...entry, driver: id, environment: [...kept, ...added] };
+    }
+    // The secrets first: T3 reloads its settings when the file changes and reads them then.
+    await Promise.all(secrets.map(async ([p, v]) => { if ((await remoteText(cell, p)) !== v)
+        await cell.files.write(p, v, { mode: '0600', createParents: true }); }));
+    const next = `${JSON.stringify({ ...doc, providerInstances: instances }, null, 2)}\n`;
+    if (next !== current)
+        await cell.files.write(path, next, { mode: '0600', createParents: true });
+}
+/**
+ * Before T3 Code opens a project VM (`shard agents new|open --in t3`): its T3 Code follows the user's proxy setup. A
+ * proxy on this computer without the hosted copy is named with the import; nothing here fails the open.
+ */
+export async function followT3ProxyInVm(ctx, ws) {
+    const plan = accountVmProxy(ctx);
+    if (plan.importable.length) {
+        const apps = plan.importable.map((a) => (a === 'claude' ? 'Claude Code' : 'Codex')).join(' and ');
+        ctx.io.stderr.write(`Your T3 Code setup sends ${apps} through CLIProxyAPI on this computer. Cloud VMs use it once it is in your account: shard cli-proxy import\n`);
+    }
+    if (!plan.hubInfo && !plan.codexConfig && !Object.keys(plan.env.claude).length && !Object.keys(plan.env.codex).length)
+        return;
+    try {
+        await prepareVmT3(ws.cell(), plan);
+    }
+    catch (error) {
+        ctx.io.stderr.write(`T3 Code in ${ws.key} uses your Shardflux sign-ins for now: ${error instanceof Error ? error.message : String(error)}\n`);
+    }
+}

package/dist/terminal-apps.d.ts

@@ -93,6 +93,17 @@ export declare function terminalReport(dir: string, env: Env, terminals: readonl
 export declare const shellWord: (s: string) => string;
 /** The command as typed: with this computer's config folder when it is not the default (an app's own, a test's). */
 export declare function commandLine(argv: readonly string[], env: Env): string;
+/** Set in the command a terminal this CLI opened runs (0.23.0+): it attaches there and never hands off to yet another
+ * terminal, even if that terminal does not look like one a person types into. */
+export declare const TERMINAL_HANDOFF = "SHARDFLUX_TERMINAL_ATTACH";
+export declare const handedToTerminal: (env: Env) => boolean;
+/**
+ * The command a new terminal runs: without the coding-agent shell variables (AGENT_SHELL_VARIABLES), which a terminal
+ * started from an agent's shell inherits on Linux, so the child is a terminal a person types into; and with the
+ * one-time hand-off guard. Nimblefox (2026-10-13): from a Codex shell each new terminal looked like an agent shell
+ * again and opened another one, stealing focus in a loop.
+ */
+export declare function launchLine(argv: readonly string[], env: Env): string;
 /** What a shell in a new tab types: into the project folder, then the command. */
 export declare const typedLine: (argv: readonly string[], cwd: string, env: Env) => string;
 /** A new window's own command (Linux, Alacritty): it keeps the window open on an error so the person can read it. */

package/dist/terminal-apps.js

@@ -15,7 +15,7 @@ import { accessSync, constants, existsSync, mkdirSync, readFileSync, readdirSync
 import { homedir } from 'node:os';
 import { basename, dirname, join } from 'node:path';
 import { AgentStateStore } from "./agent-state.js";
-import { codingAgentShell } from "./agent-setup.js";
+import { AGENT_SHELL_VARIABLES, codingAgentShell } from "./agent-setup.js";
 import { applicationDirs } from "./agent-targets.js";
 import { UsageError } from "./errors.js";
 import { linuxTerminalCommand } from "./linux-terminal.js";
@@ -258,11 +258,24 @@ export const shellWord = (s) => s && BARE_WORD.test(s) ? s : `'${s.replaceAll("'
 export function commandLine(argv, env) {
     return `${env.SHARDFLUX_CONFIG_DIR ? `env SHARDFLUX_CONFIG_DIR=${shellWord(env.SHARDFLUX_CONFIG_DIR)} ` : ''}${argv.map(shellWord).join(' ')}`;
 }
+/** Set in the command a terminal this CLI opened runs (0.23.0+): it attaches there and never hands off to yet another
+ * terminal, even if that terminal does not look like one a person types into. */
+export const TERMINAL_HANDOFF = 'SHARDFLUX_TERMINAL_ATTACH';
+export const handedToTerminal = (env) => env[TERMINAL_HANDOFF] === '1';
+/**
+ * The command a new terminal runs: without the coding-agent shell variables (AGENT_SHELL_VARIABLES), which a terminal
+ * started from an agent's shell inherits on Linux, so the child is a terminal a person types into; and with the
+ * one-time hand-off guard. Nimblefox (2026-10-13): from a Codex shell each new terminal looked like an agent shell
+ * again and opened another one, stealing focus in a loop.
+ */
+export function launchLine(argv, env) {
+    return `env ${AGENT_SHELL_VARIABLES.map(name => `-u ${name} `).join('')}${TERMINAL_HANDOFF}=1 ${commandLine(argv, env).replace(/^env /, '')}`;
+}
 /** What a shell in a new tab types: into the project folder, then the command. */
-export const typedLine = (argv, cwd, env) => `cd ${shellWord(cwd)} && ${commandLine(argv, env)}`;
+export const typedLine = (argv, cwd, env) => `cd ${shellWord(cwd)} && ${launchLine(argv, env)}`;
 /** A new window's own command (Linux, Alacritty): it keeps the window open on an error so the person can read it. */
 export function windowCommand(argv, cwd, env) {
-    return ['sh', '-c', `cd ${shellWord(cwd)} 2>/dev/null; ${commandLine(argv, env)}; status=$?; if [ "$status" -ne 0 ]; then printf '\\nPress Enter to close.'; read answer; fi; exit "$status"`];
+    return ['sh', '-c', `cd ${shellWord(cwd)} 2>/dev/null; ${launchLine(argv, env)}; status=$?; if [ "$status" -ne 0 ]; then printf '\\nPress Enter to close.'; read answer; fi; exit "$status"`];
 }
 /** An AppleScript string literal. */
 export const appleString = (s) => `"${s.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('\n', '\\n').replaceAll('\r', '\\r')}"`;
@@ -304,7 +317,7 @@ export function warpTabConfig(argv, cwd, env) {
         'id = "conversation"',
         'type = "terminal"',
         `directory = ${JSON.stringify(cwd)}`,
-        `commands = [${JSON.stringify(commandLine(argv, env))}]`,
+        `commands = [${JSON.stringify(launchLine(argv, env))}]`,
         'is_focused = true',
         '',
     ].join('\n');
@@ -366,7 +379,7 @@ async function openWith(t, mode, l) {
     const { argv, cwd, env, platform } = l;
     const line = typedLine(argv, cwd, env);
     const name = t.name;
-    const command = commandLine(argv, env);
+    const command = launchLine(argv, env);
     const mac = platform === 'darwin';
     const activate = async () => { if (mac && t.path)
         await terminalNative.run('/usr/bin/open', ['-a', t.path], { env, timeoutMs: 5000 }); };

package/dist/update.d.ts

@@ -55,6 +55,8 @@ export interface UpdateDeps {
 /** True when nothing is behind but the menu bar app, and the app the npm package carries is already that version. */
 export declare function onlyAppToSwap(pending: Component[], packagedApp: string | null): boolean;
 export declare function update(ctx: Ctx, values: Record<string, unknown>, deps?: UpdateDeps): Promise<number>;
+/** Keep an upgrade-stable alias only when it runs this exact Node (never another version from PATH). */
+export declare function stableNodePath(node: string, env: NodeJS.ProcessEnv): string;
 /** Records where `shard` runs, for the menu bar's update button. Written on macOS, only when it changed. */
 export declare function recordInstall(dir: string, runtime: Runtime, distribution: {
     package: string;

package/dist/update.js

@@ -9,9 +9,9 @@
  * macOS) and shows the outcome from last-update.json, also when the update replaced the app that started it.
  */
 import { spawn } from 'node:child_process';
-import { closeSync, existsSync, openSync, readFileSync, realpathSync, rmSync, writeSync } from 'node:fs';
+import { accessSync, closeSync, constants, existsSync, openSync, readFileSync, realpathSync, rmSync, writeSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { basename, dirname, join, sep } from 'node:path';
+import { basename, dirname, isAbsolute, join, sep } from 'node:path';
 import { clientVersionStatus, SDK_VERSION } from '@shardflux/sdk';
 import { CLI_VERSION } from "./args.js";
 import { AgentStateStore } from "./agent-state.js";
@@ -108,7 +108,7 @@ export async function components(ctx, install, catalog, menubar = menubarManager
         local.push(['@shardflux/cli', CLI_VERSION]);
     local.push(['@shardflux/sdk', SDK_VERSION]);
     if (menubar.platform === 'darwin') {
-        const status = await menubar.status().catch(() => null);
+        const status = await menubar.status(ctx.store.dir).catch(() => null);
         if (status?.installed && status.version)
             local.push([MENUBAR, status.version]);
     }
@@ -292,7 +292,7 @@ async function refreshMenubar(ctx, menubar, runtime, run, env) {
         return { status: 'off' };
     if (new AgentStateStore(ctx.store.dir).read().menubar_stopped === true)
         return { status: 'off' };
-    const before = await menubar.status().catch(() => null);
+    const before = await menubar.status(ctx.store.dir).catch(() => null);
     if (!before?.installed)
         return { status: 'off' };
     if (runtime && run && env) {
@@ -306,9 +306,35 @@ async function refreshMenubar(ctx, menubar, runtime, run, env) {
             return { status: 'current' };
         await menubar.start(ctx.store.dir, ctx.apiUrl);
     }
-    const after = await menubar.status().catch(() => null);
+    const after = await menubar.status(ctx.store.dir).catch(() => null);
     return after?.version && after.version !== before.version ? { status: 'restarted', version: after.version } : { status: 'current' };
 }
+/** Keep an upgrade-stable alias only when it runs this exact Node (never another version from PATH). */
+export function stableNodePath(node, env) {
+    let real;
+    try {
+        real = realpathSync(node);
+    }
+    catch {
+        return node;
+    }
+    const candidates = (env.PATH ?? '').split(':').filter(isAbsolute).map(dir => join(dir, 'node'));
+    // Homebrew's opt link also works when launchd's PATH has no Homebrew entry (including versioned formulae).
+    const brew = /^(.*)\/Cellar\/(node(?:@[^/]+)?)\/[^/]+\/bin\/node$/.exec(node);
+    if (brew)
+        candidates.push(join(brew[1], 'opt', brew[2], 'bin/node'), join(brew[1], 'bin/node'));
+    for (const candidate of candidates) {
+        try {
+            if (candidate.includes('/Cellar/'))
+                continue;
+            accessSync(candidate, constants.X_OK);
+            if (realpathSync(candidate) === real)
+                return candidate;
+        }
+        catch { /* missing alias: try the next one */ }
+    }
+    return node;
+}
 /** Records where `shard` runs, for the menu bar's update button. Written on macOS, only when it changed. */
 export function recordInstall(dir, runtime, distribution, env = {}) {
     let script = runtime.script;
@@ -336,7 +362,7 @@ export function recordInstall(dir, runtime, distribution, env = {}) {
     catch {
         menubarApp = null;
     }
-    const doc = { version: 1, node: runtime.node, script, package: distribution.package, package_version: distribution.version, cli_version: CLI_VERSION, ...(menubarApp ? { menubar_app: menubarApp } : {}) };
+    const doc = { version: 1, node: stableNodePath(runtime.node, env), script, package: distribution.package, package_version: distribution.version, cli_version: CLI_VERSION, ...(menubarApp ? { menubar_app: menubarApp } : {}) };
     const text = `${JSON.stringify(doc, null, 2)}\n`;
     try {
         if (readFileSync(join(dir, INSTALL_FILE), 'utf8') === text)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.22.0",
+  "version": "0.23.1",
   "type": "module",
   "description": "shard: the Shardflux command line. Create an account, sign in, set up keys and billing, then open, run commands in, move files to, suspend, resume and fork serverless agent workspaces.",
   "license": "Apache-2.0",
@@ -47,7 +47,7 @@
     "smol-toml": "1.9.0",
     "snappyjs": "0.7.0",
     "yaml": "2.9.1",
-    "@shardflux/sdk": "^0.26.0"
+    "@shardflux/sdk": "^0.27.1"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
@@ -58,9 +58,9 @@
     "typescript-eslint": "8.70.1"
   },
   "optionalDependencies": {
-    "@shardflux/desktop-linux-x64": "0.1.8",
-    "@shardflux/desktop-linux-arm64": "0.1.8",
-    "@shardflux/menubar-darwin": "^0.8.3"
+    "@shardflux/desktop-linux-x64": "0.1.11",
+    "@shardflux/desktop-linux-arm64": "0.1.11",
+    "@shardflux/menubar-darwin": "^0.8.5"
   },
   "scripts": {
     "build": "node scripts/build.mjs",