@shardflux/cli 0.18.0-next.5 → 0.18.1

package/dist/conversation-terminal.js

@@ -23,6 +23,7 @@ import { launchT3 } from "./t3-launch.js";
 import { openClaudeDesktopSession, remoteControlUrl } from "./agent-target-commands.js";
 import { openUrl } from "./browser.js";
 import { out } from "./commands.js";
+import { progress } from "./progress.js";
 /** Every terminal entry point uses the durable conversation's native harness, worktree and session. */
 export async function conversationTerminal(ctx, ws, c, project, values) {
     if (c.route === 'codex-cloud')
@@ -32,6 +33,27 @@ export async function conversationTerminal(ctx, ws, c, project, values) {
     const pty = ws.labels.shard_conversation && ws.labels.shard_conversation !== c.id ? conversationName(c) : undefined;
     return terminal(ctx, ws, c.harness, conversationName(c), project, values, undefined, c.worktree_path, { id: c.id, session: c.harness_session_id, title: c.title, ...(pty ? { pty } : {}), choice: recordedChoice(c) });
 }
+/**
+ * A conversation and its VM, for an app to open (Claude Desktop, claude.ai, T3 Code, the menu bar). A conversation
+ * whose VM was removed after it finished restores first (0.18.1+): a fresh VM from its saved branch and transcript, the
+ * same conversation and its session resumed. A terminal conversation's session starts detached, as a new one does, so
+ * the app reaches it at once; the guest starts the others.
+ */
+export async function reopenConversation(ctx, c, values) {
+    if (!c.ended_at || c.route === 'codex-cloud')
+        return { conversation: c, ws: await conversationWorkspace(ctx, c) };
+    const restored = await resumeConversation(ctx, c);
+    const ws = await conversationWorkspace(ctx, restored);
+    if (restored.route !== 'terminal') {
+        progress(ctx, 'Restored');
+        return { conversation: restored, ws };
+    }
+    if (!(await savedMachine(ctx))?.template)
+        await syncAgentConfig(ctx, ws);
+    const quiet = { ...ctx, io: { ...ctx.io, stdout: { write: () => true } } };
+    await conversationTerminal(quiet, ws, restored, ws.labels.repo_remote || ws.labels.shard_project || ws.key, { ...values, detach: true });
+    return { conversation: restored, ws };
+}
 /**
  * `shard ./` (and `agents new --in auto`): new conversations open where `agents targets` says (open_in, 0.17.0+): T3
  * Code mode, Claude Desktop or claude.ai for Claude (the conversation's Remote Control session), else this terminal.

package/dist/conversations.d.ts

@@ -1,4 +1,4 @@
-import type { Workspace, WorkspaceView } from '@shardflux/sdk';
+import type { CellClient, Workspace, WorkspaceView } from '@shardflux/sdk';
 import type { Ctx } from './commands.js';
 import type { ModelChoice } from './agent-models.js';
 export type Harness = 'claude' | 'codex';
@@ -40,6 +40,15 @@ export interface Conversation {
     /** The model and effort its harness starts with; null is the agent's own default (0.17.0+, APIs that keep them). */
     model?: string | null;
     effort?: string | null;
+    /** The account its thread runs on and the mode it started in (0.18.0+, APIs with the account pool). */
+    account?: {
+        id: string | null;
+        label: string | null;
+        provider: Harness;
+        mode: 'direct' | 'pooled';
+    } | null;
+    /** Why it needs you, while `state` is needs_you; null otherwise (0.18.0+, APIs that return it). */
+    question?: string | null;
 }
 export interface LocalConversation {
     api_url: string;
@@ -56,6 +65,13 @@ export interface LocalConversation {
  */
 export declare const conversationEnded: (c: Pick<Conversation, "state" | "ended_at" | "route" | "landed">) => boolean;
 export declare const conversationName: (c: Conversation) => string;
+/**
+ * The managed PTY a conversation's harness runs in (0.18.1+). The guest records it per conversation
+ * (sf-agent's conversation runtime record), which also keeps the PTY a fork inherited from its parent; without a
+ * record it is the one the guest names after the conversation, `shard-<name>-<harness>`. Never the VM key's name: a
+ * conversation's VM is `<project>/conv-<name>`.
+ */
+export declare function conversationPtyId(cell: Pick<CellClient, 'exec'>, c: Conversation, signal?: AbortSignal): Promise<string>;
 export declare function validateConversation(c: Conversation): Conversation;
 export declare function localConversations(ctx: Pick<Ctx, 'store' | 'apiUrl'>): Record<string, LocalConversation>;
 export declare function rememberConversation(ctx: Pick<Ctx, 'store' | 'apiUrl'>, c: Conversation, folder: string, handedOff?: boolean, baseBranch?: string): void;

package/dist/conversations.js

@@ -9,6 +9,7 @@ import { UsageError } from "./errors.js";
 import { conversationClient } from "./conversation-commands.js";
 import { recordSeedSnapshot } from "./files-mirror.js";
 import { rememberTwinSeed, sendTwinSeed, twinCheckoutArgv, twinSeed } from "./worktree-twin.js";
+import { progress } from "./progress.js";
 /**
  * Whether the conversation has ended: its VM was reclaimed, or it was archived or discarded. A finished turn is `done`
  * while its VM still takes the next turn; on Codex Cloud, `done` ends the conversation.
@@ -20,6 +21,37 @@ export const conversationName = (c) => {
         throw new Error('Conversation returned an invalid branch or name');
     return name;
 };
+/** The guest's managed PTY id: `shard-<name>-<app>` (services/guest-agent/internal/agents PtyID). */
+const MANAGED_PTY = /^shard-[a-z0-9][a-z0-9._-]{0,63}-(claude|codex)$/;
+/**
+ * The managed PTY a conversation's harness runs in (0.18.1+). The guest records it per conversation
+ * (sf-agent's conversation runtime record), which also keeps the PTY a fork inherited from its parent; without a
+ * record it is the one the guest names after the conversation, `shard-<name>-<harness>`. Never the VM key's name: a
+ * conversation's VM is `<project>/conv-<name>`.
+ */
+export async function conversationPtyId(cell, c, signal) {
+    const derived = `shard-${conversationName(c)}-${c.harness}`;
+    let stdout;
+    try {
+        const r = await cell.exec.run(['cat', `/home/user/.local/share/shardflux/conversation-runtime/${c.id}.json`], { timeoutMs: 10_000, maxOutputBytes: 4096, ...(signal ? { signal } : {}) });
+        if (r.exitCode !== 0)
+            return derived;
+        stdout = r.stdout;
+    }
+    catch (error) {
+        if (signal?.aborted)
+            throw error;
+        return derived;
+    }
+    let recorded;
+    try {
+        recorded = JSON.parse(stdout)?.pty_id;
+    }
+    catch {
+        return derived;
+    }
+    return typeof recorded === 'string' && MANAGED_PTY.test(recorded) && recorded.endsWith(`-${c.harness}`) ? recorded : derived;
+}
 export function validateConversation(c) {
     if (!c || !/^conv_[a-z0-9]{26}$/.test(c.id) || !c.project_id || !c.workspace_id || !c.worktree_path?.startsWith('/home/user/') || /[\0\r\n]/.test(c.worktree_path) || !['claude', 'codex'].includes(c.harness))
         throw new Error('Conversation response omitted its identity or binding');
@@ -120,6 +152,9 @@ export async function restoreConversationBinding(ctx, c, ws) {
     const result = await cell.exec.run(['sf-agent', 'conversation', 'restore', '--args', '{"start":false}'], { cwd: c.worktree_path, env: { SF_CONVERSATION_ID: c.id }, timeoutMs: 120_000, signal: ctx.signal });
     if (result.exitCode !== 0)
         throw new Error(`Conversation restore failed: ${result.stderr.trim()}`);
+    // A conversation whose VM was removed now runs in a fresh one, from its saved branch and transcript (0.18.1+).
+    if (c.restore.kind === 'resume')
+        progress(ctx, 'Restored');
 }
 export async function createConversationRecord(ctx, folder, harness, route, name, allocated, idempotencyKey = randomUUID(), choice = {}) {
     const project = projectIdentity(folder);

package/dist/desktop-linux.js

@@ -53,7 +53,7 @@ export class LinuxDesktopManager {
             return null;
         }
     }
-    async status(dir) {
+    status(dir) {
         const version = this.#version(this.app), pids = [];
         try {
             const pid = Number(readFileSync(join(dir, 'desktop-linux.pid'), 'utf8'));
@@ -62,20 +62,21 @@ export class LinuxDesktopManager {
                 pids.push(pid);
         }
         catch { /* no running app */ }
-        return { installed: version !== null, version, running: pids.length > 0, pids, login: existsSync(join(this.home, '.config/autostart/shardflux.desktop')) ? 'on' : 'off' };
+        return Promise.resolve({ installed: version !== null, version, running: pids.length > 0, pids, login: existsSync(join(this.home, '.config/autostart/shardflux.desktop')) ? 'on' : 'off' });
     }
     packagedVersion() { const path = this.#source(); return path ? this.#version(path) : null; }
-    async login(on) {
+    login(on) {
         const file = join(this.home, '.config/autostart/shardflux.desktop');
         if (!on) {
             rmSync(file, { force: true });
-            return;
+            return Promise.resolve();
         }
         mkdirSync(dirname(file), { recursive: true });
         const entry = join(this.home, '.local/share/applications/dev.shardflux.Desktop.desktop');
         if (!existsSync(entry))
-            throw new UsageError('Run shard menubar start first.');
+            return Promise.reject(new UsageError('Run shard menubar start first.'));
         cpSync(entry, file);
+        return Promise.resolve();
     }
     async stop(dir) {
         const status = await this.status(dir);

package/dist/filesystem-commands.d.ts

@@ -1,7 +1,17 @@
-import type { AgentFilesystem } from '@shardflux/sdk';
-import type { Handler } from './commands.js';
+import type { AgentFilesystem, Workspace } from '@shardflux/sdk';
+import type { Ctx, Handler } from './commands.js';
 /** One line per status: what is in use and what is saving or failed, its platform base and setup cache. */
 export declare function filesystemLine(state: AgentFilesystem & {
     cache_scope?: string;
 }): string;
+/** The save's one line about software under the home that went into the image (0.18.0+), as the in-VM shard says it. */
+export declare function movedLine(state: AgentFilesystem, level: 'machine' | 'template'): string;
+/** Creates or resumes the machine VM of the saved machine version; the first one gets this computer's agent config. */
+/** The account's machine VM, created or resumed; `sync: false` skips the first-open config sync (an account sign-in). */
+export declare function openMachine(ctx: Ctx, state?: AgentFilesystem, opts?: {
+    sync?: boolean;
+}): Promise<{
+    state: AgentFilesystem;
+    ws: Workspace;
+}>;
 export declare const FILESYSTEM_HANDLERS: Record<string, Handler>;

package/dist/filesystem-commands.js

@@ -1,3 +1,4 @@
+import { codingAgentShell } from "./agent-setup.js";
 import { waitTimeout } from "./commands.js";
 import { UsageError } from "./errors.js";
 import { projectIdentity, normalizeRemote } from "./project-identity.js";
@@ -37,9 +38,17 @@ async function saved(ctx, values, save, level) {
     const state = await save({ signal: ctx.signal, ...(wait ? { wait } : {}) });
     if (ctx.json)
         return output(ctx, state);
-    ctx.io.stdout.write(wait ? `${level}: version ${state.version} saved\n` : state.pending ? `${filesystemLine(state)}; shard ${level} shows when it is ready\n` : `${filesystemLine(state)}\n`);
+    const moved = movedLine(state, level);
+    ctx.io.stdout.write(wait ? `${level}: version ${state.version} saved${moved}\n` : state.pending ? `${filesystemLine(state)}; shard ${level} shows when it is ready${moved}\n` : `${filesystemLine(state)}${moved}\n`);
     return 0;
 }
+/** The save's one line about software under the home that went into the image (0.18.0+), as the in-VM shard says it. */
+export function movedLine(state, level) {
+    const moved = state.moved_to_image ?? [];
+    if (moved.length === 0)
+        return '';
+    return `; ${moved.length} large tool folder${moved.length === 1 ? '' : 's'} went into the ${level} image (${moved.join(', ')}); they keep working at the same paths`;
+}
 const rollbackTo = (value) => {
     if (value === undefined)
         return undefined;
@@ -48,34 +57,53 @@ const rollbackTo = (value) => {
         throw new UsageError('--to must be a saved version number');
     return n;
 };
+/** Creates or resumes the machine VM of the saved machine version; the first one gets this computer's agent config. */
+/** The account's machine VM, created or resumed; `sync: false` skips the first-open config sync (an account sign-in). */
+export async function openMachine(ctx, state, opts = {}) {
+    const cloud = ctx.cloud();
+    state ??= await cloud.machine.get({ signal: ctx.signal });
+    const key = `machine/${state.organization_id}/v${state.version}`;
+    const existing = await cloud.workspaces.findByKey(key, { includeDeleted: false, signal: ctx.signal });
+    if (!existing)
+        progress(ctx, `Creating your machine VM (${key}); the first open takes about a minute…`);
+    else if (existing.data.observed_state !== 'running')
+        progress(ctx, `Resuming your machine VM (${key})…`);
+    const ws = await cloud.workspaces.open({ key, template: state.template ? `${state.template.slug}@${state.template.version}` : 'coding',
+        labels: { ...existing?.labels, shard_layer: 'machine', shard_machine: state.organization_id, repo_path: '/home/user', app: 'claude', agent: 'machine' },
+        wait: { timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal } });
+    if (state.version === 0 && opts.sync !== false) {
+        progress(ctx, 'Syncing your Claude and Codex config into the machine…');
+        await syncAgentConfig(ctx, ws);
+    }
+    return { state, ws };
+}
 export const FILESYSTEM_HANDLERS = {
     async machine(ctx) {
-        const cloud = ctx.cloud();
-        const state = await cloud.machine.get({ signal: ctx.signal });
-        if (ctx.json || !ctx.io.stdin.isTTY)
+        const state = await ctx.cloud().machine.get({ signal: ctx.signal });
+        // Without a terminal (or in a coding agent's shell, 0.17.1+) there is nobody to type to the machine agent: the status.
+        if (ctx.json || !ctx.io.stdin.isTTY || codingAgentShell(ctx.io.env))
             return output(ctx, state);
-        const key = `machine/${state.organization_id}/v${state.version}`;
-        const existing = await cloud.workspaces.findByKey(key, { includeDeleted: false, signal: ctx.signal });
-        if (!existing)
-            progress(ctx, `Creating your machine VM (${key}); the first open takes about a minute…`);
-        else if (existing.data.observed_state !== 'running')
-            progress(ctx, `Resuming your machine VM (${key})…`);
-        const ws = await cloud.workspaces.open({ key, template: state.template ? `${state.template.slug}@${state.template.version}` : 'coding',
-            labels: { ...existing?.labels, shard_layer: 'machine', shard_machine: state.organization_id, repo_path: '/home/user', app: 'claude', agent: 'machine' },
-            wait: { timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal } });
-        if (state.version === 0) {
-            progress(ctx, 'Syncing your Claude and Codex config into the machine…');
-            await syncAgentConfig(ctx, ws);
-        }
+        const { ws } = await openMachine(ctx, state);
         return AGENT_HANDLERS['agents open'](ctx, {}, [ws.key]);
     },
+    /** `shard machine open` (0.17.1+): the machine VM without the agent terminal, for an agent that builds the machine. */
+    async 'machine open'(ctx) {
+        const { state, ws } = await openMachine(ctx);
+        if (ctx.json)
+            ctx.io.stdout.write(JSON.stringify({ workspace: ws.data, key: ws.key, machine: state, next: [`shard ws exec ${ws.key} -- bash -lc '<install commands>'`, `shard files write ${ws.key} <path> --from -`, 'shard machine save --wait'] }) + '\n');
+        else {
+            ctx.io.stdout.write(`${ws.key}\n`);
+            progress(ctx, `Install with shard ws exec ${ws.key} -- bash -lc '…', write files with shard files write ${ws.key} <path> --from -, then shard machine save --wait.`);
+        }
+        return 0;
+    },
     async 'machine save'(ctx, values) {
         const cloud = ctx.cloud();
         const state = await cloud.machine.get({ signal: ctx.signal });
         const ws = await cloud.workspaces.findByKey(`machine/${state.organization_id}/v${state.version}`, { signal: ctx.signal }) ??
             (state.workspace_id ? await cloud.workspaces.get(state.workspace_id) : null);
         if (!ws)
-            throw new UsageError('Open shard machine, change it, then run shard machine save');
+            throw new UsageError('Open your machine and change it first, then run shard machine save', 'shard machine in a terminal, or shard machine open --json for an agent (0.17.1+)');
         return saved(ctx, values, options => cloud.machine.save({ workspaceId: ws.id }, options), 'machine');
     },
     async 'machine rollback'(ctx, values) {

package/dist/handlers.js

@@ -20,4 +20,5 @@ import { TWIN_HANDLERS } from "./worktree-twin-engine.js";
 import { CODEX_CLOUD_HANDLERS } from "./codex-cloud.js";
 import { THREAD_HANDLERS } from "./thread-on-computer.js";
 import { CLI_PROXY_HANDLERS } from "./cli-proxy.js";
-export const HANDLERS = { ...DEVICE_HANDLERS, ...CODEX_CLOUD_HANDLERS, ...CLI_PROXY_HANDLERS, ...THREAD_HANDLERS, ...CONVERSATION_HANDLERS, ...LOCAL_CONVERSATION_HANDLERS, ...TWIN_HANDLERS, ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS, ...UPDATE_HANDLERS };
+import { ACCOUNT_POOL_HANDLERS } from "./account-pool.js";
+export const HANDLERS = { ...DEVICE_HANDLERS, ...CODEX_CLOUD_HANDLERS, ...CLI_PROXY_HANDLERS, ...THREAD_HANDLERS, ...CONVERSATION_HANDLERS, ...LOCAL_CONVERSATION_HANDLERS, ...TWIN_HANDLERS, ...CREDENTIAL_HANDLERS, ...AGENT_CREDENTIAL_HANDLERS, ...ACCOUNT_POOL_HANDLERS, ...KEY_HANDLERS, ...ACCOUNT_HANDLERS, ...AGENT_HANDLERS, ...CENTER_HANDLERS, ...TARGET_HANDLERS, ...AGENT_GIT_HANDLERS, ...MENUBAR_HANDLERS, ...FILESYSTEM_HANDLERS, ...UPDATE_HANDLERS };

package/dist/input.d.ts

@@ -13,8 +13,10 @@ export interface ErrWriter {
 }
 export declare class Input {
     #private;
-    constructor(stdin: StdinLike, stderr: ErrWriter);
-    /** True when standard input is a terminal `shard` can prompt on. */
+    constructor(stdin: StdinLike, stderr: ErrWriter, opts?: {
+        agentShell?: boolean;
+    });
+    /** True when standard input is a terminal `shard` can prompt on (and not a coding agent's shell). */
     get interactive(): boolean;
     /** The next line of piped input without its line ending, or null at the end of input. */
     line(): Promise<string | null>;

package/dist/input.js

@@ -16,18 +16,21 @@ const MAX_PIPED_BYTES = 64 * 1024;
 export class Input {
     #stdin;
     #stderr;
+    /** In a coding agent's shell nobody types at a prompt, even on a terminal (0.17.1+). */
+    #agentShell;
     #it = null;
     #decoder = new TextDecoder('utf-8');
     #buf = '';
     #eof = false;
     #read = 0;
-    constructor(stdin, stderr) {
+    constructor(stdin, stderr, opts = {}) {
         this.#stdin = stdin;
         this.#stderr = stderr;
+        this.#agentShell = opts.agentShell === true;
     }
-    /** True when standard input is a terminal `shard` can prompt on. */
+    /** True when standard input is a terminal `shard` can prompt on (and not a coding agent's shell). */
     get interactive() {
-        return this.#stdin.isTTY === true;
+        return this.#stdin.isTTY === true && !this.#agentShell;
     }
     async #more() {
         if (this.#eof)

package/dist/main.js

@@ -13,7 +13,7 @@
 import { homedir, hostname } from 'node:os';
 import { statSync } from 'node:fs';
 import { SDK_VERSION, Shardflux, ShardfluxAccount, isSessionToken } from '@shardflux/sdk';
-import { CLI_VERSION, CENTER_COMMAND, ONBOARDING_COMMAND, PROJECT_COMMAND, commandHelp, parseCommandLine, resolveApiUrl, resolveWake, resolveWakeTimeout } from "./args.js";
+import { CLI_VERSION, CENTER_COMMAND, GUIDE_COMMAND, ONBOARDING_COMMAND, PROJECT_COMMAND, parseCommandLine, resolveApiUrl, resolveWake, resolveWakeTimeout } from "./args.js";
 import { commandCenter } from "./command-center.js";
 import { launchProjectCommand } from "./conversation-terminal.js";
 import { runAcp } from "./acp.js";
@@ -21,6 +21,8 @@ import { registerInstalledT3 } from "./t3-provider.js";
 import { refreshForwarderAgent } from "./cli-proxy.js";
 import { runAcpLogin } from "./acp-login.js";
 import { terminalOnboarding } from "./terminal-onboarding.js";
+import { codingAgentShell, setupGuideText } from "./agent-setup.js";
+import { agentSetupGuide } from "./account-commands.js";
 import { tryLinuxDesktop } from "./desktop-linux.js";
 import { startLinuxHelper } from "./linux-helper.js";
 import { runDeviceHelper } from "./device-helper.js";
@@ -40,7 +42,7 @@ import { CLI_DISTRIBUTION, NOTICE_WAIT_MS, UpdateCheck, noticeOf, updateCheckDis
 const KEY_SHAPE = /^sfk_[a-z2-7]{16}_[A-Za-z0-9]+$/;
 // Printable (no C0 controls or DEL), as the API's AgentLabel pattern.
 const isLabel = (s) => s.length >= 1 && s.length <= 100 && ![...s].some((ch) => ch.charCodeAt(0) < 0x20 || ch.charCodeAt(0) === 0x7f);
-const LOGIN_HINT = 'shard auth login --email <you@example.com>';
+const LOGIN_HINT = 'shard auth login --browser';
 const STEP_UP_HINT = `confirm your password, then run the command again (valid 10 minutes): printf '%s\\n' "$PASSWORD" | shard auth step-up (add --code <totp> with two-factor authentication)`;
 /** A sleep that ends early when the signal aborts (so Ctrl-C never waits out a poll interval). */
 export function abortableSleep(signal) {
@@ -427,9 +429,12 @@ export async function run(argv, io, opts = {}) {
         io.stderr.write(redact(text, ...secrets));
         return code;
     };
+    // A coding agent's shell (0.17.1+) is no terminal to attach to or prompt on, even when it is a PTY.
+    const agentShell = codingAgentShell(io.env);
+    const tty = io.stdin.isTTY === true && io.stdout.isTTY !== false && !agentShell;
     let parsed;
     try {
-        parsed = parseCommandLine(argv, { tty: io.stdin.isTTY === true && io.stdout.isTTY !== false, isProjectPath: (path) => { try {
+        parsed = parseCommandLine(argv, { tty, isProjectPath: (path) => { try {
                 return statSync(path).isDirectory();
             }
             catch {
@@ -449,10 +454,11 @@ export async function run(argv, io, opts = {}) {
         io.stdout.write(wantsJson ? json({ cli: CLI_VERSION, sdk: SDK_VERSION }) : `shard ${CLI_VERSION} (@shardflux/sdk ${SDK_VERSION})\n`);
         return EXIT.ok;
     }
-    if (parsed.command === PROJECT_COMMAND && (!io.stdin.isTTY || io.stdout.isTTY === false) && !parsed.global.json) {
+    // shard ./ attaches Claude Code or Codex to this terminal: without one (or in a coding agent's shell) it says how to
+    // start the conversation instead of starting one nobody can see (0.17.1+: a usage error, before 0.17.1 its help).
+    if (parsed.command === PROJECT_COMMAND && !tty && !parsed.global.json) {
         await startupHousekeeping({ io, store, signal });
-        io.stdout.write(commandHelp(PROJECT_COMMAND));
-        return EXIT.ok;
+        return report(new UsageError('shard ./ opens Claude Code or Codex in a terminal, and this shell has none.', 'ask your user to run shard ./ in their own terminal, or start the conversation detached: shard ./ --json --prompt "<task>" (shard ./ codex --json ... for Codex)'));
     }
     command = parsed.command.path.join(' ');
     let ctx;
@@ -544,7 +550,7 @@ export async function run(argv, io, opts = {}) {
             timing: showTiming,
             traces,
             store,
-            input: new Input(io.stdin, io.stderr),
+            input: new Input(io.stdin, io.stderr, { agentShell }),
             distribution,
             runtime: opts.runtime ?? null,
             async clientVersions() {
@@ -606,7 +612,7 @@ export async function run(argv, io, opts = {}) {
                 else {
                     const saved = store.profile(apiUrl).session;
                     if (!saved)
-                        throw new AuthConfigError(`Not signed in to ${apiUrl}.`, `sign in: ${LOGIN_HINT} (new here? shard auth register --email <you@example.com>)`);
+                        throw new AuthConfigError(`Not signed in to ${apiUrl}.`, `sign in: ${LOGIN_HINT} (new here? shard signup; setting Shardflux up for someone: shard setup --guide)`);
                     cred.sessionSource = 'file';
                     cred.email = saved.user?.email ?? null;
                     secrets.push(saved.token);
@@ -689,6 +695,11 @@ export async function run(argv, io, opts = {}) {
         }
         stopHelper = startLinuxHelper(ctx);
     };
+    // Bare shard without a terminal (0.17.1+): the setup guide, read from local state only (never waits).
+    if (parsed.command === GUIDE_COMMAND) {
+        io.stdout.write(setupGuideText(agentSetupGuide(ctx)));
+        return EXIT.ok;
+    }
     const handler = parsed.command.path[0] === 'acp' ? (ctx) => parsed.values.login === true ? runAcpLogin(ctx) : runAcp(ctx) : parsed.command.path[0] === 'device-helper' ? (ctx) => runDeviceHelper(ctx, { service: parsed.values.service === true }) : command === 'menubar refresh' ? runMenubarRefresh : parsed.command === PROJECT_COMMAND ? launchProjectCommand : parsed.command === ONBOARDING_COMMAND ? async (ctx, values) => await tryLinuxDesktop(ctx) ? 0 : terminalOnboarding(ctx, values, { startHelper }) : parsed.command === CENTER_COMMAND ? commandCenter : HANDLERS[parsed.command.path.join(' ')];
     if (!handler)
         return report(new UsageError(`unknown command "${parsed.command.path.join(' ')}"`));

package/dist/menubar.js

@@ -342,7 +342,7 @@ export function refreshMenubarInBackground(o) {
             return false;
         const manifest = (dir) => { try {
             const m = JSON.parse(readFileSync(join(dir, 'manifest.json'), 'utf8'));
-            return m.id === 'dev.shardflux.Desktop' ? m.version : null;
+            return m.id === 'dev.shardflux.Desktop' && typeof m.version === 'string' ? m.version : null;
         }
         catch {
             return null;

package/dist/t3-asar.d.ts

@@ -1,7 +1,17 @@
 /** The server CLI inside the archive: what Electron runs as Node to issue T3 sessions. */
 export declare const T3_SERVER_ENTRY = "apps/server/dist/bin.mjs";
-/** The app's release version (package.json `version`, e.g. `0.0.46-nightly.20261010.2908`), or null. */
-export declare function asarVersion(archive: string): string | null;
+/** The archive's package.json: whether it is T3 Code's, and its release version. */
+export interface T3Package {
+    t3: boolean;
+    version: string | null;
+}
+/**
+ * The archive's package.json (null when it has none): T3 Code's when its `name` is `t3code` (as 0.0.45 and the
+ * nightlies ship it) or its `productName` is T3 Code's, and its release version (e.g. `0.0.46-nightly.20261010.2908`).
+ */
+export declare function asarPackage(archive: string): T3Package | null;
+/** The app's release version from its package.json, or null. */
+export declare const asarVersion: (archive: string) => string | null;
 /**
  * Whether the server registers the ACP Registry driver. A version number alone is insufficient (0.0.45 lacks it while
  * upstream main had it). Builds put the driver in `bin.mjs` itself, or (nightlies since October 2026) in a chunk the

package/dist/t3-asar.js

@@ -61,13 +61,22 @@ function read(a, path) {
     const bytes = Buffer.alloc(size);
     return readSync(a.fd, bytes, 0, size, offset) === size ? bytes : undefined;
 }
-/** The app's release version (package.json `version`, e.g. `0.0.46-nightly.20261010.2908`), or null. */
-export function asarVersion(archive) {
-    return fact(archive, 'version', a => {
-        const version = JSON.parse(read(a, 'package.json')?.toString() ?? '{}').version;
-        return typeof version === 'string' && RELEASE.test(version) ? version : null;
+/**
+ * The archive's package.json (null when it has none): T3 Code's when its `name` is `t3code` (as 0.0.45 and the
+ * nightlies ship it) or its `productName` is T3 Code's, and its release version (e.g. `0.0.46-nightly.20261010.2908`).
+ */
+export function asarPackage(archive) {
+    return fact(archive, 'app', a => {
+        const bytes = read(a, 'package.json');
+        if (!bytes)
+            return null;
+        const doc = JSON.parse(bytes.toString());
+        return { t3: doc.name === 't3code' || (typeof doc.productName === 'string' && /^T3 Code(?: \(.+\))?$/.test(doc.productName)),
+            version: typeof doc.version === 'string' && RELEASE.test(doc.version) ? doc.version : null };
     }, null) ?? null;
 }
+/** The app's release version from its package.json, or null. */
+export const asarVersion = (archive) => asarPackage(archive)?.version ?? null;
 /**
  * Whether the server registers the ACP Registry driver. A version number alone is insufficient (0.0.45 lacks it while
  * upstream main had it). Builds put the driver in `bin.mjs` itself, or (nightlies since October 2026) in a chunk the

package/dist/t3-launch.js

@@ -9,6 +9,7 @@ import { conversationWorkspace, getConversation } from "./conversations.js";
 import { resolveOn } from "./thread-on-computer.js";
 import { ensureCloudClaude } from "./claude-cloud-login.js";
 import { modelChoice } from "./agent-models.js";
+import { conversationPooled } from "./account-pool.js";
 /**
  * A `t3_*` refusal raised once the workspace, conversation or thread exists names them (details.workspace_key,
  * conversation_id, t3_thread_id), so a client opens what exists instead of starting it again.
@@ -124,10 +125,14 @@ export async function openT3Conversation(ctx, conversationId, values = {}) {
         return 0;
     }
     // Its VM as T3's SSH environment, with the checks every `agents open t3` makes: --reachable and the cloud Claude login.
-    let ws = await conversationWorkspace(ctx, conversation);
+    // A conversation whose VM was removed restores into a fresh one first (0.18.1+).
+    const { reopenConversation } = await import("./conversation-terminal.js");
+    let { ws } = await reopenConversation(ctx, conversation, values);
     if (values.reachable !== undefined)
         ws = await ctx.cloud().workspaces.open({ key: ws.key, ...agentReachability(values), wait: false });
-    await ensureCloudClaude(ctx, ws);
+    // A pooled thread (0.18.0+) runs on the account hub, not on the account's cloud Claude login.
+    if (!conversationPooled(conversation))
+        await ensureCloudClaude(ctx, ws);
     const { openDesktopWorkspace } = await import("./agent-target-commands.js");
     return openDesktopWorkspace(ctx, ws, 't3', install.version ?? undefined, false, undefined, install, conversationId);
 }

package/dist/t3-linux.d.ts

@@ -1,14 +1,14 @@
 type Env = Record<string, string | undefined>;
-export type T3LinuxFormat = 'deb' | 'directory' | 'appimage' | 'flatpak' | 'snap';
+export type T3LinuxFormat = 'deb' | 'directory' | 'appimage' | 'flatpak';
 export interface T3LinuxApp {
     format: T3LinuxFormat;
     /** The desktop entry's file name (the id `gtk-launch` takes); null for an AppImage found by its file name. */
     desktop_id: string | null;
     /** What starts it: the entry's Exec without field codes, or the AppImage. */
     exec: string[];
-    /** The app's resources/app.asar on this computer (deb, other unpacked installs, flatpak); null for an AppImage or snap. */
+    /** The app's resources/app.asar on this computer (deb, other unpacked installs, flatpak); null for an AppImage. */
     asar: string | null;
-    /** Flatpak: the app id and the app's files folder on this computer (mounted at /app in its sandbox). */
+    /** Flatpak (unverified layout): the app id and the app's files folder on this computer (mounted at /app in its sandbox). */
     flatpak?: {
         id: string;
         files: string;
@@ -20,7 +20,7 @@ export interface T3LinuxInstall {
     version: string | null;
     linux: T3LinuxApp;
 }
-/** The launcher T3 (nightlies since October 2026) writes to `<T3 home>/bin/t3` for its bundled CLI; for an AppImage it mounts the image itself. */
+/** The launcher T3 (from v0.0.46-preview.20261008.2800) writes to `<T3 home>/bin/t3` for its bundled CLI; for an AppImage it mounts the image itself. */
 export declare const T3_LAUNCHER_MARKER = "Written by T3 Code: runs the desktop app's bundled t3 CLI.";
 /**
  * The folders scanned on Linux, in XDG precedence: the data home's and each data dir's `applications`, snapd's and
@@ -35,8 +35,8 @@ export declare function desktopExec(value: string): string[] | undefined;
 export declare function linuxT3Apps(dirs: string[], env: Env): T3LinuxInstall[];
 /**
  * Whether this install runs the Shardflux provider (ACP mode): the server in its app.asar has the ACP Registry driver
- * (deb, unpacked installs, flatpak). An AppImage is never mounted to look: its version decides (0.0.46+ have the
- * driver), and T3's own launcher issues its sessions. A snap starts threads over SSH.
+ * (deb, unpacked installs, flatpak). An AppImage is never mounted to look: its sessions come from T3's own launcher, so
+ * it is ACP from the first build that writes one (t3WritesLauncher); earlier builds start threads over SSH.
  */
 export declare function linuxSupportsAcp(app: T3LinuxInstall): boolean;
 /**
@@ -48,6 +48,11 @@ export declare function linuxServerCli(app: T3LinuxInstall, t3Home: string): {
     command: string;
     args: string[];
 } | undefined;
+/**
+ * The environment T3 is opened with: the caller's, without what would make its Electron run as plain Node
+ * (ELECTRON_RUN_AS_NODE: `t3code` would exit at once while the open still looked fine) or detach its console.
+ */
+export declare function t3OpenEnv(env: Env): Env;
 /**
  * How T3 is opened (or brought to the front, as a second launch of T3 hands over to the running one): `gtk-launch`
  * with its desktop entry when there is one, else its own program, started detached.
@@ -58,11 +63,5 @@ export declare function linuxOpenCommands(app: T3LinuxInstall, env: Env): Array<
     detached: boolean;
 }>;
 /** Opens T3 Code on Linux. Nothing here ever stops a T3 process: a launcher that hangs is left alone. */
-export declare function openLinuxT3(env: Env, app: T3LinuxInstall): Promise<void>;
-/**
- * When T3 last started, as the filesystem records it: the program's access time once it is later than its modification
- * time (dpkg installs both at the build time; relatime updates the access time on the first start, then daily). Null
- * before the first start and on noatime mounts.
- */
-export declare function linuxLastUsed(path: string): string | null;
+export declare function openLinuxT3(callerEnv: Env, app: T3LinuxInstall): Promise<void>;
 export {};