@shardflux/cli 0.20.0 → 0.23.0

package/dist/acp.js

@@ -6,14 +6,20 @@ import { AcpRpc, RpcError, objectValue } from "./acp-rpc.js";
 import { ACP_PROBE_CATALOG, nativeCurrentModel, nativeModelOptions, withoutNativeModel } from "./acp-catalog.js";
 import { ACP_LIFECYCLE, AcpModelCache, acpScope } from "./acp-models.js";
 import { AcpJournal } from "./acp-journal.js";
-import { getConversation, conversationWorkspace, rememberConversation, resumeConversation, restoreConversationBinding } from "./conversations.js";
+import { getConversation, conversationWorkspace, preparedInFlight, rememberConversation, resumeConversation, restoreConversationBinding } from "./conversations.js";
+import { seedEvent } from "./seed-phases.js";
 import { projectIdentity } from "./project-identity.js";
+import { projectSyncBoundary } from "./project-sync.js";
+import { localManifest } from "./project-sync-manifest.js";
 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";
+import { syncAgentConfigAfterStart } from "./agent-config-sync.js";
+import { savedMachine } from "./filesystem-state.js";
+import { accountVmProxy, prepareVmProxy } from "./t3-proxy.js";
 const PREFIX = 'shardflux:';
 export function acpModel(app, id) { return `${PREFIX}${app}:${id}`; }
 export function parseAcpModel(value) {
@@ -78,6 +84,7 @@ export class ShardfluxAcp {
     #sessions = new Map();
     #lifecycle;
     #cache;
+    #proxied = new Map();
     #initialized = false;
     #probe = false;
     constructor(ctx, client, errors = acpError, lifecycle = ACP_LIFECYCLE) { this.#ctx = ctx; this.#client = client; this.#store = new AgentStateStore(ctx.store.dir); this.#cache = new AcpModelCache(ctx.store.dir); this.#errors = errors; this.#lifecycle = lifecycle; }
@@ -196,11 +203,16 @@ export class ShardfluxAcp {
         }
         if (!record.model)
             throw new RpcError(-32602, 'Choose an available model before sending a message.');
-        await this.#connect(session);
+        const started = await this.#connect(session);
         if (method === 'session/load' || method === 'session/resume')
             return this.#configuration(record.model, { ...record.setup, sessionId: record.id }, record.catalog);
         const mapped = acpReferences(params, record, session.conversation.worktree_path, true);
+        const first = method === 'session/prompt' && !record.prompted;
         if (method === 'session/prompt') {
+            // A connection this prompt started has just reconciled the project files, and settled them unless that pass
+            // moved some (0.21.1+).
+            if (!started || !session.files.settled())
+                await session.files.reconcile();
             record.prompted = true;
             record.updatedAt = new Date().toISOString();
             this.#save(record);
@@ -209,13 +221,23 @@ export class ShardfluxAcp {
             return session.transport.rpc.notify(method, mapped);
         let result;
         try {
-            result = objectValue(await session.transport.rpc.request(method, mapped, method === 'session/prompt' ? 0 : 120_000));
+            const answer = session.transport.rpc.request(method, mapped, method === 'session/prompt' ? 0 : 120_000);
+            // Without a saved machine this computer's agent config is copied in once the first prompt is on its way, never
+            // before it (0.21.1+), as for a terminal conversation.
+            if (first && session.ws && !(await savedMachine(this.#ctx).catch(() => undefined))?.template)
+                void syncAgentConfigAfterStart(this.#ctx, session.ws);
+            result = objectValue(await answer);
         }
         catch (e) {
             if (method === 'session/prompt')
                 await this.#rejectModel(session, parseAcpModel(record.model).id, e);
             throw e;
         }
+        finally {
+            // T3 snapshots the local checkout as soon as the prompt response arrives.
+            if (method === 'session/prompt' && !this.#ctx.signal.aborted && !session.stop.signal.aborted)
+                await session.files.reconcile();
+        }
         return this.#configuration(record.model, acpReferences(result, record, session.conversation.worktree_path), record.catalog);
     }
     #prepare(session) {
@@ -226,8 +248,15 @@ export class ShardfluxAcp {
         // The native selected adapter must not wait for the other harness's model
         // probe. Both are guest processes; only boot/repository preparation gates it.
         session.prepared = new Promise(resolve => { prepared = resolve; });
+        // This computer's file hashes are read while the VM starts and seeds: the first prompt's reconcile then hashes only
+        // what changed since (0.21.1+). Best effort; the reconcile reads whatever is missing.
+        if (!session.hashes) {
+            session.hashes = new Map();
+            void localManifest(record.folder, ctx.signal, session.hashes).catch(() => undefined);
+        }
         session.preparing = (async () => {
             await syncAgentCredentials(ctx.cloud(), { home: ctx.io.env.HOME, redact: value => ctx.addSecret(value) });
+            const proxy = this.#proxy();
             const catalog = await this.#lifecycle.prepare(ctx, record.folder, `acp-${record.id.slice(3).replaceAll('-', '')}`, {
                 allocated: (c, view) => {
                     session.conversation = c;
@@ -247,6 +276,7 @@ export class ShardfluxAcp {
                 },
                 ready: ws => { session.ws = ws; record.scope = acpScope(ctx.apiUrl, ws.data); this.#cache.remember(ctx, record.folder, record.scope); },
                 prepared: () => { session.seedReady = true; prepared(); },
+                proxy: { env: { ...proxy.env.claude, ...proxy.env.codex }, ready: ws => this.#proxyReady(ws, proxy) },
             });
             ctx.signal.throwIfAborted();
             if (!record.scope)
@@ -329,25 +359,41 @@ export class ShardfluxAcp {
         }
         return session;
     }
+    /** True when this call started the connection (and so reconciled the project files just now). */
     async #connect(session) {
         await session.prepared;
         if (session.preparationError)
             throw session.preparationError;
-        if (session.connecting)
-            return session.connecting;
+        if (session.connecting) {
+            await session.connecting;
+            return false;
+        }
         if (session.transport && !session.transport.rpc.closed)
-            return;
+            return false;
         session.connecting = this.#start(session).finally(() => { session.connecting = undefined; });
-        return session.connecting;
+        await session.connecting;
+        return true;
     }
     async #start(session) {
         const ctx = this.#ctx, { record } = session, app = record.app ?? parseAcpModel(record.model).app;
+        // SHARDFLUX_TRACE_SEED: when each step of the connection ends (one line each, wall clock).
+        const mark = (name) => seedEvent(`acp_${name}`, Date.now());
+        mark('connect');
         record.app = app;
         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, 'Authentication required: connect Claude Code.', { code: 'unauthenticated', fix: SIGN_IN });
+        // The user's T3 Code proxy setup, read again for every connection; the agent's variables apply when its process starts.
+        const proxy = this.#proxy();
+        // The sign-in is checked beside reading the conversation and its VM; it passes before anything starts in the VM. A
+        // proxy with its own credential needs no Shardflux Claude sign-in.
+        const signIn = (async () => {
+            await syncAgentCredentials(ctx.cloud(), { home: ctx.io.env.HOME, redact: value => ctx.addSecret(value) });
+            if (app === 'claude' && !proxy.claudeCredential && !(await cloudClaudeLogin(ctx))) {
+                throw new RpcError(-32000, proxy.importable.includes('claude') ? 'Authentication required: connect Claude Code, or move your CLIProxyAPI into your account (shard cli-proxy import).' : 'Authentication required: connect Claude Code.', { code: 'unauthenticated', fix: SIGN_IN });
+            }
+        })();
+        signIn.catch(() => undefined);
         if (!record.conversationId) {
+            await signIn;
             this.#prepare(session);
             await session.prepared;
             if (session.preparationError)
@@ -360,11 +406,38 @@ export class ShardfluxAcp {
             session.conversation = await resumeConversation(ctx, current);
             session.ws = await conversationWorkspace(ctx, session.conversation);
             rememberConversation(ctx, session.conversation, record.folder);
+            mark('conversation');
         }
+        await signIn;
+        mark('signed_in');
         let c = session.conversation;
         const cell = session.ws.cell();
-        await ensureMenubar(ctx.store.dir, ctx.apiUrl, new MenubarManager({ home: ctx.io.env.HOME, signal: ctx.signal }));
+        const menubar = ensureMenubar(ctx.store.dir, ctx.apiUrl, new MenubarManager({ home: ctx.io.env.HOME, signal: ctx.signal }));
         await restoreConversationBinding(ctx, c, session.ws);
+        mark('binding');
+        // The project files are reconciled, device approvals served and the supervisor launched side by side; the native
+        // session starts once the supervisor is up, and the connection is done (the prompt goes) once the files are
+        // reconciled too (0.21.1+).
+        const files = (async () => {
+            const boundary = await projectSyncBoundary({ ...ctx, signal: AbortSignal.any([ctx.signal, session.stop.signal]) }, session.ws, projectIdentity(record.folder), {
+                root: c.worktree_path, agent: record.id.replace(/^sf-/, 'acp-'), seed: false,
+                stateKey: `acp:${ctx.apiUrl}:${record.id}:${record.folder}`, ...(session.hashes ? { cache: session.hashes } : {}),
+                // Before its first prompt the VM holds what this computer seeded it with, so edits made here since are not conflicts.
+                vmBaseline: !record.prompted,
+                // Large media of a prepared start that are still on their way land by themselves (0.22.0+).
+                inFlight: () => preparedInFlight(ctx, c.id),
+            });
+            await boundary.reconcile();
+            mark('files');
+            return boundary;
+        })();
+        // The agent starts with the proxy setup's variables, once the VM files it reads are in place.
+        const env = proxy.env[app];
+        const launch = this.#proxyReady(session.ws, proxy).then(() => cell.exec.run(['sf-agent', 'acp', app, '--conversation', c.id, '--detach'], {
+            cwd: c.worktree_path, timeoutMs: 30_000, signal: ctx.signal, maxOutputBytes: 1 << 20, ...(Object.keys(env).length ? { env } : {})
+        }));
+        files.catch(() => undefined);
+        launch.catch(() => undefined);
         session.approvals ??= await serveAcpDeviceApprovals(ctx.store.dir, c.id, async (approval) => {
             const result = objectValue(await this.#client.request('session/request_permission', { sessionId: record.id,
                 toolCall: { toolCallId: approval.request_id, title: approval.summary, kind: 'execute', status: 'pending' },
@@ -372,15 +445,20 @@ export class ShardfluxAcp {
             const outcome = objectValue(result.outcome);
             return outcome.outcome === 'selected' && (outcome.optionId === 'once' || outcome.optionId === 'always') ? outcome.optionId : 'deny';
         });
-        const launched = await cell.exec.run(['sf-agent', 'acp', app, '--conversation', c.id, '--detach'], { cwd: c.worktree_path, timeoutMs: 30_000, signal: ctx.signal, maxOutputBytes: 1 << 20 });
+        mark('approvals');
+        const launched = await launch;
+        mark('launched');
+        await menubar;
         if (launched.exitCode !== 0)
             throw new Error(`ACP supervisor could not attach: ${launched.stderr.trim()}`);
-        c = await getConversation(ctx, c.id);
+        const [claimed, statusText] = await Promise.all([getConversation(ctx, c.id), cell.files.readText(`/home/user/.local/share/shardflux/acp/${c.id}/status.json`, { length: 8192 })]);
+        c = claimed;
+        mark('status');
         if (c.harness !== app)
             throw new Error('The guest did not claim this conversation harness.');
         session.conversation = c;
         rememberConversation(ctx, c, record.folder);
-        const status = JSON.parse(await cell.files.readText(`/home/user/.local/share/shardflux/acp/${c.id}/status.json`, { length: 8192 }));
+        const status = JSON.parse(statusText);
         if (status.conversation_id !== c.id || status.harness !== app || !Number.isSafeInteger(status.pid) || status.pid <= 0 || !status.start || status.ended)
             throw new Error('ACP supervisor identity does not match this conversation.');
         const owner = `${session.ws.id}:${status.pid}:${status.start}`;
@@ -423,13 +501,16 @@ export class ShardfluxAcp {
         };
         session.transport = transport;
         await transport.start();
+        mark('journal');
         if (initialize) {
             const initialized = objectValue(await transport.rpc.request('initialize', { protocolVersion: 1, clientInfo: { name: 'shardflux', version: CLI_VERSION }, clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false } }));
             if (initialized.protocolVersion !== 1)
                 throw new Error('Agent protocol version changed');
+            mark('initialized');
             const nativeId = c.harness_session_id ?? record.nativeId;
             const result = objectValue(await transport.rpc.request(nativeId ? 'session/load' : 'session/new', { cwd: c.worktree_path, mcpServers: [{ name: 'shardflux', command: '/usr/local/bin/sf-agent', args: ['conversation', 'mcp'], env: [{ name: 'SF_CONVERSATION_ID', value: c.id }] }], ...(nativeId ? { sessionId: nativeId } : {}) }));
             const id = result.sessionId ?? nativeId;
+            mark('session');
             if (typeof id !== 'string' || !id)
                 throw new Error('Agent returned no native session id');
             record.nativeId = id;
@@ -452,6 +533,31 @@ export class ShardfluxAcp {
             this.#cacheSession(session);
             await this.#modelUpdate(session);
         }
+        // Not connected until the files are: a failed reconcile closes the journal, so the next use connects again.
+        try {
+            session.files = await files;
+        }
+        catch (error) {
+            await session.transport.close();
+            throw error;
+        }
+        mark('files_ready');
+    }
+    /** The T3 Code proxy setup as a conversation VM follows it. Its credentials are kept out of every message. */
+    #proxy() { return accountVmProxy(this.#ctx); }
+    /** Puts the proxy's VM files in place once per VM and setup (prepareVmProxy). */
+    #proxyReady(ws, plan) {
+        if (!plan.hubInfo && !plan.codexConfig)
+            return Promise.resolve();
+        const key = JSON.stringify([plan.hubInfo, plan.codexConfig]);
+        const done = this.#proxied.get(ws.id);
+        if (done?.key === key)
+            return done.ready;
+        const ready = prepareVmProxy(ws.cell(), plan);
+        this.#proxied.set(ws.id, { key, ready });
+        ready.catch(() => { if (this.#proxied.get(ws.id)?.ready === ready)
+            this.#proxied.delete(ws.id); });
+        return ready;
     }
     async #close(session) {
         this.#sessions.delete(session.record.id);

package/dist/agent-commands.d.ts

@@ -7,13 +7,15 @@ import type { ModelChoice } from './agent-models.js';
 export declare function disambiguatedSlug(slug: string, identity: string): string;
 export declare function projectTemplate(ctx: Ctx, remote: string | null): Promise<string>;
 /** `place` is the repository or folder name session titles end with ("todo-app"), `task` what a new session is titled
- * with before the guest names it from its first prompt (a first prompt line or the conversation's title). */
+ * with before the guest names it from its first prompt (a first prompt line or the conversation's title), and
+ * `launch.titlePrefix` the marker titles start with when this computer chose one ("" for none; 0.20.1+). */
 export declare function agentPty(cell: CellClient, app: 'claude' | 'codex', agent: string, approvals: boolean, term: string, signal?: AbortSignal, place?: string, setupHash?: string, cwd?: string, ptyName?: string, onLaunch?: () => void, deferSetup?: boolean, conversation?: {
     id: string;
     session: string | null;
 }, task?: string, launch?: {
     choice?: ModelChoice;
     help?: () => Promise<string>;
+    titlePrefix?: string;
 }): Promise<PtySession>;
 /** The first non-empty line of a prompt or title, bounded; the guest makes it the task part of the session title. */
 export declare function sessionTask(text: string | undefined): string | undefined;
@@ -24,6 +26,7 @@ export declare function terminal(ctx: Ctx, ws: Workspace, app: 'claude' | 'codex
     title?: string;
     choice?: ModelChoice;
     afterStart?: () => Promise<void> | undefined;
+    setupLabelled?: Promise<void>;
 }): Promise<number>;
 export declare const launchProject: Handler;
 /** The project VM launch; with `--in t3` a first message becomes a thread on the T3 server in it (SSH mode, 0.17.0+). */

package/dist/agent-commands.js

@@ -1,6 +1,7 @@
-import { linuxTerminalSession, openLinuxTerminal } from "./linux-terminal.js";
+import { linuxTerminalSession } from "./linux-terminal.js";
+import { attachable, currentTerminal, handedToTerminal, openShardInTerminal, referenceFolder, reportTerminalOpen, storedTerminal } from "./terminal-apps.js";
 import { repositoryName } from "./files-mirror.js";
-import { prepareSetupCache } from "./setup-cache.js";
+import { prepareSetupCache, recordSetupCacheFailure } from "./setup-cache.js";
 import { launchCodexCloud, openCodexConversation } from "./codex-cloud.js";
 import { agentReachability } from "./agent-reachability.js";
 import { configureCredentialFill, watchCredentialPrompts } from "./credential-prompts.js";
@@ -21,13 +22,15 @@ import { preflightProjectSeed, projectWorkspacePath, seedAgentRepository, worksp
 import { agentName } from "./agent-git.js";
 import { cloudClaudeLogin, ensureCloudClaude, loginClaudeInWorkspace, requireClaudeTerminal } from "./claude-cloud-login.js";
 import { progress } from "./progress.js";
+import { seedEvent, seedPhase } from "./seed-phases.js";
 import { rememberLaunch } from "./agent-live.js";
 import { prepareAgentMachine } from "./agent-machine.js";
 import { installedTargets } from "./agent-targets.js";
 import { openInFor } from "./t3-mode.js";
+import { storedTitlePrefix } from "./client-settings.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 { guestFirstPrompt, INBOX_MAX_CHARS, submitInitialPrompt, prepareInitialCodexProject } from "./initial-prompt.js";
+import { conversationForOpen, conversationWorkspace, conversationsUnavailable, getConversation, listConversations, resumeConversation } from "./conversations.js";
 import { conversationClient } from "./conversation-commands.js";
 import { conversationTerminal, reopenConversation } from "./conversation-terminal.js";
 import { CHOICE_PENDING, choiceReport, hasChoice, launchChoice, modelChoice, runFlags } from "./agent-models.js";
@@ -53,7 +56,8 @@ export async function projectTemplate(ctx, remote) {
     }
 }
 /** `place` is the repository or folder name session titles end with ("todo-app"), `task` what a new session is titled
- * with before the guest names it from its first prompt (a first prompt line or the conversation's title). */
+ * with before the guest names it from its first prompt (a first prompt line or the conversation's title), and
+ * `launch.titlePrefix` the marker titles start with when this computer chose one ("" for none; 0.20.1+). */
 export async function agentPty(cell, app, agent, approvals, term, signal, place, setupHash, cwd, ptyName, onLaunch, deferSetup = false, conversation, task, launch) {
     const id = `shard-${ptyName || agent}-${app}`;
     // Arrival and changed locks queue the same durable guest job even when the
@@ -81,7 +85,8 @@ export async function agentPty(cell, app, agent, approvals, term, signal, place,
     }
     // A model and effort choice reaches only a guest whose run accepts it (the caller checked).
     const started = await cell.exec.run(['sf-agent', 'run', app, '--name', agent, '--detach', ...conversationArgs, ...(ptyName ? ['--pty-name', ptyName] : []), ...(approvals ? ['--approvals'] : []), ...(setupHash ? ['--setup', '--setup-deps-hash', setupHash] : []), ...runFlags(launch?.choice)], {
-        env: { TERM: term, ...(place ? { SF_PROJECT_NAME: place, SF_REPO_NAME: place } : {}), ...(task ? { SF_TASK_TITLE: task } : {}), ...(setupHash && deferSetup ? { SF_SETUP_DEFERRED: '1' } : {}) }, timeoutMs: 30_000, maxOutputBytes: 4096, signal, ...(cwd ? { cwd } : {}),
+        // SF_TITLE_PREFIX: the chosen marker for a launch without a conversation record (a guest before it ignores it).
+        env: { TERM: term, ...(place ? { SF_PROJECT_NAME: place, SF_REPO_NAME: place } : {}), ...(task ? { SF_TASK_TITLE: task } : {}), ...(launch?.titlePrefix !== undefined ? { SF_TITLE_PREFIX: launch.titlePrefix } : {}), ...(setupHash && deferSetup ? { SF_SETUP_DEFERRED: '1' } : {}) }, timeoutMs: 30_000, maxOutputBytes: 4096, signal, ...(cwd ? { cwd } : {}),
     });
     if (started.exitCode !== 0)
         throw new Error(`agent launch failed: ${started.stderr.trim() || `exit ${started.exitCode}`}`);
@@ -122,7 +127,12 @@ export async function terminal(ctx, ws, app, agent, project, values, setupHash,
         if (app === 'codex' && typeof values.initialPrompt === 'string') {
             await prepareInitialCodexProject(cell, cwd, `shard-${ptyName || agent}-${app}`);
         }
-        const credentialFill = await configureCredentialFill(ctx, ws);
+        // Credential fill serves the agent's later credential prompts: configured beside the first prompt, never before it.
+        const credentialFill = configureCredentialFill(ctx, ws).catch((error) => {
+            if (!ctx.signal.aborted)
+                ctx.io.stderr.write(`Credential fill is off for this session: ${error instanceof Error ? error.message : String(error)}\n`);
+            return false;
+        });
         // This command's --model/--effort, else the conversation's own (a relaunch keeps its model). A computer whose guest
         // predates the choice starts the agent with its defaults, and this command says so once.
         const help = runHelp(cell, app, ctx.signal), explicit = modelChoice(values, app);
@@ -131,16 +141,21 @@ export async function terminal(ctx, ws, app, agent, project, values, setupHash,
             ctx.io.stderr.write(`${CHOICE_PENDING}\n`);
         // A cold launch is remembered before it starts, so the listing can show it before the projection does (agent-live.ts).
         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, repositoryName(ws.labels.repo_remote || project), setupHash, cwd, ptyName, () => { rememberLaunch(ctx, ws.id); progress(ctx, `Starting ${app === 'claude' ? 'Claude' : 'Codex'} in ${ws.key}…`); }, true, conversation && { id: conversation.id, session: conversation.session }, sessionTask(typeof values.initialPrompt === 'string' ? values.initialPrompt : conversation?.title), { ...(choice ? { choice } : {}), help });
+        const titlePrefix = storedTitlePrefix(ctx.store.dir);
+        const session = await agentPty(cell, app, agent, values.approvals === true, term, ctx.signal, repositoryName(ws.labels.repo_remote || project), setupHash, cwd, ptyName, () => { rememberLaunch(ctx, ws.id); progress(ctx, `Starting ${app === 'claude' ? 'Claude' : 'Codex'} in ${ws.key}…`); }, true, conversation && { id: conversation.id, session: conversation.session }, sessionTask(typeof values.initialPrompt === 'string' ? values.initialPrompt : conversation?.title), { ...(choice ? { choice } : {}), help, ...(titlePrefix !== undefined ? { titlePrefix } : {}) });
+        seedPhase('harness_launch');
+        // When the harness's terminal started, by the VM's clock (the guest may start it before this command asks).
+        if (session.created_at)
+            seedEvent('harness_started', Date.parse(session.created_at));
         // 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`);
-        }).then(async () => {
+        const preparation = prepareSetupCache(ctx, ws).catch((error) => recordSetupCacheFailure(ctx, ws, error)).then(async () => {
             if (!setupHash)
                 return;
+            // A new conversation's VM carries the setup labels before its setup starts (0.21.1+).
+            await conversation?.setupLabelled;
             const queued = await cell.exec.run(['sf-agent', 'setup-start', '--deps-hash', setupHash], { cwd, timeoutMs: 30_000, maxOutputBytes: 4096, signal: ctx.signal });
             if (queued.exitCode !== 0)
                 throw new Error(`project setup could not be queued: ${queued.stderr.trim() || `exit ${queued.exitCode}`}`);
@@ -151,12 +166,22 @@ export async function terminal(ctx, ws, app, agent, project, values, setupHash,
             const text = values.initialPrompt;
             // A conversation's guest delivers the prompt itself when this terminal never showed its input box (0.19.1+).
             const queue = conversation ? () => conversationClient(ctx).conversations.send(conversation.id, text, { signal: ctx.signal }) : undefined;
-            delivery = await submitInitialPrompt(signal => cellConnector(cell, session.session_id)(0, signal), text, ws.key, ctx.signal, app, bytes => cell.pty.input(session.session_id, bytes), queue);
+            // The VM's guest types it where it can (0.21.1+); this terminal types it for an older guest. A harness the guest
+            // waited for without seeing its input box gets it through the inbox, not a second wait here.
+            const guest = await guestFirstPrompt(cell, session.session_id, app, text, ws.key, ctx.signal);
+            if (guest === 'submitted')
+                delivery = 'submitted';
+            else if (guest === 'not_ready' && queue && text.length <= INBOX_MAX_CHARS) {
+                await queue();
+                delivery = 'queued';
+            }
+            else
+                delivery = await submitInitialPrompt(signal => cellConnector(cell, session.session_id)(0, signal), text, ws.key, ctx.signal, app, bytes => cell.pty.input(session.session_id, bytes), queue);
         }
         // Work that must never delay the first prompt (the laptop's agent config, 0.19.0+) starts once the agent has it.
         const after = conversation?.afterStart?.();
         if (!attach) {
-            await preparation;
+            await Promise.all([preparation, credentialFill]);
             // conversation (0.16.0+): which conversation this session is, also when its computer hosts several threads.
             // model_choice (0.17.0+): the requested model and effort, and whether this thread started with them.
             ctx.io.stdout.write(json({ workspace: ws.data, session, ...(conversation ? { conversation: { id: conversation.id } } : {}), ...(delivery ? { initial_prompt: delivery === 'submitted' ? { submitted: true } : { submitted: false, queued: true } } : {}),
@@ -166,7 +191,7 @@ export async function terminal(ctx, ws, app, agent, project, values, setupHash,
         }
         ctx.io.stderr.write(`Shardflux · ${ws.key}\nDetach: Ctrl-] then d\n`);
         const attached = attachTerminal({
-            ...(credentialFill ? { credentialPrompts: (ask, signal) => watchCredentialPrompts(ctx, ws, ask, signal) } : {}),
+            ...(await credentialFill ? { credentialPrompts: (ask, signal) => watchCredentialPrompts(ctx, ws, ask, signal) } : {}),
             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),
@@ -294,18 +319,72 @@ export async function launchProjectWith(ctx, values, [path = './', explicitApp],
     await prepareAgentMachine(ctx, ws);
     return await terminal(ctx, ws, app, agent, projectKey, values, prepared?.setupHash);
 }
+/**
+ * Whether `agents open` hands the conversation to the person's terminal app (0.20.1+) rather than attaching here:
+ * `--in terminal` with --json (an app) or `--window`, any open from a shell nobody types into (a coding agent's, or no
+ * terminal), and `--in terminal` typed in a terminal other than the chosen one.
+ */
+function opensInTerminalApp(ctx, values) {
+    // A terminal this CLI opened for the conversation attaches there, never in yet another one (0.23.0+).
+    if (values.detach === true || handedToTerminal(ctx.io.env))
+        return false;
+    const here = attachable(ctx.io);
+    if (values.in === undefined)
+        return !ctx.json && !here;
+    if (values.in !== 'terminal')
+        return false;
+    if (ctx.json || !here || values.window === true)
+        return true;
+    const stored = storedTerminal(ctx.store.dir);
+    return !!stored && stored.id !== currentTerminal(ctx.io.env);
+}
+/** `shard agents open <ref>` (its attach, no --in) in a new tab of the person's terminal app, in the project folder. */
+async function openInTerminalApp(ctx, ref, values, extra = {}) {
+    const words = ['agents', 'open', ref, ...(typeof values.app === 'string' ? ['--app', values.app] : [])];
+    const result = await openShardInTerminal(ctx, words, { cwd: referenceFolder(ctx.store.dir, ctx.apiUrl, ref, ctx.io.env), window: values.window === true });
+    reportTerminalOpen(ctx, result, extra);
+    return 0;
+}
+/**
+ * `--in auto` for a terminal conversation: the person's terminal app (a tab there, 0.20.1+), or this terminal when it
+ * is the one they use. --json without a chosen terminal app keeps the command for an app to run (a menu bar before
+ * 0.20.1 opens Terminal with it).
+ */
+function terminalAuto(ctx, ws, opened, values) {
+    if (ctx.json && !storedTerminal(ctx.store.dir)) {
+        out(ctx, `shard agents open ${opened}\n`, { target: 'terminal', workspace: ws.data, command: ['shard', 'agents', 'open', opened] });
+        return Promise.resolve(0);
+    }
+    const next = { ...values, in: 'terminal' };
+    if (opensInTerminalApp(ctx, next))
+        return openInTerminalApp(ctx, opened, next, { workspace: ws.data });
+    delete next.in;
+    return AGENT_HANDLERS['agents open'](ctx, next, [opened]);
+}
 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');
-        if (process.platform === 'linux' && !ctx.json && !ctx.io.stdin.isTTY && values.detach !== true && (values.in === undefined || values.in === 'terminal'))
-            return openLinuxTerminal(ctx, agent, typeof values.app === 'string' ? values.app : undefined);
+        // A Codex Cloud conversation opens its chat in Codex, never in a terminal (0.23.0+): it is resolved before any
+        // terminal hand-off, by its id or by its computer's key, which menus before Linux 0.1.9 and menu bar 0.8.4 pass.
+        // Nimblefox (2026-10-13): the hand-off came first, and from a Codex shell each new terminal opened another one.
+        // The person's terminal app (0.20.1+): after that lookup, the new tab owns the attach, credentials and prompts; a
+        // lookup this shell cannot make (signed out here, offline) leaves the hand-off to it.
+        const handOff = opensInTerminalApp(ctx, values);
         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 (/^conv_[a-z0-9]{26}$/.test(agent) || agent.includes('/')) {
+            try {
+                resolvedConversation = await conversationForOpen(ctx, agent);
+            }
+            catch (error) {
+                if (!handOff)
+                    throw error;
+            }
         }
+        if (resolvedConversation?.route === 'codex-cloud')
+            return openCodexConversation(ctx, resolvedConversation, values.original === true ? true : values.history);
+        if (handOff)
+            return openInTerminalApp(ctx, agent, values);
         if (values.in === 'auto') {
             // The menu and other launchers use the same CLI-owned target selection. Never put provider URLs in a client.
             // A conversation id opens that conversation's own session, also when its computer hosts other threads.
@@ -330,20 +409,16 @@ export const AGENT_HANDLERS = {
             }
             if (chosen === 'claude-desktop' && app === 'claude')
                 return openClaudeDesktopSession(ctx, ws, resolvedConversation);
-            if (chosen === 'terminal' && app === 'claude') {
-                if (ctx.json) {
-                    out(ctx, `shard agents open ${opened}\n`, { target: 'terminal', workspace: ws.data, command: ['shard', 'agents', 'open', opened] });
-                    return 0;
-                }
-                const next = { ...values };
-                delete next.in;
-                return AGENT_HANDLERS['agents open'](ctx, next, [opened]);
-            }
+            // A terminal app attaches to the conversation's own session, Claude Code's or Codex's (Codex 0.21.1+).
+            if (chosen === 'terminal' && (app === 'claude' || app === 'codex'))
+                return terminalAuto(ctx, ws, opened, values);
             const saved = chosen === 'codex-app' ? undefined : 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') {
+                if (resolvedConversation?.route === 'terminal')
+                    return terminalAuto(ctx, ws, opened, values);
                 const next = { ...values };
                 delete next.in;
                 return AGENT_HANDLERS['agents open'](ctx, next, [resolvedConversation?.id ?? ws.key]);
@@ -353,21 +428,14 @@ export const AGENT_HANDLERS = {
                 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]);
+                return handler(ctx, { ...values, in: saved }, [opened]);
             }
             // 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, resolvedConversation);
             }
-            if (ctx.json) {
-                // An app runs this in the person's terminal (the menu bar opens Terminal with it).
-                out(ctx, `shard agents open ${opened}\n`, { target: 'terminal', workspace: ws.data, command: ['shard', 'agents', 'open', opened] });
-                return 0;
-            }
-            const next = { ...values };
-            delete next.in;
-            return AGENT_HANDLERS['agents open'](ctx, next, [opened]);
+            return terminalAuto(ctx, ws, opened, values);
         }
         if (values.in !== undefined && values.in !== 'terminal') {
             const { HANDLERS } = await import("./handlers.js");
@@ -379,10 +447,10 @@ export const AGENT_HANDLERS = {
         await syncCredentials(ctx);
         let ws;
         let conversation;
-        if (/^conv_[a-z0-9]{26}$/.test(agent)) {
+        if (resolvedConversation || /^conv_[a-z0-9]{26}$/.test(agent)) {
             conversation = resolvedConversation ?? await getConversation(ctx, agent);
             if (conversation.route === 'codex-cloud')
-                return openCodexConversation(ctx, conversation);
+                return openCodexConversation(ctx, conversation, values.original === true ? true : values.history);
             conversation = await resumeConversation(ctx, conversation);
             ws = await conversationWorkspace(ctx, conversation);
         }
@@ -415,7 +483,7 @@ export const AGENT_HANDLERS = {
                 if (matches.length !== 1)
                     throw new UsageError('Use the conversation id.');
                 if (matches[0].route === 'codex-cloud')
-                    return openCodexConversation(ctx, matches[0]);
+                    return openCodexConversation(ctx, matches[0], values.original === true ? true : values.history);
                 conversation = await resumeConversation(ctx, matches[0]);
                 ws = await conversationWorkspace(ctx, conversation);
             }
@@ -423,7 +491,7 @@ export const AGENT_HANDLERS = {
             if (!conversation && ws.labels.shard_conversation) {
                 conversation = await getConversation(ctx, ws.labels.shard_conversation);
                 if (conversation.route === 'codex-cloud')
-                    return openCodexConversation(ctx, conversation);
+                    return openCodexConversation(ctx, conversation, values.original === true ? true : values.history);
                 conversation = await resumeConversation(ctx, conversation);
                 ws = await conversationWorkspace(ctx, conversation);
             }

package/dist/agent-config-return.d.ts

@@ -2,6 +2,8 @@ import type { CellClient } from '@shardflux/sdk';
 import type { Ctx } from './commands.js';
 import type { Conversation, LocalConversation } from './conversations.js';
 export declare const RETURN_ROOT = "/shardflux/project/agent-config";
+/** The latest agent-config line ({notice, at}), for the Linux app's top-bar panel (CLI 0.20.2+). */
+export declare const AGENT_CONFIG_NOTICE = "agent-config-notice.json";
 /** A machine fold waits for this much quiet after the last change, and saves the machine at most this often. */
 export declare const FOLD_QUIET_MS = 60000;
 export declare const FOLD_INTERVAL_MS: number;
@@ -116,8 +118,50 @@ export declare class AgentConfigReturnState {
 }
 /** How often the device helper looks for agent config to bring back: its own loop, never behind a files or transcript pass. */
 export declare const AGENT_CONFIG_POLL_MS = 2000;
-/** One pass of the device helper's own agent-config loop: list the account's conversations and apply what came back. */
-export declare function returnAgentConfigsOnce(ctx: Ctx, state: AgentConfigReturnState): Promise<string | undefined>;
+/** With none of this user's conversations active, the full listing backs off (doubling) to this. */
+export declare const AGENT_CONFIG_IDLE_MS = 60000;
+/** While backed off, one cheap request (`state=working`, usually empty) this often notices a turn starting anywhere. */
+export declare const AGENT_CONFIG_PROBE_MS = 10000;
+/** A conversation counts as active for this long after its last activity (a turn's start or end). */
+export declare const AGENT_CONFIG_ACTIVE_WINDOW_MS: number;
+/**
+ * A working conversation counts as active only this long after its last activity: one left "working" by a VM that went
+ * away (staging QA FE1: 60 such, all more than a day old) must not hold every computer at the fast cadence. A longer
+ * turn still comes back, at the idle cadence.
+ */
+export declare const AGENT_CONFIG_WORKING_WINDOW_MS: number;
+/** This user's conversations that are working (recently) or ended a turn within the active window. */
+export declare function activeConversations(all: Conversation[], records: Record<string, LocalConversation>, me: string | undefined, now?: number): Conversation[];
+export interface CadenceOptions {
+    activeMs: number;
+    idleMs: number;
+    probeMs: number;
+}
+export declare const CADENCE: CadenceOptions;
+/**
+ * When the next listing is due. Active (one of this user's conversations works or just ended a turn): every 2 s.
+ * Idle: the interval doubles to 60 s, with a cheap working-only probe every 10 s and a check of this computer's own
+ * conversation records each second; either snaps it back to 2 s at once.
+ */
+export declare class AgentConfigCadence {
+    readonly options: CadenceOptions;
+    interval: number;
+    fullAt: number;
+    probeAt: number;
+    recordsMtime: number;
+    constructor(options?: CadenceOptions);
+    /** After a full pass: active keeps 2 s, idle doubles toward the idle ceiling. */
+    listed(active: boolean, now?: number): void;
+    snap(): void;
+    fullDue(now?: number): boolean;
+    probeDue(now?: number): boolean;
+}
+/** One full pass: list the account's conversations, apply what came back; true while one of this user's is active. */
+export declare function returnAgentConfigsOnce(ctx: Ctx, state: AgentConfigReturnState): Promise<boolean>;
+/** The cheap probe: is any of this user's conversations working right now (one request, usually an empty page)? */
+export declare function workingProbe(ctx: Ctx, state: AgentConfigReturnState): Promise<boolean>;
+/** The device helper's agent-config loop: activity-driven cadence, its own backoff on errors, never another loop's. */
+export declare function runAgentConfigLoop(ctx: Ctx, state: AgentConfigReturnState, signal: AbortSignal, cadence?: AgentConfigCadence, tickMs?: number): Promise<void>;
 /**
  * This computer's checkout of a conversation's repository: the folder it was started from here, else the folder of
  * another conversation of the same repository started here. A Shardflux project can hold many repositories (staging