@shardflux/cli 0.20.0 → 0.23.0

package/dist/agent-setup.d.ts

@@ -5,25 +5,36 @@
  */
 export declare const AGENT_SHELL_VARIABLES: readonly ["CLAUDECODE", "CODEX_SANDBOX", "CODEX_THREAD_ID", "CURSOR_AGENT", "GEMINI_CLI"];
 export declare function codingAgentShell(env: Record<string, string | undefined>): boolean;
-export declare const SETUP_QUESTION = "Is Shardflux for a SaaS platform (your product runs VMs for its own customers through the API, SDK or MCP), or for your personal setup (your own cloud coding agents: each Claude or Codex conversation gets its own VM)?";
+/**
+ * How the agent runs the setup (0.20.1+): it does the work, the person only decides. Onboarding testers (2026-10-12)
+ * found agents handing them commands, links and codes, writing paragraphs and asking open questions.
+ */
+export declare const SETUP_RULES: readonly ["Do every permitted step yourself: run each command and open each link. Never ask your user to paste a secret or sign-in code into the chat.", "Your user answers your questions, agrees to the Terms, approves sign-ins in the browser tabs shard opens, and types secrets into the page shard opens (you never see them).", "If your permission system or auto-mode classifier refuses an action, stop that action. Do not change permissions, wrap it in a script or use another tool to bypass the refusal. Explain the reason and give your user the exact refused command to run in their own terminal; continue independent permitted steps.", "After a refused action, ask for only its non-secret result and resume permitted steps when your user confirms it. Never ask for credentials, credential files or raw logs. Plugin installation needs confirmation that the plugin is installed; machine opening needs its workspace key, not local files or environment variables.", "To check saved account state without printing credentials, use shard setup --guide --json: guide.signed_in.email and guide.api_key_saved. It is a local check, not proof that a key works. If reading setup output or checking state is refused, have your user run this command and confirm those fields; do not read redirected output or credential files instead.", "A command exiting successfully is not proof of setup. Check its non-secret result and the requested behavior; keep any blocked or unobserved step unverified.", "Ask one question at a time as multiple choice, recommended answer first (use your question tool if you have one).", "Keep each message to one or two short sentences: what you are doing or what you need, never how it works.", "Commands that wait for your user in the browser (sign-ins, --ask) take up to 10 minutes: run them with a long timeout or in the background, and tell your user once what to do there."];
+export declare const SETUP_QUESTION = "What are you setting up Shardflux for?";
+/** The answers to SETUP_QUESTION, the usual one first. */
+export declare const SETUP_CHOICES: readonly ["Your own cloud coding agents: each Claude or Codex conversation gets its own VM", "Your product: it runs VMs for its customers through the API, SDK or MCP"];
 export declare const AGENT_SETUP_DOCS = "https://docs.shardflux.dev/guides/agent-setup.md";
