@shardflux/cli 0.22.0 → 0.23.0

package/dist/acp.js

@@ -6,7 +6,8 @@ import { AcpRpc, RpcError, objectValue } from "./acp-rpc.js";
 import { ACP_PROBE_CATALOG, nativeCurrentModel, nativeModelOptions, withoutNativeModel } from "./acp-catalog.js";
 import { ACP_LIFECYCLE, AcpModelCache, acpScope } from "./acp-models.js";
 import { AcpJournal } from "./acp-journal.js";
-import { getConversation, conversationWorkspace, rememberConversation, resumeConversation, restoreConversationBinding } from "./conversations.js";
+import { getConversation, conversationWorkspace, preparedInFlight, rememberConversation, resumeConversation, restoreConversationBinding } from "./conversations.js";
+import { seedEvent } from "./seed-phases.js";
 import { projectIdentity } from "./project-identity.js";
 import { projectSyncBoundary } from "./project-sync.js";
 import { localManifest } from "./project-sync-manifest.js";
@@ -18,6 +19,7 @@ import { ACP_LOGIN_METHOD, acpSignedIn } from "./acp-login.js";
 import { ensureMenubar, MenubarManager } from "./menubar.js";
 import { syncAgentConfigAfterStart } from "./agent-config-sync.js";
 import { savedMachine } from "./filesystem-state.js";
