@shardflux/cli 0.13.5 → 0.14.0

package/dist/acp.js

@@ -0,0 +1,290 @@
+import { randomUUID } from 'node:crypto';
+import { isAbsolute } from 'node:path';
+import { CLI_VERSION } from "./args.js";
+import { AgentStateStore } from "./agent-state.js";
+import { AcpRpc, RpcError, objectValue } from "./acp-rpc.js";
+import { ACP_CATALOG } from "./acp-catalog.js";
+import { AcpJournal } from "./acp-journal.js";
+import { createConversation, getConversation, conversationWorkspace, rememberConversation, resumeConversation, restoreConversationBinding } from "./conversations.js";
+import { projectIdentity } from "./project-identity.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 { syncAgentConfig } from "./agent-config-sync.js";
+import { savedMachine } from "./filesystem-state.js";
+import { ensureMenubar, MenubarManager } from "./menubar.js";
+const PREFIX = 'shardflux:';
+export function acpModel(app, id) { return `${PREFIX}${app}:${id}`; }
+export function parseAcpModel(value) {
+    if (typeof value !== 'string')
+        throw new RpcError(-32602, 'Choose a model from Shardflux.');
+    const match = /^shardflux:(claude|codex):(.+)$/.exec(value);
+    if (!match)
+        throw new RpcError(-32602, 'Choose a model from Shardflux.');
+    return { app: match[1], id: match[2] };
+}
+export function acpModelOptions(catalog) {
+    return ['claude', 'codex'].flatMap(app => {
+        const source = catalog[app].configOptions.find(c => c.category === 'model');
+        return (source?.options ?? []).flatMap(option => Array.isArray(option.options) ? option.options : [option]).map((option) => {
+            if (typeof option.value !== 'string' || !option.value || typeof option.name !== 'string' || !option.name)
+                throw new Error('Agent model metadata omitted its ID or name');
+            return { ...option, value: acpModel(app, option.value), name: `${app === 'claude' ? 'Claude Code' : 'Codex'} · ${option.name}` };
+        });
+    });
+}
+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 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.');
+    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. */
+export function acpReferences(value, record, root, inbound = false) {
+    if (Array.isArray(value))
+        return value.map(v => acpReferences(v, record, root, inbound));
+    if (!value || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, leaf]) => {
+        if (key === 'sessionId' && leaf === (inbound ? record.id : record.nativeId))
+            return [key, inbound ? record.nativeId : record.id];
+        if (typeof leaf === 'string' && ['path', 'cwd', 'uri'].includes(key)) {
+            const from = inbound ? record.folder : root, to = inbound ? root : record.folder;
+            if (leaf === from || leaf.startsWith(from + '/'))
+                return [key, to + leaf.slice(from.length)];
+            if (leaf.startsWith(`file://${from}/`))
+                return [key, `file://${to}` + leaf.slice(`file://${from}`.length)];
+        }
+        return [key, acpReferences(leaf, record, root, inbound)];
+    }));
+}
+/** One provider, two harness catalogs. The model selection determines the VM's native harness. */
+export class ShardfluxAcp {
+    #ctx;
+    #client;
+    #store;
+    #errors;
+    #sessions = new Map();
+    #catalog = { claude: structuredClone(ACP_CATALOG.claude.session), codex: structuredClone(ACP_CATALOG.codex.session) };
+    #initialized = false;
+    #probe = false;
+    constructor(ctx, client, errors = acpError) { this.#ctx = ctx; this.#client = client; this.#store = new AgentStateStore(ctx.store.dir); this.#errors = errors; }
+    #records() { return this.#store.read().acp_sessions ?? {}; }
+    #save(record) { this.#store.update(doc => { doc.acp_sessions = { ...objectValue(doc.acp_sessions), [record.id]: record }; }); }
+    #configuration(model, native = {}) {
+        const options = acpModelOptions(this.#catalog);
+        return { ...native, models: { currentModelId: model, availableModels: options.map(o => ({ modelId: o.value, name: o.name, ...(o.description ? { description: o.description } : {}) })) },
+            configOptions: [{ id: 'model', name: 'Model', category: 'model', type: 'select', currentValue: model, options }, ...(native.configOptions ?? []).filter(c => c.category !== 'model')] };
+    }
+    async handle(method, params, request) {
+        try {
+            return await this.#handle(method, params, request);
+        }
+        catch (error) {
+            throw this.#errors(error);
+        }
+    }
+    async #handle(method, params, request) {
+        if (method === 'initialize') {
+            if (this.#initialized)
+                throw new RpcError(-32600, 'Already initialized');
+            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: [],
+                agentCapabilities: { loadSession: true, promptCapabilities: { image: true, embeddedContext: true }, sessionCapabilities: { list: {}, resume: {}, close: {} } } };
+        }
+        if (!this.#initialized)
+            throw new RpcError(-32600, 'Initialize first');
+        if (method === 'session/list') {
+            const sessions = Object.values(this.#records()).filter(r => r.apiUrl === this.#ctx.apiUrl && (!params.cwd || r.folder === params.cwd));
+            return { sessions: sessions.map(r => ({ sessionId: r.id, cwd: r.folder, updatedAt: r.updatedAt })) };
+        }
+        if (method === 'session/new') {
+            if (this.#probe)
+                return this.#configuration(acpModel('claude', 'default'), { sessionId: 'shardflux-probe' });
+            if (typeof params.cwd !== 'string' || !isAbsolute(params.cwd))
+                throw new RpcError(-32602, 'Open a project folder first.');
+            const folder = projectIdentity(params.cwd).folder;
+            const record = { id: `sf-${randomUUID()}`, apiUrl: this.#ctx.apiUrl, folder, model: acpModel('claude', 'default'), from_seq: 0, updatedAt: new Date().toISOString() };
+            // T3 selects its model after session/new. Reserve identity now; allocate on the selection/first prompt.
+            this.#save(record);
+            this.#sessions.set(record.id, { record, stop: new AbortController() });
+            return this.#configuration(record.model, { sessionId: record.id });
+        }
+        if (this.#probe && method === 'session/close')
+            return {};
+        if (typeof params.sessionId !== 'string')
+            throw new RpcError(-32602, 'A conversation is required');
+        const session = this.#session(params.sessionId, params.cwd);
+        const { record } = session;
+        if (method === 'session/close') {
+            await this.#close(session);
+            return {};
+        }
+        if (method === 'session/set_model' || (method === 'session/set_config_option' && params.configId === 'model')) {
+            const model = String(method === 'session/set_model' ? params.modelId : params.value), selected = parseAcpModel(model);
+            if (session.conversation && session.conversation.harness !== selected.app)
+                throw new RpcError(-32602, 'Choose a new conversation to switch between Claude Code and Codex.');
+            record.model = model;
+            this.#save(record);
+            await this.#connect(session);
+            const result = await session.transport.rpc.request('session/set_config_option', { sessionId: record.nativeId, configId: 'model', value: selected.id });
+            return method === 'session/set_model' ? {} : this.#configuration(model, objectValue(result));
+        }
+        await this.#connect(session);
+        if (method === 'session/load' || method === 'session/resume')
+            return this.#configuration(record.model, { ...record.setup, sessionId: record.id });
+        const mapped = acpReferences(params, record, session.conversation.worktree_path, true);
+        if (method === 'session/prompt') {
+            record.prompted = true;
+            record.updatedAt = new Date().toISOString();
+            this.#save(record);
+        }
+        if (!request)
+            return session.transport.rpc.notify(method, mapped);
+        const result = objectValue(await session.transport.rpc.request(method, mapped, method === 'session/prompt' ? 0 : 120_000));
+        return this.#configuration(record.model, acpReferences(result, record, session.conversation.worktree_path));
+    }
+    #session(id, cwd) {
+        const record = this.#records()[id];
+        if (!record || record.apiUrl !== this.#ctx.apiUrl || (cwd !== undefined && (typeof cwd !== 'string' || projectIdentity(cwd).folder !== record.folder)))
+            throw new RpcError(-32000, 'Conversation not found.');
+        let session = this.#sessions.get(id);
+        if (!session) {
+            session = { record, stop: new AbortController() };
+            this.#sessions.set(id, session);
+        }
+        return session;
+    }
+    async #connect(session) {
+        if (session.connecting)
+            return session.connecting;
+        if (session.transport && !session.transport.rpc.closed)
+            return;
+        session.connecting = this.#start(session).finally(() => { session.connecting = undefined; });
+        return session.connecting;
+    }
+    async #start(session) {
+        const ctx = this.#ctx, { record } = session, { app } = parseAcpModel(record.model);
+        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.' });
+        if (!record.conversationId) {
+            const created = await createConversation(ctx, record.folder, app, 'acp');
+            session.conversation = created.conversation;
+            session.ws = created.workspace;
+            record.conversationId = created.conversation.id;
+            this.#save(record);
+            if (!(await savedMachine(ctx))?.template)
+                await syncAgentConfig(ctx, created.workspace);
+        }
+        else {
+            const current = await getConversation(ctx, record.conversationId);
+            session.conversation = await resumeConversation(ctx, current);
+            session.ws = await conversationWorkspace(ctx, session.conversation);
+            rememberConversation(ctx, session.conversation, record.folder);
+        }
+        const c = session.conversation, cell = session.ws.cell();
+        await ensureMenubar(ctx.store.dir, ctx.apiUrl, new MenubarManager({ home: ctx.io.env.HOME, signal: ctx.signal }));
+        await restoreConversationBinding(ctx, c, session.ws);
+        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' },
+                options: [{ optionId: 'once', name: 'Allow once', kind: 'allow_once' }, ...(!approval.outside ? [{ optionId: 'always', name: 'Always for this project', kind: 'allow_always' }] : []), { optionId: 'deny', name: 'Deny', kind: 'reject_once' }] }, 0, AbortSignal.any([ctx.signal, session.stop.signal])));
+            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 });
+        if (launched.exitCode !== 0)
+            throw new Error(`ACP supervisor could not attach: ${launched.stderr.trim()}`);
+        const status = JSON.parse(await cell.files.readText(`/home/user/.local/share/shardflux/acp/${c.id}/status.json`, { length: 8192 }));
+        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}`;
+        const initialize = !record.nativeId || record.owner !== owner;
+        if (record.workspaceId !== session.ws.id)
+            record.from_seq = 0;
+        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) => {
+            if (method.startsWith('fs/') || method.startsWith('terminal/'))
+                throw new RpcError(-32601, 'Files and commands run in your cloud workspace.');
+            const mapped = acpReferences(params, record, c.worktree_path);
+            if (method === 'session/update') {
+                const update = objectValue(params.update);
+                if (update.sessionUpdate === 'config_option_update' && Array.isArray(update.configOptions)) {
+                    this.#catalog[app].configOptions = update.configOptions;
+                    mapped.update = { ...update, ...this.#configuration(record.model, { configOptions: update.configOptions }) };
+                }
+            }
+            if (request) {
+                if (method === 'session/request_permission')
+                    transport.pause();
+                try {
+                    return acpReferences(await this.#client.request(method, mapped, 0, AbortSignal.any([ctx.signal, session.stop.signal])), record, c.worktree_path, true);
+                }
+                finally {
+                    if (method === 'session/request_permission')
+                        transport.resume();
+                }
+            }
+            await this.#client.notify(method, mapped);
+        };
+        session.transport = transport;
+        await transport.start();
+        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');
+            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: [], ...(nativeId ? { sessionId: nativeId } : {}) }));
+            const id = result.sessionId ?? nativeId;
+            if (typeof id !== 'string' || !id)
+                throw new Error('Agent returned no native session id');
+            record.nativeId = id;
+            record.setup = result;
+            record.owner = owner;
+            if (Array.isArray(result.configOptions))
+                this.#catalog[app].configOptions = result.configOptions;
+            this.#save(record);
+        }
+    }
+    async #close(session) {
+        this.#sessions.delete(session.record.id);
+        session.stop.abort();
+        await session.transport?.close();
+        session.ws?.cell().close();
+        await session.approvals?.stop();
+        session.approvals = undefined;
+    }
+    async close() { await Promise.all([...this.#sessions.values()].map(s => this.#close(s))); }
+}
+export async function runAcp(ctx, errors) {
+    const controller = new AbortController();
+    ctx = { ...ctx, signal: AbortSignal.any([ctx.signal, controller.signal]) };
+    const rpc = new AcpRpc(message => { ctx.io.stdout.write(JSON.stringify(message) + '\n'); return Promise.resolve(); });
+    const server = new ShardfluxAcp(ctx, rpc, errors);
+    rpc.handler = (method, params, request) => server.handle(method, params, request);
+    try {
+        for await (const chunk of ctx.io.stdin) {
+            ctx.signal.throwIfAborted();
+            rpc.feed(Buffer.from(chunk));
+        }
+    }
+    finally {
+        controller.abort();
+        rpc.close();
+        await server.close();
+        await rpc.drain();
+        await server.close();
+    }
+    return 0;
+}

package/dist/agent-commands.d.ts

@@ -1,8 +1,16 @@
-import type { CellClient, PtySession } from '@shardflux/sdk';
+import type { CellClient, PtySession, Workspace } from '@shardflux/sdk';
 import type { Ctx, Handler } from './commands.js';
+import type { Values } from './args.js';
 /** `<slug>-<6 hex of sha256(identity)>`: the same repository gets the same key on every machine. */
 export declare function disambiguatedSlug(slug: string, identity: string): string;
 export declare function projectTemplate(ctx: Ctx, remote: string | null): Promise<string>;
-export declare function agentPty(cell: CellClient, app: 'claude' | 'codex', agent: string, approvals: boolean, term: string, signal?: AbortSignal, project?: string, setupHash?: string, cwd?: string, ptyName?: string, onLaunch?: () => void, deferSetup?: boolean): Promise<PtySession>;
+export declare function agentPty(cell: CellClient, app: 'claude' | 'codex', agent: string, approvals: boolean, term: string, signal?: AbortSignal, project?: string, setupHash?: string, cwd?: string, ptyName?: string, onLaunch?: () => void, deferSetup?: boolean, conversation?: {
+    id: string;
+    session: string | null;
+}): Promise<PtySession>;
+export declare function terminal(ctx: Ctx, ws: Workspace, app: 'claude' | 'codex', agent: string, project: string, values: Values, setupHash?: string, cwd?: string, conversation?: {
+    id: string;
+    session: string | null;
+}): Promise<number>;
 export declare const launchProject: Handler;
 export declare const AGENT_HANDLERS: Record<string, Handler>;

package/dist/agent-commands.js

@@ -4,7 +4,6 @@ import { configureCredentialFill, watchCredentialPrompts } from "./credential-pr
 import { createHash } from 'node:crypto';
 import { ShardfluxApiError } from '@shardflux/sdk';
 import { UsageError } from "./errors.js";
-import { startProjectSync } from "./project-sync.js";
 import { AgentStateStore } from "./agent-state.js";
 import { attachTerminal, cellConnector } from "./agent-terminal.js";
 import { prepareProjectTemplate } from "./project-template-setup.js";
@@ -16,9 +15,12 @@ import { startAgentConfigTunnels, syncAgentConfig } from "./agent-config-sync.js
 import { rememberGitAgent } from "./agent-git-commands.js";
 import { projectWorkspacePath, seedAgentRepository, workspaceRepositoryPath } from "./agent-repository.js";
 import { agentName } from "./agent-git.js";
-import { cloudClaudeLogin, loginClaudeInWorkspace, requireClaudeTerminal } from "./claude-cloud-login.js";
+import { cloudClaudeLogin, ensureCloudClaude, loginClaudeInWorkspace, requireClaudeTerminal } from "./claude-cloud-login.js";
 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";
 const active = (session) => session.state === 'running' || session.state === 'starting';
 /** `<slug>-<6 hex of sha256(identity)>`: the same repository gets the same key on every machine. */
 export function disambiguatedSlug(slug, identity) {
@@ -40,7 +42,7 @@ export async function projectTemplate(ctx, remote) {
         throw error;
     }
 }
-export async function agentPty(cell, app, agent, approvals, term, signal, project, setupHash, cwd, ptyName, onLaunch, deferSetup = false) {
+export async function agentPty(cell, app, agent, approvals, term, signal, project, setupHash, cwd, ptyName, onLaunch, deferSetup = false, conversation) {
     const id = `shard-${ptyName || agent}-${app}`;
     // Arrival and changed locks queue the same durable guest job even when the
     // native agent is already alive. Setup never becomes its first user turn.
@@ -59,7 +61,13 @@ export async function agentPty(cell, app, agent, approvals, term, signal, projec
             throw error;
     }
     onLaunch?.();
-    const launch = await cell.exec.run(['sf-agent', 'run', app, '--name', agent, '--detach', ...(ptyName ? ['--pty-name', ptyName] : []), ...(approvals ? ['--approvals'] : []), ...(setupHash ? ['--setup', '--setup-deps-hash', setupHash] : [])], {
+    let conversationArgs = [];
+    if (conversation) {
+        const help = await cell.exec.run(['sf-agent', 'run', app, '--help'], { timeoutMs: 10_000, maxOutputBytes: 8192, signal });
+        if ((help.stdout + help.stderr).includes('-conversation'))
+            conversationArgs = ['--conversation', conversation.id, ...(conversation.session ? ['--resume-session', conversation.session] : [])];
+    }
+    const launch = await cell.exec.run(['sf-agent', 'run', app, '--name', agent, '--detach', ...conversationArgs, ...(ptyName ? ['--pty-name', ptyName] : []), ...(approvals ? ['--approvals'] : []), ...(setupHash ? ['--setup', '--setup-deps-hash', setupHash] : [])], {
         env: { TERM: term, ...(project ? { SF_PROJECT_NAME: project } : {}), ...(setupHash && deferSetup ? { SF_SETUP_DEFERRED: '1' } : {}) }, timeoutMs: 30_000, maxOutputBytes: 4096, signal, ...(cwd ? { cwd } : {}),
     });
     if (launch.exitCode !== 0)
@@ -78,7 +86,7 @@ export async function agentPty(cell, app, agent, approvals, term, signal, projec
         throw new Error(`agent exited before attach: ${session.state}`);
     return session;
 }
-async function terminal(ctx, ws, app, agent, project, values, setupHash, cwd = workspaceRepositoryPath(ws)) {
+export async function terminal(ctx, ws, app, agent, project, values, setupHash, cwd = workspaceRepositoryPath(ws), conversation) {
     const store = new AgentStateStore(ctx.store.dir);
     if (!ws.ready)
         await ws.wake({ timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
@@ -89,7 +97,7 @@ async function terminal(ctx, ws, app, agent, project, values, setupHash, cwd = w
     try {
         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);
+        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);
         // 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`);