-/** One step of a path: what it does, what to ask the user first (if anything), and the commands in order. */
+/** One step of a path: what it does, the one question to ask first (if any) with its answers, and the commands. */
 export interface GuideStep {
     step: string;
     ask?: string;
+    /** Multiple-choice answers to `ask`, the recommended one first. */
+    choices?: string[];
     commands: string[];
     note?: string;
 }
 /** What `shard setup --guide --json` prints. */
 export interface SetupGuide {
+    rules: string[];
     question: string;
+    choices: string[];
     signed_in: {
         email: string | null;
     } | null;
     api_key_saved: boolean;
     account: GuideStep;
-    saas: GuideStep[];
     personal: GuideStep[];
+    saas: GuideStep[];
     terms_url: string;
     privacy_url: string;
     docs: string;

package/dist/agent-setup.js

@@ -1,13 +1,16 @@
 /**
- * Setting Shardflux up from a coding agent (0.17.1+): the one question the agent asks its user first, and the ordered
- * steps of both answers. `shard setup --guide` prints it; so does a bare `shard` without a terminal or in a coding
- * agent's shell, where the command center would wait for keys nobody presses. Local only: no network call and nothing
- * to answer, so it returns at once.
+ * Setting Shardflux up from a coding agent (0.17.1+): how the agent runs it, the one question it asks first, and the
+ * ordered steps of both answers. `shard setup --guide` prints it; so does a bare `shard` without a terminal or in a
+ * coding agent's shell, where the command center would wait for keys nobody presses. Local only: no network call and
+ * nothing to answer, so it returns at once.
  *
- * - SaaS platform: the user's product runs VMs for its own customers (API, SDK, MCP). An account, an API key, the
+ * - Own cloud coding agents (the usual answer): sign in, connect Claude and Codex, set the machine up from this
+ *   computer, choose where conversations open, set up the project and open the first conversation (0.20.1+).
+ * - A product (SaaS platform) running VMs for its own customers (API, SDK, MCP): an account, an API key, the
  *   integration and templates for the customers' workspaces; no agent sign-ins, menu bar or machine.
- * - Personal setup: the user's own cloud coding agents. Sign in, connect Claude and Codex, build the machine from what
- *   the user asks for, set up the project and hand over `shard ./`.
+ *
+ * The agent does permitted steps; the person answers multiple-choice questions, approves browser sign-ins and types
+ * secrets into the page shard opens. A real permission refusal requires a precise user handoff (SETUP_RULES).
  */
 import { legalFields } from "./legal.js";
 /**
@@ -19,7 +22,27 @@ export const AGENT_SHELL_VARIABLES = ['CLAUDECODE', 'CODEX_SANDBOX', 'CODEX_THRE
 export function codingAgentShell(env) {
     return AGENT_SHELL_VARIABLES.some((name) => (env[name]?.trim() ?? '') !== '');
 }
-export const SETUP_QUESTION = 'Is Shardflux for a SaaS platform (your product runs VMs for its own customers through the API, SDK or MCP), or for your personal setup (your own cloud coding agents: each Claude or Codex conversation gets its own VM)?';
+/**
+ * How the agent runs the setup (0.20.1+): it does the work, the person only decides. Onboarding testers (2026-10-12)
+ * found agents handing them commands, links and codes, writing paragraphs and asking open questions.
+ */
+export const SETUP_RULES = [
+    'Do every permitted step yourself: run each command and open each link. Never ask your user to paste a secret or sign-in code into the chat.',
+    'Your user answers your questions, agrees to the Terms, approves sign-ins in the browser tabs shard opens, and types secrets into the page shard opens (you never see them).',
+    'If your permission system or auto-mode classifier refuses an action, stop that action. Do not change permissions, wrap it in a script or use another tool to bypass the refusal. Explain the reason and give your user the exact refused command to run in their own terminal; continue independent permitted steps.',
+    'After a refused action, ask for only its non-secret result and resume permitted steps when your user confirms it. Never ask for credentials, credential files or raw logs. Plugin installation needs confirmation that the plugin is installed; machine opening needs its workspace key, not local files or environment variables.',
+    'To check saved account state without printing credentials, use shard setup --guide --json: guide.signed_in.email and guide.api_key_saved. It is a local check, not proof that a key works. If reading setup output or checking state is refused, have your user run this command and confirm those fields; do not read redirected output or credential files instead.',
+    'A command exiting successfully is not proof of setup. Check its non-secret result and the requested behavior; keep any blocked or unobserved step unverified.',
+    'Ask one question at a time as multiple choice, recommended answer first (use your question tool if you have one).',
+    'Keep each message to one or two short sentences: what you are doing or what you need, never how it works.',
+    'Commands that wait for your user in the browser (sign-ins, --ask) take up to 10 minutes: run them with a long timeout or in the background, and tell your user once what to do there.',
+];
+export const SETUP_QUESTION = 'What are you setting up Shardflux for?';
+/** The answers to SETUP_QUESTION, the usual one first. */
+export const SETUP_CHOICES = [
+    'Your own cloud coding agents: each Claude or Codex conversation gets its own VM',
+    'Your product: it runs VMs for its customers through the API, SDK or MCP',
+];
 export const AGENT_SETUP_DOCS = 'https://docs.shardflux.dev/guides/agent-setup.md';
 const { terms_url: TERMS, privacy_url: PRIVACY } = legalFields();
 export function setupGuide(state) {
@@ -27,46 +50,61 @@ export function setupGuide(state) {
         ? { step: 'Account', commands: ['shard setup --json'], note: `Signed in${state.email ? ` as ${state.email}` : ''}. shard setup saves the organization, project and API key (safe to run again).` }
         : {
             step: 'Account',
-            ask: `Do you agree to the Terms of Service (${TERMS}) and the Privacy Policy (${PRIVACY})? Continue once they do.`,
+            ask: `Do you agree to the Terms of Service (${TERMS}) and the Privacy Policy (${PRIVACY})?`,
+            choices: ['Yes, I agree', 'No'],
             commands: ['shard signup --accept-terms --json'],
-            note: 'It signs up or signs in with this computer’s Codex login and saves an API key. Without a Codex login, or for an account they already have: shard auth login --browser --no-wait --json (give your user the link and the code), then shard auth login --browser --json (returns once they approved) and shard setup --json.',
+            note: 'Signs up or signs in with this computer’s Codex login. Without one, or for an existing account: shard auth login --browser --json opens the sign-in page; tell your user to approve it there (if your command times out, run it again: it waits for the same request), then shard setup --json.',
         };
     return {
+        rules: [...SETUP_RULES],
         question: SETUP_QUESTION,
+        choices: [...SETUP_CHOICES],
         signed_in: state.signedIn ? { email: state.email } : null,
         api_key_saved: state.apiKey,
         account,
-        saas: [
-            { step: 'API key for your product', commands: ['eval "$(shard env)"'], note: 'Exports SHARDFLUX_API_KEY for the SDKs, the MCP server and your product’s server. Keep it in server-side secrets, never in client code.' },
-            {
-                step: 'Integrate',
-                commands: ['npm install @shardflux/sdk', 'pip install shardflux'],
-                note: 'Or the HTTP API (https://api.shardflux.dev/v1) or the MCP server (https://mcp.shardflux.dev/mcp). Your customers’ workspaces start from a template: shard templates build template.yaml. Start at https://docs.shardflux.dev/quickstart.md',
-            },
-        ],
         personal: [
             {
                 step: 'Connect Claude and Codex',
-                ask: 'Which agents do you use: Claude, Codex or both?',
-                commands: ['shard setup --inspect --connect --json --apps claude,codex'],
-                note: 'Claude: your user runs shard agents credentials login claude in their own terminal, once (a claude.ai link and a code). Codex: codex login on this computer; --connect copies it and starts the account’s Codex remote device. Pass only the apps they use.',
+                ask: 'Which coding agents do you use?',
+                choices: ['Claude Code and Codex', 'Claude Code', 'Codex'],
+                commands: ['shard setup --inspect --json', 'shard agents credentials login claude --json', 'shard setup --inspect --connect --json --apps claude,codex'],
+                note: 'Recommend what setup --inspect finds on this computer. The Claude sign-in opens claude.ai and a page for its code in your user’s browser. Codex uses this computer’s Codex login: run codex login yourself if it is missing. Pass only the apps they use.',
+            },
+            {
+                step: 'Set up the machine',
+                ask: 'Set up your cloud machine from this computer? It copies your tools, runtimes, shell, git identity and dotfiles.',
+                choices: ['Yes, copy this computer', 'Not now'],
+                commands: ['shard machine setup --from-this-computer --json', 'shard machine setup --status --json'],
+                note: 'This computer’s Claude Code or Codex does it read-only and saves the machine, in up to 10 minutes: tell your user once, then wait. Their tools carry over once machine.state in --status is ready; when it is failed, tell them its line and run its machine.action.command. Anything else they want on it: shard machine open --json, shard ws exec <key> -- bash -lc \'<install>\', shard files write <key> <path> --ask for a secret file (your user types it in the page), then shard machine save --wait --json.',
             },
             {
-                step: 'Build the machine',
-                ask: 'What should every cloud agent start with? Languages and runtimes, CLIs and tools, dotfiles and shell, secrets and credentials, editor and agent config.',
-                commands: ['shard machine setup --from-this-computer --json', 'shard machine open --json', "shard ws exec <key> -- bash -lc '<install commands>'", 'shard files write <key> <path> --from -', 'shard machine save --wait --json'],
-                note: 'machine setup recreates this computer’s tools, runtimes, shell, git identity and dotfiles on the machine with this computer’s Claude Code or Codex, and saves it (0.20.0+). For the rest: machine open prints the machine VM’s workspace key. Install with ws exec, write dotfiles and secret files with files write (contents on standard input, never in arguments), then save: every new conversation starts from it.',
+                step: 'Choose where conversations open',
+                ask: 'Where should your conversations open?',
+                choices: ['The terminal you use now', 'Claude app', 'Codex app', 'T3 Code'],
+                commands: ['shard agents targets --json', 'shard agents targets --open-in <target> --terminal <app> --json'],
+                note: 'Offer only what targets --json lists as installed, the terminal shard runs in first (for example Ghostty, iTerm2, Warp).',
             },
             {
                 step: 'Set up the project',
-                ask: 'Which repository, which project secrets, and what does a good first run look like (tests, a dev server)?',
-                commands: ['shard ./ --json --prompt "Set up this project and run its tests"', 'shard conversations wait <conversation-id> --timeout 90', 'shard template --json'],
-                note: 'Run it in the project folder (shard ./ codex … for Codex): the conversation gets its own VM, and setup installs the dependencies and saves the project template. Run the wait again while it says Still working. Project secrets: shard secrets import --from <hsec|1password|bitwarden|keychain> NAME, or printf %s "$VALUE" | shard secrets create NAME.',
+                ask: 'Does this project need secrets (API keys, tokens)?',
+                choices: ['No', 'Yes, I’ll type them in a secure page', 'Yes, from my vault (1Password, Bitwarden, Keychain, hsec)'],
+                commands: ['shard secrets create <NAME> --ask --json', 'shard secrets import --from <vault> <item> --as <NAME> --json', 'shard ./ --json --prompt "Set up this project and run its tests"', 'shard conversations wait <conversation-id> --timeout 90', 'shard template --json'],
+                note: 'secrets create --ask opens a page where your user types the value; you only see that it was saved. Run shard ./ in the project folder (shard ./ codex … for Codex): its VM installs the dependencies and saves the project template. Run the wait again while it says Still working.',
             },
             {
-                step: 'Hand over',
+                step: 'Open the first conversation',
                 commands: ['shard ./'],
-                note: 'Your user runs it in their own terminal (shard ./ codex for Codex). Claude conversations continue on claude.ai and in the Claude app; Codex threads in the Codex app, on the web and on the phone.',
+                note: 'It opens in the app your user chose. Tell them, in one sentence, that shard ./ in any project folder starts the next one.',
+            },
+        ],
+        saas: [
+            { step: 'API key for your product', commands: ['eval "$(shard env)"'], note: 'Exports SHARDFLUX_API_KEY for the SDKs, the MCP server and your product’s server. Keep it in server-side secrets, never in client code.' },
+            {
+                step: 'Integrate',
+                ask: 'How will your product call Shardflux?',
+                choices: ['TypeScript SDK', 'Python SDK', 'HTTP API', 'MCP server'],
+                commands: ['npm install @shardflux/sdk', 'pip install shardflux'],
+                note: 'Or the HTTP API (https://api.shardflux.dev/v1) or the MCP server (https://mcp.shardflux.dev/mcp). Your customers’ workspaces start from a template: shard templates build template.yaml. Start at https://docs.shardflux.dev/quickstart.md',
             },
         ],
         terms_url: TERMS,
@@ -94,23 +132,27 @@ function stepText(n, s) {
     const head = `${n}. ${s.step}.${s.ask ? ` Ask: ${s.ask}` : ''}`;
     return [
         `  ${wrap(head, '     ')}`,
+        ...(s.choices ? [`     ${wrap(`Choices: ${s.choices.join(' | ')}`, '     ', 96)}`] : []),
         ...s.commands.map((c) => `       ${c}`),
         ...(s.note ? [`     ${wrap(s.note, '     ', 96)}`] : []),
     ].join('\n');
 }
 export function setupGuideText(g) {
     return [
-        'Set up Shardflux. Ask your user one question first:',
-        `  ${wrap(g.question, '  ')}`,
+        'Set up Shardflux for your user. How:',
+        ...g.rules.map((r) => `  - ${wrap(r, '    ', 98)}`),
         '',
-        stepText(1, g.account),
+        'First ask, as multiple choice:',
+        `  ${wrap(`${g.question} Choices: ${g.choices.join(' | ')}`, '  ')}`,
         '',
-        'SaaS platform:',
-        ...g.saas.map((s, i) => stepText(i + 2, s)),
+        stepText(1, g.account),
         '',
-        'Personal setup:',
+        'Own cloud coding agents:',
         ...g.personal.map((s, i) => stepText(i + 2, s)),
         '',
+        'Product (SaaS platform):',
+        ...g.saas.map((s, i) => stepText(i + 2, s)),
+        '',
         `Every step in detail: ${g.docs}. Every command: shard --help.`,
     ].join('\n') + '\n';
 }

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,24 +5,26 @@ 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 } from 'node:path';
+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, openT3, saveOpenIn, startSshThread, t3Install, t3NotInstalled, t3OpenFailed, t3Status } from "./t3-mode.js";
+import { openInChoices, openInTargets, openT3, saveOpenIn, startSshThread, t3Install, t3NotInstalled, t3OpenFailed, t3Status } from "./t3-mode.js";
 import { openT3Conversation, t3Fields, withT3Context } from "./t3-launch.js";
-import { conversationPooled, pooledNeedsT3, targetsAccounts } from "./account-pool.js";
+import { targetsAccounts } from "./account-pool.js";
+import { detectTerminals, openInTerminal, parseTerminalChoice, reportTerminalOpen, saveTerminalChoice, terminalName, terminalReport } from "./terminal-apps.js";
 const missing = (e) => e instanceof ShardfluxApiError && e.status === 404;
 const keyOf = (ref) => ref.includes('/') ? ref : `${projectIdentity('./').slug}/${ref}`;
 /** How long opening a Claude conversation this computer just started waits for Claude to publish its Remote Control URL. */
@@ -220,22 +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 pooled thread (0.18.0+) has no provider login on its session: it opens remotely in T3 Code.
-    if (conversation && conversationPooled(conversation)) {
-        if (!detected.targets.includes('t3'))
-            throw pooledNeedsT3(ref);
-        return openT3Conversation(ctx, ref, values);
-    }
     // A conversation whose VM was removed restores into a fresh one first (0.18.1+).
     let ws;
     if (conversation) {
@@ -257,7 +260,7 @@ const openTarget = (target) => async (ctx, values, [ref = 'main']) => {
         await ensureCloudClaude(ctx, ws);
     if (target === 'web') {
         const url = await remoteControlUrl(ctx, ws, conversation);
-        if (!ctx.json && !openUrl(url, ctx.io.env))
+        if (!ctx.json && !(await openUrl(url, ctx.io.env)))
             throw new Error(`could not open ${url}`);
         out(ctx, `${url}\n`, { target, workspace: ws.data, url, ...(conversation ? { conversation_id: conversation.id } : {}) });
         return 0;
@@ -274,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'
@@ -296,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 {
@@ -327,7 +338,7 @@ export const T3_CONNECTIONS_PAGE = 't3code://app/settings/connections';
  */
 async function linkT3Phone(ctx, ws) {
     try {
-        const { link, signIn, needsLogin } = await t3PhoneLink(ctx, ws.id);
+        const { link, signIn, needsLogin } = await t3PhoneLink(ctx, ws.id, ws.data.project_id);
         return { line: t3LinkLine(link, signIn, needsLogin), link: signIn ? { ...link, sign_in: { ...link.sign_in, ...signIn } } : needsLogin ? { ...link, needs_login: true } : link };
     }
     catch (error) {
@@ -343,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);
     }
-    return phone;
+}
+/**
+ * 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);
+    }
+    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 {
@@ -410,9 +436,18 @@ export const TARGET_HANDLERS = {
         const accounts = ctx.json ? targetsAccounts(ctx) : undefined;
         const project = targetsProject(ref, typeof values.path === 'string' ? values.path : undefined);
         const t3 = t3Status(ctx, { project, lastUsed: true });
+        // Terminals (0.20.1+): the installed ones, the one this runs in, and the app terminal conversations open in.
+        const terminals = detectTerminals(ctx.io.env, process.platform, { spotlight: true });
+        const terminal = typeof values.terminal === 'string' ? parseTerminalChoice(values.terminal, terminals) : undefined;
         if (typeof values['open-in'] === 'string')
             saveOpenIn(ctx, values['open-in'], t3, found.clients);
-        const detected = { ...found, t3, open_in: openInChoices(ctx, project, { clients: found.clients }), ...(accounts ? { accounts: await accounts } : {}) };
+        if (terminal !== undefined)
+            saveTerminalChoice(ctx.store.dir, terminal);
+        const terminalFields = terminalReport(ctx.store.dir, ctx.io.env, terminals);
+        // open_in_targets (0.21.1+): every place each app's conversations can open from this computer, so a client offers
+        // exactly what --open-in takes.
+        const detected = { ...found, t3, open_in: openInChoices(ctx, project, { clients: found.clients }),
+            open_in_targets: { claude: [...openInTargets('claude')], codex: [...openInTargets('codex')] }, ...terminalFields, ...(accounts ? { accounts: await accounts } : {}) };
         const targets = new AgentTargets(ctx.io.env, ctx.store.dir);
         const key = ref ? keyOf(ref) : undefined;
         const before = values.remove === true ? await targets.configure(undefined, ctx.apiUrl, [], false, ctx.signal) : [];
@@ -421,7 +456,8 @@ export const TARGET_HANDLERS = {
             : [];
         const detection = `${detected.clients.join(', ') || 'No installed agent clients'}\nOpen targets: ${detected.targets.join(', ')}\n` +
             (t3.installed ? `T3 Code ${t3.version ?? ''}: ${t3.mode === 'acp' ? 'Shardflux provider' : 'SSH environments'}, ${t3.connected ? 'connected' : 'not connected'}\n`.replace(' :', ':') : '') +
-            `New conversations open in: Claude → ${detected.open_in.claude}, Codex → ${detected.open_in.codex}\n`;
+            `New conversations open in: Claude → ${detected.open_in.claude}, Codex → ${detected.open_in.codex}\n` +
+            (terminalFields.terminal ? `Terminal conversations open in: ${terminalName(terminalFields.terminal.id)} (${terminalFields.terminal.mode === 'tab' ? 'a new tab' : 'a new window'}${terminalFields.terminal.saved ? '' : ', automatic'})\n` : '');
         if (values.remove === true) {
             const removed = before.filter(e => !entries.some(n => n.host === e.host));
             out(ctx, removed.length ? `Removed ${removed.map(e => `${e.workspace} (${e.host})`).join(', ')} from ${targetFiles(targets, removed).map(f => tilde(targets, f)).join(', ')}\n` : 'No managed targets to remove.\n', { ...detected, entries, removed, models: MODEL_CHOICES });
@@ -438,6 +474,12 @@ export const TARGET_HANDLERS = {
             ['claude-desktop', 'codex-app', 't3'].filter(t => t === 't3' ? !t3Installed : !entry.targets.includes(t)).map(t => `  ${{ 'claude-desktop': 'Claude Desktop', 'codex-app': 'Codex app', t3: 'T3 Code' }[t].padEnd(15)} not installed on this computer\n`).join(''), { ...detected, entries, configured: configured.map(({ target, file, name }) => ({ target, file, name })), models: MODEL_CHOICES });
         return Promise.resolve(0);
     },
+    /** An app's own commands (sign-ins, the command center) in the person's terminal app (0.20.1+, the menu bar). */
+    async 'agents terminal-run'(ctx, values, argv) {
+        const cwd = typeof values.cwd === 'string' ? resolve(values.cwd) : process.cwd() !== '/' ? process.cwd() : ctx.io.env.HOME || process.cwd();
+        reportTerminalOpen(ctx, await openInTerminal(ctx.store.dir, ctx.io.env, argv, { cwd, window: values.window === true }));
+        return 0;
+    },
     'agents open claude-desktop': openTarget('claude-desktop'),
     'agents open codex-app': openTarget('codex-app'),
     'agents open t3': openTarget('t3'),

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.20.0";
+export declare const CLI_VERSION = "0.23.0";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;