@shardflux/cli 0.15.2 → 0.17.0

package/dist/handlers.js

@@ -1,3 +1,4 @@
+import { DEVICE_HANDLERS } from "./device-approvals.js";
 import { CREDENTIAL_HANDLERS } from "./credential-prompts.js";
 import { CONVERSATION_HANDLERS } from "./conversation-commands.js";
 /**
@@ -15,5 +16,8 @@ import { MENUBAR_HANDLERS } from "./menubar.js";
 import { UPDATE_HANDLERS } from "./update.js";
 import { FILESYSTEM_HANDLERS } from "./filesystem-commands.js";
 import { CONVERSATION_HANDLERS as LOCAL_CONVERSATION_HANDLERS } from "./conversation-local.js";
+import { TWIN_HANDLERS } from "./worktree-twin-engine.js";
 import { CODEX_CLOUD_HANDLERS } from "./codex-cloud.js";
-export const HANDLERS = { ...CODEX_CLOUD_HANDLERS, ...CONVERSATION_HANDLERS, ...LOCAL_CONVERSATION_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 { 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 };

package/dist/index.d.ts

@@ -24,4 +24,8 @@ export type { ErrorInfo } from './errors.js';
 export { changedText, errorText, executionJson, executionSummary, feedbackCommand, json, suspendRequestText, suspendWhenIdleText, table, time, usageText, workspaceDetail, workspaceTable } from './format.js';
 export { TimingRecorder, coldBootNotice, hostLostNotice, lostSuspendNotice, notices, timingJson, timingText } from './timing.js';
 export { readAgentCredentials, syncAgentCredentials } from './agent-credentials.js';
+export { detectLocalCliProxy, importCliProxy } from './cli-proxy.js';
+export type { ImportOptions, ImportResult, LocalCliProxy, LocalLogin } from './cli-proxy.js';
+export { ensureCliProxyHub, readHubInfo } from './cli-proxy-hub.js';
+export type { EnsureOptions, EnsureResult, HubInfo } from './cli-proxy-hub.js';
 export type { CredentialSources } from './agent-credentials.js';

package/dist/index.js

@@ -16,3 +16,6 @@ export { EXIT, AuthConfigError, CheckoutEndedError, ExecutionFailedError, Execut
 export { changedText, errorText, executionJson, executionSummary, feedbackCommand, json, suspendRequestText, suspendWhenIdleText, table, time, usageText, workspaceDetail, workspaceTable } from "./format.js";
 export { TimingRecorder, coldBootNotice, hostLostNotice, lostSuspendNotice, notices, timingJson, timingText } from "./timing.js";
 export { readAgentCredentials, syncAgentCredentials } from "./agent-credentials.js";
+// Hosted CLIProxyAPI (onboarding offers the import when detectLocalCliProxy() finds logins).
+export { detectLocalCliProxy, importCliProxy } from "./cli-proxy.js";
+export { ensureCliProxyHub, readHubInfo } from "./cli-proxy-hub.js";

package/dist/linux-helper.d.ts

@@ -0,0 +1,12 @@
+import type { Ctx } from './commands.js';
+export declare const HELPER_UNIT = "shardflux-helper.service";
+export declare const helperUnitPath: (home: string) => string;
+/** No credentials in the unit: the helper reads the same private store as shard. */
+export declare function helperUnit(ctx: Pick<Ctx, 'runtime' | 'store' | 'apiUrl' | 'io'>): string;
+export type Systemctl = (args: string[]) => boolean;
+export declare function installLinuxHelper(ctx: Ctx, deps?: {
+    platform?: NodeJS.Platform;
+    run?: Systemctl;
+}): boolean;
+/** The caller owns fallback lifetime; never leave an unmanaged background process behind. */
+export declare function startLinuxHelper(ctx: Ctx): () => Promise<void>;

package/dist/linux-helper.js

