@shardflux/cli 0.13.6 → 0.14.1

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.d.ts

@@ -12,6 +12,8 @@ export declare function needsGitSeed(ctx: Ctx, ws: Workspace): boolean;
 export declare function seedAgentRepository(ctx: Ctx, ws: Workspace, folder: string, options?: {
     root?: string;
     populate?: boolean;
+    initialFiles?: readonly string[];
+    onInitialFiles?: () => void;
 }): Promise<void>;
 /** History above this goes through the project's origin instead of the bounded files path. */
 export declare const HISTORY_BUNDLE_LIMIT: number;

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);
@@ -32,7 +32,13 @@ export async function seedAgentRepository(ctx, ws, folder, options = {}) {
     state.update(doc => { const seeds = (doc.git_seeding ?? {}); seeds[ws.id] = { api_url: ctx.apiUrl, folder: project.folder }; doc.git_seeding = seeds; });
     const cell = ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs });
     await cell.files.mkdir(root, { parents: true });
-    await initializeProjectGit(cell, project.folder, root, ctx.signal, options.populate, retry, message => { ctx.io.stderr.write(`${message}\n`); });
+    let initialReady = false;
+    const initial = options.onInitialFiles ? { paths: new Set(options.initialFiles ?? []), ready: () => { if (!initialReady) {
+            initialReady = true;
+            options.onInitialFiles();
+        } } } : undefined;
+    await initializeProjectGit(cell, project.folder, root, ctx.signal, options.populate, retry, message => { ctx.io.stderr.write(`${message}\n`); }, initial);
+    initial?.ready();
     state.update(doc => { const seeds = (doc.git_seeding ?? {}); delete seeds[ws.id]; doc.git_seeding = seeds; });
 }
 /** History above this goes through the project's origin instead of the bounded files path. */
@@ -116,7 +122,7 @@ export async function importProjectHistory(cell, folder, root, head, branch, ori
         await cell.files.remove(remote).catch(() => undefined);
     }
 }
