@shardflux/cli 0.16.0 → 0.18.0-next.4

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # Changelog
 
+## 0.17.0 (not yet published)
+
+- Linux (Ubuntu 24.04, x64 and arm64): bare `shard` opens the Shardflux app in a graphical session. The optional CPU package installs without npm install scripts, adds Shardflux to the app grid, and starts at login. Headless sessions keep terminal onboarding. The systemd user helper keeps the live twin, files and conversation mirrors running; `shard device requests`, `shard device approve <id>` and `shard device deny <id>` handle local approvals.
+- The Ubuntu desktop app includes the custom tray panel, launcher capture and project/model menus, all Settings panes, local device and credential approval panels, notifications with actions, file downloads and packaged-app updates. `shard device approve --always` remembers matching in-project requests; outside-folder requests remain one-time approvals.
+- T3 Code on Linux: `shard` finds T3 Code installed from its .deb or AppImage (and AppImageLauncher, Gear Lever,
+  flatpak and snap entries), registers the Shardflux provider in it, shows it in onboarding, and opens it from its
+  desktop entry. `shard agents new --in t3`, `shard agents open t3` and `shard agents targets --open-in` work as on
+  macOS: a T3 build with ACP providers starts each thread on its Shardflux provider in a cloud VM of its own, and T3
+  Code 0.0.45 opens the project VM as an SSH environment. `shard agents targets --json` reports it under `t3`
+  (`last_used_at`: when T3 last started). The Shardflux provider is also recognized in the latest T3 nightlies on
+  macOS.
+
+- A Codex project opens in T3 Code without a Claude sign-in (T3 shows Claude as signed out, and says how to sign in), and `--json` names the T3 Connect sign-in `shard` started for the phone (`t3_link.sign_in`, or `t3_link.needs_login` when this computer has no session).
+- A conversation settles when its turn ends (`done` or `unresolved` right away) and its VM takes the next message.
+  `shard agents open`, `shard ./ --resume` and ACP reattach to that VM instead of resuming the conversation into a new
+  one, `shard agents computers` and `--on` offer its computer for new threads, Try locally keeps syncing across turns,
+  and the transcript mirror reads it once per change. A conversation has ended once its VM is removed, or it is
+  archived or discarded.
+- The menu bar keeps running and updating your global install: running `shard` from a source checkout, a project's
+  `node_modules` or `npx` no longer replaces the install it records (`SHARDFLUX_RECORD_INSTALL=1` records any run).
+- `--model <model>` and `--effort <level>` on `shard ./` and `shard agents new` (also with `--on` and `--in t3`)
+  (0.17.0+): a new Claude or Codex thread starts with that model and reasoning effort, such as `--model opus --effort
+  xhigh` or `--model gpt-6-astra --effort high`. The conversation keeps them across resumes and moves. `--json` adds
+  `model_choice: {model, effort, applied}`; a computer whose platform predates the choice starts the thread with the
+  agent's defaults and says so once. Unknown values are refused before anything starts.
+- `shard agents targets --json` adds `models` (0.17.0+): for `claude` and `codex`, the `models` (`id`, `label`, `short`,
+  `description`), the `efforts` (`id`, `label`) and the agent's own `default` (`model`, `effort`; `null` where the
+  agent decides at start), so the menu bar and other apps show the same choices without hardcoding them.
+- T3 Code mode: `shard agents new --in t3 --prompt-file <file>` (or `--prompt`) starts the first message as a thread in
+  T3 Code and brings T3 to the front. With T3's Shardflux provider (T3 builds with ACP providers) the thread is launched
+  on the running T3 and gets its own cloud VM; with T3 Code 0.0.45 it starts on the T3 server in the project VM, or with
+  `--on <conversation|computer>` on that computer's. `--image` attaches images to the first message; `--model` and
+  `--effort` take the same choices as every new thread. `--json` returns `{ target: "t3", mode, project, t3_thread_id,
+  conversation_id, workspace, opened: true, focused: false, model, effort }` with the model and effort T3 got. A
+  requested effort that T3 did not get is `effort: null` with `effort_reason`: `not_offered` (the model has no such
+  level) or `models_not_known` (with the Shardflux provider, before this project's first conversation on this computer
+  has shown its levels). Refusals have their own codes: `t3_not_installed`, `t3_not_connected`, `t3_server_unreachable`,
+  `t3_version_unsupported`, `t3_on_not_supported`, `t3_model_unavailable`, `t3_thread_failed`, and `t3_open_failed` for
+  a thread that started while T3 Code did not open; once the workspace, conversation or thread exists their `details`
+  name its `workspace_key`, `conversation_id` and `t3_thread_id`, so a client opens it instead of starting it again.
+- `shard agents targets --json` reports T3 Code (`t3: { installed, mode, connected, version, last_used_at }`) and where
+  each app's new conversations open (`open_in: { claude, codex }`). `--open-in claude=t3,codex=t3` saves the choice
+  (Claude: terminal, claude-desktop, web or t3; Codex: codex-app or t3). Without one, T3 is the default when it is
+  connected (the Shardflux provider registered and this computer signed in; with T3 Code 0.0.45, this project set up
+  as a T3 environment from this computer) and the most recently used of the installed apps. `shard ./` and `--in auto`
+  open new conversations there, a conversation as itself. `--path <folder>` reports them for that project (as
+  `agents new --path` names it); an agent argument wins over it.
+- `shard agents open t3 <conversation>` brings the conversation's T3 thread back (`t3_thread_id`) and, like
+  `agents open t3 <workspace>`, opens T3 with `--json` too (`opened: true`).
+- JSON errors that come with a next step carry it as `error.fix`.
+- T3 Code on your phone: `shard agents new --in t3` and `shard agents open t3` also add the project to the T3 app as **Shardflux · <project>**. The first time, open the link it prints and confirm the code once; every later project appears by itself. A message from the app wakes the VM.
+- `shard cli-proxy import` moves CLIProxyAPI from this computer into your account: one hosted copy holds your Claude, Codex and other subscription logins, sleeps between requests and wakes on the next one. This computer and every new VM reach it at `http://127.0.0.1:8317`, so Claude Code (`ANTHROPIC_BASE_URL`), Codex (`base_url …/v1`) and T3 Code's usage view keep their settings; streaming responses and WebSockets pass through.
+  - The hosted copy is made from your own config: client API keys, routing, retries, model aliases and upstream keys carry over, and your management key keeps working.
+  - Your local CLIProxyAPI stops for good on the port its config names: a Homebrew service with `brew services stop`; after you confirm (`--yes` for scripts), a launchd agent (stopped, disabled, its plist set aside), a Docker container (`docker stop`) or a process. Only a program recognized as CLIProxyAPI is ever stopped; anything else on the port is named with the command to run.
+  - Your auth files move to the hub, and the local copies move to `<auth folder>.moved-to-shardflux` (0700), where no CLIProxyAPI reads them.
+  - Run it on a second computer to connect that one too: it adds only the accounts that are new to the hub, names them, and keeps the hub's settings. Every project of your account uses the same hosted copy. `--config <path>` names the config when it is somewhere else.
+  - VMs receive only the address of the hub's VM port, which serves the model routes (OpenAI, Claude, Gemini and Codex, WebSockets included) and nothing else; the hub's logins and settings are managed from the computers that set it up. A second computer's logins are matched to the hub's by account (provider plus every account, organization, workspace and project id and email the auth file names), whatever the file names, so two accounts of one email both move.
+- `shard cli-proxy export` brings your logins back to this computer: the hosted copy stops first, the logins it last refreshed are written to your auth folder (0600), this computer stops forwarding, and the command that starts your local CLIProxyAPI is shown. `shard cli-proxy import` moves them back.
+- `shard cli-proxy` shows the hosted copy: its accounts (provider and email), whether it is running or sleeping, and where it is reachable, in a VM too. It starts CLIProxyAPI again when the hub answers that nothing listens. `--json` for scripts.
+- Revoking an API key keeps the hub reachable: when its address was created with that key, the next request through this computer, `shard cli-proxy` or an import gives the hub a new address, uses it at once and passes it to every new VM.
+- On macOS the forwarder runs as the launchd agent `dev.shardflux.cli-proxy-forward` (at login, kept running, restarted when `shard` is updated). A request the hub did not receive (while it wakes or CLIProxyAPI starts again) is sent again, POST bodies included up to 32 MiB; a client that disconnects ends its request to the hub.
+- For onboarding: `detectLocalCliProxy()` and `importCliProxy(ctx)` are exported.
+
+- A finished conversation lands in your checkout as soon as its turn ends: the menu bar's helper keeps one wait per
+  active conversation and hears the finished turn the moment the conversation reports it (no polling every second).
+  Conversations that finish together for the same branch land in one go, in the order they finished.
+
 ## 0.16.0 (not yet published)
 
 - Cloud sessions are named for the work: `shard ./` starts the agent with the repository or folder name and the first