@@ -150,6 +158,10 @@ export const launchProject = async (ctx, values, [path = './', explicitApp]) =>
     const project = like ? { folder: path, slug: like.labels.shard_project || like.key.split('/')[0], remote: like.labels.repo_remote || null } : projectIdentity(path);
     const projectKey = project.remote ?? (like ? project.slug : project.folder);
     const store = new AgentStateStore(ctx.store.dir);
+    const target = typeof values.in === 'string' && values.in !== 'terminal' ? values.in : undefined;
+    const detected = target ? installedTargets(ctx.io.env) : undefined;
+    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');
     const agent = typeof values.name === 'string' ? values.name : 'main';
     if (!/^[a-z0-9][a-z0-9._-]{0,63}$/.test(agent))
@@ -177,7 +189,7 @@ export const launchProject = async (ctx, values, [path = './', explicitApp]) =>
     const claudeReady = app === 'claude' ? await cloudClaudeLogin(ctx) : undefined;
     if (app === 'claude' && !claudeReady)
         requireClaudeTerminal(ctx);
-    if (!ctx.json && values.detach !== true)
+    if (!target && !ctx.json && values.detach !== true)
         requireTerminal(ctx);
     // A `like` agent inherits the main workspace's template; only a project's own workspace prepares one (L7).
     const prepared = like ? undefined : await prepareProjectTemplate(ctx, project, existing);