-async function initializeProjectGit(cell, folder, root, signal, populate = false, retry = false, report = () => undefined) {
+async function initializeProjectGit(cell, folder, root, signal, populate = false, retry = false, report = () => undefined, initial) {
     let top;
     try {
         top = (await projectGit(folder, ['rev-parse', '--show-toplevel'], signal)).trim();
@@ -125,7 +131,7 @@ async function initializeProjectGit(cell, folder, root, signal, populate = false
         if (signal?.aborted || error.code !== 128)
             throw error;
         if (populate)
-            await seedProjectFiles(cell, folder, root, '', new Set(), true, signal, report);
+            await seedProjectFiles(cell, folder, root, '', new Set(), true, signal, report, initial);
         return;
     }
     if (top !== folder)
@@ -192,7 +198,7 @@ async function initializeProjectGit(cell, folder, root, signal, populate = false
         // template's dependency outputs would look like agent-created source.
         // For unborn repos, intent-to-add preserves tracked ignored paths too.
         const tracked = new Set((await projectGit(folder, ['ls-files', '-z', '--cached'], signal)).split('\0'));
-        await seedProjectFiles(cell, folder, root, head, tracked, populate, signal, report);
+        await seedProjectFiles(cell, folder, root, head, tracked, populate, signal, report, initial);
     }
     // Git's info/exclude and laptop-wide excludes are selection metadata, copied
     // into a dedicated Git exclude file without syncing credentials or .git data.
@@ -221,38 +227,43 @@ async function initializeProjectGit(cell, folder, root, signal, populate = false
     if (result.exitCode !== 0)
         throw new Error('could not apply project Git exclude rules');
 }
-async function seedProjectFiles(cell, folder, root, head, tracked, populate, signal, report) {
+async function seedProjectFiles(cell, folder, root, head, tracked, populate, signal, report, initial) {
     const raw = await localManifest(folder, signal);
     for (const skip of raw.skipped)
         report(`Project seed skipped ${skip.path}: ${skip.reason}`);
     const seed = raw.entries.filter((entry) => populate || entry.path.split('/').at(-1) === '.gitignore' || (!head && tracked.has(entry.path)));
-    for (let offset = 0; offset < seed.length; offset += 32) {
-        const entries = seed.slice(offset, offset + 32);
-        const probe = await cell.exec.run(['python3', '-c', 'import os,sys,json;root=sys.argv[1];print(json.dumps([p for p in json.loads(sys.argv[2]) if not os.path.lexists(root+"/"+p)]))', root, JSON.stringify(entries.map((entry) => entry.path))], { timeoutMs: 5000, signal });
-        if (probe.exitCode !== 0)
-            throw new Error('could not inspect initial project ignore files');
-        const missing = new Set(JSON.parse(probe.stdout));
-        let seeds = new Map(), bytes = 0;
-        for (const entry of entries)
-            if (missing.has(entry.path)) {
-                if (bytes + entry.size > 8 << 20 && seeds.size) {
-                    await applyRemoteSyncBatch(cell, root, seeds, {}, signal);
-                    seeds = new Map();
-                    bytes = 0;
+    const groups = initial ? [seed.filter(e => initial.paths.has(e.path)), seed.filter(e => !initial.paths.has(e.path))] : [seed];
+    for (let group = 0; group < groups.length; group++) {
+        for (let offset = 0; offset < groups[group].length; offset += 32) {
+            const entries = groups[group].slice(offset, offset + 32);
+            const probe = await cell.exec.run(['python3', '-c', 'import os,sys,json;root=sys.argv[1];print(json.dumps([p for p in json.loads(sys.argv[2]) if not os.path.lexists(root+"/"+p)]))', root, JSON.stringify(entries.map((entry) => entry.path))], { timeoutMs: 5000, signal });
+            if (probe.exitCode !== 0)
+                throw new Error('could not inspect initial project ignore files');
+            const missing = new Set(JSON.parse(probe.stdout));
+            let seeds = new Map(), bytes = 0;
+            for (const entry of entries)
+                if (missing.has(entry.path)) {
+                    if (bytes + entry.size > 8 << 20 && seeds.size) {
+                        await applyRemoteSyncBatch(cell, root, seeds, {}, signal);
+                        seeds = new Map();
+                        bytes = 0;
+                    }
+                    const file = await readLocalSyncFile(folder, entry);
+                    seeds.set(entry.path, file);
+                    bytes += file.data.length;
+                }
+            if (seeds.size)
+                await applyRemoteSyncBatch(cell, root, seeds, {}, signal);
+            if (!head) {
+                const add = entries.filter((entry) => tracked.has(entry.path)).map((entry) => entry.path);
+                if (add.length) {
+                    const result = await cell.exec.run(['git', '-C', root, '-c', 'core.hooksPath=/dev/null', 'add', '-N', '-f', '--', ...add], { timeoutMs: 5000, signal });
+                    if (result.exitCode !== 0)
+                        throw new Error(`initial tracked project files failed: ${result.stderr.trim()}`);
                 }
-                const file = await readLocalSyncFile(folder, entry);
-                seeds.set(entry.path, file);
-                bytes += file.data.length;
-            }
-        if (seeds.size)
-            await applyRemoteSyncBatch(cell, root, seeds, {}, signal);
-        if (!head) {
-            const add = entries.filter((entry) => tracked.has(entry.path)).map((entry) => entry.path);
-            if (add.length) {
-                const result = await cell.exec.run(['git', '-C', root, '-c', 'core.hooksPath=/dev/null', 'add', '-N', '-f', '--', ...add], { timeoutMs: 5000, signal });
-                if (result.exitCode !== 0)
-                    throw new Error(`initial tracked project files failed: ${result.stderr.trim()}`);
             }
         }
+        if (group === 0)
+            initial?.ready();
     }
 }

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();

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

@@ -2,9 +2,12 @@ import { Duplex } from 'node:stream';
 import type { CellClient, Workspace } from '@shardflux/sdk';
 import type { Ctx, Handler, Io } from './commands.js';
 import { AgentTargets } from './agent-targets.js';
+import type { DesktopTarget } from './agent-targets.js';
 /** Optimistic file replacement preserves keys installed by other devices connecting at the same time. */
 export declare function installDeviceKey(cell: CellClient, key: string, signal?: AbortSignal): Promise<void>;
 /** Host trust is established over the authenticated files API, before sending any SSH protocol bytes. */
 export declare function prepareSsh(ws: Workspace, ctx: Ctx, targets: AgentTargets, host: string): Promise<CellClient>;
-export declare function proxyStream(io: Io): Duplex;
+export declare function proxyStream(io: Io, ended?: () => void, outputGate?: Promise<unknown>): Duplex;
+export declare function openDesktopWorkspace(ctx: Ctx, ws: Workspace, target: DesktopTarget, t3Version?: string, prewarmed?: boolean): Promise<number>;
+export declare function queueT3Prewarm(ctx: Ctx, ws: Workspace, version: string): Promise<void>;
 export declare const TARGET_HANDLERS: Record<string, Handler>;