@@ -308,7 +375,6 @@
 
 ## 0.12.0 (not yet published)
 
-
 - Add `cpu-service-fresh-inputs-v1` with `fresh_env_names`: fresh owned startup hooks/children consume allowed task values while immutable CPU initialization stays credential-free. Relevant or secret inputs retain ordinary startup.
 
 - Add explicit `pasteText` clipboard replacement with an application paste chord, LF-to-Return typing repair and unchanged screenshot settling.
@@ -316,7 +382,6 @@
 Every command and option the README shows is available from the version named here. Breaking changes ship in minor
 releases and are marked **Breaking**.
 
-
 - Accept caller-supplied exact desktop pixel predicates without an environment gate. Completion uses the same frozen full frame encoded as PNG; pre-satisfied refusal and timeout return no success image. Omitted predicates retain 250 ms settling.
 - Preserve explicit `initialized_cpu` service declarations through template YAML build/export/edit transport, matching SDK0.17.0.
 

package/README.md

@@ -26,7 +26,7 @@ See the [support guide](https://github.com/shardfluxdev/community/blob/main/SUPP
 
 ## Command center (0.15.0+)
 
-Run `shard` in a terminal to see live conversations. Press **Enter** to open the selected one, **/** to search,
+On macOS, run `shard` in a terminal to see live conversations. Press **Enter** to open the selected one, **/** to search,
 **D** to expand or collapse finished conversations, and **?** for targets, logs, fork, park and Git actions.
 Press **n** to start a conversation: describe the task, confirm a local project folder, then choose Claude or Codex.
 Both the task and project are required, and the task becomes the first user-authored message. **Esc** cancels;
@@ -50,6 +50,18 @@ Bulk transfers batch writes automatically. Active transfers retain their byte po
 
 ## Install
 
+Linux (Ubuntu 24.04, x64 and arm64) and macOS are supported. On Linux, run `shard` to sign in and
+connect Claude, Codex or both (0.17.0+), then run `shard ./` in your project to attach Claude Code or Codex in place. Sign-in opens your browser;
+on a headless terminal, follow the displayed URL and device code. `--accept-terms` accepts the terms notice.
+
+The Linux helper starts automatically after setup as `~/.config/systemd/user/shardflux-helper.service`
+and restarts after a CLI update. It keeps the live twin, `~/Shardflux` files and conversation history in sync.
+Use `shard device requests`, `shard device approve <id>` or `shard device deny <id>` for local approvals;
+desktop notifications point to pending requests. On systems without a systemd user session, the helper runs
+while your `shard` commands are open. `shard agents open` opens a terminal when launched outside one, using
+`$TERMINAL`, `x-terminal-emulator` or `gnome-terminal`, or prints the attach command. The Mac app adds a menu
+bar, launcher and Settings window.
+
 ```sh
 npm i -g shardflux
 shard --help
@@ -70,14 +82,15 @@ shard ./
 
 Choose Claude Code or Codex. Claude asks for one cloud sign-in per Shardflux account; Codex uses your copied login.
 Each `shard ./` starts its own conversation VM and opens your agent’s native terminal. Later turns stay in that
-VM; `shard ./ --resume` selects a saved project conversation. Native terminal and ACP sessions receive the conversation tools for their own conversation, so the agent can fork, ask for a review, and report to its parent (0.14.0+). You can open conversations in separate terminals at the same time; each stays in the project's local history. `shard` opens the optional command center. On macOS the menu bar starts automatically the first
+VM; `shard ./ --resume` selects a saved project conversation. Native terminal and ACP sessions receive the conversation tools for their own conversation, so the agent can fork, ask for a review, and report to its parent (0.14.0+). You can open conversations in separate terminals at the same time; each stays in the project's local history. On macOS, `shard` opens the optional command center. On macOS the menu bar starts automatically the first
 time `shard` runs, with launch at login enabled; `shard menubar stop` turns it off. See [Cloud agents](https://docs.shardflux.dev/guides/cloud-agents).
 
 T3 Code uses one **Shardflux** provider; choose a Claude Code or Codex model to start that agent in the cloud.
 Model choices come from your cloud agent's session and use the same coding tools and settings as its terminal.
-The provider is registered automatically when T3 Code is installed. Choose **Sign in** on its card in T3's provider
-settings: T3 runs `shard acp --login` in its own terminal, which creates or signs in to your account (with this Mac's
-Codex login, or your email) and connects Claude Code and Codex, skipping every step that is already done (0.15.0+).
+The provider is registered automatically when T3 Code is installed, on macOS and on Linux from its .deb or AppImage
+(0.17.0+). Choose **Sign in** on its card in T3's provider settings: T3 runs `shard acp --login` in its own terminal,
+which creates or signs in to your account (with this computer's Codex login, or your email) and connects Claude Code
+and Codex, skipping every step that is already done (0.15.0+).
 With T3 Code 0.0.45, `shard agents new --in t3` adds the project as an SSH environment instead.
 
 Start another thread on a computer that is already set up (0.16.0+): it shares that conversation's installed
@@ -94,6 +107,32 @@ shard ./ --on fix-login --review             # a read-only Claude reviewer of it
 the new thread. Codex threads are Codex Cloud threads, on the web and your phone too. `shard agents list` shows each
 thread's conversation and computer.
 
+Choose the model and reasoning effort a new thread starts with (0.17.0+):
+
+```sh
+shard ./ --model opus --effort xhigh          # Claude Opus at extra-high effort
+shard ./ codex --model gpt-6-astra --effort high
+shard agents new --app claude --path ./ --model sonnet --prompt "Tidy the README" --json
+```
+
+Claude takes `fable`, `opus`, `sonnet` or `haiku` and `low`, `medium`, `high`, `xhigh` or `max`; Codex takes
+`gpt-6.1-sol`, `gpt-6-astra` or `gpt-6-luna` and the same levels plus `ultra`. `default`, or leaving the flag out,
+keeps the agent's own choice. The conversation keeps its model and effort when it is resumed or moved, and `--json`
+adds `model_choice: {model, effort, applied}`. `shard agents targets --json` lists the choices as `models`, with menu
+and pill text and the agent's own default, so apps never hardcode them. `--in t3` passes them to T3 Code.
+
+Start a thread in T3 Code from the command line (0.17.0+):
+
+```sh
+shard agents new --path . --app claude --in t3 --prompt-file task.md
+shard agents targets --open-in claude=t3,codex=t3   # shard ./ starts new conversations in T3 Code
+```
+
+The first message becomes a T3 thread and T3 comes to the front. With the Shardflux provider the thread runs in its own
+cloud VM; with T3 Code 0.0.45 it runs on the T3 server in the project's VM, or with `--on` on that computer's.
+`--image` attaches images. `shard agents targets --json` shows T3 Code's mode and where each app's new conversations
+open; `shard agents open t3 <conversation>` brings its thread back.
+
 Git fetch and push use the coding guest’s platform transport when available, preserving Git’s binary packets (0.14.0+). Older guests retain their existing transport.
 
 To try a conversation on your Mac:
@@ -104,11 +143,11 @@ shard conversations try <conversation>
 
 Your branch opens in `.shard/worktrees/<name>`, syncs both ways, and its dev servers appear at localhost.
 Ctrl-C stops local sync. Your main checkout stays available for your own work.
-Device tools ask for approval on your Mac before preparing the conversation’s local worktree. With CLI 0.15.0 and menu bar 0.3.0, Review shows the exact command, file direction, paths or port mapping; access outside the conversation folder only offers Allow once. Live transcripts stay in
+Device tools ask for approval on your computer before preparing the conversation’s local worktree. With CLI 0.15.0 and menu bar 0.3.0, Review shows the exact command, file direction, paths or port mapping; access outside the conversation folder only offers Allow once. Live transcripts stay in
 `~/.config/shardflux/conversations/`; ended sessions enter Claude Code’s or Codex’s native history. Transcript files up to 64 MiB are supported (0.14.0+).
 From 0.14.3, transcript copying runs independently of device approvals. Unknown entries are skipped, and failed copies retry with backoff; diagnostics name the conversation and affected entry.
 
-Every conversation's committed files are on your Mac too (0.16.0+, with the menu bar app running):
+Every conversation's committed files are on your computer too (with the helper running; macOS 0.16.0+, Linux 0.17.0+):
 `~/Shardflux/<repository>/<base branch>/<conversation>/` holds what each conversation changed or added, read-only,
 and updates when its branch moves. Large files are listed as `<file>.placeholder.txt`; download one with the menu
 bar's **Download** or:
@@ -1252,7 +1291,7 @@ connection it configured and the file it is in (0.13.3+).
 
 `shard agents fork` or `f` in the command center copies the whole running state into an independent workspace and
 conversation. Open in your terminal, Claude Desktop or the Codex app, and the terminal Claude conversation in
-claude.ai or mobile. Session titles start with `[SF] `. Waiting agents stay reachable on their own connections;
+claude.ai or mobile. Sessions are titled with their task and repository, like `Add CSV export · todo-app`. Waiting agents stay reachable on their own connections;
 see the [settings and billing reference](https://docs.shardflux.dev/limits#cloud-agent-reachability).
 Claude needs one cloud sign-in per account; Codex uses your copied login.
 

package/dist/agent-commands.d.ts

@@ -1,6 +1,8 @@
 import type { CellClient, PtySession, Workspace } from '@shardflux/sdk';
 import type { Ctx, Handler } from './commands.js';
 import type { Values } from './args.js';
+import type { T3Install, T3ThreadRequest } from './t3-mode.js';
+import type { ModelChoice } from './agent-models.js';
 /** `<slug>-<6 hex of sha256(identity)>`: the same repository gets the same key on every machine. */
 export declare function disambiguatedSlug(slug: string, identity: string): string;
 export declare function projectTemplate(ctx: Ctx, remote: string | null): Promise<string>;
@@ -9,7 +11,10 @@ export declare function projectTemplate(ctx: Ctx, remote: string | null): Promis
 export declare function agentPty(cell: CellClient, app: 'claude' | 'codex', agent: string, approvals: boolean, term: string, signal?: AbortSignal, place?: string, setupHash?: string, cwd?: string, ptyName?: string, onLaunch?: () => void, deferSetup?: boolean, conversation?: {
     id: string;
     session: string | null;
-}, task?: string): Promise<PtySession>;
+}, task?: string, launch?: {
+    choice?: ModelChoice;
+    help?: () => Promise<string>;
+}): Promise<PtySession>;
 /** The first non-empty line of a prompt or title, bounded; the guest makes it the task part of the session title. */
 export declare function sessionTask(text: string | undefined): string | undefined;
 export declare function terminal(ctx: Ctx, ws: Workspace, app: 'claude' | 'codex', agent: string, project: string, values: Values, setupHash?: string, cwd?: string, conversation?: {
@@ -17,6 +22,9 @@ export declare function terminal(ctx: Ctx, ws: Workspace, app: 'claude' | 'codex
     session: string | null;
     pty?: string;
     title?: string;
+    choice?: ModelChoice;
 }): Promise<number>;
 export declare const launchProject: Handler;
+/** The project VM launch; with `--in t3` a first message becomes a thread on the T3 server in it (SSH mode, 0.17.0+). */
+export declare function launchProjectWith(ctx: Ctx, values: Values, [path, explicitApp]: string[], thread?: T3ThreadRequest, install?: T3Install): Promise<number>;
 export declare const AGENT_HANDLERS: Record<string, Handler>;

package/dist/agent-commands.js

@@ -1,3 +1,4 @@
+import { linuxTerminalSession, openLinuxTerminal } from "./linux-terminal.js";
 import { repositoryName } from "./files-mirror.js";
 import { prepareSetupCache } from "./setup-cache.js";
 import { launchCodexCloud, openCodexConversation } from "./codex-cloud.js";
@@ -23,10 +24,12 @@ import { progress } from "./progress.js";
 import { rememberLaunch } from "./agent-live.js";
 import { prepareAgentMachine } from "./agent-machine.js";
 import { installedTargets } from "./agent-targets.js";
+import { openInFor } from "./t3-mode.js";
 import { openClaudeDesktopSession, openDesktopWorkspace, queueT3Prewarm } from "./agent-target-commands.js";
 import { submitInitialPrompt, prepareInitialCodexProject } from "./initial-prompt.js";
 import { conversationWorkspace, conversationsUnavailable, getConversation, listConversations, resumeConversation } from "./conversations.js";
 import { conversationTerminal } from "./conversation-terminal.js";
+import { CHOICE_PENDING, choiceReport, hasChoice, launchChoice, modelChoice, runFlags } from "./agent-models.js";
 const active = (session) => session.state === 'running' || session.state === 'starting';
 /** `<slug>-<6 hex of sha256(identity)>`: the same repository gets the same key on every machine. */
 export function disambiguatedSlug(slug, identity) {
@@ -50,7 +53,7 @@ export async function projectTemplate(ctx, remote) {
 }
 /** `place` is the repository or folder name session titles end with ("todo-app"), `task` what a new session is titled
  * with before the guest names it from its first prompt (a first prompt line or the conversation's title). */
-export async function agentPty(cell, app, agent, approvals, term, signal, place, setupHash, cwd, ptyName, onLaunch, deferSetup = false, conversation, task) {
+export async function agentPty(cell, app, agent, approvals, term, signal, place, setupHash, cwd, ptyName, onLaunch, deferSetup = false, conversation, task, launch) {
     const id = `shard-${ptyName || agent}-${app}`;
     // Arrival and changed locks queue the same durable guest job even when the
     // native agent is already alive. Setup never becomes its first user turn.
@@ -71,18 +74,19 @@ export async function agentPty(cell, app, agent, approvals, term, signal, place,
     onLaunch?.();
     let conversationArgs = [];
     if (conversation) {
-        const help = await cell.exec.run(['sf-agent', 'run', app, '--help'], { timeoutMs: 10_000, maxOutputBytes: 8192, signal });
-        if ((help.stdout + help.stderr).includes('-conversation'))
+        const help = await (launch?.help ?? runHelp(cell, app, signal))();
+        if (help.includes('-conversation'))
             conversationArgs = ['--conversation', conversation.id, ...(conversation.session ? ['--resume-session', conversation.session] : [])];
     }
-    const launch = await cell.exec.run(['sf-agent', 'run', app, '--name', agent, '--detach', ...conversationArgs, ...(ptyName ? ['--pty-name', ptyName] : []), ...(approvals ? ['--approvals'] : []), ...(setupHash ? ['--setup', '--setup-deps-hash', setupHash] : [])], {
+    // A model and effort choice reaches only a guest whose run accepts it (the caller checked).
+    const started = await cell.exec.run(['sf-agent', 'run', app, '--name', agent, '--detach', ...conversationArgs, ...(ptyName ? ['--pty-name', ptyName] : []), ...(approvals ? ['--approvals'] : []), ...(setupHash ? ['--setup', '--setup-deps-hash', setupHash] : []), ...runFlags(launch?.choice)], {
         env: { TERM: term, ...(place ? { SF_PROJECT_NAME: place, SF_REPO_NAME: place } : {}), ...(task ? { SF_TASK_TITLE: task } : {}), ...(setupHash && deferSetup ? { SF_SETUP_DEFERRED: '1' } : {}) }, timeoutMs: 30_000, maxOutputBytes: 4096, signal, ...(cwd ? { cwd } : {}),
     });
-    if (launch.exitCode !== 0)
-        throw new Error(`agent launch failed: ${launch.stderr.trim() || `exit ${launch.exitCode}`}`);
+    if (started.exitCode !== 0)
+        throw new Error(`agent launch failed: ${started.stderr.trim() || `exit ${started.exitCode}`}`);
     let result;
     try {
-        result = JSON.parse(launch.stdout);
+        result = JSON.parse(started.stdout);
     }
     catch {
         throw new Error('agent launcher returned invalid JSON');
@@ -94,6 +98,11 @@ export async function agentPty(cell, app, agent, approvals, term, signal, place,
         throw new Error(`agent exited before attach: ${session.state}`);
     return session;
 }
+/** `sf-agent run <app> --help` of this computer's guest, read at most once per launch. */
+function runHelp(cell, app, signal) {
+    let text;
+    return () => text ??= cell.exec.run(['sf-agent', 'run', app, '--help'], { timeoutMs: 10_000, maxOutputBytes: 8192, signal }).then(r => r.stdout + r.stderr);
+}
 /** The first non-empty line of a prompt or title, bounded; the guest makes it the task part of the session title. */
 export function sessionTask(text) {
     const line = text?.split(/\r?\n/).map(l => l.replace(/[\s\p{Cc}]+/gu, ' ').trim()).find(Boolean);
@@ -113,9 +122,15 @@ export async function terminal(ctx, ws, app, agent, project, values, setupHash,
             await prepareInitialCodexProject(cell, cwd, `shard-${ptyName || agent}-${app}`);
         }
         const credentialFill = await configureCredentialFill(ctx, ws);
+        // This command's --model/--effort, else the conversation's own (a relaunch keeps its model). A computer whose guest
+        // predates the choice starts the agent with its defaults, and this command says so once.
+        const help = runHelp(cell, app, ctx.signal), explicit = modelChoice(values, app);
+        const { choice, applied } = await launchChoice(explicit, conversation?.choice, !!conversation, help);
+        if (hasChoice(explicit) && !applied && !ctx.json)
+            ctx.io.stderr.write(`${CHOICE_PENDING}\n`);
         // A cold launch is remembered before it starts, so the listing can show it before the projection does (agent-live.ts).
         const term = ctx.io.env.TERM && ctx.io.env.TERM !== 'dumb' ? ctx.io.env.TERM : 'xterm-256color';
-        const session = await agentPty(cell, app, agent, values.approvals === true, term, ctx.signal, repositoryName(ws.labels.repo_remote || project), setupHash, cwd, ptyName, () => { rememberLaunch(ctx, ws.id); progress(ctx, `Starting ${app === 'claude' ? 'Claude' : 'Codex'} in ${ws.key}…`); }, true, conversation && { id: conversation.id, session: conversation.session }, sessionTask(typeof values.initialPrompt === 'string' ? values.initialPrompt : conversation?.title));
+        const session = await agentPty(cell, app, agent, values.approvals === true, term, ctx.signal, repositoryName(ws.labels.repo_remote || project), setupHash, cwd, ptyName, () => { rememberLaunch(ctx, ws.id); progress(ctx, `Starting ${app === 'claude' ? 'Claude' : 'Codex'} in ${ws.key}…`); }, true, conversation && { id: conversation.id, session: conversation.session }, sessionTask(typeof values.initialPrompt === 'string' ? values.initialPrompt : conversation?.title), { ...(choice ? { choice } : {}), help });
         // A new conversation's guest can start the agent before this command reaches it, so the launch above never ran.
         // Remember it either way: listing and `agents open` then read the guest until the projection lists the session.
         rememberLaunch(ctx, ws.id);
@@ -136,7 +151,9 @@ export async function terminal(ctx, ws, app, agent, project, values, setupHash,
         if (!attach) {
             await preparation;
             // conversation (0.16.0+): which conversation this session is, also when its computer hosts several threads.
-            ctx.io.stdout.write(json({ workspace: ws.data, session, ...(conversation ? { conversation: { id: conversation.id } } : {}), ...(typeof values.initialPrompt === 'string' ? { initial_prompt: { submitted: true } } : {}) }));
+            // model_choice (0.17.0+): the requested model and effort, and whether this thread started with them.
+            ctx.io.stdout.write(json({ workspace: ws.data, session, ...(conversation ? { conversation: { id: conversation.id } } : {}), ...(typeof values.initialPrompt === 'string' ? { initial_prompt: { submitted: true } } : {}),
+                ...(hasChoice(explicit) ? { model_choice: choiceReport(explicit, applied) } : {}) }));
             return 0;
         }
         ctx.io.stderr.write(`Shardflux · ${ws.key}\nDetach: Ctrl-] then d\n`);
@@ -177,7 +194,9 @@ async function syncCredentials(ctx) {
             throw new Error('agent credentials sync failed');
     }
 }
-export const launchProject = async (ctx, values, [path = './', explicitApp]) => {
+export const launchProject = (ctx, values, args) => launchProjectWith(ctx, values, args);
+/** The project VM launch; with `--in t3` a first message becomes a thread on the T3 server in it (SSH mode, 0.17.0+). */
+export async function launchProjectWith(ctx, values, [path = './', explicitApp], thread, install) {
     if (explicitApp && explicitApp !== 'claude' && explicitApp !== 'codex')
         throw new UsageError('agent app must be claude or codex');
     let like = typeof values.like === 'string' ? await resolveWorkspace(ctx, values.like) : undefined;
@@ -189,8 +208,12 @@ export const launchProject = async (ctx, values, [path = './', explicitApp]) =>
     if (target && (!['claude-desktop', 'codex-app', 't3'].includes(target) || !detected?.targets.includes(target)))
         throw new UsageError(`${target} is not an installed desktop target`);
     const app = explicitApp ?? store.app(projectKey, like?.labels.app === 'codex' ? 'codex' : 'claude');
-    if (target === 'codex-app' || (app === 'codex' && !like && values.in === undefined))
+    // A typo in --model or --effort is refused before anything starts; T3 Code reads the same values (0.17.0+).
+    const choice = modelChoice(values, target === 'codex-app' ? 'codex' : app);
+    if (target === 'codex-app' || (app === 'codex' && !like && values.in === undefined && !linuxTerminalSession(ctx, values)))
         return launchCodexCloud(ctx, values, path);
+    if (target === 'claude-desktop' && hasChoice(choice))
+        ctx.io.stderr.write('Claude Desktop starts the session with the model chosen in the app.\n');
     const agent = typeof values.name === 'string' ? values.name : 'main';
     if (!/^[a-z0-9][a-z0-9._-]{0,63}$/.test(agent))
         throw new UsageError('agent name must match ^[a-z0-9][a-z0-9._-]{0,63}$');
@@ -236,8 +259,13 @@ export const launchProject = async (ctx, values, [path = './', explicitApp]) =>
         await queueT3Prewarm(ctx, ws, detected.versions.t3);
     if (app === 'claude' && !claudeReady)
         await loginClaudeInWorkspace(ctx, ws);
+    // T3 lists both agents; a Codex project still opens when Claude is not signed in (T3 shows Claude as signed out).
     if (target === 't3' && app === 'codex')
-        await ensureCloudClaude(ctx, ws);
+        await ensureCloudClaude(ctx, ws).catch((error) => {
+            if (!(error instanceof UsageError))
+                throw error;
+            ctx.io.stderr.write(`Claude Code in T3: ${error.message}\n`);
+        });
     if (!(await savedMachine(ctx))?.template)
         await syncAgentConfig(ctx, ws);
     // Seed once; two-way sync is scoped to explicit Try locally worktrees.
@@ -251,15 +279,17 @@ export const launchProject = async (ctx, values, [path = './', explicitApp]) =>
                 throw new Error(`project setup could not be queued: ${setup.stderr.trim() || `exit ${setup.exitCode}`}`);
         }
         store.saveTarget(projectKey, target);
-        return openDesktopWorkspace(ctx, ws, target, detected?.versions.t3, true);
+        return openDesktopWorkspace(ctx, ws, target, detected?.versions.t3, true, thread, install);
     }
     await prepareAgentMachine(ctx, ws);
     return await terminal(ctx, ws, app, agent, projectKey, values, prepared?.setupHash);
-};
+}
 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');
+        if (process.platform === 'linux' && !ctx.json && !ctx.io.stdin.isTTY && values.detach !== true && (values.in === undefined || values.in === 'terminal'))
+            return openLinuxTerminal(ctx, agent, typeof values.app === 'string' ? values.app : undefined);
         let resolvedConversation;
         if (/^conv_[a-z0-9]{26}$/.test(agent)) {
             resolvedConversation = await getConversation(ctx, agent);
@@ -274,7 +304,27 @@ export const AGENT_HANDLERS = {
             const store = new AgentStateStore(ctx.store.dir);
             const app = values.app ?? resolvedConversation?.harness ?? ws.labels.shard_app ?? ws.labels.app ?? store.app(project);
             const detected = installedTargets(ctx.io.env);
-            const saved = store.read().projects?.[project]?.target ??
+            // open_in (0.17.0+): a choice saved with `agents targets --open-in`, or T3 when it is the default, comes first.
+            // A conversation opens as itself (its id and session), as the fallbacks below open it.
+            const choice = app === 'claude' || app === 'codex' ? openInFor(ctx, ws.labels.shard_project || ws.key.split('/')[0], { clients: detected.clients })[app] : undefined;
+            const chosen = choice && (choice.saved || choice.target === 't3') ? choice.target : undefined;
+            const opened = resolvedConversation?.id ?? ws.key;
+            if (chosen === 't3' || chosen === 'web') {
+                const { HANDLERS } = await import("./handlers.js");
+                return HANDLERS[`agents open ${chosen}`](ctx, { ...values, in: chosen }, [opened]);
+            }
+            if (chosen === 'claude-desktop' && app === 'claude')
+                return openClaudeDesktopSession(ctx, ws, resolvedConversation);
+            if (chosen === 'terminal' && app === 'claude') {
+                if (ctx.json) {
+                    out(ctx, `shard agents open ${opened}\n`, { target: 'terminal', workspace: ws.data, command: ['shard', 'agents', 'open', opened] });
+                    return 0;
+                }
+                const next = { ...values };
+                delete next.in;
+                return AGENT_HANDLERS['agents open'](ctx, next, [opened]);
+            }
+            const saved = chosen === 'codex-app' ? undefined : store.read().projects?.[project]?.target ??
                 (project.startsWith('file://') ? store.read().projects?.[new URL(project).pathname]?.target : undefined);
             // 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.
@@ -295,7 +345,6 @@ export const AGENT_HANDLERS = {
             if (detected.clients.includes('claude-desktop')) {
                 return openClaudeDesktopSession(ctx, ws, resolvedConversation);
             }
-            const opened = resolvedConversation?.id ?? ws.key;
             if (ctx.json) {
                 // An app runs this in the person's terminal (the menu bar opens Terminal with it).
                 out(ctx, `shard agents open ${opened}\n`, { target: 'terminal', workspace: ws.data, command: ['shard', 'agents', 'open', opened] });

package/dist/agent-models.d.ts

@@ -0,0 +1,61 @@
+import type { Values } from './args.js';
+export type ModelApp = 'claude' | 'codex';
+export interface Choice {
+    id: string;
+    label: string;
+}
+/**
+ * `label` is the menu text, `short` the pill text and `description` what the model is for. A model may take fewer
+ * effort levels than its app (its own `efforts`, ids); without it, all of the app's.
+ */
+export interface ModelOption extends Choice {
+    short: string;
+    description?: string;
+    efforts?: string[];
+}
+/**
+ * `default` names what the agent starts with when no flag is sent, as concrete ids, or null where the agent decides at
+ * start: Claude Code resolves its default model and effort from the account's plan and organization, and Codex its
+ * default effort from the model catalog it fetches with the account's login. A Codex Cloud thread starts with
+ * gpt-6.1-sol (services/guest-agent/internal/codexcloud CloudModel), which is also Codex 0.160.0's first model.
+ */
+export interface AppModels {
+    models: ModelOption[];
+    efforts: Choice[];
+    default: {
+        model: string | null;
+        effort: string | null;
+    };
+}
+export declare const DEFAULT_CHOICE = "default";
+/** Claude Code `--model <alias>` and `--effort <level>`; Codex `-m <model>` and `-c model_reasoning_effort=<level>`. */
+export declare const MODEL_CHOICES: Readonly<Record<ModelApp, AppModels>>;
+/** What a thread starts with: absent fields are the agent's own default (no flag). */
+export interface ModelChoice {
+    model?: string;
+    effort?: string;
+}
+/** `--model` and `--effort` for this app, checked against its list. Throws a usage error for anything else. */
+export declare function modelChoice(values: Values, app: ModelApp): ModelChoice;
+export declare const hasChoice: (c: ModelChoice | undefined) => c is ModelChoice;
+/** The guest's `sf-agent run` flags for a choice (sf-agent maps them to the agent's own flags). */
+export declare function runFlags(c: ModelChoice | undefined): string[];
+/** Whether a guest's `sf-agent run --help` lists the model and effort flags (coding templates from train 14). */
+export declare const runAcceptsChoice: (help: string) => boolean;
+/**
+ * The choice a launch passes (this command's, else the conversation's recorded one, so a relaunch keeps its model) and
+ * whether the thread starts with this command's choice: the computer's guest accepts it and, for a conversation, its
+ * record carries it (the guest starts a conversation's agent from the record).
+ */
+export declare function launchChoice(explicit: ModelChoice, recorded: ModelChoice | undefined, conversation: boolean, help: () => Promise<string>): Promise<{
+    choice?: ModelChoice;
+    applied: boolean;
+}>;
+/** Said once when a computer's platform predates the choice: the thread starts with the agent's defaults. */
+export declare const CHOICE_PENDING = "The model and effort choice applies to new threads after the next platform update; this thread uses the defaults.";
+/** The record the JSON output carries for a requested choice. */
+export declare function choiceReport(c: ModelChoice, applied: boolean): {
+    model: string;
+    effort: string;
+    applied: boolean;
+};

package/dist/agent-models.js

@@ -0,0 +1,79 @@
+import { UsageError } from "./errors.js";
+export const DEFAULT_CHOICE = 'default';
+const DEFAULT_MODEL = { id: DEFAULT_CHOICE, label: 'Default', short: 'Default' };
+const LEVELS = { low: 'Low', medium: 'Medium', high: 'High', xhigh: 'Extra high', max: 'Max', ultra: 'Ultra' };
+const levels = (...ids) => [{ id: DEFAULT_CHOICE, label: 'Default' }, ...ids.map(id => ({ id, label: LEVELS[id] }))];
+/** Claude Code `--model <alias>` and `--effort <level>`; Codex `-m <model>` and `-c model_reasoning_effort=<level>`. */
+export const MODEL_CHOICES = {
+    claude: {
+        // The aliases always name the latest model of each family; descriptions are Claude Code's own.
+        models: [DEFAULT_MODEL,
+            { id: 'fable', label: 'Fable', short: 'Fable', description: 'For your toughest challenges' },
+            { id: 'opus', label: 'Opus', short: 'Opus', description: 'Most capable for ambitious work' },
+            { id: 'sonnet', label: 'Sonnet', short: 'Sonnet', description: 'Most efficient for everyday tasks' },
+            { id: 'haiku', label: 'Haiku', short: 'Haiku', description: 'Fastest for quick answers' }],
+        efforts: levels('low', 'medium', 'high', 'xhigh', 'max'),
+        default: { model: null, effort: null },
+    },
+    codex: {
+        // Descriptions are Codex's own model catalog.
+        models: [DEFAULT_MODEL,
+            { id: 'gpt-6.1-sol', label: 'GPT-6.1 Sol', short: 'GPT-6.1 Sol', description: 'Latest workhorse model for coding and everyday work' },
+            { id: 'gpt-6-astra', label: 'GPT-6 Astra', short: 'GPT-6 Astra', description: 'Frontier intelligence for the most demanding work' },
+            { id: 'gpt-6-luna', label: 'GPT-6 Luna', short: 'GPT-6 Luna', description: 'Fast and affordable model for easier tasks', efforts: [DEFAULT_CHOICE, 'low', 'medium', 'high', 'xhigh', 'max'] }],
+        efforts: levels('low', 'medium', 'high', 'xhigh', 'max', 'ultra'),
+        default: { model: 'gpt-6.1-sol', effort: null },
+    },
+};
+const list = (ids) => ids.length > 1 ? `${ids.slice(0, -1).join(', ')} or ${ids.at(-1)}` : ids[0];
+const label = (app) => app === 'claude' ? 'Claude' : 'Codex';
+/** `--model` and `--effort` for this app, checked against its list. Throws a usage error for anything else. */
+export function modelChoice(values, app) {
+    const raw = (name) => {
+        const value = values[name];
+        if (value === undefined)
+            return undefined;
+        if (typeof value !== 'string' || !value.trim())
+            throw new UsageError(`--${name} needs a value.`);
+        return value.trim().toLowerCase();
+    };
+    const model = raw('model'), effort = raw('effort'), choices = MODEL_CHOICES[app];
+    const option = model === undefined ? undefined : choices.models.find(m => m.id === model);
+    if (model !== undefined && !option)
+        throw new UsageError(`${label(app)} models: ${list(choices.models.map(m => m.id))}.`);
+    const allowed = option?.efforts ?? choices.efforts.map(e => e.id);
+    if (effort !== undefined && !allowed.includes(effort)) {
+        throw new UsageError(`${option?.efforts ? option.label : label(app)} effort levels: ${list(allowed)}.`);
+    }
+    return {
+        ...(model && model !== DEFAULT_CHOICE ? { model } : {}),
+        ...(effort && effort !== DEFAULT_CHOICE ? { effort } : {}),
+    };
+}
+export const hasChoice = (c) => !!(c?.model || c?.effort);
+/** The guest's `sf-agent run` flags for a choice (sf-agent maps them to the agent's own flags). */
+export function runFlags(c) {
+    return [...(c?.model ? ['--model', c.model] : []), ...(c?.effort ? ['--effort', c.effort] : [])];
+}
+/** Whether a guest's `sf-agent run --help` lists the model and effort flags (coding templates from train 14). */
+export const runAcceptsChoice = (help) => /-model\b/.test(help) && /-effort\b/.test(help);
+/**
+ * The choice a launch passes (this command's, else the conversation's recorded one, so a relaunch keeps its model) and
+ * whether the thread starts with this command's choice: the computer's guest accepts it and, for a conversation, its
+ * record carries it (the guest starts a conversation's agent from the record).
+ */
+export async function launchChoice(explicit, recorded, conversation, help) {
+    const choice = hasChoice(explicit) ? explicit : recorded;
+    if (!hasChoice(choice))
+        return { applied: true };
+    // A guest that cannot say what it accepts gets no flags: the thread starts either way.
+    const accepted = runAcceptsChoice(await help().catch(() => ''));
+    const kept = !conversation || !hasChoice(explicit) || (recorded?.model === explicit.model && recorded?.effort === explicit.effort);
+    return { ...(accepted ? { choice } : {}), applied: accepted && kept };
+}
+/** Said once when a computer's platform predates the choice: the thread starts with the agent's defaults. */
+export const CHOICE_PENDING = 'The model and effort choice applies to new threads after the next platform update; this thread uses the defaults.';
+/** The record the JSON output carries for a requested choice. */
+export function choiceReport(c, applied) {
+    return { model: c.model ?? DEFAULT_CHOICE, effort: c.effort ?? DEFAULT_CHOICE, applied };
+}

package/dist/agent-state.d.ts

@@ -12,6 +12,16 @@ export declare class AgentStateStore {
     read(): State;
     app(project: string, fallback?: 'claude' | 'codex'): 'claude' | 'codex';
     target(project: string, available: string[]): string;
+    /** T3 Code environments set up from this computer (the SSH route): targets.json keeps T3 out of its manifest. */
+    t3Environments(apiUrl: string): Array<{
+        workspace: string;
+        host: string;
+    }>;
+    saveT3Environment(entry: {
+        workspace: string;
+        host: string;
+        api_url: string;
+    }): void;
     saveTarget(project: string, target: string): void;
     update(change: (state: State) => void): void;
     save(project: string, app: 'claude' | 'codex'): void;

package/dist/agent-state.js

@@ -28,6 +28,19 @@ export class AgentStateStore {
         const target = this.read().projects?.[project]?.target;
         return target && available.includes(target) ? target : available.includes('t3') ? 't3' : 'terminal';
     }
+    /** T3 Code environments set up from this computer (the SSH route): targets.json keeps T3 out of its manifest. */
+    t3Environments(apiUrl) {
+        const list = this.read().t3;
+        return (Array.isArray(list) ? list : []).filter((e) => !!e && typeof e === 'object' && typeof e.workspace === 'string' && typeof e.host === 'string'
+            && e.api_url === apiUrl).map(({ workspace, host }) => ({ workspace, host }));
+    }
+    saveT3Environment(entry) {
+        this.update(doc => {
+            const list = (Array.isArray(doc.t3) ? doc.t3 : []);
+            // The newest last: the onboarding card names the one most recently set up.
+            doc.t3 = [...list.filter(e => !(e.host === entry.host && e.api_url === entry.api_url)), entry];
+        });
+    }
     saveTarget(project, target) {
         this.update(doc => {
             doc.projects ??= {};

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

@@ -4,6 +4,7 @@ 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 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>;
 /** Host trust is established over the authenticated files API, before sending any SSH protocol bytes. */
@@ -27,6 +28,10 @@ export declare const CLAUDE_DESKTOP_BUNDLE = "com.anthropic.claudefordesktop";
  * opens a Claude conversation when Claude Desktop is installed. --json prints {target, url, app_bundle_id} for apps.
  */
 export declare function openClaudeDesktopSession(ctx: Ctx, ws: Workspace, conversation?: Pick<Conversation, 'harness_session_id'>): Promise<number>;
-export declare function openDesktopWorkspace(ctx: Ctx, ws: Workspace, target: DesktopTarget, t3Version?: string, prewarmed?: boolean): Promise<number>;
+/**
+ * Opens a workspace as a desktop app's SSH environment. For T3 (0.17.0+) a first message becomes a thread on the T3
+ * server in the VM (SSH mode), and T3 is brought to the front with --json too (`opened: true`).
+ */
+export declare function openDesktopWorkspace(ctx: Ctx, ws: Workspace, target: DesktopTarget, t3Version?: string, prewarmed?: boolean, thread?: T3ThreadRequest, install?: T3Install, conversation?: string | null): Promise<number>;
 export declare function queueT3Prewarm(ctx: Ctx, ws: Workspace, version: string): Promise<void>;
 export declare const TARGET_HANDLERS: Record<string, Handler>;