@@ -188,23 +200,29 @@ export const launchProject = async (ctx, values, [path = './', explicitApp]) =>
         ...(!existing && agent !== 'main' ? { retention: { delete_after_idle_days: 7 } } : {}),
         wait: { timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal },
     });
+    if (target === 't3' && detected?.versions.t3)
+        await queueT3Prewarm(ctx, ws, detected.versions.t3);
     if (app === 'claude' && !claudeReady)
         await loginClaudeInWorkspace(ctx, ws);
+    if (target === 't3' && app === 'codex')
+        await ensureCloudClaude(ctx, ws);
     if (!(await savedMachine(ctx))?.template)
         await syncAgentConfig(ctx, ws);
-    // Extra/like agents return work through hidden refs; only the main owns local sync.
-    const sync = agent === 'main' && !like ? await startProjectSync(ctx, ws, project) : undefined;
-    try {
-        if (!sync) {
-            await ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs }).files.mkdir(workspaceRepositoryPath(ws), { parents: true });
-            await seedAgentRepository(ctx, ws, project.folder, { populate: true });
+    // Seed once; two-way sync is scoped to explicit Try locally worktrees.
+    await ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs }).files.mkdir(workspaceRepositoryPath(ws), { parents: true });
+    await seedAgentRepository(ctx, ws, project.folder, { populate: true });
+    await rememberGitAgent(ctx, ws, project.folder);
+    if (target) {
+        if (prepared?.setupHash) {
+            const setup = await ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs }).exec.run(['sf-agent', 'setup-start', '--deps-hash', prepared.setupHash], { cwd: workspaceRepositoryPath(ws), timeoutMs: 30_000, maxOutputBytes: 4096, signal: ctx.signal });
+            if (setup.exitCode !== 0)
+                throw new Error(`project setup could not be queued: ${setup.stderr.trim() || `exit ${setup.exitCode}`}`);
         }
