@shardflux/cli 0.15.2 → 0.17.0

package/dist/agent-target-commands.js

@@ -5,17 +5,23 @@ 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 { conversationWorkspace, getConversation } from "./conversations.js";
 import { out, resolveWorkspace } from "./commands.js";
-import { AgentTargets, installedTargets } from "./agent-targets.js";
+import { MODEL_CHOICES } from "./agent-models.js";
+import { AgentTargets, installedTargets, targetLabel } from "./agent-targets.js";
 import { join, relative } from 'node:path';
 import { projectIdentity } from "./project-identity.js";
 import { projectWorkspacePath } from "./agent-repository.js";
-import { UsageError } from "./errors.js";
+import { 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 { 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 { openT3Conversation, t3Fields, withT3Context } from "./t3-launch.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. */
@@ -72,6 +78,12 @@ export async function prepareSsh(ws, ctx, targets, host) {
     return cell;
 }
 async function openApp(target, env) {
+    if (target === 't3') {
+        const install = t3Install(env);
+        if (!install)
+            throw t3NotInstalled();
+        return openT3(env, install.path);
+    }
     const child = spawn('open', ['-b', { 'claude-desktop': 'com.anthropic.claudefordesktop', 'codex-app': 'com.openai.codex', t3: 'com.t3tools.t3code' }[target]], { env, stdio: 'ignore' });
     await new Promise((resolve, reject) => {
         const timer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error('app launcher timed out')); }, 10_000);
@@ -137,12 +149,18 @@ export function proxyStream(io, ended, outputGate) {
  * this computer just started can accept its first prompt before Remote Control registers, so an open of our recent
  * launch probes the guest for up to 30 s; history browsing stays passive.
  */
-export async function remoteControlUrl(ctx, ws) {
+/**
+ * The Claude Remote Control URL of a session in `ws`. With several threads on one computer (0.16.0+) a conversation's
+ * own session is chosen by its harness session id; a thread that has not reported one yet is unambiguous only alone.
+ */
+export async function remoteControlUrl(ctx, ws, conversation) {
     let cursor;
     let url;
+    const session = conversation?.harness_session_id ?? undefined;
+    const mine = (id) => session === undefined || id === session;
     do {
         const page = await ctx.cloud().agents.list({ limit: 200, ...(cursor ? { cursor } : {}) });
-        url = page.data.find(a => a.workspace_id === ws.id && a.app === 'claude' && a.state !== 'exited' && a.remote_control_url)?.remote_control_url;
+        url = page.data.find(a => a.workspace_id === ws.id && a.app === 'claude' && a.state !== 'exited' && a.remote_control_url && mine(a.id.slice(a.workspace_id.length + 1)))?.remote_control_url;
         cursor = page.nextCursor ?? undefined;
     } while (!url && cursor && !ctx.signal.aborted);
     // A new Claude process can accept its first prompt before Remote Control registers.
@@ -158,7 +176,7 @@ export async function remoteControlUrl(ctx, ws) {
             });
             if (result.exitCode !== 0)
                 break;
-            url = guestSessions(result.stdout).find(a => a.app === 'claude' && a.state !== 'exited' && a.remote_control_url)?.remote_control_url;
+            url = guestSessions(result.stdout).find(a => a.app === 'claude' && a.state !== 'exited' && a.remote_control_url && mine(a.session_id))?.remote_control_url;
             if (!url && Date.now() < deadline)
                 await delay(Math.min(250, Math.max(1, deadline - Date.now())), undefined, { signal: ctx.signal });
         }
@@ -184,9 +202,9 @@ export const CLAUDE_DESKTOP_BUNDLE = 'com.anthropic.claudefordesktop';
  * Opens the conversation itself (its live Remote Control session) in Claude Desktop (0.15.1+), the way `--in auto`
  * opens a Claude conversation when Claude Desktop is installed. --json prints {target, url, app_bundle_id} for apps.
  */
-export async function openClaudeDesktopSession(ctx, ws) {
+export async function openClaudeDesktopSession(ctx, ws, conversation) {
     await ensureCloudClaude(ctx, ws);
-    const session = await remoteControlUrl(ctx, ws);
+    const session = await remoteControlUrl(ctx, ws, conversation);
     const url = claudeDesktopLink(session);
     if (!ctx.json)
         await openLink(url, ctx.io.env);
@@ -206,23 +224,41 @@ async function openLink(url, env) {
 }
 const openTarget = (target) => async (ctx, values, [ref = 'main']) => {
     const detected = installedTargets(ctx.io.env);
+    if (target === 't3' && !detected.targets.includes('t3'))
+        throw t3NotInstalled();
     if (target !== 'web' && !detected.targets.includes(target))
         throw new UsageError(`${target} is not installed on this machine`);
-    let ws = await resolveWorkspace(ctx, keyOf(ref));
+    // 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).
+    const conversation = /^conv_[a-z0-9]{26}$/.test(ref) ? await getConversation(ctx, ref) : undefined;
+    let ws = conversation ? await conversationWorkspace(ctx, conversation) : await resolveWorkspace(ctx, keyOf(ref));
     if (values.reachable !== undefined)
         ws = await ctx.cloud().workspaces.open({ key: ws.key, ...agentReachability(values), wait: false });
-    if (target !== 'codex-app')
+    // T3 lists both agents and opens without Claude (it shows Claude as signed out); the Claude apps need it.
+    if (target === 't3')
+        await ensureCloudClaude(ctx, ws).catch((error) => {
+            if (!(error instanceof UsageError))
+                throw error;
+            ctx.io.stderr.write(`Claude Code in T3: ${error.message}\n`);
+        });
+    else if (target !== 'codex-app')
         await ensureCloudClaude(ctx, ws);
     if (target === 'web') {
-        const url = await remoteControlUrl(ctx, ws);
+        const url = await remoteControlUrl(ctx, ws, conversation);
         if (!ctx.json && !openUrl(url, ctx.io.env))
             throw new Error(`could not open ${url}`);
-        out(ctx, `${url}\n`, { target, workspace: ws.data, url });
+        out(ctx, `${url}\n`, { target, workspace: ws.data, url, ...(conversation ? { conversation_id: conversation.id } : {}) });
         return 0;
     }
-    return openDesktopWorkspace(ctx, ws, target, detected.versions.t3);
+    return openDesktopWorkspace(ctx, ws, target, detected.versions.t3, false, undefined, undefined, conversation?.id);
 };
-export async function openDesktopWorkspace(ctx, ws, target, t3Version, prewarmed = false) {
+/**
+ * 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 async function openDesktopWorkspace(ctx, ws, target, t3Version, prewarmed = false, thread, install, conversation) {
     if (target !== 't3')
         ws = await prepareDesktopRouter(ctx, ws);
     await prepareAgentMachine(ctx, ws);
@@ -235,13 +271,58 @@ export async function openDesktopWorkspace(ctx, ws, target, t3Version, prewarmed
         : target === 'claude-desktop'
             ? `Restart Claude Desktop to load the connection, then choose ${targetLabel(entry)} in Code's environment dropdown and open ${projectWorkspacePath({ slug: entry.project })}.`
             : `Restart Codex to import ${entry.host} and its remote project. If it has already been imported, enable ${entry.host} in Settings → Connections → SSH.`;
-    if (!ctx.json)
+    let started;
+    if (target === 't3' && thread) {
+        try {
+            started = await startSshThread(ctx, ws, t3Version, workspaceRepositoryPath(ws), thread);
+        }
+        catch (error) {
+            throw withT3Context(error, { workspace_key: ws.key, conversation_id: conversation ?? (ws.labels.shard_conversation || null) });
+        }
+    }
+    if (target === 't3') {
+        // The thread exists once startSshThread returns: a failure to show T3 names it rather than inviting a retry.
+        try {
+            await openT3(ctx.io.env, (install ?? t3Install(ctx.io.env))?.path ?? '');
+        }
+        catch (error) {
+            throw started ? t3OpenFailed(error, { t3_thread_id: started.t3_thread_id, conversation_id: conversation ?? (ws.labels.shard_conversation || null), workspace_key: ws.key }) : error;
+        }
+    }
+    else if (!ctx.json)
         await openApp(target, ctx.io.env);
     new AgentStateStore(ctx.store.dir).saveTarget(ws.labels.repo_remote || ws.labels.shard_project || entry.project, target);
-    out(ctx, `${instructions}\n`, { target, workspace: ws.data, host: entry.host, instructions,
+    if (target === 't3')
+        new AgentStateStore(ctx.store.dir).saveT3Environment({ workspace: ws.key, host: entry.host, api_url: ctx.apiUrl });
+    const phone = target === 't3' ? await linkT3Phone(ctx, ws) : undefined;
+    const threadLine = started ? `Started a thread in T3 Code on ${agentMachineName(ws.key)}${started.model ? ` (${started.model}${started.effort ? `, ${started.effort}` : ''})` : ''}.\n` : '';
+    out(ctx, `${threadLine}${instructions}\n${phone?.line ?? ''}`, { target, workspace: ws.data, host: entry.host, instructions, ...(phone ? { t3_link: phone.link } : {}),
+        ...(target === 't3' ? t3Fields(ws, entry.project, install ?? t3Install(ctx.io.env), started, conversation) : {}),
         app_bundle_id: { 'claude-desktop': 'com.anthropic.claudefordesktop', 'codex-app': 'com.openai.codex', t3: 'com.t3tools.t3code' }[target] });
     return 0;
 }
+/**
+ * The T3 app on the phone reaches this workspace through the account's T3 Connect sign-in (0.17.0+). The sign-in is
+ * asked for once per person; linking continues by itself once it is approved.
+ */
+async function linkT3Phone(ctx, ws) {
+    try {
+        const { link, signIn, needsLogin } = await t3PhoneLink(ctx, ws.id);
+        const line = signIn
+            ? `Phone: to use ${link.label} from the T3 app, open ${signIn.verification_uri} and confirm ${signIn.user_code} (once).\n`
+            : needsLogin ? `Phone: to use ${link.label} from the T3 app, sign in with shard auth login, then run this again.\n`
+                : `Phone: ${link.label} appears in the T3 app's environments.\n`;
+        // --json carries the sign-in shard started with its session too, so the menu bar can show it.
+        return { line, link: signIn ? { ...link, sign_in: { ...link.sign_in, ...signIn } } : needsLogin ? { ...link, needs_login: true } : link };
+    }
+    catch (error) {
+        // An API without T3 Connect leaves the desktop route as it is.
+        if (describeError(error).code === 'not_found')
+            return undefined;
+        ctx.io.stderr.write(`Phone link: ${describeError(error).message}\n`);
+        return undefined;
+    }
+}
 export async function queueT3Prewarm(ctx, ws, version) {
     try {
         await prewarmT3(ctx, ws, version);
@@ -251,7 +332,6 @@ export async function queueT3Prewarm(ctx, ws, version) {
     }
 }
 const tilde = (targets, file) => file.startsWith(`${targets.home}/`) ? `~/${relative(targets.home, file)}` : file;
-const targetLabel = (e) => e.agent === 'router' ? `Shardflux · ${e.project}` : `[SF] ${e.project} · ${e.agent}`;
 /** Where each managed connection of an entry lives: the SSH host block (and its Include), then each desktop app's file. */
 function configuredTargets(targets, e, t3 = false) {
     return [
@@ -264,30 +344,56 @@ function configuredTargets(targets, e, t3 = false) {
 function targetFiles(targets, entries) {
     return [...new Set(entries.flatMap(e => configuredTargets(targets, e).map(c => c.file)))];
 }
+/**
+ * The project `agents targets` reports T3 for: the agent argument's, else `--path`'s (resolved as `agents new --path`
+ * resolves it: the repository remote, else the folder), else the current folder's when it is one.
+ */
+function targetsProject(ref, path) {
+    if (ref)
+        return keyOf(ref).split('/')[0];
+    if (path !== undefined)
+        return projectIdentity(path).slug;
+    try {
+        return projectIdentity('./').slug;
+    }
+    catch {
+        return null;
+    }
+}
 export const TARGET_HANDLERS = {
     async 'agents targets'(ctx, values, [ref]) {
-        const detected = installedTargets(ctx.io.env);
+        const found = installedTargets(ctx.io.env);
+        // models (0.17.0+): the model and effort choices a new thread can start with; clients never hardcode them.
+        // T3 Code mode (0.17.0+): T3's state for this project (the agent's, else this folder's), and where `shard ./` opens
+        // each app's new conversations (--open-in sets it).
+        const project = targetsProject(ref, typeof values.path === 'string' ? values.path : undefined);
+        const t3 = t3Status(ctx, { project, lastUsed: true });
+        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 }) };
         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) : [];
         const entries = ref || values.remove === true
             ? await targets.configure(key, ctx.apiUrl, detected.targets.filter((t) => t === 'claude-desktop' || t === 'codex-app' || t === 't3'), values.remove === true, ctx.signal)
             : [];
-        const detection = `${detected.clients.join(', ') || 'No installed agent clients'}\nOpen targets: ${detected.targets.join(', ')}\n`;
+        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`;
         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 });
+            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 });
             return Promise.resolve(0);
         }
         const entry = key ? entries.find(e => e.workspace === key) : undefined;
         if (!entry) {
-            out(ctx, detection, { ...detected, entries });
+            out(ctx, detection, { ...detected, entries, models: MODEL_CHOICES });
             return Promise.resolve(0);
         }
-        const t3 = detected.targets.includes('t3');
-        const configured = configuredTargets(targets, entry, t3);
+        const t3Installed = detected.targets.includes('t3');
+        const configured = configuredTargets(targets, entry, t3Installed);
         out(ctx, `Configured ${entry.workspace} as SSH host ${entry.host}:\n${configured.map(c => `  ${c.label.padEnd(15)} ${tilde(targets, c.file)}${c.detail ? ` ${c.detail}` : ''}`).join('\n')}\n` +
-            ['claude-desktop', 'codex-app', 't3'].filter(t => t === 't3' ? !t3 : !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 })) });
+            ['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);
     },
     'agents open claude-desktop': openTarget('claude-desktop'),

package/dist/agent-targets.d.ts

@@ -7,6 +7,9 @@ export interface TargetEntry {
     agent: string;
     targets: DesktopTarget[];
 }
+/** What Claude Desktop and the Codex app list a target as: the project's router "Shardflux · <project>", an agent
+ * "<agent> · <project>" (the thing, then the place, as session titles are; no tag). */
+export declare const targetLabel: (e: Pick<TargetEntry, "agent" | "project">) => string;
 export declare function targetIdentity(key: string): Pick<TargetEntry, 'host' | 'workspace' | 'project' | 'agent'>;
 /** Replace only a marked block, retaining every byte outside it. Put Includes before user Host blocks. */
 export declare function managedBlock(text: string, body: string): string;
@@ -17,6 +20,8 @@ export declare function t3Apps(dirs: string[], platform?: NodeJS.Platform): Arra
 }>;
 /** The app folders scanned for desktop apps: SHARDFLUX_APPLICATIONS_DIRS, else /Applications and ~/Applications. */
 export declare function applicationDirs(env: Record<string, string | undefined>): string[];
+/** The first `name` app bundle with this bundle id in the app folders (macOS only). */
+export declare function desktopAppPath(dirs: string[], name: string, bundle: string, platform?: NodeJS.Platform): string | undefined;
 export declare function installedTargets(env: Record<string, string | undefined>, platform?: NodeJS.Platform, appDirs?: string[]): {
     targets: string[];
     clients: string[];

package/dist/agent-targets.js

@@ -15,6 +15,9 @@ const shellQuote = (s) => "'" + s.replaceAll("'", "'\\''").replaceAll('%', '%%')
 const quote = (s) => '"' + s.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%') + '"';
 // Some SSH config readers (T3 Code's host discovery) split Include on whitespace and keep quotes; quote only when needed.
 const includePath = (s) => /^[^\s"'\\#%]+$/.test(s) ? s : quote(s);
+/** What Claude Desktop and the Codex app list a target as: the project's router "Shardflux · <project>", an agent
+ * "<agent> · <project>" (the thing, then the place, as session titles are; no tag). */
+export const targetLabel = (e) => e.agent === 'router' ? `Shardflux · ${e.project}` : `${e.agent} · ${e.project}`;
 export function targetIdentity(key) {
     const parts = key.split('/');
     if (parts.length !== 2 || parts.some(p => !/^[a-z0-9][a-z0-9._-]{0,95}$/.test(p)))
@@ -71,16 +74,22 @@ export function applicationDirs(env) {
     const home = env.HOME || homedir();
     return env.SHARDFLUX_APPLICATIONS_DIRS !== undefined ? env.SHARDFLUX_APPLICATIONS_DIRS.split(':').filter(Boolean) : ['/Applications', join(home, 'Applications')];
 }
-export function installedTargets(env, platform = process.platform, appDirs) {
-    // SHARDFLUX_APPLICATIONS_DIRS (colon-separated) replaces the scanned app folders, like SHARDFLUX_CONFIG_DIR does for config.
-    const dirs = appDirs ?? applicationDirs(env);
-    const hasApp = (name, bundle) => platform === 'darwin' && dirs.map(dir => join(dir, name)).some(path => {
+/** The first `name` app bundle with this bundle id in the app folders (macOS only). */
+export function desktopAppPath(dirs, name, bundle, platform = process.platform) {
+    if (platform !== 'darwin')
+        return undefined;
+    return dirs.map(dir => join(dir, name)).find(path => {
         const info = join(path, 'Contents', 'Info.plist');
         if (!existsSync(info))
             return false;
         const result = spawnSync('/usr/libexec/PlistBuddy', ['-c', 'Print :CFBundleIdentifier', info], { input: '', encoding: 'utf8', timeout: 1000 });
         return result.status === 0 && result.stdout.trim() === bundle;
     });
+}
+export function installedTargets(env, platform = process.platform, appDirs) {
+    // SHARDFLUX_APPLICATIONS_DIRS (colon-separated) replaces the scanned app folders, like SHARDFLUX_CONFIG_DIR does for config.
+    const dirs = appDirs ?? applicationDirs(env);
+    const hasApp = (name, bundle) => desktopAppPath(dirs, name, bundle, platform) !== undefined;
     const versions = {};
     const t3Bundles = t3Apps(dirs, platform);
     const t3 = t3Bundles.length > 0;
@@ -280,7 +289,7 @@ export class AgentTargets {
             if (!(prop in doc) && !manifest.created[file].includes(prop))
                 manifest.created[file].push(prop);
             doc[prop] = [...kept, ...entries.filter(e => e.targets.includes(target)).map(e => {
-                    const label = e.agent === 'router' ? `Shardflux · ${e.project}` : `[SF] ${e.project} · ${e.agent}`;
+                    const label = targetLabel(e);
                     return target === 'claude-desktop' ? { id: e.host, name: label, sshHost: e.host, startDirectory: projectWorkspacePath({ slug: e.project }) } : { sshAlias: e.host, projects: [{ remotePath: projectWorkspacePath({ slug: e.project }), label }] };
                 })];
             if (!doc[prop].length && manifest.created[file].includes(prop))

package/dist/agent-terminal.d.ts

@@ -8,6 +8,14 @@ export interface TerminalConnection {
 }
 /** The workspace (or the VM under this terminal) is asleep: the user's next keystroke wakes it. */
 export declare function sleepingAttach(error: unknown): boolean;
+/**
+ * The wait before the next attach (0.16.0+): an attach refused with a Retry-After (503 `host_capacity` while the
+ * workspace's host makes room, 429 `quota_exceeded`) waits it with up to 20 % jitter; others back off from 100 ms to
+ * 2 s by consecutive failures, which reset once an attach delivers.
+ */
+export declare function reattachDelayMs(error: unknown, failures: number, random?: () => number): number;
+/** The line an attach that waits for room prints (0.16.0+), or null for any other refusal. */
+export declare function admissionNotice(error: unknown): string | null;
 export declare function retryableAttach(error: unknown): boolean;
 /** Offsets address bytes, including escape sequences and UTF-8 split across frames. */
 export declare class PtyOutputCursor {

package/dist/agent-terminal.js

@@ -1,11 +1,29 @@
 import { StringDecoder } from 'node:string_decoder';
-import { PtyConnection, ShardfluxApiError, ShardfluxProtocolError, exitCodePosix } from '@shardflux/sdk';
+import { PtyConnection, ShardfluxApiError, ShardfluxProtocolError, exitCodePosix, isAdmissionRefusal } from '@shardflux/sdk';
 import { UsageError } from "./errors.js";
 /** The workspace (or the VM under this terminal) is asleep: the user's next keystroke wakes it. */
 export function sleepingAttach(error) {
     return error instanceof ShardfluxApiError && error.code === 'workspace_not_running';
 }
 const ASLEEP_NOTICE = '\r\n\x1b[2m· asleep. Type to wake it.\x1b[0m\r\n';
+/**
+ * The wait before the next attach (0.16.0+): an attach refused with a Retry-After (503 `host_capacity` while the
+ * workspace's host makes room, 429 `quota_exceeded`) waits it with up to 20 % jitter; others back off from 100 ms to
+ * 2 s by consecutive failures, which reset once an attach delivers.
+ */
+export function reattachDelayMs(error, failures, random = Math.random) {
+    const hinted = error instanceof ShardfluxApiError ? error.retryAfterSeconds : undefined;
+    if (hinted !== undefined && hinted > 0)
+        return Math.floor(hinted * 1000 * (1 + 0.2 * random()));
+    return Math.min(2_000, 100 * 2 ** Math.min(failures, 5));
+}
+/** The line an attach that waits for room prints (0.16.0+), or null for any other refusal. */
+export function admissionNotice(error) {
+    if (!isAdmissionRefusal(error))
+        return null;
+    const position = typeof error.details?.queue_position === 'number' ? ` (position ${error.details.queue_position})` : '';
+    return error.reason === 'host_capacity' ? `waiting for room on the workspace's host${position}` : 'waiting for a free working slot: every workspace the plan lets work at once is busy';
+}
 export function retryableAttach(error) {
     if (error instanceof ShardfluxProtocolError && /invalid|byte gap|omitted/.test(error.message))
         return false;
@@ -164,6 +182,10 @@ export async function attachTerminal(options) {
         controller.abort();
     } });
     let reconnects = 0;
+    // Consecutive failed attaches: the backoff's exponent, back to 0 once an attach delivers a message.
+    let failures = 0;
+    let lastError;
+    let notice = null;
     let asleep = false;
     try {
         while (!signal.aborted) {
@@ -193,6 +215,9 @@ export async function attachTerminal(options) {
                 for await (const message of connection.messages()) {
                     if (signal.aborted)
                         break;
+                    // The attach delivers: a later drop starts the backoff over, and the next wait for room is said again.
+                    failures = 0;
+                    notice = null;
                     const bytes = cursor.consume(message);
                     if (bytes?.length)
                         io.stdout.write(bytes);
@@ -212,6 +237,7 @@ export async function attachTerminal(options) {
                     asleep = true;
                     continue;
                 }
+                lastError = error;
             }
             finally {
                 const previous = connection;
@@ -220,7 +246,14 @@ export async function attachTerminal(options) {
                 await previous?.close();
             }
             reconnects += 1;
-            await options.sleep(Math.min(2_000, 100 * 2 ** Math.min(reconnects, 5)), signal);
+            failures += 1;
+            // Waiting for room on the workspace's host (or a working slot): said once, and again when the position changes.
+            const waiting = admissionNotice(lastError);
+            if (waiting && waiting !== notice)
+                io.stderr.write(`\r\n\x1b[2m· ${waiting}\x1b[0m\r\n`);
+            notice = waiting;
+            await options.sleep(reattachDelayMs(lastError, failures), signal);
+            lastError = undefined;
         }
         if (inputFailure)
             throw inputFailure;

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.15.2";
+export declare const CLI_VERSION = "0.17.0";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;
@@ -27,9 +27,12 @@ export interface CommandSpec {
     positionals: PositionalSpec[];
     options: Record<string, OptionSpec>;
     examples?: string[];
+    /** Runs, but is left out of the top and group help (a program other tools start, such as a forwarder). */
+    hidden?: boolean;
 }
 export declare const GLOBAL_OPTIONS: Record<string, OptionSpec>;
 export declare const PROJECT_COMMAND: CommandSpec;
+export declare const ONBOARDING_COMMAND: CommandSpec;
 export declare const CENTER_COMMAND: CommandSpec;
 export declare const COMMANDS: CommandSpec[];
 export declare function normalizeWords(words: string[]): string[];
@@ -74,6 +77,7 @@ export type Parsed = {
  */
 export declare function parseCommandLine(argv: readonly string[], options?: {
     tty?: boolean;
+    platform?: NodeJS.Platform;
     isProjectPath?: (path: string) => boolean;
 }): Parsed;
 export declare function usageLine(c: CommandSpec): string;