@shardflux/cli 0.14.4 → 0.15.0

package/dist/acp-login.d.ts

@@ -0,0 +1,20 @@
+import type { Ctx } from './commands.js';
+/**
+ * The ACP terminal sign-in method. An editor (T3 Code) runs `shard acp --login` in its own terminal when the user
+ * chooses it, then reconnects; ACP appends these args to the configured `shard acp` invocation.
+ */
+export declare const ACP_LOGIN_METHOD: {
+    readonly id: "shardflux-login";
+    readonly name: "Sign in to Shardflux";
+    readonly description: "Create or sign in to your Shardflux account and connect Claude Code and Codex.";
+    readonly type: "terminal";
+    readonly args: readonly ["--login"];
+};
+/** Whether an API key is configured (no request; a revoked key surfaces as auth_required on its first call). */
+export declare function acpSignedIn(ctx: Ctx): boolean;
+/**
+ * `shard acp --login`: everything a first conversation needs, each step skipped when it is already done: the
+ * account (signed up or in with this Mac's Codex login, else an email), its API key, the Codex login copy and the
+ * cloud Claude sign-in.
+ */
+export declare function runAcpLogin(ctx: Ctx): Promise<number>;

package/dist/acp-login.js

@@ -0,0 +1,122 @@
+import { existsSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { describeError } from "./errors.js";
+import { cloudClaudeLogin, loginClaudeInWorkspace } from "./claude-cloud-login.js";
+import { syncAgentCredentials } from "./agent-credentials.js";
+/**
+ * The ACP terminal sign-in method. An editor (T3 Code) runs `shard acp --login` in its own terminal when the user
+ * chooses it, then reconnects; ACP appends these args to the configured `shard acp` invocation.
+ */
+export const ACP_LOGIN_METHOD = {
+    id: 'shardflux-login',
+    name: 'Sign in to Shardflux',
+    description: 'Create or sign in to your Shardflux account and connect Claude Code and Codex.',
+    type: 'terminal',
+    args: ['--login'],
+};
+/** Whether an API key is configured (no request; a revoked key surfaces as auth_required on its first call). */
+export function acpSignedIn(ctx) {
+    try {
+        ctx.cloud();
+        return true;
+    }
+    catch (error) {
+        // Only a missing or malformed key means signed out; anything else surfaces on the call that needs the API.
+        return describeError(error).code !== 'unauthenticated';
+    }
+}
+/** The sign-in flow checks the key against the API, so a revoked one is replaced. */
+async function accountReady(ctx) {
+    if (!acpSignedIn(ctx))
+        return false;
+    try {
+        await ctx.cloud().agentCredentials.list();
+        return true;
+    }
+    catch (error) {
+        if (describeError(error).code === 'unauthenticated')
+            return false;
+        throw error;
+    }
+}
+const say = (ctx, text) => { ctx.io.stderr.write(text); };
+/**
+ * `shard acp --login`: everything a first conversation needs, each step skipped when it is already done: the
+ * account (signed up or in with this Mac's Codex login, else an email), its API key, the Codex login copy and the
+ * cloud Claude sign-in.
+ */
+export async function runAcpLogin(ctx) {
+    const { HANDLERS } = await import("./handlers.js");
+    const home = ctx.io.env.HOME ?? homedir();
+    const codex = existsSync(join(home, '.codex', 'auth.json'));
+    // The account commands' own reports (paths, next steps) are for the shard terminal, not an editor's sign-in panel.
+    const quiet = { ...ctx, io: { ...ctx.io, stdout: { write: () => true } } };
+    // An editor's conversations need no Codex Cloud executor; setup here makes the account, project and key only.
+    const setup = () => HANDLERS.setup(quiet, { codex: false }, []);
+    say(ctx, 'Shardflux sign-in\n\n');
+    if (!await accountReady(ctx)) {
+        const session = ctx.store.profile(ctx.apiUrl).session;
+        if (session?.state === 'active') {
+            say(ctx, 'Creating your API key…\n');
+            await setup();
+        }
+        else if (codex) {
+            say(ctx, 'Signing in with the Codex login on this Mac…\n');
+            await HANDLERS.signup(quiet, { setup: false }, []);
+            await setup();
+        }
+        else {
+            const email = (await ctx.input.answer('Email: '))?.trim();
+            if (!email) {
+                say(ctx, 'An email address is needed to create your account.\n');
+                return 1;
+            }
+            try {
+                await HANDLERS.signup(quiet, { email, codex: false, setup: false }, []);
+            }
+            catch (error) {
+                // An existing account signs in with its password instead.
+                if (describeError(error).code !== 'conflict')
+                    throw error;
+                await HANDLERS['auth login'](quiet, { email }, []);
+            }
+            await setup();
+        }
+        if (!await accountReady(ctx)) {
+            say(ctx, '\nThe account is not ready yet. Finish the step above, then choose Sign in again.\n');
+            return 1;
+        }
+        const user = ctx.store.profile(ctx.apiUrl).session?.user;
+        say(ctx, user?.email ? `Signed in as ${user.email}.\n` : 'Signed in.\n');
+    }
+    else
+        say(ctx, 'Already signed in.\n');
+    if (codex) {
+        await syncAgentCredentials(ctx.cloud(), { home, redact: (value) => ctx.addSecret(value) });
+        say(ctx, 'Codex: connected with the login on this Mac.\n');
+    }
+    if (await cloudClaudeLogin(ctx))
+        say(ctx, 'Claude Code: connected.\n');
+    else {
+        const answer = (await ctx.input.answer('\nConnect Claude Code now? It opens a Claude sign-in page. [Y/n] '))?.trim().toLowerCase() ?? 'n';
+        if (answer === '' || answer.startsWith('y')) {
+            // A session workspace exists only for this sign-in and is deleted with it.
+            const ws = await ctx.cloud().workspaces.open({ key: `shardflux-sign-in/${randomBytes(4).toString('hex')}`, template: 'coding', lifetime: 'session',
+                wait: { signal: ctx.signal, timeoutMs: ctx.wakeTimeoutMs } });
+            try {
+                await loginClaudeInWorkspace(ctx, ws);
+            }
+            finally {
+                await ws.close().catch(() => { });
+            }
+            say(ctx, 'Claude Code: connected.\n');
+        }
+        else if (!codex) {
+            say(ctx, 'Claude Code: not connected. Choose Sign in again to connect it.\n');
+        }
+    }
+    say(ctx, '\nShardflux is ready. Return to your editor and start a conversation.\n');
+    return 0;
+}

package/dist/acp.js

@@ -12,6 +12,7 @@ import { describeError, ownHint } from "./errors.js";
 import { serveAcpDeviceApprovals } from "./device-bridge.js";
 import { syncAgentCredentials } from "./agent-credentials.js";
 import { cloudClaudeLogin } from "./claude-cloud-login.js";
+import { ACP_LOGIN_METHOD, acpSignedIn } from "./acp-login.js";
 import { ensureMenubar, MenubarManager } from "./menubar.js";
 const PREFIX = 'shardflux:';
 export function acpModel(app, id) { return `${PREFIX}${app}:${id}`; }
@@ -23,21 +24,30 @@ export function parseAcpModel(value) {
         throw new RpcError(-32602, 'Choose a model from Shardflux.');
     return { app: match[1], id: match[2] };
 }
+/** An editor's first choice comes from the probe (`<app>:default`); every conversation keeps it valid as the app's own default model. */
+const DEFAULT_MODEL = 'default';
+const hasNativeDefault = (native) => nativeModelOptions(native).some(o => o.value === DEFAULT_MODEL);
 export function acpModelOptions(catalog) {
     return ['claude', 'codex'].flatMap(app => {
-        return nativeModelOptions(catalog[app] ?? {}).map((option) => {
+        const native = nativeModelOptions(catalog[app] ?? {});
+        if (!native.length)
+            return [];
+        const options = hasNativeDefault(catalog[app] ?? {}) ? native : [{ value: DEFAULT_MODEL, name: 'Default' }, ...native];
+        return options.map((option) => {
             return { ...option, value: acpModel(app, option.value), name: `${app === 'claude' ? 'Claude Code' : 'Codex'} · ${option.name}` };
         });
     });
 }
+const SIGN_IN = 'Sign in to Shardflux from your editor (or run shard acp --login).';
 export function acpError(error) {
     if (error instanceof RpcError) {
         if (error.code === -32000 && /authentication required|oauth.*(?:revoked|expired)|not (?:signed|logged) in/i.test(error.message))
-            return new RpcError(-32000, `${error.message} Run shard setup.`, { code: 'unauthenticated', fix: 'Run shard setup.' });
+            return new RpcError(-32000, `${error.message.replace(/[.!]?$/, '.')} ${SIGN_IN}`, { code: 'unauthenticated', fix: SIGN_IN });
         return error;
     }
     const info = describeError(error);
-    const fix = info.code === 'unauthenticated' ? 'Run shard setup.' : info.code === 'not_found' || info.details?.reason === 'workspace_deleted' ? 'Open a new conversation.' : ownHint(error) ?? (info.code === 'quota_exceeded' || info.code === 'allowance_exhausted' ? 'Run shard billing plans.' : 'Try the message again.');
+    // ACP `auth_required` (-32000) with an unauthenticated code makes the editor offer the advertised sign-in method.
+    const fix = info.code === 'unauthenticated' ? SIGN_IN : info.code === 'not_found' || info.details?.reason === 'workspace_deleted' ? 'Open a new conversation.' : ownHint(error) ?? (info.code === 'quota_exceeded' || info.code === 'allowance_exhausted' ? 'Run shard billing plans.' : 'Try the message again.');
     return new RpcError(-32000, `${info.message} ${fix}`, { code: info.code, fix, ...(info.details?.reason ? { reason: info.details.reason } : {}) });
 }
 /** Rewrite structural session/file references, never the agent's prose or command output. */
@@ -94,8 +104,9 @@ export class ShardfluxAcp {
             if (params.protocolVersion !== 1 && params.protocolVersion !== 2)
                 throw new RpcError(-32602, 'Unsupported protocol version');
             this.#initialized = true;
-            this.#probe = objectValue(params.clientInfo).name === 't3-code-provider-test';
-            return { protocolVersion: 1, agentInfo: { name: 'shardflux', title: 'Shardflux', version: CLI_VERSION }, authMethods: [],
+            // T3 Code's model probe and its post-sign-in check open a session to test the provider; neither gets a VM.
+            this.#probe = ['t3-code-provider-test', 't3-code-provider-auth'].includes(String(objectValue(params.clientInfo).name));
+            return { protocolVersion: 1, agentInfo: { name: 'shardflux', title: 'Shardflux', version: CLI_VERSION }, authMethods: [ACP_LOGIN_METHOD],
                 agentCapabilities: { loadSession: true, promptCapabilities: { image: true, embeddedContext: true }, sessionCapabilities: { list: {}, resume: {}, close: {} } } };
         }
         if (!this.#initialized)
@@ -105,6 +116,9 @@ export class ShardfluxAcp {
             return { sessions: sessions.map(r => ({ sessionId: r.id, cwd: r.folder, updatedAt: r.updatedAt })) };
         }
         if (method === 'session/new') {
+            // Signed out, the editor gets ACP auth_required and offers the sign-in method, even on its model probe.
+            if (!acpSignedIn(this.#ctx))
+                throw new RpcError(-32000, 'Authentication required', { code: 'unauthenticated', fix: SIGN_IN });
             if (this.#probe)
                 return this.#configuration(acpModel('claude', 'default'), { sessionId: 'shardflux-probe' }, ACP_PROBE_CATALOG);
             if (typeof params.cwd !== 'string' || !isAbsolute(params.cwd))
@@ -163,12 +177,17 @@ export class ShardfluxAcp {
             if (!acpModelOptions(record.catalog ?? {}).some(o => o.value === model))
                 throw new RpcError(-32602, 'This model is no longer available. Choose a model from this conversation.');
             let result;
-            try {
-                result = objectValue(await session.transport.rpc.request('session/set_config_option', { sessionId: record.nativeId, configId: 'model', value: selected.id }));
-            }
-            catch (e) {
-                await this.#rejectModel(session, selected.id, e);
-                throw e;
+            // Our own default keeps the app's current model; there is nothing to tell the native session.
+            if (selected.id === DEFAULT_MODEL && !hasNativeDefault(record.catalog?.[selected.app] ?? {}))
+                result = objectValue(record.setup);
+            else {
+                try {
+                    result = objectValue(await session.transport.rpc.request('session/set_config_option', { sessionId: record.nativeId, configId: 'model', value: selected.id }));
+                }
+                catch (e) {
+                    await this.#rejectModel(session, selected.id, e);
+                    throw e;
+                }
             }
             record.model = model;
             this.#save(record);
@@ -327,7 +346,7 @@ export class ShardfluxAcp {
         await session.transport?.close();
         await syncAgentCredentials(ctx.cloud(), { home: ctx.io.env.HOME, redact: value => ctx.addSecret(value) });
         if (app === 'claude' && !(await cloudClaudeLogin(ctx)))
-            throw new RpcError(-32000, 'Sign in to Claude Code with shard agents credentials login claude.', { code: 'unauthenticated', fix: 'Run shard agents credentials login claude.' });
+            throw new RpcError(-32000, 'Authentication required: connect Claude Code.', { code: 'unauthenticated', fix: SIGN_IN });
         if (!record.conversationId) {
             this.#prepare(session);
             await session.prepared;
@@ -366,8 +385,12 @@ export class ShardfluxAcp {
             throw new Error('ACP supervisor identity does not match this conversation.');
         const owner = `${session.ws.id}:${status.pid}:${status.start}`;
         const initialize = !record.nativeId || record.owner !== owner;
-        if (record.workspaceId !== session.ws.id)
+        // A cold restore can replace the journal owner without changing the VM id.
+        // Its sequence starts at zero; an old cursor would drop initialize/load replies.
+        if (record.workspaceId !== session.ws.id || record.owner !== owner) {
             record.from_seq = 0;
+            delete record.prompt_id;
+        }
         record.workspaceId = session.ws.id;
         const transport = new AcpJournal(cell, c.id, app, c.worktree_path, record, () => this.#save(record), ctx.signal);
         transport.rpc.handler = async (method, params, request) => {

package/dist/agent-commands.js

@@ -1,11 +1,12 @@
 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';
 import { ShardfluxApiError } from '@shardflux/sdk';
 import { UsageError } from "./errors.js";
 import { AgentStateStore } from "./agent-state.js";
-import { attachTerminal, cellConnector } from "./agent-terminal.js";
+import { attachTerminal, cellConnector, workspaceAsleep } from "./agent-terminal.js";
 import { prepareProjectTemplate } from "./project-template-setup.js";
 import { projectIdentity, projectLabels } from "./project-identity.js";
 import { ensureProjectGit } from "./project-git.js";
@@ -22,6 +23,7 @@ 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 { 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,16 +121,20 @@ 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`);
         const attached = attachTerminal({
             ...(credentialFill ? { credentialPrompts: (ask, signal) => watchCredentialPrompts(ctx, ws, ask, signal) } : {}),
-            io: ctx.io, signal: ctx.signal, connect: cellConnector(cell, session.session_id),
+            io: ctx.io, signal: ctx.signal, connect: cellConnector(cell, session.session_id, { passive: true }),
             wake: (signal) => ws.wake({ timeoutMs: ctx.wakeTimeoutMs, signal }),
+            asleep: () => workspaceAsleep(ws),
             invalidate: () => cell.tokens.invalidate(),
             sleep: (ms, signal) => new Promise((resolve) => {
                 const done = () => { clearTimeout(timer); signal.removeEventListener('abort', done); resolve(); };
@@ -166,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}$');
@@ -235,6 +250,35 @@ 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]);
+            }
+            const target = saved && detected.targets.includes(saved) ? saved : 'web';
+            const { HANDLERS } = await import("./handlers.js");
+            const handler = HANDLERS[`agents open ${target}`];
+            if (!handler)
+                throw new UsageError('Choose an installed open target with shard agents targets.');
+            return handler(ctx, { ...values, in: target }, [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;
@@ -246,7 +290,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 {
@@ -277,12 +324,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.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';
@@ -145,6 +149,26 @@ const openTarget = (target) => async (ctx, values, [ref = 'main']) => {
             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);
@@ -173,7 +197,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/agent-terminal.d.ts

@@ -1,4 +1,3 @@
-import { PtyConnection } from '@shardflux/sdk';
 import type { CellClient, PtyServerMessage } from '@shardflux/sdk';
 import type { Io } from './commands.js';
 export interface TerminalConnection {
@@ -7,6 +6,8 @@ export interface TerminalConnection {
     messages(): AsyncIterable<PtyServerMessage>;
     close(): Promise<void>;
 }
+/** The workspace (or the VM under this terminal) is asleep: the user's next keystroke wakes it. */
+export declare function sleepingAttach(error: unknown): boolean;
 export declare function retryableAttach(error: unknown): boolean;
 /** Offsets address bytes, including escape sequences and UTF-8 split across frames. */
 export declare class PtyOutputCursor {
@@ -19,6 +20,12 @@ export interface AttachOptions {
     signal: AbortSignal;
     connect(offset: number, signal: AbortSignal): Promise<TerminalConnection>;
     wake(signal: AbortSignal): Promise<unknown>;
+    /**
+     * Whether the workspace went to sleep under this terminal (suspended or suspending), read without waking it. With
+     * it, a dropped terminal never wakes the workspace by itself: asleep, it waits until its user types; otherwise it
+     * reattaches, and the host wakes a parked VM for it. Without it, every reattach wakes the workspace first.
+     */
+    asleep?(signal: AbortSignal): Promise<boolean>;
     invalidate(): void;
     sleep(ms: number, signal: AbortSignal): Promise<void>;
     dimensions?: () => {
@@ -32,4 +39,19 @@ export interface AttachOptions {
 }
 /** Detaching closes only this attachment; the workspace PTY and agent keep running. */
 export declare function attachTerminal(options: AttachOptions): Promise<number>;
-export declare function cellConnector(cell: CellClient, sessionId: string): (offset: number, signal: AbortSignal) => Promise<PtyConnection>;
+/** Reads the workspace without waking it: suspended, or on its way there. */
+export declare function workspaceAsleep(ws: {
+    refresh(): Promise<unknown>;
+    state: string;
+    desiredState: string;
+}): Promise<boolean>;
+/** A host without passive attach refuses it before any output; the terminal then attaches as an ordinary one. */
+export declare function passiveUnavailable(error: unknown): boolean;
+/**
+ * Attaches a PTY. `passive` (the agent terminal, 0.14.4+) holds the workspace only while bytes move through it, so a
+ * waiting agent's workspace parks and suspends under an open terminal, and input still wakes it; on a host without
+ * passive attach the next attach is an ordinary one. An ordinary attach wakes a parked workspace and holds it.
+ */
+export declare function cellConnector(cell: CellClient, sessionId: string, opts?: {
+    passive?: boolean;
+}): (offset: number, signal: AbortSignal) => Promise<TerminalConnection>;