@@ -0,0 +1,88 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { readFileSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { CLI_VERSION } from "./args.js";
+import { writePrivateFile } from "./credentials.js";
+import { runDeviceHelper } from "./device-helper.js";
+export const HELPER_UNIT = 'shardflux-helper.service';
+export const helperUnitPath = (home) => join(home, '.config/systemd/user', HELPER_UNIT);
+const quote = (s) => '"' + s.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('%', '%%').replaceAll('\n', '\\n').replaceAll('\r', '\\r') + '"';
+/** No credentials in the unit: the helper reads the same private store as shard. */
+export function helperUnit(ctx) {
+    if (!ctx.runtime)
+        throw new Error('An installed shard is required.');
+    let script = ctx.runtime.script;
+    try {
+        script = realpathSync(script);
+    }
+    catch { /* preserve the supplied installed path */ }
+    const env = { HOME: ctx.io.env.HOME, PATH: ctx.io.env.PATH ?? '/usr/local/bin:/usr/bin:/bin', SHARDFLUX_CONFIG_DIR: ctx.store.dir,
+        SHARDFLUX_API_URL: ctx.apiUrl, SHARDFLUX_NO_UPDATE_CHECK: '1',
+        ...Object.fromEntries(['DISPLAY', 'WAYLAND_DISPLAY', 'DBUS_SESSION_BUS_ADDRESS', 'XDG_RUNTIME_DIR', 'CODEX_HOME', 'CLAUDE_CONFIG_DIR'].flatMap(k => ctx.io.env[k] ? [[k, ctx.io.env[k]]] : [])) };
+    return `# Shardflux CLI ${CLI_VERSION}\n[Unit]\nDescription=Shardflux background helper\nAfter=network-online.target\n\n[Service]\nType=simple\nExecStart=${[ctx.runtime.node, script, 'device-helper', '--service'].map(s => quote(s.replaceAll('$', '$$'))).join(' ')}\n${Object.entries(env).map(([k, v]) => `Environment=${quote(`${k}=${v}`)}`).join('\n')}\nRestart=on-failure\nRestartSec=5\nTimeoutStopSec=10\nUMask=0077\n\n[Install]\nWantedBy=default.target\n`;
+}
+export function installLinuxHelper(ctx, deps = {}) {
+    if ((deps.platform ?? process.platform) !== 'linux' || !ctx.runtime || !ctx.io.env.HOME)
+        return false;
+    const run = deps.run ?? (args => spawnSync('systemctl', ['--user', ...args], { env: ctx.io.env, stdio: 'ignore', timeout: 5000 }).status === 0);
+    // Probe before writing: containers without a user manager use the command-lifetime helper.
+    if (!run(['show-environment']))
+        return false;
+    const file = helperUnitPath(ctx.io.env.HOME), text = helperUnit(ctx);
+    const receipt = join(ctx.store.dir, 'linux-helper-started'), digest = createHash('sha256').update(text).digest('hex');
+    let before = '', started = '';
+    try {
+        before = readFileSync(file, 'utf8');
+    }
+    catch { /* first sign-in */ }
+    try {
+        started = readFileSync(receipt, 'utf8');
+    }
+    catch { /* no successful start yet */ }
+    if (before !== text) {
+        writePrivateFile(dirname(file), file, text);
+        if (!run(['daemon-reload']) || !run(['enable', '--now', HELPER_UNIT]))
+            return false;
+        if (before && !run(['restart', HELPER_UNIT]))
+            return false;
+    }
+    else if (!run(['is-active', '--quiet', HELPER_UNIT])) {
+        if (!run(['enable', '--now', HELPER_UNIT]))
+            return false;
+    }
+    else if (started !== digest && !run(['restart', HELPER_UNIT]))
+        return false;
+    // A failed restart must be retried by the next command even though the new unit was already written.
+    if (started !== digest)
+        writePrivateFile(ctx.store.dir, receipt, digest);
+    return true;
+}
+/** The caller owns fallback lifetime; never leave an unmanaged background process behind. */
+export function startLinuxHelper(ctx) {
+    const noop = () => Promise.resolve();
+    if (process.platform !== 'linux' || !ctx.runtime)
+        return noop;
+    try {
+        ctx.apiKey();
+    }
+    catch {
+        return noop;
+    }
+    try {
+        if (installLinuxHelper(ctx))
+            return noop;
+    }
+    catch { /* use the command-lifetime helper */ }
+    const notice = join(ctx.store.dir, 'linux-helper-notice');
+    try {
+        readFileSync(notice);
+    }
+    catch {
+        ctx.io.stderr.write('Shardflux helper runs while shard commands are open on this computer.\n');
+        writePrivateFile(ctx.store.dir, notice, '1\n');
+    }
+    const abort = new AbortController();
+    const work = runDeviceHelper({ ...ctx, signal: AbortSignal.any([ctx.signal, abort.signal]) }, { service: true }).catch(() => undefined);
+    return async () => { abort.abort(); await work; };
+}

package/dist/linux-terminal.d.ts

@@ -0,0 +1,11 @@
+import type { Ctx } from './commands.js';
+import type { Values } from './args.js';
+/** Linux terminals use the existing native Codex harness; explicit app routes keep Cloud. */
+export declare function linuxTerminalSession(ctx: Pick<Ctx, 'io' | 'json'>, values: Values, platform?: NodeJS.Platform): boolean;
+export declare const shellWord: (s: string) => string;
+export declare function linuxTerminalCommand(argv: string[], env: Record<string, string | undefined>): {
+    command: string;
+    args: string[];
+} | null;
+/** Invoked before cloud work: the new terminal owns the attach, credentials and any prompts. */
+export declare function openLinuxTerminal(ctx: Ctx, ref: string, app?: string): Promise<number>;

package/dist/linux-terminal.js

@@ -0,0 +1,42 @@
+import { accessSync, constants } from 'node:fs';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+/** Linux terminals use the existing native Codex harness; explicit app routes keep Cloud. */
+export function linuxTerminalSession(ctx, values, platform = process.platform) {
+    return platform === 'linux' && (values.in === 'terminal' || (values.in === undefined && !!ctx.io.stdin.isTTY && !ctx.json));
+}
+export const shellWord = (s) => `'${s.replaceAll("'", "'\\''")}'`;
+export function linuxTerminalCommand(argv, env) {
+    const executable = (name) => name.includes('/') ? [name] : (env.PATH ?? '').split(':').filter(Boolean).map(p => join(p, name));
+    const exists = (name) => executable(name).some(p => { try {
+        accessSync(p, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    } });
+    // The shell keeps the window open on an attach error so the user can read and retry it.
+    const attach = ['sh', '-c', `${argv.map(shellWord).join(' ')}; status=$?; if [ "$status" -ne 0 ]; then printf '\nPress Enter to close.'; read answer; fi; exit "$status"`];
+    for (const command of [...new Set([env.TERMINAL?.trim(), 'x-terminal-emulator', 'gnome-terminal'].filter((s) => !!s))]) {
+        if (exists(command))
+            return { command, args: [command === 'gnome-terminal' ? '--' : '-e', ...attach] };
+    }
+    return null;
+}
+/** Invoked before cloud work: the new terminal owns the attach, credentials and any prompts. */
+export async function openLinuxTerminal(ctx, ref, app) {
+    const words = ['agents', 'open', ref, '--in', 'terminal', ...(app ? ['--app', app] : [])];
+    const argv = ctx.runtime ? [ctx.runtime.node, ctx.runtime.script, '--api-url', ctx.apiUrl, ...words] : ['shard', ...words];
+    const choice = linuxTerminalCommand(argv, ctx.io.env);
+    if (choice) {
+        const child = spawn(choice.command, choice.args, { env: ctx.io.env, cwd: process.cwd(), detached: true, stdio: 'ignore' });
+        try {
+            await new Promise((resolve, reject) => { child.once('spawn', resolve); child.once('error', reject); });
+            child.unref();
+            return 0;
+        }
+        catch { /* print a runnable command if the terminal could not start */ }
+    }
+    ctx.io.stdout.write(`${['shard', '--api-url', ctx.apiUrl, ...words].map(shellWord).join(' ')}\n`);
+    return 0;
+}

package/dist/main.js

@@ -13,12 +13,15 @@
 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, PROJECT_COMMAND, commandHelp, parseCommandLine, resolveApiUrl, resolveWake, resolveWakeTimeout } from "./args.js";
+import { CLI_VERSION, CENTER_COMMAND, ONBOARDING_COMMAND, PROJECT_COMMAND, commandHelp, parseCommandLine, resolveApiUrl, resolveWake, resolveWakeTimeout } from "./args.js";
 import { commandCenter } from "./command-center.js";
-import { launchConversationProject } from "./conversation-terminal.js";
+import { launchProjectCommand } from "./conversation-terminal.js";
 import { runAcp } from "./acp.js";
 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 { startLinuxHelper } from "./linux-helper.js";
 import { runDeviceHelper } from "./device-helper.js";
 import { housekeeping, startupHousekeeping } from "./agent-git-commands.js";
 import { CredentialStore, configDir } from "./credentials.js";
@@ -31,6 +34,7 @@ import { HANDLERS } from "./handlers.js";
 import { makeFetch } from "./http.js";
 import { Input } from "./input.js";
 import { TimingRecorder, notices, timingJson, timingText } from "./timing.js";
+import { waitStatusListener } from "./wait-status.js";
 import { CLI_DISTRIBUTION, NOTICE_WAIT_MS, UpdateCheck, noticeOf, updateCheckDisabled, updateView } from "./update-check.js";
 const KEY_SHAPE = /^sfk_[a-z2-7]{16}_[A-Za-z0-9]+$/;
 // Printable (no C0 controls or DEL), as the API's AgentLabel pattern.
@@ -126,7 +130,7 @@ function hintFor(info, cred, file, command = '') {
     if (reason === 'edit_not_text')
         return 'the file is not UTF-8 text; use files write for binary data';
     if (reason === 'host_capacity')
-        return 'the workspace cannot be woken right now and the call did not run; retry in a few seconds';
+        return "the workspace's host is making room to wake it and the call did not run (it was already retried); run the command again";
     if (reason === 'host_feature_unavailable')
         return hostFeatureHint(info.details?.feature);
     // Inbound ports (0.9.0): the next step names the command.
@@ -534,6 +538,7 @@ export async function run(argv, io, opts = {}) {
             agentLabel,
             wake,
             wakeTimeoutMs,
+            wakeTimeoutExplicit: parsed.global.wakeTimeout !== undefined || Boolean(io.env.SHARDFLUX_WAKE_TIMEOUT_MS?.trim()),
             signal,
             timing: showTiming,
             traces,
@@ -569,13 +574,18 @@ export async function run(argv, io, opts = {}) {
                 if (cloud)
                     return cloud;
                 const key = apiKey();
+                // Timings, and (0.16.0+) where a wait stands: a queued start's position, a call waiting for room (stderr).
+                const waitStatus = waitStatusListener(io.stderr, parsed.global.json);
                 cloud = new Shardflux({
                     apiKey: key.token,
                     baseUrl: apiUrl,
                     userAgent,
                     fetch: watchedFetch,
                     sleep,
-                    onProgress: traces.listener,
+                    onProgress: (e) => {
+                        traces.listener(e);
+                        waitStatus(e);
+                    },
                     versionCheck: false,
                 });
                 return cloud;
@@ -653,7 +663,7 @@ export async function run(argv, io, opts = {}) {
             refreshMenubarInBackground({ dir: store.dir, home: io.env.HOME || homedir(), runtime: opts.runtime, env: { ...process.env, ...io.env } });
         }
         // The update check runs next to the command (not for `version`, which reports it itself).
-        if (!updateCheckDisabled(io.env) && !['version', 'update', 'ssh-proxy', 'acp', 'device-helper'].includes(parsed.command.path[0]) && command !== 'menubar refresh') {
+        if (!updateCheckDisabled(io.env) && !['version', 'update', 'ssh-proxy', 'acp', 'device-helper'].includes(parsed.command.path[0]) && command !== 'menubar refresh' && command !== 'cli-proxy forward') {
             try {
                 updates = new UpdateCheck({ dir: store.dir, apiUrl, distribution, fetch: base, userAgent, registry: npmRegistry(io.env) });
                 updates.start();
@@ -666,11 +676,28 @@ export async function run(argv, io, opts = {}) {
     catch (err) {
         return report(err);
     }
-    const handler = parsed.command.path[0] === 'acp' ? (ctx) => parsed.values.login === true ? runAcpLogin(ctx) : runAcp(ctx) : parsed.command.path[0] === 'device-helper' ? runDeviceHelper : command === 'menubar refresh' ? runMenubarRefresh : parsed.command === PROJECT_COMMAND ? launchConversationProject : parsed.command === CENTER_COMMAND ? commandCenter : HANDLERS[parsed.command.path.join(' ')];
+    let stopHelper;
+    const startHelper = () => {
+        if (stopHelper)
+            return;
+        try {
+            ctx.apiKey();
+        }
+        catch {
+            return;
+        }
+        stopHelper = startLinuxHelper(ctx);
+    };
+    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 ? (ctx, values) => 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(' ')}"`));
-    if (!['acp', 'device-helper'].includes(parsed.command.path[0]) && command !== 'menubar refresh')
+    // Long-running helpers other programs start (an editor, launchd, the menu bar) skip the per-command housekeeping.
+    if (!['acp', 'device-helper'].includes(parsed.command.path[0]) && command !== 'menubar refresh' && command !== 'cli-proxy forward') {
+        // An updated shard restarts this computer's CLIProxyAPI forwarder on itself (a no-op unless the version changed).
+        await refreshForwarderAgent(io.env, ctx.store.dir).catch(() => false);
         await housekeeping(ctx);
+        startHelper();
+    }
     const running = handler(ctx, parsed.values, parsed.positionals).then((code) => ({ code }), (err) => ({ err }));
     // On Ctrl-C give the command a moment to clean up (exec sends a cancel), then stop regardless.
     const interrupted = new Promise((resolve) => {
@@ -705,6 +732,9 @@ export async function run(argv, io, opts = {}) {
         if (notice)
             io.stderr.write(notice);
     }
+    if (!['acp', 'device-helper'].includes(parsed.command.path[0]) && command !== 'menubar refresh' && command !== 'cli-proxy forward')
+        startHelper();
+    await stopHelper?.();
     return code;
 }
 /**
@@ -731,7 +761,7 @@ export async function main(opts = {}) {
     const runtime = { node: process.execPath, script: process.argv[1] ?? '' };
     // The menu bar's update button runs this shard; it finds it here (macOS only, written when it changes).
     if (process.platform === 'darwin' && runtime.script)
-        recordInstall(configDir(process.env), runtime, opts.distribution ?? CLI_DISTRIBUTION);
+        recordInstall(configDir(process.env), runtime, opts.distribution ?? CLI_DISTRIBUTION, process.env);
     const code = await run(process.argv.slice(2), { stdout: process.stdout, stderr: process.stderr, stdin: process.stdin, env: process.env }, { signal: controller.signal, runtime, ...(opts.distribution ? { distribution: opts.distribution } : {}) });
     await Promise.all([flush(process.stdout), flush(process.stderr)]);
     process.exit(code);

package/dist/onboarding.d.ts

@@ -26,10 +26,12 @@ type CredentialRow = {
         checked_at: string;
     };
 };
+/** `url`: a page the person opens (the T3 Connect sign-in), instead of a command. */
 type Action = {
     title: string;
     command?: string[];
     retry?: boolean;
+    url?: string;
 };
 export interface Connection {
     id: 'account' | AgentApp | 't3';

package/dist/onboarding.js

@@ -1,7 +1,11 @@
 import { readFile, stat } from 'node:fs/promises';
 import { delimiter, join, resolve, basename } from 'node:path';
 import { homedir } from 'node:os';
+import { ShardfluxApiError } from '@shardflux/sdk';
 import { resolveWorkspace } from "./commands.js";
+import { AgentStateStore } from "./agent-state.js";
+import { describeError } from "./errors.js";
+import { t3PhoneLink } from "./t3-phone.js";
 import { readAgentCredentials, syncAgentCredentials } from "./agent-credentials.js";
 import { getConversation } from "./conversations.js";
 import { codexHealth, readCodexConnector, restartCodexConnector } from "./codex-cloud.js";
@@ -79,15 +83,59 @@ export async function t3Connection(ctx, signedIn, appDirs = applicationDirs(ctx.
             return { ...base, mode: 'provider', state: 'action', fact: error instanceof Error ? error.message : 'T3 Code’s settings could not be updated.', action: { title: 'Check again' } };
         }
     }
-    // Stable T3: an SSH environment per project; the newest one this API set up is the one to add.
+    // Stable T3: an SSH environment per project; the newest one this API set up is the one to add. They are recorded in
+    // agents.json (targets.json keeps T3 out of its manifest); a manifest entry from an older CLI still counts.
+    const recorded = new AgentStateStore(ctx.store.dir).t3Environments(ctx.apiUrl).at(-1);
     const manifest = await jsonFile(join(ctx.store.dir, 'targets.json'));
     const entries = Array.isArray(manifest?.entries) ? manifest.entries : [];
-    const host = entries.filter(e => e.api_url === ctx.apiUrl && Array.isArray(e.targets) && e.targets.includes('t3') && typeof e.host === 'string').map(e => e.host).at(-1);
-    if (host)
-        return { ...base, mode: 'ssh', state: 'verified', fact: `In T3 Code: Add environment → SSH → ${host}` };
+    const legacy = entries.filter(e => e.api_url === ctx.apiUrl && Array.isArray(e.targets) && e.targets.includes('t3') && typeof e.host === 'string').at(-1);
+    const host = recorded?.host ?? legacy?.host;
+    const workspaceKey = recorded?.workspace ?? (typeof legacy?.workspace === 'string' ? legacy.workspace : undefined);
+    if (host) {
+        const desktop = `In T3 Code: Add environment → SSH → ${host}`;
+        const phone = await t3Phone(ctx, workspaceKey);
+        if (!phone)
+            return { ...base, mode: 'ssh', state: 'verified', fact: desktop };
+        return { ...base, mode: 'ssh', ...phone, fact: phone.state === 'verified' ? `${desktop}. On your phone: ${phone.fact}` : phone.fact };
+    }
     // An SSH environment is per project (shardflux-<project>-main): it is set up once a project is picked.
     return { ...base, mode: 'ssh', state: 'info', fact: 'Available after you pick a project.', next: shard(['agents', 'new', '--in', 't3', '--path', '<project>']) };
 }
+/**
+ * The T3 app on the phone (T3 Connect, 0.17.0+): the workspace is linked with the person's one T3 Connect sign-in. The
+ * sign-in is a page to open once; afterwards every project appears in the T3 app by itself. Undefined when the API has
+ * no T3 Connect: the desktop route is the whole card then.
+ */
+async function t3Phone(ctx, key) {
+    if (!key)
+        return undefined;
+    try {
+        const ws = await resolveWorkspace(ctx, key);
+        const cloud = ctx.cloud();
+        const known = (await cloud.t3.status()).links.find(l => l.workspace_id === ws.id);
+        // A workspace connected to T3 before T3 Connect, or one whose link failed, is linked now: it is the person's choice.
+        const { link, signIn, needsLogin } = !known || known.status === 'error' || known.status === 'needs_sign_in'
+            ? await t3PhoneLink(ctx, ws.id) : { link: known, signIn: undefined, needsLogin: false };
+        if (link.status === 'linked')
+            return { state: 'verified', fact: `${link.label} in the T3 app.` };
+        if (signIn) {
+            return { state: 'action', fact: `To use it from the T3 app on your phone, confirm ${signIn.user_code} once.`,
+                action: { title: 'Connect phone', url: signIn.verification_uri } };
+        }
+        if (needsLogin)
+            return { state: 'info', fact: 'Sign in to Shardflux on this Mac to use it from the T3 app.' };
+        return { state: 'pending', fact: `Adding ${link.label} to the T3 app on your phone…` };
+    }
+    catch (error) {
+        // No T3 Connect on this API, or nothing to ask it: the desktop route stands on its own.
+        if (!(error instanceof ShardfluxApiError) || describeError(error).code === 'not_found')
+            return undefined;
+        // Another member's T3 Connect sign-in links this project: it is in their T3 app, not something to fix here.
+        if (error.details?.reason === 't3_linked_by_other_member')
+            return { state: 'info', fact: 'In the T3 app of the member who linked it.' };
+        return { state: 'unknown', fact: 'The T3 app link could not be checked just now.', action: { title: 'Retry', retry: true } };
+    }
+}
 const shard = (words) => ['shard', ...words];
 /** Claude: the account login is ready and Claude itself accepts it right now. */
 export function claudeConnection(row) {
@@ -105,7 +153,7 @@ export function codexConnection(local, synced, connector, health) {
     const enable = { title: 'Connect Codex', command: shard(['agents', 'codex', 'enable']) };
     if (!synced) {
         return local ? { state: 'action', fact: 'Available on web and phone once connected.', action: enable }
-            : { state: 'action', fact: 'Sign in to Codex on this Mac first.', action: { title: 'Sign in to Codex', command: ['codex', 'login'] } };
+            : { state: 'action', fact: 'Sign in to Codex on this computer first.', action: { title: 'Sign in to Codex', command: ['codex', 'login'] } };
     }
     const retry = { title: 'Retry', retry: true, command: shard(['setup', '--inspect', '--apps', 'codex', '--connect', '--retry-codex']) };
     switch (health) {

package/dist/registry.d.ts

@@ -1,48 +1,8 @@
-export declare const NPM_REGISTRY = "https://registry.npmjs.org";
-/** Each registry request's timeout (ms). */
-export declare const REGISTRY_TIMEOUT_MS = 3000;
+import type { RegistryOptions } from '@shardflux/sdk';
+export { NPM_REGISTRY, npmLatest, withRegistryLatest } from '@shardflux/sdk';
 /** The npm packages whose versions `shard update` compares. */
 export declare const NPM_CLIENTS: readonly ["shardflux", "@shardflux/cli", "@shardflux/sdk", "@shardflux/mcp", "@shardflux/menubar-darwin"];
-export interface RegistryAnswer {
-    latest: string | null;
-    /** The registry's validator for the next request (npm's dist-tags endpoint sends none today). */
-    etag: string | null;
-    /** 304: what the caller cached under `etag` is still current. */
-    notModified: boolean;
-}
-export interface RegistryOptions {
-    fetch: typeof fetch;
-    /** Default https://registry.npmjs.org (SHARDFLUX_NPM_REGISTRY overrides it for the CLI). */
-    registry?: string;
-    etag?: string | null;
-    timeoutMs?: number;
-    signal?: AbortSignal;
-    userAgent?: string;
-}
 /** The registry to ask: SHARDFLUX_NPM_REGISTRY, else npm's public registry. */
 export declare function npmRegistry(env: Record<string, string | undefined>): string;
-/** `latest` of an npm package from `<registry>/-/package/<name>/dist-tags`, or null when the registry did not answer. */
-export declare function npmLatest(pkg: string, opts: RegistryOptions): Promise<RegistryAnswer | null>;
 /** `latest` of every package in `packages`, asked in parallel; a package the registry did not answer is absent. */
 export declare function npmLatestAll(packages: readonly string[], opts: RegistryOptions): Promise<Record<string, string>>;
-export interface CatalogEntry {
-    package: string;
-    ecosystem: string;
-    latest: string | null;
-    minimum_supported: string | null;
-    upgrade_command: string | null;
-    release_notes_url: string | null;
-    hold?: string | null;
-    [key: string]: unknown;
-}
-/**
- * A GET /v1/client-versions body whose npm entries carry the registry's `latest` (`registry`: package -> version; an
- * absent package keeps the catalog's). Works with every catalog shape the API has served: no `hold` field, `latest`
- * null, a package missing from the list, or no catalog at all (`catalog` null: the API did not answer).
- *
- * `hold`: when the registry's latest is that version, it is not recommended; the catalog's own `latest` is, when it is
- * older, else `minimum_supported` (so "no longer supported" still works and nobody is told to update).
- */
-export declare function withRegistryLatest(catalog: unknown, registry: Record<string, string | null | undefined>): {
-    clients: CatalogEntry[];
-};

package/dist/registry.js

@@ -1,102 +1,18 @@
 /**
- * The latest version of each Shardflux client comes from its registry (0.15.2+), so a release is known the moment it
- * is published: npm's `latest` dist-tag, which is what `npm i -g shardflux` and `shard update` install. (`stable` is an
- * opt-in tag for installs behind a release-age gate, docs/progress/packaging.md; it never drives the update notice.)
- *
- * The API catalog (GET /v1/client-versions) still says which versions it serves (`minimum_supported`) and may name a
- * version to stop recommending (`hold`, an emergency brake). Its `latest` is only the fallback when the registry does
- * not answer. Every request here is bounded and never throws: offline means "no answer".
+ * The latest version of each Shardflux client comes from npm (0.15.2+; the SDK's registry helpers): its `latest`
+ * dist-tag is what `npm i -g shardflux` and `shard update` install. The API catalog adds `minimum_supported` and
+ * `hold` (see withRegistryLatest).
  */
-import { compareVersions } from '@shardflux/sdk';
-export const NPM_REGISTRY = 'https://registry.npmjs.org';
-/** Each registry request's timeout (ms). */
-export const REGISTRY_TIMEOUT_MS = 3_000;
+import { npmLatest, registryFromEnv } from '@shardflux/sdk';
+export { NPM_REGISTRY, npmLatest, withRegistryLatest } from '@shardflux/sdk';
 /** The npm packages whose versions `shard update` compares. */
 export const NPM_CLIENTS = ['shardflux', '@shardflux/cli', '@shardflux/sdk', '@shardflux/mcp', '@shardflux/menubar-darwin'];
-const str = (v) => (typeof v === 'string' && v.length > 0 ? v : null);
-const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
 /** The registry to ask: SHARDFLUX_NPM_REGISTRY, else npm's public registry. */
 export function npmRegistry(env) {
-    const own = env.SHARDFLUX_NPM_REGISTRY?.trim();
-    return own ? own.replace(/\/+$/, '') : NPM_REGISTRY;
-}
-/** `latest` of an npm package from `<registry>/-/package/<name>/dist-tags`, or null when the registry did not answer. */
-export async function npmLatest(pkg, opts) {
-    try {
-        const timeout = AbortSignal.timeout(opts.timeoutMs ?? REGISTRY_TIMEOUT_MS);
-        const headers = { accept: 'application/json' };
-        if (opts.userAgent)
-            headers['user-agent'] = opts.userAgent;
-        if (opts.etag)
-            headers['if-none-match'] = opts.etag;
-        const res = await opts.fetch(`${(opts.registry ?? NPM_REGISTRY).replace(/\/+$/, '')}/-/package/${encodeURIComponent(pkg)}/dist-tags`, {
-            method: 'GET',
-            headers,
-            signal: opts.signal ? AbortSignal.any([timeout, opts.signal]) : timeout,
-        });
-        const etag = res.headers.get('etag');
-        if (res.status === 304) {
-            await res.body?.cancel().catch(() => undefined);
-            return { latest: null, etag: etag ?? opts.etag ?? null, notModified: true };
-        }
-        if (!res.ok) {
-            await res.body?.cancel().catch(() => undefined);
-            return null;
-        }
-        const body = JSON.parse(await res.text());
-        const latest = isObj(body) ? str(body.latest) : null;
-        // A tag that is not a version (a broken registry mirror) is no answer.
-        if (latest === null || compareVersions(latest, latest) === null)
-            return null;
-        return { latest, etag, notModified: false };
-    }
-    catch {
-        return null;
-    }
+    return registryFromEnv(env, 'npm');
 }
 /** `latest` of every package in `packages`, asked in parallel; a package the registry did not answer is absent. */
 export async function npmLatestAll(packages, opts) {
     const answers = await Promise.all(packages.map(async (pkg) => [pkg, await npmLatest(pkg, { ...opts, etag: null })]));
     return Object.fromEntries(answers.flatMap(([pkg, a]) => (a?.latest ? [[pkg, a.latest]] : [])));
 }
-const DEFAULT_UPGRADE = {
-    shardflux: 'npm i -g shardflux',
-    '@shardflux/cli': 'npm i -g shardflux',
-    '@shardflux/menubar-darwin': 'shard update',
-};
-/**
- * A GET /v1/client-versions body whose npm entries carry the registry's `latest` (`registry`: package -> version; an
- * absent package keeps the catalog's). Works with every catalog shape the API has served: no `hold` field, `latest`
- * null, a package missing from the list, or no catalog at all (`catalog` null: the API did not answer).
- *
- * `hold`: when the registry's latest is that version, it is not recommended; the catalog's own `latest` is, when it is
- * older, else `minimum_supported` (so "no longer supported" still works and nobody is told to update).
- */
-export function withRegistryLatest(catalog, registry) {
-    const listed = isObj(catalog) && Array.isArray(catalog.clients) ? catalog.clients.filter(isObj) : [];
-    const entries = listed.map((c) => ({
-        ...c,
-        package: String(c.package),
-        ecosystem: String(c.ecosystem),
-        latest: str(c.latest),
-        minimum_supported: str(c.minimum_supported),
-        upgrade_command: str(c.upgrade_command),
-        release_notes_url: str(c.release_notes_url),
-        hold: str(c.hold),
-    }));
-    for (const pkg of Object.keys(registry)) {
-        if (!entries.some((e) => e.ecosystem === 'npm' && e.package === pkg)) {
-            entries.push({ package: pkg, ecosystem: 'npm', latest: null, minimum_supported: null, upgrade_command: DEFAULT_UPGRADE[pkg] ?? null, release_notes_url: `https://www.npmjs.com/package/${pkg}?activeTab=versions`, hold: null });
-        }
-    }
-    return {
-        clients: entries.map((e) => {
-            const fromRegistry = e.ecosystem === 'npm' ? str(registry[e.package]) : null;
-            let latest = fromRegistry ?? e.latest;
-            if (latest !== null && e.hold && compareVersions(latest, e.hold) === 0) {
-                latest = e.latest !== null && compareVersions(e.latest, e.hold) === -1 ? e.latest : e.minimum_supported;
-            }
-            return { ...e, latest };
-        }),
-    };
-}

package/dist/t3-launch.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The CLI side of T3 Code mode (0.17.0+): `shard agents new --in t3 [--prompt…] [--on <ref>]`, `shard ./` and
+ * `--in auto` when T3 is where new conversations open, and `shard agents open t3 <conversation|workspace>`.
+ * --json results (contract shared with the menu bar):
+ *   new:  { target: "t3", mode, project, t3_thread_id, conversation_id, workspace: { workspace_key, id } | null,
+ *           opened: true, focused: false, model, effort, ... }
+ *   open: { opened: true, t3_thread_id, focused: false, ... }
+ * `focused` is false: T3 has no way to show a given thread from outside, so T3 is brought to the front instead.
+ */
+import type { Workspace } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+import type { Values } from './args.js';
+import type { AgentApp, T3Install, T3ThreadRequest, T3ThreadResult } from './t3-mode.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.
+ */
+export declare function withT3Context(error: unknown, ref: {
+    workspace_key?: string | null;
+    conversation_id?: string | null;
+    t3_thread_id?: string | null;
+}): unknown;
+/** The thread to start, when the command carries a first message (`--prompt`, `--prompt-file`, `--image`, `--model`, `--effort`). */
+export declare function t3ThreadRequest(ctx: Ctx, values: Values, app: AgentApp): Promise<T3ThreadRequest | undefined>;
+/**
+ * `agents new --in t3`: with a first message in ACP mode, the thread starts on T3's Shardflux provider (its own VM);
+ * otherwise the project VM is opened as T3's SSH environment (with its phone link), and a first message becomes a
+ * thread on the T3 server in that VM. `--on <ref>` uses that existing workspace instead of the project VM.
+ */
+export declare function launchT3(ctx: Ctx, values: Values, path: string, explicitApp: string | undefined): Promise<number>;
+/** The T3 fields of an SSH-mode result (the thread, when one was started in the VM). */
+export declare function t3Fields(ws: Workspace, project: string, install: T3Install | undefined, started: T3ThreadResult | undefined, conversation?: string | null): Record<string, unknown>;
+/**
+ * `agents open t3 <conversation>` for a conversation that runs on T3's Shardflux provider (ACP mode): T3 is brought to
+ * the front with that thread's id. A conversation of another route opens its VM as T3's SSH environment.
+ */
+export declare function openT3Conversation(ctx: Ctx, conversationId: string, values?: Values): Promise<number>;