+import { accountVmProxy, prepareVmProxy } from "./t3-proxy.js";
 const PREFIX = 'shardflux:';
 export function acpModel(app, id) { return `${PREFIX}${app}:${id}`; }
 export function parseAcpModel(value) {
@@ -82,6 +84,7 @@ export class ShardfluxAcp {
     #sessions = new Map();
     #lifecycle;
     #cache;
+    #proxied = new Map();
     #initialized = false;
     #probe = false;
     constructor(ctx, client, errors = acpError, lifecycle = ACP_LIFECYCLE) { this.#ctx = ctx; this.#client = client; this.#store = new AgentStateStore(ctx.store.dir); this.#cache = new AcpModelCache(ctx.store.dir); this.#errors = errors; this.#lifecycle = lifecycle; }
@@ -253,6 +256,7 @@ export class ShardfluxAcp {
         }
         session.preparing = (async () => {
             await syncAgentCredentials(ctx.cloud(), { home: ctx.io.env.HOME, redact: value => ctx.addSecret(value) });
+            const proxy = this.#proxy();
             const catalog = await this.#lifecycle.prepare(ctx, record.folder, `acp-${record.id.slice(3).replaceAll('-', '')}`, {
                 allocated: (c, view) => {
                     session.conversation = c;
@@ -272,6 +276,7 @@ export class ShardfluxAcp {
                 },
                 ready: ws => { session.ws = ws; record.scope = acpScope(ctx.apiUrl, ws.data); this.#cache.remember(ctx, record.folder, record.scope); },
                 prepared: () => { session.seedReady = true; prepared(); },
+                proxy: { env: { ...proxy.env.claude, ...proxy.env.codex }, ready: ws => this.#proxyReady(ws, proxy) },
             });
             ctx.signal.throwIfAborted();
             if (!record.scope)
@@ -371,13 +376,20 @@ export class ShardfluxAcp {
     }
     async #start(session) {
         const ctx = this.#ctx, { record } = session, app = record.app ?? parseAcpModel(record.model).app;
+        // SHARDFLUX_TRACE_SEED: when each step of the connection ends (one line each, wall clock).
+        const mark = (name) => seedEvent(`acp_${name}`, Date.now());
+        mark('connect');
         record.app = app;
         await session.transport?.close();
-        // The sign-in is checked beside reading the conversation and its VM; it passes before anything starts in the VM.
+        // The user's T3 Code proxy setup, read again for every connection; the agent's variables apply when its process starts.
+        const proxy = this.#proxy();
+        // The sign-in is checked beside reading the conversation and its VM; it passes before anything starts in the VM. A
+        // proxy with its own credential needs no Shardflux Claude sign-in.
         const signIn = (async () => {
             await syncAgentCredentials(ctx.cloud(), { home: ctx.io.env.HOME, redact: value => ctx.addSecret(value) });
-            if (app === 'claude' && !(await cloudClaudeLogin(ctx)))
-                throw new RpcError(-32000, 'Authentication required: connect Claude Code.', { code: 'unauthenticated', fix: SIGN_IN });
+            if (app === 'claude' && !proxy.claudeCredential && !(await cloudClaudeLogin(ctx))) {
+                throw new RpcError(-32000, proxy.importable.includes('claude') ? 'Authentication required: connect Claude Code, or move your CLIProxyAPI into your account (shard cli-proxy import).' : 'Authentication required: connect Claude Code.', { code: 'unauthenticated', fix: SIGN_IN });
+            }
         })();
         signIn.catch(() => undefined);
         if (!record.conversationId) {
@@ -394,25 +406,36 @@ export class ShardfluxAcp {
             session.conversation = await resumeConversation(ctx, current);
             session.ws = await conversationWorkspace(ctx, session.conversation);
             rememberConversation(ctx, session.conversation, record.folder);
+            mark('conversation');
         }
         await signIn;
+        mark('signed_in');
         let c = session.conversation;
         const cell = session.ws.cell();
         const menubar = ensureMenubar(ctx.store.dir, ctx.apiUrl, new MenubarManager({ home: ctx.io.env.HOME, signal: ctx.signal }));
         await restoreConversationBinding(ctx, c, session.ws);
+        mark('binding');
         // The project files are reconciled, device approvals served and the supervisor launched side by side; the native
-        // session starts once all three are done (0.21.1+).
+        // session starts once the supervisor is up, and the connection is done (the prompt goes) once the files are
+        // reconciled too (0.21.1+).
         const files = (async () => {
             const boundary = await projectSyncBoundary({ ...ctx, signal: AbortSignal.any([ctx.signal, session.stop.signal]) }, session.ws, projectIdentity(record.folder), {
                 root: c.worktree_path, agent: record.id.replace(/^sf-/, 'acp-'), seed: false,
                 stateKey: `acp:${ctx.apiUrl}:${record.id}:${record.folder}`, ...(session.hashes ? { cache: session.hashes } : {}),
                 // Before its first prompt the VM holds what this computer seeded it with, so edits made here since are not conflicts.
                 vmBaseline: !record.prompted,
+                // Large media of a prepared start that are still on their way land by themselves (0.22.0+).
+                inFlight: () => preparedInFlight(ctx, c.id),
             });
             await boundary.reconcile();
+            mark('files');
             return boundary;
         })();
-        const launch = cell.exec.run(['sf-agent', 'acp', app, '--conversation', c.id, '--detach'], { cwd: c.worktree_path, timeoutMs: 30_000, signal: ctx.signal, maxOutputBytes: 1 << 20 });
+        // The agent starts with the proxy setup's variables, once the VM files it reads are in place.
+        const env = proxy.env[app];
+        const launch = this.#proxyReady(session.ws, proxy).then(() => cell.exec.run(['sf-agent', 'acp', app, '--conversation', c.id, '--detach'], {
+            cwd: c.worktree_path, timeoutMs: 30_000, signal: ctx.signal, maxOutputBytes: 1 << 20, ...(Object.keys(env).length ? { env } : {})
+        }));
         files.catch(() => undefined);
         launch.catch(() => undefined);
         session.approvals ??= await serveAcpDeviceApprovals(ctx.store.dir, c.id, async (approval) => {
@@ -422,13 +445,15 @@ export class ShardfluxAcp {
             const outcome = objectValue(result.outcome);
             return outcome.outcome === 'selected' && (outcome.optionId === 'once' || outcome.optionId === 'always') ? outcome.optionId : 'deny';
         });
-        session.files = await files;
+        mark('approvals');
         const launched = await launch;
+        mark('launched');
         await menubar;
         if (launched.exitCode !== 0)
             throw new Error(`ACP supervisor could not attach: ${launched.stderr.trim()}`);
         const [claimed, statusText] = await Promise.all([getConversation(ctx, c.id), cell.files.readText(`/home/user/.local/share/shardflux/acp/${c.id}/status.json`, { length: 8192 })]);
         c = claimed;
+        mark('status');
         if (c.harness !== app)
             throw new Error('The guest did not claim this conversation harness.');
         session.conversation = c;
@@ -476,13 +501,16 @@ export class ShardfluxAcp {
         };
         session.transport = transport;
         await transport.start();
+        mark('journal');
         if (initialize) {
             const initialized = objectValue(await transport.rpc.request('initialize', { protocolVersion: 1, clientInfo: { name: 'shardflux', version: CLI_VERSION }, clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false } }));
             if (initialized.protocolVersion !== 1)
                 throw new Error('Agent protocol version changed');
+            mark('initialized');
             const nativeId = c.harness_session_id ?? record.nativeId;
             const result = objectValue(await transport.rpc.request(nativeId ? 'session/load' : 'session/new', { cwd: c.worktree_path, mcpServers: [{ name: 'shardflux', command: '/usr/local/bin/sf-agent', args: ['conversation', 'mcp'], env: [{ name: 'SF_CONVERSATION_ID', value: c.id }] }], ...(nativeId ? { sessionId: nativeId } : {}) }));
             const id = result.sessionId ?? nativeId;
+            mark('session');
             if (typeof id !== 'string' || !id)
                 throw new Error('Agent returned no native session id');
             record.nativeId = id;
@@ -505,6 +533,31 @@ export class ShardfluxAcp {
             this.#cacheSession(session);
             await this.#modelUpdate(session);
         }
+        // Not connected until the files are: a failed reconcile closes the journal, so the next use connects again.
+        try {
+            session.files = await files;
+        }
+        catch (error) {
+            await session.transport.close();
+            throw error;
+        }
+        mark('files_ready');
+    }
+    /** The T3 Code proxy setup as a conversation VM follows it. Its credentials are kept out of every message. */
+    #proxy() { return accountVmProxy(this.#ctx); }
+    /** Puts the proxy's VM files in place once per VM and setup (prepareVmProxy). */
+    #proxyReady(ws, plan) {
+        if (!plan.hubInfo && !plan.codexConfig)
+            return Promise.resolve();
+        const key = JSON.stringify([plan.hubInfo, plan.codexConfig]);
+        const done = this.#proxied.get(ws.id);
+        if (done?.key === key)
+            return done.ready;
+        const ready = prepareVmProxy(ws.cell(), plan);
+        this.#proxied.set(ws.id, { key, ready });
+        ready.catch(() => { if (this.#proxied.get(ws.id)?.ready === ready)
+            this.#proxied.delete(ws.id); });
+        return ready;
     }
     async #close(session) {
         this.#sessions.delete(session.record.id);

package/dist/agent-commands.js

@@ -1,5 +1,5 @@
 import { linuxTerminalSession } from "./linux-terminal.js";
-import { attachable, currentTerminal, openShardInTerminal, referenceFolder, reportTerminalOpen, storedTerminal } from "./terminal-apps.js";
+import { attachable, currentTerminal, handedToTerminal, openShardInTerminal, referenceFolder, reportTerminalOpen, storedTerminal } from "./terminal-apps.js";
 import { repositoryName } from "./files-mirror.js";
 import { prepareSetupCache, recordSetupCacheFailure } from "./setup-cache.js";
 import { launchCodexCloud, openCodexConversation } from "./codex-cloud.js";
@@ -30,7 +30,7 @@ import { openInFor } from "./t3-mode.js";
 import { storedTitlePrefix } from "./client-settings.js";
 import { openClaudeDesktopSession, openDesktopWorkspace, queueT3Prewarm } from "./agent-target-commands.js";
 import { guestFirstPrompt, INBOX_MAX_CHARS, submitInitialPrompt, prepareInitialCodexProject } from "./initial-prompt.js";
-import { conversationWorkspace, conversationsUnavailable, getConversation, listConversations, resumeConversation } from "./conversations.js";
+import { conversationForOpen, conversationWorkspace, conversationsUnavailable, getConversation, listConversations, resumeConversation } from "./conversations.js";
 import { conversationClient } from "./conversation-commands.js";
 import { conversationTerminal, reopenConversation } from "./conversation-terminal.js";
 import { CHOICE_PENDING, choiceReport, hasChoice, launchChoice, modelChoice, runFlags } from "./agent-models.js";
@@ -325,7 +325,8 @@ export async function launchProjectWith(ctx, values, [path = './', explicitApp],
  * terminal), and `--in terminal` typed in a terminal other than the chosen one.
  */
 function opensInTerminalApp(ctx, values) {
-    if (values.detach === true)
+    // A terminal this CLI opened for the conversation attaches there, never in yet another one (0.23.0+).
+    if (values.detach === true || handedToTerminal(ctx.io.env))
         return false;
     const here = attachable(ctx.io);
     if (values.in === undefined)
@@ -364,15 +365,26 @@ export const AGENT_HANDLERS = {
     async 'agents open'(ctx, values, [agent = 'main']) {
         if (values.app !== undefined && values.app !== 'claude' && values.app !== 'codex')
             throw new UsageError('--app must be claude or codex');
-        // The person's terminal app (0.20.1+): before any cloud work, the new tab owns the attach, credentials and prompts.
-        if (opensInTerminalApp(ctx, values))
-            return openInTerminalApp(ctx, agent, values);
+        // A Codex Cloud conversation opens its chat in Codex, never in a terminal (0.23.0+): it is resolved before any
+        // terminal hand-off, by its id or by its computer's key, which menus before Linux 0.1.9 and menu bar 0.8.4 pass.
+        // Nimblefox (2026-10-13): the hand-off came first, and from a Codex shell each new terminal opened another one.
+        // The person's terminal app (0.20.1+): after that lookup, the new tab owns the attach, credentials and prompts; a
+        // lookup this shell cannot make (signed out here, offline) leaves the hand-off to it.
+        const handOff = opensInTerminalApp(ctx, values);
         let resolvedConversation;
-        if (/^conv_[a-z0-9]{26}$/.test(agent)) {
-            resolvedConversation = await getConversation(ctx, agent);
-            if (resolvedConversation.route === 'codex-cloud')
-                return openCodexConversation(ctx, resolvedConversation);
+        if (/^conv_[a-z0-9]{26}$/.test(agent) || agent.includes('/')) {
+            try {
+                resolvedConversation = await conversationForOpen(ctx, agent);
+            }
+            catch (error) {
+                if (!handOff)
+                    throw error;
+            }
         }
+        if (resolvedConversation?.route === 'codex-cloud')
+            return openCodexConversation(ctx, resolvedConversation, values.original === true ? true : values.history);
+        if (handOff)
+            return openInTerminalApp(ctx, agent, values);
         if (values.in === 'auto') {
             // The menu and other launchers use the same CLI-owned target selection. Never put provider URLs in a client.
             // A conversation id opens that conversation's own session, also when its computer hosts other threads.
@@ -405,6 +417,8 @@ export const AGENT_HANDLERS = {
             // Codex's default open implementation owns Cloud/desktop routing. PAS-XB replaces that path; do not pin
             // the menu to the old per-VM SSH target. An explicit saved desktop target still takes precedence.
             if ((!saved || !detected.targets.includes(saved)) && app === 'codex') {
+                if (resolvedConversation?.route === 'terminal')
+                    return terminalAuto(ctx, ws, opened, values);
                 const next = { ...values };
                 delete next.in;
                 return AGENT_HANDLERS['agents open'](ctx, next, [resolvedConversation?.id ?? ws.key]);
@@ -414,7 +428,7 @@ export const AGENT_HANDLERS = {
                 const handler = HANDLERS[`agents open ${saved}`];
                 if (!handler)
                     throw new UsageError('Choose an installed open target with shard agents targets.');
-                return handler(ctx, { ...values, in: saved }, [ws.key]);
+                return handler(ctx, { ...values, in: saved }, [opened]);
             }
             // Claude opens where people work (0.15.1+): the conversation in Claude Desktop when it is installed, else Claude
             // Code in a terminal. The browser (claude.ai) only when it is the chosen target (--in web).
@@ -433,10 +447,10 @@ export const AGENT_HANDLERS = {
         await syncCredentials(ctx);
         let ws;
         let conversation;
-        if (/^conv_[a-z0-9]{26}$/.test(agent)) {
+        if (resolvedConversation || /^conv_[a-z0-9]{26}$/.test(agent)) {
             conversation = resolvedConversation ?? await getConversation(ctx, agent);
             if (conversation.route === 'codex-cloud')
-                return openCodexConversation(ctx, conversation);
+                return openCodexConversation(ctx, conversation, values.original === true ? true : values.history);
             conversation = await resumeConversation(ctx, conversation);
             ws = await conversationWorkspace(ctx, conversation);
         }
@@ -469,7 +483,7 @@ export const AGENT_HANDLERS = {
                 if (matches.length !== 1)
                     throw new UsageError('Use the conversation id.');
                 if (matches[0].route === 'codex-cloud')
-                    return openCodexConversation(ctx, matches[0]);
+                    return openCodexConversation(ctx, matches[0], values.original === true ? true : values.history);
                 conversation = await resumeConversation(ctx, matches[0]);
                 ws = await conversationWorkspace(ctx, conversation);
             }
@@ -477,7 +491,7 @@ export const AGENT_HANDLERS = {
             if (!conversation && ws.labels.shard_conversation) {
                 conversation = await getConversation(ctx, ws.labels.shard_conversation);
                 if (conversation.route === 'codex-cloud')
-                    return openCodexConversation(ctx, conversation);
+                    return openCodexConversation(ctx, conversation, values.original === true ? true : values.history);
                 conversation = await resumeConversation(ctx, conversation);
                 ws = await conversationWorkspace(ctx, conversation);
             }

package/dist/agent-target-commands.d.ts

@@ -1,9 +1,10 @@
 import { Duplex } from 'node:stream';
-import type { CellClient, Workspace } from '@shardflux/sdk';
+import type { CellClient, T3Link, Workspace } from '@shardflux/sdk';
 import type { Conversation } from './conversations.js';
 import type { Ctx, Handler, Io } from './commands.js';
 import { AgentTargets } from './agent-targets.js';
 import type { DesktopTarget } from './agent-targets.js';
+import { CodedError } from './errors.js';
 import type { T3Install, T3ThreadRequest } from './t3-mode.js';
 /** Optimistic file replacement preserves keys installed by other devices connecting at the same time. */
 export declare function installDeviceKey(cell: CellClient, key: string, signal?: AbortSignal): Promise<void>;
@@ -35,5 +36,23 @@ export declare function openClaudeDesktopSession(ctx: Ctx, ws: Workspace, conver
 export declare function openDesktopWorkspace(ctx: Ctx, ws: Workspace, target: DesktopTarget, t3Version?: string, prewarmed?: boolean, thread?: T3ThreadRequest, install?: T3Install, conversation?: string | null): Promise<number>;
 /** T3 Code's Connections page (its t3code:// link), where a project linked with T3 Connect is listed. */
 export declare const T3_CONNECTIONS_PAGE = "t3code://app/settings/connections";
+/** A workspace's link as `agents open t3` reports it (`t3_link`): the PUT answer, or the outcome the status read gave. */
+export type T3LinkView = Omit<T3Link, 'status'> & {
+    status: T3Link['status'] | 'error';
+    last_error?: string;
+    needs_login?: boolean;
+};
+/** How long `agents open t3` waits for a link in progress to be linked or refused (at most the wake timeout). */
+export declare const T3_LINK_WAIT_MS = 30000;
+/**
+ * The link T3 Code needs is refused (`t3_link_failed`, with the API's remedy: for T3 Connect's environment limit, its
+ * Connections page) or still linking after T3_LINK_WAIT_MS (`t3_link_pending`). Both name the workspace, conversation
+ * and any started thread, so a client opens what exists again rather than starting another.
+ */
+export declare function t3LinkNotReady(link: T3LinkView, ref: {
+    workspace_key: string;
+    conversation_id: string | null;
+    t3_thread_id: string | null;
+}): CodedError;
 export declare function queueT3Prewarm(ctx: Ctx, ws: Workspace, version: string): Promise<void>;
 export declare const TARGET_HANDLERS: Record<string, Handler>;

package/dist/agent-target-commands.js

@@ -5,19 +5,20 @@ import { ensureCloudClaude } from "./claude-cloud-login.js";
 import { spawn } from 'node:child_process';
 import { Readable, Duplex } from 'node:stream';
 import { ShardfluxApiError, WorkspaceTunnels } from '@shardflux/sdk';
-import { getConversation } from "./conversations.js";
+import { conversationForOpen } from "./conversations.js";
 import { out, resolveWorkspace } from "./commands.js";
 import { MODEL_CHOICES } from "./agent-models.js";
 import { AgentTargets, installedTargets, targetLabel } from "./agent-targets.js";
 import { join, relative, resolve } from 'node:path';
 import { projectIdentity } from "./project-identity.js";
 import { projectWorkspacePath } from "./agent-repository.js";
-import { UsageError, describeError } from "./errors.js";
+import { CodedError, UsageError, describeError } from "./errors.js";
 import { t3PhoneLink } from "./t3-phone.js";
 import { prepareDesktopRouter } from "./conversation-router.js";
 import { openUrl } from "./browser.js";
 import { agentMachineName, prepareAgentMachine } from "./agent-machine.js";
 import { prewarmT3 } from "./t3-runtime.js";
+import { followT3ProxyInVm } from "./t3-proxy.js";
 import { AgentStateStore } from "./agent-state.js";
 import { workspaceRepositoryPath } from "./agent-repository.js";
 import { openInChoices, openInTargets, openT3, saveOpenIn, startSshThread, t3Install, t3NotInstalled, t3OpenFailed, t3Status } from "./t3-mode.js";
@@ -221,16 +222,23 @@ async function openLink(url, env) {
     });
 }
 const openTarget = (target) => async (ctx, values, [ref = 'main']) => {
+    // A conversation started in T3 (its Shardflux provider) opens its own thread there (0.17.0+); a Codex Cloud one opens
+    // its Codex chat (0.23.0+). openT3Conversation checks T3 Code itself where it needs it.
+    let conversation = await conversationForOpen(ctx, /^conv_[a-z0-9]{26}$/.test(ref) ? ref : keyOf(ref));
+    if (target === 't3' && conversation)
+        return openT3Conversation(ctx, conversation.id, values);
+    // A Codex Cloud conversation opens its existing thread in the Codex app, not an SSH environment (0.23.0+).
+    if (target === 'codex-app' && conversation?.route === 'codex-cloud')
+        return (await import("./codex-cloud.js")).openCodexConversation(ctx, conversation);
     const detected = installedTargets(ctx.io.env);
     if (target === 't3' && !detected.targets.includes('t3'))
         throw t3NotInstalled();
+    if (target === 'codex-app' && !detected.targets.includes(target) && detected.clients.includes('codex-app')) {
+        throw new UsageError('On Linux the Codex app opens Codex Cloud conversations (shard agents open codex-app <conversation>).', `Open this one with: shard agents open ${ref}`);
+    }
     if (target !== 'web' && !detected.targets.includes(target))
         throw new UsageError(`${target} is not installed on this machine`);
-    // A conversation started in T3 (its Shardflux provider) opens its own thread there (0.17.0+).
-    if (target === 't3' && /^conv_[a-z0-9]{26}$/.test(ref))
-        return openT3Conversation(ctx, ref, values);
     // A conversation id opens that conversation's own session on its computer (claude.ai, the desktop apps).
-    let conversation = /^conv_[a-z0-9]{26}$/.test(ref) ? await getConversation(ctx, ref) : undefined;
     // A conversation whose VM was removed restores into a fresh one first (0.18.1+).
     let ws;
     if (conversation) {
@@ -269,6 +277,9 @@ export async function openDesktopWorkspace(ctx, ws, target, t3Version, prewarmed
     await prepareAgentMachine(ctx, ws);
     if (target === 't3' && t3Version && !prewarmed)
         await queueT3Prewarm(ctx, ws, t3Version);
+    // The VM's T3 Code follows the user's T3 proxy setup, before its server starts for a thread or the T3 Connect link.
+    if (target === 't3')
+        await followT3ProxyInVm(ctx, ws);
     const targets = new AgentTargets(ctx.io.env, ctx.store.dir);
     const entry = (await (ws.labels.shard_router === 'project' ? targets.configureProject(ws.key, ctx.apiUrl, [target], ctx.signal) : targets.configure(ws.key, ctx.apiUrl, [target], false, ctx.signal))).find(e => e.workspace === ws.key);
     const instructions = target === 't3'
@@ -291,8 +302,13 @@ export async function openDesktopWorkspace(ctx, ws, target, t3Version, prewarmed
     // The first time a project is set up for T3 Code, T3 opens on its Connections page once the project is linked: the
     // project is listed there (or T3's own Sign in to T3 Connect, when T3 Code is signed out).
     if (target === 't3') {
-        if (fresh && phone?.link.status === 'linking')
-            phone = await waitT3Linked(ctx, ws, phone);
+        // T3 Code lists the project only once its T3 Connect link is linked (0.23.0+): a refused or still pending link is
+        // reported as such, naming what exists, instead of an opened T3 that does not show it.
+        if (phone?.link.status === 'linking')
+            phone = await waitT3Link(ctx, ws, phone);
+        const ref = { workspace_key: ws.key, conversation_id: conversation ?? (ws.labels.shard_conversation || null), t3_thread_id: started?.t3_thread_id ?? null };
+        if (phone?.link.status === 'error' || phone?.link.status === 'linking')
+            throw t3LinkNotReady(phone.link, ref);
         const page = fresh && phone?.link.status === 'linked' ? T3_CONNECTIONS_PAGE : undefined;
         // The thread exists once startSshThread returns: a failure to show T3 names it rather than inviting a retry.
         try {
@@ -338,25 +354,40 @@ const t3LinkLine = (link, signIn, needsLogin) => signIn
     : needsLogin ? `To have ${link.label} appear in T3 Code and the T3 app, sign in with shard auth login, then run this again.\n`
         : link.status === 'linked' ? `${link.label} is linked to your T3 account.\n`
             : `Linking ${link.label} to your T3 account…\n`;
-/** A project linking for the first time: T3 lists it once linked, so its Connections page waits for that (at most 20 s). */
-async function waitT3Linked(ctx, ws, phone) {
-    const until = Date.now() + 20_000;
-    while (Date.now() < until && !ctx.signal?.aborted) {
-        await delay(2000);
+/** How long `agents open t3` waits for a link in progress to be linked or refused (at most the wake timeout). */
+export const T3_LINK_WAIT_MS = 30_000;
+/** A link in progress: its outcome from the account's T3 status, read every 2 s for at most T3_LINK_WAIT_MS. */
+async function waitT3Link(ctx, ws, phone) {
+    const until = Date.now() + Math.min(T3_LINK_WAIT_MS, ctx.wakeTimeoutMs ?? T3_LINK_WAIT_MS);
+    for (;;) {
         try {
             const known = (await ctx.cloud().t3.status()).links.find(l => l.workspace_id === ws.id);
-            if (known?.status === 'linked') {
-                const link = { ...phone.link, status: 'linked' };
+            if (known && known.status !== 'linking') {
+                const link = { ...phone.link, status: known.status === 'linked' ? 'linked' : known.status === 'needs_sign_in' ? 'needs_sign_in' : 'error', ...(known.last_error ? { last_error: known.last_error } : {}) };
                 return { line: t3LinkLine(link), link };
             }
-            if (known && known.status !== 'linking')
-                return phone;
         }
         catch {
             return phone;
         }
+        if (Date.now() >= until || ctx.signal?.aborted)
+            return phone;
+        await delay(2000);
+    }
+}
+/**
+ * The link T3 Code needs is refused (`t3_link_failed`, with the API's remedy: for T3 Connect's environment limit, its
+ * Connections page) or still linking after T3_LINK_WAIT_MS (`t3_link_pending`). Both name the workspace, conversation
+ * and any started thread, so a client opens what exists again rather than starting another.
+ */
+export function t3LinkNotReady(link, ref) {
+    const again = `shard agents open t3 ${ref.conversation_id ?? ref.workspace_key}`;
+    const details = { ...ref, t3_link: link };
+    if (link.status !== 'error') {
+        return new CodedError('t3_link_pending', `Linking ${link.label} to your T3 account. T3 Code lists it once it is linked.`, `Open it in a moment: ${again}`, details);
     }
-    return phone;
+    const limit = /environment limit/i.test(link.last_error ?? '');
+    return new CodedError('t3_link_failed', link.last_error ?? `T3 Connect could not link ${link.label}.`, limit ? `In T3 Code open Settings → Connections (${T3_CONNECTIONS_PAGE}), remove an environment you no longer need, then: ${again}` : `Then open it again: ${again}`, limit ? { ...details, recovery: { title: 'Open T3 Code Connections', url: T3_CONNECTIONS_PAGE } } : details);
 }
 export async function queueT3Prewarm(ctx, ws, version) {
     try {

package/dist/agent-targets.js

@@ -8,6 +8,7 @@ import { UsageError } from "./errors.js";
 import { projectWorkspacePath } from "./agent-repository.js";
 import { withTargetLock } from "./target-lock.js";
 import { linuxApplicationDirs, linuxSupportsAcp, linuxT3Apps } from "./t3-linux.js";
+import { linuxCodexApps } from "./codex-linux.js";
 import { t3ArchiveSupportsAcp } from "./t3-asar.js";
 import { compareT3Versions } from "./t3-version.js";
 const PERSISTED_TARGETS = ['claude-desktop', 'codex-app'];
@@ -132,7 +133,11 @@ export function installedTargets(env, platform = process.platform, appDirs) {
     const clients = [hasApp('Claude.app', 'com.anthropic.claudefordesktop') && 'claude-desktop', (hasApp('Codex.app', 'com.openai.codex') || hasApp('ChatGPT.app', 'com.openai.codex')) && 'codex-app', executable('claude') && 'claude', executable('codex') && 'codex'].filter((v) => !!v);
     if (t3)
         clients.push('t3');
-    // Linux has T3 Code (0.17.0+); Claude Desktop and the Codex app are macOS apps.
+    // The Codex app on Linux (0.23.0+): the entry that handles codex:// (OpenAI's ChatGPT app for Linux, or a community
+    // build). It opens Codex Cloud conversations; its SSH environments stay a macOS target.
+    if (platform === 'linux' && linuxCodexApps(dirs, env).length > 0)
+        clients.push('codex-app');
+    // Linux has T3 Code (0.17.0+); Claude Desktop and the Codex app's SSH environments are macOS targets.
     const desktop = platform === 'darwin' ? clients.filter(c => c.endsWith('-app') || c === 'claude-desktop' || c === 't3') : platform === 'linux' && t3 ? ['t3'] : [];
     return { targets: [...desktop, 'web'], clients, versions };
 }

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.22.0";
+export declare const CLI_VERSION = "0.23.0";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;

package/dist/args.js

@@ -13,7 +13,7 @@ import { parseArgs } from 'node:util';
 import { ACCOUNT_COMMANDS } from "./account-args.js";
 import { UsageError } from "./errors.js";
 import { DEFAULT_CHOICE, MODEL_CHOICES } from "./agent-models.js";
-export const CLI_VERSION = '0.22.0';
+export const CLI_VERSION = '0.23.0';
 export const GLOBAL_OPTIONS = {
     'api-url': { type: 'string', value: '<url>', description: 'API base URL (default $SHARDFLUX_API_URL, else https://api.shardflux.dev).' },
     json: { type: 'boolean', description: 'Print machine-readable JSON on stdout (errors as JSON on stderr).' },
@@ -1289,8 +1289,8 @@ const AGENT_COMMANDS = [
             session: { type: 'string', value: '<id>', description: 'The session to move: a Claude Code session id or Codex thread id.' },
             path: { type: 'string', value: '<path>', description: 'The project folder (default: the current folder).' },
             plan: { type: 'boolean', description: 'Inspect all registered worktree paths, reference hits and file bytes before any upload.' },
-            'preserve-all-worktrees': { type: 'boolean', description: 'Preserve every registered worktree, all local refs, indices and ignored files. Reports paths and bytes; keeps a durable recovery archive.' },
-            'this-worktree-only': { type: 'boolean', description: 'Explicitly leave other registered worktrees and their local refs on this computer.' },
+            'preserve-all-worktrees': { type: 'boolean', description: 'Also bring every registered worktree, all local refs, indices and ignored files. Reports paths and bytes; keeps a durable recovery archive.' },
+            'this-worktree-only': { type: 'boolean', description: 'Move the session’s checkout only (the default): other worktrees and local refs stay on this computer.' },
             claude: { type: 'boolean', description: 'With --last or --list: Claude Code sessions only.' },
             codex: { type: 'boolean', description: 'With --last or --list: Codex sessions only.' },
             list: { type: 'boolean', description: 'List this project’s sessions on this computer, and where the moved ones continue.' },
@@ -1316,7 +1316,7 @@ const AGENT_COMMANDS = [
         },
     })),
     ...['status', 'enable', 'disable'].map(action => ({ path: ['agents', 'codex', action], summary: `${action} the account's billed Codex Cloud connector`, positionals: [], options: {} })),
-    { path: ['agents', 'open'], summary: 'Open a conversation (Codex Cloud or the native Claude session)', description: 'Codex opens its existing Cloud thread without waking its VM. Claude attaches its native session.', positionals: [{ name: 'agent', required: true }], options: { ...AGENT_OPTIONS, app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice).' }, in: { type: 'string', value: '<terminal|auto|claude-desktop|codex-app|web|t3>', description: 'Where to open it. auto (0.15.1+): the saved target, else a Claude conversation in Claude Desktop when it is installed, else in this terminal; web opens claude.ai. terminal (0.20.1+): a new tab of the terminal app agents targets --terminal chose, or this terminal when it is that one.' },
+    { path: ['agents', 'open'], summary: 'Open a conversation (Codex Cloud or the native Claude session)', description: 'Codex opens its existing Cloud thread without waking its VM. Claude attaches its native session.', positionals: [{ name: 'agent', required: true }], options: { ...AGENT_OPTIONS, original: { type: 'boolean', description: 'Open the original Codex Cloud history after a connector change.' }, history: { type: 'string', value: '<thread-id>', description: 'Open an earlier thread listed in the Cloud conversation history.' }, app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice).' }, in: { type: 'string', value: '<terminal|auto|claude-desktop|codex-app|web|t3>', description: 'Where to open it. auto (0.15.1+): the saved target, else a Claude conversation in Claude Desktop when it is installed, else in this terminal; web opens claude.ai. terminal (0.20.1+): a new tab of the terminal app agents targets --terminal chose, or this terminal when it is that one.' },
             window: { type: 'boolean', description: 'With --in terminal: a new window of the terminal app instead of a tab (0.20.1+).' } } },
     { path: ['agents', 'terminal-run'], hidden: true, summary: 'Run a command in the terminal app agents targets --terminal chose (0.20.1+)', positionals: [{ name: 'command', required: true, variadic: true }], options: {
             cwd: { type: 'string', value: '<path>', description: 'The folder the new tab starts in (default the current folder).' },
@@ -1353,10 +1353,11 @@ const CLI_PROXY_COMMANDS = [
     { path: ['cli-proxy', 'import'], summary: 'Move CLIProxyAPI from this computer into your account, reachable at 127.0.0.1:8317 everywhere', description: `${CLI_PROXY_HELP} Import brings your config and logins over, stops the local copy (one copy refreshes each login), and connects this computer and your machine template. On a second computer it connects that computer.`, positionals: [], options: {
             config: { type: 'string', value: '<path>', description: 'Your CLIProxyAPI config file (default: the one the running CLIProxyAPI uses, else the usual locations).' },
             yes: { type: 'boolean', description: 'Stop the local CLIProxyAPI without asking.' },
-            use: { type: 'string', multiple: true, value: '<email|file>', description: 'The login that is active for its provider when this computer has several (repeatable, one per provider). Default: the hub’s active login, else the oldest.' },
+            use: { type: 'string', multiple: true, value: '<email|file>', description: 'Serve its provider with only this login; the provider’s others are kept, disabled (repeatable, one per provider). Default: every login as it is on this computer.' },
         }, examples: ['shard cli-proxy import', 'shard cli-proxy'] },
-    { path: ['cli-proxy', 'use'], summary: 'Make a login its provider’s active one in your hosted CLIProxyAPI', positionals: [{ name: 'login', required: true }], options: {},
-        examples: ['shard cli-proxy use ana@example.com'] },
+    { path: ['cli-proxy', 'use'], summary: 'Choose which logins your hosted CLIProxyAPI uses: one for its provider, or all', description: 'Your hosted CLIProxyAPI routes requests across its enabled logins as its config says. `use <login>` keeps only that login enabled for its provider (the others stay in the hub, disabled); `use --all` enables every login again.', positionals: [{ name: 'login' }], options: {
+            all: { type: 'boolean', description: 'Enable every login; the hub routes across them as its config says.' },
+        }, examples: ['shard cli-proxy use ana@example.com', 'shard cli-proxy use --all'] },
     { path: ['cli-proxy', 'export'], summary: 'Bring your logins back to this computer and stop the hosted CLIProxyAPI', description: 'The hosted copy stops first, so only this computer refreshes your logins from then on. Its logins, as last refreshed, go to the auth folder the import took them from (0600), this computer stops forwarding 127.0.0.1:8317, and the command that starts your local CLIProxyAPI is shown. shard cli-proxy import moves them back.', positionals: [], options: {
             yes: { type: 'boolean', description: 'Do it without asking.' },
         } },

package/dist/cli-proxy-forward.d.ts

@@ -13,8 +13,6 @@ export interface ForwarderOptions {
      * for once, so a URL that stays invalid is answered as is.
      */
     renew?: () => Promise<void>;
-    /** Called as each request (or upgrade) arrives, before it is forwarded: the hub is about to be awake. */
-    onRequest?: () => void;
     host?: string;
     port?: number;
     /** How long one request may be retried for (default 60 s, plus the time a repair takes). */

package/dist/cli-proxy-forward.js

@@ -97,8 +97,8 @@ export class CliProxyForwarder {
                 this.dropIdleConnections();
             tick = now;
         }, 5_000).unref();
-        this.#server = createServer((req, res) => { this.#arrived(); void this.#handle(req, res); });
-        this.#server.on('upgrade', (req, socket, head) => { this.#arrived(); void this.#upgrade(req, socket, head); });
+        this.#server = createServer((req, res) => void this.#handle(req, res));
+        this.#server.on('upgrade', (req, socket, head) => void this.#upgrade(req, socket, head));
         // Long streams (SSE, Responses) must not be cut by the server's own timeouts.
         this.#server.requestTimeout = 0;
         this.#server.headersTimeout = 60_000;
@@ -327,13 +327,6 @@ export class CliProxyForwarder {
             delay = Math.min(delay * 2, 8000);
         }
     }
-    /** onRequest never fails or delays a request. */
-    #arrived() {
-        try {
-            this.#o.onRequest?.();
-        }
-        catch { /* the hook is advisory */ }
-    }
     async #handle(req, res) {
         if (pathOnly(req.url) === IDENTITY_PATH) {
             const info = this.#o.hub();