-        await rememberGitAgent(ctx, ws, project.folder);
-        return await terminal(ctx, ws, app, agent, projectKey, values, prepared?.setupHash, sync?.root);
-    }
-    finally {
-        await sync?.stop();
+        store.saveTarget(projectKey, target);
+        return openDesktopWorkspace(ctx, ws, target, detected?.versions.t3, true);
     }
+    await prepareAgentMachine(ctx, ws);
+    return await terminal(ctx, ws, app, agent, projectKey, values, prepared?.setupHash);
 };
 export const AGENT_HANDLERS = {
     async 'agents open'(ctx, values, [agent = 'main']) {
@@ -239,6 +257,7 @@ export const AGENT_HANDLERS = {
             requireTerminal(ctx);
         if (ws.labels.shard_layer !== 'machine' && !(await savedMachine(ctx))?.template)
             await syncAgentConfig(ctx, ws);
+        await prepareAgentMachine(ctx, ws);
         return terminal(ctx, ws, app, (ws.labels.agent ?? agent).split('/').at(-1), projectKey, values);
     },
 };

package/dist/agent-machine.d.ts

@@ -0,0 +1,6 @@
+import type { Workspace } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+export declare function agentMachineName(key: string): string;
+/** Root owns machine-info; T3 reads the label and caches its environment identity at server start. */
+export declare const AGENT_MACHINE_SCRIPT = "import os, pathlib, pwd, select, shutil, signal, sys, tempfile\nlabel, identity = sys.argv[1:3]\npath = pathlib.Path(sys.argv[3]) if len(sys.argv) > 3 else pathlib.Path('/etc/machine-info')\nif path.is_symlink():\n    raise RuntimeError('machine-info must not be a symlink')\nprevious = path.read_text() if path.exists() else ''\nlines = [line for line in previous.splitlines() if not line.startswith('PRETTY_HOSTNAME=')]\nlines.append('PRETTY_HOSTNAME=\"' + label + '\"')\ncontent = '\\n'.join(lines) + '\\n'\nif previous != content:\n    fd, tmp = tempfile.mkstemp(prefix='.machine-info-', dir=path.parent)\n    try:\n        with os.fdopen(fd, 'w') as file:\n            file.write(content)\n            os.fchmod(file.fileno(), 0o644)\n        os.replace(tmp, path)\n    finally:\n        if os.path.exists(tmp): os.unlink(tmp)\nif identity:\n    user = pwd.getpwnam('user')\n    home = pathlib.Path(user.pw_dir)\n    state = home / '.t3/userdata'\n    target = state / 'environment-id'\n    if target.is_symlink() or any(p.is_symlink() for p in [home / '.t3', state]):\n        raise RuntimeError('T3 identity paths must not be symlinks')\n    if not target.exists() or target.read_text().strip() != identity:\n        # Inspect the executable and owner, never trust a stale PID file after a fork.\n        servers = []\n        try:\n            for proc in pathlib.Path('/proc').iterdir():\n                if not proc.name.isdigit(): continue\n                fd = None\n                try:\n                    if proc.stat().st_uid != user.pw_uid: continue\n                    fd = os.pidfd_open(int(proc.name))\n                    executable = os.readlink(proc / 'exe').removesuffix(' (deleted)')\n                    args = (proc / 'cmdline').read_bytes().split(b'\\0')\n                    if not executable.startswith(str(home / '.t3/runtime') + '/') or b'serve' not in args:\n                        continue\n                    servers.append(fd)\n                    signal.pidfd_send_signal(fd, signal.SIGTERM)\n                except (FileNotFoundError, ProcessLookupError):\n                    continue\n                except PermissionError as error:\n                    raise RuntimeError('could not inspect user T3 processes; identity left unchanged') from error\n                finally:\n                    if fd is not None and fd not in servers: os.close(fd)\n            if servers:\n                stopped, _, _ = select.select(servers, [], [], 2)\n                remaining = [fd for fd in servers if fd not in stopped]\n                for fd in remaining:\n                    try: signal.pidfd_send_signal(fd, signal.SIGKILL)\n                    except ProcessLookupError: pass\n                if remaining and len(select.select(remaining, [], [], 2)[0]) != len(remaining):\n                    raise RuntimeError('T3 server did not stop')\n        finally:\n            for fd in servers: os.close(fd)\n        launch = home / '.t3/ssh-launch'\n        if launch.is_symlink(): launch.unlink()\n        elif launch.exists(): shutil.rmtree(launch)\n        (state / 'server-runtime.json').unlink(missing_ok=True)\n        state.mkdir(parents=True, exist_ok=True)\n        os.chown(home / '.t3', user.pw_uid, user.pw_gid)\n        os.chown(state, user.pw_uid, user.pw_gid)\n        fd, tmp = tempfile.mkstemp(prefix='.environment-id-', dir=state)\n        try:\n            with os.fdopen(fd, 'w') as file:\n                file.write(identity + '\\n')\n                os.fchown(file.fileno(), user.pw_uid, user.pw_gid)\n            os.replace(tmp, target)\n            recovery = state / 'environment-id.recovery'\n            recovery.unlink(missing_ok=True)\n        finally:\n            if os.path.exists(tmp): os.unlink(tmp)\n";
+export declare function prepareAgentMachine(ctx: Ctx, ws: Workspace): Promise<void>;

package/dist/agent-machine.js

@@ -0,0 +1,93 @@
+import { targetIdentity } from "./agent-targets.js";
+export function agentMachineName(key) {
+    const { project, agent } = targetIdentity(key);
+    return `Shardflux · ${project}${agent === 'main' ? '' : ` · ${agent}`}`;
+}
+/** Root owns machine-info; T3 reads the label and caches its environment identity at server start. */
+export const AGENT_MACHINE_SCRIPT = `import os, pathlib, pwd, select, shutil, signal, sys, tempfile
+label, identity = sys.argv[1:3]
+path = pathlib.Path(sys.argv[3]) if len(sys.argv) > 3 else pathlib.Path('/etc/machine-info')
+if path.is_symlink():
+    raise RuntimeError('machine-info must not be a symlink')
+previous = path.read_text() if path.exists() else ''
+lines = [line for line in previous.splitlines() if not line.startswith('PRETTY_HOSTNAME=')]
+lines.append('PRETTY_HOSTNAME="' + label + '"')
+content = '\\n'.join(lines) + '\\n'
+if previous != content:
+    fd, tmp = tempfile.mkstemp(prefix='.machine-info-', dir=path.parent)
+    try:
+        with os.fdopen(fd, 'w') as file:
+            file.write(content)
+            os.fchmod(file.fileno(), 0o644)
+        os.replace(tmp, path)
+    finally:
+        if os.path.exists(tmp): os.unlink(tmp)
+if identity:
+    user = pwd.getpwnam('user')
+    home = pathlib.Path(user.pw_dir)
+    state = home / '.t3/userdata'
+    target = state / 'environment-id'
+    if target.is_symlink() or any(p.is_symlink() for p in [home / '.t3', state]):
+        raise RuntimeError('T3 identity paths must not be symlinks')
+    if not target.exists() or target.read_text().strip() != identity:
+        # Inspect the executable and owner, never trust a stale PID file after a fork.
+        servers = []
+        try:
+            for proc in pathlib.Path('/proc').iterdir():
+                if not proc.name.isdigit(): continue
+                fd = None
+                try:
+                    if proc.stat().st_uid != user.pw_uid: continue
+                    fd = os.pidfd_open(int(proc.name))
+                    executable = os.readlink(proc / 'exe').removesuffix(' (deleted)')
+                    args = (proc / 'cmdline').read_bytes().split(b'\\0')
+                    if not executable.startswith(str(home / '.t3/runtime') + '/') or b'serve' not in args:
+                        continue
+                    servers.append(fd)
+                    signal.pidfd_send_signal(fd, signal.SIGTERM)
+                except (FileNotFoundError, ProcessLookupError):
+                    continue
+                except PermissionError as error:
+                    raise RuntimeError('could not inspect user T3 processes; identity left unchanged') from error
+                finally:
+                    if fd is not None and fd not in servers: os.close(fd)
+            if servers:
+                stopped, _, _ = select.select(servers, [], [], 2)
+                remaining = [fd for fd in servers if fd not in stopped]
+                for fd in remaining:
+                    try: signal.pidfd_send_signal(fd, signal.SIGKILL)
+                    except ProcessLookupError: pass
+                if remaining and len(select.select(remaining, [], [], 2)[0]) != len(remaining):
+                    raise RuntimeError('T3 server did not stop')
+        finally:
+            for fd in servers: os.close(fd)
+        launch = home / '.t3/ssh-launch'
+        if launch.is_symlink(): launch.unlink()
+        elif launch.exists(): shutil.rmtree(launch)
+        (state / 'server-runtime.json').unlink(missing_ok=True)
+        state.mkdir(parents=True, exist_ok=True)
+        os.chown(home / '.t3', user.pw_uid, user.pw_gid)
+        os.chown(state, user.pw_uid, user.pw_gid)
+        fd, tmp = tempfile.mkstemp(prefix='.environment-id-', dir=state)
+        try:
+            with os.fdopen(fd, 'w') as file:
+                file.write(identity + '\\n')
+                os.fchown(file.fileno(), user.pw_uid, user.pw_gid)
+            os.replace(tmp, target)
+            recovery = state / 'environment-id.recovery'
+            recovery.unlink(missing_ok=True)
+        finally:
+            if os.path.exists(tmp): os.unlink(tmp)
+`;
+export async function prepareAgentMachine(ctx, ws) {
+    if (ws.labels.shard_layer === 'machine')
+        return;
+    const identity = ws.labels?.t3_environment_id ?? '';
+    if (identity && !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(identity))
+        throw new Error('invalid fork T3 environment identity');
+    const cell = ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs });
+    const label = ws.labels.shard_router === 'project' ? `Shardflux · ${ws.key.split('/')[0]}` : agentMachineName(ws.key);
+    const result = await cell.exec.run(['python3', '-c', AGENT_MACHINE_SCRIPT, label, identity], { user: 'root', timeoutMs: 10_000, maxOutputBytes: 4096, signal: ctx.signal });
+    if (result.exitCode !== 0)
+        throw new Error(`could not prepare ${ws.key} machine identity: ${result.stderr.trim() || `exit ${result.exitCode}`}`);
+}

