@shardflux/cli 0.14.5 → 0.15.1

package/dist/agent-commands.js

@@ -1,4 +1,5 @@
 import { prepareSetupCache } from "./setup-cache.js";
+import { launchCodexCloud, openCodexConversation } from "./codex-cloud.js";
 import { agentReachability } from "./agent-reachability.js";
 import { configureCredentialFill, watchCredentialPrompts } from "./credential-prompts.js";
 import { createHash } from 'node:crypto';
@@ -10,7 +11,7 @@ import { prepareProjectTemplate } from "./project-template-setup.js";
 import { projectIdentity, projectLabels } from "./project-identity.js";
 import { ensureProjectGit } from "./project-git.js";
 import { json } from "./format.js";
-import { resolveWorkspace } from "./commands.js";
+import { out, resolveWorkspace } from "./commands.js";
 import { savedMachine } from "./filesystem-state.js";
 import { startAgentConfigTunnels, syncAgentConfig } from "./agent-config-sync.js";
 import { rememberGitAgent } from "./agent-git-commands.js";
@@ -21,7 +22,8 @@ import { progress } from "./progress.js";
 import { rememberLaunch } from "./agent-live.js";
 import { prepareAgentMachine } from "./agent-machine.js";
 import { installedTargets } from "./agent-targets.js";
-import { openDesktopWorkspace, queueT3Prewarm } from "./agent-target-commands.js";
+import { openClaudeDesktopSession, openDesktopWorkspace, queueT3Prewarm } from "./agent-target-commands.js";
+import { submitInitialPrompt, prepareInitialCodexProject } from "./initial-prompt.js";
 import { conversationWorkspace, conversationsUnavailable, getConversation, listConversations, resumeConversation } from "./conversations.js";
 import { conversationTerminal } from "./conversation-terminal.js";
 const active = (session) => session.state === 'running' || session.state === 'starting';
@@ -98,9 +100,16 @@ export async function terminal(ctx, ws, app, agent, project, values, setupHash,
     // Laptop-local MCP servers are reachable while a terminal is attached (L6); --json/--detach start no tunnels.
     const tunnels = attach ? await startAgentConfigTunnels(ctx, ws) : null;
     try {
+        if (app === 'codex' && typeof values.initialPrompt === 'string') {
+            await prepareInitialCodexProject(cell, cwd, `shard-${ws.labels.agent_pty_name || agent}-${app}`);
+        }
         const credentialFill = await configureCredentialFill(ctx, ws);
         // A cold launch is remembered before it starts, so the listing can show it before the projection does (agent-live.ts).
-        const session = await agentPty(cell, app, agent, values.approvals === true, ctx.io.env.TERM || 'xterm-256color', ctx.signal, ws.labels.shard_project || ws.key.split('/')[0], setupHash, cwd, ws.labels.agent_pty_name, () => { rememberLaunch(ctx, ws.id); progress(ctx, `Starting ${app === 'claude' ? 'Claude' : 'Codex'} in ${ws.key}…`); }, true, conversation);
+        const term = ctx.io.env.TERM && ctx.io.env.TERM !== 'dumb' ? ctx.io.env.TERM : 'xterm-256color';
+        const session = await agentPty(cell, app, agent, values.approvals === true, term, ctx.signal, ws.labels.shard_project || ws.key.split('/')[0], setupHash, cwd, ws.labels.agent_pty_name, () => { rememberLaunch(ctx, ws.id); progress(ctx, `Starting ${app === 'claude' ? 'Claude' : 'Codex'} in ${ws.key}…`); }, true, conversation);
+        // A new conversation's guest can start the agent before this command reaches it, so the launch above never ran.
+        // Remember it either way: listing and `agents open` then read the guest until the projection lists the session.
+        rememberLaunch(ctx, ws.id);
         // The real agent is running before any cache provisioning or mount wait.
         const preparation = prepareSetupCache(ctx, ws).catch((error) => {
             ctx.io.stderr.write(`Account setup cache unavailable: ${error instanceof Error ? error.message : String(error)}\n`);
@@ -112,9 +121,12 @@ export async function terminal(ctx, ws, app, agent, project, values, setupHash,
                 throw new Error(`project setup could not be queued: ${queued.stderr.trim() || `exit ${queued.exitCode}`}`);
         });
         store.save(project, app);
+        if (typeof values.initialPrompt === 'string') {
+            await submitInitialPrompt(signal => cellConnector(cell, session.session_id)(0, signal), values.initialPrompt, ws.key, ctx.signal, app, bytes => cell.pty.input(session.session_id, bytes));
+        }
         if (!attach) {
             await preparation;
-            ctx.io.stdout.write(json({ workspace: ws.data, session }));
+            ctx.io.stdout.write(json({ workspace: ws.data, session, ...(typeof values.initialPrompt === 'string' ? { initial_prompt: { submitted: true } } : {}) }));
             return 0;
         }
         ctx.io.stderr.write(`Shardflux · ${ws.key}\nDetach: Ctrl-] then d\n`);
@@ -167,6 +179,8 @@ export const launchProject = async (ctx, values, [path = './', explicitApp]) =>
     if (target && (!['claude-desktop', 'codex-app', 't3'].includes(target) || !detected?.targets.includes(target)))
         throw new UsageError(`${target} is not an installed desktop target`);
     const app = explicitApp ?? store.app(projectKey, like?.labels.app === 'codex' ? 'codex' : 'claude');
+    if (target === 'codex-app' || (app === 'codex' && !like && values.in === undefined))
+        return launchCodexCloud(ctx, values, path);
     const agent = typeof values.name === 'string' ? values.name : 'main';
     if (!/^[a-z0-9][a-z0-9._-]{0,63}$/.test(agent))
         throw new UsageError('agent name must match ^[a-z0-9][a-z0-9._-]{0,63}$');
@@ -236,6 +250,49 @@ export const AGENT_HANDLERS = {
     async 'agents open'(ctx, values, [agent = 'main']) {
         if (values.app !== undefined && values.app !== 'claude' && values.app !== 'codex')
             throw new UsageError('--app must be claude or codex');
+        let resolvedConversation;
+        if (/^conv_[a-z0-9]{26}$/.test(agent)) {
+            resolvedConversation = await getConversation(ctx, agent);
+            if (resolvedConversation.route === 'codex-cloud')
+                return openCodexConversation(ctx, resolvedConversation);
+        }
+        if (values.in === 'auto') {
+            // The menu and other launchers use the same CLI-owned target selection. Never put provider URLs in a client.
+            const ws = await resolveWorkspace(ctx, agent);
+            const project = ws.labels.repo_remote || ws.labels.shard_project || ws.key;
+            const store = new AgentStateStore(ctx.store.dir);
+            const app = values.app ?? ws.labels.shard_app ?? ws.labels.app ?? store.app(project);
+            const detected = installedTargets(ctx.io.env);
+            const saved = store.read().projects?.[project]?.target ??
+                (project.startsWith('file://') ? store.read().projects?.[new URL(project).pathname]?.target : undefined);
+            // Codex's default open implementation owns Cloud/desktop routing. PAS-XB replaces that path; do not pin
+            // the menu to the old per-VM SSH target. An explicit saved desktop target still takes precedence.
+            if ((!saved || !detected.targets.includes(saved)) && app === 'codex') {
+                const next = { ...values };
+                delete next.in;
+                return AGENT_HANDLERS['agents open'](ctx, next, [ws.key]);
+            }
+            if (saved && detected.targets.includes(saved)) {
+                const { HANDLERS } = await import("./handlers.js");
+                const handler = HANDLERS[`agents open ${saved}`];
+                if (!handler)
+                    throw new UsageError('Choose an installed open target with shard agents targets.');
+                return handler(ctx, { ...values, in: saved }, [ws.key]);
+            }
+            // Claude opens where people work (0.15.1+): the conversation in Claude Desktop when it is installed, else Claude
+            // Code in a terminal. The browser (claude.ai) only when it is the chosen target (--in web).
+            if (detected.clients.includes('claude-desktop')) {
+                return openClaudeDesktopSession(ctx, ws);
+            }
+            if (ctx.json) {
+                // An app runs this in the person's terminal (the menu bar opens Terminal with it).
+                out(ctx, `shard agents open ${ws.key}\n`, { target: 'terminal', workspace: ws.data, command: ['shard', 'agents', 'open', ws.key] });
+                return 0;
+            }
+            const next = { ...values };
+            delete next.in;
+            return AGENT_HANDLERS['agents open'](ctx, next, [ws.key]);
+        }
         if (values.in !== undefined && values.in !== 'terminal') {
             const { HANDLERS } = await import("./handlers.js");
             const target = typeof values.in === 'string' ? HANDLERS[`agents open ${values.in}`] : undefined;
@@ -247,7 +304,10 @@ export const AGENT_HANDLERS = {
         let ws;
         let conversation;
         if (/^conv_[a-z0-9]{26}$/.test(agent)) {
-            conversation = await resumeConversation(ctx, await getConversation(ctx, agent));
+            conversation = resolvedConversation ?? await getConversation(ctx, agent);
+            if (conversation.route === 'codex-cloud')
+                return openCodexConversation(ctx, conversation);
+            conversation = await resumeConversation(ctx, conversation);
             ws = await conversationWorkspace(ctx, conversation);
         }
         else {
@@ -278,12 +338,17 @@ export const AGENT_HANDLERS = {
                     throw error;
                 if (matches.length !== 1)
                     throw new UsageError('Use the conversation id.');
+                if (matches[0].route === 'codex-cloud')
+                    return openCodexConversation(ctx, matches[0]);
                 conversation = await resumeConversation(ctx, matches[0]);
                 ws = await conversationWorkspace(ctx, conversation);
             }
             // The menu bar supplies workspace_key from agents list, not the conversation key.
             if (!conversation && ws.labels.shard_conversation) {
-                conversation = await resumeConversation(ctx, await getConversation(ctx, ws.labels.shard_conversation));
+                conversation = await getConversation(ctx, ws.labels.shard_conversation);
+                if (conversation.route === 'codex-cloud')
+                    return openCodexConversation(ctx, conversation);
+                conversation = await resumeConversation(ctx, conversation);
                 ws = await conversationWorkspace(ctx, conversation);
             }
         }

package/dist/agent-git-commands.js

@@ -61,7 +61,8 @@ async function workspace(ctx, git, name, key) {
     if (ws.data.deleted_at)
         throw new UsageError(`workspace ${key} is gone; use shard agents restore ${name} if it was archived`);
     const project = projectIdentity(git.root);
-    if (ws.labels.repo_remote && ws.labels.repo_remote !== project.remote)
+    // A folder without an origin is identified by its path, as conversations label it (agent-repository.ts).
+    if (ws.labels.repo_remote && ws.labels.repo_remote !== (project.remote ?? `file://${project.folder}`))
         throw new UsageError('agent repository does not match this local repository');
     const saved = git.entries()[name];
     if (saved && saved.workspace_id !== ws.id)

package/dist/agent-reachability.js

@@ -8,6 +8,6 @@ export function agentReachability(values) {
         throw new UsageError('--reachable requires a duration');
     const ms = /^0+(?:\.0+)?(?:ms|s|m|h)?$/.test(text.trim()) ? 0 : parseDuration(text, 'reachable');
     if (ms % 1000 !== 0 || ms > 86_400_000)
-        throw new UsageError('--reachable must be whole seconds from 0 to 24h (e.g. 30m; 0 off)');
+        throw new UsageError('--reachable must be whole seconds from 0 to 24h (deprecated; accepted for compatibility)');
     return { agentReachableSeconds: ms / 1000 };
 }

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

@@ -8,6 +8,20 @@ export declare function installDeviceKey(cell: CellClient, key: string, signal?:
 /** Host trust is established over the authenticated files API, before sending any SSH protocol bytes. */
 export declare function prepareSsh(ws: Workspace, ctx: Ctx, targets: AgentTargets, host: string): Promise<CellClient>;
 export declare function proxyStream(io: Io, ended?: () => void, outputGate?: Promise<unknown>): Duplex;
+/**
+ * The Remote Control URL (https://claude.ai/code/session_…) of the workspace's live Claude session. A Claude process
+ * 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 declare function remoteControlUrl(ctx: Ctx, ws: Workspace): Promise<string>;
+/** Claude Desktop's own link to a Remote Control session: claude://code/<session id> opens it in its Code tab. */
+export declare function claudeDesktopLink(remoteControl: string): string;
+export declare 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 declare function openClaudeDesktopSession(ctx: Ctx, ws: Workspace): Promise<number>;
 export declare function openDesktopWorkspace(ctx: Ctx, ws: Workspace, target: DesktopTarget, t3Version?: string, prewarmed?: boolean): Promise<number>;
 export declare function queueT3Prewarm(ctx: Ctx, ws: Workspace, version: string): Promise<void>;
 export declare const TARGET_HANDLERS: Record<string, Handler>;

package/dist/agent-target-commands.js

@@ -1,3 +1,5 @@
+import { setTimeout as delay } from 'node:timers/promises';
+import { guestSessions, LAUNCH_WINDOW_MS } from "./agent-live.js";
 import { agentReachability } from "./agent-reachability.js";
 import { ensureCloudClaude } from "./claude-cloud-login.js";
 import { spawn } from 'node:child_process';
@@ -16,6 +18,8 @@ import { prewarmT3 } from "./t3-runtime.js";
 import { AgentStateStore } from "./agent-state.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. */
+const RECENT_LAUNCH_URL_WAIT_MS = 30_000;
 /** Optimistic file replacement preserves keys installed by other devices connecting at the same time. */
 export async function installDeviceKey(cell, key, signal) {
     const path = '/home/user/.ssh/authorized_keys';
@@ -128,6 +132,78 @@ export function proxyStream(io, ended, outputGate) {
     source.once('error', (error) => stream.destroy(error));
     return stream;
 }
+/**
+ * The Remote Control URL (https://claude.ai/code/session_…) of the workspace's live Claude session. A Claude process
+ * 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) {
+    let cursor;
+    let url;
+    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;
+        cursor = page.nextCursor ?? undefined;
+    } while (!url && cursor && !ctx.signal.aborted);
+    // A new Claude process can accept its first prompt before Remote Control registers.
+    // Only an explicit open of our recent launch probes the guest; history browsing stays passive.
+    const launchedAt = new AgentStateStore(ctx.store.dir).read().agent_launches?.[ws.id];
+    if (!url && typeof launchedAt === 'number' && Date.now() - launchedAt < LAUNCH_WINDOW_MS && ws.ready) {
+        const waitMs = Math.min(ctx.wakeTimeoutMs, RECENT_LAUNCH_URL_WAIT_MS);
+        const deadline = Date.now() + waitMs;
+        const cell = ws.cell({ agentLabel: ctx.agentLabel });
+        while (!url && Date.now() < deadline) {
+            const result = await cell.exec.run(['sf-agent', 'list'], {
+                timeoutMs: Math.min(10_000, Math.max(1, deadline - Date.now())), signal: ctx.signal, maxOutputBytes: 1 << 20,
+            });
+            if (result.exitCode !== 0)
+                break;
+            url = guestSessions(result.stdout).find(a => a.app === 'claude' && a.state !== 'exited' && a.remote_control_url)?.remote_control_url;
+            if (!url && Date.now() < deadline)
+                await delay(Math.min(250, Math.max(1, deadline - Date.now())), undefined, { signal: ctx.signal });
+        }
+        if (!url)
+            throw new Error(`Claude in ${ws.key} did not publish a Remote Control URL within ${Math.ceil(waitMs / 1000)} s; run shard agents open ${ws.key} again`);
+    }
+    if (!url)
+        throw new UsageError(`${ws.key} has no active Remote Control URL; start Claude with Remote Control first`);
+    const parsed = new URL(url);
+    if (parsed.protocol !== 'https:' || parsed.hostname !== 'claude.ai' || !parsed.pathname.startsWith('/code/') || parsed.username || parsed.password)
+        throw new Error('agent returned an invalid Claude Remote Control URL');
+    return url;
+}
+/** Claude Desktop's own link to a Remote Control session: claude://code/<session id> opens it in its Code tab. */
+export function claudeDesktopLink(remoteControl) {
+    const id = new URL(remoteControl).pathname.split('/')[2] ?? '';
+    if (!/^(cse|session)_[A-Za-z0-9_-]+$/.test(id))
+        throw new Error('agent returned an invalid Claude Remote Control URL');
+    return `claude://code/${id}`;
+}
+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) {
+    await ensureCloudClaude(ctx, ws);
+    const session = await remoteControlUrl(ctx, ws);
+    const url = claudeDesktopLink(session);
+    if (!ctx.json)
+        await openLink(url, ctx.io.env);
+    out(ctx, `${url}\n`, { target: 'claude-desktop', workspace: ws.data, url, remote_control_url: session, app_bundle_id: CLAUDE_DESKTOP_BUNDLE });
+    return 0;
+}
+async function openLink(url, env) {
+    const child = spawn('open', [url], { env, stdio: 'ignore' });
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error('Claude Desktop did not open in time')); }, 10_000);
+        child.once('error', e => { clearTimeout(timer); reject(e); });
+        child.once('exit', code => { clearTimeout(timer); if (code === 0)
+            resolve();
+        else
+            reject(new Error(`could not open ${url}`)); });
+    });
+}
 const openTarget = (target) => async (ctx, values, [ref = 'main']) => {
     const detected = installedTargets(ctx.io.env);
     if (target !== 'web' && !detected.targets.includes(target))
@@ -138,18 +214,7 @@ const openTarget = (target) => async (ctx, values, [ref = 'main']) => {
     if (target !== 'codex-app')
         await ensureCloudClaude(ctx, ws);
     if (target === 'web') {
-        let cursor;
-        let url;
-        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;
-            cursor = page.nextCursor ?? undefined;
-        } while (!url && cursor && !ctx.signal.aborted);
-        if (!url)
-            throw new UsageError(`${ws.key} has no active Remote Control URL; start Claude with Remote Control first`);
-        const parsed = new URL(url);
-        if (parsed.protocol !== 'https:' || parsed.hostname !== 'claude.ai' || !parsed.pathname.startsWith('/code/') || parsed.username || parsed.password)
-            throw new Error('agent returned an invalid Claude Remote Control URL');
+        const url = await remoteControlUrl(ctx, ws);
         if (!ctx.json && !openUrl(url, ctx.io.env))
             throw new Error(`could not open ${url}`);
         out(ctx, `${url}\n`, { target, workspace: ws.data, url });
@@ -173,7 +238,8 @@ export async function openDesktopWorkspace(ctx, ws, target, t3Version, prewarmed
     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 });
+    out(ctx, `${instructions}\n`, { target, workspace: ws.data, host: entry.host, instructions,
+        app_bundle_id: { 'claude-desktop': 'com.anthropic.claudefordesktop', 'codex-app': 'com.openai.codex', t3: 'com.t3tools.t3code' }[target] });
     return 0;
 }
 export async function queueT3Prewarm(ctx, ws, version) {

package/dist/agent-targets.d.ts

@@ -10,6 +10,13 @@ export interface TargetEntry {
 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;
+/** The installed T3 Code apps (any channel), with their path and version, in the given app folders. */
+export declare function t3Apps(dirs: string[], platform?: NodeJS.Platform): Array<{
+    path: string;
+    version: string | null;
+}>;
+/** The app folders scanned for desktop apps: SHARDFLUX_APPLICATIONS_DIRS, else /Applications and ~/Applications. */
+export declare function applicationDirs(env: Record<string, string | undefined>): string[];
 export declare function installedTargets(env: Record<string, string | undefined>, platform?: NodeJS.Platform, appDirs?: string[]): {
     targets: string[];
     clients: string[];

package/dist/agent-targets.js

@@ -33,10 +33,47 @@ export function managedBlock(text, body) {
     const stop = end + END.length + (text[end + END.length] === '\n' ? 1 : 0);
     return text.slice(0, start) + block + text.slice(stop);
 }
-export function installedTargets(env, platform = process.platform, appDirs) {
+/** The installed T3 Code apps (any channel), with their path and version, in the given app folders. */
+export function t3Apps(dirs, platform = process.platform) {
+    const found = [];
+    if (platform !== 'darwin')
+        return found;
+    for (const dir of dirs) {
+        let names;
+        try {
+            names = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names.filter(name => name.endsWith('.app'))) {
+            const info = join(dir, name, 'Contents', 'Info.plist');
+            // XML and binary plists store this ASCII bundle id verbatim. Avoid a
+            // subprocess for every unrelated app on the normal no-T3 path.
+            try {
+                if (!readFileSync(info).includes('com.t3tools.t3code'))
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            const result = spawnSync('/usr/libexec/PlistBuddy', ['-c', 'Print :CFBundleIdentifier', '-c', 'Print :CFBundleShortVersionString', info], { input: '', encoding: 'utf8', timeout: 1000 });
+            const [bundle, version] = result.stdout?.trim().split('\n') ?? [];
+            if (bundle !== 'com.t3tools.t3code')
+                continue;
+            found.push({ path: join(dir, name), version: result.status === 0 && version && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version) ? version : null });
+        }
+    }
+    return found;
+}
+/** The app folders scanned for desktop apps: SHARDFLUX_APPLICATIONS_DIRS, else /Applications and ~/Applications. */
+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 ?? (env.SHARDFLUX_APPLICATIONS_DIRS !== undefined ? env.SHARDFLUX_APPLICATIONS_DIRS.split(':').filter(Boolean) : ['/Applications', join(home, 'Applications')]);
+    const dirs = appDirs ?? applicationDirs(env);
     const hasApp = (name, bundle) => platform === 'darwin' && dirs.map(dir => join(dir, name)).some(path => {
         const info = join(path, 'Contents', 'Info.plist');
         if (!existsSync(info))
@@ -45,36 +82,11 @@ export function installedTargets(env, platform = process.platform, appDirs) {
         return result.status === 0 && result.stdout.trim() === bundle;
     });
     const versions = {};
-    let t3 = false;
-    if (platform === 'darwin')
-        for (const dir of dirs) {
-            let names;
-            try {
-                names = readdirSync(dir);
-            }
-            catch {
-                continue;
-            }
-            for (const name of names.filter(name => name.endsWith('.app'))) {
-                const info = join(dir, name, 'Contents', 'Info.plist');
-                // XML and binary plists store this ASCII bundle id verbatim. Avoid a
-                // subprocess for every unrelated app on the normal no-T3 path.
-                try {
-                    if (!readFileSync(info).includes('com.t3tools.t3code'))
-                        continue;
-                }
-                catch {
-                    continue;
-                }
-                const result = spawnSync('/usr/libexec/PlistBuddy', ['-c', 'Print :CFBundleIdentifier', '-c', 'Print :CFBundleShortVersionString', info], { input: '', encoding: 'utf8', timeout: 1000 });
-                const [bundle, version] = result.stdout?.trim().split('\n') ?? [];
-                if (bundle !== 'com.t3tools.t3code')
-                    continue;
-                t3 = true;
-                if (result.status === 0 && version && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version))
-                    versions.t3 ??= version;
-            }
-        }
+    const t3Bundles = t3Apps(dirs, platform);
+    const t3 = t3Bundles.length > 0;
+    for (const app of t3Bundles)
+        if (app.version)
+            versions.t3 ??= app.version;
     const executable = (name) => (env.PATH ?? '').split(':').filter(Boolean).some(p => { try {
         accessSync(join(p, name), constants.X_OK);
         return true;

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.14.5";
+export declare const CLI_VERSION = "0.15.1";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;
@@ -6,6 +6,8 @@ export interface OptionSpec {
     /** Placeholder shown in help, e.g. `<slug>`. */
     value?: string;
     description: string;
+    /** Accept the option for compatibility but omit it from help. */
+    hidden?: boolean;
 }
 export interface PositionalSpec {
     name: string;

package/dist/args.js

@@ -12,7 +12,7 @@
 import { parseArgs } from 'node:util';
 import { ACCOUNT_COMMANDS } from "./account-args.js";
 import { UsageError } from "./errors.js";
-export const CLI_VERSION = '0.14.5';
+export const CLI_VERSION = '0.15.1';
 export const GLOBAL_OPTIONS = {
     'api-url': { type: 'string', value: '<url>', description: 'API base URL (default $SHARDFLUX_API_URL, else https://api.shardflux.dev).' },
     json: { type: 'boolean', description: 'Print machine-readable JSON on stdout (errors as JSON on stderr).' },
@@ -268,7 +268,7 @@ const KEY_COMMANDS = [
             'delete-after-idle': { type: 'string', value: '<days>d', description: 'Delete this persistent workspace after 1..3650 idle days (e.g. 14d).' },
             like: { type: 'string', value: '<id|key>', description: 'Open a fresh workspace with the source’s template and configuration.' },
             volume: { type: 'string', multiple: true, value: '<name:/path[:ro]>', description: 'Replace the named volume mounts; repeat for each mount.' },
-            reachable: { type: 'string', value: '<duration>', description: 'Keep waiting agents reachable (default 30m; 0 off; maximum 24h).' },
+            reachable: { type: 'string', value: '<duration>', hidden: true, description: 'Deprecated; ignored. Claude conversations stay reachable without a time limit.' },
             'agent-idle-grace-seconds': { type: 'string', value: '<0-3600>', description: 'Grace after a coding agent waits or exits (default 300 seconds).' },
             'idle-policy': { type: 'string', value: '<policy>', description: 'adaptive, never or fixed:<seconds>.' },
             secret: {
@@ -876,9 +876,10 @@ const KEY_COMMANDS = [
     { path: ['credentials', 'list'], summary: 'Show pending login requests', positionals: [], options: {} },
     { path: ['credentials', 'enable'], summary: 'Enable credential fill in a workspace', positionals: [REF], options: {} },
     { path: ['credentials', 'deny'], summary: 'Deny a login request', positionals: [{ name: 'request-id', required: true }], options: {} },
-    { path: ['credentials', 'forget'], summary: 'Remove a remembered site credential', positionals: [REF, { name: 'site', required: true }], options: {} },
+    { path: ['credentials', 'forget'], summary: 'Remove a remembered site credential', positionals: [REF, { name: 'site', required: true }], options: { scope: { type: 'string', value: '<conversation|project|machine>', description: 'Remembered sign-in scope (default project).' } } },
     { path: ['credentials', 'approve'], summary: 'Approve a login directly from your vault', positionals: [{ name: 'request-id', required: true }], options: {
             from: { type: 'string', description: 'hsec, 1password, bitwarden or keychain.' }, item: { type: 'string', description: 'Vault login item name.' },
+            scope: { type: 'string', value: '<ask|project|machine>', description: 'Future-request scope; unattended sign-in uses the same scope.' },
             always: { type: 'boolean', description: 'Always allow these fields for this project on this laptop.' }, remember: { type: 'boolean', description: 'Remember for unattended use, encrypted with AWS KMS.' },
         } },
     {
@@ -1166,8 +1167,12 @@ const AGENT_CREDENTIAL_COMMANDS = [
     ...['sync', 'status', 'forget'].map((action) => ({ path: ['agents', 'credentials', action], summary: `${action} Codex copies and the account's cloud Claude login (contents never printed)`, positionals: [], options: {} })),
     { path: ['agents', 'credentials', 'login'], summary: 'Sign in once to cloud Claude for this account', positionals: [{ name: 'app', required: true }], options: { workspace: { type: 'string', value: '<id|key>', description: 'Use this workspace for the cloud sign-in.' } } },
 ];
+const COMPUTER_OPTION = { type: 'boolean', description: 'Give the new conversation a desktop with a browser its agent drives (computer use).' };
 const AGENT_OPTIONS = {
-    reachable: { type: 'string', value: '<duration>', description: 'Keep waiting agents reachable (default 30m; 0 off; maximum 24h).' },
+    prompt: { type: 'string', value: '<text>', description: 'First user message for a new conversation.' },
+    'prompt-file': { type: 'string', value: '<file|->', description: 'Read the first user message from a UTF-8 file or stdin (-), up to 256 KiB.' },
+    image: { type: 'string', multiple: true, value: '<file|->', description: 'Attach a PNG, JPEG, GIF or WebP image to the first message (repeatable, up to 5 of 10 MiB each; - reads PNG images back to back from stdin) (0.15.0+).' },
+    reachable: { type: 'string', value: '<duration>', hidden: true, description: 'Deprecated; ignored. Claude conversations stay reachable without a time limit.' },
     approvals: { type: 'boolean', description: 'Keep the agent’s permission prompts.' },
 };
 export const PROJECT_COMMAND = {
@@ -1175,6 +1180,7 @@ export const PROJECT_COMMAND = {
     description: 'Opens Claude Code or Codex directly. --resume continues a project conversation. With --json it starts detached and prints the session. Detach with Ctrl-] then d.',
     positionals: [{ name: 'path', required: true }, { name: 'claude|codex' }], options: {
         ...AGENT_OPTIONS,
+        computer: COMPUTER_OPTION,
         new: { type: 'boolean', description: 'Start a new conversation.' },
         resume: { type: 'boolean', description: 'Continue a conversation from this project.' },
         claude: { type: 'boolean', description: 'Same as the claude argument (0.14.4+).' },
@@ -1200,9 +1206,11 @@ const AGENT_COMMANDS = [
             ...(action === 'keep' ? { push: { type: 'boolean', description: 'Push the kept branch to origin and open a PR when gh is installed.' } } : {}),
         },
     })),
-    { path: ['agents', 'open'], summary: 'Attach an agent in the terminal', description: 'Detach with Ctrl-] then d; /exit ends the agent session.', positionals: [{ name: 'agent', required: true }], options: { ...AGENT_OPTIONS, app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice).' }, in: { type: 'string', value: '<terminal|claude-desktop|codex-app|web|t3>', description: 'Where to open the session (default terminal).' } } },
-    { path: ['agents', 'new'], summary: 'Start a session or a named agent', positionals: [{ name: 'agent' }], options: {
+    ...['status', 'enable', 'disable'].map(action => ({ path: ['agents', 'codex', action], summary: `${action} the account's billed Codex Cloud connector`, positionals: [], options: {} })),
+    { path: ['agents', 'open'], summary: 'Open a conversation (Codex Cloud or the native Claude session)', description: 'Codex opens its existing Cloud thread without waking its VM. Claude attaches its native session.', positionals: [{ name: 'agent', required: true }], options: { ...AGENT_OPTIONS, app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice).' }, in: { type: 'string', value: '<terminal|auto|claude-desktop|codex-app|web|t3>', description: 'Where to open it. auto (0.15.1+): the saved target, else a Claude conversation in Claude Desktop when it is installed, else in this terminal; web opens claude.ai.' } } },
+    { path: ['agents', 'new'], summary: 'Start a conversation in a fresh VM; Codex opens a genuine Cloud thread', positionals: [{ name: 'agent' }], options: {
             ...AGENT_OPTIONS,
+            computer: COMPUTER_OPTION,
             app: { type: 'string', value: '<claude|codex>', description: 'Agent app (default remembered choice).' },
             path: { type: 'string', value: '<path>', description: 'Local project path for first launch.' },
             name: { type: 'string', value: '<name>', description: 'New agent name; copies the project main workspace with --like.' },
@@ -1396,6 +1404,9 @@ function toParseArgsOptions(opts) {
  * returns help text for --help, bare groups and non-TTY bare `shard`.
  */
 export function parseCommandLine(argv, options = {}) {
+    // `acp --login` is the ACP terminal sign-in an editor runs (ACP appends the method's args to `shard acp`).
+    if (argv.length === 2 && argv[0] === 'acp' && argv[1] === '--login')
+        return { kind: 'run', command: { path: ['acp'], summary: '', positionals: [], options: {} }, values: { login: true }, positionals: [], global: { apiUrl: undefined, json: false, agentLabel: undefined, wake: undefined, wakeTimeout: undefined } };
     if (argv.length === 1 && (argv[0] === 'acp' || argv[0] === 'device-helper'))
         return { kind: 'run', command: { path: [argv[0]], summary: '', positionals: [], options: {} }, values: {}, positionals: [], global: { apiUrl: undefined, json: false, agentLabel: undefined, wake: undefined, wakeTimeout: undefined } };
     const terminator = argv.indexOf('--');
@@ -1559,7 +1570,7 @@ function emailedTokensAsPositionals(rest, command) {
 }
 // ---- help ----------------------------------------------------------------------------------
 function optionLines(opts) {
-    const rows = Object.entries(opts).map(([name, o]) => [`${o.short ? `-${o.short}, ` : '    '}--${name}${o.value ? ` ${o.value}` : ''}`, o.description]);
+    const rows = Object.entries(opts).filter(([, o]) => !o.hidden).map(([name, o]) => [`${o.short ? `-${o.short}, ` : '    '}--${name}${o.value ? ` ${o.value}` : ''}`, o.description]);
     const w = Math.max(0, ...rows.map((r) => r[0].length));
     return rows.map(([l, d]) => `  ${l.padEnd(w)}  ${d}`);
 }
@@ -1574,8 +1585,9 @@ export function commandHelp(c) {
     const lines = [`Usage: ${usageLine(c)}`, '', c.summary + '.'];
     if (c.description)
         lines.push('', c.description);
-    if (Object.keys(c.options).length > 0)
-        lines.push('', 'Options:', ...optionLines(c.options));
+    const options = optionLines(c.options);
+    if (options.length > 0)
+        lines.push('', 'Options:', ...options);
     lines.push('', 'Global options:', ...optionLines(GLOBAL_OPTIONS));
     if (c.examples?.length)
         lines.push('', 'Examples:', ...c.examples.map((e) => `  ${e}`));

package/dist/browser-login.d.ts

@@ -0,0 +1,35 @@
+import type { AccountClientOptions, AuthUser } from '@shardflux/sdk';
+export interface DeviceAuthorization {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete: string;
+    expires_in: number;
+    interval: number;
+}
+export interface DeviceSession {
+    status: 'authenticated';
+    user: AuthUser;
+    session_token: string;
+    session_expires_at: string;
+}
+export interface DevicePollOptions {
+    signal: AbortSignal;
+    /** Waits `ms` (ends early when the signal aborts). */
+    sleep(ms: number): Promise<void>;
+    now?: () => number;
+    /** A token poll that has not answered after this long is a connection timeout (default 15 s). */
+    requestTimeoutMs?: number;
+}
+/** The default name on the approval page: "shard CLI on <hostname>". */
+export declare function defaultClientName(hostname: string): string;
+/** POST /v1/auth/device. */
+export declare function startDeviceAuthorization(opts: AccountClientOptions, clientName: string, signal: AbortSignal): Promise<DeviceAuthorization>;
+/**
+ * Polls POST /v1/auth/device/token until the session is issued (RFC 8628 §3.4, §3.5): waits `interval` seconds before
+ * each poll; a slow_down adds 5 s (or takes the server's longer interval); a connection failure or timeout doubles the
+ * interval (exponential backoff); 429 waits its Retry-After and 5xx the interval, while the request can still be
+ * approved. Stops on access_denied, expired_token and every other refusal (thrown as the API's error), and when the
+ * request's lifetime has passed.
+ */
+export declare function waitForDeviceSession(opts: AccountClientOptions, d: DeviceAuthorization, poll: DevicePollOptions): Promise<DeviceSession>;