package/dist/agent-repository.js

@@ -24,7 +24,7 @@ export function needsGitSeed(ctx, ws) {
 export async function seedAgentRepository(ctx, ws, folder, options = {}) {
     const project = projectIdentity(folder);
     // A cloud-only `like` launch must never seed an unrelated laptop repository.
-    if (ws.labels.repo_remote && ws.labels.repo_remote !== project.remote)
+    if (ws.labels.repo_remote && ws.labels.repo_remote !== (project.remote ?? `file://${project.folder}`))
         return;
     const root = options.root ?? workspaceRepositoryPath(ws);
     const retry = needsGitSeed(ctx, ws);

package/dist/agent-state.d.ts

@@ -1,6 +1,7 @@
 type State = Record<string, unknown> & {
     projects?: Record<string, {
         app?: string;
+        target?: string;
     }>;
 };
 /** Keep other lanes' sync manifests and project settings when remembering the app choice. */
@@ -10,6 +11,8 @@ export declare class AgentStateStore {
     constructor(dir: string);
     read(): State;
     app(project: string, fallback?: 'claude' | 'codex'): 'claude' | 'codex';
+    target(project: string, available: string[]): string;
+    saveTarget(project: string, target: string): void;
     update(change: (state: State) => void): void;
     save(project: string, app: 'claude' | 'codex'): void;
 }

package/dist/agent-state.js

@@ -24,25 +24,46 @@ export class AgentStateStore {
         const app = this.read().projects?.[project]?.app;
         return app === 'claude' || app === 'codex' ? app : fallback;
     }
+    target(project, available) {
+        const target = this.read().projects?.[project]?.target;
+        return target && available.includes(target) ? target : available.includes('t3') ? 't3' : 'terminal';
+    }
+    saveTarget(project, target) {
+        this.update(doc => {
+            doc.projects ??= {};
+            doc.projects[project] = { ...doc.projects[project], target };
+        });
+    }
     update(change) {
         ensurePrivateDir(this.dir);
         const lock = `${this.file}.lock`;
-        try {
-            writeFileSync(lock, String(process.pid), { flag: 'wx', mode: 0o600 });
-        }
-        catch (error) {
-            if (error.code !== 'EEXIST')
-                throw error;
+        const deadline = performance.now() + 2000;
+        const wait = new Int32Array(new SharedArrayBuffer(4));
+        for (;;) {
             try {
-                process.kill(Number(readFileSync(lock, 'utf8')), 0);
+                writeFileSync(lock, String(process.pid), { flag: 'wx', mode: 0o600 });
+                break;
             }
-            catch (probe) {
-                if (probe.code === 'ESRCH') {
-                    rmSync(lock);
-                    return this.update(change);
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+                try {
+                    process.kill(Number(readFileSync(lock, 'utf8')), 0);
+                }
+                catch (probe) {
+                    if (probe.code === 'ENOENT')
+                        continue;
+                    if (probe.code === 'ESRCH') {
+                        rmSync(lock, { force: true });
+                        continue;
+                    }
                 }
+                if (performance.now() >= deadline)
+                    throw new UsageError('another shard process is updating agent state; run the command again');
+                // Updates are synchronous and short. The competing writer is another
+                // process, so it can finish while this process waits without spinning.
+                Atomics.wait(wait, 0, 0, Math.min(10, deadline - performance.now()));
             }
-            throw new UsageError('another shard process is updating agent state; run the command again');
         }
         try {
             const state = this.read();